Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, February 9, 2022

gperl (1)


gperl - groff preprocessor for Perl parts in roff files


gperl [-] [--] [ filespec ....]
gperl -h|--help
gperl -v|--version


GPERL(1)                    General Commands Manual                   GPERL(1)

       gperl - groff preprocessor for Perl parts in roff files

       gperl [-] [--] [ filespec ....]
       gperl -h|--help
       gperl -v|--version

       This is a preprocesor for groff(1).  It allows to add perl(7) code into
       groff(7) files.  The result of a Perl  part  can  be  stored  in  groff
       strings  or  numerical registers based on the arguments at a final line
       of a Perl part.

       So far, there are only filespec or breaking options.

       filespec are file names or the minus character - character for standard
       input.  As usual, the argument -- can be used in order to let all fowl-
       lowing arguments mean file names, even if the names begin with a  minus
       character -.

       An  option  is  breaking,  when the program just writes the information
       that was asked for and then stops.  All other arguments will be ignored
       by that.  These breaking options are heree

       -h | --help
              Print  help  information  with a short explanation of options to
              standard output.

       -v | --version
              Print version information to standard output.

       Perl parts in groff files are enclosed by two .Perl requests with  dif-
       ferent arguments, a starting and an ending command.

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

              * .Perl

              * .Perl start

   Ending Perl Mode without Storage
       A .Perl command line with an argument different from start  finishes  a
       running  Perl part.  Of course, it would be reasonable to add the argu-
       ment stop; that's possible, but not necessary.

              * .Perl stop

              * .Perl other_than_start
       The argument other_than_start can  additionally  be  used  as  a  groff
       string variable name for storage -- see next section.

   Ending Perl Mode with Storage
       A useful feature of gperl is to store one or more results from the Perl

       The output of a Perl part 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 sev-
       eral 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

       groff strings
              by creating a groff command .ds

       groff number register
              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 groff string
       and .nr changes the mode into groff number register 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 number registers can be
       very restrictive.

       In string mode, gperl generates a groff string storage line
              .ds var_name content
       In number register mode the following groff command is generated
              .nr var_name content

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

       .Perl .ds var_name
              This  will  store  1  output  line  into  the groff string named
              var_name by the automatically created command
                     .ds var_name output

       .Perl var_name
              If var_name is different from start this is  equivalent  to  the
              former  command, because the string mode is string with .ds com-
              mand.  default.

       .Perl var_name1 var_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 .ds var_name1 var_name2
                     .Perl .ds var_name1 .ds var_name2

       .Perl .nr var_name1 varname2
              stores both variables as number register variables.  gperl  gen-
              .nr var_name1 output_line1
              .nr var_name2 output_line2

       .Perl .nr var_name1 .ds var_name2
              stores  the  1st  argument  as number register and the second as
              string by
              .nr var_name1 output_line1
              .ds var_name2 output_line2

   Printing towards STDERR is without Storage
       The printing towards STDERR, (standard  error)  works  as  usual.   All
       error information goes to the real normal standard error, without other
       automatical storage.

       A possible Perl part in a roff file could look like that:
              .Perl start
              my $result = 'some data';
              print $result;
              .Perl stop .ds string_var

       This stores  the  result  "some  data"  into  the  roff  string  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 Perl part 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

       See attributes(7) for descriptions of the following attributes:

       |Availability   | text/groff       |
       |Stability      | Uncommitted      |

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

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

       Copyright (C) 2014 Free Software Foundation, Inc.

       This  file  is  part  of gperl, which is part of groff, a free software
       project.  You can redistribute it and/or modify it under the  terms  of
       the  GNU  General  Public  License  as  published  by the Free Software
       Foundation, version 2.

       The   license    text    is    available    in    the    internet    at

       This file was written by Bernd Warken <groff-bernd.warken-72@web.de>.

       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source                was                downloaded                from

       Further information about this software can be found on the open source
       community website at https://www.gnu.org/software/groff.

Groff Version 1.22.3            4 November 2014                       GPERL(1)