Re: .br vertical spacing in html output

[Ingo Schwarze <schwarze@usta.de>]

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 <dl>
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