IMPORTANT: Added publication checklist, improved relevant infrastructure

Possible semantic conflicts (that may not show up as Git conflicts but may
cause a crash in your project after the merge):

   1) The project title (and other basic metadata) should be set in
      'reproduce/analysis/conf/metadata.conf'. Please include this file in
      your merge (if it is ignored because of '.gitattributes'!).

   2) Consider importing the changes in 'initialize.mk' and 'verify.mk' (if
      you have added all analysis Makefiles to the '.gitattributes' file
      (thus not merging any change in them with your branch). For example
      with this command:
        git diff master...maneage -- reproduce/analysis/make/initialize.mk

   3) The old 'verify-txt-no-comments-leading-space' function has been
      replaced by 'verify-txt-no-comments-no-space'. The new function will
      also remove all white-space characters between the columns (not just
      white space characters at the start of the line). Thus the resulting
      check won't involve spacing between columns.

A common set of steps are always necessary to prepare a project for
publication. Until now, we would simply look at previous submissions and
try to follow them, but that was prone to errors and could cause
confusion. The internal infrastructure also didn't have some useful
features to make good publication possible. Now that the submission of a
paper fully devoted to the founding criteria of Maneage is complete
(arXiv:2006.03018), it was time to formalize the necessary steps for easier
submission of a project using Maneage and implement some low-level features
that can make things easier.

With this commit a first draft of the publication checklist has been added
to 'README-hacking.md', it was tested in the submission of arXiv:2006.03018
and zenodo.3872248. To help guide users on implementing the good practices
for output datasets, the outputs of the default project shown in the paper
now use the new features). After reading the checklist, please inspect
these.

Some other relevant changes in this commit:

  - The publication involves a copy of the necessary software
    tarballs. Hence a new target ('dist-software') was also added to
    package all the project's software tarballs in one tarball for easy
    distribution.

  - A new 'dist-lzip' target has been defined for those who want to
    distribute an Lzip-compressed tarball.

  - The '\includetikz' LaTeX macro now has a second argument to allow
    configuring the '\includegraphics' call when the plot should not be
    built, but just imported.

1 files changed, 36 insertions, 13 deletions

diff --git a/reproduce/analysis/make/verify.mk b/reproduce/analysis/make/verify.mk
index 43d1472..67b3fea 100644
--- a/reproduce/analysis/make/verify.mk
+++ b/reproduce/analysis/make/verify.mk
@@ -40,22 +40,34 @@ verify-print-tips = \
   echo "the following project source file:"; \
   echo "    reproduce/analysis/make/verify.mk"
 
-verify-txt-no-comments-leading-space = \
+# Removes following components of a plain-text file, calculates checksum
+# and compares with given checksum:
+#   - All commented lines (starting with '#') are removed.
+#   - All empty lines are removed.
+#   - All space-characters in remaining lines are removed (so the width of
+#     the printed columns won't invalidate the verification).
+#
+# It takes three arguments:
+#   - First argument: Full address of file to check.
+#   - Second argument: Expected checksum of the file to check.
+#   - File name to write result.
+verify-txt-no-comments-no-space = \
   infile=$(strip $(1)); \
   inchecksum=$(strip $(2)); \
+  innobdir=$$(echo $$infile | sed -e's|$(BDIR)/||g'); \
   if ! [ -f "$$infile" ]; then \
     $(call verify-print-error-start); \
     echo "The following file (that should be verified) doesn't exist:"; \
     echo "    $$infile"; \
     echo; exit 1; \
   fi; \
-  checksum=$$(sed -e 's/^[[:space:]]*//g' \
+  checksum=$$(sed -e 's/[[:space:]][[:space:]]*//g' \
                   -e 's/\#.*$$//' \
                   -e '/^$$/d' $$infile \
-	          | md5sum \
-	          | awk '{print $$1}'); \
+                  | md5sum \
+                  | awk '{print $$1}'); \
   if [ x"$$inchecksum" = x"$$checksum" ]; then \
-    echo "Verified: $$infile"; \
+    echo "%% (VERIFIED) $$checksum $$innobdir" >> $(3); \
   else \
     $(call verify-print-error-start); \
     $(call verify-print-tips); \
@@ -105,11 +117,20 @@ $(mtexdir)/verify.tex: $(foreach s, $(verify-dep), $(mtexdir)/$(s).tex)
         # Make sure that verification is actually requested.
 	if [ x"$(verify-outputs)" = xyes ]; then
 
+          # Make sure the temporary output doesn't exist (because we want
+          # to append to it). We are making a temporary output target so if
+          # there is a crash in the middle, Make will not continue. If we
+          # write in the final target progressively, the file will exist,
+          # and its date will be more recent than all prerequisites, so
+          # next time the project is run, Make will continue and ignore the
+          # rest of the checks.
+	  rm -f $@.tmp
+
           # Verify the figure datasets.
-	  $(call verify-txt-no-comments-leading-space, \
-	         $(delete-num), ad345e873e6af577f0e4e7c8942cdf08)
-	  $(call verify-txt-no-comments-leading-space, \
-	         $(delete-histogram), 12a81c4c8c5f552e5ed5686453587fe8)
+	  $(call verify-txt-no-comments-no-space, \
+	         $(dm-squared), 6b6d3b0f9c351de53606507b59bca5d1, $@.tmp)
+	  $(call verify-txt-no-comments-no-space, \
+	         $(dm-img-histogram), b1f9c413f915a1ad96078fee8767b16c, $@.tmp)
 
           # Verify TeX macros (the values that go into the PDF text).
 	  for m in $(verify-check); do
@@ -118,9 +139,11 @@ $(mtexdir)/verify.tex: $(foreach s, $(verify-dep), $(mtexdir)/$(s).tex)
 	    elif [ $$m == delete-me ]; then s=711e2f7fa1f16ecbeeb3df6bcb4ec705
 	    else echo; echo "'$$m' not recognized."; exit 1
 	    fi
-	    $(call verify-txt-no-comments-leading-space, $$file, $$s)
+	    $(call verify-txt-no-comments-no-space, $$file, $$s, $@.tmp)
 	  done
-	fi
 
-        # Make an empty final target.
-	touch $@
+          # Move temporary file to final target.
+	  mv $@.tmp $@
+	else
+	  echo "% Verification was DISABLED!" > $@
+	fi