Rule of tex/pipeline.tex now defined in paper.mk not top Makefile

To avoid redundant steps in the the top-level Makefile and make it simpler
and easier to follow, we now define the base names of all the Makefiles in
the `makesrc' variable of the top-level Makefile. `makesrc' is then used to
define the Makefiles to include and the necessary TeX macros at the same
time. This is much more clear and obvious than the previous case were we
had to list the Makefiles and TeX macro files separately in the top level
Makefile.

3 files changed, 143 insertions, 122 deletions

diff --git a/reproduce/src/make/Top-Makefile b/reproduce/src/make/Top-Makefile
deleted file mode 100644
index 4c547be..0000000
--- a/reproduce/src/make/Top-Makefile
+++ /dev/null
@@ -1,122 +0,0 @@
-# A ONE-LINE DESCRIPTION OF THE WHOLE PIPELINE
-#
-# Original author:
-#     Mohammad Akhlaghi <mohammad@akhlaghi.org>
-# Contributing author(s):
-#     Your name <your@email.address>
-# Copyright (C) 2018, Your Name.
-#
-# This Makefile is free software: you can redistribute it and/or modify it
-# under the terms of the GNU General Public License as published by the
-# Free Software Foundation, either version 3 of the License, or (at your
-# option) any later version.
-#
-# This Makefile is distributed in the hope that it will be useful, but
-# WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
-# Public License for more details.
-#
-# A copy of the GNU General Public License is available at
-# <http://www.gnu.org/licenses/>.
-
-
-
-
-
-# Ultimate target of this pipeline
-# --------------------------------
-#
-# The final paper (in PDF format) is the main target of this whole
-# reproduction pipeline. So as defined in the Make paradigm, we are
-# defining it here.
-#
-# Note that if you don't have LaTeX to build the PDF, or generally are just
-# interested in the processing, you can skip create the final PDF creation
-# with `pdf-build-final' of `reproduce/config/pipeline/pdf-build.mk'.
-all: paper.pdf
-
-
-
-
-
-# Include specific Makefiles
-# --------------------------
-#
-# To keep things clean, managable and readable, each set of operations is
-# (and must be) classified (modularized) by context into separate
-# Makefiles: the more the better. They are included in this top-level
-# Makefile through the command below.
-#
-# To further help in readability, it is best to avoid including Makefiles
-# within any other Makefile. So in short, it is best that the `foreach'
-# loop below contains all the `reproduce/src/make/*.mk' files.
-#
-# IMPORTANT NOTE: order matters in the inclusion of the processing
-# Makefiles. As the pipeline grows, some Makefiles will probably define
-# variables/dependencies that others need. Therefore unlike the
-# `reproduce/config/pipeline/*.mk' Makefiles which only define low-level
-# variables (not dependent on other variables and contain no rules), the
-# high-level processing Makefiles are included through the `foreach' loop
-# below by explicitly requesting them in a specific order here.
-include reproduce/config/pipeline/*.mk
-include $(foreach f, initialize                    \
-                     download                      \
-                     delete-me                     \
-                     paper                         \
-                   , reproduce/src/make/$(f).mk)
-
-
-
-
-
-# LaTeX macros for paper
-# ----------------------
-#
-# The final report's PDF (final target of this reproduction pipeline) takes
-# variable strings from the pipeline. Those variables are defined as LaTeX
-# macros in `tex/pipeline.tex'. This file is thus the interface between the
-# pipeline scripts and the final PDF.
-#
-# Each of the pipeline steps will save their macros into their own `.tex'
-# file in the `$(mtexdir)' directory. Those individual macros are the
-# pre-requisite to `tex/pipeline.txt'. `tex/pipeline.tex' is thus a
-# high-level output and is defined in this top-most Makefile (and not
-# `reproduce/src/make/paper.mk'). This enables a clear demonstration of the
-# top-level dependencies clearly.
-#
-# Note that if you don't want the final PDF and just want the processing
-# and file outputs, you can remove the value of the `pdf-build-final'
-# variable in `reproduce/config/pdf-build.mk'.
-tex/pipeline.tex: $(foreach f, initialize          \
-                               download            \
-                               delete-me           \
-                             , $(mtexdir)/$(f).tex)
-
-        # If no PDF is requested, or if LaTeX isn't available, don't
-        # continue to building the final PDF. Otherwise, merge all the TeX
-        # macros into one for building the PDF.
-	@if [ -f .local/bin/pdflatex ] && [ x"$(pdf-build-final)" != x ]; then
-	  cat $(mtexdir)/*.tex > $@
-	else
-	  echo
-	  echo "-----"
-	  echo "The processing has COMPLETED SUCCESSFULLY! But the final "
-	  echo "LaTeX-built PDF paper will not be built."
-	  echo
-	  if [ x$(more-on-building-pdf) = x1 ]; then
-	    echo "To do so, make sure you have LaTeX within the pipeline (you"
-	    echo "can check by running './.local/bin/latex --version'), _AND_"
-	    echo "make sure that the 'pdf-build-final' variable has a value."
-	    echo "'pdf-build-final' is defined in: "
-	    echo     "'reproduce/config/pipeline/pdf-build.mk'."
-	    echo
-	    echo "If you don't have LaTeX within the pipeline, please re-run"
-	    echo "'./configure' when you have internet access. To speed it up,"
-	    echo "you can keep the previous configuration files (answer 'n'"
-	    echo "when it asks about re-writing previous configuration files)."
-	  else
-	    echo "For more, run './.local/bin/make more-on-building-pdf=1'"
-	  fi
-	  echo
-	  echo "" > $@
-	fi
diff --git a/reproduce/src/make/paper.mk b/reproduce/src/make/paper.mk
index d50c59a..8e024ee 100644
--- a/reproduce/src/make/paper.mk
+++ b/reproduce/src/make/paper.mk
@@ -22,6 +22,62 @@
 
 
 
+# LaTeX macros for paper
+# ----------------------
+#
+# To report the input settings and results, the final report's PDF
+# (final target of this reproduction pipeline) uses macros generated
+# from various steps of the pipeline. All these macros are defined in
+# `tex/pipeline.tex'.
+#
+# `tex/pipeline.tex' is actually just a combination of separate files
+# that keep the LaTeX macros related to each workhorse Makefile (in
+# `reproduce/src/make/*.mk'). Those individual macros are
+# pre-requisites to `tex/pipeline.tex'. The only workhorse Makefile
+# that doesn't need to produce LaTeX macros is this Makefile
+# (`reproduce/src/make/paper.mk').
+#
+# This file is thus the interface between the pipeline scripts and the
+# final PDF: when we get to this point, all the processing has been
+# completed.
+#
+# Note that if you don't want the final PDF and just want the
+# processing and file outputs, you can remove the value of
+# `pdf-build-final' in `reproduce/config/pipeline/pdf-build.mk'.
+tex/pipeline.tex: $(foreach s, $(subst paper,,$(makesrc)), $(mtexdir)/$(s).tex)
+
+        # If no PDF is requested, or if LaTeX isn't available, don't
+        # continue to building the final PDF. Otherwise, merge all the TeX
+        # macros into one for building the PDF.
+	@if [ -f .local/bin/pdflatex ] && [ x"$(pdf-build-final)" != x ]; then
+	  cat $(mtexdir)/*.tex > $@
+	else
+	  echo
+	  echo "-----"
+	  echo "The processing has COMPLETED SUCCESSFULLY! But the final "
+	  echo "LaTeX-built PDF paper will not be built."
+	  echo
+	  if [ x$(more-on-building-pdf) = x1 ]; then
+	    echo "To do so, make sure you have LaTeX within the pipeline (you"
+	    echo "can check by running './.local/bin/latex --version'), _AND_"
+	    echo "make sure that the 'pdf-build-final' variable has a value."
+	    echo "'pdf-build-final' is defined in: "
+	    echo     "'reproduce/config/pipeline/pdf-build.mk'."
+	    echo
+	    echo "If you don't have LaTeX within the pipeline, please re-run"
+	    echo "'./configure' when you have internet access. To speed it up,"
+	    echo "you can keep the previous configuration files (answer 'n'"
+	    echo "when it asks about re-writing previous configuration files)."
+	  else
+	    echo "For more, run './.local/bin/make more-on-building-pdf=1'"
+	  fi
+	  echo
+	  echo "" > $@
+	fi
+
+
+
+
 
 # The bibliography
 # ----------------
diff --git a/reproduce/src/make/top.mk b/reproduce/src/make/top.mk
new file mode 100644
index 0000000..c002bf7
--- /dev/null
+++ b/reproduce/src/make/top.mk
@@ -0,0 +1,87 @@
+# A ONE-LINE DESCRIPTION OF THE WHOLE PIPELINE
+#
+# Original author:
+#     Mohammad Akhlaghi <mohammad@akhlaghi.org>
+# Contributing author(s):
+#     Your name <your@email.address>
+# Copyright (C) 2018, Your Name.
+#
+# This Makefile is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation, either version 3 of the License, or (at your
+# option) any later version.
+#
+# This Makefile is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+#
+# A copy of the GNU General Public License is available at
+# <http://www.gnu.org/licenses/>.
+
+
+
+
+
+# Ultimate target of this pipeline
+# --------------------------------
+#
+# The final paper (in PDF format) is the main target of this whole
+# reproduction pipeline. So as defined in the Make paradigm, we are
+# defining it here.
+#
+# Note that if you don't have LaTeX to build the PDF, or generally are just
+# interested in the processing, you can skip create the final PDF creation
+# with `pdf-build-final' of `reproduce/config/pipeline/pdf-build.mk'.
+all: paper.pdf
+
+
+
+
+
+# Define source Makefiles
+# -----------------------
+#
+# To keep things clean, managable and readable, each set of operations
+# is (and must be) classified (modularized) by context into separate
+# Makefiles: the more the better. These modular steps are then
+# included in this top-level Makefile through the `include' command of
+# the next step. Each Makefile should also produce a LaTeX macro file
+# with the same fixed name (used to keep all the parameters and
+# relevant outputs of the steps in it for the final paper).
+#
+# In the rare case that no special LaTeX macros are necessary in a
+# workhorse Makefile, you can simply make an empty file with `touch
+# $@'. This will not add any lines to the final combined LaTeX macros
+# file, but will create the file that is a prerequisite to the final
+# paper generation.
+#
+# To (significantly) help in readability, this top-level Makefile should be
+# the only one in charge of including Makefiles. So if you care about easy
+# maintainence and understandability (even for your self, in one year! It
+# is VERY IMPORTANT and as a scientist, you MUST care about it!), do not
+# include Makefiles from any other Makefile.
+#
+# IMPORTANT NOTE: order matters in the inclusion of the processing
+# Makefiles. As the pipeline grows, some Makefiles will define
+# variables/dependencies that later Makefiles need. Therefore we are using
+# a `foreach' loop in the next step to explicitly request loading them in
+# the same order that they are defined here (we aren't just using a
+# wild-card like the configuration Makefiles).
+makesrc = initialize                    \
+          download                      \
+          delete-me                     \
+          paper
+
+
+
+
+
+# Include necessary Makefiles
+# ---------------------------
+#
+# First, we'll include all the configuration-Makefiles (only defining
+# variables with no rules or order), then the workhorse Makefiles which
+# contain rules and order matters for them.
+include reproduce/config/pipeline/*.mk
+include $(foreach s,$(makesrc), reproduce/src/make/$(s).mk)