Re: Reasons to not use quote signs directly?
On Wed, 2016-09-21 at 01:59:10 +0200, Guillem Jover wrote:
> But I've found some quirks and issues that while not unsurmountable,
> might need to be looked at first and perhaps fixed or workarounds found
> to avoid "regressions", and I'm not sure which ones Russ would be happy
> to get bug reports for? :) I'm attaching a PoC conversion (can be tested
> with «pod2man deb-symbols.pod|man -l -», and is available also from [G])
> and here's a list of potential differences/issues:
I've been playing with this a bit, converted few more pages and
updated the build infrastructure, and it might be workable after all.
One ideal goal would be to try to get as less fuzzied strings as
possible after a conversion. Here's a list of alternatives/workarounds
for some of the issues/differences:
> - Link references are in italic not bold.
Can use B<man>(N) instead of L<man(N)>. Which might be needed anyway
to reduce the amount of fuzzy strings. The same to using I<> instead
of the more semantic F<>.
> - Does not map ‘’, “”, and other UTF-8 quotes to roff escape sequences
> (or have to use non-portable --utf8 option).
Could use UTF-8 in source and map to roff macros on install. This
would make the translations even easier. Arguably this could be done
already on the current raw man pages.
> - Needs raw roff for some formatting, as POD is not expressive enough
> (this will have to do with «=begin man» as pod2man cannot change
> the POD syntax anyway).
Seems to be really needed, mostly to markup verbatim blocks, otherwise
the formattig would need to be dropped. :/
> - Many minus signs are output as hyphens (for example for field names).
I don't think this can be easily fixed, not even in pod2man. :/ OTOH
although I've tried to be very strict about this, even man-db renders
hyphens as hyphen-minus, but this might not be a portable assumption?
> - Default for pod2man is no justified text.
Could use "=for man .ad b" before "=encoding utf8", but perhaps
there's no point after all. Ideally perhaps this would be controllable
> - The license blurb is only present as a comment on the source.
Given that the result is a generated file, I guess this can be
> [G] <https://git.hadrons.org/cgit/debian/dpkg/dpkg.git/log/?h=pu/man-switch-to-pod-trial>