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

[Ingo Schwarze]

Hello Branden,

G. Branden Robinson wrote on Thu, Jan 23, 2020 at 01:12:34PM +1100:
> At 2020-01-16T16:27:42+0100, Ingo Schwarze wrote:

>> These are three very different cases.
>> 
>> 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.

A table consists of three sections:  (optionally) options, a mandatory
layout, and some data lines.  Disregarding T{ for the moment, each
input line is one table line.  The text up to the first column
separator character, if any - \t by default or the one confugred
with the tab() option -, is the text in the first table cell.  So
an empty input line is table line containing one empty table cell.

Tbl implementations actually work that way.  Given the table

  .TS
  L.
  line1
  
  line3
  .TE

GNU tbl produces:

  [...]
  \&\h'|\n[3cl0]u'line1
  [...]
  \&                     \" this is the empty cell in line 2
  [...]
  \&\h'|\n[3cl0]u'line3
  [...]

with about 20 lines of formatting around each table line.

Heirloom tbl produces:

  [...]
  \&\h'|\n(40u'^Bline1^C^B
  [...]
  \&\h'|\n(40u'^B^C^B       \" this is the empty cell in line 2
  [...]
  \&\h'|\n(40u'^Bline3^C^B
  [...]

with four lines of formatting around each table line.

Plan 9 tbl produces almost the same as Heirloom, except with
only three lines of formatting commands in between.

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

> All of them say the same thing:
> 
>       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.

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

> they _have no semantics_ for tbl,

They do, see above.

> and they should be discouraged

I don't see any reason why.
Inside .TS, it is clear what a blank line means.

> as and where they are in other roff documents (in other words, they
> shouldn't be used in raw roff documents and otherwise it's
> up to a macro package to support them; e.g., ms(7) does, man(7)
> doesn't).

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.

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.

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

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.
Manual pages should be written in a way that is as semantic as
possible, and they should contain as little physical formatting
as possible.

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.

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

Yours,
  Ingo

> The blank lines were there as a form of sub-sectioning within the (often
> long) tables, so there are probably other ways to skin this cat.
> 
> I'll reply separate regarding man pages and examples, particularly since
> your objects there are not as strong.