[gnuastro-commits] master b2359ac: Book: added explanation for GAL_SPECLINES_INVALID_MAX of last commit

[Mohammad Akhlaghi]

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

    Book: added explanation for GAL_SPECLINES_INVALID_MAX of last commit
    
    In the previous commit, this new macro was defined in the `speclines.h'
    header (with an old name of `GAL_SPECLINES_NUMBER'), but I forgot to put a
    description for it in the book. Also, the old name could be misleading, or
    confusing (since its not the number of lines, its the number of lines, plus
    one).
    
    With this commit, the description is added in the book and also a line is
    added to the `NEWS' file, and the name is corrected to this new name which
    is more clear. An example usage has also been added in the book.
---
 NEWS                     |  1 +
 bin/cosmiccal/ui.c       |  2 +-
 doc/gnuastro.texi        | 17 ++++++++++++++---
 lib/gnuastro/speclines.h |  5 ++++-
 4 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/NEWS b/NEWS
index 3db946e..1bbf3e6 100644
--- a/NEWS
+++ b/NEWS
@@ -21,6 +21,7 @@ See the end of the file for license conditions.
    --notequal: Can now work on columns with string type also.
 
   Library:
+   - GAL_SPECLINES_INVALID_MAX: Total number of spectral lines, plus 1.
    - gal_txt_trim_space: trim white space before and after a string.
 
 ** Removed features
diff --git a/bin/cosmiccal/ui.c b/bin/cosmiccal/ui.c
index 665fa54..93c8bc0 100644
--- a/bin/cosmiccal/ui.c
+++ b/bin/cosmiccal/ui.c
@@ -426,7 +426,7 @@ ui_list_lines(struct cosmiccalparams *p)
   printf("# Column 2: Name       [name,  str10] Pre-defined line name.\n");
 
   /* Print the line information. */
-  for(i=1;i<GAL_SPECLINES_NUMBER;++i)
+  for(i=1;i<GAL_SPECLINES_INVALID_MAX;++i)
     printf("%-15g%s\n", gal_speclines_line_angstrom(i),
            gal_speclines_line_name(i));
 
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 2249976..31829cd 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -17245,7 +17245,8 @@ It can be one of the standard names below, or any 
rest-frame wavelength in Angst
 The second argument is the observed wavelength of that line.
 For example @option{--obsline=lyalpha,6000} is the same as 
@option{--obsline=1215.64,6000}.
 
-The accepted names are listed below, sorted from red (longer wavelength) to 
blue (shorter wavelength).
+The pre-defined names are listed below, sorted from red (longer wavelength) to 
blue (shorter wavelength).
+You can get this list on the command-line with the @option{--listlines}.
 
 @table @code
 @item siired
@@ -17470,9 +17471,10 @@ The comoving volume in Megaparsecs cube 
(Mpc@mymath{^3}) until the desired redsh
 @item -i STR/FLT
 @itemx --lineatz=STR/FLT
 The wavelength of the specified line at the redshift given to CosmicCalculator.
-The line can be specified either by its name (see description of 
@option{--obsline} in @ref{CosmicCalculator input options}), or directly as a 
number.
+The line can be specified either by its name or directly as a number (its 
wavelength).
+To get the list of pre-defined names for the lines and their wavelength, you 
can use the @option{--listlines} option, see @ref{CosmicCalculator input 
options}.
 In the former case (when a name is given), the returned number is in units of 
Angstroms.
-In the latter (when a number is given), the returned value is the same units 
of the input number.
+In the latter (when a number is given), the returned value is the same units 
of the input number (assuming its a wavelength).
 
 @end table
 
@@ -24646,8 +24648,17 @@ spectral lines. All these functions are declared in
 @deffnx Macro GAL_SPECLINES_HEIIBLUE
 @deffnx Macro GAL_SPECLINES_LYALPHA
 @deffnx Macro GAL_SPECLINES_LYLIMIT
+@deffnx Macro GAL_SPECLINES_INVALID_MAX
 Internal values/identifiers for specific spectral lines as is clear from
 their names.
+Note the first and last one, they can be used when parsing the lines 
automatically: both don't correspond to any line, but their integer values 
correspond to the two integers just before and after the first and last line 
identifier.
+
+@code{GAL_SPECLINES_INVALID} has a value of zero, and allows you to have a 
fixed integer which never corresponds to a line.
+@code{GAL_SPECLINES_INVALID_MAX} is the total number of pre-defined lines, 
plus one.
+So you can parse all the known lines with a @code{for} loop like this:
+@example
+for(i=1;i<GAL_SPECLINES_INVALID_MAX;++i)
+@end example
 @end deffn
 
 @deffn  Macro GAL_SPECLINES_ANGSTROM_SIIRED
diff --git a/lib/gnuastro/speclines.h b/lib/gnuastro/speclines.h
index 9d52b15..370db1a 100644
--- a/lib/gnuastro/speclines.h
+++ b/lib/gnuastro/speclines.h
@@ -49,7 +49,10 @@ __BEGIN_C_DECLS  /* From C++ preparations */
 /* Spectral line internal codes (SORT BY WAVELENGTH). */
 enum gal_speclines_line_codes
 {
+  /* Allowing `0' to be identied as a known-non-line. */
   GAL_SPECLINES_INVALID=0,
+
+  /* Main list of recognized lines. */
   GAL_SPECLINES_SIIRED,
   GAL_SPECLINES_SII,
   GAL_SPECLINES_SIIBLUE,
@@ -82,7 +85,7 @@ enum gal_speclines_line_codes
 
   /* This should be the last element (to keep the total number of
      lines). */
-  GAL_SPECLINES_NUMBER,
+  GAL_SPECLINES_INVALID_MAX,
 };