Re: keeping makewhatis happy wrt/ pod (Was: Re: UPD: devel/p5-Moose)
On Mon, Mar 23, 2009 at 09:06:07AM -0600, Theo de Raadt wrote: > > On Sun, Mar 22, 2009 at 12:47:28AM -0600, Theo de Raadt wrote: > > > Another way to solve this is a rewrite of pod2man .. which will then > > > generate mandoc instead. > > > > > > That also benefits the other manual page project. > > > > hum... so let's trade 10 lines of makewhatis to a complete new back-end > > to pod2man ? > > > > I'm not saying this would not be a good idea, but: > > - we will always need to parse some nroff stuff. Converting all manpages in > > all 3rd party ports is not realistic. > > Huh? > > Converting all pods to mandoc, and getting the prettiness for fre, isn't > worth it? "For free" ? pod2man is 1700 lines. Figuring out what to rewrite to get mandoc instead of old nroff isn't exactly "for free"... Yes, it's worthwhile. No I currently don't have the time to do it. Small incremental changes to makewhatis that take 1 or 2 hours, on the other hand, are doable...
Re: keeping makewhatis happy wrt/ pod (Was: Re: UPD: devel/p5-Moose)
> On Sun, Mar 22, 2009 at 12:47:28AM -0600, Theo de Raadt wrote: > > Another way to solve this is a rewrite of pod2man .. which will then > > generate mandoc instead. > > > > That also benefits the other manual page project. > > hum... so let's trade 10 lines of makewhatis to a complete new back-end > to pod2man ? > > I'm not saying this would not be a good idea, but: > - we will always need to parse some nroff stuff. Converting all manpages in > all 3rd party ports is not realistic. Huh? Converting all pods to mandoc, and getting the prettiness for fre, isn't worth it? It has no downside.
Re: keeping makewhatis happy wrt/ pod (Was: Re: UPD: devel/p5-Moose)
On Sun, Mar 22, 2009 at 12:47:28AM -0600, Theo de Raadt wrote: > Another way to solve this is a rewrite of pod2man .. which will then > generate mandoc instead. > > That also benefits the other manual page project. hum... so let's trade 10 lines of makewhatis to a complete new back-end to pod2man ? I'm not saying this would not be a good idea, but: - we will always need to parse some nroff stuff. Converting all manpages in all 3rd party ports is not realistic. - I'll just put this on my list of things to do when I have time. ;-)
Re: keeping makewhatis happy wrt/ pod (Was: Re: UPD: devel/p5-Moose)
Another way to solve this is a rewrite of pod2man .. which will then
generate mandoc instead.
That also benefits the other manual page project.
> Actually, this is more complex than it looks, because recent pod converters
> make a lot of use of
> .ie n
> .el
> constructions, and that throws makewhatis completely off-base, especially
> wrt Moose.
>
> I have some quick hacks which allow it to proceed, and I'm still wondering
> whether I should actually teach makewhatis how to parse .ie constructs.
>
> the
> .ie n
> .el
> lines are rather simple, I'm ways more worried about multiline tests, like
> .ie n \{
>
>
> .br \}
> .el \{
>
> .br \}
>
> which promises to be a nightmare...
>
Re: keeping makewhatis happy wrt/ pod (Was: Re: UPD: devel/p5-Moose)
Actually, this is more complex than it looks, because recent pod converters
make a lot of use of
.ie n
.el
constructions, and that throws makewhatis completely off-base, especially
wrt Moose.
I have some quick hacks which allow it to proceed, and I'm still wondering
whether I should actually teach makewhatis how to parse .ie constructs.
the
.ie n
.el
lines are rather simple, I'm ways more worried about multiline tests, like
.ie n \{
.br \}
.el \{
.br \}
which promises to be a nightmare...
keeping makewhatis happy wrt/ pod (Was: Re: UPD: devel/p5-Moose)
On Mon, Feb 09, 2009 at 04:23:40PM -0800, James Wright wrote:
> Simon Bertrang wrote:
>> On Mon, Feb 09, 2009 at 03:41:40AM -0800, James Wright wrote:
>>
>>> This updates Moose to 068. This update depends on the previously posted
>>> p5-Class-MOP update, I also added a bunch of regress-depends, though some
>>> tests are still skipped due to missing dependencies (that are not yet in
>>> the tree): Params::Coerce, DBM::Deep and Declare::Constraints::Simple.
>>>
>>> This release adds a huge swath of actually useful documentation (thanks
>>> to a Perl Foundation grant), check out Moose::Manual (supersedes
>>> Moose::Intro).
>>>
>>
>>
>> Code-wise i see no issues... but when installing i got the following:
>> ...
>> ===> Installing p5-Moose-0.68 from /usr/ports/packages/amd64/all/
>> p5-Moose-0.68: complete
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>> /usr/local/man/man3p/Moose::Manual::Concepts.3p: can't expand Aq
>>
>> I've identified the single quotes (') to be involved somehow but have no
>> idea yet why. Anyone who immediately knows what's going on here?
>> Otherwise i'll try to find out later today.
>>
>> Regards,
>> Simon
>>
>>
> This is in OpenBSD::Makewhatis::Unformated, in add_unformated_subject,
> no mention of Aq (bsd.port.mk runs makewhatis in -p mode).
>
> The Aq comes from Pod::Man's standard preamble
>
> .\" Escape single quotes in literal strings from groff's Unicode transform.
> .ie \n(.g .ds Aq \(aq
> .el .ds Aq '
>
> f.e.:
> \& use Moose;
> \& # now it\*(Aqs a Moose class!
>
> It seems to parse fine with groff.
>
Well spotted again, thanks!
A bit searching brought me to a debian bug report that seems to describe
the issue in detail:
http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=457839
With that it was easy to track it further down to
src/gnu/usr.bin/perl/lib/Pod/Man.pm which as change a lot with the
update of perl to 5.10.
Not being a *roff expert i'm proposing the following silly approach to
prevent Pod::Man to replace single quotes. This change keeps makewhatis
silent and the resulting manpage seem still fine to me. Maybe someone
with more clue in that area can enlighten us with a better fix.
Perhaps it would be better to replace the quotes in
OpenBSD::Makewhatis::Unformated, comments anyone?
Regards,
Simon
Index: lib/Pod/Man.pm
===
RCS file: /cvs/src/gnu/usr.bin/perl/lib/Pod/Man.pm,v
retrieving revision 1.11
diff -u -p -r1.11 Man.pm
--- lib/Pod/Man.pm 29 Sep 2008 17:36:13 - 1.11
+++ lib/Pod/Man.pm 10 Feb 2009 09:22:38 -
@@ -368,7 +368,8 @@ sub format_text {
# Ensure that *roff doesn't convert literal quotes to UTF-8 single quotes,
# but don't mess up our accept escapes.
if ($literal) {
-$text =~ s/(?
