Pod::Man(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

🌸 Pod::Man 💖

ok so bestie, you're looking at Pod::Man(3perl) from the Perl Programmers Reference Guide — that's the whole vibe of this page. It's the module that turns POD into *roff man pages, and honestly? iconic. Let's get into it ✨

✨ NAME ✨

Pod::Man — it converts POD data into formatted *roff input. that's it, that's the whole job, and she does it flawlessly 💅

🦋 SYNOPSIS 🦋

use Pod::Man;
my $parser = Pod::Man->new (release => $VERSION, section => 8);

# Read POD from STDIN and write to STDOUT.
$parser->parse_file (\*STDIN);

# Read POD from file.pod and write to file.1.
$parser->parse_from_file ('file.pod', 'file.1');

like. look at her. three lines and she's already doing the most 🎀

💜 DESCRIPTION 💜

okay so Pod::Man is the module that takes documentation written in POD (which is, no cap, the preferred language for documenting Perl) and converts it into *roff input using the man macro set. the resulting *roff code is perfect for showing on your terminal with nroff(1) — usually through man(1) — or for printing with troff(1). conventionally you'd invoke it with the driver script pod2man, but bestie she can also be used directly. main character energy, honestly 👑

By default (on non-EBCDIC systems, iykyk), Pod::Man outputs UTF-8. her output should work with the man program on systems that use groff (most Linux distros) or mandoc (most BSD variants), but it may result in mangled output on older UNIX systems. 😭 if you need a different, possibly more backward-compatible output mangling on those systems, set the encoding option to roff — that was the default in earlier Pod::Man versions, fun fact ✨. see the encoding option and the ENCODING section for more details.

Also go peep the COMPATIBILTY section for the versions of Pod::Man with significant backward-incompatible changes (not counting constructor options, because those versions are documented down below, don't worry 🫶), plus which versions of Perl shipped them.

👑 CLASS METHODS 👑

🌟 new(ARGS) 🌟

Creates a brand new Pod::Man object. ARGS should be a list of key/value pairs, where the keys are picked from the following. every option is annotated with the version of Pod::Man where that option was added with its current meaning — so like, a little glow-up timeline 📜✨

  • center — [1.00] sets the centered page header for the .TH macro. if you don't specify this option, the default is User Contributed Perl Documentation.
  • date — [4.00] sets the left-hand footer for the .TH macro. if this option isn't set, the contents of the environment variable POD_MAN_DATE get used, if it's set. failing that? the value of SOURCE_DATE_EPOCH, or the modification date of the input file, or the current time if stat() can't find that file — which, bestie, will be the case if the input is coming from STDIN. 😬 if it's taken from any source other than POD_MAN_DATE (which gets used verbatim, no edits), the date gets formatted as YYYY-MM-DD and is based on UTC, so that the output stays reproducible no matter what your local time zone is doing. slay for determinism 🕰️
  • encoding — [5.00] specifies the encoding of the output. the value has to be an encoding recognized by the Encode module (see Encode::Supported), or one of the special values roff or groff. the default on non-EBCDIC systems is UTF-8.

if the output contains characters that can't be represented in this encoding, that's an error — reported as configured by the errors option. if error handling is anything other than die, the unrepresentable character gets replaced with the Encode substitution character (normally ?).

if the encoding option is set to the special value groff (the default on EBCDIC systems), or if the Encode module isn't available and the encoding is set to anything other than roff, Pod::Man will translate all non-ASCII characters to \[uNNNN] Unicode escapes. these aren't traditionally part of the *roff language, but they are supported by groff and mandoc — and therefore by the majority of manual page processors in use today 💪

if the encoding option is set to the special value roff, Pod::Man falls back to her historic transformation of (some) ISO 8859-1 characters into *roff escapes, which may be adequate in troff and may be readable (if ugly) in nroff 🙈. this was the default behavior of Pod::Man versions before 5.00. with this encoding, all other non-ASCII characters get replaced with X. it might be required for very old troff and nroff implementations that don't support UTF-8, but ngl its representation of any non-ASCII character is very poor and often specific to European languages. not her finest era fr fr

if the output file handle has a PerlIO encoding layer set, setting encoding to anything other than groff or roff gets ignored and no encoding will be done by Pod::Man at all. instead she'll rely on the encoding layer to make whatever output encoding transformations you want.

⚠️ 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. if you don't do that, Pod::Simple 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 info 🫶
  • errors — [2.27] how to report errors. die says to throw an exception on any POD formatting error. stderr says to report errors on standard error, but not 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 pod. ✨
  • fixed — [1.00] the fixed-width font to use for verbatim text and code. defaults to CW. some systems prefer CR instead. only matters for troff output.
  • fixedbold — [1.00] bold version of the fixed-width font. defaults to CB. only matters for troff output.
  • fixeditalic — [1.00] italic version of the fixed-width font (which is kind of a misnomer, since most fixed-width fonts only have an oblique version, not a true italic version 🙃). defaults to CI. only matters for troff output.
  • fixedbolditalic — [1.00] bold italic (in theory; probably oblique in practice) version of the fixed-width font. Pod::Man doesn't assume you even have this, and defaults to CB. some systems (like Solaris) have this font available as CX. only matters for troff output.
  • guesswork — [5.00] by default, Pod::Man applies some default formatting rules based on guesswork and regular expressions, intended to make writing Perl documentation easier and require less explicit markup. these rules may not always be appropriate, especially for documentation that isn't about Perl. this option lets you turn all or some of it off 🔇

the special value all enables all guesswork. it's also the default, for backward compatibility reasons. the special value none disables all guesswork. otherwise, the value should be a comma-separated list of one or more of these keywords:

  • functions — convert function references like foo() to bold even if they have no markup. the function name accepts valid Perl characters for function names (including :), and the trailing parentheses must be present and empty.
  • manref — make the first part (before the parentheses) of manual page references like foo(1) bold even if they have no markup. the section must be a single number optionally followed by lowercase letters.
  • 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.
  • variables — convert Perl variable names to a fixed-width font even if they have no markup. this transformation will only be apparent in troff output, or some other output format (unlike nroff terminal output) that supports fixed-width fonts.

any unknown guesswork name is silently ignored (for potential future compatibility), so bestie... be careful about spelling. 👀

  • language — [5.00] adds commands telling groff that the input file is in the given language. the value of this setting must be a language abbreviation for which groff provides supplemental configuration, such as ja (for Japanese) or zh (for Chinese).

specifically, this adds:

.mso <language>.tmac
.hla <language>

to the start of the file, which configures correct line breaking for the specified language. without these commands, groff may not know how to add proper line breaks for Chinese and Japanese text if the manual page is installed into the normal manual page directory, such as /usr/share/man 😭

on many systems, this gets done automatically if the manual page is installed into a language-specific manual page directory, such as /usr/share/man/zh_CN. in that case, this option isn't required 🎀

unfortunately, the commands added with this option are specific to groff and will not work with other troff and nroff implementations. sorry bestie 💀

  • lquote / rquote — [4.08] sets the quote marks used to surround C<> text. lquote sets the left quote mark and rquote sets the right quote mark. either one may also be set to the special value none, in which case no quote mark gets added on that side of the C<> text (but the font is still changed for troff output). ✨

also check the quotes option, which sets both quotes at once. if both quotes and one of these other options is set, lquote or rquote overrides quotes. 💅

more coming, bestie — don't go anywhere 🦋

  • name — [4.08] sets the name of the manual page for the .TH macro. If you don't give it, the manual name is set to the uppercased base name of the file being converted, unless the manual section is 3 — then the path gets parsed to see if it's a Perl module path. If it is, a path like .../lib/Pod/Man.pm is converted into a name like Pod::Man. This option, if given, overrides any automatic determination of the name. 💅

If you're generating a manual page from standard input, the name will be set to STDIN if this option is not provided. In this case, providing this option is strongly recommended to set a meaningful manual page name. no cap.

  • nourls — [2.27] 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 option, if set to a true value, 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. iconic.

  • quotes — [4.00] Sets the quote marks used to surround C<> text. If the value 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. 🎀

This may also be set to the special value "none", in which case no quote marks are added around C<> text (but the font is still changed for troff output).

Also see the "lquote" and "rquote" options, which can be used to set the left and right quotes independently. If both "quotes" and one of the other options is set, "lquote" or "rquote" overrides "quotes". periodt.

  • release — [1.00] Set the centered footer for the .TH macro. By default, this is set to the version of Perl you run Pod::Man under. Setting this to the empty string will cause some *roff implementations to use the system default value. 🙈

Note that some system "an" macro sets assume that the centered footer will be a modification date and will prepend something like "Last modified: ". If this is the case for your target system, you may want to set "release" to the last modified date and "date" to the version number. iykyk.

  • section — [1.00] Set the section for the .TH macro. The standard section numbering convention is to use 1 for user commands, 2 for system calls, 3 for functions, 4 for devices, 5 for file formats, 6 for games, 7 for miscellaneous information, and 8 for administrator commands. There is a lot of variation here, however; some systems (like Solaris) use 4 for file formats, 5 for miscellaneous information, and 7 for devices. Still others use 1m instead of 8, or some mix of both. About the only section numbers that are reliably consistent are 1, 2, and 3. 💀

By default, section 1 will be used unless the file ends in .pm in which case section 3 will be selected.

  • stderr — [2.19] If set to a true value, send error messages about invalid POD to standard error instead of appending a POD ERRORS section to the generated *roff output. This is equivalent to setting "errors" to "stderr" if "errors" is not already set.

This option is for backward compatibility with Pod::Man versions that did not support "errors". Normally, the "errors" option should be used instead.

  • utf8 — [2.21] This option used to set the output encoding to UTF-8. Since this is now the default, it is ignored and does nothing. lowkey useless now, bestie.

✨ INSTANCE METHODS ✨

As a derived class from Pod::Simple, Pod::Man supports the same methods and interfaces. See Pod::Simple for all the details. This section summarizes the most-frequently-used methods and the ones added by Pod::Man. 🫶

💖 output_fh(FH) 💖

Direct the output from parse_file(), parse_lines(), or parse_string_document() to the file handle FH instead of "STDOUT".

🌸 output_string(REF) 🌸

Direct the output from parse_file(), parse_lines(), or parse_string_document() to the scalar variable pointed to by REF, rather than "STDOUT". For example:

my $man = Pod::Man->new();
my $output;
$man->output_string(\$output);
$man->parse_file('/some/input/file');

Be aware that the output in that variable will already be encoded in UTF-8.

🦋 parse_file(PATH) 🦋

Read the POD source from PATH and format it. By default, the output is sent to "STDOUT", but this can be changed with the output_fh() or output_string() methods.

🌈 parse_from_file(INPUT, OUTPUT) / parse_from_filehandle(FH, OUTPUT) 🌈

Read the POD source from INPUT, format it, and output the results to OUTPUT.

parse_from_filehandle() is provided for backward compatibility with older versions of Pod::Man. parse_from_file() should be used instead. no cap.

⭐ parse_lines(LINES[, ...[, undef]]) ⭐

Parse the provided lines as POD source, writing the output to either "STDOUT" or the file handle set with the output_fh() or output_string() methods. This method can be called repeatedly to provide more input lines. An explicit "undef" should be passed to indicate the end of input.

This method expects raw bytes, not decoded characters. 💅

🎀 parse_string_document(INPUT) 🎀

Parse the provided scalar variable as POD source, writing the output to either "STDOUT" or the file handle set with the output_fh() or output_string() methods.

This method expects raw bytes, not decoded characters. periodt.

🌈 ENCODING 🌈

Okay bestie, this is a big one, so buckle up. ✨

Since Pod::Man 5.00, the default output encoding is UTF-8. And like, it should just work on any modern system using either groff (that's most Linux distros, bestie) or mandoc (Alpine Linux and most BSD variants, including macOS, no cap). 🦋

The user will probably have to be in a UTF-8 locale to see correct output though. Sometimes that's the default; if it's not, set the LANG or LC_CTYPE environment variables to a locale that's actually right for you. The locale C.UTF-8 is available on most systems if you want correct output without changing all the other stuff locales affect, like collation. 💅

The backward-compatible output format from Pod::Man versions before 5.00 is still there — just set the encoding option to roff. It might give you marginally nicer results on older UNIX versions that don't use groff or mandoc, but listen: none of the available options will correctly render Unicode characters on those systems. Periodt.

Below are some additional details about how this choice was made, plus some discussion of alternatives. Grab a snack. 🍓

🌸 History 🌸

The default output encoding for Pod::Man has been a long-standing problem, fr fr. troff and nroff predate Unicode by a significant margin, and their implementations for many UNIX systems reflect that legacy. It's common for Unicode to not be supported in any form. 😭

Because of this, versions of Pod::Man prior to 5.00 maintained the highly conservative output of the original pod2man, which output pure ASCII with complex macros to simulate common western European accented characters when processed with troff. The nroff output was awkward and sometimes incorrect, and characters not used in western European scripts were replaced with "X". This choice maximized backwards compatibility with man and nroff/troff implementations at the cost of incorrect rendering of many POD documents, particularly those containing people's names. 🙈

The modern implementations, groff (used in most Linux distributions) and mandoc (used by most BSD variants), do now support Unicode. Other UNIX systems often do not, but they're now a tiny minority of the systems people use on a daily basis. It's increasingly common (for very good reasons) to use Unicode characters for POD documents rather than using ASCII conversions of people's names or avoiding non-English text, which makes the limitations in the old output format more apparent.

Four options have been proposed to fix this:

  • Optionally support UTF-8 output but don't change the default. This is the approach taken since Pod::Man 2.1.0, which added the utf8 option. Some Pod::Man users use this option for better output on platforms known to support Unicode, but since the defaults have not changed, people continued to encounter (and file bug reports about) the poor default rendering.
  • Convert characters to troff \(xx escapes. This requires maintaining a large translation table and addresses only a tiny part of the problem, since many Unicode characters have no standard troff name. groff has the largest list, but if one is willing to assume groff is the formatter, the next option is better.
  • Convert characters to groff \[uNNNN] escapes. This is implemented as the groff encoding for those who want to use it, and is supported by both groff and mandoc. However, it is no better than UTF-8 output for portability to other implementations. See "Testing results" for more details.
  • Change the default output format to UTF-8 and ask those who want maximum backward compatibility to explicitly select the old encoding. This fixes the issue for most users at the cost of backwards compatibility. While the rendering of non-ASCII characters is different on older systems that don't support UTF-8, it's not always worse than the old output.

Pod::Man 5.00 and later makes the last choice. This arguably produces worse output when manual pages are formatted with troff into PostScript or PDF, but doing this is rare and normally manual, so the encoding can be changed in those cases. The older output encoding is available by setting encoding to roff.

🧚 Testing results 🧚

Here is the results of testing encoding values of utf-8 and groff on various operating systems. The testing methodology was to create man/man1 in the current directory, copy encoding.utf8 or encoding.groff from the podlators 5.00 distribution to man/man1/encoding.1, and then run:

LANG=C.UTF-8 MANPATH=$(pwd)/man man 1 encoding

If the locale is not explicitly set to one that includes UTF-8, the Unicode characters were usually converted to ASCII (by, for example, dropping an accent) or deleted or replaced with "<?>" if there was no conversion.

Tested on 2022-09-25. Many thanks to the GCC Compile Farm project for access to testing hosts. 🫶

  • AIX 7.1 — UTF-8: no [1] · groff: no [2]
  • Alpine 3.15.0 — UTF-8: yes · groff: yes
  • CentOS 7.9 — UTF-8: yes · groff: yes
  • Debian 7 — UTF-8: yes · groff: yes
  • FreeBSD 13.0 — UTF-8: yes · groff: yes
  • NetBSD 9.2 — UTF-8: yes · groff: yes
  • OpenBSD 7.1 — UTF-8: yes · groff: yes
  • openSUSE Leap 15.4 — UTF-8: yes · groff: yes
  • Solaris 10 — UTF-8: yes · groff: no [2]
  • Solaris 11 — UTF-8: no [3] · groff: no [3]

I did not have access to a macOS system for testing, but since it uses mandoc, it's behavior is probably the same as the BSD hosts. 🦋

Notes:

  • [1] Unicode characters were converted to one or two random ASCII characters unrelated to the original character.
  • [2] Unicode characters were shown as the body of the groff escape rather than the indicated character (in other words, text like "[u00EF]").
  • [3] Unicode characters were deleted entirely, as if they weren't there. Using nroff -man instead of man to format the page showed the same results as Solaris 10. Using groff -k -man -Tutf8 to format the page produced the correct output.

PostScript and PDF output using groff on a Debian 12 system do not support combining accent marks or SMP characters due to a lack of support in the default output font. 💀

Testing on additional platforms is welcome. Please let the author know if you have additional results.

💅 DIAGNOSTICS 💅

  • roff font should be 1 or 2 chars, not "%s" — (F) You specified a *roff font (using fixed, fixedbold, etc.) that wasn't either one or two characters. Pod::Man doesn't support *roff fonts longer than two characters, although some *roff extensions do (the canonical versions of nroff and troff don't either).
  • Invalid errors setting "%s" — (F) The errors parameter to the constructor was set to an unknown value.
  • Invalid quote specification "%s" — (F) The quote specification given (the quotes option to the constructor) was invalid. A quote specification must be either one character long or an even number (greater than one) characters long.
  • POD document had syntax errors — (F) The POD document being formatted had syntax errors and the errors option was set to die.

👑 ENVIRONMENT 👑

  • PERL_CORE — If set and Encode is not available, silently fall back to an encoding of groff without complaining to standard error. This environment variable is set during Perl core builds, which build Encode after podlators. Encode is expected to not (yet) be available in that case. 😌
  • POD_MAN_DATE — If set, this will be used as the value of the left-hand footer unless the date option is explicitly set, overriding the timestamp of the input file or the current time. This is primarily useful to ensure reproducible builds of the same output file given the same source and Pod::Man version, even when file timestamps may not be consistent. ✨
  • SOURCE_DATE_EPOCH — If set, and POD_MAN_DATE and the date options are not set, this will be used as the modification time of the source file, overriding the timestamp of the input file or the current time. It should be set to the desired time in seconds since UNIX epoch. This is primarily useful to ensure reproducible builds of the same output file given the same source and Pod::Man version, even when file timestamps may not be consistent. See <https://reproducible-builds.org/specs/source-date-epoch/> for the full specification.
Arguably, according to the specification, this variable should be used only if the timestamp of the input file is not available and Pod::Man uses the current time. However, for reproducible builds in Debian, results were more reliable if this variable overrode the timestamp of the input file. 🙈

🌈 COMPATIBILITY 🌈

okay bestie, history lesson time, because this module has been through it 💀

  • Pod::Man 1.02 (built on Pod::Parser) was the very first version to ship with Perl — that was in Perl 5.6.0. iconic founding mother behavior.
  • The current API, the one based on Pod::Simple, showed up in Pod::Man 2.00. Then Pod::Man 2.04 landed in Perl 5.9.3, which was the first Perl to actually incorporate those changes. And THIS is the first version that correctly supports all modern POD syntax ✨ periodt. Oh and the parse_from_filehandle() method got re-added for backward compatibility in Pod::Man 2.09, which came with Perl 5.9.4.
  • Support for anchor text in L<> links of type URL? Added in Pod::Man 2.23, included in Perl 5.11.5 💅
  • parse_lines(), parse_string_document(), and parse_file() started setting a default output file handle of STDOUT if one wasn't already set, as of Pod::Man 2.28, included in Perl 5.19.5.
  • Support for SOURCE_DATE_EPOCH and POD_MAN_DATE got added in Pod::Man 4.00, included in Perl 5.23.7 — and generated dates switched to using UTC instead of the local time zone 🕐. That's also the first release that aligned the module version with the version of the podlators distribution. From this point forward, all modules included in podlators — and the podlators distribution itself — share the same version number. one version to rule them all fr fr 👑
  • Pod::Man 4.10, included in Perl 5.27.8, changed the formatting for manual page references and function names to bold instead of italic, following the current Linux manual page standard. glow up 💖
  • Pod::Man 5.00, included in Perl 5.37.7, changed the default output encoding to UTF-8, overridable with the new encoding option. It also fixed problems with bold or italic extending too far when used with C<> escapes, and began converting Unicode zero-width spaces (U+200B) to the "\:" roff escape. It *also dropped attempts to add subtle formatting corrections in the output that would only be visible when typeset with troff — which had previously been a significant source of bugs. good riddance honestly 🙈
  • Pod::Man v6.0.0 and later unconditionally convert "-" to the "\-" *roff escape, representing an ASCII hyphen-minus. Earlier versions tried to use heuristics to decide when a given "-" character should translate to a hyphen-minus or a true hyphen, but those heuristics were buggy and fragile 😭. And v6.0.0 and later also unconditionally convert "`" and "'" to ASCII grave accent and apostrophe marks instead of the default *roff behavior of interpreting them as paired quotes. no more guessing, we love a decisive queen ✨

💀 BUGS 💀

ngl there are numerous bugs and language-specific assumptions in the nroff fallbacks for accented characters in the "roff" encoding 😬. But listen — since the whole point of that encoding is backward compatibility with the output from earlier versions of Pod::Man, and it's deprecated except when it's necessary to support old systems, those bugs are unlikely to ever be fixed. it is what it is 🫶

Also: Pod::Man doesn't handle font names longer than two characters. Neither do most troff implementations — but groff does, as an extension. It would be nice to support as an option for those who want to use it 🌸

🎀 CAVEATS 🎀

Sentence spacing

Pod::Man copies the input spacing verbatim to the output *roff document. Which means your output is gonna be affected by how nroff generally handles sentence spacing. it's giving "we don't editorialize, we just deliver" 💅

nroff dates from an era in which it was standard to use two spaces after sentences, and it will always add two spaces after a line-ending period (or similar punctuation) when reflowing text. For example, the following input:

=pod

One sentence.
Another sentence.

will result in two spaces after the period when the text is reflowed. If you use two spaces after sentences anyway, this will be consistent — although you'll have to be careful to not end a line with an abbreviation such as "e.g." or "Ms.". Output will also be consistent if you use the roff style guide (and XKCD 1285 https://xkcd.com/1285/) recommendation of putting a line break after each sentence, although that will *consistently produce two spaces after each sentence, which may not be what you want 😅

If you prefer one space after sentences (which is the more modern style), you will unfortunately need to ensure that no line in the middle of a paragraph ends in a period or similar sentence-ending paragraph. Otherwise, nroff will add a two spaces after that sentence when reflowing, and your output document will have inconsistent spacing 😭 the struggle is real.

Hyphens and quotes

The *roff language distinguishes between two types of hyphens:

  • "-", which is a true typesetting hyphen (roughly equivalent to the Unicode U+2010 code point) 🎀
  • "\-", which is the ASCII hyphen-minus (U+002D) — the one used for UNIX command options and most filenames 💻

Hyphens, where appropriate, produce better typesetting. But incorrectly using them for command names and options can cause problems with searching and cut-and-paste. 🙃

POD does not draw this distinction. Before podlators v6.0.0, Pod::Man attempted to translate "-" in the input into either a hyphen or a hyphen-minus, depending on context. However, this distinction proved impossible to do correctly with heuristics. So Pod::Man therefore translates all "-" characters in the input to "\-" in the output, ensuring that command names and options are correct at the cost of somewhat inferior typesetting and line breaking issues with long hyphenated phrases. trade-offs bestie, trade-offs ⚖️

To use true hyphens in the Pod::Man output, declare an input character set of UTF-8 (or some other Unicode encoding) and use Unicode hyphens. Pod::Man and *roff should handle those correctly with the default output format and most modern *roff implementations ✨

Similarly, Pod::Man disables the default *roff behavior of turning "`" and "'" characters into matched quotes, and pairs of those characters into matched double quotes — because there's no good way to tell from the POD input whether this interpretation is desired or whether the intent is to use a literal grave accent or neutral apostrophe 🤷‍♀️. If you want paired quotes in the output, use Unicode and its paired quote characters. that's the assignment 💅

👑 AUTHOR 👑

Written by Russ Allbery <rra@cpan.org>, based on the original pod2man by Tom Christiansen <tchrist@mox.perl.com>.

The modifications to work with Pod::Simple instead of Pod::Parser were contributed by Sean Burke <sburke@cpan.org>, but I've since hacked them beyond recognition and all bugs are mine 💀 iconic honesty honestly.

Copyright 1999-2020, 2022-2024 Russ Allbery <rra@cpan.org>

Substantial contributions by Sean Burke <sburke@cpan.org>.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. 🫶

🌟 SEE ALSO 🌟

Encode::Supported, Pod::Simple, perlpod(1), pod2man(1), nroff(1), troff(1), man(1), man(7)

Ossanna, Joseph F., and Brian W. Kernighan. "Troff User's Manual," Computing Science Technical Report No. 54, AT&T Bell Laboratories. This is the best documentation of standard nroff and troff 📚. At the time of this writing, it's available at http://www.troff.org/54.pdf.

The manual page documenting the man macro set may be man(5) instead of man(7) on your system. iykyk 🤷‍♀️

See perlpodstyle(1) for documentation on writing manual pages in POD if you've not done it before and aren't familiar with the conventions ✍️

The current version of this module is always available from its web site at https://www.eyrie.org/~eagle/software/podlators/. It is also part of the Perl core distribution as of 5.6.0 🌸

and that's the whole page bestie, we made it to the end 🎉 this one's perl v5.44.0, dated 2026-10-17, filed under Pod::Man(3perl). go forth and format your manual pages, you absolute icon 👑💖✨

📦 where this page comes from