Re: [groff] 01/03: **/*.man: Eliminate blank lines in man pages.

[G. Branden Robinson]

[lots of context preserved here; sorry for the deep quoting]

At 2020-01-23T04:33:27+0100, Ingo Schwarze wrote:
> >> 1. In man/groff_char.7.man, the blank lines were inside tbl(1)
> >> code.  In that context, the meaning of a blank line is well
> >> defined: it means a table row without any cells, i.e. an empty
> >> table row.
> 
> > I can't find any support at all for your claim.  I've checked 1976,
> > 1977, 1979, and 1989 versions of the Bell Labs tbl whitepaper (not
> > the man page, the journal paper--or "Volume 2" article, if you
> > will).
> 
> You don't need any explicit statement for that, and i doubt that any
> historical document would state it explicitly because it is already
> clear from how tables work in the first place.
[...]
> So all implementations are careful to represent the empty cell as
> "\&", not as an empty line, which would indeed be dubious roff(7)
> output because we want an empty *table* line here, not an empty *text*
> line, which would be the meaning of an empty line in .nf mode (which
> is set by tbl(1) at this point).

I'm with you so far.

> >     Troff commands within tables
> > 
> >     --- An input line beginning with a '.' followed by anything but
> >     a number is assumed to be a command to _troff_ and is passed
> >     through unchanged, retaining its position in the table.  So, for
> >     example, space within a table may be produced by ".sp" commands
> >     in the data.
> 
> That is completely unrelated and doesn't call the meaning of empty
> lines into question.  Indeed, this *had* to be explained explictly in
> the paper because it is *not* obvious that roff commands can be nested
> inside tables at all, given that each input line represents a table
> row inside a table.  So that rule had to be explicitly waived for roff
> requests.
> 
> Besides, .sp is not the same as an empty table line.  The height of
> both can be different, and .sp can even take an argument.

Checking CSTR #54, we see:

        Blank text line.        -       B
                Causes a break and output of a blank line exactly like
                `sp 1`.
[... (actually earlier)]
        .sp _N_ -       _N_ = 1 B,*v*
                Space vertically in either direction.  If _N_ is
                negative, the motion is backward (upward) and is limited
                in distance to the top of the page.  Forward (downward)
                motion is truncated to the distance to the nearest trap.
                if the no-space mode is on, no spacing occurs (see `ns`,
                and `rs` below).

(with Markdown markup injected to indicate italics, bold, or font family
change to Courier).

So, ".sp" _is_ the same as ".sp 1" and _is_ the same as a blank line.

Unless we're in GNU land and someone has used `.blm` on us.

However, I acknowledge that our implementation does not quite seem to
manifest this.  When I tried out my change in September, I noticed that
replacing the blank lines with `.sp` changed where the breaks occurred
and I could not figure out why.  That is why I stopped contributing for
about three months.  I got stuck on this and then forgot about it and
then popped the stack having forgotten why I got stuck.

Probably the right thing to do would have been to have just pushed this
change in September anyway, counting on you and others to prompt
exploration and investigation.  Many eyes make bugs shallow and all
that.  :)

> > I cannot find any mention of blank or empty lines, and of course
> > .blm is a GNU extension so we're not likely to find it produced by
> > classical tbl.
> > 
> > Also, since tbl is a preprocessor, if it passes through empty lines
> > unchanged,
> 
> No, it doesn't.  Absolutely not.  Just look at the tbl(1) output.

I concede.  I should have looked at output, not just the literature.

> > they _have no semantics_ for tbl,
> 
> They do, see above.

Also conceded.  The whitepapers don't make it clear but the
implementations do.

> > and they should be discouraged
> 
> I don't see any reason why.
> Inside .TS, it is clear what a blank line means.

This, I cannot quite concede.  Fill mode is turned off with .nf, but the
meaning of a blank line is still subject to your environment/context.
For ms documents, it is supposed to be equivalent to a pargraph break.

Is a line

\&

"blank"?  If I recall correctly, this actually seems to depend on
compatibility mode.  :-/

> Even that is inaccurate.  You are right in fill mode.  There, they
> are bad style no matter which macro package you use.  But once you
> switch to no-fill mode, blank lines are again just fine - in no-fill
> mode, they mean a blank output line, of the same height as any other
> output line.

No.  This is context-dependent.

Traditionally, in groff's man(7), a blank line gives you a vertical
space of 0.4v in troff mode and 1v in nroff mode.  Another recent change
of mine actually altered groff's man(7) implementation to align with
your presumptions.  But I did it for esthetic reasons, not due to any
underlying conviction about what a blank line "means".

> You can use that inside .nf/.fi in raw roff(7), inside .EX/.EE in
> man(7), inside .Bd -unfilled/.Ed in mdoc(7), and so on.

As I think Ralph pointed out, you're mistaken with groff 1.22.4 and
earlier, when the output is typeset.

> > Bell Labs has been blessing .sp within tbl tables since 1976.
> 
> Yes.  I do admit that not supporting low-level roff requests inside
> tbl code is a serious weakness in mandoc.

Well, it's a limitation.  I don't know if it's a serious weakness--if
you can convince mdoc(7) document authors to confine themselves to a
subset of tbl when using it, it need not be a serious weakness.

> But that something has a well-defined meaning in roff in general
> does not imply that it is a good idea to use it in manual pages.

I think about it in a way that is similar but not quite identical.

Every roff document author can expect to have tbl(1) at their disposal;
however, what they can get away with their _input_ to tbl(1) depends on
the macro package they're using.

groff_me(7), for instance, says that most raw roff requests are "unsafe"
to use.

Ironically for the purposes of our discussion, `.sp` is one of the few
it allows.  But on the bright side, mandoc(1) has no need to parse me(7)
documents.

> Manual pages should be written in a way that is as semantic as
> possible,

And here's where you get to note with satisfaction that man(7) allows
relatively little, semantically.  :P

> and they should contain as little physical formatting as possible.

Agreed.  You and I have hammered on the "Portability" section of
groff_man(7) to try and restrain man(7) authors from running wild with
escapes and requests.  In my view, the fewer such things a man(7)
document has, the more it approaches the Platonic ideal man(7) page.

But, as I am fundamentally an anti-Platonist, I permit myself to know
sin and use (particuarly) escapes when I must.  Just not font escapes,
which are a contemptible blight upon every man page where they appear.

Except maybe in tbl(1) input, damn it.

:-|

> So *in a manual page*, it is better to use only tbl syntax inside
> a tbl and refrain from using low-level physical formatting there.

I am inclined to regard a blank input line _as_ low-level physical
formatting because of its context-dependence, even with the context
limited to no-fill mode.  That information is not completely
dispositive.  We have .cp and .blm to worry about.  "We" meaning
developers of groff, that is.

> >>    So i would prefer if this part of the commit could be reverted.
> 
> > I find it pretty difficult to accept your assertion that my change
> > is wrong,
> 
> I don't say it is wrong.  It is valid low-level roff(7).
> 
> What i say it is that is bad style in a manual page, whereas a blank
> line inside a tbl is both valid syntax, too, but also perfectly fine
> style even in a manual page.
> 
> > but since I want to overhaul this page anyway, I won't rule out
> > changing it in some way that doesn't cause mandoc grief.
> 
> That isn't even the main reason (although in a certain sense,
> the reason why i consider it bad style in a manual page also
> causes the reasons that make it so hard to support in mandoc).

Well, I hope we'll figure something out.  As you have probably figured
out by now, I like neither blank lines _nor_ .sp requests inside tbl
input in man pages.  I fear they will encourage man(7) writers to use
them _outside_ of tbl input.  I regard .sp as a lesser compromise, but
I'd prefer to solve this problem with some alternative to both.

I don't regard myself as a tbl expert which is why I've been reading the
whitepaper carefully.  But it seems I should pay more attention to tbl
_output_, which I haven't done much of to date becuse, well, it often
looks gross to me, like an unmaintainable write-only mess.

Regards,
Branden

signature.asc
Description: PGP signature