.br vertical spacing in html output

.br vertical spacing in html output

[Mark Harris]

With -Thtml, with or without -Ostyle=mandoc.css, a roff .br (line break)
directive is producing a large vertical space between lines.  This is
unexpected and does not occur with -Tascii/utf8.  Here is an example:

--- foo.1 ---
.TH foo 1
.SH OPTIONS
.IP -a
Enable a
.IP -b
Enable b
.IP -c
The following lines are expected to be single-spaced:

  Alpha
.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, 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?

 - Mark
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: .br vertical spacing in html output

[Ingo Schwarze]

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

Re: .br vertical spacing in html output

[Ingo Schwarze]

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.  This is
> unexpected and does not occur with -Tascii/utf8.  Here is an example:
[...]
> .br
>   Beta

The first commit in the context of the HTML syntax audit already
reduced the spacing a bit, see below.  There is still a spurious
blank line, though, and more is also needed to prevent bad nesting
in other situations.

Yours,
  Ingo


Log Message:
-----------
Render .br as <br/>, not as an empty <div>.
The element <br/> was already employed for many other purposes,
so there is nothing wrong with using it.
Also, it is safer because <br/> is permitted in phrasing content,
whereas <div> is only allowed in flow content.

This is the first part of the HTML syntax audit which i wanted 
to do for a long time.  Reminded by a loosely related bug report 
from Mark Harris <mark dot hsj at gmail dot com>.

Examples of where this caused HTML nesting syntax errors:
* in man(7) code between .nf and .fi
* in mdoc(7) code between .Bd -unfilled and .Ed
* in mdoc(7) code between .Ql Xo and .Xc
* in mdoc(7) code between .Rs and .Re

Modified Files:
--------------
    mandoc:
        roff_html.c

Revision Data
-------------
Index: roff_html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/roff_html.c,v
retrieving revision 1.12
retrieving revision 1.13
diff -Lroff_html.c -Lroff_html.c -u -p -r1.12 -r1.13
--- roff_html.c
+++ roff_html.c
@@ -58,11 +58,7 @@ roff_html_pre(struct html *h, const stru
 static void
 roff_html_pre_br(ROFF_HTML_ARGS)
 {
-	struct tag	*t;
-
-	t = print_otag(h, TAG_DIV, "");
-	print_text(h, "\\~");  /* So the div isn't empty. */
-	print_tagq(h, t);
+	print_otag(h, TAG_BR, "");
 }
 
 static void
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: .br vertical spacing in html output

[Ingo Schwarze]

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.  This is
> unexpected and does not occur with -Tascii/utf8.  Here is an example:
[...]
> .br
>   Beta

After some cleanup that was required first, i fixed this now with the
commit appended below.

Yours,
  Ingo


Log Message:
-----------
During validation, drop .br before a text line starting with a 
blank, rather than teaching each formatter individually to ignore
the .br in such situations.  That's simpler and also results in
better diagnostics.

Mark Harris <mark dot hsj at gmail dot com> reported 
that -T html got confused in particular.

Modified Files:
--------------
    mandoc:
        roff_validate.c

Revision Data
-------------
Index: roff_validate.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/roff_validate.c,v
retrieving revision 1.11
retrieving revision 1.12
diff -Lroff_validate.c -Lroff_validate.c -u -p -r1.11 -r1.12
--- roff_validate.c
+++ roff_validate.c
@@ -67,6 +67,14 @@ roff_valid_br(ROFF_VALID_ARGS)
 		mandoc_vmsg(MANDOCERR_ARG_SKIP, man->parse,
 		    n->line, n->pos, "br %s", n->child->string);
 
+	if (n->next != NULL && n->next->type == ROFFT_TEXT &&
+	    *n->next->string == ' ') {
+		mandoc_msg(MANDOCERR_PAR_SKIP, man->parse, n->line, n->pos,
+		    "br before text line with leading blank");
+		roff_node_delete(man, n);
+		return;
+	}
+
 	if ((np = n->prev) == NULL)
 		return;
 
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv