Text surrounding software acknowledgements as a configuration file

Until now, the English texts that embeds the list of software to
acknowledge in the paper was hard-wired into the low-level coding
('reproduce/software/shell/configure.sh' to be more specific). But this
file is very low-level, thus discouraging users to modify this surrounding
text.

While the list of software packages can be considered to be 'data' and is
fixed, the surrounding text to describe the lists is something the authors
should decide on. Authors of a scientific research paper take
responsibility for the full paper, including for the style of the
acknowledgments, even if these may well evolve into some standard text.

With this commit, authors who do *not* modify
'reproduce/software/config/acknowledge_software.sh' will have a default
text, with only a minor English correction from earlier versions of
Maneage. However, Authors choosing to use their own wording should be able
to modify the text parameters in
`reproduce/software/config/acknowledge_software.sh` in the obvious
way. This is much more modular than asking project authors to go looking
into the long and technical 'configure.sh' script.

Systematic issues: the file
`reproduce/software/config/acknowledge_software.sh` is an executable shell
script, because it has to be called by
`reproduce/software/shell/configure.sh`, which, in principle, does not yet
have access to `GNU make` (if I understand the bootstrap sequence
correctly). It is placed in `config/` rather than `shell/`, because the
user will expect to find configuration files in `config/`, not in `shell/`.

A possible alternative to avoid having a shell script as a configure file
would be to let `reproduce/software/config/acknowledge_software.sh` appear
to be a `make` file, but analyse it in `configure.sh` using `sed` to remove
whitespace around `=`, and adding other hacks to switch from `make` syntax
to `shell` syntax. However, this risks misleading the user, who will not
know whether s/he should follow `make` conventions or `shell` conventions.

2 files changed, 124 insertions, 11 deletions

diff --git a/reproduce/software/config/software_acknowledge_context.sh b/reproduce/software/config/software_acknowledge_context.sh
new file mode 100755
index 0000000..b0ede85
--- /dev/null
+++ b/reproduce/software/config/software_acknowledge_context.sh
@@ -0,0 +1,112 @@
+#!/usr/bin/env sh
+
+# Surrounding text for software acknowledgement and citation. The list of
+# names, versions and citations of the software are written by an automatic
+# script. However, through this file, users have the option to specify the
+# text surrounding those lists.
+#
+# We recommend to leave these values untouched at first, after building
+# your PDF, you can see how they surround the list of software you used in
+# your project to make a smoothly readable English text. Afterwards, please
+# feel free to modify them as you wish.
+#
+# Copyright (C) 2020 Boud Roukema <boud@cosmo.torun.pl>
+# Copyright (C) 2020 Mohammad Akhlaghi <mohammad@akhlaghi.org>
+#
+# This script 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 script 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/>.
+
+# WARNING:
+# In contrast to most configure files in maneage, this configure file is
+# technically a shell script, to be called by 'configure.sh', so the
+# variables defined here must follow 'shell' syntax, not 'make' syntax.
+
+# These variables will be exported to the 'configure.sh' script - so
+# descriptive, unique names should be used, to reduce the chance of
+# conflicts between identically named variables.
+
+# COMMENT:
+# Sentences have a tendancy to become very long. To avoid making the
+# variable values too long (and thus making this file hard to read), one
+# method is to break the sentence into smaller components and build the
+# full sentence gradually, similar to what we have done with 'str' in the
+# examples below. Each time, the value of 'str' is re-written by appending
+# its previous value with the rest of the sentence.
+
+# COMMENT:
+# As of 2020-06-10, the general issue of how to best cite software within
+# maneage, especially a full list of software in the Acknowledgments
+# section, remains wide open. See
+# https://savannah.nongnu.org/task/index.php?15318 for some technical
+# aspects of software citation.
+
+
+
+
+
+# Add your definitions of the LaTeX text here.
+#
+# To override a default but generate no text, use a string of non-zero
+# length such as "{}" that will have only minor effects in LaTeX.
+
+# An introduction to the software acknowledgement.
+thank_software_introduce=
+
+# The text to be used before listing C/C++ programs and libraries.
+thank_progs_libs=
+
+# The text to be used before listing Python modules.
+thank_python=
+
+# The text to be used before listing LaTeX packages.
+thank_latex=
+
+# Concluding remarks.
+thank_software_conclude=
+
+
+
+
+
+# Defaults
+# --------
+#
+# These are the default values which are only written into the variable if
+# you don't specify a value above
+if [ "x$thank_software_introduce" = "x" ]; then
+    thank_software_introduce=""
+fi
+
+if [ "x$thank_progs_libs" = "x" ]; then
+    str="This research was done with the following free software"
+    str="$str programs and libraries:"
+    thank_progs_libs="$str"
+fi
+
+if [ "x$thank_python" = "x" ]; then
+    thank_python="Within Python, the following modules were used:"
+fi
+
+if [ "x$thank_latex" = "x" ]; then
+    str="The \LaTeX{} source of the paper was compiled to make the"
+    str="$str PDF using the following packages:"
+    thank_latex="$str"
+fi
+
+if [ "x${thank_software_conclude}" = "x" ]; then
+    str="We are very grateful to all their creators for freely "
+    str="$str providing this necessary infrastructure. This research "
+    str="$str (and many other projects) would not be possible without "
+    str="$str them."
+    thank_software_conclude="$str"
+fi
diff --git a/reproduce/software/shell/configure.sh b/reproduce/software/shell/configure.sh
index 1963bc7..68009a2 100755
--- a/reproduce/software/shell/configure.sh
+++ b/reproduce/software/shell/configure.sh
@@ -1387,26 +1387,27 @@ prepare_name_version ()
     fi
 }
 
+# Import the context/sentences for placing between the list of software
+# names during their acknowledgment.
+. $cdir/software_acknowledge_context.sh
+
 # Report the different software in separate contexts (separating Python and
 # TeX packages from the C/C++ programs and libraries).
 proglibs=$(prepare_name_version $verdir/proglib/*)
 pymodules=$(prepare_name_version $verdir/python/*)
 texpkg=$(prepare_name_version $verdir/tex/texlive)
 
-# Write them as one paragraph for LaTeX.
+# Acknowledge these software packages in a LaTeX paragraph.
 pkgver=$mtexdir/dependencies.tex
-.local/bin/echo "This research was done with the following free" > $pkgver
-.local/bin/echo "software programs and libraries: $proglibs."   >> $pkgver
+
+# Add the text to the ${pkgver} file.
+.local/bin/echo "$thank_software_introduce " > $pkgver
+.local/bin/echo "$thank_progs_libs $proglibs. "   >> $pkgver
 if [ x"$pymodules" != x ]; then
-    .local/bin/echo "Within Python, the following modules"      >> $pkgver
-    echo "were used: $pymodules."                               >> $pkgver
+    .local/bin/echo "$thank_python $pymodules. "   >> $pkgver
 fi
-.local/bin/echo "The \LaTeX{} source of the paper was compiled" >> $pkgver
-.local/bin/echo "to make the PDF using the following packages:" >> $pkgver
-.local/bin/echo "$texpkg. We are very grateful to all their"    >> $pkgver
-.local/bin/echo "creators for freely providing this necessary"  >> $pkgver
-.local/bin/echo "infrastructure. This research (and many "      >> $pkgver
-.local/bin/echo "others) would not be possible without them."   >> $pkgver
+.local/bin/echo "$thank_latex $texpkg. " >> $pkgver
+.local/bin/echo "$thank_software_conclude" >> $pkgver
 
 # Prepare the BibTeX entries for the used software (if there are any).
 hasentry=0