Described the first analysis phase with a demo subMakefile

Until now, there was no explanation on an actual analysis phase, therefore
with this commit an example scenario with a readable Makefile is included.
The Data lineage graph was also simplified to both be more readable, and
also to correspond to this new explanation and subMakefile.

Some random edits/typos were also corrected and some references added for
discussion.

5 files changed, 130 insertions, 26 deletions

diff --git a/tex/src/figure-data-lineage.tex b/tex/src/figure-data-lineage.tex
index aa2a397..010a0be 100644
--- a/tex/src/figure-data-lineage.tex
+++ b/tex/src/figure-data-lineage.tex
@@ -136,14 +136,14 @@
 
   %% input-2.dat
   \ifdefined\inputtwo
-  \node (input2) [node-terminal, at={(-2.93cm,1.1cm)}] {input2.dat};
+  \node (input2) [node-terminal, at={(-2.93cm,1.9cm)}] {menke20.xlsx};
   \draw [->] (input2) -- (downloadtex);
   \fi
 
   %% INPUTS.conf
   \ifdefined\inputsconf
   \node (INPUTS) [node-nonterminal, at={(-2.93cm,4.6cm)}] {INPUTS.conf};
-  \node (input2-west) [node-point, at={(-4.33cm,1.1cm)}] {};
+  \node (input2-west) [node-point, at={(-4.33cm,1.9cm)}] {};
   \draw [->,rounded corners] (INPUTS.west) -| (input2-west) |- (input2);
   \fi
 
@@ -155,31 +155,14 @@
 
   %% out1b.dat
   \ifdefined\outoneb
-  \node (out1b) [node-terminal, at={(-0.13cm,1.1cm)}] {out-1b.dat};
+  \node (out1b) [node-terminal, at={(-0.13cm,1.1cm)}] {menke20-table-3.txt};
   \draw [->] (out1b) -- (a1tex);
   \fi
 
   %% outonebdep
   \ifdefined\outonebdep
   \node (out1b-west) [node-point, at={(-1.53cm,1.1cm)}] {};
-  \node (out1a) [node-terminal, at={(-0.13cm,2.7cm)}] {out-1a.dat};
-  \node (a1conf1) [node-nonterminal, at={(-0.13cm,4.6cm)}] {param-1.conf};
-  \draw [->] (input2) -- (out1b);
-  \draw [->] (out1a) -- (out1b);
-  \draw [->,rounded corners] (a1conf1.west) -| (out1b-west) |- (out1b);
-  \fi
-
-  %% input1.dat
-  \ifdefined\inputone
-  \node (input1) [node-terminal, at={(-2.93cm,1.9cm)}] {input1.dat};
-  \draw [->,rounded corners,] (input1.north) |- (out1a);
-  \fi
-
-  %% input1 dependencies
-  \ifdefined\inputonedep
-  \node (input1-east) [node-point, at={(-1.53cm,1.9cm)}] {};
-  \node (input1-west) [node-point, at={(-4.33cm,1.9cm)}] {};
-  \draw [->,rounded corners] (INPUTS.west) -| (input1-west) |- (input1);
+  \draw [->, rounded corners] (input2) |- (out1b);
   \fi
 
   %% analysis2.tex
@@ -227,14 +210,13 @@
   \node (out2a-west) [node-point, at={(1.27cm,1.9cm)}] {};
   \draw [->,rounded corners] (a2conf1.west) -| (out2a-west) |- (out2a);
   \draw [->,rounded corners] (a2conf2.west) -| (out2a-west) |- (out2a);
-  \draw [->] (input1) -- (out2a);
+  %\draw [->] (input1) -- (out2a);
   \fi
 
   %% Dependencies of out-3a
   \ifdefined\outthreeadep
   \node (out3a-west) [node-point, at={(4.07cm,2.7cm)}] {};
   \node (a3conf1) [node-nonterminal, at={(5.47cm,4.6cm)}]  {param-3.conf};
-  \draw [->] (out1a) -- (out3a);
   \draw [rounded corners] (a3conf1.west) -| (out3a-west) |- (out3a);
   \fi
 \end{tikzpicture}
diff --git a/tex/src/figure-download.tex b/tex/src/figure-download.tex
new file mode 100644
index 0000000..b9da02f
--- /dev/null
+++ b/tex/src/figure-download.tex
@@ -0,0 +1,8 @@
+\begin{tcolorbox}
+  \footnotesize
+  \texttt{\mkcomment{Write download URL into the paper (through a LaTeX macro).}}
+
+  \texttt{\mktarget{\$(mtexdir)/download.tex}: \$(\mkvar{indir})/menke20.xlsx}
+
+  \texttt{\mktab{}\mkprog{echo} "\textbackslash{}newcommand{\textbackslash{}menketwentyurl}\{\mktarget{\$(MK20URL)}\}" > \$@}
+\end{tcolorbox}
diff --git a/tex/src/figure-mk20tab3.tex b/tex/src/figure-mk20tab3.tex
new file mode 100644
index 0000000..ebeac0e
--- /dev/null
+++ b/tex/src/figure-mk20tab3.tex
@@ -0,0 +1,50 @@
+\begin{tcolorbox}
+  \footnotesize
+  \texttt{\mkcomment{Define and build the directory hosting the final table.}}
+
+  \texttt{\mkvar{a1dir} = \$(\mkvar{BDIR})/analysis-1}
+
+  \texttt{\mktarget{\$(a1dir)}:}
+
+  \texttt{\mktab{}\mkprog{mkdir} \$@}
+
+  \vspace{1.5em}
+  \texttt{\mkcomment{Define and build the main target.}}
+
+  \texttt{\mkvar{mk20tab3} = \$(\mkvar{a1dir})/menke20-table-3.txt}
+
+  \texttt{\mktarget{\$(mk20tab3)}: \$(\mkvar{indir})/menke20.xlsx | \$(\mkvar{a1dir})}
+
+  \texttt{\recipecomment{Call XLSX I/O to convert all the spreadsheets into different CSV files.}}
+
+  \texttt{\recipecomment{We only want the `table-3' spreadsheet, but XLSX I/O doesn't allow setting its}}
+
+  \texttt{\recipecomment{output filename. For simplicity, let's assume its written in `table-3.csv'.}}
+
+  \texttt{\mktab{}\mkprog{xlsxio\_xlsx2csv} \$<}
+
+  \vspace{0.5em}
+  \texttt{\recipecomment{Use GNU AWK to keep the desired columns in space-separated, fixed-width format.}}
+
+  \texttt{\recipecomment{With `FPAT' commas within double quotes are not counted as columns.}}
+
+  \texttt{\mktab{}\mkprog{awk} 'NR>1\{printf("\%-10d\%-10d\%-10d \%s\textbackslash{}n", \$\$2, \$\$3, \$\$(NF-1)*\$\$NF, \$\$1)\}' \textbackslash}
+
+  \texttt{\mktab{}{ }{ }{ }{ }FPAT='([\^{},]+)|("[\^{}"]+")' table-3.csv > \$@}
+
+  \vspace{0.5em}
+  \texttt{\recipecomment{Delete the temporary CSV file.}}
+
+  \texttt{\mktab{}\mkprog{rm} table-3.csv}
+
+  \vspace{1.5em}
+  \texttt{\mkcomment{Main LaTeX macro file}}
+
+  \texttt{\mktarget{\$(mtexdir)/analysis1.tex}: \$(\mkvar{mk20tab3)}}
+
+  \texttt{\recipecomment{Count the total number of papers in their study to report in this paper.}}
+
+  \texttt{\mktab{}v=\$\$(\mkprog{awk} '\!/\^{}\#/\{c+=\$\$2\} END\{print c\}' \$(\mkvar{mk20tab3)})}
+
+  \texttt{\mktab{}\mkprog{echo} "\textbackslash{}newcommand\{\textbackslash{}menkenumpapers\}\{\$\$v\}" > \$@}
+\end{tcolorbox}
diff --git a/tex/src/preamble-style.tex b/tex/src/preamble-style.tex
index 9556f54..e20c73c 100644
--- a/tex/src/preamble-style.tex
+++ b/tex/src/preamble-style.tex
@@ -135,11 +135,16 @@
  \renewcommand\footrulewidth{0.0pt}
 }
 
+%% For creating color boxes
+\usepackage[many]{tcolorbox}
+
 %% Custom macros
 \newcommand{\inlinecode}[1]{\textcolor{blue!35!black}{\texttt{#1}}}
 
 %% Example Makefile macros
-\newcommand{\mkcomment}[1]{\textcolor{red!35!white}{#1}}
+\newcommand{\mkcomment}[1]{\textcolor{red!70!white}{\# #1}}
+\newcommand{\mkvar}[1]{\textcolor{orange!40!black}{#1}}
 \newcommand{\mktarget}[1]{\textcolor{blue!40!black}{#1}}
-\newcommand{\mkprereq}[1]{\textcolor{green!30!black}{#1}}
-\newcommand{\mktab}[1]{\textcolor{black!25!white}{\_\_\_TAB\_\_\_}}
+\newcommand{\mkprog}[1]{\textcolor{green!30!black}{#1}}
+\newcommand{\mktab}[1]{\textcolor{black!30!white}{\_\_\_TAB\_\_\_}}
+\newcommand{\recipecomment}[1]{{ }{ }{ }{ }{ }{ }{ }{ }{ }\mkcomment{#1}}
diff --git a/tex/src/references.tex b/tex/src/references.tex
index 2a67584..f4dee1d 100644
--- a/tex/src/references.tex
+++ b/tex/src/references.tex
@@ -12,6 +12,24 @@
 
 
 
+@ARTICLE{konkol20,
+       author = {{Konkol}, Markus and {N{\"u}st}, Daniel and {Goulier}, Laura},
+        title = "{Publishing computational research -- A review of infrastructures for reproducible and transparent scholarly communication}",
+      journal = {arXiv},
+         year = 2020,
+        month = jan,
+        pages = {2001.00484},
+archivePrefix = {arXiv},
+       eprint = {2001.00484},
+ primaryClass = {cs.DL},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2020arXiv200100484K},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+
+
+
+
 @ARTICLE{infante20,
        author = {{Infante-Sainz}, Ra{\'u}l and {Trujillo}, Ignacio and
          {Rom{\'a}n}, Javier},
@@ -49,6 +67,47 @@ archivePrefix = {arXiv},
 
 
 
+@ARTICLE{miksa19a,
+     author = {Tomasz Miksa and Paul Walk and Peter Neish},
+      title = {RDA DMP Common Standard for Machine-actionable Data Management Plans},
+       year = {2019},
+    journal = {RDA},
+      pages = {doi:10.15497/rda00039},
+        doi = {10.15497/rda00039},
+}
+
+
+
+
+
+@ARTICLE{miksa19b,
+     author = {Tomasz Miksa and Stephanie Simms and Daniel Mietchen and Sarah Jones},
+      title = {Ten principles for machine-actionable data management plans},
+       year = {2019},
+    journal = {PLoS Computational Biology},
+     volume = {15},
+      pages = {e1006750},
+        doi = {10.1371/journal.pcbi.1006750},
+}
+
+
+
+
+
+@ARTICLE{dicosmo19,
+     author = {Roberto {Di Cosmo} and Francois Pellegrini},
+      title = {Encouraging a wider usage of software derived from research},
+       year = {2019},
+    journal = {\doihref{https://www.ouvrirlascience.fr/wp-content/uploads/2020/02/Opportunity-Note_software-derived-from-research_EN.pdf}{Ouvrir la science}},
+     volume = {},
+      pages = {},
+        doi = {},
+}
+
+
+
+
+
 @ARTICLE{perignon19,
      author = {Christophe P\'erignon and Kamel Gadouche and Christophe Hurlin and Roxane Silberman and Eric Debonnel},
       title = {Certify reproducibility with confidential data},