# .. -*- Makefile -*-

# Makefile portion defining pattern rules for docutils
# ****************************************************

# This file is intended 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, the accompanying file
# `<Makefile.docutils>`_ might be what you want.

# GNU Make is required!

# The last version of this files is availiable at
# http://docutils.sourceforge.net/sandbox/cben/make/Makelib.docutils

# "Namespace"
# ===========

# All variables defined in this file are (by default) prefixed with
# ``docutils.`` to avoid namespace pollution.

# If you are too lazy to write out the ``docutils.`` prefix, you can shorten
# [or eliminate] it by setting this variable [to an empty string].  You must
# do it before including this file.  Note that the name ends in a period.
docutils. ?= docutils.

# Tool names
# ==========

# The tools / processing stages that are supported and have [at least some]
# associated variables according to the conventions below:
$(docutils.)TOOLS += RST2HTML PEPTOOL RST2LATEX RST2PDFLATEX		\
		     MATHHACK IMGMATHHACK				\
		     HTML_WILD_EXTS LATEX_WILD_EXTS PDFLATEX_WILD_EXTS

# ``html.py`` is expected to be renamed to ``rst2html.py`` soon.
$(docutils.)RST2HTML ?= html.py
$(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).

# @@@ 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 `$(docutils.)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 that control the
# source/target dependencies 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 we 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 support preprocessing by mathhack.py and
# imgmathhack.py.  Set $(docutils.)ENABLE_MATHHACK to 1 to insert 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 ?= 1
ifeq "$($(docutils.)RST2HTML.ENABLE_SOURCE_URL)" "1"
$(docutils.)RST2HTML.FLAGS += --source-url=$*$($(docutils.)SRCEXT)
endif

# You can set `$(docutils.)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 adapting of file extensions
# .......................................

# Docutils currently doesn't support referencing differnt 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 $(docutils.)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
# $(docutils.)<toolname>.FLAGS.  $(docutils.)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
unexport DOCUTILSCONFIG
# 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.

# Set this to override the depencies on config files without changing the
# actual config files used by docutils.  It's space-separated.
$(docutils.)CONFIG ?= $(subst :, ,$(DOCUTILSCONFIG))

# Add only config files that exist to the actual extra dependencies (or make
# will complain that it doesn't know how to make them).
$(docutuls.)EXTRA_DEPS += $(wildcard $($(docutils.)CONFIG))

# 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 `$(docutils.)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"
LATEX ?= latex
PDFLATEX ?= pdflatex
DVIPS ?= dvips
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

# Fallback when you don't provide for different PDFLaTeX processing.
%$($(docutils.)RST2PDFLATEX.TRGEXT): %$($(docutils.)RST2LATEX.TRGEXT)
	cp $< $@