
# For better or for worse, the book's build procedure has grown somewhat
# complicated over time.  This is not because the author wanted to break
# from standard LaTeX book format; he didn't and for the most part
# hasn't.  It is for small reasons, like the need to combine Timothy
# Van Zandt's PSTricks package with proper PDF page numbering, or the
# need for an extra digit of section number (10.10 instead of just 10.9)
# in the book's table of contents.
#
# Actually, for what it does, the build procedure is a good, clean
# one---or so the author believes.  If you find yourself maintaining the
# book and do not understand at first what the extra parts of the build
# procedure do, then you can remove the parts one by one until you reach
# a comfortable position, and then add the parts back one by one as you
# climb the learning curve.  Except in ../btool/fill-toc-ends
# (a minor step which you can omit if you wish with little harm), the
# build does little or nothing in a tricky way.  But, still, for a LaTeX
# document, there is admittedly a fair bit to building this one.  The
# author develops on a standard Debian platform; you might try that if
# appropriate and you think that it will help.  Good luck.
#
# On the other hand, if you do not yet know make(1), sed(1), bash(1)
# and C++, well, those are standard tools; sorry.  It's hard, but that
# is the way it has to be.  The author has tried to avoid doing things
# in *nonstandard* ways, not to avoid doing them in standard ways!  The
# author has even refrained from inflicting Perl on you, confining its
# use strictly to the optional development helpers (and has refrained
# from inflicting the Autotools even on himself); and of course he has
# written all narrative solely in English.  For certain tasks, one needs
# certain skills; so you will probably need to learn the standard tools
# make(1), sed(1), bash(1) and maybe C++, along with LaTeX and the
# English language of course, decently thoroughly to grok this source.
#
# Some comments on the last point seem in order.  If you have peeked at
# various free-software sources from time to time but have not really
# understood most of it very well, well, it must be admitted that some
# of it is not very understandable.  However, a lot of it is
# understandable; you just have to learn how to understand it.  There is
# no substitute for taking the trouble to learn.  The author stood in
# your place as recently as 1996; he had to learn, too, mostly by
# reviewing sources like the one you are reading now, not understanding,
# going away and reading dense manuals, returning, understanding a
# little more, etc.  Esoteric tools and software written in poor style,
# you can mostly ignore, but you cannot afford permanently to ignore
# sophisticated but standard techniques just because they look cryptic
# to you right now, if you want to learn to program free software.  You
# want to learn increasingly sophisticated standard techniques gradually
# over time.
#
# The author has taken moderate pains to ensure that this particular
# source makes a decent model to study, if improving your ability to
# maintain free software and to contribute to its development happens to
# be your goal.  By design, to read this source requires generally
# relevant rather than generally irrelevant programming skills.  The
# short, cryptic-looking but actually logical ../btool/Makefile-subdir
# is a particularly good example of the principle: one needs to know a
# lot to read it, but almost everything one needs to know to read it is
# well worth knowing (or you can just show it to your dad as evidence of
# what you've been doing recently; he'll think it evidence that the
# monkeys have been at your computer keyboard having another go at
# typing Hamlet).
#
# Anyway, back in 1996 the author wished that one of the free-software
# source files he was then trying to understand had taken the trouble to
# explain what the preceding paragraphs have tried to explain.  That
# might have saved the author some grief.  If the paragraphs have
# illuminated anything worth illuminating in your estimation, why, there
# they are, and make of them what you will.
#
#

SHELL  := /bin/bash

out    := derivations
class  := book

def    := def.tex
main0  := main
bib    := bib.bib
tmpl0  := template

clsdir := /usr/share/texmf-texlive/tex/latex/base

# The author cannot say definitively at which PDF level it is best to
# build the book.  Plainly, the higher the level, the greater the number
# of readers who will have trouble opening the PDF.  Also, incrementing
# the level could break the book's build tools.  The author's current
# Ghostscript can build levels 1.2, 1.3 and 1.4; all these seem to
# suffice.  As it happens, while programming the build tools, the author
# read parts of Adobe's PDF Reference 1.7, learning that level 1.5
# brings some potentially interesting features like image transparency,
# but that level 1.6 brings features of another character.  Level 1.6
# brings advanced features like encryption, interactive form pages and
# three-dimensional rendering, which are complex (thus suspected to
# break build tools) and probably mostly, maybe even wholly, useless to
# the book.  If one has no reason to do otherwise, one might refrain
# from increasing $(pdflvl) beyond 1.5 for this reason, even if and when
# Ghostscript gains the ability to produce PDF 1.6 or better.
pdflvl := 1.4

# The following are for sed(1) to adapt $(cls).  No
# parameter $(l1a) is formally defined, but this only
# because the corresponding length, 1.5em, is not
# altered; logically, l1a := 1.5em is there.
# Observe that $(l2a) = $(l1a) + $(l1b), and likewise
# that $(l3a) = $(l2a) + $(l2b); otherwise the entries
# in the book's table of contents would not fall
# visually into proper vertical line.  Observe however
# that per the original $(cls0) the pattern does not
# carry through to $(l4a).
p1   := \\newcommand\*\\l@
p2   := \\@dottedtocline
l1b  := 2.5em
l2a  := 4.0em
l2b  := 3.3em
l3a  := 7.3em

# ----------------------------------------------------------------------

main   := $(main0).tex
cls0   := $(class).cls
cls    := $(out)-$(cls0)
ch     := $(filter-out $(main) $(def) $(wildcard $(tmpl0)-*.tex), \
  $(wildcard *.tex))
define gs
	gs \
	  -dSAFER -dNOPAUSE -dBATCH \
	  -sDEVICE=pdfwrite -dCompatibilityLevel=$(pdflvl) \
	  -sPAPERSIZE=letter \
	  -sOutputFile=$@ $<
endef

.PHONY: all FORCE
all : $(out).ps $(out).pdf

$(out).dvi : $(main) $(def) $(cls) $(ch) $(bib)
	rubber $<
	mv -v $(main0).dvi $@
%.dvi      : %.tex $(def)
	rubber $<
%.ps       : %.dvi
	dvips -t letter -o $@ $<
# See the dvipdf(1), ps2pdfwr(1) and gs(1) manpages for explanation
# of the following rule.
%.pdf      : %.ps ; $(gs)

# Do you like unreadable sed(1) expressions?  Here are some.  Actually,
# if you know sed(1) and also understand the escaping role of the dollar
# sign ($) in make(1), then the expressions are not *quite* as unreadable as
# they look.  [If you do not, then you might learn when you have some time:
# sed(1) and make(1) are standard tools worth learning.]  Comments tend to grow
# outdated, so you might be wary of these words, but at the time of this
# writing the sole purpose of the sed(1) operation here is to create and modify
# a local copy of LaTeX's book class, to allow just a tad extra space between
# the section and subsection numbers and their respective titles in the book's
# table of contents (the creator of LaTeX, Leslie Lamport, evidently estimated
# section number 10.10 to be unlikely, but the book Derivations happens to have
# such sections).
$(cls)     :
	sed >$(cls) $(clsdir)/$(cls0) \
          -e 's/^\(\\ProvidesClass{\)$(class)\(}\)[[:space:]]*$$/\1$(out)-$(class)\2/' \
	  -e 's/^\($(p1)section{$(p2){1}{\)\([^{}]*\)\(}{\)\([^{}]*\)\(}}\)[[:space:]]*$$/\1\2\3$(l1b)\5/' \
	  -e 's/^\($(p1)subsection{$(p2){2}{\)\([^{}]*\)\(}{\)\([^{}]*\)\(}}\)[[:space:]]*$$/\1$(l2a)\3$(l2b)\5/' \
	  -e 's/^\($(p1)subsubsection{$(p2){3}{\)\([^{}]*\)\(}{\)\([^{}]*\)\(}}\)[[:space:]]*$$/\1$(l3a)\3\4\5/'

../btool/complete-pdf ../btool/romanize: FORCE; $(MAKE) -C $(@D) $(@F)
derivations.pdf: derivations.ps ../btool/complete-pdf
	$(gs)
	../btool/fill-toc-ends main.toc main.pgn >pdf-addendum.toc
	../btool/complete-pdf $@ $< pdf-addendum.toc >pdf-addendum
	cat pdf-addendum >>$@

# To "make cleanless" removes the various intermediate TeX working
# files, but leaves intact the final output document files.  The "check"
# target circumvents rubber(1), which quashes LaTeX warnings; with "make
# check", you get an extra latex(1) run which shows any warnings.
.PHONY: check cleanless clean
check      : $(out).dvi
	latex $(main)
cleanless  :
	rm -fv *.{cls,dvi,aux,bbl,blg,idx,ilg,ind,log,lof,lot,toc,pgn,bak} \
	  pdf-addendum
clean      : cleanless
	rm -fv *.{ps,pdf}

