gperl - execute Perl commands in groff documents

gperl was written by Bernd Warken.

       This is a preprocessor for groff(1).  It allows the use of perl(7) code in groff(7) files.  The result of
       a  Perlpart can be stored in groff strings or numericalregisters based on the arguments at a final line
       of a Perlpart.

       If no operands are given, or if file is “-”, gperl  reads  the  standard  input  stream.   A  double-dash
       argument  (“--”)  causes all subsequent arguments to be interpreted as file operands, even if their names
       start with a dash.  -h and --help display a usage message,  whereas  -v  and  --version  display  version
       information; all exit afterward.

       A possible Perlpart in a rofffile could look like that:
              before
              .Perl start
              my $result = 'some data';
              print $result;
              .Perl stop .ds string_var
              after

       This stores the result ”somedata” into the roffstring called string_var, such that the  following  line
       is printed:
              .ds string_var some data
       by gperl as food for the coming groff run.

       A Perlpart with several outputs is:
              .Perl start
              print ”first\n”;
              print ”second line\n”;
              print ”3\n”;
              .Perl var1 var2 .nr var3
       This  stores 3 printed lines into 3 groff strings.  var1,var2,var3.  So the following groff command lines
       are created:
              .ds var1 first
              .ds var2 second line
              .nr var3 3

       gperl - execute Perl commands in groff documents

Perl  parts in grofffiles are enclosed by two .Perl requests with different arguments, a starting and an
       ending command.

   StartingPerlmode
       The starting Perlrequest can either be without arguments, or by a request that has the term start as its
       only argument.

              •      .Perl

              •      .PerlstartEndingPerlmodewithoutstorage
       A .Perl command line with an argument different from start finishes a running Perlpart.  Of  course,  it
       would be reasonable to add the argument stop; that's possible, but not necessary.

              •      .Perlstop

              •      .Perlother_than_start
       The  argument other_than_start can additionally be used as a groff string variable name for storage — see
       next section.

   EndingPerlmodewithstorage
       A useful feature of gperl is to store one or more results from the Perlmode.

       The output of a Perlpart can be got with backticks `...`.

       This program collects all printing to STDOUT (normal standard output) by the Perl  print  program.   This
       pseudo-printing  output  can have several lines, due to printed line breaks with \n.  By that, the output
       of a Perl run should be stored into a Perl array, with a single line for each array member.

       This Perl array output can be stored by gperl in either

       groffstrings
              by creating a groff command .dsgroffregister
              by creating a groff command .rn

       The storage modes can be determined by arguments of a final stopping .Perl command.   Each  argument  .ds
       changes  the mode into groffstring and .nr changes the mode into groffregister for all following output
       parts.

       By default, all output is saved as strings, so .ds is not really needed before  the  first  .nr  command.
       That  suits to groff(7), because every output can be saved as groff string, but the registers can be very
       restrictive.

       In stringmode, gperl generates a groffstring storage line
              .dsvar_namecontent
       In registermode the following groff command is generated
              .nrvar_namecontent

       We present argument collections in the following.  You can add as first argument for all stop.   We  omit
       this additional element.

       .Perl.dsvar_name
              This  will  store  1 output line into the groff string named var_name by the automatically created
              command
                     .dsvar_nameoutput.Perlvar_name
              If var_name is different from start this is equivalent to the former command, because  the  string
              mode is string with .ds command.  default.

       .Perlvar_name1var_name2
              This  will  store  2  output  lines  into  groff string names var_name1 and var_name2, because the
              default mode .ds is active, such that no .ds argument is needed.  Of course, this is equivalent to
                     .Perl.dsvar_name1var_name2
              and
                     .Perl.dsvar_name1.dsvar_name2.Perl.nrvar_name1varname2
              stores both variables as register variables.  gperl generates
              .nrvar_name1output_line1.nrvar_name2output_line2.Perl.nrvar_name1.dsvar_name2
              stores the 1st argument as register and the second as string by
              .nrvar_name1output_line1.dsvar_name2output_line2

       Man pages related to groff are groff(1), groff(7), and grog(1).

       Documents related to Perl are perl(1), perl(7).

groff 1.23.0                                    26 December 2024                                        gperl(1)

gperl [file ...]

       gperl-hgperl--helpgperl-vgperl--version