From 76a2148e8ef083712c078fff098e785f2e83bb64 Mon Sep 17 00:00:00 2001
From: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Date: Wed, 22 Apr 2020 19:08:35 +0100
Subject: Minor edits to summarize section on project.tex and verify.tex
After going through Boud's corrections, I thought it can be further
summarized without loosing any major point.
---
paper.tex | 28 +++++++++++++---------------
1 file changed, 13 insertions(+), 15 deletions(-)
diff --git a/paper.tex b/paper.tex
index 16c3eb6..70b0346 100644
--- a/paper.tex
+++ b/paper.tex
@@ -496,33 +496,31 @@ The high-level connections of this project with previous projects are formalized
\subsubsection{Values within text (\inlinecode{project.tex})}
\label{sec:valuesintext}
-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.
+Figures, plots, tables, datasets, and/or narrative are not the only outputs of a project.
+In many cases, quantitative values from the analysis are also blended into the sentences of the report's narration, or published with the dataset in a database.
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.
+The value `0.25', for the signal-to-noise ratio (S/N), also depends on the analysis, and is thus also an output.
+Manually typing such numbers in the narrative is prone to errors and discourages experimentation.
To automatically generate and blend them in the text, Maneage uses \LaTeX{} macros.
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 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.
+However, managing them in a single file would violate the modularity principle, be hard to parallelize, frustrating to manage, and bug-prone.
+All subMakefiles thus contain a fixed target with the same name but a different suffix: \inlinecode{.tex} instead of \inlinecode{.mk}, hosting values generated in that subMakefile.
+Figure \ref{fig:datalineage} shows them as built products of 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 in any subMakefile ultimately lead to one of these \LaTeX{} macro files.
\subsubsection{Verification of outputs (\inlinecode{verify.mk})}
\label{sec:outputverification}
-Before the modular \LaTeX{} macro files of Section \ref{sec:valuesintext} are merged into the single \inlinecode{project.tex} file, they need to pass through the verification filter, which implements another core principle of Maneage (\ref{principle:verify}).
-Confirming the checksum of the final PDF or of figures and datasets is not generally useful: many tools write the creation date into the produced files.
-To avoid this, the raw data must be verified independent of metadata like dates.
+Before the modular \LaTeX{} macro files described above are merged into the single \inlinecode{project.tex} file, they need to pass through the verification filter, which implements another core principle of Maneage, \ref{principle:verify}.
+Confirming the checksum of the final PDF or of figures and datasets is not generally useful because many tools write the creation date into the files.
+To avoid this, the raw data must be verified independent of metadata like date.
Some standards include such date-independent verification features, for example, the \inlinecode{DATASUM} keyword in the FITS format \citep{pence10}.
To facilitate output verification, Maneage has the \inlinecode{verify.mk} subMakefile that separates the analytical phase of the paper from the production of the report (see Figure \ref{fig:datalineage}).
-This file implements some tests on pre-defined formats. Other formats can easily be added.
+This file implements some tests on pre-defined formats.
+Other formats can easily be added.
\subsubsection{The analysis}
\label{sec:analysis}
--
cgit v1.2.1