[groff] 01/01: gperl: from running Perl part use output variables for groff strings or number registers; allow; several varibales; rewrite gperl.man

[Bernd Warken]

bwarken pushed a commit to branch master
in repository groff.

commit 5ec955592fa3f0b287e32f61bed9dd8810f0882a
Author: Bernd Warken <address@hidden>
Date:   Sun Jun 15 21:57:09 2014 +0200

    gperl: from running Perl part use output variables for groff strings or 
number registers; allow; several varibales; rewrite gperl.man
---
 contrib/gperl/ChangeLog    |    8 +
 contrib/gperl/Makefile.sub |   19 ++-
 contrib/gperl/gperl.man    |  317 ++++++++++++++++++++++++++++++++------------
 contrib/gperl/gperl.pl     |   99 ++++++++------
 4 files changed, 313 insertions(+), 130 deletions(-)

diff --git a/contrib/gperl/ChangeLog b/contrib/gperl/ChangeLog
index ab9c26f..09900b6 100644
--- a/contrib/gperl/ChangeLog
+++ b/contrib/gperl/ChangeLog
@@ -1,3 +1,11 @@
+2014-06-15  Bernd Warken  <address@hidden>
+
+       * gperl.pl: Version 1.2.  Getting several storage variables from
+       printing in `Perl' with several lines.  Accept string and number
+       register variable names for `.ds' and `.nr'.
+
+       * gperl.man: Rewrite with the actual additions.
+
 2014-06-14  Bernd Warken  <address@hidden>
 
        * gperl.pl: Version 1.1.  New structure without subs.  Restrict
diff --git a/contrib/gperl/Makefile.sub b/contrib/gperl/Makefile.sub
index 7281250..02f24f4 100644
--- a/contrib/gperl/Makefile.sub
+++ b/contrib/gperl/Makefile.sub
@@ -30,12 +30,14 @@ MAN1=gperl.n
 
 MOSTLYCLEANADD=gperl $(MAN1)
 
+# not all make programs have $(RM) predefined.
+RM=rm -f
+
 all: gperl
 
 gperl: gperl.pl
-       rm -f $@
        sed -f "$(SH_DEPS_SED_SCRIPT)" \
-           -e "s|@g@|$(g)|g" \
+            -e "s|@g@|$(g)|g" \
            -e "s|@BINDIR@|$(DESTDIR)$(bindir)|g" \
            -e "s|@VERSION@|$(version)$(revision)|g" \
            -e "$(SH_SCRIPT_SED_CMD)" \
@@ -45,9 +47,18 @@ gperl: gperl.pl
 .PHONY: install_data
 install_data: gperl
        -test -d $(DESTDIR)$(bindir) || $(mkinstalldirs) $(DESTDIR)$(bindir)
-       rm -f $(DESTDIR)$(bindir)/gperl
+       $(RM) $(DESTDIR)$(bindir)/gperl
        $(INSTALL_SCRIPT) gperl $(DESTDIR)$(bindir)/gperl
 
 .PHONY: uninstall_sub
 uninstall_sub:
-       rm -f $(DESTDIR)$(bindir)/gperl
+       $(RM) $(DESTDIR)$(bindir)/gperl
+
+
+########################################################################
+# Emacs settings
+########################################################################
+#
+# Local Variables:
+# mode: makefile
+# End:
diff --git a/contrib/gperl/gperl.man b/contrib/gperl/gperl.man
index 7b89b7f..409b1d9 100644
--- a/contrib/gperl/gperl.man
+++ b/contrib/gperl/gperl.man
@@ -190,7 +190,7 @@ The starting
 .I Perl request
 can either be without arguments, or by a request that has the term
 .B start
-as its first argument.
+as its only argument.
 .RS
 .Topic
 .B \&.Perl
@@ -198,10 +198,6 @@ as its first argument.
 .B \&.Perl start
 .RE
 .
-All arguments after
-.B start
-are ignored.
-.
 .
 .\" --------------------------------------------------------------------
 .SS "Ending Perl Mode without Storage"
@@ -227,8 +223,9 @@ that's possible, but not necessary.
 .
 The argument
 .I other_than_start
-can additionally used as a variable name for storage, see next
-section.
+can additionally be used as a
+.I groff
+string variable name for storage \[em] see next section.
 .
 .
 .\" --------------------------------------------------------------------
@@ -237,113 +234,221 @@ section.
 .
 A useful feature of
 .B gperl
-is to store some result from the
+is to store one or more results from the
 .IR "Perl mode" .
 .
 .
 .P
-That can be done by running the
+The output of a
 .I Perl part
-within
-.B gperl
-using one of the
+can be got by using one of the
 .I Perl commands
 from
-.BR IPC::System::Simple .
+.BR IPC::System::Simple :
+.BR capture ,
+.BR capturex ,
+.BR run ,
+.BR runx ,
+.BR system ,
+or
+.BR systemx .
 .
-We use now the program
-.B capture
-for running the
-.IR "Perl parts" .
+Several of these programs work, we use now the program
+.B capturex
+from running Perl parts.
 .
 .
 .P
-The related storage information comes from the collection of all
-printing to standard output with the normal Perl
+This program collects all printing to STDOUT (normal standard output)
+by the Perl
 .B print
-command in a
-.IR "Perl part" .
+program.
 .
-This pseudo-printing information does not go to
-.I STDOUT
-as normally, but is received as the result from the program, which
-runs the
-.IR "Perl part" .
+This pseudo-printing output can have several lines, due to printed
+line breaks with
+.BR \[rs]n .
+.
+By that, the output of a Perl run should be stored into a Perl array,
+with a single line for each array member.
 .
 .
 .P
-But the printing towards
-.IR STDERR ,
-(standard error) works as usual.
+This Perl array output can be stored by
+.B gperl
+in either
+.TP
+.I groff strings
+by creating a groff command
+.B .ds
 .
-All error information goes to the real normal
-.IR "standard error" ,
-without other automatical storage.
+.TP
+.I groff number register
+by creating a groff command
+.B .rn
 .
 .
 .P
-To use that output from the
-.I Perl part
-for
-.IR roff ,
-.B gperl
-creates automatically a line with the string defining roff command
-.BR .ds .
-.
-Because of the Perl-structure of the result, only string output can be
-used, not
-.IR "numerical roff registers" .
+The storage modes can be determined by arguments of a final stopping
+.B .Perl
+command.
 .
-In
-.BR \%groff (@MAN7EXT@),
-one can create registers from strings.
+Each argument
+.B .ds
+changes the mode into
+.I groff string
+and
+.B .nr
+changes the mode into
+.I groff number register
+for all following output parts.
 .
 .
-.B
-As the
-.I Perl mode
-must first be finished to get the information, this storage can only
-be done by arguments in the final
-.B .Perl
+.P
+By default, all output is saved as strings, so
+.B .ds
+is not really needed before the first
+.B .nr
 command.
 .
-Possible arguments are
+That suits to
+.BR \%groff (@MAN7EXT@),
+because every output can be saved as
+.I groff
+string, but the number registers can be very restrictive.
+.
+.
+.P
+In
+.IR "string mode" ,
+.B gperl
+generates a
+.I groff string
+storage line
+.RS
+.EX
+\&\fB.ds \fIvar_name content
+.EE
+.RE
 .
+In
+.I number register mode
+the following groff command is generated
 .RS
-.Topic
-.BI .Perl " var_name"
-.Topic
-.BI ".Perl ds" " var_name"
-.Topic
-.BI ".Perl .ds" " var_name"
-.Topic
-.BI ".Perl stop" " var_name"
-.Topic
-.BI ".Perl stop ds" " var_name"
-.Topic
-.BI ".Perl stop .ds" " var_name"
+.EX
+\&\fB.nr \fIvar_name content
+.EE
 .RE
 .
 .
 .P
-The
+We present argument collections in the following.
+.
+You can add as first argument for all
+.BR stop .
+.
+We omit this additional element. 
+.
+.
+.P
+.TP
+.BI ".Perl .ds " var_name
+This will store 1 output line into the groff string named
 .I var_name
-is some word that will be used by
-.B gperl
-for a
-.B .ds
-roff string definition.
+by the automatically created command
+.RS
+.RS
+.EX
+.BI .ds " var_name output"
+.EE
+.RE
+.RE
 .
-If this
+.
+.TP
+.BI .Perl " var_name"
+If
 .I var_name
-is the only argument, it must be different from
-.BR start ,
-at other argument places it can be chosen arbitrarily, but without
-spaces.
+is different from
+.B start
+this is equivalent to the former command, because the string mode is
+string with
+.B .ds
+command.
+default.
+.
+.
+.TP
+.BI .Perl " var_name1 var_name2"
+This will store 2 output lines into groff string names
+.I var_name1
+and
+.IR var_name2 ,
+because the default mode
+.B .ds
+is active, such that no
+.B .ds
+argument is needed.
+.
+Of course, this is equivalent to
+.RS
+.RS
+.EX
+.BI ".Perl .ds " "var_name1 var_name2"
+.EE
+.RE
+and
+.RS
+.EX
+.BI ".Perl .ds " "var_name1 " ".ds" " var_name2"
+.EE
+.RE
+.RE
+.
+.
+.TP
+.BI ".Perl .nr" " var_name1 varname2"
+stores both variables as number register variables.
+.
+.B gperl
+generates
+.RS
+.EX
+.BI .nr " var_name1 output_line1"
+.BI .nr " var_name2 output_line2"
+.EE
+.RE
+.
+.
+.TP
+.BI ".Perl .nr " var_name1 " .ds " var_name2
+stores the 1st argument as
+.I number register
+and the second as
+.I string
+by
+.RS
+.EX
+.BI .nr " var_name1 output_line1"
+.BI .ds " var_name2 output_line2"
+.EE
+.RE
 .
 .
 .\" --------------------------------------------------------------------
-.SH "EXAMPLE"
+.SS "Printing towards STDERR is without Storage"
+.\" --------------------------------------------------------------------
+.
+The printing towards
+.IR STDERR ,
+(standard error) works as usual.
+.
+All error information goes to the real normal
+.IR "standard error" ,
+without other automatical storage.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "EXAMPLES"
 .\" --------------------------------------------------------------------
 .
 A possible
@@ -356,8 +461,8 @@ could look like that:
 before
 \&.Perl start
 my $result = 'some data';
-print $result . \[rq]\[rs]n\[rq];
-\&.Perl stop .ds some_string 
+print $result;
+\&.Perl stop .ds string_var
 after
 .EE
 .RE
@@ -369,11 +474,11 @@ This stores the result
 into the
 .I roff string
 called
-.BR some_string ,
+.BR string_var ,
 such that the following line is printed:
 .RS
 .EX
-\&.ds some_string some data
+\&.ds string_var some data
 .EE
 .RE
 by
@@ -383,17 +488,63 @@ as food for the coming
 run.
 .
 .
+.P
+A
+.I Perl part
+with several outputs is:
+.RS
+.EX
+\&.Perl start
+print \[rq]first\[rs]n\[rq];
+print \[rq]second line\[rs]n\[rq];
+print \[rq]3\[rs]n\[rq];
+\&.Perl var1 var2 .nr var3 
+.EE
+.RE
+.
+This stores 3 printed lines into 3
+.I groff
+strings.
+.BR var1 , var2 , var3 .
+.
+So the following
+.I groff
+command lines are created:
+.RS
+.EX
+\&.ds var1 first
+\&.ds var2 second line
+\&.nr var3 3
+.EE
+.RE
+.
+.
 .\" --------------------------------------------------------------------
 .SH "SEE ALSO"
 .\" --------------------------------------------------------------------
 .
 .P
+Man\-pages related to
+.I groff
+are
 .BR \%groff (@MAN1EXT@),
 .BR \%groff (@MAN7EXT@),
 .BR \%grog (@MAN1EXT@),
-.BR \%groffer (@MAN1EXT@),
+and
+.BR \%groffer (@MAN1EXT@).
+.
+.
+.P
+Documents related to
+.I Perl
+are
 .BR \%perl (@MAN1EXT@),
-.BR \%perl (@MAN7EXT@).
+.BR \%perl (@MAN7EXT@),
+and
+.UR http://\:search.cpan.org/\:~pjf/\:IPC-System-Simple-1.25/\:lib/\:\
+IPC/\:System/\:Simple.pm
+.IR "Perl " IPC:System:Simple
+.UE
 .
 .
 .\" --------------------------------------------------------------------
diff --git a/contrib/gperl/gperl.pl b/contrib/gperl/gperl.pl
index ccb1670..2412dd5 100755
--- a/contrib/gperl/gperl.pl
+++ b/contrib/gperl/gperl.pl
@@ -10,8 +10,8 @@
 
 # Written by Bernd Warken <address@hidden>.
 
-my $Latest_Update = '14 Jun 2014';
-my $version = '1.1';
+my $Latest_Update = '15 Jun 2014';
+my $version = '1.2';
 
 # This file is part of `gperl', which is part of `groff'.
 
@@ -25,9 +25,8 @@ my $version = '1.1';
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 # General Public License for more details.
 
-# You should have received a copy of the GNU General Public License
-# along with this program. If not, see
-# <http://www.gnu.org/licenses/gpl-2.0.html>.
+# You can find a copy of the GNU General Public License in the internet
+# at <http://www.gnu.org/licenses/gpl-2.0.html>.
 
 ########################################################################
 
@@ -53,8 +52,9 @@ use Cwd;
 # $Bin is the directory where this script is located
 use FindBin;
 
-# for running perl scripts
-use IPC::System::Simple qw(system systemx capture capturex);
+# for running the perl parts with the `Perl' programs and getting output
+# also useful for shell programs
+use IPC::System::Simple qw(capture capturex run runx system systemx);
 
 
 ########################################################################
@@ -136,7 +136,6 @@ my $out_file;
 ########################################################################
 
 my $perl_mode = 0;
-my %set_cmd;
 
 foreach (<>) {
   chomp;
@@ -162,8 +161,11 @@ foreach (<>) {
 
   my @args = split /\s+/, $args;
 
-  if ( @args == 0 || $args[0] eq 'start' ) {
-    # for `.Perl' no args or first arg `start' means opening `Perl' mode
+  ##########
+  # start Perl mode
+  if ( @args == 0 || @args == 1 && $args[0] eq 'start' ) {
+    # For `.Perl' no args or first arg `start' means opening `Perl' mode.
+    # Everything else means an ending command.
     if ( $perl_mode ) {
       # `.Perl' was started twice, ignore
       print STDERR q(`.Perl' starter was run several times);
@@ -180,7 +182,8 @@ foreach (<>) {
 
   unless ( $perl_mode ) {
     print STDERR 'gperl: there was a Perl ending without being in ' .
-      'Perl mode.';
+      'Perl mode:';
+    print STDERR '    ' . $line;
     next;
   }
 
@@ -189,49 +192,59 @@ foreach (<>) {
 
   ##########
   # run this `Perl' part, later on about storage of the result
-  my $print_res = capturex('perl',  $out_file);
+  # array stores prints with \n
+  my @print_res = capturex('perl',  $out_file);
 
-  shift @args if ( $args[0] eq 'stop' ); # remove `stop' arg if exists
+  # remove `stop' arg if exists
+  shift @args if ( $args[0] eq 'stop' );
 
   if ( @args == 0 ) {
-    # no args for saving, so $print_res doesn't matter
+    # no args for saving, so @print_res doesn't matter
     next;
   }
 
-  # extract the now leading arg for saving mode
-  my $save_mode = shift @args;
+  my @var_names = ();
+  my @mode_names = ();
 
-  if ( @args == 0 ) {
-    # no args for saving variable name, so $print_res doesn't matter
-    print STDERR 'gperl: a variable name for the saving mode ' .
-      $save_mode . ' must be provided in the line:';
-    print STDERR '    ' . $line;
-    next;
+  my $mode = 'ds';
+  for ( @args ) {
+    if ( /^\.?ds$/ ) {
+      $mode = '.ds';
+      next;
+    }
+    if ( /^\.?nr$/ ) {
+      $mode = '.nr';
+      next;
+    }
+    push @mode_names, $mode;
+    push @var_names, $_;
   }
 
-  my $command;
-
-  # variable name for saving command the $print_res
-  my $var_name = shift @args;
-  # ignore all other args
-
-  if ( $save_mode =~ /^\.?ds$/ ) {             # string
-    $command = '.ds';
-  } elsif ( $save_mode =~ /^\.?nr$/ ) {
-    # Number registers do not work, just for compatibility.
-    # Storage is done into a `groff' string variable
-    $command = '.ds';
-  } else {     # no storage variables provided
-     print STDERR 'gperl: wrong argument ' . $save_mode .
-       'in Perl stop line:';
-     print STDERR '    ' . $line;
-     print STDERR 'allowed are only .ds for storing a string or .nr ' .
-       'for a number register';
-     next;
+  my $n_res = @print_res;
+  my $n_vars = @var_names;
+
+  if ( $n_vars < $n_res ) {
+    print STDERR 'gperl: not enough variables for Perl part: ' .
+      $n_vars . ' variables for ' . $n_res . ' output lines.';
+  } elsif ( $n_vars > $n_res ) {
+    print STDERR 'gperl: too many variablenames for Perl part: ' .
+      $n_vars . ' variables for ' . $n_res . ' output lines.';
   }
+  if ( $n_vars < $n_res ) {
+    print STDERR 'gperl: not enough variables for Perl part: ' .
+      $n_vars . ' variables for ' . $n_res . ' output lines.';
+  }
+
+  my $n_min = $n_res;
+  $n_min = $n_vars if ( $n_vars < $n_res );
+  exit unless ( $n_min );
+  $n_min -= 1; # for starting with 0
 
-  $command .= ' ' . $var_name . ' ' . $print_res;
-  print $command;
+  for my $i ( 0..$n_min ) {
+    my $value = $print_res[$i];
+    chomp $value;
+    print $mode_names[$i] . ' ' . $var_names[$i] . ' ' . $value;
+  }
 }