{ "content": [ { "type": "text", "text": "# Pod::Man (perldoc)\n\n## NAME\n\nPod::Man - Convert POD data to formatted *roff input\n\n## SYNOPSIS\n\nuse Pod::Man;\nmy $parser = Pod::Man->new (release => $VERSION, section => 8);\n# Read POD from STDIN and write to STDOUT.\n$parser->parsefile (\\*STDIN);\n# Read POD from file.pod and write to file.1.\n$parser->parsefromfile ('file.pod', 'file.1');\n\n## DESCRIPTION\n\nPod::Man is a module to convert documentation in the POD format (the preferred language for\ndocumenting Perl) into *roff input using the man macro set. The resulting *roff code is suitable\nfor display on a terminal using nroff(1), normally via man(1), or printing using troff(1). It is\nconventionally invoked using the driver script pod2man, but it can also be used directly.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **CLASS METHODS** (1 subsections)\n- **INSTANCE METHODS** (7 subsections)\n- **ENCODING** (2 subsections)\n- **DIAGNOSTICS**\n- **ENVIRONMENT**\n- **COMPATIBILITY** (1 subsections)\n- **BUGS**\n- **CAVEATS** (2 subsections)\n- **AUTHOR**\n- **COPYRIGHT AND LICENSE**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Pod::Man", "section": "", "mode": "perldoc", "summary": "Pod::Man - Convert POD data to formatted *roff input", "synopsis": "use Pod::Man;\nmy $parser = Pod::Man->new (release => $VERSION, section => 8);\n# Read POD from STDIN and write to STDOUT.\n$parser->parsefile (\\*STDIN);\n# Read POD from file.pod and write to file.1.\n$parser->parsefromfile ('file.pod', 'file.1');", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "perlpod", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/perlpod/1/json" }, { "name": "pod2man", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/pod2man/1/json" }, { "name": "nroff", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/nroff/1/json" }, { "name": "troff", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/troff/1/json" }, { "name": "man", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/man/1/json" }, { "name": "man", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/man/7/json" }, { "name": "man", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/man/5/json" }, { "name": "man", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/man/7/json" }, { "name": "perlpodstyle", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/perlpodstyle/1/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 9, "subsections": [] }, { "name": "DESCRIPTION", "lines": 16, "subsections": [] }, { "name": "CLASS METHODS", "lines": 1, "subsections": [ { "name": "new", "lines": 220 } ] }, { "name": "INSTANCE METHODS", "lines": 4, "subsections": [ { "name": "output_fh", "lines": 3 }, { "name": "output_string", "lines": 10 }, { "name": "parse_file", "lines": 3 }, { "name": "parse_from_file", "lines": 1 }, { "name": "parse_from_filehandle", "lines": 5 }, { "name": "parse_lines", "lines": 7 }, { "name": "parse_string_document", "lines": 5 } ] }, { "name": "ENCODING", "lines": 17, "subsections": [ { "name": "History", "lines": 45 }, { "name": "Testing results", "lines": 47 } ] }, { "name": "DIAGNOSTICS", "lines": 17, "subsections": [] }, { "name": "ENVIRONMENT", "lines": 25, "subsections": [] }, { "name": "COMPATIBILITY", "lines": 10, "subsections": [ { "name": "parse_lines", "lines": 17 } ] }, { "name": "BUGS", "lines": 9, "subsections": [] }, { "name": "CAVEATS", "lines": 1, "subsections": [ { "name": "Sentence spacing", "lines": 24 }, { "name": "Hyphens", "lines": 4 } ] }, { "name": "AUTHOR", "lines": 6, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 7, "subsections": [] }, { "name": "SEE ALSO", "lines": 15, "subsections": [] } ], "sections": { "NAME": { "content": "Pod::Man - Convert POD data to formatted *roff input\n", "subsections": [] }, "SYNOPSIS": { "content": "use Pod::Man;\nmy $parser = Pod::Man->new (release => $VERSION, section => 8);\n\n# Read POD from STDIN and write to STDOUT.\n$parser->parsefile (\\*STDIN);\n\n# Read POD from file.pod and write to file.1.\n$parser->parsefromfile ('file.pod', 'file.1');\n", "subsections": [] }, "DESCRIPTION": { "content": "Pod::Man is a module to convert documentation in the POD format (the preferred language for\ndocumenting Perl) into *roff input using the man macro set. The resulting *roff code is suitable\nfor display on a terminal using nroff(1), normally via man(1), or printing using troff(1). It is\nconventionally invoked using the driver script pod2man, but it can also be used directly.\n\nBy default (on non-EBCDIC systems), Pod::Man outputs UTF-8. Its output should work with the man\nprogram on systems that use groff (most Linux distributions) or mandoc (most BSD variants), but\nmay result in mangled output on older UNIX systems. To choose a different, possibly more\nbackward-compatible output mangling on such systems, set the \"encoding\" option to \"roff\" (the\ndefault in earlier Pod::Man versions). See the \"encoding\" option and \"ENCODING\" for more\ndetails.\n\nSee \"COMPATIBILTY\" for the versions of Pod::Man with significant backward-incompatible changes\n(other than constructor options, whose versions are documented below), and the versions of Perl\nthat included them.\n", "subsections": [] }, "CLASS METHODS": { "content": "", "subsections": [ { "name": "new", "content": "Create a new Pod::Man 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::Man in which\nthat option was added with its current meaning.\n\ncenter\n[1.00] Sets the centered page header for the \".TH\" macro. The default, if this option is\nnot specified, is \"User Contributed Perl Documentation\".\n\ndate\n[4.00] Sets the left-hand footer for the \".TH\" macro. If this option is not set, the\ncontents of the environment variable PODMANDATE, if set, will be used. Failing that,\nthe value of SOURCEDATEEPOCH, the modification date of the input file, or the current\ntime if stat() can't find that file (which will be the case if the input is from\n\"STDIN\") will be used. If taken from any source other than PODMANDATE (which is used\nverbatim), the date will be formatted as \"YYYY-MM-DD\" and will be based on UTC (so that\nthe output will be reproducible regardless of local time zone).\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), or the special values \"roff\" or \"groff\". The\ndefault on non-EBCDIC systems is UTF-8.\n\nIf the output contains characters that cannot be represented in this encoding, that is\nan error that will be reported as configured by the \"errors\" option. If error handling\nis other than \"die\", the unrepresentable character will be replaced with the Encode\nsubstitution character (normally \"?\").\n\nIf the \"encoding\" option is set to the special value \"groff\" (the default on EBCDIC\nsystems), or if the Encode module is not available and the encoding is set to anything\nother than \"roff\", Pod::Man will translate all non-ASCII characters to \"\\[uNNNN]\"\nUnicode escapes. These are not traditionally part of the *roff language, but are\nsupported by groff and mandoc and thus by the majority of manual page processors in use\ntoday.\n\nIf the \"encoding\" option is set to the special value \"roff\", Pod::Man will do its\nhistoric transformation of (some) ISO 8859-1 characters into *roff escapes that may be\nadequate in troff and may be readable (if ugly) in nroff. This was the default behavior\nof versions of Pod::Man before 5.00. With this encoding, all other non-ASCII characters\nwill be replaced with \"X\". It may be required for very old troff and nroff\nimplementations that do not support UTF-8, but its representation of any non-ASCII\ncharacter is very poor and often specific to European languages.\n\nIf the output file handle has a PerlIO encoding layer set, setting \"encoding\" to\nanything other than \"groff\" or \"roff\" will be ignored and no encoding will be done by\nPod::Man. It will instead rely on the encoding layer to make whatever output encoding\ntransformations 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. If this is not done, Pod::Simple will will attempt to guess the encoding and\nmay be successful if it's Latin-1 or UTF-8, but it will produce warnings. See perlpod(1)\nfor more information.\n\nerrors\n[2.27] 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\nfixed\n[1.00] The fixed-width font to use for verbatim text and code. Defaults to \"CW\". Some\nsystems prefer \"CR\" instead. Only matters for troff output.\n\nfixedbold\n[1.00] Bold version of the fixed-width font. Defaults to \"CB\". Only matters for troff\noutput.\n\nfixeditalic\n[1.00] Italic version of the fixed-width font (something of a misnomer, since most\nfixed-width fonts only have an oblique version, not an italic version). Defaults to\n\"CI\". Only matters for troff output.\n\nfixedbolditalic\n[1.00] Bold italic (in theory, probably oblique in practice) version of the fixed-width\nfont. Pod::Man doesn't assume you have this, and defaults to \"CB\". Some systems (such as\nSolaris) have this font available as \"CX\". Only matters for troff output.\n\nguesswork\n[5.00] By default, Pod::Man 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 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\nfunctions\nConvert function references like foo() to bold even if they have no markup. The\nfunction name accepts valid Perl characters for function names (including \":\"), and\nthe trailing parentheses must be present and empty.\n\nmanref\nMake the first part (before the parentheses) of manual page references like foo(1)\nbold even if they have no markup. The section must be a single number optionally\nfollowed by lowercase letters.\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\nvariables\nConvert Perl variable names to a fixed-width font even if they have no markup. This\ntransformation will only be apparent in troff output, or some other output format\n(unlike nroff terminal output) that supports fixed-width fonts.\n\nAny unknown guesswork name is silently ignored (for potential future compatibility), so\nbe careful about spelling.\n\nlanguage\n[5.00] Add commands telling groff that the input file is in the given language. The\nvalue of this setting must be a language abbreviation for which groff provides\nsupplemental configuration, such as \"ja\" (for Japanese) or \"zh\" (for Chinese).\n\nSpecifically, this adds:\n\n.mso .tmac\n.hla \n\nto the start of the file, which configure correct line breaking for the specified\nlanguage. Without these commands, groff may not know how to add proper line breaks for\nChinese and Japanese text if the manual page is installed into the normal manual page\ndirectory, such as /usr/share/man.\n\nOn many systems, this will be done automatically if the manual page is installed into a\nlanguage-specific manual page directory, such as /usr/share/man/zhCN. In that case,\nthis option is not required.\n\nUnfortunately, the commands added with this option are specific to groff and will not\nwork with other troff and nroff implementations.\n\nlquote\nrquote\n[4.08] Sets the quote marks used to surround C<> text. \"lquote\" sets the left quote mark\nand \"rquote\" sets the right quote mark. Either may also be set to the special value\n\"none\", in which case no quote mark is added on that side of C<> text (but the font is\nstill changed for troff output).\n\nAlso see the \"quotes\" option, which can be used to set both quotes at once. If both\n\"quotes\" and one of the other options is set, \"lquote\" or \"rquote\" overrides \"quotes\".\n\nname\n[4.08] Set the name of the manual page for the \".TH\" macro. Without this option, the\nmanual name is set to the uppercased base name of the file being converted unless the\nmanual section is 3, in which case the path is parsed to see if it is a Perl module\npath. If it is, a path like \".../lib/Pod/Man.pm\" is converted into a name like\n\"Pod::Man\". This option, if given, overrides any automatic determination of the name.\n\nIf generating a manual page from standard input, the name will be set to \"STDIN\" if this\noption is not provided. In this case, providing this option is strongly recommended to\nset a meaningful manual page name.\n\nnourls\n[2.27] 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\n\nis formatted as:\n\nfoo \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 (but the font is still changed for troff output).\n\nAlso see the \"lquote\" and \"rquote\" options, which can be used to set the left and right\nquotes independently. If both \"quotes\" and one of the other options is set, \"lquote\" or\n\"rquote\" overrides \"quotes\".\n\nrelease\n[1.00] Set the centered footer for the \".TH\" macro. By default, this is set to the\nversion of Perl you run Pod::Man under. Setting this to the empty string will cause some\n*roff implementations to use the system default value.\n\nNote that some system \"an\" macro sets assume that the centered footer will be a\nmodification date and will prepend something like \"Last modified: \". If this is the case\nfor your target system, you may want to set \"release\" to the last modified date and\n\"date\" to the version number.\n\nsection\n[1.00] Set the section for the \".TH\" macro. The standard section numbering convention is\nto use 1 for user commands, 2 for system calls, 3 for functions, 4 for devices, 5 for\nfile formats, 6 for games, 7 for miscellaneous information, and 8 for administrator\ncommands. There is a lot of variation here, however; some systems (like Solaris) use 4\nfor file formats, 5 for miscellaneous information, and 7 for devices. Still others use\n1m instead of 8, or some mix of both. About the only section numbers that are reliably\nconsistent are 1, 2, and 3.\n\nBy default, section 1 will be used unless the file ends in \".pm\" in which case section 3\nwill be selected.\n\nstderr\n[2.19] If set to a true value, send error messages about invalid POD to standard error\ninstead of appending a POD ERRORS section to the generated *roff output. This is\nequivalent to setting \"errors\" to \"stderr\" if \"errors\" is not already set.\n\nThis option is for backward compatibility with Pod::Man versions that did not support\n\"errors\". Normally, the \"errors\" option should be used instead.\n\nutf8\n[2.21] This option used to set the output encoding to UTF-8. Since this is now the\ndefault, it is ignored and does nothing.\n" } ] }, "INSTANCE METHODS": { "content": "As a derived class from Pod::Simple, Pod::Man 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::Man.\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 in UTF-8.\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" } ] }, "ENCODING": { "content": "As of Pod::Man 5.00, the default output encoding for Pod::Man is UTF-8. This should work\ncorrectly on any modern system that uses either groff (most Linux distributions) or mandoc\n(Alpine Linux and most BSD variants, including macOS).\n\nThe user will probably have to use a UTF-8 locale to see correct output. This may be done by\ndefault; if not, set the LANG or LCCTYPE environment variables to an appropriate local. The\nlocale \"C.UTF-8\" is available on most systems if one wants correct output without changing the\nother things locales affect, such as collation.\n\nThe backward-compatible output format used in Pod::Man versions before 5.00 is available by\nsetting the \"encoding\" option to \"roff\". This may produce marginally nicer results on older UNIX\nversions that do not use groff or mandoc, but none of the available options will correctly\nrender Unicode characters on those systems.\n\nBelow are some additional details about how this choice was made and some discussion of\nalternatives.\n", "subsections": [ { "name": "History", "content": "The default output encoding for Pod::Man has been a long-standing problem. troff and nroff\npredate Unicode by a significant margin, and their implementations for many UNIX systems reflect\nthat legacy. It's common for Unicode to not be supported in any form.\n\nBecause of this, versions of Pod::Man prior to 5.00 maintained the highly conservative output of\nthe original pod2man, which output pure ASCII with complex macros to simulate common western\nEuropean accented characters when processed with troff. The nroff output was awkward and\nsometimes incorrect, and characters not used in western European scripts were replaced with \"X\".\nThis choice maximized backwards compatibility with man and nroff/troff implementations at the\ncost of incorrect rendering of many POD documents, particularly those containing people's names.\n\nThe modern implementations, groff (used in most Linux distributions) and mandoc (used by most\nBSD variants), do now support Unicode. Other UNIX systems often do not, but they're now a tiny\nminority of the systems people use on a daily basis. It's increasingly common (for very good\nreasons) to use Unicode characters for POD documents rather than using ASCII conversions of\npeople's names or avoiding non-English text, making the limitations in the old output format\nmore apparent.\n\nFour options have been proposed to fix this:\n\n* Optionally support UTF-8 output but don't change the default. This is the approach taken since\nPod::Man 2.1.0, which added the \"utf8\" option. Some Pod::Man users use this option for better\noutput on platforms known to support Unicode, but since the defaults have not changed, people\ncontinued to encounter (and file bug reports about) the poor default rendering.\n\n* Convert characters to troff \"\\(xx\" escapes. This requires maintaining a large translation\ntable and addresses only a tiny part of the problem, since many Unicode characters have no\nstandard troff name. groff has the largest list, but if one is willing to assume groff is the\nformatter, the next option is better.\n\n* Convert characters to groff \"\\[uNNNN]\" escapes. This is implemented as the \"groff\" encoding\nfor those who want to use it, and is supported by both groff and mandoc. However, it is no\nbetter than UTF-8 output for portability to other implementations. See \"Testing results\" for\nmore details.\n\n* Change the default output format to UTF-8 and ask those who want maximum backward\ncompatibility to explicitly select the old encoding. This fixes the issue for most users at\nthe cost of backwards compatibility. While the rendering of non-ASCII characters is different\non older systems that don't support UTF-8, it's not always worse than the old output.\n\nPod::Man 5.00 and later makes the last choice. This arguably produces worse output when manual\npages are formatted with troff into PostScript or PDF, but doing this is rare and normally\nmanual, so the encoding can be changed in those cases. The older output encoding is available by\nsetting \"encoding\" to \"roff\".\n" }, { "name": "Testing results", "content": "Here is the results of testing \"encoding\" values of \"utf-8\" and \"groff\" on various operating\nsystems. The testing methodology was to create man/man1 in the current directory, copy\nencoding.utf8 or encoding.groff from the podlators 5.00 distribution to man/man1/encoding.1, and\nthen run:\n\nLANG=C.UTF-8 MANPATH=$(pwd)/man man 1 encoding\n\nIf the locale is not explicitly set to one that includes UTF-8, the Unicode characters were\nusually converted to ASCII (by, for example, dropping an accent) or deleted or replaced with\n\"\" if there was no conversion.\n\nTested on 2022-09-25. Many thanks to the GCC Compile Farm project for access to testing hosts.\n\nOS UTF-8 groff\n------------------ ------- -------\nAIX 7.1 no [1] no [2]\nAlpine 3.15.0 yes yes\nCentOS 7.9 yes yes\nDebian 7 yes yes\nFreeBSD 13.0 yes yes\nNetBSD 9.2 yes yes\nOpenBSD 7.1 yes yes\nopenSUSE Leap 15.4 yes yes\nSolaris 10 yes no [2]\nSolaris 11 no [3] no [3]\n\nI did not have access to a macOS system for testing, but since it uses mandoc, it's behavior is\nprobably the same as the BSD hosts.\n\nNotes:\n\n[1] Unicode characters were converted to one or two random ASCII characters unrelated to the\noriginal character.\n\n[2] Unicode characters were shown as the body of the groff escape rather than the indicated\ncharacter (in other words, text like \"[u00EF]\").\n\n[3] Unicode characters were deleted entirely, as if they weren't there. Using \"nroff -man\"\ninstead of man to format the page showed the same results as Solaris 10. Using \"groff -k\n-man -Tutf8\" to format the page produced the correct output.\n\nPostScript and PDF output using groff on a Debian 12 system do not support combining accent\nmarks or SMP characters due to a lack of support in the default output font.\n\nTesting on additional platforms is welcome. Please let the author know if you have additional\nresults.\n" } ] }, "DIAGNOSTICS": { "content": "roff font should be 1 or 2 chars, not \"%s\"\n(F) You specified a *roff font (using \"fixed\", \"fixedbold\", etc.) that wasn't either one or\ntwo characters. Pod::Man doesn't support *roff fonts longer than two characters, although\nsome *roff extensions do (the canonical versions of nroff and troff don't either).\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": [] }, "ENVIRONMENT": { "content": "PERLCORE\nIf set and Encode is not available, silently fall back to an encoding of \"groff\" without\ncomplaining to standard error. This environment variable is set during Perl core builds,\nwhich build Encode after podlators. Encode is expected to not (yet) be available in that\ncase.\n\nPODMANDATE\nIf set, this will be used as the value of the left-hand footer unless the \"date\" option is\nexplicitly set, overriding the timestamp of the input file or the current time. This is\nprimarily useful to ensure reproducible builds of the same output file given the same source\nand Pod::Man version, even when file timestamps may not be consistent.\n\nSOURCEDATEEPOCH\nIf set, and PODMANDATE and the \"date\" options are not set, this will be used as the\nmodification time of the source file, overriding the timestamp of the input file or the\ncurrent time. It should be set to the desired time in seconds since UNIX epoch. This is\nprimarily useful to ensure reproducible builds of the same output file given the same source\nand Pod::Man version, even when file timestamps may not be consistent. See\n for the full specification.\n\n(Arguably, according to the specification, this variable should be used only if the\ntimestamp of the input file is not available and Pod::Man uses the current time. However,\nfor reproducible builds in Debian, results were more reliable if this variable overrode the\ntimestamp of the input file.)\n", "subsections": [] }, "COMPATIBILITY": { "content": "Pod::Man 1.02 (based on Pod::Parser) was the first version included with Perl, in Perl 5.6.0.\n\nThe current API based on Pod::Simple was added in Pod::Man 2.00. Pod::Man 2.04 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::Man 2.09, included in Perl 5.9.4.\n\nSupport for anchor text in L<> links of type URL was added in Pod::Man 2.23, included in Perl\n5.11.5.\n", "subsections": [ { "name": "parse_lines", "content": "\"STDOUT\" if one was not already set as of Pod::Man 2.28, included in Perl 5.19.5.\n\nSupport for SOURCEDATEEPOCH and PODMANDATE was added in Pod::Man 4.00, included in Perl\n5.23.7, and generated dates were changed to use UTC instead of the local time zone. This is also\nthe first release that aligned the module version and the version of the podlators distribution.\nAll modules included in podlators, and the podlators distribution itself, share the same version\nnumber from this point forward.\n\nPod::Man 4.10, included in Perl 5.27.8, changed the formatting for manual page references and\nfunction names to bold instead of italic, following the current Linux manual page standard.\n\nPod::Man 5.00 changed the default output encoding to UTF-8, overridable with the new \"encoding\"\noption. It also fixed problems with bold or italic extending too far when used with C<> escapes,\nand began converting Unicode zero-width spaces (U+200B) to the \"\\:\" *roff escape. It also\ndropped attempts to add subtle formatting corrections in the output that would only be visible\nwhen typeset with troff, which had previously been a significant source of bugs.\n" } ] }, "BUGS": { "content": "There are numerous bugs and language-specific assumptions in the nroff fallbacks for accented\ncharacters in the \"roff\" encoding. Since the point of this encoding is backward compatibility\nwith the output from earlier versions of Pod::Man, and it is deprecated except when necessary to\nsupport old systems, those bugs are unlikely to ever be fixed.\n\nPod::Man doesn't handle font names longer than two characters. Neither do most troff\nimplementations, but groff does as an extension. It would be nice to support as an option for\nthose who want to use it.\n", "subsections": [] }, "CAVEATS": { "content": "", "subsections": [ { "name": "Sentence spacing", "content": "Pod::Man copies the input spacing verbatim to the output *roff document. This means your output\nwill be affected by how nroff generally handles sentence spacing.\n\nnroff dates from an era in which it was standard to use two spaces after sentences, and will\nalways add two spaces after a line-ending period (or similar punctuation) when reflowing text.\nFor example, the following input:\n\n=pod\n\nOne sentence.\nAnother sentence.\n\nwill result in two spaces after the period when the text is reflowed. If you use two spaces\nafter sentences anyway, this will be consistent, although you will have to be careful to not end\na line with an abbreviation such as \"e.g.\" or \"Ms.\". Output will also be consistent if you use\nthe *roff style guide (and XKCD 1285 ) recommendation of putting a line\nbreak after each sentence, although that will consistently produce two spaces after each\nsentence, which may not be what you want.\n\nIf you prefer one space after sentences (which is the more modern style), you will unfortunately\nneed to ensure that no line in the middle of a paragraph ends in a period or similar\nsentence-ending paragraph. Otherwise, nroff will add a two spaces after that sentence when\nreflowing, and your output document will have inconsistent spacing.\n" }, { "name": "Hyphens", "content": "The handling of hyphens versus dashes is somewhat fragile, and one may get a the wrong one under\nsome circumstances. This will normally only matter for line breaking and possibly for troff\noutput.\n" } ] }, "AUTHOR": { "content": "Written by Russ Allbery , based on the original pod2man by Tom Christiansen\n.\n\nThe modifications to work with Pod::Simple instead of Pod::Parser were contributed by Sean Burke\n, but I've since hacked them beyond recognition and all bugs are mine.\n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "Copyright 1999-2010, 2012-2020, 2022 Russ Allbery \n\nSubstantial contributions by Sean Burke .\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::Supported, Pod::Simple, perlpod(1), pod2man(1), nroff(1), troff(1), man(1), man(7)\n\nOssanna, Joseph F., and Brian W. Kernighan. \"Troff User's Manual,\" Computing Science Technical\nReport No. 54, AT&T Bell Laboratories. This is the best documentation of standard nroff and\ntroff. At the time of this writing, it's available at .\n\nThe manual page documenting the man macro set may be man(5) instead of man(7) on your system.\n\nSee perlpodstyle(1) for documentation on writing manual pages in POD if you've not done it\nbefore and aren't familiar with the conventions.\n\nThe current version of this module is always available from its web site at\n. It is also part of the Perl core\ndistribution as of 5.6.0.\n", "subsections": [] } } } }