.. -*- 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 (`.SRCEXT` and `.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 `.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