From 3af64fc32c081608f9c619df2b43800b712d2a5a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Del=20Pino?= <stephane.delpino44@gmail.com>
Date: Mon, 23 May 2022 18:17:50 +0200
Subject: [PATCH] Fix a set of typos

---
 doc/userdoc.org | 92 ++++++++++++++++++++++++++-----------------------
 1 file changed, 48 insertions(+), 44 deletions(-)

diff --git a/doc/userdoc.org b/doc/userdoc.org
index 4c2bc1352..457d7ed44 100644
--- a/doc/userdoc.org
+++ b/doc/userdoc.org
@@ -107,8 +107,8 @@ The example is quite easy to read.
   mesh. Observe that if the resulting mesh is stored in the same
   variable ~m~, the old one was not modified in the process. It is
   important to already have in mind that the ~pugs~ language *does not
-  allow* the modifications of values of *non-basic* types. This is
-  discussed in the section [[high-level-types]].
+  allow* the modifications of values of variables of *non-basic*
+  types. This is discussed in the section [[high-level-types]].
 - Finally, the last block consists in saving the obtained mesh in a
   ~gnuplot~ file. The result is shown on Figure [[fig:intro-example]].
 
@@ -140,7 +140,7 @@ already be discussed.
   almost the same but one must know their differences to understand
   better the underlying mechanisms and choices that we made. See
   section [[basic-types]] and [[high-level-types]] for details.
-- Also, there are two types of function: *user-defined* functions and
+- Also, there are two types of functions: *user-defined* functions and
   *builtin* functions. In this example, ~theta~, ~M~ and ~T~ are user-defined
   functions. All other functions (~cos~, ~cartesian2dMesh~,...) are
   builtin functions and are generally defined when importing a
@@ -174,7 +174,7 @@ provided script. A ~C++~ function is associated to each instruction of
 the script. The ~C++~ components of ~pugs~ are completely unaware of the
 other ones. ~pugs~ interpreter is responsible of data flow between the
 components: it manages the data transfer between those ~C++~ components
-and ensure that the workflow is properly defined.
+and ensures that the workflow is properly defined.
 
 **** Why?
 
@@ -197,16 +197,17 @@ methods or their settings.
 - Data files may contain irrelevant information. Actually, it is quite
   common to allow to define options that are valid but irrelevant to a
   given scenario. This policy can be changed but it is generally not
-  an easy task and require more work from the user (which can be a
+  an easy task and requires more work from the user (which can be a
   good thing).
 - It is quite common that data files become obsolete. An option was
-  not the right one, or its type depended of a simpler context... This
-  puts pressure on the user.
-- Even worst options meaning can depend on other
+  not the right one, or its type changed to allow other
+  contexts... This puts pressure on the user.
+- Even worst, options meaning can depend on other
   options. Unfortunately, it happens quite easily. For instance, a
   global option can change implicitly the treatment associated to
   another one. This is quite dangerous since writing or reading the
-  data file requires an important knowledge of the code internals.
+  data file requires an important and up to date knowledge of the
+  code's internals.
 - Another major difficulty when dealing with data files is to check
   the compatibility of provided options.
 
@@ -221,8 +222,8 @@ files or a script), but it presents several drawbacks.
   defining the model and numerical options, the user has generally
   access to the whole code and can change almost everything, even
   things that should not be changed.
-- Again, easily one can have access to irrelevant options and it
-  requires a great knowledge of the code to find relevant ones.
+- Again, one can easily have access to irrelevant options and it
+  requires a great knowledge of the code to find important ones.
 - With that regard, defining a simulation properly can be a difficult
   task. For instance, in the early developments of ~pugs~ (when it was
   just a raw ~C++~ code) it was tricky to change boundary conditions for
@@ -240,20 +241,20 @@ files or a script), but it presents several drawbacks.
 Actually, an honest analysis cannot conclude that a DSL is the
 solution to all problems. However, it offers some advantages.
 
-- First it allows a fine control on what the user can or cannot
-  performed. In some sense it offers a chosen level of flexibility.
+- First, it allows a fine control on what the user can or cannot
+  perform. In some sense, it offers a chosen level of flexibility.
 - It allows to structure the code in the sense that new developments
   have to be designed not only focusing on the result but also on the
   way it should be used (its interactions with the scripting language).
 - In the same idea, it provides a framework that should ease the
-  definition of "do simple things and do it well".
-- There are no hidden dependencies between numerical options: the code
-  is easier to read and it is more difficult to get obsolete (this is
-  not that true in early development since the language itself and
-  some concepts are still likely to change).
-- The simulation scenario is *defined* by the script, it is the
-  responsibility of the user in some sense and not to the charge of
-  the code to check its meaning.
+  desired principle of "do simple things and do them well".
+- There are no hidden dependencies between numerical options: the DSL
+  code is easier to read (than data files) and it is more difficult to
+  get it obsolete (this is not that true in early developments since
+  the language itself and some concepts are still likely to change).
+- The simulation scenario is *defined* by the script, it is to the
+  responsibility of the user and not to the charge of the code to
+  check its meaning.
 
 
 ***** ~pugs~ language purpose
@@ -266,7 +267,7 @@ Another purpose of the language is to allow perform high-level
 calculations. In other words, the language defines a data flow and
 checks that each ~C++~ piece of code is used correctly. Since each piece
 of code acts as a pure function (arguments are unchanged by calls),
-the context is quite easily checked.
+the calling context is quite easy to check.
 
 Finally it aims at simplifying the definition of new methods since
 common utilities are available directly in scripts.
@@ -275,17 +276,19 @@ common utilities are available directly in scripts.
 
 ~pugs~ is a research oriented software, thus generally the user is also
 a developer. If this paragraph is indeed more dedicated to the
-developer, reading it, the user will understand better the choices and
-policy that drive the code.
+developer, by reading it, the user will have a better understanding of
+the development choices and the underlying policy that that the code
+follows.
 
 Actually the development framework imposed by the DSL tends to guide
 writing of new methods.
 
 - A natural consequence is that the developer is encourage to write
-  small independent ~C++~ methods (even it does not forbid to write big
-  monolithic pieces of code). However as already said, one should try
-  to respect the following precept: write small piece of code to ease
-  their testing and validation, try to do simple things the right way.
+  small independent ~C++~ methods (even if it does not forbid to write
+  big monolithic pieces of code). However as already said, one should
+  try to respect the following precept: write small piece of code to
+  ease their testing and validation, try to do simple things the right
+  way.
 - Also, in the process of writing a *new numerical methods*, one must
   create *new functions in the language*. Moreover, if a new method is
   close to an existing one, it is generally *better* to use completely
@@ -309,11 +312,12 @@ writing of new methods.
   - If the new method is abandoned or simply not kept, the existing
     code is not polluted.
   - Finally when a method is validated and ready to integrate the
-    mainline of the code, it is easier to see differences with
+    mainline sources of the code, it is easier to see differences with
     existing ones and *at this time* one can redesign the ~C++~ code
     checking that results are unchanged and performances not
     deteriorated. At this time, it is likely that the numerical method
-    design if finished, thus (re)designing the code makes more sense.
+    design is finished, thus (re)designing the source code makes more
+    sense.
 - Another consequence is that utilities are not be developed again and
   again.
   - This implies an /a priori/ safer code: utilities are well tested and
@@ -325,16 +329,17 @@ writing of new methods.
     knowledge of existing utilities is required, this document tries
     to address a part of it. In the other hand, if the developer
     requires a new utility, a good practice is to discuss with the
-    others to check if it could benefit to the others to determine if
-    it should integrate rapidly or not the main development branch.
+    others to check if it could benefit to them. Then one can
+    determine if it should integrate rapidly or not the main
+    development branch.
 
 ***** Why not python or any other scripting language?
 
 As it was already pointed out above, general purpose languages offer
 to much freedom: it is not easy to protect data. For instance in the
 ~pugs~ DSL, non basic variables are constant (see paragraph
-[[high-level-types]]). It is important since its prevent the user to modify
-data in an inconsistent way. Also, one must keep in mind that
+[[high-level-types]]). It is important since it prevents the user to
+modify data in inconsistent ways. Also, one must keep in mind that
 constraining the expressiveness is actually a strength. As said
 before, one can warranty coherence of the data, perform calculations
 without paying attention to the parallelism aspects,... Observe that
@@ -367,8 +372,9 @@ programmer knows that writing the code is only the first step of a
 much longer process which requires rigorous tests and validations, the
 enrichment of a non-regression database. Generally one also desires to
 ensure that the development is used within the correct bounds which
-requires to implement some checking. In a perfect world, an up-to-date
-documentation of the functionality and its domain of validity.
+requires to implement checking and data verification. In a perfect
+world, an up-to-date documentation of the functionality and its domain
+of validity.
 
 This is even more true when defining a language (or a DSL). Enriching
 a language syntax (or grammar) is not something that must be done to
@@ -385,10 +391,10 @@ If the grammar of ~pugs~ is still likely to be extended, it should *never*
 integrate low-level instructions. Low-level instructions give too much
 freedom and thus are a source of errors. Several things are already
 done to forbid this kind of evolution. The constness of high-level
-data for instance is a good illustration. In practice for instance
-meshes or discrete functions *cannot* be modified. This is not only a
-security that protects the user from doing "dangerous" manipulations,
-but that also permits to define high-level optimizations.
+data is a good illustration. For instance, meshes or discrete
+functions *cannot* be modified. This is not only a security to protects
+the user from doing "dangerous" manipulations, but it also permits to
+define high-level optimizations.
 - Since meshes are constant objects, one can for instance compute
   geometric data on demand. These data are kept into memory as long as
   the mesh lives.
@@ -405,7 +411,7 @@ write errors.
 ** Variables
 
 In order to simplify the presentation, before going further, we
-introduce the construction that allow to print data to the
+introduce the construction that allows to print data to the
 terminal. It follows ~C++~ streams construction for convenience. For
 instance
 #+NAME: cout-preamble-example
@@ -452,7 +458,7 @@ For instance to declare a real variable ~x~, one writes
 The instructions that follow the declaration of a variable can use it
 while defined in the same scope, but it cannot be used before. Also,
 after its declaration, one cannot declare another variable with the
-same name in the same scope.
+same name in the same scope (see [[blocks-and-life-time]]).
 #+NAME: redeclare-variable
 #+BEGIN_SRC pugs-error :exports both :results output
   let x:R; // first declaration
@@ -1136,8 +1142,6 @@ they follow a few rules.
 
 *** TODO Tuples types
 
-*** TODO blocks and variables lifetime
-
 ** TODO modules
 
 ** TODO Statements
-- 
GitLab