Bug#941980: pod2man: Please convert zero-width space (u200B) to \:

[Russ Allbery]

Diederik de Haas  writes:

> $ aptitude show podlators-perl
> No candidate version found for podlators-perl
> Package: podlators-perl
> State: not a real package
> Provided by: perl (5.32.1-4+deb11u1), perl (5.32.1-4+deb11u2), perl (5.36.0-7)

> Does this mean that this bug is fixed in Stable and Testing/Unstable now?

No, the change isn't in 5.32 (or 5.34 or 5.36).  I expect it will probably
be in 5.38.

podlators is not separately packaged in Debian; Debian just uses the
version that comes with Perl.  This is usually simpler, but it means that
the time lag between a change and having it show up in Debian is fairly
long.  It has to make its way into Perl and then Perl has to make a new
stable release and Debian has to incorporate that stable release.  In
terms of stable releases, it won't be until the next Debian stable release
after the upcoming one, since Perl 5.38 isn't out yet.

In the interim, you would need to install Pod::Man directly from CPAN,
vian cpanm for example, to get the new behavior.

-- 
Russ Allbery (r...@debian.org)  

Bug#941980: pod2man: Please convert zero-width space (u200B) to \:

[Diederik de Haas]

Hi Russ,

On Sat, 26 Nov 2022 08:47:59 -0800 Russ Allbery  wrote:
> Russ Allbery  writes:
> > Jean-Michel Vourgère  writes:
> 
> >> I'm using pod to generate man files in package rrdtool.
> 
> >> I expected pod2man to generate the corect \: escape sequence, but it
> >> did not.
> 
> [...]
> 
> > Unfortunately, \: appears to be a groff extension as far as I can tell.
> > It's at least not mentioned in CSTR 54, nor in other older documentation
> > I can find for the *roff language.  That means this gets entangled in
> > the general design constraint that pod2man tries to produce portable
> > *roff output that's not specific to groff.
> 
> > I'm not certain this is fully correct because unfortunately it's very
> > difficult to search for \: to get more data.
> 
> Many years later, I have incorporated this change in podlators 5.00, just
> now released.  It will still be a bit before that's incorporated into Perl
> and thus into the Debian Perl packages, but I wanted to let you know that
> this fix is properly in progress.
> 
> I went ahead and did the conversion to \: unconditionally since it's
> documented in the mandoc roff reference as well as groff.  That covers
> nearly all modern platforms.  It may still not work on a few older nroff
> implementations like Solaris or AIX, but this case is obscure enough and
> enough other things related to Unicode don't work there anyway that I
> don't think it should cause any serious problems.

$ aptitude show podlators-perl
No candidate version found for podlators-perl
Package: podlators-perl
State: not a real package
Provided by: perl (5.32.1-4+deb11u1), perl (5.32.1-4+deb11u2), perl (5.36.0-7)

Does this mean that this bug is fixed in Stable and Testing/Unstable now?

Cheers,
  Diederik

signature.asc
Description: This is a digitally signed message part.

Bug#941980: pod2man: Please convert zero-width space (u200B) to \:

[Russ Allbery]

Russ Allbery  writes:
> Jean-Michel Vourgère  writes:

>> I'm using pod to generate man files in package rrdtool.

>> I had an issue with long man lines such as:
>> BIvnameE>=IrrdfileE>:Ids-nameE>:ICFE>[:step=IstepE>][:start=ItimeE>][:end=ItimeE>][:reduce=IBE>][:daemon=IaddressE>]
>> that results lintian "manpage-has-errors-from-man": can't break line.

>> That I fixed that by inserting unicode zero-width-space characters 200B:
>> BIvnameE>=IrrdfileE>:Ids-nameE>:ICFE>[:step=IstepE>][:start=ItimeE>]E<0x200B>[:end=ItimeE>]E<0x200B>[:reduce=IBE>]E<0x200B>[:daemon=IaddressE>]

>> I expected pod2man to generate the corect \: escape sequence, but it
>> did not.

[...]

> Unfortunately, \: appears to be a groff extension as far as I can tell.
> It's at least not mentioned in CSTR 54, nor in other older documentation
> I can find for the *roff language.  That means this gets entangled in
> the general design constraint that pod2man tries to produce portable
> *roff output that's not specific to groff.

> I'm not certain this is fully correct because unfortunately it's very
> difficult to search for \: to get more data.

Many years later, I have incorporated this change in podlators 5.00, just
now released.  It will still be a bit before that's incorporated into Perl
and thus into the Debian Perl packages, but I wanted to let you know that
this fix is properly in progress.

I went ahead and did the conversion to \: unconditionally since it's
documented in the mandoc roff reference as well as groff.  That covers
nearly all modern platforms.  It may still not work on a few older nroff
implementations like Solaris or AIX, but this case is obscure enough and
enough other things related to Unicode don't work there anyway that I
don't think it should cause any serious problems.

-- 
Russ Allbery (r...@debian.org)  

Bug#941980: pod2man: Please convert zero-width space (u200B) to \:

[Russ Allbery]

Jean-Michel Vourgère  writes:

> I'm using pod to generate man files in package rrdtool.

> I had an issue with long man lines such as:
> BIvnameE>=IrrdfileE>:Ids-nameE>:ICFE>[:step=IstepE>][:start=ItimeE>][:end=ItimeE>][:reduce=IBE>][:daemon=IaddressE>]
> that results lintian "manpage-has-errors-from-man": can't break line.

> That I fixed that by inserting unicode zero-width-space characters 200B:
> BIvnameE>=IrrdfileE>:Ids-nameE>:ICFE>[:step=IstepE>][:start=ItimeE>]E<0x200B>[:end=ItimeE>]E<0x200B>[:reduce=IBE>]E<0x200B>[:daemon=IaddressE>]

> I expected pod2man to generate the corect \: escape sequence, but it
> did not.

> Right now, as a work around, I'm using in my make file:
> pod2man ... --utf8 $< | sed -e $$'s|\u200B|:|g' > $@

> This is working great.

> However, it would be nice if pod2man would generate automatically the \:
> escape sequences, so that I don't have to sed the output!

Unfortunately, \: appears to be a groff extension as far as I can tell.
It's at least not mentioned in CSTR 54, nor in other older documentation I
can find for the *roff language.  That means this gets entangled in the
general design constraint that pod2man tries to produce portable *roff
output that's not specific to groff.

I'm not certain this is fully correct because unfortunately it's very
difficult to search for \: to get more data.

Sadly, \& doesn't seem to work here; if it did, this would be easy to fix
in pod2man.

I'll have to think about this a bit and ponder what the best approach
would be.  I'm still considering whether the time has come to just assume
that the output formatter is almost certainly going to be groff or
something compatible with groff and start using more groff-specific logic
(such as assuming that the formatter can handle Unicode output).

-- 
Russ Allbery (r...@debian.org)   

Bug#941980: pod2man: Please convert zero-width space (u200B) to \:

[Jean-Michel Vourgère]

Package: perl
Version: 5.28.1-6
Severity: normal
File: /usr/bin/pod2man

Dear Maintainer,

I'm using pod to generate man files in package rrdtool.

I had an issue with long man lines such as:
BIvnameE>=IrrdfileE>:Ids-nameE>:ICFE>[:step=IstepE>][:start=ItimeE>][:end=ItimeE>][:reduce=IBE>][:daemon=IaddressE>]
that results lintian "manpage-has-errors-from-man": can't break line.

That I fixed that by inserting unicode zero-width-space characters 200B:
BIvnameE>=IrrdfileE>:Ids-nameE>:ICFE>[:step=IstepE>][:start=ItimeE>]E<0x200B>[:end=ItimeE>]E<0x200B>[:reduce=IBE>]E<0x200B>[:daemon=IaddressE>]

I expected pod2man to generate the corect \: escape sequence, but it
did not.

Right now, as a work around, I'm using in my make file:
pod2man ... --utf8 $< | sed -e $$'s|\u200B|:|g' > $@

This is working great.

However, it would be nice if pod2man would generate automatically the \:
escape sequences, so that I don't have to sed the output!

One could argue that man should handle the "\u200B" character correctly,
but it seems logical to have pod2man do the escape as it would works both
with and without utf-8 encoding.

Thank you!

-- System Information:
Debian Release: 10.1
  APT prefers stable-updates
  APT policy: (500, 'stable-updates'), (500, 'stable')
Architecture: amd64 (x86_64)

Kernel: Linux 4.19.0-6-amd64 (SMP w/2 CPU cores)
Locale: LANG=en_GB.utf8, LC_CTYPE=en_GB.utf8 (charmap=UTF-8), 
LANGUAGE=en_GB.utf8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

Versions of packages perl depends on:
ii  dpkg   1.19.7
ii  libperl5.285.28.1-6
ii  perl-base  5.28.1-6
ii  perl-modules-5.28  5.28.1-6

Versions of packages perl recommends:
ii  netbase  5.6

Versions of packages perl suggests:
pn  libb-debug-perl 
pn  liblocale-codes-perl
pn  libterm-readline-gnu-perl | libterm-readline-perl-perl  
ii  make4.2.1-1.2
ii  perl-doc5.28.1-6

-- no debconf information