From 10b133db1a2115cad8dba2cc7e5641facc080454 Mon Sep 17 00:00:00 2001
From: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Date: Sat, 4 Jul 2020 02:12:09 +0100
Subject: Improved comments in paper.mk and README.md

In 'README.md' I tried to explain a little better that TeXLive will only
install its necessary packages, not the full TeXLive library! Also in
paper.mk, I slightly improved the comments with very minor edits.

Both these parts are slated to go into the core Maneage branch, so its
important to maintain them here for now.
---
 README.md                        | 16 +++++++++-------
 reproduce/analysis/make/paper.mk |  6 +++++-
 2 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index f16057c..a12770c 100644
--- a/README.md
+++ b/README.md
@@ -229,13 +229,15 @@ can disable internet. In this situation, the configuration and analysis
 will be exactly reproduced, the final LaTeX macros will be created, and all
 results will be verified successfully. However, no final `paper.pdf` will
 be created to visualize/combine everything in one easy-to-read file. Until
-[task 15267](https://savannah.nongnu.org/task/?15267) is complete, if there
-is no internet, TeXLive packages can't be installed in the `./project
-configure` phase. This won't stop the configuration, and it will finish
-successfully (since all the analysis can still be reproduced). We are
-working on completing this task as soon as possible, but until then, if you
-want to disable internet *and* you want to build the final PDF, please
-disable internet after the configuration phase.
+[task 15267](https://savannah.nongnu.org/task/?15267) is complete, we need
+internet to install TeXLive packages (using TeXLive's own package manager
+`tlmgr`) in the `./project configure` phase. This won't stop the
+configuration, and it will finish successfully (since all the analysis can
+still be reproduced). We are working on completing this task as soon as
+possible, but until then, if you want to disable internet *and* you want to
+build the final PDF, please disable internet after the configuration
+phase. Note that only the necessary TeXLive packages are installed (~350
+MB), not the full TeXLive collection!
 
  1. **Choose the base operating system:** The first step is to select the
     operating system that will be used in the docker image. Note that your
diff --git a/reproduce/analysis/make/paper.mk b/reproduce/analysis/make/paper.mk
index 6d69d49..b00ed5a 100644
--- a/reproduce/analysis/make/paper.mk
+++ b/reproduce/analysis/make/paper.mk
@@ -91,12 +91,14 @@ $(mtexdir)/project.tex: $(mtexdir)/verify.tex
 # PDF.
 $(texbdir)/paper.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)
 	if [ x"$$macros" != x ]; then
 
           # Unfortunately I can't get bibtex to look into a special
-          # directory for the references, so we'll copy it here.
+          # directory for the references, so we'll copy it into the LaTeX
+          # building directory.
 	  p=$$(pwd)
 	  if ! [ -L $(texbdir)/references.bib ]; then
 	    ln -s $$p/tex/src/references.tex $(texbdir)/references.bib
@@ -133,6 +135,8 @@ $(texbdir)/paper.bbl: tex/src/references.tex $(mtexdir)/dependencies-bib.tex \
 	    | sed -e 's/\([^,]\) *\( \|EOLINE\) *\\eprint/\1, \\eprint/g' \
 	    | sed -e 's/\([^,]\) *\( \|EOLINE\) *\\doi/\1, \\doi/g' \
 	    | sed -e 's/EOLINE/\n/g' > paper.bbl
+
+          # The pre-final run of LaTeX after 'paper.bb' was created.
 	  latex -shell-escape -halt-on-error $$p/paper.tex
 	fi
 
-- 
cgit v1.2.1