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
12 gperl --help
13 gperl -v
15 gperl --version
16
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
24 So far, there are only filespec or breaking options.
25 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 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 -h | --help
36 Print help information with a short explanation of options to
37 standard output.
38 -v | --version
40 Print version information to standard output.
41
43 Perl parts in groff files are enclosed by two .Perl requests with dif‐
44 ferent arguments, a starting and an ending command.
45 Starting Perl Mode
47 The starting Perl request can either be without arguments, or by a re‐
48 quest that has the term start as its only argument.
49 * .Perl
51 * .Perl start
53 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 * .Perl stop
60 * .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 Ending Perl Mode with Storage
66 A useful feature of gperl is to store one or more results from the Perl
67 mode.
68 The output of a Perl part can be got with backticks `...`.
70 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 This Perl array output can be stored by gperl in either
78 groff strings
80 by creating a groff command .ds
81 groff number register
83 by creating a groff command .rn
84 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 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 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 We present argument collections in the following. You can add as first
101 argument for all stop. We omit this additional element.
102 .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 .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 .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 .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 .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 Printing towards STDERR is without Storage
134 The printing towards STDERR, (standard error) works as usual. All er‐
135 ror information goes to the real normal standard error, without other
136 automatic storage.
137
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 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 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
165 gperl was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.
166
168 Man pages related to groff are groff(1), groff(7), grog(1), and
169 groffer(1).
170 Documents related to Perl are perl(1), perl(7).
172groff 1.22.4 17 March 2021 GPERL(1)