From: Cherniavsky B. <cb...@us...> - 2004-02-28 22:13:52
|
Update of /cvsroot/docutils/sandbox/cben/make In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv8841 Modified Files: Makefile.docutils README.txt Added Files: Makefile make2rst.py Removed Files: Makelib.docutils Log Message: - Merged Makelib.docutils into Makefile.docutils (making it conditional). - Implemented quick-and-dirty ``make2rst.py``. Index: Makefile.docutils =================================================================== RCS file: /cvsroot/docutils/sandbox/cben/make/Makefile.docutils,v retrieving revision 1.3 retrieving revision 1.4 diff -u -d -r1.3 -r1.4 --- Makefile.docutils 16 Dec 2003 23:33:07 -0000 1.3 +++ Makefile.docutils 28 Feb 2004 21:56:15 -0000 1.4 @@ -1,48 +1,410 @@ # .. -*- Makefile -*- -# Makefile with typical rules for docutils -# **************************************** +# ****************************************************** +# Generic makefile for document processing with docutils +# ****************************************************** -# This file provides typical rules for processing documents with docutils. -# It's mainly intended for including in your makefile after setting some -# variables (at least `DOCS`) but it can function as a standalone makefile -# too (processing *.txt in this directory). +# 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. -# GNU Make is required! +# 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). -# The last version of this files is availiable at +# 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 -# Almost everything is intended to be configurable by setting variables -# defined in this file and `<Makelib.docutils>`_. The ``docutils.`` prefix is -# by default disabled to allow easy configuration on the make command line. -# Feel free to enable it. + +# "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. -include Makelib.docutils -# Now we can use variables defined there. +# Pattern rules - very include-friendly makefile portion +# ****************************************************** -# This gives the documents to process. You should typically set this. +# 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 mathhack.py and +# 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) +$(docutils.)MATHHACK.TRGEXT ?= .txt.mathhack + +# 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) +$(docutils.)IMGMATHHACK.TRGEXT ?= .txt.imgmathhack + +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' $< > $@ + + +# Extra options +# ============= + +# You can provide extra docutils options by setting variables named +# `<toolname>.FLAGS`. `FLAGS` gives default flags for all tools. +$(docutils.)FLAGS ?= +$(docutils.)RST2HTML.FLAGS += $($(docutils.)FLAGS) +$(docutils.)RST2LATEX.FLAGS += $($(docutils.)FLAGS) +$(docutils.)PEPTOOL.FLAGS += $($(docutils.)FLAGS) + +# Consider using config files instead of flags for most tasks. +# Note that you can do something like:: +# +# RST2HTML.FLAGS += --config=$(*D)/docutils.conf +# +# to use per-directory config files; similar tricks allow per-file config... + + +# Extra dependencies +# ================== + +# When docutils config files change, it usually affects docutils' so it should +# be rebuilt. So we add them as dependencies. + +# Figure out the config files from the environment: +DOCUTILSCONFIG ?= /etc/docutils.conf:./docutils.conf:$(HOME)/.docutils + +# Please *don't* override `DOCUTILSCONFIG` in makefiles, it's for the user. +# Note that ``./docutils.conf`` is taken from the current working directory +# which need not be the same as the processed file's, which gives you some +# control. Add ``--config=...`` to `FLAGS` for more control. + +# 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)) + +# `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)) -# The docs without the suffix, making rules shorter. + +# `STEMS` is the docs list without the source extension, (makes rules shorter). $(docutils.)STEMS ?= $($(docutils.)DOCS:$($(docutils.)SRCEXT)=) -# Set $(docutils.)ALL to change the things to build by default. +# 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. +# 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 -all: docutils.all endif html: $($(docutils.)STEMS:=.html) @@ -51,19 +413,25 @@ 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 -# Extensions of unnneded byproducts. -$(docutils.)SAFECLEAN_EXTS += .log .aux .out .toc +# `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 --- Makelib.docutils DELETED --- --- NEW FILE: Makefile --- # .. -*- Makefile -*- # This makefile pertains build documention about ``Makefile.docutils`` only. DOCS = Makefile.docutils.txt README.txt ALL = html include Makefile.docutils Makefile.docutils.txt: Makefile.docutils ./make2rst.py $< > $@ --- NEW FILE: make2rst.py --- #!/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:]) Index: README.txt =================================================================== RCS file: /cvsroot/docutils/sandbox/cben/make/README.txt,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- README.txt 22 Nov 2003 21:57:17 -0000 1.1 +++ README.txt 28 Feb 2004 21:56:15 -0000 1.2 @@ -1,21 +1,15 @@ -This directory contains parts of makefiles intended for inclusion in your -makefiles. - -``Makelib.docutils`` contains only variables settings and implicit rules. -It's designed to be maximally friendly to the makefile it's included in. - -``Makefile.docutils`` includes the above file and builds upon it some useful -rules like ``html``, ``pdf`` or ``clean``. The minimum example of a makefile -including it is:: +`Makefile.docutils <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 -However these makefiles are very flexible and configurable by setting many -variables. They also support pre/postprocessing, notably with +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 -format-dependant convertion of ``.*`` names with sed scripts. +output-format-dependant convertion of ``.*`` names with sed scripts. Enjoy and tell me (cb...@us...) if you miss any functionality or flexibility... |