[gnuastro-commits] master 7186702: Edits in the Synchronization section

[Mohammad Akhlaghi]

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

    Edits in the Synchronization section
    
    Based on a discusstion with Leindert Boogaard, the Synchronization section
    was edited to be more clear. Also, a `make distclean' step was added and we
    now recommend `autoreconf' instead of `autoconf'. Also, a link to the
    "Configure and build in RAM" section was added to introduce the readers to
    the very convenient `tmpfs-config-make' script.
---
 doc/gnuastro.texi | 81 ++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 50 insertions(+), 31 deletions(-)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 00e5d9b..061541c 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -5285,34 +5285,55 @@ lists}).  Subscribing to them can help you decide when 
to synchronize with
 the official repository.
 
 To pull all the most recent work in Gnuastro, run the following command
-from the top Gnuastro directory:
+from the top Gnuastro directory. If you don't already have a built system,
+ignore @command{make distclean}. The separate steps are described in detail
+afterwards.
 
 @example
-$ git pull && autoconf -f
+$ make distclean && git pull && autoreconf -f
 @end example
 
address@hidden GNU Autoconf
address@hidden Mailing list: info-gnuastro
address@hidden @code{info-gnuastro@@gnu.org}
-GNU Autoconf is part of the GNU build system and will update the
address@hidden/configure} script based on the hand-written configurations (in
address@hidden, which is version controlled in Gnuastro). The pulled
-changes might contain changes in the build system configurations. However,
-The most important reason for running this command is to generate a version
-number for your Gnuastro snapshot. This generated version number will
-include the commit information if you are building Gnuastro from any point
-in Gnuastro's history (see @ref{Version numbering}). Since the version
-number is included in nearly all outputs of the programs, this can help
-you later exactly reproduce an old result by checking out the exact point
-in Gnuastro's history that produced those results. Therefore, be sure to
-run address@hidden -f}' after every synchronization. You can also run them
-separately:
address@hidden
+You can also run the commands separately:
 
 @example
+$ make distclean
 $ git pull
-$ autoconf -f
+$ autoreconf -f
 @end example
 
address@hidden GNU Autoconf
address@hidden Mailing list: info-gnuastro
address@hidden @code{info-gnuastro@@gnu.org}
+If Gnuastro was already built in this directory, you don't want some
+outputs from the previous version being mixed with outputs from the newly
+pulled work. Therefore, the first step is to clean/delete all the built
+files with @command{make distclean}. Fortunately the GNU build system
+allows the separation of source and built files (in separate
+directories). You can use it to avoid the cleaning step. Gnuastro already
+has script for this, see @ref{Configure and build in RAM}.
+
+After the pull, we must re-configure Gnuastro with @command{autoreconf -f}
+(part of GNU Autoconf). It will update the @file{./configure} script and
+all the @address@hidden the GNU build system,
address@hidden/configure} will use the @file{Makefile.in} files to create the
+necessary @file{Makefile} files that are later read by @command{make} to
+build the package.} files based on the hand-written configurations (in
address@hidden and the @file{Makefile.am} files). After running
address@hidden -f}, a warning about @code{TEXI2DVI} might show up, you
+can ignore that.
+
+The most important reason for re-building Gnuastro's build system is to
+generate/update the version number for your updated Gnuastro snapshot. This
+generated version number will include the commit information (see
address@hidden numbering}). The version number is included in nearly all
+outputs of Gnuastro's programs, therefore it is vital for reproducing an
+old result.
+
+As a summary, be sure to run address@hidden -f}' after every change
+in the Git history. This includes synchronization with the main server or
+even a commit you have made yourself.
+
 If you would like to see what has changed since you last synchronized your
 local clone, you can take the following steps instead of the simple command
 above (don't type anything after @code{#}):
@@ -5322,7 +5343,7 @@ $ git checkout master             # Confirm if you are on 
master.
 $ git fetch origin                # Fetch all new commits from server.
 $ git log master..origin/master   # See all the new commit messages.
 $ git merge origin/master         # Update your master branch.
-$ autoconf -f                     # Update ./configure.
+$ autoreconf -f                   # Update the build system.
 @end example
 
 @noindent
@@ -5331,19 +5352,17 @@ By default @command{git log} prints the most recent 
commit first, add the
 exactly what has been changed in the source code along with the commit
 message, add a @option{-p} option to the @command{git log}.
 
-If you intend make changes in the code, have a look at @ref{Developing} to
+If you want to make changes in the code, have a look at @ref{Developing} to
 get started easily. Be sure to commit your changes in a separate branch
 (keep your @code{master} branch to follow the official repository) and
-re-run @command{autoconf -f} after the commit. If you intend to send your
-changes to us (see @ref{Contributing to Gnuastro}) for the benefit of the
-whole community. If you send your work to us, you can safely use your
-commit since it will be ultimately recorded in Gnuastro's official
-history. If not, please upload your separate branch to a public hosting
-service, for example @url{https://gitlab.com, GitLab} (see @ref{Forking
-tutorial}), and link to it in your report. Alternatively, run @command{make
-distcheck} and upload the output @file{gnuastro-X.X.X.XXXX.tar.gz} to a
-publicly accessible webpage so your results can be considered scientific
-(reproducible).
+re-run @command{autoreconf -f} after the commit. If you intend to send your
+work to us, you can safely use your commit since it will be ultimately
+recorded in Gnuastro's official history. If not, please upload your
+separate branch to a public hosting service, for example
address@hidden://gitlab.com, GitLab}, and link to it in your
+report/paper. Alternatively, run @command{make distcheck} and upload the
+output @file{gnuastro-X.X.X.XXXX.tar.gz} to a publicly accessible webpage
+so your results can be considered scientific (reproducible) later.