[gnuastro-commits] master a0dda22 1/4: Minor corrections in book

[Mohammad Akhlaghi]

branch: master
commit a0dda227971aa185428dabd80cee9b9cbf4ad06d
Author: Mohammad Akhlaghi <address@hidden>
Commit: Mohammad Akhlaghi <address@hidden>

    Minor corrections in book
    
    A few minor issues/edits were made in the book.
---
 doc/gnuastro.texi | 143 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 74 insertions(+), 69 deletions(-)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index b9f9dff..1bcd7d6 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -1760,9 +1760,9 @@ distributions. If you use another graphical desktop 
environment, replace
 @command{eog} with any other image viewer.}. Since he has used it before,
 he knows that once it opens an image, he can use the @key{ENTER} or
 @key{SPACE} keys on the keyboard to go to the next image in the directory
-or the @key{Backspace} key to to go the previous image. So he opens the
-image of the first object with the command below and with his cup of coffee
-in his other hand, he flips through his targets very fast to get a good
+or the @key{Backspace} key to go the previous image. So he opens the image
+of the first object with the command below and with his cup of coffee in
+his other hand, he flips through his targets very fast to get a good
 initial impression of the morphologies of these extra-galactic nebulae.
 
 @example
@@ -21367,7 +21367,7 @@ both polygons have to be sorted in an anti-clock-wise 
manner.
 
 The C programming language comes with the @code{qsort} (Quick sort)
 function. @code{qsort} is a generic function which allows you to sort any
-kind of data structure (not just a single number). To to define greater and
+kind of data structure (not just a single number). To define greater and
 smaller (for sorting), @code{qsort} needs another function, even for simple
 numerical types. To facilitate numerical sorting for Gnuastro's
 programs/libraries, Gnuastro defines a function for each type's increasing
@@ -21747,14 +21747,15 @@ Apply @mymath{\sigma}-clipping on a given dataset and 
return a dataset that
 contains the results. For a description of @mymath{\sigma}-clipping see
 @ref{Sigma clipping}. @code{multip} is the multiple of the standard
 deviation (@mymath{\sigma} that is used to define outliers in each round of
-clipping.
+clipping).
 
 The role of @code{param} is determined based on its value. If @code{param}
 is larger than @code{1} (one), it must be an integer and will be
 interpretted as the number clips to do. If it is less than @code{1} (one),
 it is interpretted as the tolerance level to stop the iteration.
 
-The output dataset has the following elements:
+The output dataset has the following elements with a
address@hidden type:
 @example
 array[0]: Number of points used.
 array[1]: Median.
@@ -22508,9 +22509,8 @@ benefit, and the larger community if they are willing 
to share it. In
 short, we hope that at least from the software point of view, the
 ``obscurantist faith in the expert's special skill and in his personal
 knowledge and authority'' can be broken, see @ref{Science and its
-tools}. With this aim in mind, Gnuastro was designed to to have a very
-basic, simple, and easy to understand architecture for any interested
-inquirer.
+tools}. With this aim in mind, Gnuastro was designed to have a very basic,
+simple, and easy to understand architecture for any interested inquirer.
 
 This chapter starts with very general design choices, in particular
 @ref{Why C} and @ref{Program design philosophy}. It will then get a little
@@ -22663,15 +22663,19 @@ speed'' is desired.
 @node Program design philosophy, Coding conventions, Why C, Developing
 @section Program design philosophy
 
address@hidden Gnulib
 The core processing functions of each program (and all libraries) are
 written mostly with the basic ISO C90 standard. We do make lots of use of
-the GNU additions to the C language in the GNU C library, but these
-additional functions are mainly used in the user interface functions
-(reading your inputs and preparing them prior to or after the
-analysis). The actual algorithms, which most scientists would be more
-interested in, are much more closer to ISO C90. For this reason, program
-source files that deal with user interface issues and those doing the
-actual processing are clearly separated, see @ref{Program source}. If
+the GNU additions to the C language in the GNU C address@hidden
+uses many GNU additions to the C library. However, thanks to the GNU
+Portability library (Gnulib) which is included in the Gnuastro tarball,
+users of non-GNU/Linux operating systems can also benefit from all these
+features when using Gnuastro.}, but these functions are mainly used in the
+user interface functions (reading your inputs and preparing them prior to
+or after the analysis). The actual algorithms, which most scientists would
+be more interested in, are much more closer to ISO C90. For this reason,
+program source files that deal with user interface issues and those doing
+the actual processing are clearly separated, see @ref{Program source}. If
 anything particular to the GNU C library is used in the processing
 functions, it is explained in the comments in between the code.
 
@@ -22739,17 +22743,16 @@ in. However, this visual aid greatly helps in general 
inspections of the
 code and help the reader get a grip of the function's processing.
 
 @item
-When ever you see that the function cannot be fully displayed (vertically)
-in your monitor, this is a sign that it has probably become too long and
-should be broken up into multiple functions. 40 lines is usually a good
-reference. When the start and end of a function are clearly visible in one
-glance, the function is much more easier to understand. This is most
-important for low-level functions (which usually define a lot of
-variables). Low-level functions do most of the processing, they will also
-be the most interesting part of a program for an inquiring astronomer. This
-convention is less important for higher level functions that don't define
-too many variables and whose only purpose is to run the lower-level
-functions in a specific order and with checks.
+A function that cannot be fully displayed (vertically) in your monitor is
+probably too long and may be more useful if it is broken up into multiple
+functions. 40 lines is usually a good reference. When the start and end of
+a function are clearly visible in one glance, the function is much more
+easier to understand. This is most important for low-level functions (which
+usually define a lot of variables). Low-level functions do most of the
+processing, they will also be the most interesting part of a program for an
+inquiring astronomer. This convention is less important for higher level
+functions that don't define too many variables and whose only purpose is to
+run the lower-level functions in a specific order and with checks.
 
 @cindex Optimization flag
 @cindex GNU Compiler Collection
@@ -23043,11 +23046,11 @@ program containing all these files, see @ref{The 
TEMPLATE program}.
 @item main.c
 @cindex @code{main} function
 Each executable has a @code{main} function, which is located in
address@hidden Therefore this file in any program's source code will be the
-starting point. No actual processing functions must be defined in this
-file, the function(s) in this file are only meant to connect the most high
-level steps of each program. Generally, @code{main} will first call the top
-user interface function to read user input and make all the
address@hidden Therefore this file is the starting point when reading any
+program's source code. No actual processing functions must be defined in
+this file, the function(s) in this file are only meant to connect the most
+high level steps of each program. Generally, @code{main} will first call
+the top user interface function to read user input and make all the
 preparations. Then it will pass control to the top processing function for
 that program. The functions to do both these jobs must be defined in other
 source files.
@@ -23397,9 +23400,8 @@ $ ./configure --disable-shared CFLAGS="-g -O0"
 @end example
 
 @noindent
-These options to configure are already included in
address@hidden, you just have to un-comment them when you want to
-start developing or debugging.
+In @file{tmpfs-config-make} you can ask for this behavior by setting
address@hidden to @code{1}.
 
 In order to understand the building process, you can go through the
 Autoconf, Automake and Libtool manuals, like all GNU manuals they provide
@@ -23442,10 +23444,11 @@ executable.
 The most important thing to have in mind about all the test scripts is that
 they are run from inside the @file{tests/} directory in the ``build
 tree''. Which can be different from the directory they are stored in (known
-as the ``source tree''). The @file{tmpfs-config-make} script uses this
-feature (see @ref{Configure and build in RAM}). This distinction is made by
-GNU Autoconf and Automake (which configure, build and install Gnuastro) so
-that you can install the program even if you don't have write access to the
+as the ``source tree'')@footnote{The @file{tmpfs-config-make} script also
+uses this feature to keep the source and build directories separate (see
address@hidden and build in RAM}).}. This distinction is made by GNU
+Autoconf and Automake (which configure, build and install Gnuastro) so that
+you can install the program even if you don't have write access to the
 directory keeping the source files. See the ``Parallel build trees (a.k.a
 VPATH builds)'' in the Automake manual for a nice explanation.
 
@@ -23674,7 +23677,7 @@ addition/change with the whole community as part of the 
official
 release. This is great and your contribution is most welcome. This section
 and the next (see @ref{Developer's checklist}) are written in the hope of
 making it as easy as possible for you to share your great idea with the
-Gnuastro community.
+community.
 
 @cindex FSF
 @cindex Free Software Foundation
@@ -23930,22 +23933,24 @@ might change and evolve to better suit our needs.
 @node Forking tutorial,  , Production workflow, Contributing to Gnuastro
 @subsection Forking tutorial
 
-This is a tutorial on the second suggested method that you can submit your
-modifications in Gnuastro (see @ref{Production workflow}), which is
-commonly known as forking. Let's assume you want to start contributing to
-Gnuastro and you would like to use address@hidden
+This is a tutorial on the second suggested method (commonly known as
+forking) that you can submit your modifications in Gnuastro (see
address@hidden workflow}).
+
+To start, please create an empty repository on your hosting service webpage
+(we recommend address@hidden
 @url{https://www.gnu.org/software/repo-criteria-evaluation.html} for an
-evaluation of the major existing repositories.} to host your work remotely
-and share it with other Gnuastro developers once you are ready. You can
-create an empty repository on your hosting service webpage. If this is your
-first hosted repository on the webpage, you also have to upload your public
-SSH address@hidden example see this explanation provided by GitLab:
+evaluation of the major existing repositories. Gnuastro uses GNU Savannah
+(which also has the highest ranking in the evaluation), but for starters,
+GitLab may be easier.}). If this is your first hosted repository on the
+webpage, you also have to upload your public SSH address@hidden example
+see this explanation provided by GitLab:
 @url{http://docs.gitlab.com/ce/ssh/README.html}.} for the @command{git
 push} command below to work. Here we'll assume you use the name
 @file{janedoe} to refer to yourself everywhere and that you choose
 @file{gnuastro-janedoe} as the name of your Gnuastro fork. Any online
-hosting service will give you an address (similar to
address@hidden@@gitlab.com:}' below) of the empty repository you have created
+hosting service will give you an address (similar to the
address@hidden@@gitlab.com:...}' below) of the empty repository you have created
 using their webpage, use that address in the third line below.
 
 @example
@@ -23966,20 +23971,19 @@ repository.
 
 To test (compile) your changes during your work, you will need to bootstrap
 the version controlled source, see @ref{Bootstrapping} for a full
-description. The process above is only necessary for your first time setup,
-you don't need to repeat it. However, please repeat the steps below for
-each independent issue you intend to work on.
+description. The cloning process above is only necessary for your first
+time setup, you don't need to repeat it. However, please repeat the steps
+below for each independent issue you intend to work on.
 
 Let's assume you have found a bug in @file{lib/statistics.c}'s median
-calculating function. You announce it (see @ref{Report a bug}) so everyone
-knows you are working on it. However, if it is a very simple, clear/obvious
-and straightforward bug to fix you can skip this initial announcement. With
-the commands below, you make a branch, checkout to it, correct the bug,
-check if it is indeed fixed, add it to the staging area, commit it to the
-new branch and push it to your hosting service. But before all of them,
-make sure that you are on the @file{master} branch and that your
address@hidden branch is up to date with the main Gnuastro repository with
-the first two commands.
+calculating function. Before actually doing anything, please announce it
+(see @ref{Report a bug}) so everyone knows you are working on it or to find
+out others aren't already working on it. With the commands below, you make
+a branch, checkout to it, correct the bug, check if it is indeed fixed, add
+it to the staging area, commit it to the new branch and push it to your
+hosting service. But before all of them, make sure that you are on the
address@hidden branch and that your @file{master} branch is up to date with
+the main Gnuastro repository with the first two commands.
 
 @example
 $ git checkout master
@@ -24000,8 +24004,8 @@ be merged into the main Gnuastro history, they will 
merge it into the
 @file{master} branch. After that is done, you can simply checkout your
 local @file{master} branch and pull all the changes from the main
 repository. After the pull you can run address@hidden log}' as shown below,
-to see how @file{bug-median-stats} is merged with master. So you can push
-all the changes to your hosted repository and delete the branches:
+to see how @file{bug-median-stats} is merged with master. To finalize, you
+can push all the changes to your hosted repository and delete the branch:
 
 @example
 $ git checkout master
@@ -24015,10 +24019,11 @@ $ git push janedoe --delete bug-median-stats    # 
delete remote branch
 Just as a reminder, always keep your work on each issue in a separate local
 and remote branch so work can progress on them independently. After you
 make your announcement, other people might contribute to the branch before
-merging it in to @file{master}, so this is very important. Also before
-starting each issue branch from @file{master}, be sure to run @command{git
-pull} in @file{master} as shown above, to start your branch (work) from the
-most recent history point and thus simplify the final merging of your work.
+merging it in to @file{master}, so this is very important. As a final
+reminder: before starting each issue branch from @file{master}, be sure to
+run @command{git pull} in @file{master} as shown above. This will enable
+you to start your branch (work) from the most recent commit and thus
+simplify the final merging of your work.