1GPERL(1) General Commands Manual GPERL(1)
2
6 gperl - groff preprocessor for Perl parts in roff files
7
9 gperl [-] [--] [ filespec ....]
10 gperl -h|--help
11 gperl -v|--version
12
14 This is a preprocesor for groff(1). It allows to add perl(7) code into
15 groff(7) files. The result of a Perl part can be stored in groff
16 strings or numerical registers based on the arguments at a final line
17 of a Perl part.
18
20 So far, there are only filespec or breaking options.
21 filespec are file names or the minus character - character for standard
23 input. As usual, the argument -- can be used in order to let all fowl‐
24 lowing arguments mean file names, even if the names begin with a minus
25 character -.
26 An option is breaking, when the program just writes the information
28 that was asked for and then stops. All other arguments will be ignored
29 by that. These breaking options are heree
30 -h | --help
32 Print help information with a short explanation of options to
33 standard output.
34 -v | --version
36 Print version information to standard output.
37
39 Perl parts in groff files are enclosed by two .Perl requests with dif‐
40 ferent arguments, a starting and an ending command.
41 Starting Perl Mode
43 The starting Perl request can either be without arguments, or by a
44 request that has the term start as its only argument.
45 * .Perl
47 * .Perl start
49 Ending Perl Mode without Storage
51 A .Perl command line with an argument different from start finishes a
52 running Perl part. Of course, it would be reasonable to add the argu‐
53 ment stop; that's possible, but not necessary.
54 * .Perl stop
56 * .Perl other_than_start
58 The argument other_than_start can additionally be used as a groff
59 string variable name for storage — see next section.
60 Ending Perl Mode with Storage
62 A useful feature of gperl is to store one or more results from the Perl
63 mode.
64 The output of a Perl part can be got with backticks `...`.
66 This program collects all printing to STDOUT (normal standard output)
68 by the Perl print program. This pseudo-printing output can have sev‐
69 eral lines, due to printed line breaks with \n. By that, the output of
70 a Perl run should be stored into a Perl array, with a single line for
71 each array member.
72 This Perl array output can be stored by gperl in either
74 groff strings
76 by creating a groff command .ds
77 groff number register
79 by creating a groff command .rn
80 The storage modes can be determined by arguments of a final stopping
82 .Perl command. Each argument .ds changes the mode into groff string
83 and .nr changes the mode into groff number register for all following
84 output parts.
85 By default, all output is saved as strings, so .ds is not really needed
87 before the first .nr command. That suits to groff(7), because every
88 output can be saved as groff string, but the number registers can be
89 very restrictive.
90 In string mode, gperl generates a groff string storage line
92 .ds var_name content
93 In number register mode the following groff command is generated
94 .nr var_name content
95 We present argument collections in the following. You can add as first
97 argument for all stop. We omit this additional element.
98 .Perl .ds var_name
100 This will store 1 output line into the groff string named
101 var_name by the automatically created command
102 .ds var_name output
103 .Perl var_name
105 If var_name is different from start this is equivalent to the
106 former command, because the string mode is string with .ds com‐
107 mand. default.
108 .Perl var_name1 var_name2
110 This will store 2 output lines into groff string names var_name1
111 and var_name2, because the default mode .ds is active, such that
112 no .ds argument is needed. Of course, this is equivalent to
113 .Perl .ds var_name1 var_name2
114 and
115 .Perl .ds var_name1 .ds var_name2
116 .Perl .nr var_name1 varname2
118 stores both variables as number register variables. gperl gen‐
119 erates
120 .nr var_name1 output_line1
121 .nr var_name2 output_line2
122 .Perl .nr var_name1 .ds var_name2
124 stores the 1st argument as number register and the second as
125 string by
126 .nr var_name1 output_line1
127 .ds var_name2 output_line2
128 Printing towards STDERR is without Storage
130 The printing towards STDERR, (standard error) works as usual. All
131 error information goes to the real normal standard error, without other
132 automatical storage.
133
135 A possible Perl part in a roff file could look like that:
136 before
137 .Perl start
138 my $result = 'some data';
139 print $result;
140 .Perl stop .ds string_var
141 after
142 This stores the result ”some data” into the roff string called
144 string_var, such that the following line is printed:
145 .ds string_var some data
146 by gperl as food for the coming groff run.
147 A Perl part with several outputs is:
149 .Perl start
150 print ”first\n”;
151 print ”second line\n”;
152 print ”3\n”;
153 .Perl var1 var2 .nr var3
154 This stores 3 printed lines into 3 groff strings. var1,var2,var3. So
155 the following groff command lines are created:
156 .ds var1 first
157 .ds var2 second line
158 .nr var3 3
159
161 Man-pages related to groff are groff(1), groff(7), grog(1), and
162 groffer(1).
163 Documents related to Perl are perl(1), perl(7).
165
167 Copyright © 2014 Free Software Foundation, Inc.
168 This file is part of gperl, which is part of groff, a free software
170 project. You can redistribute it and/or modify it under the terms of
171 the GNU General Public License as published by the Free Software
172 Foundation, version 2.
173 The license text is available in the internet at
175 ⟨http://www.gnu.org/licenses/gpl-2.0.html⟩.
176
178 This file was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.
179Groff Version 1.22.3 4 November 2014 GPERL(1)