{
    "mode": "perldoc",
    "parameter": "Pod::Text",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Pod%3A%3AText/json",
    "generated": "2026-08-10T13:12:15Z",
    "synopsis": "use Pod::Text;\nmy $parser = Pod::Text->new (sentence => 1, width => 78);\n# Read POD from STDIN and write to STDOUT.\n$parser->parsefromfilehandle;\n# Read POD from file.pod and write to file.txt.\n$parser->parsefromfile ('file.pod', 'file.txt');",
    "sections": {
        "NAME": {
            "content": "Pod::Text - Convert POD data to formatted text\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Pod::Text;\nmy $parser = Pod::Text->new (sentence => 1, width => 78);\n\n# Read POD from STDIN and write to STDOUT.\n$parser->parsefromfilehandle;\n\n# Read POD from file.pod and write to file.txt.\n$parser->parsefromfile ('file.pod', 'file.txt');\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Pod::Text is a module that can convert documentation in the POD format (the preferred language\nfor documenting Perl) into formatted text. It uses no special formatting controls or codes, and\nits output is therefore suitable for nearly any device.\n",
            "subsections": [
                {
                    "name": "Encoding",
                    "content": "Pod::Text uses the following logic to choose an output encoding, in order:\n\n1.  If a PerlIO encoding layer is set on the output file handle, do not do any output encoding\nand will instead rely on the PerlIO encoding layer.\n\n2.  If the \"encoding\" or \"utf8\" options are set, use the output encoding specified by those\noptions.\n\n3.  If the input encoding of the POD source file was explicitly specified (using \"=encoding\") or\nautomatically detected by Pod::Simple, use that as the output encoding as well.\n\n4.  Otherwise, if running on a non-EBCDIC system, use UTF-8 as the output encoding. Since this\nis a superset of ASCII, this will result in ASCII output unless the POD input contains\nnon-ASCII characters without declaring or autodetecting an encoding (usually via E<>\nescapes).\n\n5.  Otherwise, for EBCDIC systems, output without doing any encoding and hope this works.\n\nOne caveat: Pod::Text has to commit to an output encoding the first time it outputs a non-ASCII\ncharacter, and then has to stick with it for consistency. However, \"=encoding\" commands don't\nhave to be at the beginning of a POD document. If someone uses a non-ASCII character early in a\ndocument with an escape, such as E<0xEF>, and then puts \"=encoding iso-8859-1\" later, ideally\nPod::Text would follow rule 3 and output the entire document as ISO 8859-1. Instead, it will\ncommit to UTF-8 following rule 4 as soon as it sees that escape, and then stick with that\nencoding for the rest of the document.\n\nUnfortunately, there's no universally good choice for an output encoding. Each choice will be\nincorrect in some circumstances. This approach was chosen primarily for backwards compatibility.\nCallers should consider forcing the output encoding via \"encoding\" if they have any knowledge\nabout what encoding the user may expect.\n\nIn particular, consider importing the Encode::Locale module, if available, and setting\n\"encoding\" to \"locale\" to use an output encoding appropriate to the user's locale. But be aware\nthat if the user is not using locales or is using a locale of \"C\", Encode::Locale will set the\noutput encoding to US-ASCII. This will cause all non-ASCII characters will be replaced with \"?\"\nand produce a flurry of warnings about unsupported characters, which may or may not be what you\nwant.\n"
                }
            ]
        },
        "CLASS METHODS": {
            "content": "",
            "subsections": [
                {
                    "name": "new",
                    "content": "Create a new Pod::Text object. ARGS should be a list of key/value pairs, where the keys are\nchosen from the following. Each option is annotated with the version of Pod::Text in which\nthat option was added with its current meaning.\n\nalt [2.00] If set to a true value, selects an alternate output format that, among other\nthings, uses a different heading style and marks \"=item\" entries with a colon in the\nleft margin. Defaults to false.\n\ncode\n[2.13] If set to a true value, the non-POD parts of the input file will be included in\nthe output. Useful for viewing code documented with POD blocks with the POD rendered and\nthe code left intact.\n\nencoding\n[5.00] Specifies the encoding of the output. The value must be an encoding recognized by\nthe Encode module (see Encode::Supported). If the output contains characters that cannot\nbe represented in this encoding, that is an error that will be reported as configured by\nthe \"errors\" option. If error handling is other than \"die\", the unrepresentable\ncharacter will be replaced with the Encode substitution character (normally \"?\").\n\nIf the output file handle has a PerlIO encoding layer set, this parameter will be\nignored and no encoding will be done by Pod::Man. It will instead rely on the encoding\nlayer to make whatever output encoding transformations are desired.\n\nWARNING: The input encoding of the POD source is independent from the output encoding,\nand setting this option does not affect the interpretation of the POD input. Unless your\nPOD source is US-ASCII, its encoding should be declared with the \"=encoding\" command in\nthe source, as near to the top of the file as possible. If this is not done, Pod::Simple\nwill will attempt to guess the encoding and may be successful if it's Latin-1 or UTF-8,\nbut it will produce warnings. See perlpod(1) for more information.\n\nerrors\n[3.17] How to report errors. \"die\" says to throw an exception on any POD formatting\nerror. \"stderr\" says to report errors on standard error, but not to throw an exception.\n\"pod\" says to include a POD ERRORS section in the resulting documentation summarizing\nthe errors. \"none\" ignores POD errors entirely, as much as possible.\n\nThe default is \"pod\".\n\nguesswork\n[5.01] By default, Pod::Text applies some default formatting rules based on guesswork\nand regular expressions that are intended to make writing Perl documentation easier and\nrequire less explicit markup. These rules may not always be appropriate, particularly\nfor documentation that isn't about Perl. This option allows turning all or some of it\noff.\n\nThe special value \"all\" enables all guesswork. This is also the default for backward\ncompatibility reasons. The special value \"none\" disables all guesswork. Otherwise, the\nvalue of this option should be a comma-separated list of one or more of the following\nkeywords:\n\nquoting\nIf no guesswork is enabled, any text enclosed in C<> is surrounded by double quotes\nin nroff (terminal) output unless the contents are already quoted. When this\nguesswork is enabled, quote marks will also be suppressed for Perl variables,\nfunction names, function calls, numbers, and hex constants.\n\nAny unknown guesswork name is silently ignored (for potential future compatibility), so\nbe careful about spelling.\n\nindent\n[2.00] The number of spaces to indent regular text, and the default indentation for\n\"=over\" blocks. Defaults to 4.\n\nloose\n[2.00] If set to a true value, a blank line is printed after a \"=head1\" heading. If set\nto false (the default), no blank line is printed after \"=head1\", although one is still\nprinted after \"=head2\". This is the default because it's the expected formatting for\nmanual pages; if you're formatting arbitrary text documents, setting this to true may\nresult in more pleasing output.\n\nmargin\n[2.21] The width of the left margin in spaces. Defaults to 0. This is the margin for all\ntext, including headings, not the amount by which regular text is indented; for the\nlatter, see the *indent* option. To set the right margin, see the *width* option.\n\nnourls\n[3.17] Normally, L<> formatting codes with a URL but anchor text are formatted to show\nboth the anchor text and the URL. In other words:\n\nL<foo|http://example.com/>\n\nis formatted as:\n\nfoo <http://example.com/>\n\nThis option, if set to a true value, suppresses the URL when anchor text is given, so\nthis example would be formatted as just \"foo\". This can produce less cluttered output in\ncases where the URLs are not particularly important.\n\nquotes\n[4.00] Sets the quote marks used to surround C<> text. If the value is a single\ncharacter, it is used as both the left and right quote. Otherwise, it is split in half,\nand the first half of the string is used as the left quote and the second is used as the\nright quote.\n\nThis may also be set to the special value \"none\", in which case no quote marks are added\naround C<> text.\n\nsentence\n[3.00] If set to a true value, Pod::Text will assume that each sentence ends in two\nspaces, and will try to preserve that spacing. If set to false, all consecutive\nwhitespace in non-verbatim paragraphs is compressed into a single space. Defaults to\nfalse.\n\nstderr\n[3.10] Send error messages about invalid POD to standard error instead of appending a\nPOD ERRORS section to the generated output. This is equivalent to setting \"errors\" to\n\"stderr\" if \"errors\" is not already set. It is supported for backward compatibility.\n\nutf8\n[3.12] If this option is set to a true value, the output encoding is set to UTF-8. This\nis equivalent to setting \"encoding\" to \"UTF-8\" if \"encoding\" is not already set. It is\nsupported for backward compatibility.\n\nwidth\n[2.00] The column at which to wrap text on the right-hand side. Defaults to 76.\n"
                }
            ]
        },
        "INSTANCE METHODS": {
            "content": "As a derived class from Pod::Simple, Pod::Text supports the same methods and interfaces. See\nPod::Simple for all the details. This section summarizes the most-frequently-used methods and\nthe ones added by Pod::Text.\n",
            "subsections": [
                {
                    "name": "output_fh",
                    "content": "Direct the output from parsefile(), parselines(), or parsestringdocument() to the file\nhandle FH instead of \"STDOUT\".\n"
                },
                {
                    "name": "output_string",
                    "content": "Direct the output from parsefile(), parselines(), or parsestringdocument() to the scalar\nvariable pointed to by REF, rather than \"STDOUT\". For example:\n\nmy $man = Pod::Man->new();\nmy $output;\n$man->outputstring(\\$output);\n$man->parsefile('/some/input/file');\n\nBe aware that the output in that variable will already be encoded (see \"Encoding\").\n"
                },
                {
                    "name": "parse_file",
                    "content": "Read the POD source from PATH and format it. By default, the output is sent to \"STDOUT\", but\nthis can be changed with the outputfh() or outputstring() methods.\n"
                },
                {
                    "name": "parse_from_file",
                    "content": ""
                },
                {
                    "name": "parse_from_filehandle",
                    "content": "Read the POD source from INPUT, format it, and output the results to OUTPUT.\n\nparsefromfilehandle() is provided for backward compatibility with older versions of\nPod::Man. parsefromfile() should be used instead.\n"
                },
                {
                    "name": "parse_lines",
                    "content": "Parse the provided lines as POD source, writing the output to either \"STDOUT\" or the file\nhandle set with the outputfh() or outputstring() methods. This method can be called\nrepeatedly to provide more input lines. An explicit \"undef\" should be passed to indicate the\nend of input.\n\nThis method expects raw bytes, not decoded characters.\n"
                },
                {
                    "name": "parse_string_document",
                    "content": "Parse the provided scalar variable as POD source, writing the output to either \"STDOUT\" or\nthe file handle set with the outputfh() or outputstring() methods.\n\nThis method expects raw bytes, not decoded characters.\n"
                }
            ]
        },
        "FUNCTIONS": {
            "content": "Pod::Text exports one function for backward compatibility with older versions. This function is\ndeprecated; instead, use the object-oriented interface described above.\n",
            "subsections": [
                {
                    "name": "pod2text",
                    "content": "Convert the POD source from INPUT to text and write it to OUTPUT. If OUTPUT is not given,\ndefaults to \"STDOUT\". INPUT can be any expression supported as the second argument to\ntwo-argument open().\n\nIf \"-a\" is given as an initial argument, pass the \"alt\" option to the Pod::Text constructor.\nThis enables alternative formatting.\n\nIf \"-NNN\" is given as an initial argument, pass the \"width\" option to the Pod::Text\nconstructor with the number \"NNN\" as its argument. This sets the wrap line width to NNN.\n"
                }
            ]
        },
        "DIAGNOSTICS": {
            "content": "Bizarre space in item\nItem called without tag\n(W) Something has gone wrong in internal \"=item\" processing. These messages indicate a bug\nin Pod::Text; you should never see them.\n\nCan't open %s for reading: %s\n(F) Pod::Text was invoked via the compatibility mode pod2text() interface and the input file\nit was given could not be opened.\n\nInvalid errors setting \"%s\"\n(F) The \"errors\" parameter to the constructor was set to an unknown value.\n\nInvalid quote specification \"%s\"\n(F) The quote specification given (the \"quotes\" option to the constructor) was invalid. A\nquote specification must be either one character long or an even number (greater than one)\ncharacters long.\n\nPOD document had syntax errors\n(F) The POD document being formatted had syntax errors and the \"errors\" option was set to\n\"die\".\n",
            "subsections": []
        },
        "COMPATIBILITY": {
            "content": "Pod::Text 2.03 (based on Pod::Parser) was the first version of this module included with Perl,\nin Perl 5.6.0. Earlier versions of Perl had a different Pod::Text module, with a different API.\n\nThe current API based on Pod::Simple was added in Pod::Text 3.00. Pod::Text 3.01 was included in\nPerl 5.9.3, the first version of Perl to incorporate those changes. This is the first version\nthat correctly supports all modern POD syntax. The parsefromfilehandle() method was re-added\nfor backward compatibility in Pod::Text 3.07, included in Perl 5.9.4.\n\nPod::Text 3.12, included in Perl 5.10.1, first implemented the current practice of attempting to\nmatch the default output encoding with the input encoding of the POD source, unless overridden\nby the \"utf8\" option or (added later) the \"encoding\" option.\n\nSupport for anchor text in L<> links of type URL was added in Pod::Text 3.14, included in Perl\n5.11.5.\n",
            "subsections": [
                {
                    "name": "parse_lines",
                    "content": "\"STDOUT\" if one was not already set as of Pod::Text 3.18, included in Perl 5.19.5.\n\nPod::Text 4.00, included in Perl 5.23.7, aligned the module version and the version of the\npodlators distribution. All modules included in podlators, and the podlators distribution\nitself, share the same version number from this point forward.\n\nPod::Text 4.09, included in Perl 5.25.7, fixed a serious bug on EBCDIC systems, present in all\nversions back to 3.00, that would cause opening brackets to disappear.\n\nPod::Text 5.00 now defaults, on non-EBCDIC systems, to UTF-8 encoding if it sees a non-ASCII\ncharacter in the input and the input encoding is not specified. It also commits to an encoding\nwith the first non-ASCII character and does not change the output encoding if the input encoding\nchanges. The Encode module is now used for all output encoding rather than PerlIO layers, which\nfixes earlier problems with output to scalars.\n"
                }
            ]
        },
        "AUTHOR": {
            "content": "Russ Allbery <rra@cpan.org>, based *very* heavily on the original Pod::Text by Tom Christiansen\n<tchrist@mox.perl.com> and its conversion to Pod::Parser by Brad Appleton\n<bradapp@enteract.com>. Sean Burke's initial conversion of Pod::Man to use Pod::Simple provided\nmuch-needed guidance on how to use Pod::Simple.\n",
            "subsections": []
        },
        "COPYRIGHT AND LICENSE": {
            "content": "Copyright 1999-2002, 2004, 2006, 2008-2009, 2012-2016, 2018-2019, 2022 Russ Allbery\n<rra@cpan.org>\n\nThis program is free software; you may redistribute it and/or modify it under the same terms as\nPerl itself.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "Encode::Locale, Encode::Supproted, Pod::Simple, Pod::Text::Termcap, perlpod(1), pod2text(1)\n\nThe current version of this module is always available from its web site at\n<https://www.eyrie.org/~eagle/software/podlators/>. It is also part of the Perl core\ndistribution as of 5.6.0.\n",
            "subsections": []
        }
    },
    "summary": "Pod::Text - Convert POD data to formatted text",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "perlpod",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/perlpod/1/json"
        },
        {
            "name": "pod2text",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/pod2text/1/json"
        }
    ]
}