podlators 5.00 released

Hi all,

This is the first major release of podlators, which provides Pod::Man and
Pod::Text, in some time.

The big change is that I finally did the research required to convince
myself that the rendering of UTF-8 output from Pod::Man is no worse than
the previous output, and far better on all modern systems.  This release
therefore changes the default output for Pod::Man to UTF-8 on non-EBCDIC
systems, and to use the groff \[uNNNN] extension (also supported by
mandoc) on EBCDIC systems.  This will hopefully mean the beginning of the
end of mangling people's names and languages with X characters.

Perl core maintainers, please note the new language option to Pod::Man and
the corresponding --language flag to pod2man.  You ideally should build
perljp with --language=ja and perlcn with --language=zh to get correct
line breaking, but unfortunately this only works on systems that use groff
(I'm not sure if mandoc is even enough), so it may need to be conditional
on the platform.

Here are all the changes since the previous release:

 - 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 (--guesswork 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.

-- 
#!/usr/bin/perl -- Russ Allbery, Just Another Perl Hacker
$^=q;@!>~|{>krw>yn{u<$$<[~||<Juukn{=,<S~|}<Jwx}qn{<Yn{u<Qjltn{ > 0gFzD gD,
 00Fz, 0,,( 0hF 0g)F/=, 0> "L$/GEIFewe{,$/ 0C$~> "@=,m,|,(e 0.), 01,pnn,y{
rw} >;,$0=q,$,,($_=$^)=~y,$/ C-~><@=\n\r,-~$:-u/ #y,d,s,(\$.),$1,gee,print

• podlators 5.00 released by Russ Allbery
• Re: podlators 5.00 released by Leon Timmermans
• Re: podlators 5.00 released by Russ Allbery
• Re: podlators 5.00 released by Russ Allbery
• Re: podlators 5.00 released by Leon Timmermans
• Re: podlators 5.00 released by Karen Etheridge
• Re: podlators 5.00 released by Ricardo Signes