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