# phpman > man > gperl(1) [GPERL(1)](https://www.chedong.com/phpMan.php/man/GPERL/1/markdown) General Commands Manual [GPERL(1)](https://www.chedong.com/phpMan.php/man/GPERL/1/markdown) ## NAME gperl - groff preprocessor for Perl parts in roff files ## SYNOPSIS **gperl** [_filespec_ ...] ### gperl -h ### gperl --help ### gperl -v ### gperl --version ## DESCRIPTION This is a preprocessor for [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown). It allows the use of [**perl**(7)](https://www.chedong.com/phpMan.php/man/perl/7/markdown) code in [**groff**(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown) 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_. ## OPTIONS So 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 following 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 here ### -h --help Print help information with a short explanation of options to standard output. ### -v --version Print version information to standard output. ## PERL PARTS _Perl_ parts in _groff_ _files_ are enclosed by two **.Perl** requests with different arguments, a _starting_ and an _ending_ command. ### Starting Perl Mode The starting _Perl_ _request_ can either be without arguments, or by a request that has the term **start** as its only argument. * **.Perl** * **.Perl** **start** ### Ending Perl Mode without Storage A **.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_ The argument _other_than_start_ can additionally be used as a _groff_ string variable name for storage — see next section. ### Ending Perl Mode with Storage A 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** pro‐ gram. This pseudo-printing output can have several lines, due to printed line breaks with **\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 **.rn** The storage modes can be determined by arguments of a final stopping **.Perl** command. Each ar‐ gument **.ds** changes the mode into _groff_ _string_ and **.nr** changes the mode into _groff_ _number_ _reg__‐ _ister_ for all following output parts. By default, all output is saved as strings, so **.ds** is not really needed before the first **.nr** command. That suits to [**groff**(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown), because every output can be saved as _groff_ string, but the number registers can be very restrictive. In _string_ _mode_, **gperl** generates a _groff_ _string_ storage line **.ds** _var_name_ _content_ In _number_ _register_ _mode_ the following groff command is generated **.nr** _var_name_ _content_ We present argument collections in the following. You can add as first argument for all **stop**. We omit this additional element. **.Perl** **.ds** _var_name_ This will store 1 output line into the groff string named _var_name_ by the automati‐ cally 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 _var_name1_ and _var_name2_, be‐ cause the default mode **.ds** is active, such that no **.ds** argument is needed. Of course, this is equivalent to **.Perl** **.ds** _var_name1_ _var_name2_ and **.Perl** **.ds** _var_name1_ **.ds** _var_name2_ **.Perl** **.nr** _var_name1_ _varname2_ stores both variables as number register variables. **gperl** generates **.nr** _var_name1_ _output_line1_ **.nr** _var_name2_ _output_line2_ **.Perl** **.nr** _var_name1_ **.ds** _var_name2_ stores the 1st argument as _number_ _register_ and the second as _string_ by **.nr** _var_name1_ _output_line1_ **.ds** _var_name2_ _output_line2_ ### Printing towards STDERR is without Storage The printing towards _STDERR_, (standard error) works as usual. All error information goes to the real normal _standard_ _error_, without other automatic storage. ## EXAMPLES A 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 This stores the result ””**some** **data**”” into the _roff_ _string_ called **string**___**var**, such that the fol‐ lowing line is printed: .ds string_var some data by **gperl** as food for the coming **groff** run. A _Perl_ _part_ with several outputs is: .Perl start print ”first\n”; print ”second line\n”; print ”3\n”; .Perl var1 var2 .nr var3 This stores 3 printed lines into 3 _groff_ strings. **var1**,**var2**,**var3**. So the following _groff_ command lines are created: .ds var1 first .ds var2 second line .nr var3 3 ## AUTHORS **gperl** was written by Bernd Warken ⟨⟩. ## SEE ALSO Man pages related to _groff_ are [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown), [**groff**(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown), [**grog**(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown), and [**groffer**(1)](https://www.chedong.com/phpMan.php/man/groffer/1/markdown). Documents related to _Perl_ are [**perl**(1)](https://www.chedong.com/phpMan.php/man/perl/1/markdown), [**perl**(7)](https://www.chedong.com/phpMan.php/man/perl/7/markdown). groff 1.22.4 23 March 2022 [GPERL(1)](https://www.chedong.com/phpMan.php/man/GPERL/1/markdown)