Supplement (containing appendices) optionally built separately

Until now, the build strategy of the paper was to have a single output PDF
that either contains (1) the full paper with appendices in the same paper
(2) only the main body of the paper with no appencies.

But the editor in chief of CiSE recently recommended publishing the
appendices as supplements that is a separate PDF (on its webpage). So with
this commit, the project can make either (1) a single PDF (containing both
the main body and the appendices) that will be published on arXiv and will
be the default output (this is the same as before). (2) two PDFs: one that
is only the main body of the paper and another that is only the appendices.

Since the appendices will be printed as a PDF in any case now, the old
'--no-appendix' option has been replaced by '--supplement'. Also, the
internal shell/TeX variable 'noappendix' has been renamed to
'separatesupplement'.

3 files changed, 55 insertions, 47 deletions

diff --git a/reproduce/analysis/make/initialize.mk b/reproduce/analysis/make/initialize.mk
index 75f87ee..0cc04ee 100644
--- a/reproduce/analysis/make/initialize.mk
+++ b/reproduce/analysis/make/initialize.mk
@@ -77,21 +77,11 @@ endif
 # (independent parts of the paper can be added to it independently). To fix
 # this problem, when we are in a group setting, we'll use the user's ID to
 # create a separate LaTeX build directory for each user.
-#
-# The same logic applies to the final paper PDF: each user will create a
-# separte final PDF (for example `paper-user1.pdf' and `paper-user2.pdf')
-# and no `paper.pdf' will be built. This isn't a problem because
-# `initialize.tex' is a .PHONY prerequisite, so the rule to build the final
-# paper is always executed (even if it is present and nothing has
-# changed). So in terms of over-all efficiency and processing steps, this
-# doesn't change anything.
 ifeq (x$(GROUP-NAME),x)
 texbtopdir  = build
-final-paper = paper.pdf
 else
 user        = $(shell whoami)
 texbtopdir  = build-$(user)
-final-paper = paper-$(user).pdf
 endif
 texbdir     = $(texdir)/$(texbtopdir)
 tikzdir     = $(texbdir)/tikz
@@ -220,14 +210,15 @@ project-package-contents = $(texdir)/$(project-package-name)
 # we want to ensure that the file is always built in every run: it contains
 # the project version which may change between two separate runs, even when
 # no file actually differs.
-.PHONY: all clean dist dist-zip dist-lzip distclean clean-mmap \
+.PHONY: all clean dist dist-zip dist-lzip texclean distclean \
         $(project-package-contents) $(mtexdir)/initialize.tex
 
-# --------- Delete for no Gnuastro ---------
-clean-mmap:; rm -f reproduce/config/gnuastro/mmap*
-# ------------------------------------------
+texclean:
+	rm *.pdf
+	rm -rf $(BDIR)/tex/build/*
+	mkdir $(BDIR)/tex/build/tikz # 'tikz' is assumed to already exist.
 
-clean: clean-mmap
+clean:
         # Delete the top-level PDF file.
 	rm -f *.pdf
 
diff --git a/reproduce/analysis/make/paper.mk b/reproduce/analysis/make/paper.mk
index d8f18b3..1776363 100644
--- a/reproduce/analysis/make/paper.mk
+++ b/reproduce/analysis/make/paper.mk
@@ -18,6 +18,7 @@
 
 
 
+
 # LaTeX macros for paper
 # ----------------------
 #
@@ -55,8 +56,8 @@ $(mtexdir)/project.tex: $(mtexdir)/verify.tex
 	  done
 
           # Possibly print the appendix in the final PDF.
-	  if [ x"$(noappendix)" = x1 ]; then
-	    echo "\newcommand{\noappendix}{}" >> $$projecttex
+	  if [ x"$(separatesupplement)" = x1 ]; then
+	    echo "\newcommand{\separatesupplement}{}" >> $$projecttex
 	  fi
 
           # Possibly highlight the '\new' parts of the text.
@@ -99,17 +100,18 @@ $(mtexdir)/project.tex: $(mtexdir)/verify.tex
 # The bibliography
 # ----------------
 #
-# We need to run the `biber' program on the output of LaTeX to generate the
-# necessary bibliography before making the final paper. So we'll first have
-# one run of LaTeX (similar to the `paper.pdf' recipe), then `biber'.
+# We need to run the `bibtex' program on the output of LaTeX to generate
+# the necessary bibliography before making the final paper. So we'll first
+# have one run of LaTeX (similar to the `paper.pdf' recipe), then `biber'.
 #
 # NOTE: `$(mtexdir)/project.tex' is an order-only-prerequisite for
 # `paper.bbl'. This is because we need to run LaTeX in both the `paper.bbl'
 # recipe and the `paper.pdf' recipe. But if `tex/src/references.bib' hasn't
 # been modified, we don't want to re-build the bibliography, only the final
 # PDF.
-$(texbdir)/paper.bbl: tex/src/references.tex $(mtexdir)/dependencies-bib.tex \
-                      | $(mtexdir)/project.tex
+bbls = $(foreach t,$(subst .pdf,,$(top-pdfs)),$(texbdir)/$(t).bbl)
+$(bbls): $(texbdir)/%.bbl: tex/src/references.tex \
+         $(mtexdir)/dependencies-bib.tex | $(mtexdir)/project.tex
 
         # If `$(mtexdir)/project.tex' is empty, don't build PDF.
 	@macros=$$(cat $(mtexdir)/project.tex)
@@ -120,14 +122,14 @@ $(texbdir)/paper.bbl: tex/src/references.tex $(mtexdir)/dependencies-bib.tex \
           # building directory.
 	  p=$$(pwd)
 	  if ! [ -L $(texbdir)/references.bib ]; then
-	    ln -s $$p/tex/src/references.tex $(texbdir)/references.bib
+	    ln -sf $$p/tex/src/references.tex $(texbdir)/references.bib
 	  fi
 
           # Copy the improved IEEE bst file into the build directory.
           # The improved bst file provides ArXiv clickable URLs and
           # if available, open-access URLs based on the DOIs, with
           # closed-access URLs as a fallback, via https://oadoi.org .
-	  cp -pv $$p/tex/src/IEEEtran_openaccess.bst $(texbdir)
+	  ln -sf $$p/tex/src/IEEEtran_openaccess.bst $(texbdir)/
 
           # We'll run LaTeX first to generate the `.bcf' file (necessary
           # for `biber') and then run `biber' to generate the `.bbl' file.
@@ -140,19 +142,27 @@ $(texbdir)/paper.bbl: tex/src/references.tex $(mtexdir)/dependencies-bib.tex \
           # it. It will be built anyway once this rule is done.
 	  rm -f $@
 
+          # Put a link to the main LaTeX source that we want to build.
+	  if [ $* = paper ]; then sdir="$$p"
+	  else                    sdir="$$p"/tex/src
+	  fi
+	  ln -sf "$$sdir"/$*.tex ./
+
           # The pdflatex option '-shell-escape' is "normally disallowed for
           # security reasons" according to the `info pdflatex' manual, but
           # is enabled here in order to allow the use of PGFPlots. If you
-          # do not use PGFPlots, then you should remove the `-shell-escape'
+          # do not use PGFPlots, then you can remove the `-shell-escape'
           # option for better security. See
           # https://savannah.nongnu.org/task/?15694 for details.
-	  latex -shell-escape -halt-on-error "$$p"/paper.tex
-
-          # Since we have multiple bibliographies (one for the main body,
-          # and one for the appendix), we use 'multibib'. Multibib creates
-          # a separate '.aux' file for each bibliography.
-	  bibtex paper
-	  if [ x"$(noappendix)" != x1 ]; then
+	  latex -shell-escape -halt-on-error $*.tex
+
+          # When we are building the main paper and the appendices are to
+          # be built within the main paper's PDF, we need two
+          # bibliographies: one for the main body, and one for the
+          # appendix. For this, we use 'multibib'. Multibib creates a
+          # separate '.aux' file for each bibliography.
+	  bibtex $*
+	  if [ x"$(separatesupplement)" != x1 ]; then
 	    bibtex appendix
 	  fi
 
@@ -160,14 +170,14 @@ $(texbdir)/paper.bbl: tex/src/references.tex $(mtexdir)/dependencies-bib.tex \
           # TODO (better): read Part 4 of
           # http://mirrors.ctan.org/info/bibtex/tamethebeast/ttb_en.pdf
           # and fix the .bst style properly.
-	  cp -pv paper.bbl paper-tmp.bbl \
-	    && sed -e "s/\'/EOLINE/g" paper-tmp.bbl \
+	  cp -pv $*.bbl $*-tmp.bbl \
+	    && sed -e "s/\'/EOLINE/g" $*-tmp.bbl \
 	    | tr -d '\n' \
 	    | sed -e 's/\([0-9]\)\( \|EOLINE\)}/\1}/g' \
 	    | sed -e 's/\([^,]\) *\( \|EOLINE\) *\\eprint/\1, \\eprint/g' \
 	    | sed -e 's/\([^,]\) *\( \|EOLINE\) *\\doi/\1, \\doi/g' \
-	    | sed -e 's/EOLINE/\n/g' > paper.bbl
-	  if [ x"$(noappendix)" != x1 ]; then
+	    | sed -e 's/EOLINE/\n/g' > $*.bbl
+	  if [ x"$(separatesupplement)" != x1 ]; then
 	    cp -pv appendix.bbl appendix-tmp.bbl \
 	      && sed -e "s/\'/EOLINE/g" appendix-tmp.bbl \
 	      | tr -d '\n' \
@@ -178,18 +188,19 @@ $(texbdir)/paper.bbl: tex/src/references.tex $(mtexdir)/dependencies-bib.tex \
 	  fi
 
 	  # Paper-specific hacks for reducing very-long author lists.
-	  cp -pv paper.bbl paper-tmp.bbl \
-	    && sed -e "s/\'/EOLINE/g" paper-tmp.bbl \
+	  cp -pv $*.bbl $*-tmp.bbl \
+	    && sed -e "s/\'/EOLINE/g" $*-tmp.bbl \
 	    | tr -d '\n' \
 	    | sed -e 's;, D\..Chong[^{]*Forstag; et al.\\/;' \
 	    | sed -e 's;, V\..Khodiyar[^{]*Whyte; et al.\\/;' \
-	    | sed -e 's/EOLINE/\n/g' > paper.bbl
+	    | sed -e 's/EOLINE/\n/g' > $*.bbl
+
           # The pre-final run of LaTeX after 'paper.bbl' was created.
-	  latex -shell-escape -halt-on-error "$$p"/paper.tex
+	  latex -shell-escape -halt-on-error $*.tex
 	fi
 
 
-#	    | sed -e 's;Chong;HELLO MUM;' \
+
 
 
 # The final paper
@@ -200,7 +211,8 @@ $(texbdir)/paper.bbl: tex/src/references.tex $(mtexdir)/dependencies-bib.tex \
 # to run everything cleanly from there, it is necessary to add the current
 # directory (top project directory) to the `TEXINPUTS' environment
 # variable.
-paper.pdf: $(mtexdir)/project.tex paper.tex $(texbdir)/paper.bbl
+$(top-pdfs): %.pdf: $(mtexdir)/project.tex paper.tex \
+         tex/src/appendix-*.tex $(texbdir)/%.bbl
 
         # If `$(mtexdir)/project.tex' is empty, don't build the PDF.
 	@macros=$$(cat $(mtexdir)/project.tex)
@@ -213,17 +225,17 @@ paper.pdf: $(mtexdir)/project.tex paper.tex $(texbdir)/paper.bbl
 
           # See above for a warning and brief discussion on the the
           # pdflatex option `-shell-escape'.
-	  latex -shell-escape -halt-on-error "$$p"/paper.tex
+	  latex -shell-escape -halt-on-error $*.tex
 
           # Convert the DVI to PostScript, and the PostScript to PDF. The
           # `-dNOSAFER' option to GhostScript allows transparencies in the
           # conversion from PostScript to PDF, see
           # https://www.ghostscript.com/doc/current/Language.htm#Transparency
-	  dvips paper.dvi
-	  ps2pdf paper.ps
+	  dvips $*.dvi
+	  ps2pdf $*.ps
 
           # Come back to the top project directory and copy the built PDF
           # file here.
 	  cd "$$p"
-	  cp $(texbdir)/$@ $(final-paper)
+	  cp $(texbdir)/$*.pdf $@
 	fi
diff --git a/reproduce/analysis/make/top-make.mk b/reproduce/analysis/make/top-make.mk
index 18d54b1..d552dc1 100644
--- a/reproduce/analysis/make/top-make.mk
+++ b/reproduce/analysis/make/top-make.mk
@@ -64,8 +64,13 @@ include reproduce/software/config/LOCAL.conf
 # If you are just interested in the processing and don't want to build the
 # PDF, you can skip the creation of the final PDF by giving a value of
 # `yes' to `pdf-build-final' in `reproduce/analysis/config/pdf-build.conf'.
+ifeq ($(separatesupplement),0)
+top-pdfs = paper.pdf
+else
+top-pdfs = paper.pdf supplement.pdf
+endif
 ifeq (x$(reproducible_paper_group_name),x$(GROUP-NAME))
-all: paper.pdf
+all: $(top-pdfs)
 else
 all:
 	@if [ "x$(GROUP-NAME)" = x ]; then \