[groff] 02/09: tfmtodit: Improve diagnostics and man page.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 3805840a1e761116405aad372716ec47d2bae319
Author: G. Branden Robinson <address@hidden>
AuthorDate: Thu Apr 30 00:46:10 2020 +1000

    tfmtodit: Improve diagnostics and man page.
    
    * src/utils/tfmtodit/tfmtodit.cpp (read_map): Report invalid character
      code from map file in diagnostic.
    
      (main): Report invalid skew character position in diagnostic.
      Explicitly report insufficient arguments in addition to usage message.
      Lift invariant computed expressions s out of loops (more to shorten
      long lines than because I think the compiler won't figure it out).
      Give content to "impossible assertion".
    
      (tfm::load): Capitalism TFM initialism in diagnostics.
    
      (usage): Use full capitals for parameters as is conventional.
      Document disjunction of -v/--version flag from other invocations.
    
      Tidy up long lines and whitespace.
    
      Tested with:
        ./build/tfmtodit A
        ./build/tfmtodit A B
        ./build/tfmtodit A B C
        ./build/tfmtodit -g G -k 1 -s A B C
        ./build/tfmtodit -g G -k -1 -s A B C
        ./build/tfmtodit -g G -k D A B C
    
    * src/utils/tfmtodit/tfmtodit.1.man: Move compatibility mode save below
      legal terms notice, since we don't need compatibility mode in that
      comment block or the apropos/mkwhatis line before it.
    
      Tweak parameter names to be more idiomatic (use hyphens, not
      underscores--these are not C symbol names).
    
      Kill off font escapes in favor of font macros.
    
      Use ellipsis more clearly in a heterogeneous parameter list.
    
      Use .RS/.RE in preference to .IP for text insets that aren't
      paragraphs.
    
      Use .RS+.EX and .EE+.RE for lengthy examples.  Eliminate direct use of
      .nf, .fi, and .ft requests.
    
      Document options in alphabetical order.
    
      Attempt to tighten and clarify language.
---
 ChangeLog                         |  29 ++---
 src/utils/tfmtodit/tfmtodit.1.man | 248 +++++++++++++++++++++-----------------
 src/utils/tfmtodit/tfmtodit.cpp   |  53 ++++----
 3 files changed, 185 insertions(+), 145 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 610c23e..c13a3fc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2020-04-30  G. Branden Robinson <address@hidden>
+
+       * src/utils/tfmtodit/tfmtodit.cpp (read_map): Report invalid
+       character code from map file in diagnostic.
+       (main): Report invalid skew character position in diagnostic.
+       Explicitly report insufficient arguments in addition to
+       usage message.  Lift invariant computed expressions s out of
+       loops (more to shorten long lines than because I think the
+       compiler won't figure it out).  Give content to "impossible
+       assertion".
+       (tfm::load): Capitalism TFM initialism in diagnostics.
+       (usage): Use full capitals for parameters as is conventional.
+       Document disjunction of -v/--version flag from other
+       invocations.
+
 2020-04-29  G. Branden Robinson <address@hidden>
 
        * src/utils/addftinfo/addftinfo.cpp (usage): Add overloaded
@@ -11,20 +26,6 @@
 
        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.
diff --git a/src/utils/tfmtodit/tfmtodit.1.man 
b/src/utils/tfmtodit/tfmtodit.1.man
index 393ffd5..e61b6c0 100644
--- a/src/utils/tfmtodit/tfmtodit.1.man
+++ b/src/utils/tfmtodit/tfmtodit.1.man
@@ -3,11 +3,6 @@
 tfmtodit \- create font files for use with groff \-Tdvi
 .
 .
-.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
-.do nr *groff_tfmtodit_1_man_C \n[.cp]
-.cp 0
-.
-.
 .\" ====================================================================
 .\" Legal Terms
 .\" ====================================================================
@@ -30,6 +25,11 @@ tfmtodit \- create font files for use with groff \-Tdvi
 .\" instead of in the original English.
 .
 .
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr *groff_tfmtodit_1_man_C \n[.cp]
+.cp 0
+.
+.
 .\" ====================================================================
 .\" Definitions
 .\" ====================================================================
@@ -44,10 +44,10 @@ tfmtodit \- create font files for use with groff \-Tdvi
 .
 .SY tfmtodit
 .OP \-s
-.OP \-g gf_file
-.OP \-k skewchar
-.I tfm_file
-.I map_file
+.OP \-g gf-file
+.OP \-k skew-char
+.I tfm-file
+.I map-file
 .I font
 .YS
 .
@@ -66,121 +66,145 @@ tfmtodit \- create font files for use with groff \-Tdvi
 .SH Description
 .\" ====================================================================
 .
-.B tfmtodit
+.I tfmtodit
 creates a font file for use with
-.B
-groff \-Tdvi\fR.
+.RB \[lq] "groff \-Tdvi" \[rq].
 .
-.I tfm_file
+.I tfm-file
 is the name of the \*(tx font metric file for the font.
 .
-.I map_file
-is a file giving the groff names for characters in the font;
-this file should consist of a sequence of lines of the form:
-.IP
-.I
-n c1 c2 \fR.\|.\|.
+.I map-file
+is a file giving the
+.I groff
+names for characters in the font;
+this file should consist of a sequence of lines of the form
 .
+.RS
+.IR "i c1" \~\&.\|.\|.\&\~ cn
+.RE
 .
-.LP
 where
-.I n
+.I i
 is a decimal integer giving the position of the character in the font,
 and
-.IR c1 ,
-.IR c2 ,.\|.\|.
-are the groff names of the character.
-.
-If a character has no groff names but exists in the tfm file,
-then it will be put in the groff font file as an unnamed character.
+.I c1
+through
+.I cn
+are
+are the
+.I groff
+names of the character.
+.
+If a character has no
+.I groff
+names but exists in
+.IR tfm-file ,
+then it will be put in the
+.I groff
+font file as an unnamed character.
 .
-.I font
-is the name of the groff font file.
-.
-The groff font file is written to
+The
+.I groff
+font file is written to
 .IR font .
 .
 .
 .LP
 The
 .B \-s
-option should be given if the font is special
-(a font is
-.I special
-if
-.B troff
-should search it whenever
-a character is not found in the current font.)
-.
-If the font is special,
-it should be listed in the
+option should be given if the font is \[lq]special\[rq],
+meaning that
+.I groff
+should search it whenever a character is not found in the current font.
+.
+In that case,
+.I font
+should be listed as an argument to the
 .B fonts
-command in the DESC file;
-if it is not special, there is no need to list it, since
-.B troff
-can automatically mount it when it's first used.
+directive in the
+.I DESC
+file;
+if it is not special,
+there is no need to list it,
+since
+.I groff
+can automatically mount it when it is first used.
 .
 .
 .LP
-To do a good job of math typesetting, groff requires font metric
-information not present in the tfm file.
-.
-The reason for this is that \*(tx has separate math italic fonts
-whereas groff uses normal italic fonts for math.
-.
-The additional information required by groff is given by the two
-arguments to the
+To do a good job of math typesetting,
+.I groff
+requires font metric information not present in
+.IR tfm-file .
+.
+This is because \*(tx has separate math italic fonts,
+whereas
+.I groff
+uses normal italic fonts for math.
+.
+The additional information required by
+.I groff
+is given by the two arguments to the
 .B math_fit
 macro in the Metafont programs for the Computer Modern fonts.
 .
 In a text font (a font for which
-.B math_fitting
-is false), Metafont normally ignores these two arguments.
+.B math_fit
+is false),
+Metafont normally ignores these two arguments.
 .
-Metafont can be made to put this information in the gf file by loading
-the following definition after
+Metafont can be made to put this information into the GF
+(\[lq]generic font\[rq])
+files it produces by loading the following definition after
 .B cmbase
 when creating
-.IR cm.base :
-.IP
-.nf
-.ft B
+.IR cm.base .
+.
+.RS
+.EX
 def ignore_math_fit(expr left_adjustment,right_adjustment) =
     special "adjustment";
     numspecial left_adjustment*16/designsize;
     numspecial right_adjustment*16/designsize;
     enddef;
-.fi
-.ft R
+.EE
+.RE
+.
+.
 .LP
-For the EC font family, load the following definition after
-.B exbase
-(it is probably easiest to patch
+For the EC font family,
+load the following definition after
+.BR exbase \[em]it
+is probably easiest to patch
 .I exbase.mf
-locally):
-.IP
-.nf
-.ft B
+locally.
+.
+.RS
+.EX
 def ignore_math_fit(expr left_adjustment,right_adjustment) =
     ori_special "adjustment";
     ori_numspecial left_adjustment*16/designsize;
     ori_numspecial right_adjustment*16/designsize;
     enddef;
-.fi
-.ft R
+.EE
+.RE
+.
+The only difference from the previous example is the \[lq]ori_\[rq]
+prefix to \[lq]special\[rq] and \[lq]numspecial\[rq].
+.
+.
 .LP
-The gf file created using this modified
+The GF file created using this modified
 .I cm.base
 or
-.I exbase
+.I exbase.mf
 should be specified with the
 .B \-g
-option.
-.
-The
-.B \-g
-option should not be given for a font for which
-.B math_fitting
+option,
+which should
+.I not
+be given for a font for which
+.B math_fit
 is true.
 .
 .
@@ -188,44 +212,49 @@ is true.
 .SH Options
 .\" ====================================================================
 .
-Whitespace is permitted between a command-line option and its argument.
-.
-.
-.TP
+.B \-\-help
+displays a usage message,
+while
 .B \-v
-Print the version number.
+and
+.B \-\-version
+show version information;
+all exit afterward.
+.
 .
 .TP
-.B \-s
-The font is special.
+.BI \-g \~gf-file
+Use the
+.I gf-file
+produced by Metafont containing
+.RB \[lq] special \[rq]
+and
+numspecial
+commands to obtain additional font metric information.
 .
-The effect of this option is to add the
-.B special
-command to the font file.
 .
 .TP
-.BI \-k n
-The skewchar of this font is at position
-.IR n .
+.BI \-k \~skew-char
+The skew charcter of this font is at position
+.IR skew-char .
 .
-.I n
+.I skew-char
 should be an integer;
 it may be given in decimal,
-or with a leading
-.B 0
-in octal,
-or with a leading
-.B 0x
-in hexadecimal.
+with a leading 0 in octal,
+or with a leading 0x in hexadecimal.
+.
+Any kerns whose second component is
+.I skew-char
+are ignored.
 .
-The effect of this option is to ignore any kerns whose second
-component is the specified character.
 .
 .TP
-.BI \-g gf_file
-.I gf_file
-is a gf file produced by Metafont containing special and numspecial
-commands giving additional font metric information.
+.B \-s
+Add the
+.B special
+directive to the generated file
+.IR font .
 .
 .
 .\" ====================================================================
@@ -245,9 +274,10 @@ Font description file for font
 .\" ====================================================================
 .SH "See Also"
 .\" ====================================================================
-.BR groff (@MAN1EXT@),
-.BR grodvi (@MAN1EXT@),
-.BR groff_font (@MAN5EXT@)
+.
+.IR groff (@MAN1EXT@),
+.IR grodvi (@MAN1EXT@),
+.IR groff_font (@MAN5EXT@)
 .
 .
 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
diff --git a/src/utils/tfmtodit/tfmtodit.cpp b/src/utils/tfmtodit/tfmtodit.cpp
index f83d98d..6a49fe9 100644
--- a/src/utils/tfmtodit/tfmtodit.cpp
+++ b/src/utils/tfmtodit/tfmtodit.cpp
@@ -29,7 +29,8 @@ case of a font for which math_fitting is false, these two 
arguments
 are normally ignored by Metafont. We need to get hold of these two
 parameters and put them in the groff font file.
 
-We do this by loading this definition after cmbase when creating cm.base.
+We do this by loading this definition after cmbase when creating
+cm.base.
 
 def ignore_math_fit(expr left_adjustment,right_adjustment) =
  special "adjustment";
@@ -163,7 +164,7 @@ int kern_iterator::next(unsigned char *c1, unsigned char 
*c2, int *k)
     }
   return 0;
 }
-         
+
 tfm::tfm()
 : char_info(0), width(0), height(0), depth(0), italic(0), lig_kern(0),
   kern(0), param(0)
@@ -251,7 +252,7 @@ tfm::~tfm()
   a_delete kern;
   a_delete param;
 }
-  
+
 int read2(unsigned char *&s)
 {
   int n;
@@ -270,7 +271,6 @@ int read4(unsigned char *&s)
   return n;
 }
 
-
 int tfm::load(const char *file)
 {
   errno = 0;
@@ -300,7 +300,7 @@ int tfm::load(const char *file)
   }
   fclose(fp);
   if (lf < 6) {
-    error("bad tfm file '%1': impossibly short", file);
+    error("bad TFM file '%1': impossibly short", file);
     a_delete buf;
     return 0;
   }
@@ -316,13 +316,14 @@ int tfm::load(const char *file)
   nk = read2(ptr);
   int ne = read2(ptr);
   np = read2(ptr);
-  if (6 + lh + (ec - bc + 1) + nw + nh + nd + ni + nl + nk + ne + np != lf) {
-    error("bad tfm file '%1': lengths do not sum", file);
+  if ((6 + lh + (ec - bc + 1) + nw + nh + nd + ni + nl + nk + ne + np)
+      != lf) {
+    error("bad TFM file '%1': lengths do not sum", file);
     a_delete buf;
     return 0;
   }
   if (lh < 2) {
-    error("bad tfm file '%1': header too short", file);
+    error("bad TFM file '%1': header too short", file);
     a_delete buf;
     return 0;
   }
@@ -592,7 +593,8 @@ struct char_list {
   char_list(const char *, char_list * = 0);
 };
 
-char_list::char_list(const char *s, char_list *p) : ch(strsave(s)), next(p)
+char_list::char_list(const char *s, char_list *p) : ch(strsave(s)),
+                    next(p)
 {
 }
 
@@ -626,7 +628,7 @@ int read_map(const char *file, char_list **table)
       return 0;
     }
     if (n < 0 || n > 255) {
-      error("%1:%2: code out of range", file, lineno);
+      error("%1:%2: code %3 out of range", file, lineno, n);
       fclose(fp);
       return 0;
     }
@@ -681,7 +683,7 @@ struct S2 {
   };
 
 static void usage(FILE *stream);
-  
+
 int main(int argc, char **argv)
 {
   program_name = argv[0];
@@ -694,7 +696,8 @@ int main(int argc, char **argv)
     { "version", no_argument, 0, 'v' },
     { NULL, 0, 0, 0 }
   };
-  while ((opt = getopt_long(argc, argv, "svg:k:", long_options, NULL)) != EOF)
+  while ((opt = getopt_long(argc, argv, "svg:k:", long_options, NULL))
+        != EOF)
     switch (opt) {
     case 'g':
       gf_file = optarg;
@@ -710,7 +713,7 @@ int main(int argc, char **argv)
            || *ptr != '\0'
            || n < 0
            || n > UCHAR_MAX)
-         error("invalid skewchar");
+         error("invalid skew character position '%1'", optarg);
        else
          skewchar = (int)n;
        break;
@@ -730,9 +733,10 @@ int main(int argc, char **argv)
       exit(1);
       break;
     case EOF:
-      assert(0);
+      assert(0 == "EOF encountered in option processing");
     }
   if (argc - optind != 3) {
+    error("insufficient arguments");
     usage(stderr);
     exit(1);
   }
@@ -752,7 +756,8 @@ int main(int argc, char **argv)
     return 1;
   errno = 0;
   if (!freopen(font_file, "w", stdout)) {
-    error("can't open '%1' for writing: %2", font_file, strerror(errno));
+    error("can't open '%1' for writing: %2", font_file,
+         strerror(errno));
     return 1;
   }
   printf("name %s\n", font_file);
@@ -762,8 +767,8 @@ int main(int argc, char **argv)
   int len = strlen(internal_name);
   if (len > 4 && strcmp(internal_name + len - 4, ".tfm") == 0)
     internal_name[len - 4] = '\0';
-  // DIR_SEPS[] are possible directory separator characters, see nonposix.h.
-  // We want the rightmost separator of all possible ones.
+  // DIR_SEPS[] are possible directory separator characters, see
+  // nonposix.h.  We want the rightmost separator of all possible ones.
   // Example: d:/foo\\bar.
   const char *s = strrchr(internal_name, DIR_SEPS[0]), *s1;
   const char *sep = &DIR_SEPS[1];
@@ -789,8 +794,10 @@ int main(int argc, char **argv)
   // Print the list of ligatures.
   // First find the indices of each character that can participate in
   // a ligature.
+  size_t lig_char_entries = sizeof(lig_chars)/sizeof(lig_chars[0]);
+  size_t lig_table_entries = sizeof(lig_table)/sizeof(lig_table[0]);
   for (i = 0; i < 256; i++)
-    for (unsigned int j = 0; j < sizeof(lig_chars)/sizeof(lig_chars[0]); j++)
+    for (unsigned int j = 0; j < lig_char_entries; j++)
       for (char_list *p = table[i]; p; p = p->next)
        if (strcmp(lig_chars[j].ch, p->ch) == 0)
          lig_chars[j].i = i;
@@ -798,7 +805,7 @@ int main(int argc, char **argv)
   // and it appears as a ligature in the tfm file, include in
   // the list of ligatures.
   int started = 0;
-  for (i = 0; i < sizeof(lig_table)/sizeof(lig_table[0]); i++) {
+  for (i = 0; i < lig_table_entries; i++) {
     int i1 = lig_chars[lig_table[i].c1].i;
     int i2 = lig_chars[lig_table[i].c2].i;
     int r = lig_chars[lig_table[i].res].i;
@@ -837,7 +844,7 @@ int main(int argc, char **argv)
     }
   printf("charset\n");
   char_list unnamed("---");
-  for (i = 0; i < 256; i++) 
+  for (i = 0; i < 256; i++)
     if (t.contains(i)) {
       char_list *p = table[i] ? table[i] : &unnamed;
       int m[6];
@@ -868,6 +875,8 @@ int main(int argc, char **argv)
 
 static void usage(FILE *stream)
 {
-  fprintf(stream, "usage: %s [-sv] [-g gf_file] [-k skewchar] tfm_file 
map_file font\n",
-         program_name);
+  fprintf(stream, "usage: %s [-s] [-g GF-FILE] [-k SKEW-CHAR] TFM-FILE"
+         " MAP-FILE FONT\n", program_name);
+  fprintf(stream, "%s -v\n", program_name);
+  fprintf(stream, "%s --version\n", program_name);
 }