podlators

Changes for version 5.00 - 2022-11-25

Drop support for Perl 5.8. The minimum required version is Perl 5.10.
The default output encoding of Pod::Man on non-EBCDIC systems is now UTF-8. The utf8 option (-u or --utf8 to pod2man) is now ignored, since it is the default. See the ENCODING section of its documentation for testing results and further discussion. (#68741)
Pod::Man now supports an encoding option (-e or --encoding to pod2man), to change the output encoding to any encoding recognized by Encode, or the special values groff or roff. Setting it to roff requests the old behavior of using character substitutions and *roff escapes to generate ASCII-only output (the default prior to this version).
Pod::Man now supports the groff output encoding, which replaces all non-ASCII characters with \[uNNNN] escapes. This escape was not supported by the originally *roff implementation, but it is supported by groff and mandoc and allows proper representation of Unicode characters. This output format has no known advantages in portability over UTF-8 on non-EBCDIC systems. It is the default output format on EBCDIC systems, and when the Encode module is not available. (#73804)
Pod::Man no longer does guesswork transformations that only affected troff output. Formatting manual pages with troff is exceptionally rare, and this magic caused constant maintenance issues. This means "--" is no longer changed to an em-dash, strings of capital letters aren't made a bit smaller, no attempt is made to change double quotes to paired quotes, and no special formatting is done for C++. (#132007)
Guesswork (formatting rules based on heuristics intended for Perl documentation) can now be disabled or selectively enabled in Pod::Man with the guesswork option (--guessword to pod2man). (#143668)
Pod::Text now supports an encoding option (-e or --encoding to pod2text) to force the output encoding, similar to Pod::Man. The utf8 option (-u or --utf8 to pod2text) is still supported and is equivalent to setting encoding to UTF-8.
Pod::Text now defaults to UTF-8 encoding if it sees a non-ASCII character on a non-EBCDIC system and the input encoding is not specified. This should fix rendering of E<> escapes of non-ASCII characters in POD files that don't specify an input encoding, at the cost of assuming UTF-8 output. Pod::Text also now commits to an encoding the first time it outputs a non-ASCII character and sticks with that encoding for the rest of the file, even if the detected or declared input encoding changes. (#102631)
Stop using a PerlIO encoding layer for Pod::Text output and instead use Encode. If a PerlIO encoding layer is already set, trust it and do no encoding. This fixes encoding problems with output to a string.
Add a coding tag comment to the start of Pod::Man output if the output encoding is not ASCII. groff's preconv program and FreeBSD's mandoc will use this line to determine the input encoding.
Pod::Man now supports a language option (--language to pod2man) that adds groff language configuration commands to the start of the output. This is required for proper line breaking of Japanese and Chinese text when the manual page is not installed in a language-specific directory so that the man program knows to add that configuration automatically. Unfortunately, the commands added when this option is used are groff-specific. Thanks to zynldyx for the bug report and suggested fix.
Pod::Man now converts Unicode zero-width spaces (U+200B) to the *roff escape \:, which indicates a line break point without a space or hyphen. (Unfortunately, groff does not honor U+200B itself as a line break point.) This escape is not part of the language defined in CSTR #54, but is supported by both groff and mandoc, so hopefully use of this escape won't cause problems. (Debian Bug#941980)
Pod::Man and Pod::Text now correctly honor S<> wrapping L<> with an anchor and URL, and make the space between the anchor and URL nonbreaking. (#143768)
Clear the current font before changing fonts in all Pod::Man output, not just headings. groff 1.22.4 does not clear bold or italic when seeing \f(CW font change, which meant bold and italic were extending farther than they should without this change. (#143667)
Honor the quotes, lquote, and rquote configuration parameters to Pod::Man for C<> text inside the special NAME section. (#143967)
Pod::Man suppresses quote marks around some additional cases of Perl code in C<> where the intent had been to suppress the quotes but there were various bugs in the matching regular expressions. This primarily affects method calls and negative numbers.
Avoid non-standard *roff escape in the troff accent mark definition for an acute accent. \h"..." was used instead of \h'...' as seen in the other accent mark definitions. This error appears to have existed since the first version of Pod::Man. Thanks, Paul Evans. (GitHub #14)
Document that nroff adds two spaces after each sentence when reflowing, and therefore if you want formatted Pod::Man output to consistently have one space after each sentence, you will have to avoid ending a sentence at the end of a line in the middle of a paragraph.