[gnuastro-commits] master 56f8c18 071/125: Cosmetic changes in option printing style

[Mohammad Akhlaghi]

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

    Cosmetic changes in option printing style
    
    While finalizing the work on MakeProfiles, the style of printing option
    printing style slightly changed to be more readable/useful. In particular,
    when an option's `doc' string is longer than 80 characters, it is now
    broken into multiple lines, similar to what `--help' does.
    
    Because the `doc' strings can be broken into multiple lines, it is now
    necessary to start the `doc' string with a `#', otherwise the first word of
    the new line would be read as an option name, and the second as its value.
    
    Also, thanks to the new features of Arithmetic (in particular `where'), the
    old `inputascanvas' option was no longer necessary. If a user doesn't want
    the pixel values, they can use it. The strategies are now described in the
    book under the `--background' option.
---
 bin/mkprof/args.h |  39 +++++++--------------
 doc/gnuastro.texi | 100 ++++++++++++++++++++++++++++--------------------------
 lib/options.c     |  56 +++++++++++++++++++++++++++---
 3 files changed, 116 insertions(+), 79 deletions(-)

diff --git a/bin/mkprof/args.h b/bin/mkprof/args.h
index 8d5bbbd..3d85351 100644
--- a/bin/mkprof/args.h
+++ b/bin/mkprof/args.h
@@ -88,19 +88,6 @@ struct argp_option program_options[] =
       GAL_OPTIONS_NOT_SET
     },
     {
-      "inputascanvas",
-      ARGS_OPTION_KEY_INPUTASCANVAS,
-      0,
-      0,
-      "Use input image for output size and WCS.",
-      GAL_OPTIONS_GROUP_OUTPUT,
-      &p->inputascanvas,
-      GAL_OPTIONS_NO_ARG_TYPE,
-      GAL_OPTIONS_RANGE_0_OR_1,
-      GAL_OPTIONS_NOT_MANDATORY,
-      GAL_OPTIONS_NOT_SET
-    },
-    {
       "oversample",
       ARGS_OPTION_KEY_OVERSAMPLE,
       "INT",
@@ -325,13 +312,13 @@ struct argp_option program_options[] =
 
     {
       0, 0, 0, 0,
-      "Columns by info (see `--searchin') or number (starting from 1):",
+      "Columns, by info (see `--searchin'), or number (starting from 1):",
       ARGS_GROUP_CATALOG
     },
     {
       "xcol",
       ARGS_OPTION_KEY_XCOL,
-      "INT/STR",
+      "STR/INT",
       0,
       "Center along first FITS axis (horizontal).",
       ARGS_GROUP_CATALOG,
@@ -344,7 +331,7 @@ struct argp_option program_options[] =
     {
       "ycol",
       ARGS_OPTION_KEY_YCOL,
-      "INT/STR",
+      "STR/INT",
       0,
       "Center along second FITS axis (vertical).",
       ARGS_GROUP_CATALOG,
@@ -357,7 +344,7 @@ struct argp_option program_options[] =
     {
       "racol",
       ARGS_OPTION_KEY_RACOL,
-      "INT/STR",
+      "STR/INT",
       0,
       "Center right ascension.",
       ARGS_GROUP_CATALOG,
@@ -370,7 +357,7 @@ struct argp_option program_options[] =
     {
       "deccol",
       ARGS_OPTION_KEY_DECCOL,
-      "INT/STR",
+      "STR/INT",
       0,
       "Center declination.",
       ARGS_GROUP_CATALOG,
@@ -383,9 +370,9 @@ struct argp_option program_options[] =
     {
       "fcol",
       ARGS_OPTION_KEY_FCOL,
-      "INT/STR",
+      "STR/INT",
       0,
-      "Sersic (0), Moffat (1), Gaussian (2), Point (3),\n"
+      "Sersic (0), Moffat (1), Gaussian (2), Point (3), "
       "Flat (4), Circumference (5).",
       ARGS_GROUP_CATALOG,
       &p->fcol,
@@ -397,7 +384,7 @@ struct argp_option program_options[] =
     {
       "rcol",
       ARGS_OPTION_KEY_RCOL,
-      "INT/STR",
+      "STR/INT",
       0,
       "Effective radius or FWHM in pixels.",
       ARGS_GROUP_CATALOG,
@@ -410,7 +397,7 @@ struct argp_option program_options[] =
     {
       "ncol",
       ARGS_OPTION_KEY_NCOL,
-      "INT/STR",
+      "STR/INT",
       0,
       "Sersic index or Moffat beta.",
       ARGS_GROUP_CATALOG,
@@ -423,7 +410,7 @@ struct argp_option program_options[] =
     {
       "pcol",
       ARGS_OPTION_KEY_PCOL,
-      "INT/STR",
+      "STR/INT",
       0,
       "Position angle.",
       ARGS_GROUP_CATALOG,
@@ -436,7 +423,7 @@ struct argp_option program_options[] =
     {
       "qcol",
       ARGS_OPTION_KEY_QCOL,
-      "INT/STR",
+      "STR/INT",
       0,
       "Axis ratio.",
       ARGS_GROUP_CATALOG,
@@ -449,7 +436,7 @@ struct argp_option program_options[] =
     {
       "mcol",
       ARGS_OPTION_KEY_MCOL,
-      "INT/STR",
+      "STR/INT",
       0,
       "Magnitude.",
       ARGS_GROUP_CATALOG,
@@ -462,7 +449,7 @@ struct argp_option program_options[] =
     {
       "tcol",
       ARGS_OPTION_KEY_TCOL,
-      "INT/STR",
+      "STR/INT",
       0,
       "Truncation in units of --rcol, unless --tunitinp.",
       ARGS_GROUP_CATALOG,
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index f226da1..0374b33 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -13811,18 +13811,39 @@ Output:
 @table @option
 
 @item -k STR
address@hidden --background=STR
-A background image FITS file to build the profiles on, the extension that
address@hidden --background=STR
+A background image FITS file to build the profiles on. The extension that
 contains the image should be specified with the @option{--backhdu} option,
-see below. If this option is called, the profiles will be created on the
-background image specified and the @option{--naxis1} and @option{--naxis2}
-options will be ignored. If the image has WCS information, that information
-will also be used and the WCS related options (@option{--crpix1},
address@hidden, @option{--crval1}, @option{--crval2}, and
address@hidden) will also be ignored.
+see below. When a background image is specified, it will be used to derive
+all the information about the output image. Hence, the following options
+will be ignored: @option{--naxis1}, @option{--naxis2}, @option{--crpix1},
address@hidden, @option{--crval1}, @option{--crval2},
address@hidden, @option{--oversample}, and @option{--type}.
+
+The profiles will be built on the image (profile pixel values will be
+summed with the background image pixel values). If you want to use all the
+image information above, except for the pixel values (you want to have a
+blank canvas to build the profiles on, based on an input image), you can
+use @ref{Arithmetic} as below and feed the output into MakeProfiles with
+this option.
+
address@hidden
+$ astarithmetic img.fits 0 "*" --output=bz.fits
address@hidden example
+
+The command above will also preserve all the (possible) blank pixels in the
+image (see @ref{Blank pixels}). In case the input image has blank pixels
+and you want them to be zero too, you can do so with the following command
+(both Arithmetic operations can also be merged into one command, see
address@hidden polish notation}, recall that @option{-o} is the short version
+of @option{--output}, see @ref{Options}):
+
address@hidden
+$ astarithmetic bz.fits bz.fits isblank 0 where -oz.fits
address@hidden example
 
 @item -B STR/INT
address@hidden --backhdu=STR/INT
address@hidden --backhdu=STR/INT
 The header data unit (HDU) of the file given to
 
 @item -x INT
@@ -13842,36 +13863,17 @@ The number of pixels in the output image along the 
second FITS axis
 
 @item -T STR
 @itemx --type=STR
-Type of the output image pixels (specified by @code{BITPIX} in the FITS
-standard). It can have any one of the following values: @option{byte},
address@hidden, @option{long}, @option{longlong}, @option{float},
address@hidden Internally, the images are made in the float type, but
-upon writing of the single output (not individual profiles), the image will
-be converted to the type specified by this option.
-
-When a background image is given without the @option{--inputascanvas}
-option, it is assumed that you want the output in the same format as the
-background, therefore the value to this option is ignored.
+Data type of the output image pixels (specified by @code{BITPIX} in the
+FITS standard, see @ref{Data types}). It can have any one of the following
+values: @option{byte}, @option{short}, @option{long}, @option{longlong},
address@hidden, @option{double}. Internally, the images are made in the
+float type, but upon writing of the single output (not individual
+profiles), the image will be converted to the type specified by this
+option.
 
address@hidden -C
address@hidden --inputascanvas
-When an image is given as an argument, use the input image as the canvas to
-make all the mock profiles. In practice, this option only changes the
-non-blank pixels (see @ref{Blank pixels}) of the input image (in memory
-after reading, not the actual input file) to zero before making the
-profiles. The profiles are then built on those cleared pixels. With this
-option (like when building on a background image) the values to
address@hidden, @option{--naxis2}, @option{--crpix1}, @option{--crpix2},
address@hidden, @option{--crval2}, and @option{--resolution} are
-ignored. However, if @option{--type} is given, its value will take
-precedence over the background image type.
-
-This option can be very useful when the mock image is to be made over a
-real sky region and compared to a real image (that might have blank
-pixels. One example can be when you want to make circular or elliptical
-labeled regions to feed into MakeCatalog along with NoiseChisel's outputs
-for aperture photometry. See the discussion and examples under the
address@hidden' for more.
+When a background image is given without the @option{--backascanvas}
+option, it is assumed that you want the output with the same data type as
+the background, therefore the value to this option is ignored.
 
 @item -s INT
 @itemx --oversample=INT
@@ -14053,7 +14055,7 @@ column number, where counting starts from zero.
 
 @table @option
 
address@hidden --fcol=INT
address@hidden --fcol=INT/STR
 The functional form of the profile with one of the values below. Note that
 this value will be converted to an integer before analysis using the
 internal type conversion of C. So for example 2.80 will be converted to 2.
@@ -14076,16 +14078,16 @@ to the @option{--circumwidth}. Currently this is only 
intended to be
 used for making an elliptical annulus (with a width of 1 or 2 pixels).
 @end itemize
 
address@hidden --xcol=INT
address@hidden --xcol=STR/INT
 The center of the profiles along the first FITS axis (horizontal when
 viewed in SAO ds9). See the explanations for @option{--racol} for
 precedence when both image and WCS coordinate columns are given.
 
address@hidden --ycol=INT
address@hidden --ycol=STR/INT
 The center of the profiles along the second FITS axis (vertical when viewed
 in SAO ds9). Similar to @option{--xcol}.
 
address@hidden --racol=INT
address@hidden --racol=STR/INT
 The profile center's right ascension. Along with @option{--deccol}, these
 WCS coordinate columns are not mandatory. If they are not given, the
 @option{--xcol} and @option{--ycol} options will be used to specify the
@@ -14094,28 +14096,28 @@ columns (@option{--xcol} and @option{--ycol}) and WCS 
coordinate columns
 (@option{--racol} and @option{--deccol}) are given, the WCS coordinate
 columns take precedence and image coordinate columns will be ignored.
 
address@hidden --deccol=INT
address@hidden --deccol=STR/INT
 The profile center's declination. Similar to @option{--racol}.
 
address@hidden --rcol=INT
address@hidden --rcol=STR/INT
 The radius parameter of the profiles. Effective radius (@mymath{r_e}) if
 S@'ersic, FWHM if Moffat or Gaussian.
 
address@hidden --ncol=INT
address@hidden --ncol=STR/INT
 The S@'ersic index (@mymath{n}) or Moffat @mymath{\beta}.
 
address@hidden --pcol=INT
address@hidden --pcol=STR/INT
 The position angle (in degrees) of the profiles relative to the first FITS
 axis (horizontal when viewed in SAO ds9).
 
address@hidden --qcol=INT
address@hidden --qcol=STR/INT
 The axis ratio of the profiles (minor axis divided by the major axis).
 
address@hidden --mcol=INT
address@hidden --mcol=STR/INT
 The total pixelated magnitude of the profile within the truncation radius,
 see @ref{Profile magnitude}.
 
address@hidden --tcol=INT
address@hidden --tcol=STR/INT
 The truncation radius of this profile. By default it is in units of the
 radial parameter of the profile (the value in the @option{--rcol} of the
 catalog). If @option{--tunitinp} is given, this value is interpreted in
diff --git a/lib/options.c b/lib/options.c
index fea33d5..0bb7404 100644
--- a/lib/options.c
+++ b/lib/options.c
@@ -1177,6 +1177,50 @@ options_set_lengths(struct argp_option *poptions,
 
 
 
+/* The `#' before the `doc' string are not required by the configuration
+   file parser when the documentation string fits in a line. However, when
+   the `doc' string is longer than 80 characters, it will be cut between
+   multiple lines and without the `#', the start of the line will be read
+   as an option. */
+static void
+options_print_doc(FILE *fp, char *doc, int nvwidth)
+{
+  size_t len=strlen(doc);
+
+  /* The `+3' is because of the three extra spaces in this line: one before
+     the variable name, one after it and one after the value. */
+  int i, prewidth=nvwidth+3, width=78-prewidth, cwidth;
+
+  /* We only want the formatting when writing to stdout. */
+  if(len<width)
+    fprintf(fp, "# %s\n", doc);
+  else
+    {
+      /* If the break is in the middle of a word, then pull set it before
+         the word starts.*/
+      cwidth=width; while( doc[cwidth]!=' ' ) --cwidth;
+      fprintf(fp, "# %.*s\n", cwidth, doc);
+      i=cwidth;
+
+      /* Go over the rest of the line */
+      while(i<len)
+        {
+          /* Remove any possible space before the first word. */
+          while( doc[i]==' ' ) ++i;
+
+          /* Check if the line break won't fall in the middle of a word. */
+          cwidth=width;
+          if( i+cwidth<len) while( doc[i+cwidth]!=' ' ) --cwidth;
+          fprintf(fp, "%*s# %.*s\n", prewidth, "", cwidth, &doc[i]);
+          i+=cwidth;
+        }
+    }
+}
+
+
+
+
+
 static void
 options_print_all_in_group(struct argp_option *options, int groupint,
                            int namelen, int valuelen, FILE *fp)
@@ -1199,7 +1243,7 @@ options_print_all_in_group(struct argp_option *options, 
int groupint,
               fprintf(fp, " %-*s ", namewidth, options[i].name);
               options_print_any_type(&tmp->v, GAL_DATA_TYPE_STRING,
                                      valuewidth, fp);
-              fprintf(fp, "(%s\b)\n", options[i].doc);
+              options_print_doc(fp, options[i].doc, namewidth+valuewidth);
             }
 
         /* Normal types. */
@@ -1208,7 +1252,7 @@ options_print_all_in_group(struct argp_option *options, 
int groupint,
             fprintf(fp, " %-*s ", namewidth, options[i].name);
             options_print_any_type(options[i].value, options[i].type,
                                    valuewidth, fp);
-            fprintf(fp, "(%s\b)\n", options[i].doc);
+            options_print_doc(fp, options[i].doc, namewidth+valuewidth);
           }
       }
 }
@@ -1252,7 +1296,8 @@ options_print_all(struct gal_options_common_params *cp, 
char *dirname,
 
       /* Print the basic information as comments in the file first. */
       time(&rawtime);
-      fprintf(fp, "# Configuration file produced by for %s (%s) %s.\n"
+      fprintf(fp,
+              "# %s (%s) %s.\n"
               "# Written at %s#\n"
               "#  - Empty lines are ignored.\n"
               "#  - Lines starting with `#` are ignored.\n"
@@ -1306,6 +1351,9 @@ options_print_all(struct gal_options_common_params *cp, 
char *dirname,
 
       /* First print the topic, */
       fprintf(fp, "\n# %s\n", topicstr);
+      fprintf(fp, "# ");
+      i=0; while(i++<strlen(topicstr)) fprintf(fp, "%c", '-');
+      fprintf(fp, "\n");
 
       /* Then, print all the options that are in this group. */
       options_print_all_in_group(coptions, groupint, namelen, valuelen, fp);
@@ -1315,7 +1363,7 @@ options_print_all(struct gal_options_common_params *cp, 
char *dirname,
   /* Let the user know. */
   if(dirname)
     {
-      printf("\n%s: new/updated configuration file.\n\n"
+      printf("\nNew/updated configuration file:\n\n  %s\n\n"
              "You may inspect it with `cat %s'.\n"
              "You may use your favorite text editor to modify it later.\n"
              "Or, run %s again with new values for the options and `--%s'.\n",