From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 603fdea8 for ; Tue, 23 Oct 2018 12:45:48 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1gF0kU-00081L-BM; Tue, 23 Oct 2018 19:45:47 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1gF0kU-00032S-1d; Tue, 23 Oct 2018 19:45:46 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1gF0kW-0006P9-K2; Tue, 23 Oct 2018 19:45:48 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 870a9446; Tue, 23 Oct 2018 19:45:45 +0200 (CEST) Date: Tue, 23 Oct 2018 19:45:45 +0200 From: Ingo Schwarze To: pali.rohar@gmail.com Cc: discuss@mandoc.bsd.lv Subject: Re: mandoc & perl documentation Message-ID: <20181023174545.GD58247@athene.usta.de> References: <20180913151226.oaon3nvlvgcqioau@pali> <20181011075247.2jo4of7bkpvhkekm@pali> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20181011075247.2jo4of7bkpvhkekm@pali> User-Agent: Mutt/1.8.0 (2017-02-23) 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 
.
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 
 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 = 
, print even empty lines. */
+		h->col++;
 		print_endline(h);
+	}
 }
 
 /*
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv