Re: mandoc & perl documentation

["Pali Rohár" <pali.rohar@gmail.com>]

On Tuesday 23 October 2018 19:45:45 Ingo Schwarze wrote:
> Hi Pali,
> 
> Pali Rohar wrote on Thu, Oct 11, 2018 at 09:52:47AM +0200:
> > On Thursday 13 September 2018 17:12:26 Pali Rohar wrote:
> 
> >> In perl world is documentation for perl modules or perl scripts writing
> >> in the POD format. Build process for perl scripts/modules then convert
> >> POD documentation into manpages and install it into standard system
> >> location.
> >> 
> >> I looked at Debian manpages which uses mandoc for converting man pages
> >> to HTML and basically documentation for perl modules is not good.
> >> 
> >> For example this is HTMLized manpage for Email::Address::XS perl module:
> >> https://manpages.debian.org/Email::Address::XS
> >> 
> >> There is also converting tool which formats POD documentation directly
> >> into HTML output. And for Email::Address::XS module is looks like:
> >> https://metacpan.org/pod/Email::Address::XS
> >> 
> >> So, I would like to ask, how can be HTML output generated from perl
> >> manpages improved (process: POD --> mandoc --> HTML), so documentation
> >> would be more close to the native HTML output (process: POD --> HTML)?
> >> 
> >> I understand that something like syntax highlighting is not possible,
> >> but if you look at differences, in HTML output from mandoc are broken
> >> vertical spaces (some are totally missing)
> 
> At first, i got confused because your report isn't really related
> to the POD format at all (but your mail misled me to think so),
> because your English is slightly hard to understand, because the
> actual bug you were trying to report was well hidden near the end
> of the text, because you only vaguely alluded to what was wrong with
> the output without being specific, and because i couldn't readily
> access the actual source document you were trying to format - and
> then i forgot about the report.  Sorry for the delay!

Hi Ingo!

Sorry for that. English is not my native language and I guessed that
problem could be in Pod::Man...

> >> or missing all different font families.
> 
> I'm still not sure what you are alluding to here - can you be more
> specific?

Different font families. E.g. directive C<...> in POD switches font
family to typewriter/monospaced, I<...> to italic, B<...> to bold...

Looks like that bold and italic families are working.

But typewriter/monospaced font is somehow ignored or unsupported in html
output from mandoc.

If you look at the output for Email::Address::XS, then whole SYNOPSIS
should be written in typewriter/monospaced font. Or e.g. section
"Deprecated Functions and Variables" has also some keywords in
monospaced font and remaining parts are in normal/roman font. Compare it
with html output on metacpan to see how it should look like.

> >> If problem is in POD --> manpage converter (Pod::Man module), I can
> >> look at it.
> 
> In general, that is not very likely.  Pod2man is very stable software
> that rarely changes nowadays, and i hardly ever found a bug in it -
> well, maybe one in a decade or so.
> 
> Besides, even if pod2man(1) would contain a bug, mandoc(1) should
> possibly try to cope because pod2man(1) is so stable and widespread
> that whatever it does can almost be considered a feature.

Ok. But seems that Pod::Man is still under development and fixes bugs...
https://metacpan.org/changes/distribution/podlators

> >> But at the first I would need to know what mandoc is able to
> >> process and what not.
> 
> Most of that is documented in the man(7) and roff(7) manual pages
> included in the mandoc distribution.  To explain more details, i
> would need a more specific question - which feature is it that
> you feel unsure whether mandoc implements it or not?
> 
> Besides, (new) manual pages should really only use a tiny fraction
> of the features implemented in mandoc.  Most of the functionality
> is provided purely fo backward compatibility.
> 
> > Just to note, raw manpage (generated by Pod::Man) is available there:
> > https://manpages.debian.org/Email::Address::XS.3pm.en.gz
> 
> Oh yes, that link is helpful, and thanks for the reminder.

Btw, link to raw manpage is also in the upper right corner of HTMLized
Debian page.

> > And viewing it on terminal does not case problems with vertical spaces
> > like in HTML output.
> > 
> > So it is problem in mandoc HTML generator?
> 
> Yes, in the mandoc -man -Thtml formatter; i fixed it with the
> commit appended below.

Great, thank you!

> In general, finding problems in -man -Thtml output is still more
> likely than in -mdoc -Thtml because the man(7) language is much
> more complicated than mdoc(7), much less suited to translation to
> HTML because it is purely presentational, and much less used in
> practice, so mostly untested.
> 
> Thanks for the report and sorry again for the delay,
>   Ingo
> 
> 
> Log Message:
> -----------
> Input lines that are not blank but generate no output,
> for example lines containing nothing but "\&", are significant
> in no-fill mode and can be represented by blank lines inside <pre>.
> Fixing a bug that Pali dot Rohar at gmail dot com found
> in pod2man(1) output, for example Email::Address::XS(3p).
> 
> While here, inside no-fill mode, there is no need to encode
> totally blank input lines by emulating .PP - just let them
> through as we are inside <pre> anyway.
> 
> Modified Files:
> --------------
>     mandoc:
>         man_html.c
> 
> Revision Data
> -------------
> Index: man_html.c
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/man_html.c,v
> retrieving revision 1.156
> retrieving revision 1.157
> diff -Lman_html.c -Lman_html.c -u -p -r1.156 -r1.157
> --- man_html.c
> +++ man_html.c
> @@ -264,7 +264,7 @@ print_man_node(MAN_ARGS)
>  		    n->flags & NODE_LINE && *n->string == ' ' &&
>  		    (h->flags & HTML_NONEWLINE) == 0)
>  			print_otag(h, TAG_BR, "");
> -		if (*n->string != '\0')
> +		if (want_fillmode == MAN_nf || *n->string != '\0')
>  			break;
>  		print_paragraph(h);
>  		return;
> @@ -338,8 +338,11 @@ print_man_node(MAN_ARGS)
>  	print_stagq(h, t);
>  
>  	if (fillmode(h, 0) == MAN_nf &&
> -	    n->next != NULL && n->next->flags & NODE_LINE)
> +	    n->next != NULL && n->next->flags & NODE_LINE) {
> +		/* In .nf = <pre>, print even empty lines. */
> +		h->col++;
>  		print_endline(h);
> +	}
>  }
>  
>  /*

-- 
Pali Rohár
pali.rohar@gmail.com
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv