Re: mandoc & perl documentation

[Ingo Schwarze <schwarze@usta.de>]

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!

>> or missing all different font families.

I'm still not sure what you are alluding to here - can you be more
specific?

>> 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.

>> 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.

> 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.

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);
+	}
 }
 
 /*
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv