Re: discrepancy between groff and mandoc for html rendering of wg-quick(8)

[Ingo Schwarze <schwarze@usta.de>]

Hello Jason,

Jason A. Donenfeld wrote on Tue, Feb 11, 2020 at 11:59:21PM +0100:

> Compare:
> 
> [mandoc] https://manpages.debian.org/testing/wireguard-tools/wg-quick.8.en.html
> [groff] https://git.zx2c4.com/wireguard-tools/about/src/man/wg-quick.8
> 
> Look at the "EXAMPLES" section. Notice weird line break issues with mandoc.

Closer inspection revealed that it is actually fine that the roff
validation module in mandoc (roff_validate.c) removes the redundant
.br requests, but there was a bug in the man(7) HTML formatter
(man_html.c), forgetting to actually break the line.

The commit appended below fixes the bug.

Thank you for reporting!

> Is this a man page source bug or a mandoc bug?

Foremost, it was a mandoc bug.

Besides, while the following man(7) code in wg-quick(8) isn't incorrect,
it isn't good style either:

 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----
The following might be used for connecting as a client to a VPN gateway
for tunneling all traffic:

    [Interface]
.br
    \fBAddress = 10.200.100.8/24\fP
.br
    \fBDNS = 10.200.100.1\fP
 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----

Blank lines are bad style in manual pages outside no-fill mode.
Forcing line breaks with leading whitespace is also bad style in
manual pages.  The .br requests are redundant and look quite ugly.
Using font escapes instead of font macros is bad style in manual
pages.  So it would be better to write this:

 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----
The following might be used for connecting as a client to a VPN gateway
for tunneling all traffic:
.PP \" optional, can be left out
.RS 4n \" the 4n is optional, give no arg to get the default indentation
.nf
[Interface]
.B Address = 10.200.100.8/24
.B BDNS = 10.200.100.1
[...]
.fi
.RE
.PP
[...]
 ----- 8< ----- schnipp ----- >8 ----- 8< ----- schnapp ----- >8 -----

(Bold face isn't really needed in an example either, but oh well...)

Anyway, bad style in a manual page is no excuse
for mandoc misformatting it.

Yours,
  Ingo


Log Message:
-----------
In roff, a space character at the beginning of an input line requires 
starting a new output line, and merely starting a new line of HTML 
code isn't sufficient to achieve that.  Solve this in the same way
as mdoc_html.c already does it, by printing a <br/> element.
Fixing a bug reported by Jason A. Donenfeld <Jason at zx2c4 dot com>
in the wg-quick(8) manual page on manpages.debian.org.

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.174
retrieving revision 1.175
diff -Lman_html.c -Lman_html.c -u -p -r1.174 -r1.175
--- man_html.c
+++ man_html.c
@@ -1,7 +1,7 @@
 /*	$Id$ */
 /*
  * Copyright (c) 2008-2012, 2014 Kristaps Dzonsons <kristaps@bsd.lv>
- * Copyright (c) 2013-2015, 2017-2019 Ingo Schwarze <schwarze@openbsd.org>
+ * Copyright (c) 2013-2015, 2017-2020 Ingo Schwarze <schwarze@openbsd.org>
  *
  * Permission to use, copy, modify, and distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -178,7 +178,7 @@ print_man_node(MAN_ARGS)
 		}
 		if (*n->string == ' ' && n->flags & NODE_LINE &&
 		    (h->flags & HTML_NONEWLINE) == 0)
-			print_endline(h);
+			print_otag(h, TAG_BR, "");
 		else if (n->flags & NODE_DELIMC)
 			h->flags |= HTML_NOSPACE;
 		t = h->tag;
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv