re-added docutils-0.3.9 tag one level deeper (without web/ and sandboxes/)docutils-0.3.9

git-svn-id: http://svn.code.sf.net/p/docutils/code/tags/docutils-0.3.9@3815 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

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