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 mandoc.bsd.lv (OpenSMTPD) with ESMTP id f8006bb7 for ; Wed, 12 Feb 2020 16:44:40 -0500 (EST) Received: from hekate.asta.kit.edu ([141.3.145.153] 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 1j1zoD-0003Kp-Av; Wed, 12 Feb 2020 22:44:39 +0100 Received: from donnerwolke.asta.kit.edu ([141.3.145.61] helo=donnerwolke.usta.de) by hekate.usta.de with esmtp (Exim 4.92.2) (envelope-from ) id 1j1zoC-0001Hy-6L; Wed, 12 Feb 2020 22:44:36 +0100 Received: from athene.asta.kit.edu ([141.3.145.60] helo=athene.usta.de) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1j1zoC-0003if-21; Wed, 12 Feb 2020 22:44:36 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id a08f8614; Wed, 12 Feb 2020 22:44:36 +0100 (CET) Date: Wed, 12 Feb 2020 22:44:36 +0100 From: Ingo Schwarze To: "Jason A. Donenfeld" Cc: discuss@mandoc.bsd.lv Subject: Re: discrepancy between groff and mandoc for html rendering of wg-quick(8) Message-ID: <20200212214436.GF20240@athene.usta.de> References: 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: User-Agent: Mutt/1.12.2 (2019-09-21) 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
element. Fixing a bug reported by Jason A. Donenfeld 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 - * Copyright (c) 2013-2015, 2017-2019 Ingo Schwarze + * Copyright (c) 2013-2015, 2017-2020 Ingo Schwarze * * 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