Bug#457839: general: Many man pages display shell quotes ` and ' wrong in Unicode environment

[Russ Allbery <rra@debian.org>]

Neil Williams <codehelp@debian.org> writes:

> I used to come across this intermittently - usually when trying to copy
> and paste examples from a manpage. However, the situation appears solved
> in a Unicode environment:
>
> This perldoc code:
> Only print the list, do not call 'sudo dpkg -P'
> becomes this manpage content:
> \&Only print the list, do not call \(aqsudo dpkg \-P\(aq
> which displays as:
> Only print the list, do not call 'sudo dpkg -P'
>
> Changing the original code to:
> Only print the list, do not call `sudo dpkg -P`
> becomes this manpage content:
> \&Only print the list, do not call `sudo dpkg \-P`
> which displays as:
> Only print the list, do not call ‘sudo dpkg -P‘
>
> So it may be more useful to investigate the manpage generator packages
> rather than a bug against the 'general' metapackage. If I'm following
> this right, you would seek that pod2man retains the existing behaviour
> for ' (first example) and changes the handling of ` from ` to \ga
> (second example)?

This is fixed in the version of Pod::Man that will be included in Perl
5.10.  I think Brendan is currently working on getting that into
experimental.

For the record, \(aq is groff-specific, so upstreams who care about
platforms other than Linux won't like this change.  I'm not sure about
\(ga, but \` worked fine in my testing.  (\' doesn't; it generates an
acute accent mark instead.)

The new version of pod2man adds:

.ie \n(.g .ds Aq \(aq
.el       .ds Aq '

to the preamble and then uses \*(Aq for apostrophes, which falls back on a
regular ' for non-groff.  But non-groff generally don't do Unicode, and
this is therefore usually okay except in the rarer case of troff output.
It uses \` for grave accent marks.

If anyone knows of a more general solution, I'm all ears.

Note that it only does this in verbatim text and in C<> blocks, so people
who use 'text' or `text' in general text in POD will still get the Unicode
quotes.  I think this is the correct behavior, but I'm always open to
further suggestions.  (I'm upstream for Pod::Man.)

Given the number of pod2man-generated man pages, it's probably not worth
trying to track this down too much until we get an updated Pod::Man into
the archive.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>