GNUmakefile,examples: overhaul

First, rename GNUmakefile to GNUmakefile.mjo. This contains most of
the logic and has been updated to leave MJOTEX, BIBS, INDICES, and so
on undefined. It is not intended to be invoked directly.

The entire "examples" document has been moved to an "examples"
directory with its own GNUmakefile that declares a few variables and
then includes GNUmakefile.mjo (via kpsewhich). The idea here is that
new projects should be able use a minimal GNUmakefile, offloading most
of the work to GNUmakefile.mjo, wherever it lives.

diff --git a/GNUmakefile b/GNUmakefile.mjo
similarity index 90%
rename from GNUmakefile
rename to GNUmakefile.mjo
index c0071cbfbb251aad56020ef092be3a1ff8bbf5d9..c13e7d38d6ac62123010b3836f2276422dd2b49c 100644 (file)
--- a/GNUmakefile
+++ b/GNUmakefile.mjo
@@ -1,58 +1,27 @@
-#
-# Example makefile using mjotex and a BibTeX references database.
-#
-# After defining $(PN) to be the name of your document, this will
-# compile the source file $(PN).tex to $(PN).pdf.
-#
-# To support workflows where the document is kept open in a PDF reader
-# during recompilation, the build process takes place in a separate
-# $(BUILDDIR) directory that defaults to "build". Only when the build
-# has completed do we move the resulting $(PN).pdf to the current
-# directory. This avoids renaming or modifying the open document in
-# place, which in turn helps prevent flickering, loss of bookmarks, et
-# cetera, in several PDF readers.
-
-# The build directory. Not broken? Don't fix.
-BUILDDIR=build
-
-# The latex compiler. The SOURCE_DATE_EPOCH=0 prevents the creation
-# and modification dates from being embedded as metadata into the
-# output file; that in turn is important because it allows us to tell
-# when the output stops changing (that is, when we are done). The
-# variable is supported in pdftex v1.40.17 and later.
-LATEX = SOURCE_DATE_EPOCH=0 pdflatex -file-line-error -halt-on-error --output-directory $(BUILDDIR)
-
 # The name of this document.
 #
 # For example, to use the name of our parent directory, after
 # stripping the ".git" suffix (if there is one).
 #
-# PN = $(patsubst %.git,%,$(notdir $(realpath .)))
-#
-PN = examples
+# PN = examples
+PN ?= $(patsubst %.git,%,$(notdir $(realpath .)))
 
 # A space-separated list of bib files. These must all belong to paths
 # contained in your $BIBINPUTS environment variable.
 #
 # Leave commented if you don't use a bibliography database.
 #
-BIBS = local-references.bib
+# BIBS = local-references.bib
 
 # A space-separated list of the mjotex files that you use. The path to
 # mjotex must be contain in your $TEXINPUTS environment variable.
 #
 # MJOTEX  = mjotex.sty
-#
-MJOTEX  = mjo-algebra.tex mjo-algorithm.tex mjo-arrow.tex mjo-calculus.tex
-MJOTEX += mjo-common.tex mjo-complex.tex mjo-cone.tex mjo-convex.tex
-MJOTEX += mjo-eja.tex mjo-font.tex mjo-hurwitz.tex mjo-linear_algebra.tex
-MJOTEX += mjo-listing.tex mjo-proof_by_cases.tex mjo-set.tex mjo-theorem.tex
-MJOTEX += mjo-theorem-star.tex mjo-topology.tex mjo.bst
 
 # Compile a list of raw source code listings (*.listing) and their
 # associated output files (*.py) that will be tested by check-sage.
-SAGE_LISTING_SRCS = $(wildcard sage_listings/*.listing)
-SAGE_LISTING_DSTS = $(patsubst %.listing,%.py,$(SAGE_LISTING_SRCS))
+#
+# SAGE_LISTING_SRCS = $(wildcard sage_listings/*.listing)
 
 # A space-separated list of indices (just their names). Usually you'll
 # have just one, and it will be named the same thing as your document,
@@ -60,7 +29,26 @@ SAGE_LISTING_DSTS = $(patsubst %.listing,%.py,$(SAGE_LISTING_SRCS))
 #
 # Leave commented if you don't use an index.
 #
-INDICES = $(PN)
+# INDICES = $(PN)
+
+
+# To support workflows where the document is kept open in a PDF reader
+# during recompilation, the build process takes place in a separate
+# $(BUILDDIR) directory that defaults to "build". Only when the build
+# has completed do we move the resulting $(PN).pdf to the current
+# directory. This avoids renaming or modifying the open document in
+# place, which in turn helps prevent flickering, loss of bookmarks, et
+# cetera, in several PDF readers.
+#
+# The build directory. Not broken? Don't fix.
+BUILDDIR ?= build
+
+# The latex compiler. The SOURCE_DATE_EPOCH=0 prevents the creation
+# and modification dates from being embedded as metadata into the
+# output file; that in turn is important because it allows us to tell
+# when the output stops changing (that is, when we are done). The
+# variable is supported in pdftex v1.40.17 and later.
+LATEX ?= SOURCE_DATE_EPOCH=0 pdflatex -file-line-error -halt-on-error --output-directory $(BUILDDIR)
 
 # We have to rebuild the index whenever the contents of the document
 # change, because page numbers get moved around. But when no INDICES
@@ -84,7 +72,8 @@ ifdef MJOTEX
 MJOTEXPATHS = $(shell kpsewhich $(MJOTEX))
 SRCS += $(MJOTEXPATHS)
 endif
-ifdef SAGE_LISTING_DSTS
+ifdef SAGE_LISTING_SRCS
+SAGE_LISTING_DSTS = $(patsubst %.listing,%.py,$(SAGE_LISTING_SRCS))
 SRCS += $(SAGE_LISTING_DSTS)
 endif
 

diff --git a/examples/GNUmakefile b/examples/GNUmakefile
new file mode 100644 (file)
index 0000000..c499348
--- /dev/null
+++ b/examples/GNUmakefile
@@ -0,0 +1,35 @@
+#
+# Example makefile using mjotex and a BibTeX references database.
+#
+# After defining $(PN) to be the name of your document, this will
+# compile the source file $(PN).tex to $(PN).pdf. The remaining
+# optional variables are all used by this project:
+#
+#  * BIBS - BibTeX bibliography
+#  * INDICES - the index, typically singular and named $(PN)
+#  * SAGE_LISTING_SRCS - testable sage code listings
+#  * MJOTEX - macro source files from mjotex
+#
+
+# The repository has to be added to the TeX path, if this is not done
+# in ~/.bashrc or some equivalent place.
+export TEXINPUTS := $(TEXINPUTS):../
+export BSTINPUTS := $(BSTINPUTS):../
+
+# The name of the document. Defaults to name of the parent directory
+# which in this case is also "examples", but is usually required.
+PN = examples
+
+# Specify the remaining variables only if you use them.
+BIBS = local-references.bib
+INDICES = $(PN)
+SAGE_LISTING_SRCS = $(wildcard sage_listings/*.listing)
+
+# Only the ones we use... AKA all of them.
+MJOTEX  = mjo-algebra.tex mjo-algorithm.tex mjo-arrow.tex mjo-calculus.tex
+MJOTEX += mjo-common.tex mjo-complex.tex mjo-cone.tex mjo-convex.tex
+MJOTEX += mjo-eja.tex mjo-font.tex mjo-hurwitz.tex mjo-linear_algebra.tex
+MJOTEX += mjo-listing.tex mjo-proof_by_cases.tex mjo-set.tex mjo-theorem.tex
+MJOTEX += mjo-theorem-star.tex mjo-topology.tex mjo.bst
+
+include $(shell kpsewhich GNUmakefile.mjo)

diff --git a/examples.tex b/examples/examples.tex
similarity index 100%
rename from examples.tex
rename to examples/examples.tex

diff --git a/local-references.bib b/examples/local-references.bib
similarity index 100%
rename from local-references.bib
rename to examples/local-references.bib

diff --git a/sage_listings/example.listing b/examples/sage_listings/example.listing
similarity index 100%
rename from sage_listings/example.listing
rename to examples/sage_listings/example.listing