[groff] 07/07: [grog]: Refactor command-line argument handling.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 6145868098b56a77b5e585f0ee3ec04ab73c5e66
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jun 29 14:11:14 2021 +1000

    [grog]: Refactor command-line argument handling.
    
    * src/utils/grog/grog.pl:
      - Drop scalars `groff_opts`, `device`, and `with_warnings`.
      - Move scalar `pdf_with_ligatures`...
    
      (process_arguments): ...here.  Recognize all groff options that take
      an optionally whitespace-separated option argument and apply the
      existing "delayed option" handling to them.  Push any groff option
      except `-m` as-is onto the constructed groff command's argument list
      (`-m` handling is unchanged).  Match long option names exactly, not
      sloppily.  Stop recognizing `--with-warnings` option.  Emit error
      diagnostic if unrecognized long option encountered.
    
      (infer_device): Delete subroutine and its top-level call site.
    
      (help): Undocument `--warnings`.
    
    * src/utils/grog/grog.1.man:
      (Synopsis): Use font style macros instead of .OP.  Undocument
      `--warnings`.
    
      (Options): Note that the groff arguments produced by the grog
      `--ligatures` option are supported only by the `pdf` device.
      Undocument `--warnings`.  Undocument groff-incompatible restriction on
      whitespace before option arguments; grog is compatible now.  Simplify
      discussion in light of simplified grog logic.
    
      (Details): Undocument scenario where grog infers multiple
      main/major/full-service macro packages; this no longer happens.
    
      (Examples): Update to no longer illustrate includion of `-T ps`
      option; this no longer happens by default.
    
    * NEWS: Document removal of grog's `--warnings` option.
    
    Fixes <https://savannah.gnu.org/bugs/?55301>; grog no longer
    mandatorily specifies a `-T` option to groff.
    
    Fixes <https://savannah.gnu.org/bugs/?57873>; groff options are
    no longer "mangled".
---
 ChangeLog                 |  41 ++++++++++++++++
 NEWS                      |   2 +
 src/utils/grog/grog.1.man |  97 ++++++++++++------------------------
 src/utils/grog/grog.pl    | 123 +++++++++++++---------------------------------
 4 files changed, 108 insertions(+), 155 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 207f4d3..4b956e4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,46 @@
 2021-06-29  G. Branden Robinson <g.branden.robinson@gmail.com>
 
+       [grog]: Refactor command-line argument handling.
+
+       * src/utils/grog/grog.pl:
+         - Drop scalars `groff_opts`, `device`, and `with_warnings`.
+         - Move scalar `pdf_with_ligatures`...
+         (process_arguments): ...here.  Recognize all groff options
+         that take an optionally whitespace-separated option argument
+         and apply the existing "delayed option" handling to them.
+         Push any groff option except `-m` as-is onto the constructed
+         groff command's argument list (`-m` handling is unchanged).
+         Match long option names exactly, not sloppily.  Stop
+         recognizing `--with-warnings` option.  Emit error diagnostic
+         if unrecognized long option encountered.
+         (infer_device): Delete subroutine and its top-level call site.
+         (help): Undocument `--warnings`.
+
+       * src/utils/grog/grog.1.man:
+         (Synopsis): Use font style macros instead of .OP.  Undocument
+         `--warnings`.
+         (Options): Note that the groff arguments produced by the grog
+         `--ligatures` option are supported only by the `pdf` device.
+         Undocument `--warnings`.  Undocument groff-incompatible
+         restriction on whitespace before option arguments; grog is
+         compatible now.  Simplify discussion in light of simplified
+         grog logic.
+         (Details): Undocument scenario where grog infers multiple
+         main/major/full-service macro packages; this no longer
+         happens.
+         (Examples): Update to no longer illustrate includion of `-T
+         ps` option; this no longer happens by default.
+
+       * NEWS: Document removal of grog's `--warnings` option.
+
+       Fixes <https://savannah.gnu.org/bugs/?55301>; grog no longer
+       mandatorily specifies a `-T` option to groff.
+
+       Fixes <https://savannah.gnu.org/bugs/?57873>; groff options are
+       no longer "mangled".
+
+2021-06-29  G. Branden Robinson <g.branden.robinson@gmail.com>
+
        Add regression test for Savannah #57873.
 
        * src/utils/grog/tests/preserve-groff-options.sh: Test it.
diff --git a/NEWS b/NEWS
index 3863e17..a933bec 100644
--- a/NEWS
+++ b/NEWS
@@ -215,6 +215,8 @@ o The semantics of the environment variable 
SOURCE_DATE_EPOCH (support
 
 o groffer has been deleted from the distribution.
 
+o grog no longer supports the "--warnings" option; the one diagnostic
+  message that it enabled has been removed.
 
 VERSION 1.22.4
 ==============
diff --git a/src/utils/grog/grog.1.man b/src/utils/grog/grog.1.man
index 2996c28..9eb34fd 100644
--- a/src/utils/grog/grog.1.man
+++ b/src/utils/grog/grog.1.man
@@ -33,12 +33,11 @@ requires
 .\" ====================================================================
 .
 .SY grog
-.OP \-\-run
-.OP \-\-warnings
-.OP \-\-ligatures
+.RB [ \-\-run ]
+.RB [ \-\-ligatures ]
 .RI [ groff-option
 \&.\|.\|.\&]
-.OP \-\-
+.RB [ \-\- ]
 .RI [ file
 \&.\|.\|.]
 .YS
@@ -109,12 +108,16 @@ all exit afterward.
 .
 .TP
 .B \-\-ligatures
-forces inclusion of the arguments
+includes the arguments
 .B \-P\-y \-PU
 in the generated
 .I groff
 command.
 .
+These are supported only by the
+.B pdf
+output driver.
+.
 .
 .TP
 .B \-\-run
@@ -122,33 +125,19 @@ writes the inferred command to the standard error stream 
and then
 executes it.
 .
 .
-.TP
-.B \-\-warnings
-issues more warnings to the standard error stream.
-.
-.
 .P
 All other specified short options
-(words starting with one minus character
-.RB \[lq] \- \[rq])
+(that is,
+arguments beginning with a minus sign
+.RB \[lq] \- \[rq]
+followed by a letter)
 are interpreted as
 .I groff
-options or option clusters with or without argument.
+options or option clusters with or without an option argument.
 .
-No space is allowed between such an option and its argument when it is
-specified to
-.IR grog ;
-this is not the case for
+Such options are included in the constructed
 .I groff
-itself.
-.
-Except for
-.BR \-m ,
-these options are passed through;
-that is,
-they are included unchanged in the output command without affecting the
-work of
-.IR grog .
+command line.
 .
 .
 .\" ====================================================================
@@ -191,7 +180,7 @@ and
 .
 The inferred
 .I groff
-command including those options and any
+command including these options and any
 .I file
 parameters is written to the standard output stream.
 .
@@ -201,10 +190,7 @@ It is possible to specify arbitrary
 .I groff
 options on the command line.
 .
-These are included in the inferred command without change,
-except for
-.B \-m
-options.
+These are included in the inferred command without change.
 .
 Choices of
 .I groff
@@ -228,29 +214,9 @@ it is best to specify no
 .B \-m
 options to
 .I grog
-unless it cannot correctly infer any
+unless it cannot correctly infer all of the
 .B \-m
-arguments at all.
-.
-.I grog
-will only accept
-.B \-m
-arguments and exit successfully if it can infer no
-.I groff
-.B \-m
-argument from the input or if the inferred and specified
-.B \-m
-arguments agree.
-.
-.
-.P
-If multiple
-.B \-m
-options are inferred by
-.IR grog ,
-it emits a diagnostic and terminates with an error exit status.
-.
-The inferred command is written with the wrong options nevertheless.
+arguments a document requires.
 .
 .
 .P
@@ -303,7 +269,7 @@ and compare the output to running
 on the input directly.
 .
 If the
-.IR \%@g@soelim 'ed
+.RI \[lq] \%@g@soelim \[rq]ed
 input causes
 .I grog
 to infer additional preprocessor options,
@@ -367,7 +333,10 @@ groff \-s \-t \-T ps 1.roff
 .I grog
 exits with error status
 .B 1
-if the input document appears to be malformed,
+if a macro package appears to be in use by the input document,
+but
+.I grog
+was unable to infer which one,
 or
 .B 2
 if there were problems handling an option or operand.
@@ -397,7 +366,7 @@ Running
 at the command line results in
 .RS
 .EX
-groff \-T ps \-me meintro.me
+groff \-me meintro.me
 .EE
 .RE
 .
@@ -421,7 +390,7 @@ outputs
 .
 .RS
 .EX
-groff \-T ps \-t \-e \-p \-ms pic.ms
+groff \-t \-e \-p \-ms pic.ms
 .EE
 .RE
 .
@@ -433,19 +402,17 @@ macro package,
 .I grog
 recognizes that the file
 .B pic.ms
-additionally needs
-.BR \-pte ,
-the combination of
-.B \-p
-for
-.IR pic ,
+additionally needs the combination of
 .B \-t
 for
 .IR tbl ,
-and
 .B \-e
 for
-.IR eqn .
+.IR eqn ,
+and
+.B \-p
+for
+.IR pic .
 .
 .
 .P
diff --git a/src/utils/grog/grog.pl b/src/utils/grog/grog.pl
index 944f14c..486c261 100644
--- a/src/utils/grog/grog.pl
+++ b/src/utils/grog/grog.pl
@@ -40,17 +40,10 @@ $\ = "\n";
 
 my $groff_version = 'DEVELOPMENT';
 
-# from 'src/roff/groff/groff.cpp' near 'getopt_long'
-my $groff_opts =
-  'abcCd:D:eEf:F:gGhiI:jJkK:lL:m:M:n:No:pP:r:RsStT:UvVw:W:XzZ';
-
 my @command = ();              # the constructed groff command
-my $device = '';               # argument to '-T' grog option
 my @requested_package = ();    # arguments to '-m' grog options
 
 my $do_run = 0;                        # run generated 'groff' command
-my $pdf_with_ligatures = 0;    # '-P-y -PU' for 'pdf' device
-my $with_warnings = 0;         # XXX: more like "hints"  --GBR
 
 my $program_name = $0;
 {
@@ -185,6 +178,7 @@ sub process_arguments {
   my $delayed_option = '';
   my $was_minus = 0;
   my $optarg = 0;
+  my $pdf_with_ligatures = 0;
 
   foreach my $arg (@ARGV) {
     if ( $optarg ) {
@@ -199,8 +193,13 @@ sub process_arguments {
     }
 
     if ($delayed_option) {
-      push @requested_package, $arg if ($delayed_option eq 'm');
-      $device = $arg if ($delayed_option eq 'T');
+      if ($delayed_option eq '-m') {
+       push @requested_package, $arg;
+      } else {
+       push @command, $delayed_option;
+      }
+
+      push @command, $arg;
       $delayed_option = '';
       next;
     }
@@ -225,35 +224,29 @@ sub process_arguments {
       next;
     }
 
-    # XXX: Stop matching these sloppily.  --GBR
-    &version() if $arg =~ /^--?v/;     # --version, with exit
-    &help() if $arg  =~ /--?h/;                # --help, with exit
-
-    if ( $arg =~ /^--r/ ) {            #  --run, no exit
-      $do_run = 1;
-      next;
-    }
+    # Handle options that cause an early exit.
+    &version() if ($arg eq '-v' || $arg eq '--version');
+    &help() if ($arg eq '-h' || $arg eq '--help');
 
-    if ( $arg =~ /^--wa/ ) {           #  --warnings, no exit
-      $with_warnings = 1;
+    if ($arg =~ '^--.') {
+      if ($arg =~ '^--(run|with-ligatures)$') {
+       $do_run = 1             if ($arg eq '--run');
+       $pdf_with_ligatures = 1 if ($arg eq '--with-ligatures');
+      } else {
+        &fail("unrecognized grog option '$arg'; ignored");
+      }
       next;
     }
 
-    if ( $arg =~ /^--(wi|l)/ ) { # --ligatures, no exit
-      # the old --with_ligatures is only kept for compatibility
-      $pdf_with_ligatures = 1;
-      next;
-    }
+    # Handle groff options that take an argument.
 
-    # Handle '-m' or '-T' followed by whitespace.
-    if ($arg =~ /^-[mT]$/) {
+    # Handle the option argument being separated by whitespace.
+    if ($arg =~ /^-[dfFIKLmMnoPrTwW]$/) {
       $delayed_option = $arg;
-      $delayed_option =~ s/-//;
       next;
     }
 
-    # Handle '-m' and '-T' without whitespace.
-
+    # Handle '-m' option without subsequent whitespace.
     if ($arg =~ /^-m/) {
       my $package = $arg;
       $package =~ s/-m//;
@@ -261,41 +254,16 @@ sub process_arguments {
       next;
     }
 
-    if ($arg =~ /^-T/) {
-      my $dev = $arg;
-      $dev =~ s/-T//;
-      $device = $dev;
-      next;
-    }
+    # Treat anything else as (possibly clustered) groff options that
+    # take no arguments.
+    push @command, $arg;
+  }
 
-    if ($arg =~ /^-(\w)(\w*)$/) {      # maybe a groff option
-      my $opt_char = $1;
-      my $opt_char_with_arg = $opt_char . ':';
-      my $others = $2;
-      if ( $groff_opts =~ /$opt_char_with_arg/ ) {     # groff optarg
-       if ( $others ) {        # optarg is here
-         push @command, '-' . $opt_char;
-         push @command, '-' . $others;
-         next;
-       }
-       # next arg is optarg
-       $optarg = 1;
-       next;
-      } elsif ( $groff_opts =~ /$opt_char/ ) { # groff no optarg
-       push @command, '-' . $opt_char;
-       if ( $others ) {        # $others is now an opt collection
-         $arg = '-' . $others;
-         redo;
-       }
-       # arg finished
-       next;
-      } else {         # not a groff opt
-       &warn("unrecognized groff option '$arg'");
-       push(@command, $arg);
-       next;
-      }
-    }
+  if ($pdf_with_ligatures) {
+    push @command, '-P-y';
+    push @command, '-PU';
   }
+
   @filespec = ('-') unless (@filespec);
 } # process_arguments()
 
@@ -696,30 +664,6 @@ my @m = ();
 my @supplemental_package = ();
 my @preprocessor = ();
 
-sub infer_device {
-  if ($device) {
-    push @command, '-T';
-    push @command, $device;
-  }
-
-  if ( $device eq 'pdf' ) {
-    if ( $pdf_with_ligatures ) {       # with --ligature argument
-      push( @command, '-P-y' );
-      push( @command, '-PU' );
-    } else {   # no --ligature argument
-      if ( $with_warnings ) {
-       print STDERR <<EOF;
-If you have trouble with ligatures like 'fi' in the 'groff' output, you
-can proceed as one of
-- add 'grog' option '--with_ligatures' or
-- use the 'grog' option combination '-P-y -PU' or
-- try to remove the font named similar to 'fonts-texgyre' from your system.
-EOF
-      }        # end of warning
-    }  # end of ligature
-  }    # end of pdf device
-} # infer_device()
-
 
 sub infer_preprocessors {
   # preprocessors without 'groff' option
@@ -827,7 +771,7 @@ sub infer_macro_packages {
     $inferred_main_package = 'm';
     return 1;  # true
   }
-  # XXX: Is this necessary?  mmse .mso's mm, but we probably already
+  # XXX: Is this necessary?  mmse "mso"s mm, but we probably already
   # detected mm macro calls anyway.  --GBR
   if ( $Groff{'mmse'} ) {      # Swedish mm
     return 1;  # true
@@ -920,7 +864,6 @@ names, even if they start with a '-' character.
 --ligatures    include options '-P-y -PU' for internal font, which
                preserves the ligatures like 'fi'
 --run          run the checked-out groff command
---warnings     display more warnings to standard error
 
 All other options should be 'groff' 1-character options.  These are then
 appended to the generated 'groff' command line.  The '-m' options will
@@ -951,7 +894,6 @@ $groff_version = '@VERSION@' unless ($in_source_tree);
 &process_input();
 
 if ($have_any_valid_arguments) {
-  &infer_device();
   &infer_preprocessors();
   &infer_macro_packages() || &infer_man_or_ms_package();
   &construct_command();
@@ -963,6 +905,7 @@ exit 0;
 
 1;
 # Local Variables:
+# fill-column: 72
 # mode: CPerl
 # End:
-# vim: set autoindent textwidth=72:
+# vim: set autoindent noexpandtab shiftwidth=2 textwidth=72: