Highlighting changes can now be toggled at run-time

Until now, the core Maneage 'paper.tex' had a '\highlightchanges' macro
that defines two LaTeX macros: '\new' and '\tonote'.

When '\highlightchanges' was defined, anything that was written within
'\new' became dark green (highlighting new things that have been
added). Also, anything that was written in '\tonote' was put within a '[]'
and became dark red (to show that there is a note here that should be
addressed later).

When '\highlightchanges' wasn't defined, anything within the '\new' element
would be black (like the rest of the text), and the things in '\tonote'
would not be shown at all.

Commenting the '\newcommand{\highlightchanges}{}' line within 'paper.tex'
(to toggle the modes above) would create a different Git hash and has to be
committed.

But this different commit hash could create a false sense in the reader
that other things have also been changed and the only way they could
confirm was to actually go and look into the project history (which they
will not usually have time to do, and thus won't be able to trust the two
modes of the text).

Also, the added highlights and the note highlights were bundeled together
into one macro, so you couldn't only have one of them.

With this commit, the choice of highlighting either one of the two is now
done as two new run-time options to the './project' script (which are
passed to the Makefiles, and written into the 'project.tex' file which is
loaded into 'paper.tex'). In this way, we can generate two PDFs with the
same Git commit (project's state): one with the selected highlights and
another one without it.

This issue actually came up for me while implementing the changes here: we
need to submit one PDF to the journal/referees with highlights on the added
features. But we also need to submit another PDF to arXiv and Zenodo
without any highlights. If the PDFs have different commit hashes, the
referees may associate it with other changes in any part of the work. For
example https://oadoi.org/10.22541/au.159724632.29528907 that mentions
"Another version of the manuscript was published on arXiv: 2006.03018",
while the only difference was a few words in the abstract after the journal
complained on the abstract word-count of our first submission (where the
commit hashes matched with arXiv/Zenodo).

1 files changed, 14 insertions, 3 deletions

diff --git a/project b/project
index 88aa8fd..311c051 100755
--- a/project
+++ b/project
@@ -42,8 +42,10 @@ make_targets=
 software_dir=
 clean_texdir=0
 prepare_redo=0
+highlightnew=0
 all_highlevel=0
 existing_conf=0
+highlightnotes=0
 scriptname="./project"
 minmapsize=10000000000
 
@@ -119,11 +121,15 @@ Configure and Make options:
   -j, --jobs=INT           Number of threads to build/run the software.
   -?, --help               Print this help list.
 
-Make options:
-      --no-appendix        Don't include the appendix in the final paper.
+Make (analysis) options:
   -d, --debug=FLAGS        Print various types of debugging information.
   -p, --prepare-redo       Re-do preparation (only done automatically once).
 
+Make (final PDF) options:
+      --highlight-new      Highlight '\new' parts of text as green.
+      --highlight-notes    Show '\tonote' regions as red text in PDF.
+      --no-appendix        Don't include the appendix in the final paper.
+
 Mandatory or optional arguments to long options are also mandatory or optional
 for any corresponding short options.
 
@@ -209,6 +215,10 @@ do
   # value, it is like giving it a value of `a'):
   --no-appendix)          noappendix=1;                                                    shift;;
   --no-appendix=*)        on_off_option_error --no-appendix;;
+  --highlight-new)        highlightnew=1;                                                  shift;;
+  --highlight-new=*)      on_off_option_error --highlight-new;;
+  --highlight-notes)      highlightnotes=1;                                                shift;;
+  --highlight-notes=*)    on_off_option_error --highlight-notes;;
   -d|--debug)             if [ x"$2" = x ]; then debug=a;          shift;
                           else debug="$2"; check_v debug "$debug"; shift;shift; fi;;
   -d=*|--debug=*)         debug="${1#*=}";                       check_v debug "$debug";   shift;;
@@ -374,7 +384,8 @@ controlled_env() {
     # Remove all existing environment variables (with `env -i') and only
     # use some pre-defined environment variables, then build the project.
     envmake=".local/bin/env -i HOME=$bdir sys_rm=$(which rm) $gopt"
-    envmake="$envmake noappendix=$noappendix .local/bin/make"
+    envmake="$envmake noappendix=$noappendix highlightnew=$highlightnew"
+    envmake="$envmake highlightnotes=$highlightnotes .local/bin/make "
     envmake="$envmake --no-builtin-rules --no-builtin-variables -f $1"
     if ! [ x"$debug" = x  ]; then envmake="$envmake --debug=$debug"; fi