From 48869d6e4abba9bfae6c5a0700180d731e8c1f44 Mon Sep 17 00:00:00 2001
From: Rodrigo Arias Mallo <rodrigo.arias@bsc.es>
Date: Mon, 9 Nov 2020 12:09:54 +0100
Subject: [PATCH] Clarify some sections

---
 garlic/doc/pp.ms | 50 ++++++++++++++++++++++++++----------------------
 1 file changed, 27 insertions(+), 23 deletions(-)

diff --git a/garlic/doc/pp.ms b/garlic/doc/pp.ms
index dc28536..ddaf4b2 100644
--- a/garlic/doc/pp.ms
+++ b/garlic/doc/pp.ms
@@ -25,11 +25,10 @@ move-punctuation
 .NH 1
 Introduction
 .LP
-After the correct execution of an experiment some measurements are
-recorded in the results for further investigation. Typically the time of
-the execution or other quantities are measured and presented later in a
-figure (generally a plot or a table).
-The
+After the correct execution of an experiment the results are stored for
+further investigation. Typically the time of the execution or other
+quantities are measured and presented later in a figure (generally a
+plot or a table). The
 .I "postprocess pipeline"
 consists of all the steps required to create a set of figures from the
 results. Similarly to the execution pipeline where several stages run
@@ -52,9 +51,9 @@ Results
 The results are generated in the same
 .I "target"
 machine where the experiment is executed and are stored in the garlic
-.I output ,
-organized into a directory structure following the experiment name, the
-unit name and the run number (governed by the
+.I out
+directory, organized into a tree structure following the experiment
+name, the unit name and the run number (governed by the
 .I control
 stage):
 .QS
@@ -76,15 +75,18 @@ and
 attributes (defined in the experiment configuration) and linking them to
 the appropriate experiment and unit directories. These links are
 overwritten by the last experiment with the same names so they are only
-valid for the last execution. The output and index directories are
+valid for the last execution. The out and index directories are
 placed into a per-user directory, as we cannot guarantee the complete
-execution of each unit when multiple users can share units.
+execution of each unit when multiple users share units.
 .PP
-The messages printed to the standard output and error are
+The messages printed to 
+.I stdout
+and
+.I stderr
 are stored in the log files with the same name inside each run
 directory. Additional data is sometimes generated by the experiments,
 and is found in each run directory. As the generated data can be very
-large, is ignored by default when considering the results.
+large, is ignored by default when fetching the results.
 .NH 1
 Fetching the results
 .LP
@@ -93,14 +95,16 @@ measure some properties that the experimenter wants to present in a
 visual plot. When the experiment is launched, the execution
 pipeline (EP) is completely executed and it will generate some
 results. In this escenario, the execution pipeline depends on the
-program\[em]any changes in the program will cause nix to build it again
+program\[em]any changes in the program will cause nix to build the
+pipeline again
 using the updated program. The results will also depend on the
-execution pipeline, and the graph on the results. This chain of
-dependencies can be shown in the following dependency graph:
+execution pipeline as well as the postprocess pipeline (PP) and the plot
+on the results. This chain of dependencies can be shown in the
+following dependency graph:
 .ie t \{\
 .PS
 circlerad=0.22;
-linewid=0.35;
+linewid=0.3;
 right
 circle "Prog"
 arrow
@@ -122,15 +126,15 @@ circle "Plot"
 .\}
 Ideally, the dependencies should be handled by nix, so it can detect any
 change and rebuild the necessary parts automatically. Unfortunately, nix
-is not able to build the result as a derivation directly as it requires access
-to the
+is not able to build the result as a derivation directly, as it requires
+access to the
 .I "target"
 machine with several user accounts. In order to let several users reuse
-the same results from a cache, we
-use the
-.I "nix store"
-to make them available. To generate the results from the
-experiment, we add some extra steps that must be executed manually.
+the same results from a shared cache, we would like to use the
+.I "nix store" .
+.PP
+To generate the results from the
+experiment, we add some extra steps that must be executed manually:
 .PS
 circle "Prog"
 arrow