-.TH GPERL @MAN1EXT@ "@MDATE@" "groff @VERSION@"
-.SH NAME
-gperl \- groff preprocessor for Perl parts in roff files
+.TH gperl @MAN1EXT@ "@MDATE@" "groff @VERSION@"
+.SH Name
+gperl \- execute Perl commands in
+.I groff
+documents
+.
.
.\" ====================================================================
.\" Legal Terms
.\" ====================================================================
.\"
-.\" Copyright (C) 2014-2018 Free Software Foundation, Inc.
+.\" Copyright (C) 2014-2020 Free Software Foundation, Inc.
.\"
.\" This file is part of gperl, which is part of groff, a free software
.\" project.
.\" The license text is available in the internet at
.\" <http://www.gnu.org/licenses/gpl-2.0.html>.
.
-.\" ====================================================================
-.\" Characters
-.\" ====================================================================
.
-.\" Ellipsis ...
-.ie t .ds EL \fS\N'188'\fP\"
-.el .ds EL \&.\|.\|.\&\"
-.\" called with \*(EL
+.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
+.do nr *groff_gperl_1_man_C \n[.cp]
+.cp 0
.
-.\" Bullet
-.ie t .ds BU \(bu
-.el .ds BU *
-.\" used in '.IP \*(BU 2m' (former .Topic)
+.\" 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"
+.SH Synopsis
.\" ====================================================================
.
.SY gperl
-.RI [ filespec
-\*(EL]
+.RI [ file\~ .\|.\|.]
.YS
.
+.
.SY gperl
.B \-h
+.
.SY gperl
.B \-\-help
.YS
.
.SY gperl
.B \-v
+.
.SY gperl
.B \-\-version
.YS
.
.
.\" ====================================================================
-.SH DESCRIPTION
+.SH Description
.\" ====================================================================
.
This is a preprocessor for
-.BR \%groff (@MAN1EXT@).
+.MR groff @MAN1EXT@ .
.
It allows the use of
-.BR perl (7)
+.MR perl 7
code in
-.BR groff (7)
+.MR groff @MAN7EXT@
files.
.
The result of a
.IR "Perl part" .
.
.
-.\" ====================================================================
-.SH "OPTIONS"
-.\" ====================================================================
-.
-So far, there are only
-.I filespec
-or
-.I breaking
-options.
-.
-.
-.P
-.I filespec
-are file names or the minus character
-.B \-
-character for standard input.
-.
-As usual, the argument
-.B \-\-
-can be used in order to let all following arguments mean file names,
-even if the names begin with a minus character
-.BR \- .
-.
-.
.P
-An option is
-.IR breaking ,
-when the program just writes the information that was asked for and
-then stops.
-.
-All other arguments will be ignored by that.
-.
-These
-.I breaking
-options are here
-.
-.TP
-.B \-h\~\fR|\fB\~\-\-help
-Print help information with a short explanation of options to
-standard output.
-.
+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.
.
-.TP
-.B \-v\~\fR|\fB\~\-\-version
-Print version information to standard output.
+.B \-h
+and
+.B \-\-help
+display a usage message,
+whereas
+.B \-v
+and
+.B \-\-version
+display version information;
+all exit afterward.
.
.
.\" ====================================================================
-.SH "PERL PARTS"
+.SH "Perl regions"
.\" ====================================================================
.
.I Perl
.
.
.\" ====================================================================
-.SS "Starting Perl Mode"
+.SS "Starting Perl mode"
.\" ====================================================================
.
The starting
.B start
as its only argument.
.RS
-.IP \*(BU 2m
+.IP \(bu
.B .Perl
-.IP \*(BU 2m
+.IP \(bu
.B .Perl start
.RE
.
.
.\" ====================================================================
-.SS "Ending Perl Mode without Storage"
+.SS "Ending Perl mode without storage"
.\" ====================================================================
.
A
that's possible, but not necessary.
.
.RS
-.IP \*(BU 2m
+.IP \(bu
.B .Perl stop
-.IP \*(BU 2m
+.IP \(bu
.BI .Perl " other_than_start"
.RE
.
.
.
.\" ====================================================================
-.SS "Ending Perl Mode with Storage"
+.SS "Ending Perl mode with storage"
.\" ====================================================================
.
A useful feature of
-.B gperl
+.I gperl
is to store one or more results from the
.IR "Perl mode" .
.
.
.P
This Perl array output can be stored by
-.B gperl
+.I gperl
in either
.TP
.I groff strings
.B .ds
.
.TP
-.I groff number register
+.I groff register
by creating a groff command
.B .rn
.
and
.B .nr
changes the mode into
-.I groff number register
+.I groff register
for all following output parts.
.
.
+.br
+.ne 2v
.P
By default, all output is saved as strings, so
.B .ds
command.
.
That suits to
-.BR \%groff (@MAN7EXT@),
+.MR groff @MAN7EXT@ ,
because every output can be saved as
.I groff
-string, but the number registers can be very restrictive.
+string, but the registers can be very restrictive.
.
.
.P
In
.IR "string mode" ,
-.B gperl
+.I gperl
generates a
.I groff string
storage line
.RE
.
In
-.I number register mode
+.I register mode
the following groff command is generated
.RS
.EX
.
.TP
.BI ".Perl .nr" " var_name1 varname2"
-stores both variables as number register variables.
+stores both variables as register variables.
.
-.B gperl
+.I gperl
generates
.RS
.EX
.TP
.BI ".Perl .nr " var_name1 " .ds " var_name2
stores the 1st argument as
-.I number register
+.I register
and the second as
.I string
by
.
.
.\" ====================================================================
-.SS "Printing towards STDERR is without Storage"
-.\" ====================================================================
-.
-The printing towards
-.IR STDERR ,
-(standard error) works as usual.
-.
-All error information goes to the real normal
-.IR "standard error" ,
-without other automatic storage.
-.
-.
-.\" ====================================================================
-.SH "EXAMPLES"
+.SH Example
.\" ====================================================================
.
A possible
.EX
before
\&.Perl start
-my $result = 'some data';
+my $result = \[aq]some data\[aq];
print $result;
\&.Perl stop .ds string_var
after
.EE
.RE
by
-.B gperl
+.I gperl
as food for the coming
-.B groff
+.I groff
run.
.
.
.
.
.\" ====================================================================
-.SH AUTHORS
+.SH Authors
.\" ====================================================================
-.B gperl
+.
+.I gperl
was written by
-.MT groff\-bernd.warken\-72@\:web.de
+.MT groff\-bernd\:.warken\-72@\:web\:.de
Bernd Warken
.ME .
.
.
.\" ====================================================================
-.SH "SEE ALSO"
+.SH "See also"
.\" ====================================================================
.
.P
Man pages related to
.I groff
are
-.BR \%groff (@MAN1EXT@),
-.BR \%groff (@MAN7EXT@),
-.BR \%grog (@MAN1EXT@),
+.MR groff @MAN1EXT@ ,
+.MR groff @MAN7EXT@ ,
and
-.BR \%groffer (@MAN1EXT@).
+.MR grog @MAN1EXT@ .
.
.
.P
Documents related to
.I Perl
are
-.BR \%perl (@MAN1EXT@),
-.BR \%perl (@MAN7EXT@).
+.MR perl 1 ,
+.MR perl 7 .
.
.
-.\" ====================================================================
-.\" Emacs settings
-.\" ====================================================================
+.\" 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:
+.\" vim: set filetype=groff textwidth=72:
projects / platform / upstream / groff.git / blobdiff