path: root/sandbox/cben/make/Makefile.docutils.txt

 .. -*- Makefile -*-

******************************************************
Generic makefile for document processing with docutils
******************************************************

This file provides typical rules for processing documents with docutils.  By
default it provides common targets (`all`, `pdf`, `clean`, etc.) for
processing all ``*.txt`` files in this directory.

You should be able to customize just about everything by setting variables
defined here (they all have defaults and are documented in comments).  You
can set them on make's command line or by building your own makefile that
sets them before including this one.  For simplest cases, you'd want to give
`DOCS` and perhaps `ALL`.

Some things can be customized per document with make's
per-target/per-pattern variable assignment syntax, e.g. ``mydoc.ps: FLAGS +=
--no-doc-title``.  Unfortunately this won't work for any variables that
affect rules sources/targets (in particular, extension variables and
variables that enable pre/postprocessing).

If you want deeper customization or to integrate this into your makefile(s)
for other things, you can make it very include-friendly by flipping a few
settings:

- All variables can be put in a "namespace" by setting the variable
  `docutils.` (note the dot!) to the desired prefix.  In comments, variable
  names are given without the prefix.

- The non-pattern common targets and, to a lesser degree, the LaTeX rules
  might conflict with your rules.  You can disable them by setting
  `ENABLE_COMMON_TARGETS` and/or `ENABLE_LATEX_RULES` to ``0``.

  - The most common targets, like `all`, don't have commands but depend on
    targets like `docutils.all` that do the real work.  This way they are
    automatically merged with your dependencies and commands for the same
    name.

This file should be self-documenting; read it file for the full list of
customizable variables and other gory details...

GNU Make is required!  Some targets use common unix utils.

The latest version of this file lives at
http://docutils.sourceforge.net/sandbox/cben/make/Makefile.docutils


"Namespace"
***********

All variables defined in this file can be optionally prefixed with anything
you want (e.g.  ``DOCUTILS.``) to avoid namespace pollution.  To enable
this, set the variable `docutils.` (note the period in the variable name) to
the desired prefix.  Note that then, you would have to use the prefix when
setting any variables that affect this file...

::

	docutils. ?=
	##docutils. ?= DOCUTILS.
	

Pattern rules - very include-friendly makefile portion
******************************************************

This part is designed to be included in makefiles.  It supplies implicit
pattern rules for docutils' tools.  All that is left to you is to request
building of files with extensions of the output formats (.html, .tex, .dvi,
.ps, .pdf).  You should have (or be able to build) input files with .txt
extension.  Almost everything (including extensions) is configurable by
setting variables defined in this file.  You should set these variables
before including this file to avoid problems.

If you also want typical explicit rules for targets like ``html``, ``dvi``
and ``clean`` to build associated files, you will find them in later
sections...

Tool names
==========

`TOOLS` lists the tools / processing stages that are supported and have [at
least some] associated variables according to the conventions below.  It
provides some introspection ablity, currently used in the `docutils.clean`
target for computing the list of output extensions.

::

	$(docutils.)TOOLS += RST2HTML PEPTOOL RST2LATEX RST2PDFLATEX		\
			     MATHHACK IMGMATHHACK				\
			     HTML_WILD_EXTS LATEX_WILD_EXTS PDFLATEX_WILD_EXTS
	

As accustomed in makefiles, tool names can be customized by setting
variables named after the tools.  Here they are slightly more systemathic
than their current names.

``html.py`` is expected to be renamed to ``rst2html.py`` soon.

::

	ifneq "$(shell which rst2html.py)" ""
	$(docutils.)RST2HTML ?= rst2html.py
	else
	$(docutils.)RST2HTML ?= html.py
	endif
	
	$(docutils.)RST2LATEX ?= rst2latex.py
	

``rstpep2html.py`` is the RST PEP -> HTML converter tool;
``pep2html.py`` also supports old PEP format and does extra PEP
services.

::

	$(docutils.)RSTPEP2HTML ?= rep.py
	
	$(docutils.)PEPTOOL ?= pep2html.py
	

In this makefile I use only PEPTOOL (too bad RSTPEP2HTML doesn't support the
old pep format, it has a better command-line interface).

More such variables appear in the pre/postprocessing sections below.

@@@ TODO: Support other tools, e.g. RST2XML.

Extensions
==========

For simplicity, only one source extension is supported at a time.  If you
need to allow several (e.g. ``.txt`` and ``.rst``), you should be able to
call make recursively several times, setting `SRCEXT` to a different value
each time...

::

	$(docutils.)SRCEXT ?= .txt
	

There are various reasons to preprocess/postprocess docutils.  This makefile
directly supports some ways and should play nice with others.  It's more
convenient to use intermediate files than pipes (because then you can easily
inspect them for debugging).  So we need a way to insert intermediate files
into the dependency chain.  Solution: variables (`<toolname>.SRCEXT` and
`<toolname>.TRGEXT`) that control the source/target extensions of each rule.
These variables must be set before the rules that use them.

::

	$(docutils.)PEPTOOL.SRCEXT ?= $($(docutils.)SRCEXT)
	$(docutils.)PEPTOOL.TRGEXT ?= .html
	$(docutils.)RST2HTML.SRCEXT ?= $($(docutils.)SRCEXT)
	$(docutils.)RST2HTML.TRGEXT ?= .html
	$(docutils.)RST2LATEX.SRCEXT ?= $($(docutils.)SRCEXT)
	$(docutils.)RST2LATEX.TRGEXT ?= .tex
	

PDFLaTeX might need different processing and extension (in particular
because no image format is supported by both it and LaTeX).  This is sort of
a hack: pretend we have a separate RST2PDFLATEX tool.

::

	$(docutils.)RST2PDFLATEX.SRCEXT ?= $($(docutils.)RST2LATEX.SRCEXT)
	$(docutils.)RST2PDFLATEX.TRGEXT ?= .pdftex
	

Specific preprocessing/postprocessing support
---------------------------------------------

The extension manipulation is subtle.  It's important to use simple
variables (set with ``:=``) to allow chaining.  Since each processing stage
can be enabled independently of others, they can only be attached to the
main tool (e.g. RST2HTML).

Note that PEPTOOL is not supported here because non-standard processing is
not a good idea in PEPs anyway.  Won't be a big problem to add if needed...

@@@ TODO: Support as many external/sandbox tools as possible.

sandbox/cben/rolehack math preprocessing hacks
..............................................

This makefile provides rules that support preprocessing by
`<../rolehack/mathhack.py>`_ and `<../rolehack/imgmathhack.py>`_.  Set
`ENABLE_MATHHACK` to 1 to run them before rst2html.py and rst2latex.py.

::

	$(docutils.)ENABLE_MATHHACK ?= 0
	
	$(docutils.)MATHHACK.SRCEXT := $($(docutils.)RST2LATEX.SRCEXT)
	ifeq "$(origin $(docutils.)MATHHACK.TRGEXT)" "undefined"
	$(docutils.)MATHHACK.TRGEXT := $($(docutils.)RST2LATEX.SRCEXT).mathhack
	endif
	

In theory, IMGMATHHACK is applicable to all tools.  It's not very useful
with anything but RST2HTML, so that's the only one we attach to currently...

::

	$(docutils.)IMGMATHHACK.SRCEXT := $($(docutils.)RST2HTML.SRCEXT)
	ifeq "$(origin $(docutils.)IMGMATHHACK.TRGEXT)" "undefined"
	$(docutils.)IMGMATHHACK.TRGEXT := $($(docutils.)RST2HTML.SRCEXT).imgmathhack
	endif
	
	ifeq "$($(docutils.)ENABLE_MATHHACK)" "1"
	$(docutils.)RST2LATEX.SRCEXT := $($(docutils.)MATHHACK.TRGEXT)
	$(docutils.)RST2HTML.SRCEXT := $($(docutils.)IMGMATHHACK.TRGEXT)
	endif
	

If any preprocessing has been applied, it's good to tell docutils the name
of the original file.  But in current docutils, ``--source-url`` forces on
``--source-link``.  So you can control this option, per tool.

::

	$(docutils.)RST2LATEX.ENABLE_SOURCE_URL ?= 0
	ifeq "$($(docutils.)RST2LATEX.ENABLE_SOURCE_URL)" "1"
	$(docutils.)RST2LATEX.FLAGS += --source-url=$*$($(docutils.)SRCEXT)
	endif
	
	$(docutils.)RST2HTML.ENABLE_SOURCE_URL ?= 0
	ifeq "$($(docutils.)RST2HTML.ENABLE_SOURCE_URL)" "1"
	$(docutils.)RST2HTML.FLAGS += --source-url=$*$($(docutils.)SRCEXT)
	endif
	

You can set `MATHHACK_DIR` to provide an explicit location for these scripts
(you must include a trailing slash!).  You can also change the tool name
variables completely...

::

	$(docutils.)MATHHACK_DIR ?=
	$(docutils.)MATHHACK ?= $($(docutils.)MATHHACK_DIR)mathhack.py
	$(docutils.)IMGMATHHACK ?= $($(docutils.)MATHHACK_DIR)imgmathhack.py
	
	%$($(docutils.)MATHHACK.TRGEXT): %$($(docutils.)MATHHACK.SRCEXT)
		$($(docutils.)MATHHACK) $< $@
	
	%$($(docutils.)IMGMATHHACK.TRGEXT): %$($(docutils.)IMGMATHHACK.SRCEXT)
		$($(docutils.)IMGMATHHACK) $< $@
	

Rudimentary adaptation of ``.*`` file extensions to output format
.................................................................

Docutils currently doesn't support referencing different files depending on
on the output format (e.g. LaTeX requires EPS images but HTML supports
everything else).  Here are simple sed scripts, converting ``.*`` to one
extension for images and one for links, different for each tool.  **Be
warned that the regexps are not bullet-proof and could be confused!**

Set `ENABLE_WILD_EXTS` to 1 if you want to enable them.

::

	$(docutils.)ENABLE_WILD_EXTS ?= 0
	

This is an arbitrary guess, quite probable that you would want to change it.

::

	$(docutils.)HTML_WILD_EXTS.IMGEXT ?= .png

``.htm`` is also widespread but here we mostly talk about local files
produced with docutils.

::

	$(docutils.)HTML_WILD_EXTS.LINKEXT ?= .html
	

LaTeX only undestands Encapsulated PostScript.

::

	$(docutils.)LATEX_WILD_EXTS.IMGEXT ?= .eps

LaTeX is just as well convetible to PS but only PDF supports links, so this
is a good guess...

::

	$(docutils.)LATEX_WILD_EXTS.LINKEXT ?= .pdf
	

PDFLaTeX understands common formats like PNG but doesn't understand EPS!

::

	$(docutils.)PDFLATEX_WILD_EXTS.IMGEXT ?= .png

Again, PDFLaTeX supports links.

::

	$(docutils.)PDFLATEX_WILD_EXTS.LINKEXT ?= .pdf
	

Intermediate extensions:

::

	$(docutils.)HTML_WILD_EXTS.SRCEXT ?= .html.wild_exts
	$(docutils.)LATEX_WILD_EXTS.SRCEXT ?= .tex.wild_exts
	$(docutils.)PDFLATEX_WILD_EXTS.SRCEXT ?= .pdftex.wild_exts
	

Chain to the tools.

::

	$(docutils.)HTML_WILD_EXTS.TRGEXT := $($(docutils.)RST2HTML.TRGEXT)
	$(docutils.)LATEX_WILD_EXTS.TRGEXT := $($(docutils.)RST2LATEX.TRGEXT)
	$(docutils.)PDFLATEX_WILD_EXTS.TRGEXT := $($(docutils.)RST2PDFLATEX.TRGEXT)
	
	ifeq "$($(docutils.)ENABLE_WILD_EXTS)" "1"
	$(docutils.)RST2HTML.TRGEXT := $($(docutils.)HTML_WILD_EXTS.SRCEXT)
	$(docutils.)RST2LATEX.TRGEXT := $($(docutils.)LATEX_WILD_EXTS.SRCEXT)
	$(docutils.)RST2PDFLATEX.TRGEXT := $($(docutils.)PDFLATEX_WILD_EXTS.SRCEXT)
	endif
	
	%$($(docutils.)HTML_WILD_EXTS.TRGEXT): %$($(docutils.)HTML_WILD_EXTS.SRCEXT)
		sed -e 's/\( [sS][rR][cC]="[^"]*\)\.\*"/\1$($(docutils.)HTML_WILD_EXTS.IMGEXT)"/g' -e "s/\( [sS][rR][cC]='[^']*\)\.\*'/\1$($(docutils.)HTML_WILD_EXTS.IMGEXT)'/g" -e 's/\( [hH][rR][eE][fF]="[^"]*\)\.\*"/\1$($(docutils.)HTML_WILD_EXTS.LINKEXT)"/g' -e "s/\( [hH][rR][eE][fF]='[^']*\)\.\*'/\1$($(docutils.)HTML_WILD_EXTS.LINKEXT)'/g" $< > $@
	
	%$($(docutils.)LATEX_WILD_EXTS.TRGEXT): %$($(docutils.)LATEX_WILD_EXTS.SRCEXT)
		sed -e 's/\(\\includegraphics{[^}]*\)\.\*}/\1$($(docutils.)LATEX_WILD_EXTS.IMGEXT)}/g' -e 's/\(\\href{[^}]*\)\.\*}/\1$($(docutils.)LATEX_WILD_EXTS.LINKEXT)}/g' $< > $@
	
	%$($(docutils.)PDFLATEX_WILD_EXTS.TRGEXT): %$($(docutils.)PDFLATEX_WILD_EXTS.SRCEXT)
		sed -e 's/\(\\includegraphics{[^}]*\)\.\*}/\1$($(docutils.)PDFLATEX_WILD_EXTS.IMGEXT)}/g' -e 's/\(\\href{[^}]*\)\.\*}/\1$($(docutils.)PDFLATEX_WILD_EXTS.LINKEXT)}/g' $< > $@
	
	

Config files and extra flags
============================

Consider using config files instead of flags for most tasks.  To specify
config file(s) other than the default, set `CONFIG` to a space-separated
list of them.  Later files override earlier ones (and all override the
`DOCUTILSCONFIG` environment variable, which you should *not* touch in a
Makefile, it's for the user).  Non-existant config files are ignored.

Relative file names in `CONFIG` are relative to the current directory,
independently of the target name.  If you use ``%`` in `CONFIG`, it will be
replaced with the target name (without extension) and it will be
interpretted relative to the target's directory -- giving you per-file
configs.

::

	$(docutils.)CONFIG ?=
	

I found absolutely no way to implement in make per-directory config file
dependencies that don't depend on the target basename.  You can just do::

    $(docutils.)FLAGS += $(*D)/config.file.name

but it won't be considered a dependency (which is not such a big issue).  Or
you can always run make in the directory of the target...

You can provide extra docutils options by setting variables named
`<toolname>.FLAGS`.  `FLAGS` gives default flags for all tools.

::

	$(docutils.)FLAGS += $(foreach c,$($(docutils.)CONFIG),--config=$(subst %,$(*D)/,$(findstring %,$(c)))$(subst %,$(*F),$(c)))
	$(docutils.)RST2HTML.FLAGS += $($(docutils.)FLAGS)
	$(docutils.)RST2LATEX.FLAGS += $($(docutils.)FLAGS)
	$(docutils.)PEPTOOL.FLAGS += $($(docutils.)FLAGS)
	
	

Extra dependencies
==================

When docutils config files change, it usually affects docutils' so it should
be rebuilt.  So we add them as dependencies.

.. note:: Deletion of a config file will *not* cause a rebuild.

Figure out the default config files from the environment:

::

	DOCUTILSCONFIG ?= /etc/docutils.conf:./docutils.conf:$(HOME)/.docutils
	

You can set `CONFIG_DEPS` to override the depencies on config files without
changing the actual config files used by docutils.  It's space-separated.

::

	$(docutils.)CONFIG_DEPS ?= $(subst :, ,$(DOCUTILSCONFIG)) $($(docutils.)CONFIG)
	

`EXTRA_DEPS` specifies the actual extra dependencies.

Config files that exist are automatically included (unexistant ones would
cause make to complain that it doesn't know how to build them).

::

	$(docutuls.)EXTRA_DEPS += $(wildcard $($(docutils.)CONFIG_DEPS))
	

Note also that you can supply extra dependencies for pattern rules by
yourself, as long as you don't provide commands, e.g. ::

   foo.html: extra_deps

Typical extra depencies you'd want to add: HTML stylesheets (if you embed
them), files appearing in ``.. include::``.


HTML output
===========

pep-%.html must be before the %.html rule to get higher priority.

::

	pep-%$($(docutils.)PEPTOOL.TRGEXT): pep-%$($(docutils.)PEPTOOL.SRCEXT) \
					    $($(docutils.)EXTRA_DEPS)
		$($(docutils.)PEPTOOL) $($(docutils.)PEPTOOL.FLAGS) $<
	ifneq "$($(docutils.)PEPTOOL.TRGEXT)" ".html"
		# $($(docutils.)PEPTOOL) lacks output file name control, work around.
		mv $(basename $<).html $<
	endif
	
	%$($(docutils.)RST2HTML.TRGEXT): %$($(docutils.)RST2HTML.SRCEXT) \
					 $($(docutils.)EXTRA_DEPS)
		$($(docutils.)RST2HTML) $($(docutils.)RST2HTML.FLAGS) $< $@
	

LaTeX output
============


::

	%$($(docutils.)RST2LATEX.TRGEXT): %$($(docutils.)RST2LATEX.SRCEXT) \
					  $($(docutils.)EXTRA_DEPS)
		$($(docutils.)RST2LATEX) $($(docutils.)RST2LATEX.FLAGS) $< $@
	

LaTeX processing rules
----------------------

This part is not fully parametrized; it's not related to docutils so if you
want to get fancy in this respect, provide your own rules.  You can disable
the rules here, by setting `ENABLE_LATEX_RULES` to 0.

::

	$(docutils.)ENABLE_LATEX_RULES ?= 1
	

PDFLaTeX does a better job than LaTeX->DVIPDF (e.g. it supports hyperlinks
and generates a PDF outline) but you usually can't run the same file through
both LaTeX and PDFLaTeX because they don't understand a single common
format.  Solution: there is a separate preprocessing stage
PDFLATEX_WILD_EXTS.  Set this to 0 to go through DVIPDF.

::

	$(docutils.)ENABLE_PDFLATEX ?= 1
	
	ifeq "$($(docutils.)ENABLE_LATEX_RULES)" "1"
	

These variables are common-practice but it's still cleaner to put them in
the "namespace".


::

	$(docutils.)LATEX ?= latex
	$(docutils.)PDFLATEX ?= pdflatex
	$(docutils.)DVIPS ?= dvips
	$(docutils.)DVIPDF ?= dvipdf
	
	%.dvi: %.tex
		cd $(*D); $(LATEX) $(*F)
	
	%.ps: %.dvi
		$(DVIPS) $< -o $@
	
	ifeq "$($(docutils.)ENABLE_PDFLATEX)" "1"
	%.pdf: %.pdftex
		cd $(*D); $(PDFLATEX) $(*F).pdftex
	else
	%.pdf: %.dvi
		$(DVIPDF) $< $@
	endif
	
	endif # ENABLE_LATEX_RULES
	

Fallback when you don't provide for different PDFLaTeX processing.

::

	%$($(docutils.)RST2PDFLATEX.TRGEXT): %$($(docutils.)RST2LATEX.TRGEXT)
		cp $< $@
	
	

Typical standard targets
************************

This section provides typical rules for processing documents with docutils.
Since they might clash with your rules, they are optional and can be
disabled by setting `ENABLE_COMMON_TARGETS` to ``0``.

::

	$(docutils.)ENABLE_COMMON_TARGETS ?= 1
	

`DOCS` gives the documents to process.  You should typically set this
(defaults to all files with the source extension in current directory).

::

	$(docutils.)DOCS ?= $(wildcard *$($(docutils.)SRCEXT))
	

`STEMS` is the docs list without the source extension, (makes rules shorter).

::

	$(docutils.)STEMS ?= $($(docutils.)DOCS:$($(docutils.)SRCEXT)=)
	

Set `ALL` to change the things to build by default.

::

	$(docutils.)ALL ?= html ps pdf
	
	ifeq "$($(docutils.)ENABLE_COMMON_TARGETS)" "1"
	
	docutils.all: $($(docutils.)ALL)
	

Targets like ``clean`` weren't directly used.  Rather they don't have
commands but have targets like ``docutils.clean`` (that do have commands) as
prerequisites.  This allows you to give your commands for them.  You can
inhibit these alias dependencies by setting `ENABLE_SHORT_TARGETS` to 0.

::

	$(docutils.)ENABLE_SHORT_TARGETS ?= 1
	
	ifeq "$($(docutils.)ENABLE_SHORT_TARGETS)" "1"
	all: docutils.all
	safeclean: docutils.safeclean
	mostlyclean: docutils.mostlyclean
	clean: docutils.clean
	endif
	
	html: $($(docutils.)STEMS:=.html)
	tex: $($(docutils.)STEMS:=.tex)
	dvi: $($(docutils.)STEMS:=.dvi)
	ps: $($(docutils.)STEMS:=.ps)
	pdf: $($(docutils.)STEMS:=.pdf)
	

Extensions of unneeded byproducts (specifically, LaTeX byproducts).

::

	$(docutils.)SAFECLEAN_EXTS += .log .aux .out .toc
	

Extensions that are direct outputs of this makefile.

::

	$(docutils.)CLEAN_EXTS += $(foreach tool,$($(docutils.)TOOLS),$($(docutils.)$(tool).TRGEXT))
	$(docutils.)CLEAN_EXTS += .dvi .ps .pdf
	

`safeclean` cleans only unneeded byproducts.

::

	docutils.safeclean:
		-rm -f $(foreach ext,$($(docutils.)SAFECLEAN_EXTS),$($(docutils.)STEMS:=$(ext)))
	

`mostlyclean` cleans almost everything.

::

	docutils.mostlyclean: docutils.safeclean
		-rm -f $(foreach ext,$($(docutils.)CLEAN_EXTS),$($(docutils.)STEMS:=$(ext)))
	

`clean` also cleans imgmathhack images that take a lot of time to rebuild.

::

	docutils.clean: docutils.mostlyclean
	ifeq "$($(docutils.)ENABLE_MATHHACK)" "1"
		-rm -rf ./imgmath/
	endif
	
	endif # ENABLE_COMMON_TARGETS