mjo-hurwitz.tex: new file for Hurwitz algebras (quaternions and octonions).
[mjotex.git] / GNUmakefile
1 #
2 # Example makefile using mjotex and a BibTeX references database.
3 #
4
5 # The latex compiler. The SOURCE_DATE_EPOCH=0 prevents the creation
6 # and modification dates from being embedded as metadata into the
7 # output file; that in turn is important because it allows us to tell
8 # when the output stops changing (that is, when we are done). The
9 # variable is supported in pdftex v1.40.17 and later.
10 LATEX = SOURCE_DATE_EPOCH=0 pdflatex -file-line-error -halt-on-error
11
12 # The name of this document.
13 #
14 # For example, to use the name of our parent directory:
15 #
16 # PN = $(notdir $(realpath .))
17 #
18 PN = examples
19
20 # A space-separated list of bib files. These must all belong to paths
21 # contained in your $BIBINPUTS environment variable.
22 #
23 # Leave commented if you don't use a bibliography database.
24 #
25 BIBS = local-references.bib
26
27 # A space-separated list of the mjotex files that you use. The path to
28 # mjotex must be contain in your $TEXINPUTS environment variable.
29 #
30 # MJOTEX = mjotex.sty
31 #
32 MJOTEX = mjo-algebra.tex mjo-algorithm.tex mjo-arrow.tex mjo-calculus.tex
33 MJOTEX += mjo-common.tex mjo-complex.tex mjo-cone.tex mjo-convex.tex
34 MJOTEX += mjo-eja.tex mjo-font.tex mjo-hurwitz.tex mjo-linear_algebra.tex
35 MJOTEX += mjo-listing.tex mjo-proof_by_cases.tex mjo-set.tex mjo-theorem.tex
36 MJOTEX += mjo-theorem-star.tex mjo-topology.tex mjo.bst
37
38 # Compile a list of raw source code listings (*.listing) and their
39 # associated output files (*.py) that will be tested by check-sage.
40 SAGE_LISTING_SRCS = $(wildcard sage_listings/*.listing)
41 SAGE_LISTING_DSTS = $(patsubst %.listing,%.py,$(SAGE_LISTING_SRCS))
42
43 # A space-separated list of indices (just their names). Usually you'll
44 # have just one, and it will be named the same thing as your document,
45 # because that's what the makeidx package does.
46 #
47 # Leave commented if you don't use an index.
48 #
49 INDICES = $(PN)
50
51 # We have to rebuild the index whenever the contents of the document
52 # change, because page numbers get moved around. But when no INDICES
53 # are defined, rebuilding them should be a no-op. This next definition
54 # ensures that.
55 ifdef INDICES
56 REMAKE_INDICES = makeindex $(INDEX_SRCS)
57 else
58 REMAKE_INDICES = true
59 endif
60
61 # Use kpsewhich (from the kpathsea suite) to find the absolute paths
62 # of the bibtex/mjotex files listed in in $(BIBS)/$(MJOTEX). The SRCS
63 # variable should contain all (Bib)TeX source files for the document.
64 SRCS = $(PN).tex
65 ifdef BIBS
66 BIBPATHS = $(shell kpsewhich $(BIBS))
67 SRCS += $(BIBPATHS)
68 endif
69 ifdef MJOTEX
70 MJOTEXPATHS = $(shell kpsewhich $(MJOTEX))
71 SRCS += $(MJOTEXPATHS)
72 endif
73 ifdef SAGE_LISTING_DSTS
74 SRCS += $(SAGE_LISTING_DSTS)
75 endif
76
77 ifdef INDICES
78 INDEX_SRCS = $(addsuffix .idx,$(INDICES))
79 INDEX_DSTS = $(addsuffix .ind,$(INDICES))
80 endif
81
82 # The first target is the default, so put the PDF document first.
83 #
84 # This voodoo is all designed to find a "fixed point" of calling
85 # $(LATEX). When you build a LaTeX document, it requires an unknown
86 # number of compilation passes. How do you know when to stop? Easy,
87 # stop when the output file stops changing! But how to encode that
88 # in a makefile?
89 #
90 # At the start of this target, we call $(LATEX) to compile $(PN).tex.
91 # Afterwards, we check for the existence of a "previous" file. If
92 # there isn't one, then this is the first time that we've built the
93 # PDF. In that case, we take the PDF that we've just built and make it
94 # the "previous" file before starting all over. If, on the other hand,
95 # there already *was* a "previous" file, then this is the second (or
96 # third...) time that we've built the PDF. We diff the newly-built PDF
97 # against the "previous" file; if they're the same, then we've
98 # succeeded and stop. Otherwise, we make the new PDF the "previous"
99 # one, and start all over. The end result is that we will loop until
100 # the newly-created PDF and the "previous" one are identical.
101 #
102 $(PN).pdf: $(SRCS) $(PN).bbl $(INDEX_DSTS)
103 $(LATEX) $(PN).tex
104
105 if [ -f $@.previous ] && cmp -s $@ $@.previous; then \
106 rm $@.previous; \
107 else \
108 mv $@ $@.previous; \
109 $(REMAKE_INDICES); \
110 $(MAKE) $@; \
111 fi;
112
113
114 $(PN).aux: $(SRCS)
115 $(LATEX) $(PN).tex
116
117
118 ifdef INDICES
119 # We need to be able to build the index source files without involving
120 # the main $(PN).pdf rule, in order to avoid a chicken-and-egg problem.
121 # This is similar to the $(PN).aux rule above, except that an index is
122 # optional and there might be more than one of them.
123 $(INDEX_SRCS): $(PN).tex
124 $(LATEX) $(PN).tex
125 endif
126
127 ifdef INDICES
128 # Create real indices from source files by running "makeindex" on
129 # them. We depend on SRCS here because we *do* want to rebuild the
130 # index if the source document changes, but we use an order-only
131 # dependency (see the bbl rule below) on the idx files to prevent us
132 # from going into a rebuild loop when the idx files are regenerated.
133 %.ind: $(SRCS) | %.idx
134 makeindex $|
135 endif
136
137 # The pipe below indicates an "order-only dependency" on the aux file.
138 # Without it, every compilation of $(PN).tex would produce a new
139 # $(PN).aux, and thus $(PN).bbl would be rebuilt. This in turn causes
140 # $(PN).pdf to appear out-of-date, which leads to a recompilation of
141 # $(PN).tex... and so on. The order-only dependency means we won't
142 # rebuild $(PN).bbl if $(PN).aux changes.
143 #
144 # As a side effect, we now need to depend on $(SRCS) here, since we
145 # won't pick it up transitively from $(PN).aux.
146 #
147 # If the $BIBS variable is undefined, we presume that there are no
148 # references and create an empty bbl file. Otherwise, we risk trying
149 # to run biblatex on an aux file containing no citations. If you do
150 # define $BIBS but don't cite anything, you'll run into a similar
151 # problem. Don't do that.
152 #
153 $(PN).bbl: $(SRCS) | $(PN).aux
154 ifdef BIBS
155 bibtex $(PN).aux
156 else
157 printf '' > $@
158 endif
159
160 # If the output PDF exists but the log file does not, then an attempt
161 # to "build the log file" (i.e. build the PDF) would do nothing. Thus
162 # whenever the log file does not exist, we do a fresh build.
163 $(PN).log: $(SRCS)
164 $(MAKE) clean
165 $(MAKE)
166
167 # How do we convert a raw listing into something testable by sage? We
168 # append/prepend triple quotes to make the whole thing into a doctest,
169 # and then we replace any blank lines by "<BLANKLINE>".
170 sage_listings/%.py: sage_listings/%.listing
171 echo '"""' > $@ && cat $< >> $@ && echo '"""' >> $@ && sed -i 's/^[[:space:]]*$$/<BLANKLINE>/' $@
172
173 # Ensure that there are no overfull or underfull boxes in the output
174 # document by parsing the log for said warnings.
175 .PHONY: check-boxes
176 check-boxes: $(PN).log
177 @! grep -i 'overfull\|underfull' $<
178
179 # Run chktex to find silly mistakes. There is some exit code weirdness
180 # (Savannah bug 53129), so we just look for empty output.
181 .PHONY: check-chktex
182 CHKTEX = chktex --localrc .chktexrc --quiet --inputfiles=0
183 check-chktex:
184 @chktexout=$$($(CHKTEX) $(PN).tex); \
185 test -z "$${chktexout}" || { echo "$${chktexout}" 1>&2; exit 1; }
186
187 # Ensure that there are no undefined references in the document by
188 # parsing the log file for said warnings.
189 .PHONY: check-undefined
190 check-undefined: $(PN).log
191 @! grep -i 'undefined' $<
192
193 # Use sage to doctest any \sagelisting{}s in SAGE_LISTING_DSTS.
194 # The actuall command is ifdef'd so that we can comment out
195 # the definition of SAGE_LISTING_DSTS without breaking the
196 # default definition of the "check" target.
197 .PHONY: check-sage
198 check-sage: $(SAGE_LISTING_DSTS)
199 ifdef SAGE_LISTING_DSTS
200 sage -t --timeout=0 --memlimit=0 $^
201 endif
202
203 # Run a suite of checks.
204 .PHONY: check
205 check: check-boxes check-chktex check-undefined check-sage
206
207 # Clean up leftover junk. This only looks overcomplicated because
208 # the *.{foo,bar} syntax supported by Bash is not POSIX, and Make
209 # will execute these commands using /bin/sh (which should be POSIX).
210 JUNK_EXTENSIONS = aux bbl bcf blg glo ilg ist listing lof log nav out pdf
211 JUNK_EXTENSIONS += snm spl toc xml
212 .PHONY: clean
213 clean:
214 for ext in $(JUNK_EXTENSIONS); do rm -f *.$$ext; done;
215 rm -rf dist/
216 rm -f $(SAGE_LISTING_DSTS) $(INDEX_SRCS) $(INDEX_DSTS)
217
218 # If this document will be published, the publisher isn't going to
219 # have your BibTeX database or your mjotex files. So, you need to
220 # package them up along with the code for your document. This target
221 # will create a "dist" directory and copy the necessary stuff there.
222 #
223 .PHONY: dist
224 dist: $(PN).bbl
225 mkdir -p dist
226 cp $(SRCS) $(PN).bbl dist/