diff options
Diffstat (limited to 'sandbox/cben')
| -rw-r--r-- | sandbox/cben/make/Makefile | 11 | ||||
| -rw-r--r-- | sandbox/cben/make/Makefile.docutils | 454 | ||||
| -rw-r--r-- | sandbox/cben/make/Makefile.docutils.txt | 617 | ||||
| -rw-r--r-- | sandbox/cben/make/README.txt | 23 | ||||
| -rwxr-xr-x | sandbox/cben/make/make2rst.py | 57 | ||||
| -rw-r--r-- | sandbox/cben/rolehack/README.txt | 66 | ||||
| -rwxr-xr-x | sandbox/cben/rolehack/imgmathhack.py | 98 | ||||
| -rwxr-xr-x | sandbox/cben/rolehack/mathhack.py | 27 | ||||
| -rw-r--r-- | sandbox/cben/rolehack/rolehack.py | 192 |
9 files changed, 0 insertions, 1545 deletions
diff --git a/sandbox/cben/make/Makefile b/sandbox/cben/make/Makefile deleted file mode 100644 index 81679f24d..000000000 --- a/sandbox/cben/make/Makefile +++ /dev/null @@ -1,11 +0,0 @@ -# .. -*- Makefile -*- - -# This makefile only builds documention for ``Makefile.docutils`` (which see). - -DOCS = Makefile.docutils.txt README.txt -ALL = html - -include Makefile.docutils - -Makefile.docutils.txt: Makefile.docutils - ./make2rst.py $< > $@ diff --git a/sandbox/cben/make/Makefile.docutils b/sandbox/cben/make/Makefile.docutils deleted file mode 100644 index c7f785327..000000000 --- a/sandbox/cben/make/Makefile.docutils +++ /dev/null @@ -1,454 +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 - -# ``rstpep2html.py`` is the RST PEP -> HTML converter tool; -# ``pep2html.py`` also supports old PEP format and does extra PEP -# services. -$(docutils.)RSTPEP2HTML ?= rstpep2html.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 diff --git a/sandbox/cben/make/Makefile.docutils.txt b/sandbox/cben/make/Makefile.docutils.txt deleted file mode 100644 index 956ecdb06..000000000 --- a/sandbox/cben/make/Makefile.docutils.txt +++ /dev/null @@ -1,617 +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 - - -``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 diff --git a/sandbox/cben/make/README.txt b/sandbox/cben/make/README.txt deleted file mode 100644 index 6447967cb..000000000 --- a/sandbox/cben/make/README.txt +++ /dev/null @@ -1,23 +0,0 @@ -`<Makefile.docutils>`_ is a makefile that handles most things one would want -to do with docutils. For minimal applications it can be used directly; -typically you would include it in your makefiles, e.g.:: - - DOCS = foo.txt bar.txt - - include Makefile.docutils - -For quick jobs ``make DOCS=foo.txt\ bar.txt`` or just ``make`` (taking all -``*.txt`` files) will also work. - -This makefile is very flexible and can be configured by setting many -variables. It also supports pre/postprocessing, currently with -`sandbox/cben/rolehack <../rolehack>`_ scripts and rudimentary -output-format-dependant adaptation of ``.*`` names with sed scripts. - -The makefile is heavily commented and the comments themeselves are in reST -(sort of literate programming). A script (`<make2rst.py>`_) is provided that -can convert the whole file to legal reST - run ``make`` in this directory to -build the docs (``make ps pdf`` would give you more formats). - -Enjoy and tell me (cben@users.sf.net) if you miss any functionality or -flexibility... diff --git a/sandbox/cben/make/make2rst.py b/sandbox/cben/make/make2rst.py deleted file mode 100755 index 1a4498f0c..000000000 --- a/sandbox/cben/make/make2rst.py +++ /dev/null @@ -1,57 +0,0 @@ -#!/usr/bin/env python -""" -A simple tool for converting a Makefile to reStructuredText. - -Basically it strips all comments starting at column 0 that don't start with -``##`` and converts all the rest to literal blocks. The first comment line -defines the number of spaces after the comment sign to be ignored (this allows -``# text...`` which is more readable than ``#text...``). - -""" - -from __future__ import generators - -import fileinput, sys - -def convert(lines): - """Generate lines of reST from makefile lines.""" - in_literal_block = False # state - comment_spaces = None # stripped from all lines - leading_spaces = 0 # this/last line's indentation - - for line in lines: - if line.isspace(): - # Empty line accepted in both states. - if not in_literal_block: - line = '#\n' - else: - line = '\n' - if line[0] == '#' and not line[:2] == '##': - # Comment line - if in_literal_block: - yield '\n' - in_literal_block = False - - line = line.expandtabs()[1:] - leading_spaces = len(line) - len(line.lstrip(' ')) - if comment_spaces is None: - comment_spaces = leading_spaces - else: - line = line[min(leading_spaces, comment_spaces):] - - yield line - else: - # Literal line - if not in_literal_block: - yield '\n' - yield '::\n' - yield '\n' - in_literal_block = True - - yield '\t' + line - -def main(*args): - sys.stdout.writelines(convert(fileinput.input(args))) - -if __name__ == '__main__': - main(*sys.argv[1:]) diff --git a/sandbox/cben/rolehack/README.txt b/sandbox/cben/rolehack/README.txt deleted file mode 100644 index 1ec7d8bda..000000000 --- a/sandbox/cben/rolehack/README.txt +++ /dev/null @@ -1,66 +0,0 @@ -Mathhack Instructions -===================== - -Formula syntax is everything LaTeX supports in math mode. This is supported -for the LaTeX writer and for anything else by converting with LaTeX (and some -external_ commands) to *images*. - -There are now other solutions (see the FAQ entry__) that employ dialects of -LaTeX for translation to MathML so you should consider limiting yourself to -the intersection of the syntaxes if you want to allow all possible convertions. - -__ http://docutils.sourceforge.net/ - FAQ.html#how-can-i-include-mathematical-equations-in-documents - -Just write:: - - text... :texmath:`formula` ...text - -or simply:: - - text... `formula` ...text - -for inline formulas; for display formulas use a directive:: - - .. texmath:: formula - -Inline formulas can also be written with substitution references:: - - text... |name| ...text - - .. |name| texmath:: formula - -Now you take this (in file foo.txt) and run:: - - mathhack.py foo.txt | rst2latex.py - foo.tex - -which converts the roles/directives to ``raw:: latex`` directives or:: - - imgmathhack.py foo.txt | html.py - foo.html - -which runs TeX (generating images into a subdirectory!) and converts -the roles/directives into ``img::`` directives. Quick, dirty and -convenient ;-). - -To allow including preprocessed files, do:: - - mathhack.py included.txt > included.txt.mathhack - imgmathhack.py included.txt > included.txt.imgmathhack - -and include ``included.txt.mathhack`` (imgmathhack.py will mangle this to -include ``included.txt.imgmathhack`` automatically). My makefile_ can do all -this for you (just set ENABLE_MATHHACK=1). - -.. _makefile: ../make/Makefile.docutils - -.. _external: - -Note that the `<imgmathhack.py>`_ script relies on some external commands (see -the comments at its top). `tex_to_images` seems to be separately availiable -from the `speech_tools CVS`__ - -__ http://cvs.sf.net/viewcvs.py/*checkout*/emu/speech_tools/scripts/tex_to_images.prl?rev=HEAD - -Also note that the scripts use regexps to "parse" the roles/directives, so -expect some bugs (e.g. don't try to split a formula into multiple lines inside -a table cell...). diff --git a/sandbox/cben/rolehack/imgmathhack.py b/sandbox/cben/rolehack/imgmathhack.py deleted file mode 100755 index 084dc05f0..000000000 --- a/sandbox/cben/rolehack/imgmathhack.py +++ /dev/null @@ -1,98 +0,0 @@ -#!/usr/bin/env python -""" -Convert latex math to images. Treats the default and ``texmath`` roles as -inline LaTeX math and the ``texmath::`` directive as display latex math. - -If you include a file which also needs mathhack/imgmathhack preprocessing, -write a name containing ``.mathhack`` in the include directive and it will be -replaced with ``.imgmathhack`` when preprocessed by this script (of course, -you should create both preprocessed versions of the file). - -.. note:: - This runs external commands and leaves files after itself! To reduce - running time when images are not changed and to reuse images for equal - fomulas, image names are md5 of the formula (hoping that no collisions - will happen) and images that already exist are not rebuilt. You should - purge the ``imgmath`` subdirectory manually to get rid of unused formulas. - - You'll need: - - - ``tex_to_images``, last version seems to live at the `speech_tools - CVS`__. - - __ http://cvs.sourceforge.net/viewcvs.py/*checkout*/ - emu/speech_tools/scripts/tex_to_images.prl?rev=HEAD - - It, in turn, relies upon: - - - LaTeX - - ``dviselect`` (part of ``dviutils``) - - ``dvips`` - - Ghoscript - - netpbm tools -""" - -import os, os.path, md5 - -from rolehack import * - -class Tex_to_images(object): - """Feeds math to ``tex_to_images``. Always goes through ppm.""" - def __init__(self, dir='./imgmath', options='-s 1.5', - converter='pnmtopng', extension='.png'): - try: - os.mkdir(dir) - except OSError: - pass - self.options = options - self.dir = dir - self.converter = converter - self.extension = extension - def process(self, text): - """Returns output filename.""" - dir = self.dir - extension = self.extension - options = self.options - converter = self.converter - fname = md5.new(text).hexdigest() - fpath = os.path.join(dir, fname) - if not os.path.exists(fpath + extension): - f = file(fpath, 'w') - f.write('@Start\n%s\n@End\n' % (text,)) - f.close() - os.system(('tex_to_images -f ppm -d %(dir)s -o %(fname)s.tmp ' - '%(options)s < %(fpath)s >& /dev/null' % vars())) - if self.converter: - os.system('%s < %s.tmp > %s%s' % - (self.converter, fpath, fpath, extension)) - else: - os.rename(fpath + '.tmp', fpath + '.ppm') - os.remove(fpath + '.tmp') - return fpath + extension - def texmath(self, text): - text = ' '.join(text.split()) - src = self.process(text) - return '''\ -image:: %(src)s - :align: middle - :class: texmath - :alt: %(text)s -''' % locals() - def texdisplay(self, text): - src = self.process(text) - return '''\ -image:: %(src)s - :align: center - :class: texdisplay - :alt: %(text)s -''' % locals() - -child = Tex_to_images() -texmath = child.texmath -texdisplay = child.texdisplay - -def mangle_include(text): - return 'include:: ' + text.replace('.mathhack', '.imgmathhack') - -main({'texmath': texmath}, texmath, - {'texmath': texdisplay, 'include': mangle_include}) diff --git a/sandbox/cben/rolehack/mathhack.py b/sandbox/cben/rolehack/mathhack.py deleted file mode 100755 index 0a02f231c..000000000 --- a/sandbox/cben/rolehack/mathhack.py +++ /dev/null @@ -1,27 +0,0 @@ -#!/usr/bin/env python -""" -.. epigraph:: - - Using ``raw`` is almost always evidence of a hack in progress. It's not a - clean solution. - - -- David Goodger. - -Convert the default and ``texmath`` role to raw latex inline math and the -``texmath`` directive to display math. -""" - -from rolehack import * - -texmath = template('''\ -raw:: latex - - $''', '$\n') - -texdisplay = template('''\ -raw:: latex - - \[ ''', ' \]\n') - -main({'texmath': texmath}, texmath, - {'texmath': texdisplay}) diff --git a/sandbox/cben/rolehack/rolehack.py b/sandbox/cben/rolehack/rolehack.py deleted file mode 100644 index 13895caa5..000000000 --- a/sandbox/cben/rolehack/rolehack.py +++ /dev/null @@ -1,192 +0,0 @@ -"""Preprocess reStructuredText roles to directives. - -This is a stop-gap hack for prototyping new syntaxes for reST, mainly useful -when you find yourself using directives every 3 lines. In such cases an -extension to docutils allowing some inline syntax is desired thing and such -extensions most probably will take the form of new interpretted text roles. - -This module allows to easily prototype them by converting given interpretted -text roles to directives. To make them inline, the uses of the roles are -replaced with substitutions and all substitution definitions are appeneded at -the end of the document (hint: use ``replace::`` if you don't want a -directive). - -Since what's useful for inline syntaxes might also be useful outside of -paragraphs, preprocessing simple directives (only an argument, no options or -content) into other directives is also supported. - -I was too lazy to implement an elaborate command-line interface, so this is -only a module. You should import it from a python script and call this module -with specific role->template mappings to do the work. - -BUGS -==== - -There are too many. Most can't be fixed here, the right thing is to extend -the docutils parser... - -- Backslashes are not interpretted in any way (except that backticks preceded - by backslashes are won't be treated as start/end of interpretted text). - This means backslashes are passed to the directive which probably won't stay - this way if the role is accepted into docutils (only the double-backtick - literal text syntax behaves this way). - - This bug is semi-intentional because it makes LaTeX generation easier... - -- Any number of lines is consumed in search for the closing backtick, - disregarding indentation. The content is pasted into the directive as one - line with normalized whitespace. - -- The width of the substitution references is not equal to the original, so - you can't use it in tables. - -- Long parts of the document without empty lines might cause ``recursion limit - exceeded`` errors. - -- Directives not recognized if preceded by non-whitespace (e.g. in a table). - -""" - -import re - -# Named groups are used to allow simultaneous replacement of all roles. - -_re_options = re.IGNORECASE | re.MULTILINE | re.DOTALL | re.VERBOSE - -def _role_re(group_name): - return r''' - # Start-string: - (?:^|(?<=\s|[\'"([{<\-/:])) - ` - (?=\S) - # Content: - (?P<%(group_name)s> - (?:[^`]|\\.)+ # skip escaped chars - ) - # End-string: - (?<=\S) - ` - (?=$|\s|[#\'")\]}>\-/:.,;!?\\]) - ''' % locals() - -_default_re = _role_re('_DEFAULT') - -def _role2regexp(role): - """Return regexp for approximate recognition of `role`.""" - prefix_re = _role_re('prefix_' + role) - postfix_re = _role_re('postfix_' + role) - return r''' - :%(role)s: - %(prefix_re)s - | - %(postfix_re)s - :%(role)s: - ''' % locals() - -def _dir2regexp(dir): - """Return regexp for approximate recognition of directive `dir`.""" - return r''' - ^(?P<indent_%(dir)s> [ \t]* ) # record indentation - \.\. \s+ - (?P<subst_%(dir)s> - ## (?:|[^|]*|)? # optional substitution - ) - \s* - %(dir)s \s* :: - (?P<argument_%(dir)s> - [^\n]* - (?: - \n - (?P=indent_%(dir)s) [ \t] # bigger indentation - [^\n]+ - )* - ) - ''' % locals() - -def process(doc, roles={}, default_role=None, directives={}): - """Process `doc` replacing given `roles`. - - `doc` should be a single string containing the whole document. The - `roles` dictionary maps from role names to replacement functions that - should accept the role content and return the directive text, starting - from the directive name, e.g.:: - - def repl(text): - return 'raw:: latex\n\n %s\n' % (text,) - - See `template()` for an easy way to create such trivial functions. The - optional `default_role` argument specifies a replacement for the default - role. - - The `directives` dictionary like `roles` but specifies directive names to - handle. The directive can have only an argument; substitution definitions - with these directives are also recognized. Indentation is adjusted - properly for directives. - - """ - re_parts = [] - repls = {} - if default_role: - re_parts.append(_default_re) - repls['_DEFAULT'] = default_role - for role, repl in roles.items(): - re_parts.append(_role2regexp(role)) - repls['prefix_' + role] = repls['postfix_' + role] = repl - for dir, repl in directives.items(): - re_parts.append(_dir2regexp(dir)) - repls['argument_' + dir] = repl - full_re = '\n|'.join(re_parts) - full_re = re.compile(full_re, _re_options) - - after_output = [] - def count(n=0): - while True: - yield n - n += 1 - ids = count() - def dispatch(match): - groupname = match.lastgroup - content = match.group(groupname) - kind, name = groupname.split('_', 1) - if kind == 'argument': # substitution - indent = match.group('indent_' + name) - subst = match.group('subst_' + name) - repl = '\n.. %s %s' % (subst, repls[groupname](content)) - return indent + repl.replace('\n', '\n' + indent) - else: # role - id = ids.next() - subst = '|rolehack_%d|' % (id,) - repl = '.. %s %s' % (subst, repls[groupname](content)) - after_output.append(repl) - return subst - - # Hack: process by chunks separated by blank lines, trying to avoid - # "recursion limit exceeded" errors. - empty_line_re = re.compile(r'\n[ \t]*\n') - output = [full_re.sub(dispatch, chunk) - for chunk in empty_line_re.split(doc)] - return '\n\n'.join(output + after_output) - -def template(pre, post): - """Make replacement function for wrapping content with two strings.""" - def repl(text): - return ''.join((pre, text, post)) - return repl - -def main(*args, **kw_args): - """Simple command-line interface.""" - import sys - def parse_args(input='-', output='-'): - if input == '-': - input = sys.stdin - else: - input = file(input) - if output == '-': - output = sys.stdout - else: - output = file(output, 'w') - output.write(process(input.read(), *args, **kw_args)) - parse_args(*sys.argv[1:]) - -##main({'foo': template('foo::\n\n ', '\n')}, -## template('default::\n\n ', '\n')) |