discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
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

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