[gnuastro-commits] master de80e97 046/125: Further explanations on Gnuastro's plain text tables

[Mohammad Akhlaghi]

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

    Further explanations on Gnuastro's plain text tables
    
    Some further explanation was added to the `Gnuastro text table format'
    section to make it better understandable. In particular on these aspects:
    
     - I had forgot to include the `unsigned int' and `unsigned long' types
       that Gnuastro can accept, but the FITS tables don't recognize. So a note
       was added after the list to explain this. An explanation was also added
       on FITS ASCII tables and how they only have one integer type.
    
     - The `strN' type also needed further explanation and an example to be
       more clear and for how to deal with trailing or leading white space if
       they are important.
---
 doc/gnuastro.texi | 54 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 45 insertions(+), 9 deletions(-)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 3487e71..71bdda5 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -5228,8 +5228,9 @@ Except for the column number (@code{N}), the rest of the 
fields are not
 mandatory and the column information doesn't have to be in order. Also, you
 don't have to specify information for all columns. Those without
 information will be interpretted with the default settings (like the case
-above: all types are double, with no name, units, or comments) So these
-lines are all acceptable:
+above: all types are double, with no name, units, or comments). So these
+lines are all acceptable (the first one with nothing but the column number
+is redundant!):
 
 @example
 # Column 5:
@@ -5237,7 +5238,7 @@ lines are all acceptable:
 # Column 3: mag_f160w [AB mag, f] Magnitude from the F160W filter
 @end example
 
-The following type codes are recognized:
+The following type codes are recognized in Gnuastro's plain text tables:
 
 @itemize
 @item
@@ -5249,8 +5250,12 @@ The following type codes are recognized:
 @item
 address@hidden': for (signed) @code{short}.
 @item
address@hidden': for @code{unsigned int} (see note below).
address@hidden
 address@hidden': for (signed) @code{int}.
 @item
address@hidden': for @code{unsigned long} (see note below).
address@hidden
 address@hidden': for (signed) @code{long}.
 @item
 address@hidden': for @code{long long}.
@@ -5259,18 +5264,49 @@ The following type codes are recognized:
 @item
 address@hidden': for @code{double}.
 @item
address@hidden': for strings. The @code{N} value identifies how many
-characters define for the string. The start of the string on each row is
address@hidden': for strings. The @code{N} value identifies the length of the
+string (how many characters it has). The start of the string on each row is
 the first non-delimiter character of the column that has the string
 type. The next @code{N} characters will be interpretted as a string and all
-trailing white space will be removed. So only if strings are present in the
-table you have to be careful that a the next column is not too close. If
+trailing white space will be removed. If there is a new-line character (the
+string character is the last column, or we have reached the end of the
+line), then reading of the string will stop, even if the @code{N}
+characters are not complete yet. See @file{tests/table/table.txt} for one
+example.
+
+So the only time you have to pay attention to the positioning of the
+columns is when you have a string column immediately before another one. If
 the next column's characters, are closer than @code{N} characters, they
-will be considered part of the string. See @file{tests/table/table.txt} for
-one example.
+will be considered part of the string.
+
+The only limitation in this format is that trailing and leading white space
+characters will be removed from the columns that are read. So if trailing
+and leading white-spaces are critically important to your analysis, define
+your own starting and ending characters and remove them after the table has
+been read. For example in the sample table below, the two address@hidden|}'
+characters (which are arbitrary) will remain in the value of the second
+column and you can remove them manually later. If only one of the leading
+or trailing white spaces is important for your work, you can only use one
+of the address@hidden|}'s.
+
address@hidden
+# Column 1: ID [label, uc]
+# Column 2: Notes [no unit, str50]
+1    leading and trailing white space is ignored here    2.3442e10
+2   |         but they will be preserved here        |   2.3442e10
address@hidden example
 
 @end itemize
 
+Note that the FITS standard does not define the @code{unsigned int} and
address@hidden long} types for its binary tables, so if you want to convert
+your tables to FITS binary tables, use other types. Also, note that in the
+FITS ASCII table, there is only one integer type (@code{long}). So if you
+convert a Gnuastro plain text table a FITS ASCII table with the @ref{Table}
+program, the type information for integers will be lost. Conversely if
+integer types are important for you, you have to manually set them when
+reading a FITS ASCII table, for example with the Table program into a file,
+or with the @file{gnuastro/table.h} library functions into memory.