[gnuastro-commits] master 61e44ed: Fits program and library: better explanation on HDU contents

[Mohammad Akhlaghi]

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

    Fits program and library: better explanation on HDU contents
    
    Until now, when a HDU didn't have a name, we would just print 'n/a'
    (not-applicable) for the name column when the Fits program was run on the
    file. But this could be confusing for some, leading them to think that
    'n/a' is the actual HDU name.
    
    With this commit, when a HDU doesn't have a name, after the column
    description, another line is printed, explicity mentioning that 'n/a' means
    that there is no name. This doesn't happen for FITS files where all
    extensions have a name.
    
    Also, the error message that came when the data is the pimary HDU has been
    modified to be more clear about the problem. We recently found out that it
    could be interpretted as "the FITS file has problems", while that was not
    the point.
---
 bin/fits/fits.c |  5 +++++
 lib/fits.c      | 40 ++++++++++++++++++++++++----------------
 2 files changed, 29 insertions(+), 16 deletions(-)

diff --git a/bin/fits/fits.c b/bin/fits/fits.c
index 466cbd5..9483355 100644
--- a/bin/fits/fits.c
+++ b/bin/fits/fits.c
@@ -86,6 +86,7 @@ fits_print_extension_info(struct fitsparams *p)
 {
   uint16_t *ui16;
   fitsfile *fptr;
+  int hasblankname=0;
   gal_data_t *cols=NULL, *tmp;
   char **tstra, **estra, **sstra;
   size_t i, numext, *dsize, ndim;
@@ -169,6 +170,7 @@ fits_print_extension_info(struct fitsparams *p)
 
         case KEY_NO_EXIST:
           sprintf(extname, "%s", GAL_BLANK_STRING);
+          hasblankname=1;
           status=0;
           break;
 
@@ -234,6 +236,9 @@ fits_print_extension_info(struct fitsparams *p)
       printf(" Column 1: Index (counting from 0, usable with '--hdu').\n");
       printf(" Column 2: Name ('EXTNAME' in FITS standard, usable with "
              "'--hdu').\n");
+      if(hasblankname)
+        printf("           ('%s' means that no name is specified for this "
+               "HDU)\n", GAL_BLANK_STRING);
       printf(" Column 3: Image data type or 'table' format (ASCII or "
              "binary).\n");
       printf(" Column 4: Size of data in HDU.\n");
diff --git a/lib/fits.c b/lib/fits.c
index e76ff66..819119b 100644
--- a/lib/fits.c
+++ b/lib/fits.c
@@ -706,23 +706,31 @@ gal_fits_hdu_open(char *filename, char *hdu, int iomode)
            notice. */
         case END_OF_FILE:
           if( hdu[0]=='1' && hdu[1]=='\0' )
-            error(EXIT_FAILURE, 0, "%s has only one extension/HDU but you "
-                  "have asked for the second HDU (hdu number 1 in CFITSIO)."
-                  "\n\n"
-                  "To fix the problem please add '--hdu=0' (or '-h0') to "
-                  "your command when calling Gnuastro's programs. For "
-                  "library users, please give a value of '0' to the HDU "
-                  "argument.\n\n"
+            error(EXIT_FAILURE, 0, "%s: only has one HDU.\n\n"
+                  "You should tell Gnuastro's command-line "
+                  "programs to look for data in the primary HDU with the "
+                  "'--hdu=0' option (or '-h0'). For library users, you can "
+                  "put \"0\" (a string literal) for the function's HDU "
+                  "argument. For more, see the FOOTNOTE below.\n\n"
+                  "Pro TIP: if your desired HDU has a name (value to "
+                  "'EXTNAME' keyword), it is best to just use that name "
+                  "with '--hdu' instead of relying on a counter. You can "
+                  "see the list of HDUs in a FITS file (with their data "
+                  "format, type, size and possibly HDU name) using "
+                  "Gnuastro's 'astfits' program, for example:\n\n"
+                  "    astfits %s\n\n"
                   "FOOTNOTE -- When writing a new FITS file, Gnuastro leaves "
-                  "the first HDU blank (with no data) and writes the "
-                  "outputs in the second HDU. In this way the keywords of "
-                  "the the first HDU can be used as meta data of the whole "
-                  "file (which may contain many extensions). This is the "
-                  "recommended way in the FITS standard. As a result, "
-                  "Gnuastro's default HDU to read an extension in a FITS "
-                  "file is the second. This error is commonly caused when "
-                  "the FITS file wasn't created according to this "
-                  "convention.", filename);
+                  "the pimary HDU only for metadata. The output datasets "
+                  "(tables, images or cubes) are written after the primary "
+                  "HDU. In this way the keywords of the the first HDU can be "
+                  "used as metadata of the whole file (which may contain many "
+                  "extensions, this is stipulated in the FITS standard). "
+                  "Usually the primary HDU keywords contains the option names "
+                  "and values that the program was run with. Because of this, "
+                  "Gnuastro's default HDU to read data in a FITS file is the "
+                  "second (or '--hdu=1'). This error is commonly caused when "
+                  "the FITS file wasn't created by Gnuastro or by a program "
+                  "respecting this convention.", filename, filename);
           break;
 
         /* Generic error below is fine for this case */