NAMEgperl - groff preprocessor for Perl parts in roff files
SYNOPSIS[ - ] [ -- ] [ filespec ... ] gperl -h|--help
DESCRIPTIONThis is a preprocesor for groff(1). It allows to add perl(7) code into groff(7) files. The result of a Perl part can be stored in groff strings or numerical registers based on the arguments at a final line of a Perl part.
OPTIONSSo far, there are only filespec or breaking options. filespec are file names or the minus character - character for standard input. As usual, the argument -- can be used in order to let all fowllowing arguments mean file names, even if the names begin with a minus character -. An option is breaking, when the program just writes the information that was asked for and then stops. All other arguments will be ignored by that. These breaking options are heree
- Print help information with a short explanation of options to standard output.
- Print version information to standard output.
PERL PARTSPerl parts in groff files are enclosed by two .Perl requests with different arguments, a starting and an ending command.
Starting Perl ModeThe starting Perl request can either be without arguments, or by a request that has the term start as its only argument.
- .Perl start
Ending Perl Mode without StorageA .Perl command line with an argument different from start finishes a running Perl part. Of course, it would be reasonable to add the argument stop; that's possible, but not necessary.
- .Perl stop
- .Perl other_than_start
Ending Perl Mode with StorageA useful feature of gperl is to store one or more results from the Perl mode. The output of a Perl part can be got with backticks `...`. This program collects all printing to STDOUT (normal standard output) by the Perl print program. This pseudo-printing output can have several lines, due to printed line breaks with [rs]n. By that, the output of a Perl run should be stored into a Perl array, with a single line for each array member. This Perl array output can be stored by gperl in either
- groff strings
- by creating a groff command .ds
- groff number register
by creating a groff command
The storage modes can be determined by arguments of a final stopping
changes the mode into
changes the mode into
groff number register
for all following output parts.
By default, all output is saved as strings, so
is not really needed before the first
That suits to
because every output can be saved as
string, but the number registers can be very restrictive.
- .ds var_name content
- .nr var_name content
- .Perl .ds var_name
This will store 1 output line into the groff string named
by the automatically created command
- .ds var_name output
- .Perl var_name
- If var_name is different from start this is equivalent to the former command, because the string mode is string with .ds command. default.
- .Perl var_name1 var_name2
This will store 2 output lines into groff string names
because the default mode
is active, such that no
argument is needed.
Of course, this is equivalent to
- .Perl .ds var_name1 var_name2
- .Perl .ds var_name1 .ds var_name2
- .Perl .nr var_name1 varname2
stores both variables as number register variables.
- .nr var_name1 output_line1 .nr var_name2 output_line2
- .Perl .nr var_name1 .ds var_name2
stores the 1st argument as
and the second as
- .nr var_name1 output_line1 .ds var_name2 output_line2
Printing towards STDERR is without StorageThe printing towards STDERR, (standard error) works as usual. All error information goes to the real normal standard error, without other automatical storage.
EXAMPLESA possible Perl part in a roff file could look like that:
- before .Perl start my $result = 'some data'; print $result; .Perl stop .ds string_var after
- .ds string_var some data
- .Perl start print [rq]first[rs]n[rq]; print [rq]second line[rs]n[rq]; print [rq]3[rs]n[rq]; .Perl var1 var2 .nr var3
- .ds var1 first .ds var2 second line .nr var3 3