diff options
Diffstat (limited to 'sandbox/cben/make/Makefile.docutils.txt')
| -rw-r--r-- | sandbox/cben/make/Makefile.docutils.txt | 616 |
1 files changed, 0 insertions, 616 deletions
diff --git a/sandbox/cben/make/Makefile.docutils.txt b/sandbox/cben/make/Makefile.docutils.txt deleted file mode 100644 index 048df0588..000000000 --- a/sandbox/cben/make/Makefile.docutils.txt +++ /dev/null @@ -1,616 +0,0 @@ - .. -*- 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 - - -``pep.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 |