{
    "content": [
        {
            "type": "text",
            "text": "# gperl (man)\n\n## NAME\n\ngperl - groff preprocessor for Perl parts in roff files\n\n## SYNOPSIS\n\ngperl [filespec ...]\n\n## DESCRIPTION\n\nThis  is  a  preprocessor for groff(1).  It allows the use of perl(7) code in groff(7) files.\nThe result of a Perl part can be stored in groff strings or numerical registers based on  the\narguments at a final line of a Perl part.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS** (4 subsections)\n- **DESCRIPTION**\n- **OPTIONS** (2 subsections)\n- **PERL PARTS** (4 subsections)\n- **EXAMPLES**\n- **AUTHORS**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "gperl",
        "section": "",
        "mode": "man",
        "summary": "gperl - groff preprocessor for Perl parts in roff files",
        "synopsis": "gperl [filespec ...]",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [
            {
                "flag": "-h",
                "long": "--help",
                "arg": null,
                "description": "Print help information with a short explanation of options to standard output."
            },
            {
                "flag": "-v",
                "long": "--version",
                "arg": null,
                "description": "Print version information to standard output."
            }
        ],
        "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 stringvar",
            "after",
            "This stores the result ””some data”” into the roff string called stringvar, such that the fol‐",
            "lowing line is printed:",
            ".ds stringvar 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"
        ],
        "see_also": [
            {
                "name": "groff",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/groff/1/json"
            },
            {
                "name": "groff",
                "section": "7",
                "url": "https://www.chedong.com/phpMan.php/man/groff/7/json"
            },
            {
                "name": "grog",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/grog/1/json"
            },
            {
                "name": "groffer",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/groffer/1/json"
            },
            {
                "name": "perl",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/perl/1/json"
            },
            {
                "name": "perl",
                "section": "7",
                "url": "https://www.chedong.com/phpMan.php/man/perl/7/json"
            }
        ],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 2,
                "subsections": [
                    {
                        "name": "gperl -h",
                        "lines": 1
                    },
                    {
                        "name": "gperl --help",
                        "lines": 1
                    },
                    {
                        "name": "gperl -v",
                        "lines": 1
                    },
                    {
                        "name": "gperl --version",
                        "lines": 1
                    }
                ]
            },
            {
                "name": "DESCRIPTION",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "OPTIONS",
                "lines": 9,
                "subsections": [
                    {
                        "name": "-h --help",
                        "lines": 2,
                        "flag": "-h",
                        "long": "--help"
                    },
                    {
                        "name": "-v --version",
                        "lines": 2,
                        "flag": "-v",
                        "long": "--version"
                    }
                ]
            },
            {
                "name": "PERL PARTS",
                "lines": 3,
                "subsections": [
                    {
                        "name": "Starting Perl Mode",
                        "lines": 7
                    },
                    {
                        "name": "Ending Perl Mode without Storage",
                        "lines": 9
                    },
                    {
                        "name": "Ending Perl Mode with Storage",
                        "lines": 60
                    },
                    {
                        "name": "Printing towards STDERR is without Storage",
                        "lines": 3
                    }
                ]
            },
            {
                "name": "EXAMPLES",
                "lines": 25,
                "subsections": []
            },
            {
                "name": "AUTHORS",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 7,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "gperl - groff preprocessor for Perl parts in roff files\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "gperl [filespec ...]\n",
                "subsections": [
                    {
                        "name": "gperl -h",
                        "content": ""
                    },
                    {
                        "name": "gperl --help",
                        "content": ""
                    },
                    {
                        "name": "gperl -v",
                        "content": ""
                    },
                    {
                        "name": "gperl --version",
                        "content": ""
                    }
                ]
            },
            "DESCRIPTION": {
                "content": "This  is  a  preprocessor for groff(1).  It allows the use of perl(7) code in groff(7) files.\nThe result of a Perl part can be stored in groff strings or numerical registers based on  the\narguments at a final line of a Perl part.\n",
                "subsections": []
            },
            "OPTIONS": {
                "content": "So far, there are only filespec or breaking options.\n\nfilespec are file names or the minus character - character for standard input.  As usual, the\nargument -- can be used in order to let all following arguments mean file names, even if  the\nnames begin with a minus character -.\n\nAn  option  is  breaking, when the program just writes the information that was asked for and\nthen stops.  All other arguments will be ignored by that.  These breaking options are here\n",
                "subsections": [
                    {
                        "name": "-h --help",
                        "content": "Print help information with a short explanation of options to standard output.\n",
                        "flag": "-h",
                        "long": "--help"
                    },
                    {
                        "name": "-v --version",
                        "content": "Print version information to standard output.\n",
                        "flag": "-v",
                        "long": "--version"
                    }
                ]
            },
            "PERL PARTS": {
                "content": "Perl parts in groff files are enclosed by two .Perl  requests  with  different  arguments,  a\nstarting and an ending command.\n",
                "subsections": [
                    {
                        "name": "Starting Perl Mode",
                        "content": "The  starting Perl request can either be without arguments, or by a request that has the term\nstart as its only argument.\n\n* .Perl\n\n* .Perl start\n"
                    },
                    {
                        "name": "Ending Perl Mode without Storage",
                        "content": "A .Perl command line with an argument different from start finishes a running Perl part.   Of\ncourse, it would be reasonable to add the argument stop; that's possible, but not necessary.\n\n* .Perl stop\n\n* .Perl otherthanstart\nThe  argument  otherthanstart  can additionally be used as a groff string variable name for\nstorage — see next section.\n"
                    },
                    {
                        "name": "Ending Perl Mode with Storage",
                        "content": "A useful feature of gperl is to store one or more results from the Perl mode.\n\nThe output of a Perl part can be got with backticks `...`.\n\nThis program collects all printing to STDOUT (normal standard output) by the Perl print  pro‐\ngram.   This  pseudo-printing  output can have several lines, due to printed line breaks with\n\\n.  By that, the output of a Perl run should be stored into a Perl array, with a single line\nfor each array member.\n\nThis Perl array output can be stored by gperl in either\n\ngroff strings\nby creating a groff command .ds\n\ngroff number register\nby creating a groff command .rn\n\nThe storage modes can be determined by arguments of a final stopping .Perl command.  Each ar‐\ngument .ds changes the mode into groff string and .nr changes the mode into groff number reg‐\nister for all following output parts.\n\nBy  default, all output is saved as strings, so .ds is not really needed before the first .nr\ncommand.  That suits to groff(7), because every output can be saved as groff string, but  the\nnumber registers can be very restrictive.\n\nIn string mode, gperl generates a groff string storage line\n.ds varname content\nIn number register mode the following groff command is generated\n.nr varname content\n\nWe  present  argument  collections  in  the following.  You can add as first argument for all\nstop.  We omit this additional element.\n\n.Perl .ds varname\nThis will store 1 output line into the groff string named varname  by  the  automati‐\ncally created command\n.ds varname output\n\n.Perl varname\nIf  varname is different from start this is equivalent to the former command, because\nthe string mode is string with .ds command.  default.\n\n.Perl varname1 varname2\nThis will store 2 output lines into groff string names varname1  and  varname2,  be‐\ncause the default mode .ds is active, such that no .ds argument is needed.  Of course,\nthis is equivalent to\n.Perl .ds varname1 varname2\nand\n.Perl .ds varname1 .ds varname2\n\n.Perl .nr varname1 varname2\nstores both variables as number register variables.  gperl generates\n.nr varname1 outputline1\n.nr varname2 outputline2\n\n.Perl .nr varname1 .ds varname2\nstores the 1st argument as number register and the second as string by\n.nr varname1 outputline1\n.ds varname2 outputline2\n"
                    },
                    {
                        "name": "Printing towards STDERR is without Storage",
                        "content": "The printing towards STDERR, (standard error) works as usual.  All error information goes  to\nthe real normal standard error, without other automatic storage.\n"
                    }
                ]
            },
            "EXAMPLES": {
                "content": "A possible Perl part in a roff file could look like that:\nbefore\n.Perl start\nmy $result = 'some data';\nprint $result;\n.Perl stop .ds stringvar\nafter\n\nThis stores the result ””some data”” into the roff string called stringvar, such that the fol‐\nlowing line is printed:\n.ds stringvar some data\nby gperl as food for the coming groff run.\n\nA Perl part with several outputs is:\n.Perl start\nprint ”first\\n”;\nprint ”second line\\n”;\nprint ”3\\n”;\n.Perl var1 var2 .nr var3\nThis stores 3 printed lines into 3 groff strings.  var1,var2,var3.  So  the  following  groff\ncommand lines are created:\n.ds var1 first\n.ds var2 second line\n.nr var3 3\n",
                "subsections": []
            },
            "AUTHORS": {
                "content": "gperl was written by Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "Man pages related to groff are groff(1), groff(7), grog(1), and groffer(1).\n\nDocuments related to Perl are perl(1), perl(7).\n\n\n\ngroff 1.22.4                                23 March 2022                                   GPERL(1)",
                "subsections": []
            }
        }
    }
}