diff options
Diffstat (limited to '')
| -rw-r--r-- | contrib/gperl/gperl.1.man | 491 |
1 files changed, 491 insertions, 0 deletions
diff --git a/contrib/gperl/gperl.1.man b/contrib/gperl/gperl.1.man new file mode 100644 index 0000000..14afdcf --- /dev/null +++ b/contrib/gperl/gperl.1.man @@ -0,0 +1,491 @@ +.TH gperl @MAN1EXT@ "@MDATE@" "groff @VERSION@" +.SH Name +gperl \- execute Perl commands in +.I groff +documents +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 2014-2020 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 +.\" <http://www.gnu.org/licenses/gpl-2.0.html>. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_gperl_1_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY gperl +.RI [ file\~ .\|.\|.] +.YS +. +. +.SY gperl +.B \-h +. +.SY gperl +.B \-\-help +.YS +. +.SY gperl +.B \-v +. +.SY gperl +.B \-\-version +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +This is a preprocessor for +.MR groff @MAN1EXT@ . +. +It allows the use of +.MR perl 7 +code in +.MR groff @MAN7EXT@ +files. +. +The result of a +.I Perl part +can be stored in groff +.I strings +or +.I numerical registers +based on the arguments at a final line of a +.IR "Perl part" . +. +. +.P +If no operands are given, +or if +.I file +is +.RB \[lq] \- \[rq], +.I gperl +reads the standard input stream. +. +A double-dash argument +.RB (\[lq] \-\- \[rq]) +causes all subsequent arguments to be interpreted as +.I file +operands, +even if their names start with a dash. +. +.B \-h +and +.B \-\-help +display a usage message, +whereas +.B \-v +and +.B \-\-version +display version information; +all exit afterward. +. +. +.\" ==================================================================== +.SH "Perl regions" +.\" ==================================================================== +. +.I Perl +parts in +.I groff files +are enclosed by two +.B .Perl +requests with different arguments, a +.I starting +and an +.I ending +command. +. +. +.\" ==================================================================== +.SS "Starting Perl mode" +.\" ==================================================================== +. +The starting +.I Perl request +can either be without arguments, or by a request that has the term +.B start +as its only argument. +.RS +.IP \(bu +.B .Perl +.IP \(bu +.B .Perl start +.RE +. +. +.\" ==================================================================== +.SS "Ending Perl mode without storage" +.\" ==================================================================== +. +A +.B .Perl +command line with an argument different from +.B start +finishes a running +.IR "Perl part" . +. +Of course, it would be reasonable to add the argument +.BR stop ; +that's possible, but not necessary. +. +.RS +.IP \(bu +.B .Perl stop +.IP \(bu +.BI .Perl " other_than_start" +.RE +. +The argument +.I other_than_start +can additionally be used as a +.I groff +string variable name for storage \(em see next section. +. +. +.\" ==================================================================== +.SS "Ending Perl mode with storage" +.\" ==================================================================== +. +A useful feature of +.I gperl +is to store one or more results from the +.IR "Perl mode" . +. +. +.P +The output of a +.I Perl part +can be got with backticks +.BR \[ga]...\[ga] . +. +. +.P +This program collects all printing to STDOUT (normal standard output) +by the Perl +.B print +program. +. +This pseudo-printing output can have several lines, due to printed +line breaks with +.BR \(rsn . +. +By that, the output of a Perl run should be stored into a Perl array, +with a single line for each array member. +. +. +.P +This Perl array output can be stored by +.I gperl +in either +.TP +.I groff strings +by creating a groff command +.B .ds +. +.TP +.I groff register +by creating a groff command +.B .rn +. +. +.P +The storage modes can be determined by arguments of a final stopping +.B .Perl +command. +. +Each argument +.B .ds +changes the mode into +.I groff string +and +.B .nr +changes the mode into +.I groff register +for all following output parts. +. +. +.br +.ne 2v +.P +By default, all output is saved as strings, so +.B .ds +is not really needed before the first +.B .nr +command. +. +That suits to +.MR groff @MAN7EXT@ , +because every output can be saved as +.I groff +string, but the registers can be very restrictive. +. +. +.P +In +.IR "string mode" , +.I gperl +generates a +.I groff string +storage line +.RS +.EX +.BI .ds " var_name content" +.EE +.RE +. +In +.I register mode +the following groff command is generated +.RS +.EX +.BI .nr " var_name content" +.EE +.RE +. +. +.P +We present argument collections in the following. +. +You can add as first argument for all +.BR stop . +. +We omit this additional element. +. +. +.P +.TP +.BI ".Perl .ds " var_name +This will store 1 output line into the groff string named +.I var_name +by the automatically created command +.RS +.RS +.EX +.BI .ds " var_name output" +.EE +.RE +.RE +. +. +.TP +.BI .Perl " var_name" +If +.I var_name +is different from +.B start +this is equivalent to the former command, because the string mode is +string with +.B .ds +command. +default. +. +. +.TP +.BI .Perl " var_name1 var_name2" +This will store 2 output lines into groff string names +.I var_name1 +and +.IR var_name2 , +because the default mode +.B .ds +is active, such that no +.B .ds +argument is needed. +. +Of course, this is equivalent to +.RS +.RS +.EX +.BI ".Perl .ds " "var_name1 var_name2" +.EE +.RE +and +.RS +.EX +.BI ".Perl .ds " "var_name1 " ".ds" " var_name2" +.EE +.RE +.RE +. +. +.TP +.BI ".Perl .nr" " var_name1 varname2" +stores both variables as register variables. +. +.I gperl +generates +.RS +.EX +.BI .nr " var_name1 output_line1" +.BI .nr " var_name2 output_line2" +.EE +.RE +. +. +.TP +.BI ".Perl .nr " var_name1 " .ds " var_name2 +stores the 1st argument as +.I register +and the second as +.I string +by +.RS +.EX +.BI .nr " var_name1 output_line1" +.BI .ds " var_name2 output_line2" +.EE +.RE +. +. +.\" ==================================================================== +.SH Example +.\" ==================================================================== +. +A possible +.I Perl part +in a +.I roff file +could look like that: +.RS +.EX +before +\&.Perl start +my $result = \[aq]some data\[aq]; +print $result; +\&.Perl stop .ds string_var +after +.EE +.RE +. +. +.P +This stores the result +.B \(rqsome data\(rq +into the +.I roff string +called +.BR string_var , +such that the following line is printed: +.RS +.EX +\&.ds string_var some data +.EE +.RE +by +.I gperl +as food for the coming +.I groff +run. +. +. +.P +A +.I Perl part +with several outputs is: +.RS +.EX +\&.Perl start +print \(rqfirst\(rsn\(rq; +print \(rqsecond line\(rsn\(rq; +print \(rq3\(rsn\(rq; +\&.Perl var1 var2 .nr var3 +.EE +.RE +. +This stores 3 printed lines into 3 +.I groff +strings. +.BR var1 , var2 , var3 . +. +So the following +.I groff +command lines are created: +.RS +.EX +\&.ds var1 first +\&.ds var2 second line +\&.nr var3 3 +.EE +.RE +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +.I gperl +was written by +.MT groff\-bernd\:.warken\-72@\:web\:.de +Bernd Warken +.ME . +. +. +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +.P +Man pages related to +.I groff +are +.MR groff @MAN1EXT@ , +.MR groff @MAN7EXT@ , +and +.MR grog @MAN1EXT@ . +. +. +.P +Documents related to +.I Perl +are +.MR perl 1 , +.MR perl 7 . +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_gperl_1_man_C] +.do rr *groff_gperl_1_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: |