Debian Codegraph @

upstream/debian-unstable/man1/gperl.1

raw
1 .TH gperl 1 "2026-04-22" "groff 1.24.1"
2 .SH Name
3 gperl \- execute Perl commands in
4 .I groff
5 documents
6 .
7 .
8 .\" ====================================================================
9 .\" Legal Terms
10 .\" ====================================================================
11 .\"
12 .\" Copyright 2014-2020 Free Software Foundation, Inc.
13 .\"
14 .\" This file is part of gperl.
15 .\"
16 .\" gperl is distributed with groff, the GNU roff typesetting system.
17 .\"
18 .\" groff is free software; you can redistribute it and/or modify it
19 .\" under the terms of the GNU General Public License as published by
20 .\" the Free Software Foundation, either version 3 of the License, or
21 .\" (at your option) any later version.
22 .\"
23 .\" groff is distributed in the hope that it will be useful, but WITHOUT
24 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
25 .\" or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
26 .\" License for more details.
27 .\"
28 .\" You should have received a copy of the GNU General Public License
29 .\" along with this program. If not, see
30 .\" <https://www.gnu.org/licenses/>.
31 .
32 .
33 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
34 .do nr *groff_gperl_1_man_C \n[.cp]
35 .cp 0
36 .
37 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
38 .nr do-fallback 0
39 .if !\n(.f .nr do-fallback 1 \" mandoc
40 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
41 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
42 .if \n[do-fallback] \{\
43 . de MR
44 . ie \\n(.$=1 \
45 . I \%\\$1
46 . el \
47 . IR \%\\$1 (\\$2)\\$3
48 . .
49 .\}
50 .rr do-fallback
51 .
52 .
53 .\" ====================================================================
54 .SH Synopsis
55 .\" ====================================================================
56 .
57 .SY gperl
58 .RI [ file\~ .\|.\|.]
59 .YS
60 .
61 .
62 .P
63 .SY gperl
64 .B \-h
65 .YS
66 .
67 .SY gperl
68 .B \-\-help
69 .YS
70 .
71 .
72 .P
73 .SY gperl
74 .B \-v
75 .YS
76 .
77 .SY gperl
78 .B \%\-\-version
79 .YS
80 .
81 .
82 .\" ====================================================================
83 .SH Description
84 .\" ====================================================================
85 .
86 This is a preprocessor for
87 .MR groff 1 .
88 .
89 It allows the use of
90 .MR perl 7
91 code in
92 .MR groff 7
93 files.
94 .
95 The result of a
96 .I Perl part
97 can be stored in groff
98 .I strings
99 or
100 .I numerical registers
101 based on the arguments at a final line of a
102 .IR "Perl part" .
103 .
104 .
105 .P
106 If no operands are given,
107 or if
108 .I file
109 is
110 .RB \[lq] \- \[rq],
111 .I gperl
112 reads the standard input stream.
113 .
114 A double-dash argument
115 .RB (\[lq] \-\- \[rq])
116 causes all subsequent arguments to be interpreted as
117 .I file
118 operands,
119 even if their names start with a dash.
120 .
121 .B \-h
122 and
123 .B \-\-help
124 display a usage message,
125 whereas
126 .B \-v
127 and
128 .B \%\-\-version
129 display version information;
130 all exit afterward.
131 .
132 .
133 .\" ====================================================================
134 .SH "Perl regions"
135 .\" ====================================================================
136 .
137 .I Perl
138 parts in
139 .I groff files
140 are enclosed by two
141 .B .Perl
142 requests with different arguments, a
143 .I starting
144 and an
145 .I ending
146 command.
147 .
148 .
149 .\" ====================================================================
150 .SS "Starting Perl mode"
151 .\" ====================================================================
152 .
153 The starting
154 .I Perl request
155 can either be without arguments, or by a request that has the term
156 .B start
157 as its only argument.
158 .RS
159 .IP \(bu
160 .B .Perl
161 .IP \(bu
162 .B .Perl start
163 .RE
164 .
165 .
166 .\" ====================================================================
167 .SS "Ending Perl mode without storage"
168 .\" ====================================================================
169 .
170 A
171 .B .Perl
172 command line with an argument different from
173 .B start
174 finishes a running
175 .IR "Perl part" .
176 .
177 Of course, it would be reasonable to add the argument
178 .BR stop ;
179 that's possible, but not necessary.
180 .
181 .RS
182 .IP \(bu
183 .B .Perl stop
184 .IP \(bu
185 .BI .Perl " other_than_start"
186 .RE
187 .
188 The argument
189 .I other_than_start
190 can additionally be used as a
191 .I groff
192 string variable name for storage \(em see next section.
193 .
194 .
195 .\" ====================================================================
196 .SS "Ending Perl mode with storage"
197 .\" ====================================================================
198 .
199 A useful feature of
200 .I gperl
201 is to store one or more results from the
202 .IR "Perl mode" .
203 .
204 .
205 .P
206 The output of a
207 .I Perl part
208 can be got with backticks
209 .BR \[ga]...\[ga] .
210 .
211 .
212 .P
213 This program collects all printing to STDOUT (normal standard output)
214 by the Perl
215 .B print
216 program.
217 .
218 This pseudo-printing output can have several lines, due to printed
219 line breaks with
220 .BR \(rsn .
221 .
222 By that, the output of a Perl run should be stored into a Perl array,
223 with a single line for each array member.
224 .
225 .
226 .P
227 This Perl array output can be stored by
228 .I gperl
229 in either
230 .TP
231 .I groff strings
232 by creating a groff command
233 .B .ds
234 .
235 .TP
236 .I groff register
237 by creating a groff command
238 .B .rn
239 .
240 .
241 .P
242 The storage modes can be determined by arguments of a final stopping
243 .B .Perl
244 command.
245 .
246 Each argument
247 .B .ds
248 changes the mode into
249 .I groff string
250 and
251 .B .nr
252 changes the mode into
253 .I groff register
254 for all following output parts.
255 .
256 .
257 .br
258 .ne 2v
259 .P
260 By default, all output is saved as strings, so
261 .B .ds
262 is not really needed before the first
263 .B .nr
264 command.
265 .
266 That suits to
267 .MR groff 7 ,
268 because every output can be saved as
269 .I groff
270 string, but the registers can be very restrictive.
271 .
272 .
273 .P
274 In
275 .IR "string mode" ,
276 .I gperl
277 generates a
278 .I groff string
279 storage line
280 .RS
281 .EX
282 .BI .ds " var_name content"
283 .EE
284 .RE
285 .
286 In
287 .I register mode
288 the following groff command is generated
289 .RS
290 .EX
291 .BI .nr " var_name content"
292 .EE
293 .RE
294 .
295 .
296 .P
297 We present argument collections in the following.
298 .
299 You can add as first argument for all
300 .BR stop .
301 .
302 We omit this additional element.
303 .
304 .
305 .P
306 .TP
307 .BI ".Perl .ds " var_name
308 This will store 1 output line into the groff string named
309 .I var_name
310 by the automatically created command
311 .RS
312 .RS
313 .EX
314 .BI .ds " var_name output"
315 .EE
316 .RE
317 .RE
318 .
319 .
320 .TP
321 .BI .Perl " var_name"
322 If
323 .I var_name
324 is different from
325 .B start
326 this is equivalent to the former command, because the string mode is
327 string with
328 .B .ds
329 command.
330 default.
331 .
332 .
333 .TP
334 .BI .Perl " var_name1 var_name2"
335 This will store 2 output lines into groff string names
336 .I var_name1
337 and
338 .IR var_name2 ,
339 because the default mode
340 .B .ds
341 is active, such that no
342 .B .ds
343 argument is needed.
344 .
345 Of course, this is equivalent to
346 .RS
347 .RS
348 .EX
349 .BI ".Perl .ds " "var_name1 var_name2"
350 .EE
351 .RE
352 and
353 .RS
354 .EX
355 .BI ".Perl .ds " "var_name1 " ".ds" " var_name2"
356 .EE
357 .RE
358 .RE
359 .
360 .
361 .TP
362 .BI ".Perl .nr" " var_name1 varname2"
363 stores both variables as register variables.
364 .
365 .I gperl
366 generates
367 .RS
368 .EX
369 .BI .nr " var_name1 output_line1"
370 .BI .nr " var_name2 output_line2"
371 .EE
372 .RE
373 .
374 .
375 .TP
376 .BI ".Perl .nr " var_name1 " .ds " var_name2
377 stores the 1st argument as
378 .I register
379 and the second as
380 .I string
381 by
382 .RS
383 .EX
384 .BI .nr " var_name1 output_line1"
385 .BI .ds " var_name2 output_line2"
386 .EE
387 .RE
388 .
389 .
390 .\" ====================================================================
391 .SH Example
392 .\" ====================================================================
393 .
394 A possible
395 .I Perl part
396 in a
397 .I roff file
398 could look like that:
399 .RS
400 .EX
401 before
402 \&.Perl start
403 my $result = \[aq]some data\[aq];
404 print $result;
405 \&.Perl stop .ds string_var
406 after
407 .EE
408 .RE
409 .
410 .
411 .P
412 This stores the result
413 .B \(rqsome data\(rq
414 into the
415 .I roff string
416 called
417 .BR string_var ,
418 such that the following line is printed:
419 .RS
420 .EX
421 \&.ds string_var some data
422 .EE
423 .RE
424 by
425 .I gperl
426 as food for the coming
427 .I groff
428 run.
429 .
430 .
431 .P
432 A
433 .I Perl part
434 with several outputs is:
435 .RS
436 .EX
437 \&.Perl start
438 print \(rqfirst\(rsn\(rq;
439 print \(rqsecond line\(rsn\(rq;
440 print \(rq3\(rsn\(rq;
441 \&.Perl var1 var2 .nr var3
442 .EE
443 .RE
444 .
445 This stores 3 printed lines into 3
446 .I groff
447 strings.
448 .BR var1 , var2 , var3 .
449 .
450 So the following
451 .I groff
452 command lines are created:
453 .RS
454 .EX
455 \&.ds var1 first
456 \&.ds var2 second line
457 \&.nr var3 3
458 .EE
459 .RE
460 .
461 .
462 .\" ====================================================================
463 .SH Authors
464 .\" ====================================================================
465 .
466 .I gperl
467 was written by
468 .MT groff\-bernd\:.warken\-72@\:web\:.de
469 Bernd Warken
470 .ME .
471 .
472 .
473 .\" ====================================================================
474 .SH "See also"
475 .\" ====================================================================
476 .
477 .P
478 Man pages related to
479 .I groff
480 are
481 .MR groff 1 ,
482 .MR groff 7 ,
483 and
484 .MR grog 1 .
485 .
486 .
487 .P
488 Documents related to
489 .I Perl
490 are
491 .MR perl 1 ,
492 .MR perl 7 .
493 .
494 .
495 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
496 .cp \n[*groff_gperl_1_man_C]
497 .do rr *groff_gperl_1_man_C
498 .
499 .
500 .\" Local Variables:
501 .\" fill-column: 72
502 .\" mode: nroff
503 .\" End:
504 .\" vim: set filetype=groff textwidth=72: