From: Ingo Schwarze <schwarze@usta.de> To: "Jason A. Donenfeld" <Jason@zx2c4.com> Cc: discuss@mandoc.bsd.lv Subject: Re: discrepancy between groff and mandoc for html rendering of wg-quick(8) Date: Wed, 12 Feb 2020 22:44:36 +0100 [thread overview] Message-ID: <20200212214436.GF20240@athene.usta.de> (raw) In-Reply-To: <CAHmME9oJVrtMXCKvXBQZkUTbcA1sK8_J+GziwO97sVP=hsdNnA@mail.gmail.com> 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
next prev parent reply other threads:[~2020-02-12 21:44 UTC|newest] Thread overview: 29+ messages / expand[flat|nested] mbox.gz Atom feed top [not found] <CAHmME9rVyL+QUhks0J8xOpykb6V+5wKadgowc8bndP=Shi5gyA@mail.gmail.com> 2020-02-11 22:59 ` Jason A. Donenfeld 2020-02-12 7:02 ` Jan Stary 2020-02-12 15:06 ` Ingo Schwarze 2020-02-12 15:14 ` Jan Stary 2020-02-12 15:25 ` Ingo Schwarze 2020-02-12 21:44 ` Ingo Schwarze [this message] 2020-02-13 4:29 ` Stephen Gregoratto 2020-02-13 4:49 ` [PATCH] Fix formatting in wg-quick(8) Stephen Gregoratto 2020-02-13 8:57 ` Raf Czlonka 2020-02-13 16:31 ` Jason A. Donenfeld 2020-02-13 18:34 ` Ingo Schwarze 2020-02-13 17:57 ` Ingo Schwarze 2020-02-13 18:00 ` Jason A. Donenfeld 2020-02-13 19:34 ` Ingo Schwarze 2020-02-13 19:55 ` Jason A. Donenfeld 2020-02-13 22:28 ` Ingo Schwarze 2020-02-13 22:38 ` Jason A. Donenfeld 2020-02-13 22:44 ` Jan Stary 2020-02-13 23:21 ` Steffen Nurpmeso 2020-02-14 4:00 ` Anthony J. Bentley 2020-02-14 11:08 ` Jason A. Donenfeld 2020-02-14 15:05 ` Ingo Schwarze 2020-02-14 22:36 ` Anthony J. Bentley 2020-02-14 18:20 ` Ingo Schwarze 2020-02-15 0:45 ` [PATCH v2] Rewrite wg-quick.8 in mdoc Stephen Gregoratto 2020-02-15 19:53 ` Jason A. Donenfeld 2020-02-16 10:32 ` Stephen Gregoratto 2020-02-16 15:52 ` Ingo Schwarze 2020-02-13 16:34 ` discrepancy between groff and mandoc for html rendering of wg-quick(8) Jason A. Donenfeld
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20200212214436.GF20240@athene.usta.de \ --to=schwarze@usta.de \ --cc=Jason@zx2c4.com \ --cc=discuss@mandoc.bsd.lv \ --subject='Re: discrepancy between groff and mandoc for html rendering of wg-quick(8)' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).