From 085141f5359926c54b5ad524b24b0c1878226738 Mon Sep 17 00:00:00 2001 From: Boud Roukema Date: Wed, 22 Apr 2020 18:58:43 +0200 Subject: 4.3.2 Project analysis - values within text Reduction of about 15 words. The phrase "which does not need it" is removed. On its own, this is a claim, not an explanation. If the reader is wondering why `paper.tex` is not a produced file, then stating that the file is not needed will not help very much. Looking at the diagram will show that `paper.tex` is the overall article template; and the diagram strongly suggests that values from initialize.tex, ..., are passed into verify.tex, and from there into project.tex, which goes into paper.tex. The phrase "files, possibly in another subMakefile" should really be something like "files, possibly created by another subMakefile". But this would add more words, and given that the user has full control to modify and adapt the overall scheme (including making a mess of it), we can safely drop the info that the scheme can be made more complicated. :) --- paper.tex | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/paper.tex b/paper.tex index ae2d45d..77ac564 100644 --- a/paper.tex +++ b/paper.tex @@ -498,21 +498,21 @@ The high-level connections of this project with previous projects are formalized Figures, plots, tables and narrative are not the only analysis products that are included in the paper/report. In many cases, quantitative values from the analysis are also blended into the sentences of the report's narration. -For example, this sentence in the abstract of \citet[\href{https://doi.org/10.5281/zenodo.3408481}{zenodo.3408481}, written in Maneage]{akhlaghi19}: ``\emph{... detect the outer wings of M51 down to S/N of 0.25 ...}''. -The value `0.25', for the signal-to-noise ratio (S/N), depends on the analysis, and is an output of the analysis just like paper's figures and plots. -Manually typing such numbers in the narrative is prone to very important errors and discourages testing in scientific papers. -Therefore, they must \emph{also} be automatically generated. +An example is in the abstract of \citet[\href{https://doi.org/10.5281/zenodo.3408481}{zenodo.3408481}, written in Maneage]{akhlaghi19}: ``\emph{... detect the outer wings of M51 down to S/N of 0.25 ...}''. +The value `0.25', for the signal-to-noise ratio (S/N), depends on the analysis, and is an output of the analysis just like the paper's figures and plots. +Manually typing such numbers in the narrative can easiliy introduce errors and discourages testing in scientific papers. +Therefore, these values must \emph{also} be automatically generated. To automatically generate and blend them in the text, Maneage uses \LaTeX{} macros. -For example, \LaTeX{} source of the quote above is: ``\inlinecode{\small detect the outer wings of M51 down to S/N of \$\textbackslash{}demo\-sf\-optimized\-sn\$}''. -T\-he ma\-cro ``\inlinecode{\small\textbackslash{}demosfoptimizedsn}'' is automatically created during in the project and expands to the value ``\inlinecode{0.25}'' when the PDF output is built. +For example, the \LaTeX{} source of the quote above is: ``\inlinecode{\small detect the outer wings of M51 down to S/N of \$\textbackslash{}demo\-sf\-optimized\-sn\$}''. +The ma\-cro ``\inlinecode{\small\textbackslash{}demosfoptimizedsn}'' is automatically created during the project. It expands to the value ``\inlinecode{0.25}'' when the PDF output is built. All such values are referenced in \inlinecode{project.tex}. -However, managing all the necessary \LaTeX{} macros in one file is against the modularity principle and can be frustrating and buggy. -To address this problem, Maneage adopts the convention that all subMakefiles \emph{must} contain a fixed target with the same base-name, but with a \inlinecode{.tex} suffix to store reported values generated in that subMakefile. -If it does not need to report any values in the text, the file can indeed be empty. -In Figure \ref{fig:datalineage}, these macro files can be seen in every subMakefile, except for \inlinecode{paper.mk} (which does not need it). -These \LaTeX{} macro files thus form the core skeleton of a Maneage project: as shown in Figure \ref{fig:datalineage}, the outward arrows of all built files of any subMakefile ultimately leads to one of these \LaTeX{} macro files, possibly in another subMakefile. +However, managing all the necessary \LaTeX{} macros in a single file would violate the modularity principle and would be frustrating and bug-prone. +Thus, Maneage adopts the convention that all subMakefiles \emph{must} contain a fixed target with the same unsuffixed filename, but with a \inlinecode{.tex} suffix to store calculated values generated by that subMakefile. +If this file does not need to report any values, it may be left empty. +In Figure \ref{fig:datalineage}, these macro files can be seen in every subMakefile, except for \inlinecode{paper.mk}. +These \LaTeX{} macro files form the core skeleton of a Maneage project: as shown in Figure \ref{fig:datalineage}, the outward arrows of all built files of any subMakefile ultimately lead to one of these \LaTeX{} macro files. \subsubsection{Verification of outputs (\inlinecode{verify.mk})} \label{sec:outputverification} -- cgit v1.2.1