[groff] 08/10: addftinfo: Improve diagnostics and man page.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 2a4c8d7475f61f9056c0a25b5ae68843e3c7fbe7
Author: G. Branden Robinson <address@hidden>
AuthorDate: Wed Apr 29 00:33:49 2020 +1000

    addftinfo: Improve diagnostics and man page.
    
    * src/utils/addftinfo/addftinfo.cpp (usage): Add overloaded version that
      accepts a constant string argument, which emits the argument as a
      diagnostic and then calls usage().
    
      (main): Add diagnostics to usage message where the problem is clear.
      Add comment explaining why it sometimes isn't.
    
      (usage): Refactor main usage message (which prints the summary) to
      report the actual names of the accepted option arguments instead of
      just "-param", which is not literally accepted.
    
      Sort param_table alphabetically for use by the usage message.
    
      Tidy up long lines and whitespace.
    
      Tested with:
        addftinfo -1 -2 /dev/null
        addftinfo -asc-height 1 -body-depth 2 3
        addftinfo -asc-height 1 -body-depth 2 3 4
        addftinfo -asc-height 1 -body-depth 2 3 4 /dev/null
        addftinfo /dev/null
        addftinfo 1
        addftinfo 1 -2 /dev/null
        addftinfo 1 /dev/null
        addftinfo 1 2 /dev/null
        addftinfo 1 2 3
    
    * src/utils/addftinfo/addftinfo.1.man: Condense summary.
    
      Delete unused string definition for ellipsis.
    
      Use English words and phrases for parameter names.
    
      Document --help and --version.
    
      Sort option list alphabetically.
    
      Make minor clarifications.
    
      Save and restore compatibility mode since we now use groff extensions
      (\~ and \[]-form character escapes).
---
 ChangeLog                           |  30 ++++++++-
 src/utils/addftinfo/addftinfo.1.man | 131 +++++++++++++++++++++---------------
 src/utils/addftinfo/addftinfo.cpp   |  58 ++++++++++------
 3 files changed, 141 insertions(+), 78 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 7d5e032..ff121c1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,30 @@
+2020-04-29  G. Branden Robinson <address@hidden>
+
+       * src/utils/addftinfo/addftinfo.cpp (usage): Add overloaded
+       version that accepts a constant string argument, which emits the
+       argument as a diagnostic and then calls usage().
+       (main): Add diagnostics to usage message where the problem is
+       clear.  Add comment explaining why it sometimes isn't.
+       (usage): Refactor main usage message (which prints the summary)
+       to report the actual names of the accepted option arguments
+       instead of just "-param", which is not literally accepted.
+
+       Sort param_table alphabetically for use by the usage message.
+
+       Tidy up long lines and whitespace.
+
+       Tested with:
+               addftinfo -1 -2 /dev/null
+               addftinfo -asc-height 1 -body-depth 2 3
+               addftinfo -asc-height 1 -body-depth 2 3 4
+               addftinfo -asc-height 1 -body-depth 2 3 4 /dev/null
+               addftinfo /dev/null
+               addftinfo 1
+               addftinfo 1 -2 /dev/null
+               addftinfo 1 /dev/null
+               addftinfo 1 2 /dev/null
+               addftinfo 1 2 3
+
 2020-04-22  G. Branden Robinson <address@hidden>
 
        Delete groffer.
@@ -6193,7 +6220,8 @@ notice and this notice are preserved.
 
 ##### Editor settings
 Local Variables:
+fill-column: 72
 mode: change-log
 version-control: never
 End:
-vim:set autoindent:
+vim:set autoindent textwidth=72:
diff --git a/src/utils/addftinfo/addftinfo.1.man 
b/src/utils/addftinfo/addftinfo.1.man
index dac73cf..04c5b1e 100644
--- a/src/utils/addftinfo/addftinfo.1.man
+++ b/src/utils/addftinfo/addftinfo.1.man
@@ -1,6 +1,11 @@
 .TH addftinfo @MAN1EXT@ "@MDATE@" "groff @VERSION@"
 .SH Name
-addftinfo \- add information to troff font files for use with groff
+addftinfo \- add font metrics to troff fonts for use with groff
+.
+.
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr *groff_addftinfo_1_man_C \n[.cp]
+.cp 0
 .
 .
 .\" ====================================================================
@@ -26,16 +31,6 @@ addftinfo \- add information to troff font files for use 
with groff
 .
 .
 .\" ====================================================================
-.\" Characters
-.\" ====================================================================
-.
-.\" Ellipsis ...
-.ie t .ds EL \fS\N'188'\fP\"
-.el .ds EL \&.\|.\|.\&\"
-.\" called with \*(EL
-.
-.
-.\" ====================================================================
 .SH Synopsis
 .\" ====================================================================
 .
@@ -48,8 +43,8 @@ addftinfo \- add information to troff font files for use with 
groff
 .OP \-desc\-depth n
 .OP \-fig\-height n
 .OP \-x\-height n
-.I res
-.I unitwidth
+.I resolution
+.I unit-width
 .I font
 .YS
 .
@@ -68,107 +63,131 @@ addftinfo \- add information to troff font files for use 
with groff
 .SH Description
 .\" ====================================================================
 .
-.B addftinfo
-reads a troff font file and adds some additional font-metric
-information that is used by the groff system.
+.I addftinfo
+reads an
+.RI AT&T \~troff
+font file
+.IR font ,
+adds additional font metric information required by
+.IR groff ,
+and writes the combined result to the standard output.
 .
-The font file with the information added is written on the standard
-output.
+The information added is guessed using some parametric information about
+the font and assumptions about the traditional
+.I troff
+names for characters.
 .
-The information added is guessed using some parametric information
-about the font and assumptions about the traditional troff names for
-characters.
-.
-The main information added is the heights and depths of characters.
+Among the font metrics added are the heights and depths of characters
+(how far each extends vertically above and below the baseline).
 .
 The
-.I res
+.I resolution
 and
-.I unitwidth
+.I unit-width
 arguments should be the same as the corresponding parameters in the
-DESC file;
+.I DESC
+file.
+.
 .I font
 is the name of the file describing the font;
 if
 .I font
 ends with
-.B I
-the font will be assumed to be italic.
+.RB \[lq] I \[rq],
+the font is assumed to be italic.
 .
 .
 .\" ====================================================================
 .SH Options
 .\" ====================================================================
 .
+.B \-\-help
+displays a usage message,
+while
 .B \-v
-prints the version number.
+and
+.B \-\-version
+show version information;
+all exit afterward.
 .
 .
 .LP
 All other options change one of the parameters that are used to derive
 the heights and depths.
 .
-Like the existing quantities in the font file, each
+Like the existing quantities in the font file,
+each
 .I value
 is in
-.RI inches/ res
+.RI inches/ resolution
 for a font whose point size is
-.IR unitwidth .
+.IR unit-width .
 .
-.I param-option
-must be one of:
 .
 .TP
-.B \-x\-height
-The height of lowercase letters without ascenders such as x.
+.BI \-asc\-height \~n
+The height of characters with ascenders,
+such as \[lq]b\[rq], \[lq]d\[rq], or \[lq]l\[rq].
 .
-.TP
-.B \-fig\-height
-The height of figures (digits).
 .
 .TP
-.B \-asc\-height
-The height of characters with ascenders, such as b, d or l.
+.BI \-body\-depth \~n
+The depth of characters such as parentheses.
+.
 .
 .TP
-.B \-body\-height
+.BI \-body\-height \~n
 The height of characters such as parentheses.
 .
+.
 .TP
-.B \-cap\-height
-The height of uppercase letters such as A.
+.BI \-cap\-height \~n
+The height of uppercase letters such as \[lq]A\[rq].
+.
 .
 .TP
-.B \-comma\-depth
+.BI \-comma\-depth \~n
 The depth of a comma.
 .
+.
 .TP
-.B \-desc\-depth
-The depth of characters with descenders, such as p, q, or y.
+.BI \-desc\-depth \~n
+The depth of characters with descenders,
+such as \[lq]p\[rq], \[lq]q\[rq], or \[lq]y\[rq].
+.
 .
 .TP
-.B \-body\-depth
-The depth of characters such as parentheses.
+.B \-fig\-height
+The height of figures (digits, numerals).
+.
+.
+.TP
+.BI \-x\-height \~n
+The height of lowercase letters without ascenders such as \[lq]x\[rq].
 .
 .
 .LP
-.B addftinfo
+.I addftinfo
 makes no attempt to use the specified parameters to guess the
 unspecified parameters.
 .
-If a parameter is not specified the default will be used.
+If a parameter is not specified,
+the default will be used.
 .
-The defaults are chosen to have the reasonable values for a Times
-font.
+The defaults are chosen to have reasonable values for a Times font.
 .
 .
 .\" ====================================================================
 .SH "See Also"
 .\" ====================================================================
 .
-.BR groff_font (@MAN5EXT@),
-.BR groff (@MAN1EXT@),
-.BR groff_char (@MAN7EXT@)
+.IR groff_font (@MAN5EXT@),
+.IR groff (@MAN1EXT@),
+.IR groff_char (@MAN7EXT@)
+.
+.
+.\" Restore compatibility mode (for, e.g., Solaris 10/11).
+.cp \n[*groff_addftinfo_1_man_C]
 .
 .
 .\" Local Variables:
diff --git a/src/utils/addftinfo/addftinfo.cpp 
b/src/utils/addftinfo/addftinfo.cpp
index 4211c59..7e63b9d 100644
--- a/src/utils/addftinfo/addftinfo.cpp
+++ b/src/utils/addftinfo/addftinfo.cpp
@@ -33,6 +33,7 @@ extern "C" const char *Version_string;
 
 static void usage(FILE *stream);
 static void usage();
+static void usage(const char *problem);
 static void version();
 static void convert_font(const font_params &, FILE *, FILE *);
 
@@ -42,14 +43,14 @@ static struct {
   const char *name;
   param_t par;
 } param_table[] = {
-  { "x-height", &font_params::x_height },
-  { "fig-height", &font_params::fig_height },
   { "asc-height", &font_params::asc_height },
+  { "body-depth", &font_params::body_depth },
   { "body-height", &font_params::body_height },
   { "cap-height", &font_params::cap_height },
   { "comma-depth", &font_params::comma_depth },
   { "desc-depth", &font_params::desc_depth },
-  { "body-depth", &font_params::body_depth },
+  { "fig-height", &font_params::fig_height },
+  { "x-height", &font_params::x_height },
 };
 
 // These are all in thousandths of an em.
@@ -77,17 +78,20 @@ int main(int argc, char **argv)
     }
   }
   if (argc < 4)
-    usage();
+    usage("insufficient arguments");
+  /* The next couple of usage() calls cannot provide a meaningful
+     diagnostic because we don't know whether sscanf() failed on a
+     required parameter or an option.  A refactor could fix this. */
   int resolution;
   if (sscanf(argv[argc-3], "%d", &resolution) != 1)
     usage();
   if (resolution <= 0)
-    fatal("resolution must be > 0");
+    fatal("resolution must be positive");
   int unitwidth;
   if (sscanf(argv[argc-2], "%d", &unitwidth) != 1)
     usage();
   if (unitwidth <= 0)
-    fatal("unitwidth must be > 0");
+    fatal("unit width must be positive");
   font_params param;
   const char *font = argv[argc-1];
   param.italic = (font[0] != '\0' && strchr(font, '\0')[-1] == 'I');
@@ -106,7 +110,7 @@ int main(int argc, char **argv)
       break;
     }
     if (i + 1 >= argc)
-      usage();
+      usage("option requires argument");
     size_t j;
     for (j = 0;; j++) {
       if (j >= sizeof(param_table)/sizeof(param_table[0]))
@@ -115,11 +119,11 @@ int main(int argc, char **argv)
        break;
     }
     if (sscanf(argv[i+1], "%d", &(param.*(param_table[j].par))) != 1)
-      fatal("invalid argument '%1'", argv[i+1]);
+      fatal("invalid option argument '%1'", argv[i+1]);
     i++;
-  }    
+  }
   if (argc - i != 3)
-    usage();
+    usage("insufficient arguments");
   errno = 0;
   FILE *infp = fopen(font, "r");
   if (infp == 0)
@@ -130,16 +134,27 @@ int main(int argc, char **argv)
 
 static void usage(FILE *stream)
 {
-  fprintf(stream, "usage: %s [-v] [-param value] ... "
-                 "resolution unitwidth font\n",
-         program_name);
+  fprintf(stream, "usage: %s", program_name);
+  size_t len = sizeof(param_table)/sizeof(param_table[0]);
+  for (int i = 0; i < len; i++)
+    fprintf(stream, " [-%s N]", param_table[i].name);
+  fprintf(stream, " RESOLUTION UNIT-WIDTH FONT\n");
+  fprintf(stream, "%s -v\n", program_name);
+  fprintf(stream, "%s --version\n", program_name);
 }
+
 static void usage()
 {
   usage(stderr);
   exit(1);
 }
 
+static void usage(const char *problem)
+{
+  error("%1", problem);
+  usage();
+}
+
 static void version()
 {
   printf("GNU addftinfo (groff) version %s\n", Version_string);
@@ -157,8 +172,9 @@ static int get_line(FILE *fp, string *p)
   }
   return p->length() > 0;
 }
-  
-static void convert_font(const font_params &param, FILE *infp, FILE *outfp)
+
+static void convert_font(const font_params &param, FILE *infp,
+                        FILE *outfp)
 {
   string s;
   while (get_line(infp, &s)) {
@@ -200,18 +216,18 @@ static void convert_font(const font_params &param, FILE 
*infp, FILE *outfp)
                printf(",%d,%d", metric.height, metric.depth);
            }
            else
-             printf(",%d,%d,%d", metric.height, metric.depth, metric.ic);
+             printf(",%d,%d,%d", metric.height, metric.depth,
+                    metric.ic);
          }
          else
-           printf(",%d,%d,%d,%d", metric.height, metric.depth, metric.ic,
-                  metric.left_ic);
+           printf(",%d,%d,%d,%d", metric.height, metric.depth,
+                  metric.ic, metric.left_ic);
        }
        else
-         printf(",%d,%d,%d,%d,%d", metric.height, metric.depth, metric.ic,
-                metric.left_ic, metric.sk);
+         printf(",%d,%d,%d,%d,%d", metric.height, metric.depth,
+                metric.ic, metric.left_ic, metric.sk);
       }
     }
     fputs(p, outfp);
   }
 }
-