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 6b488c50 for ; Sun, 2 Dec 2018 12:21:37 -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 1gTVR1-0000kR-1S; Sun, 02 Dec 2018 18:21:36 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1gTVR0-0000vY-8V; Sun, 02 Dec 2018 18:21:34 +0100 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1gTVR0-0002wT-3d; Sun, 02 Dec 2018 18:21:34 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id edc44440; Sun, 2 Dec 2018 18:21:34 +0100 (CET) Date: Sun, 2 Dec 2018 18:21:34 +0100 From: Ingo Schwarze To: Mark Harris Cc: discuss@mandoc.bsd.lv Subject: Re: .br vertical spacing in html output Message-ID: <20181202172134.GD11586@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.8.0 (2017-02-23) Hi Mark, Mark Harris wrote on Sat, Dec 01, 2018 at 01:31:05PM -0800: > With -Thtml, with or without -Ostyle=mandoc.css, a roff .br (line break) > directive is producing a large vertical space between lines. It is not the .br causing the vertical space, but the leading whitespace on your Greek lines. > This is > unexpected and does not occur with -Tascii/utf8. Here is an example: That example is terrible style. Some hints inline. > --- foo.1 --- > .TH foo 1 > .SH OPTIONS Never use the non-standard section .SH OPTIONS, use the standard section .SH DESCRIPTION instead. > .IP -a > Enable a > .IP -b > Enable b > .IP -c > The following lines are expected to be single-spaced: > Never, ever insert a blank line into any manual page file. If you want a paragraph break, use ".PP" in man(7) or ".Pp" in mdoc(7). If you want visual structuring of the source code without changing the content and formatting, use an empty macro line, i.e. a line containing nothing but a single dot (though such structuring is usually not done in BSD manuals because it merely makes the source code longer with no formatting benefit). > Alpha What is the point of the leading whitespace here? In manual pages, that is an obscure way to request a physical line break that i would strongly discourage because the behaviour is not very reliable (as you have just seen) and even more so because it is extremely confusing for human readers. If you want a paragraph where no automatic line-breaking is done but the existing line breaks are preserved, use an ".nf" ... ".fi" block in man(7) or a ".Bd -unfilled" (or ".Bd -literal" if that's what you want) ... ".Ed" block in mdoc(7). If you want a single physical line break in the middle of otherwise normally filled text, you can use the ".br" request. It occasionally makes sense in man(7) code, but i'd not recommend it in mdoc(7), it is almost never needed and breaks the semantic paradigm. Using *both* ".br" and leading whitespace together certainly makes no sense whatsoever. If you want indentation, use ".IP" or ".RS" in man(7) or ".Bd -offset" in mdoc(7). > .br > Beta > .br > Gamma > .br > Delta > > The lines are single-spaced as expected with -Tascii, but with -Thtml > there is a large amount of space between the lines. > .IP -d > Enable d > ------ > > The missing vertical space between .IP paragraphs can be ameliorated by > removing the dl styling from the stylesheet, Don't do that, it will totally break formatting of tagged lists in most other manual pages. The styling of tagged lists is by far the hardest part of the stylesheet. It is not perfect yet, but what there is now is the best compromise we could come up with so far. There are many things one can freely tweak in mandoc.css, but
is the last thing you should touch. I'm not aware of any way to get vertical spacing between tagged list items right now that doesn't break something else that is worse. I have talked to many people about the problem for years and at least three promised to solve the issue, but none managed to. In a nutshell, the problem to solve is that the tag needs to be left of the body when the tag is short, or above the body when the tag is long (again, without breaking anything else). > but I don't see an easy way to address the extra .br spacing with the > stylesheet. Is this something that can be addressed in mandoc? I agree that the vertical spacing of .br + leading whitespace is incorrect. It is related to the question of flow content vs. phrasing content in HTML. Some improvements were reached in the past to avoid HTML element nesting errors in mandoc output, but some parts are still a mess, and what you report can hardly be fixed without sorting that out. So i have just started an audit of mandoc with respect to the emission of flow content and phrasing content and whether both are correctly nested; i wanted to do that for some time anyway. In that context, your issue will get fixed as a side effect. I'll tell you when it's done. Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv