{
    "mode": "man",
    "parameter": "pod2text",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/pod2text/1/json",
    "generated": "2026-10-25T03:34:04Z",
    "synopsis": "pod2text [-aclostu] [--code] [-e encoding]\n[--errors=style] [--guesswork=rule[,rule...]]\n[-i indent] [-q quotes]\n[--nourls] [--stderr] [-w width] [input [output ...]]\npod2text -h",
    "sections": {
        "NAME": {
            "content": "pod2text - Convert POD data to formatted ASCII text\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "pod2text [-aclostu] [--code] [-e encoding]\n[--errors=style] [--guesswork=rule[,rule...]]\n[-i indent] [-q quotes]\n[--nourls] [--stderr] [-w width] [input [output ...]]\n\npod2text -h\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "pod2text is a wrapper script around the Pod::Text and its subclasses.  It uses them to\ngenerate formatted text from POD source.  It can optionally use either termcap sequences or\nANSI color escape sequences to format the text.\n\ninput is the file to read for POD source (the POD can be embedded in code).  If input isn't\ngiven, it defaults to \"STDIN\".  output, if given, is the file to which to write the formatted\noutput.  If output isn't given, the formatted output is written to \"STDOUT\".  Several POD\nfiles can be processed in the same pod2text invocation (saving module load and compile times)\nby providing multiple pairs of input and output files on the command line.\n\nBy default, the output encoding is the same as the encoding of the input file, or UTF-8 if\nthat encoding is not set (except on EBCDIC systems).  See the -e option to explicitly set the\noutput encoding and \"Encoding\" in Pod::Text for more discussion.\n",
            "subsections": []
        },
        "OPTIONS": {
            "content": "Each option is annotated with the version of podlators in which that option was added with\nits current meaning.\n",
            "subsections": [
                {
                    "name": "-a --alt",
                    "content": "[1.00]  Use an alternate output format that, among other things, uses a different heading\nstyle and marks \"=item\" entries with a colon in the left margin.\n",
                    "flag": "-a",
                    "long": "--alt"
                },
                {
                    "name": "--code",
                    "content": "[1.11] Include any non-POD text from the input file in the output as  well.   Useful  for\nviewing code documented with POD blocks with the POD rendered and the code left intact.\n",
                    "long": "--code"
                },
                {
                    "name": "-c --color",
                    "content": "[1.00]  Format  the  output with ANSI color escape sequences.  Using this option requires\nthat Term::ANSIColor be installed on your system.\n",
                    "flag": "-c",
                    "long": "--color"
                },
                {
                    "name": "-e _ --encoding",
                    "content": "[5.00] Specifies the encoding of the output.  encoding 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\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\n--errors=style\n[2.5.0] Set the error handling style.  \"die\" says  to  throw  an  exception  on  any  POD\nformatting  error.  \"stderr\" says to report errors on standard error, but not to throw an\nexception.  \"pod\" says to include a POD ERRORS section  in  the  resulting  documentation\nsummarizing the errors.  \"none\" ignores POD errors entirely, as much as possible.\n\nThe default is \"die\".\n\n--guesswork=rule[,rule...]\n[5.01]  By default, pod2text applies some default formatting rules based on guesswork and\nregular 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  rule  \"all\"  enables  all guesswork.  This is also the default for backward\ncompatibility reasons.  The special rule \"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",
                    "flag": "-e",
                    "long": "--encoding"
                },
                {
                    "name": "-i _ --indent=_",
                    "content": "[1.00] Set the number of spaces to indent regular text, and the default  indentation  for\n\"=over\" blocks.  Defaults to 4 spaces if this option isn't given.\n",
                    "flag": "-i",
                    "long": "--indent",
                    "arg": "_"
                },
                {
                    "name": "-h --help",
                    "content": "[1.00] Print out usage information and exit.\n",
                    "flag": "-h",
                    "long": "--help"
                },
                {
                    "name": "-l --loose",
                    "content": "[1.00]  Print  a blank line after a \"=head1\" heading.  Normally, no blank line is printed\nafter \"=head1\", although one is  still  printed  after  \"=head2\",  because  this  is  the\nexpected  formatting  for  manual  pages;  if you're formatting arbitrary text documents,\nusing this option is recommended.\n",
                    "flag": "-l",
                    "long": "--loose"
                },
                {
                    "name": "-m _ --left-margin --margin",
                    "content": "[1.24] The width of the left margin in spaces.  Defaults to 0.  This is  the  margin  for\nall  text,  including headings, not the amount by which regular text is indented; for the\nlatter, see -i option.\n",
                    "flag": "-m",
                    "long": "--margin"
                },
                {
                    "name": "--nourls",
                    "content": "[2.5.0] 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  flag, if given, suppresses the URL when anchor text is given, so this example would\nbe formatted as just \"foo\".  This can produce less cluttered output in  cases  where  the\nURLs are not particularly important.\n",
                    "long": "--nourls"
                },
                {
                    "name": "-o --overstrike",
                    "content": "[1.06]  Format  the output with overstrike printing.  Bold text is rendered as character,\nbackspace, character.  Italics and file names  are  rendered  as  underscore,  backspace,\ncharacter.   Many  pagers,  such  as less, know how to convert this to bold or underlined\ntext.\n",
                    "flag": "-o",
                    "long": "--overstrike"
                },
                {
                    "name": "-q _ --quotes",
                    "content": "[4.00] Sets the quote marks used to surround C<> text to quotes.  If quotes 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\nquotes  may  also  be  set  to the special value \"none\", in which case no quote marks are\nadded around C<> text.\n",
                    "flag": "-q",
                    "long": "--quotes"
                },
                {
                    "name": "-s --sentence",
                    "content": "[1.00] Assume each sentence ends with two  spaces  and  try  to  preserve  that  spacing.\nWithout  this option, all consecutive whitespace in non-verbatim paragraphs is compressed\ninto a single space.\n",
                    "flag": "-s",
                    "long": "--sentence"
                },
                {
                    "name": "--stderr",
                    "content": "[2.1.3] By default, pod2text dies if any errors  are  detected  in  the  POD  input.   If\n--stderr is given and no --errors flag is present, errors are sent to standard error, but\npod2text  does  not  abort.  This is equivalent to \"--errors=stderr\" and is supported for\nbackward compatibility.\n",
                    "long": "--stderr"
                },
                {
                    "name": "-t --termcap",
                    "content": "[1.00] Try to determine the width of the screen and the bold and underline sequences  for\nthe  terminal  from  termcap,  and use that information in formatting the output.  Output\nwill be wrapped at two columns less than the width of your terminal device.   Using  this\noption  requires  that your system have a termcap file somewhere where Term::Cap can find\nit and requires that your system support  termios.   With  this  option,  the  output  of\npod2text will contain terminal control sequences for your current terminal type.\n",
                    "flag": "-t",
                    "long": "--termcap"
                },
                {
                    "name": "-u --utf8",
                    "content": "[2.2.0]  Set  the output encoding to UTF-8.  This is equivalent to \"--encoding=UTF-8\" and\nis supported for backward compatibility.\n",
                    "flag": "-u",
                    "long": "--utf8"
                },
                {
                    "name": "-w --width=_ -_",
                    "content": "[1.00] The column at which to wrap text on the right-hand side.  Defaults to  76,  unless\n-t is given, in which case it's two columns less than the width of your terminal device.\n",
                    "flag": "-w",
                    "long": "--width",
                    "arg": "_"
                }
            ]
        },
        "EXIT STATUS": {
            "content": "As long as all documents processed result in some output, even if that output includes errata\n(a \"POD ERRORS\" section generated with \"--errors=pod\"), pod2text will exit with status 0.  If\nany  of the documents being processed do not result in an output document, pod2text will exit\nwith status 1.  If there are syntax errors in a POD document being processed  and  the  error\nhandling  style  is  set  to  the default of \"die\", pod2text will abort immediately with exit\nstatus 255.\n",
            "subsections": []
        },
        "DIAGNOSTICS": {
            "content": "If pod2text fails with errors, see Pod::Text and Pod::Simple for information about what those\nerrors might mean.  Internally, it can also produce the following diagnostics:\n\n-c (--color) requires Term::ANSIColor be installed\n(F) -c or --color were given, but Term::ANSIColor could not be loaded.\n\nUnknown option: %s\n(F) An unknown command line option was given.\n\nIn addition, other Getopt::Long error messages may result from invalid command-line options.\n",
            "subsections": []
        },
        "ENVIRONMENT": {
            "content": "COLUMNS\nIf -t is given, pod2text will take the current width of your screen from this environment\nvariable, if available.  It overrides terminal width information in TERMCAP.\n\nTERMCAP\nIf -t is given, pod2text will use the contents of this environment variable if  available\nto determine the correct formatting sequences for your current terminal device.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Russ Allbery <rra@cpan.org>.\n",
            "subsections": []
        },
        "COPYRIGHT AND LICENSE": {
            "content": "Copyright 1999-2001, 2004, 2006, 2008, 2010, 2012-2019, 2022 Russ Allbery <rra@cpan.org>\n\nThis  program is free software; you may redistribute it and/or modify it under the same terms\nas Perl itself.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "Encode::Supported, Pod::Text,  Pod::Text::Color,  Pod::Text::Overstrike,  Pod::Text::Termcap,\nPod::Simple, perlpod(1)\n\nThe   current   version   of   this   script  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\nperl v5.38.2                                 2026-08-18                                  POD2TEXT(1)",
            "subsections": []
        }
    },
    "summary": "pod2text - Convert POD data to formatted ASCII text",
    "flags": [
        {
            "flag": "-a",
            "long": "--alt",
            "arg": null,
            "description": "[1.00] Use an alternate output format that, among other things, uses a different heading style and marks \"=item\" entries with a colon in the left margin."
        },
        {
            "flag": "",
            "long": "--code",
            "arg": null,
            "description": "[1.11] Include any non-POD text from the input file in the output as well. Useful for viewing code documented with POD blocks with the POD rendered and the code left intact."
        },
        {
            "flag": "-c",
            "long": "--color",
            "arg": null,
            "description": "[1.00] Format the output with ANSI color escape sequences. Using this option requires that Term::ANSIColor be installed on your system."
        },
        {
            "flag": "-e",
            "long": "--encoding",
            "arg": null,
            "description": "[5.00] Specifies the encoding of the output. encoding must be an encoding recognized by the Encode module (see Encode::Supported). If the output contains characters that cannot be represented in this encoding, that is an error that will be reported as configured by the \"errors\" option. If error handling is other than \"die\", the unrepresentable character will be replaced with the Encode substitution character (normally \"?\"). WARNING: The input encoding of the POD source is independent from the output encoding, and setting this option does not affect the interpretation of the POD input. Unless your POD source is US-ASCII, its encoding should be declared with the \"=encoding\" command in the source, as near to the top of the file as possible. If this is not done, Pod::Simple will will attempt to guess the encoding and may be successful if it's Latin-1 or UTF-8, but it will produce warnings. See perlpod(1) for more information. --errors=style [2.5.0] Set the error handling style. \"die\" says to throw an exception on any POD formatting error. \"stderr\" says to report errors on standard error, but not to throw an exception. \"pod\" says to include a POD ERRORS section in the resulting documentation summarizing the errors. \"none\" ignores POD errors entirely, as much as possible. The default is \"die\". --guesswork=rule[,rule...] [5.01] By default, pod2text applies some default formatting rules based on guesswork and regular expressions that are intended to make writing Perl documentation easier and require less explicit markup. These rules may not always be appropriate, particularly for documentation that isn't about Perl. This option allows turning all or some of it off. The special rule \"all\" enables all guesswork. This is also the default for backward compatibility reasons. The special rule \"none\" disables all guesswork. Otherwise, the value of this option should be a comma-separated list of one or more of the following keywords: quoting If no guesswork is enabled, any text enclosed in C<> is surrounded by double quotes in nroff (terminal) output unless the contents are already quoted. When this guesswork is enabled, quote marks will also be suppressed for Perl variables, function names, function calls, numbers, and hex constants. Any unknown guesswork name is silently ignored (for potential future compatibility), so be careful about spelling."
        },
        {
            "flag": "-i",
            "long": "--indent",
            "arg": "_",
            "description": "[1.00] Set the number of spaces to indent regular text, and the default indentation for \"=over\" blocks. Defaults to 4 spaces if this option isn't given."
        },
        {
            "flag": "-h",
            "long": "--help",
            "arg": null,
            "description": "[1.00] Print out usage information and exit."
        },
        {
            "flag": "-l",
            "long": "--loose",
            "arg": null,
            "description": "[1.00] Print a blank line after a \"=head1\" heading. Normally, no blank line is printed after \"=head1\", although one is still printed after \"=head2\", because this is the expected formatting for manual pages; if you're formatting arbitrary text documents, using this option is recommended."
        },
        {
            "flag": "-m",
            "long": "--margin",
            "arg": null,
            "description": "[1.24] The width of the left margin in spaces. Defaults to 0. This is the margin for all text, including headings, not the amount by which regular text is indented; for the latter, see -i option."
        },
        {
            "flag": "",
            "long": "--nourls",
            "arg": null,
            "description": "[2.5.0] Normally, L<> formatting codes with a URL but anchor text are formatted to show both the anchor text and the URL. In other words: L<foo|http://example.com/> is formatted as: foo <http://example.com/> This flag, if given, suppresses the URL when anchor text is given, so this example would be formatted as just \"foo\". This can produce less cluttered output in cases where the URLs are not particularly important."
        },
        {
            "flag": "-o",
            "long": "--overstrike",
            "arg": null,
            "description": "[1.06] Format the output with overstrike printing. Bold text is rendered as character, backspace, character. Italics and file names are rendered as underscore, backspace, character. Many pagers, such as less, know how to convert this to bold or underlined text."
        },
        {
            "flag": "-q",
            "long": "--quotes",
            "arg": null,
            "description": "[4.00] Sets the quote marks used to surround C<> text to quotes. If quotes is a single character, it is used as both the left and right quote. Otherwise, it is split in half, and the first half of the string is used as the left quote and the second is used as the right quote. quotes may also be set to the special value \"none\", in which case no quote marks are added around C<> text."
        },
        {
            "flag": "-s",
            "long": "--sentence",
            "arg": null,
            "description": "[1.00] Assume each sentence ends with two spaces and try to preserve that spacing. Without this option, all consecutive whitespace in non-verbatim paragraphs is compressed into a single space."
        },
        {
            "flag": "",
            "long": "--stderr",
            "arg": null,
            "description": "[2.1.3] By default, pod2text dies if any errors are detected in the POD input. If --stderr is given and no --errors flag is present, errors are sent to standard error, but pod2text does not abort. This is equivalent to \"--errors=stderr\" and is supported for backward compatibility."
        },
        {
            "flag": "-t",
            "long": "--termcap",
            "arg": null,
            "description": "[1.00] Try to determine the width of the screen and the bold and underline sequences for the terminal from termcap, and use that information in formatting the output. Output will be wrapped at two columns less than the width of your terminal device. Using this option requires that your system have a termcap file somewhere where Term::Cap can find it and requires that your system support termios. With this option, the output of pod2text will contain terminal control sequences for your current terminal type."
        },
        {
            "flag": "-u",
            "long": "--utf8",
            "arg": null,
            "description": "[2.2.0] Set the output encoding to UTF-8. This is equivalent to \"--encoding=UTF-8\" and is supported for backward compatibility."
        },
        {
            "flag": "-w",
            "long": "--width",
            "arg": "_",
            "description": "[1.00] The column at which to wrap text on the right-hand side. Defaults to 76, unless -t is given, in which case it's two columns less than the width of your terminal device."
        }
    ],
    "examples": [],
    "see_also": [
        {
            "name": "perlpod",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/perlpod/1/json"
        }
    ]
}