gperl(1) - f33

1GPERL(1)                    General Commands Manual                   GPERL(1)
2
3
4

NAME

6       gperl - groff preprocessor for Perl parts in roff files
7

SYNOPSIS

9       gperl [filespec ...]
10
11       gperl -h
12       gperl --help
13
14       gperl -v
15       gperl --version
16

DESCRIPTION

18       This is a preprocessor for groff(1).  It allows the use of perl(7) code
19       in groff(7) files.  The result of a Perl part can be  stored  in  groff
20       strings  or  numerical registers based on the arguments at a final line
21       of a Perl part.
22

OPTIONS

24       So far, there are only filespec or breaking options.
25
26       filespec are file names or the minus character - character for standard
27       input.   As usual, the argument -- can be used in order to let all fol‐
28       lowing arguments mean file names, even if the names begin with a  minus
29       character -.
30
31       An  option  is  breaking,  when the program just writes the information
32       that was asked for and then stops.  All other arguments will be ignored
33       by that.  These breaking options are here
34
35       -h | --help
36              Print  help  information  with a short explanation of options to
37              standard output.
38
39       -v | --version
40              Print version information to standard output.
41

PERL PARTS

43       Perl parts in groff files are enclosed by two .Perl requests with  dif‐
44       ferent arguments, a starting and an ending command.
45
46   Starting Perl Mode
47       The  starting  Perl  request  can  either be without arguments, or by a
48       request that has the term start as its only argument.
49
50              * .Perl
51
52              * .Perl start
53
54   Ending Perl Mode without Storage
55       A .Perl command line with an argument different from start  finishes  a
56       running  Perl part.  Of course, it would be reasonable to add the argu‐
57       ment stop; that's possible, but not necessary.
58
59              * .Perl stop
60
61              * .Perl other_than_start
62       The argument other_than_start can  additionally  be  used  as  a  groff
63       string variable name for storage — see next section.
64
65   Ending Perl Mode with Storage
66       A useful feature of gperl is to store one or more results from the Perl
67       mode.
68
69       The output of a Perl part can be got with backticks `...`.
70
71       This program collects all printing to STDOUT (normal  standard  output)
72       by  the  Perl print program.  This pseudo-printing output can have sev‐
73       eral lines, due to printed line breaks with \n.  By that, the output of
74       a  Perl  run should be stored into a Perl array, with a single line for
75       each array member.
76
77       This Perl array output can be stored by gperl in either
78
79       groff strings
80              by creating a groff command .ds
81
82       groff number register
83              by creating a groff command .rn
84
85       The storage modes can be determined by arguments of  a  final  stopping
86       .Perl  command.   Each  argument .ds changes the mode into groff string
87       and .nr changes the mode into groff number register for  all  following
88       output parts.
89
90       By default, all output is saved as strings, so .ds is not really needed
91       before the first .nr command.  That suits to  groff(7),  because  every
92       output  can  be  saved as groff string, but the number registers can be
93       very restrictive.
94
95       In string mode, gperl generates a groff string storage line
96              .ds var_name content
97       In number register mode the following groff command is generated
98              .nr var_name content
99
100       We present argument collections in the following.  You can add as first
101       argument for all stop.  We omit this additional element.
102
103       .Perl .ds var_name
104              This  will  store  1  output  line  into  the groff string named
105              var_name by the automatically created command
106                     .ds var_name output
107
108       .Perl var_name
109              If var_name is different from start this is  equivalent  to  the
110              former  command, because the string mode is string with .ds com‐
111              mand.  default.
112
113       .Perl var_name1 var_name2
114              This will store 2 output lines into groff string names var_name1
115              and var_name2, because the default mode .ds is active, such that
116              no .ds argument is needed.  Of course, this is equivalent to
117                     .Perl .ds var_name1 var_name2
118              and
119                     .Perl .ds var_name1 .ds var_name2
120
121       .Perl .nr var_name1 varname2
122              stores both variables as number register variables.  gperl  gen‐
123              erates
124              .nr var_name1 output_line1
125              .nr var_name2 output_line2
126
127       .Perl .nr var_name1 .ds var_name2
128              stores  the  1st  argument  as number register and the second as
129              string by
130              .nr var_name1 output_line1
131              .ds var_name2 output_line2
132
133   Printing towards STDERR is without Storage
134       The printing towards STDERR, (standard  error)  works  as  usual.   All
135       error information goes to the real normal standard error, without other
136       automatic storage.
137

EXAMPLES

139       A possible Perl part in a roff file could look like that:
140              before
141              .Perl start
142              my $result = 'some data';
143              print $result;
144              .Perl stop .ds string_var
145              after
146
147       This stores  the  result  ”some  data”  into  the  roff  string  called
148       string_var, such that the following line is printed:
149              .ds string_var some data
150       by gperl as food for the coming groff run.
151
152       A Perl part with several outputs is:
153              .Perl start
154              print ”first\n”;
155              print ”second line\n”;
156              print ”3\n”;
157              .Perl var1 var2 .nr var3
158       This  stores 3 printed lines into 3 groff strings.  var1,var2,var3.  So
159       the following groff command lines are created:
160              .ds var1 first
161              .ds var2 second line
162              .nr var3 3
163

AUTHORS

165       gperl was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.
166