[groff] 32/53: doc/meref.me: Fix errors in tbl(1) usage material.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 132bcede8a456106606423ecbf3b5bc2610b5abc
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Dec 13 16:08:17 2021 +1100

    doc/meref.me: Fix errors in tbl(1) usage material.
    
    * me(7) does nothing special to try to keep tbl(1) tables on one page
      (at least, neither Heirloom Doctools me(7) nor groff me(7) do).  By
      default, the page breaks before the first table row that won't fit.
    * Document the vertical space that brackets tables.
    * Move discussion of floating keep usage from `TE` to `TS` synopsis.
    * De-document discussion of `sp`'s influence on table breaking; again,
      nothing special seems to be happening here.  If you put `sp` between
      rows of table data, the page can break there; if you put `sp` inside a
      text block, it can't, because a row with a text block is always set
      unbroken (that is why a text block cannot be taller than the printable
      area of the page).
    * Cross-reference the groff tbl(1) man page instead of Lesk 1979 since
      the former is readily available to groff users.
---
 doc/meref.me | 73 ++++++++++++++++++++++++++++--------------------------------
 1 file changed, 34 insertions(+), 39 deletions(-)

diff --git a/doc/meref.me b/doc/meref.me
index 26a79d7..de54bf4 100644
--- a/doc/meref.me
+++ b/doc/meref.me
@@ -1450,53 +1450,48 @@ above and below it.
 .b .TS
 .i h
 .DE
-Table start.
-Tables are single spaced
-and kept on one page
-if possible.
+Begin (start)
+.i \%@g@tbl (1)
+table.
+Tables are single-spaced
+and preceded and followed by
+.NR (bs
+of space.
 If you have a large table
-which will not fit on one page,
-use
-.i h
-=
+that will not fit on one page
+and want to repeat a table heading
+on each subsequent page,
+specify
 .b H
-and follow the header part
-(to be printed on every page of the table)
-with a
-.b .TH .
-See
-.i "Tbl \- A Program to Format Tables"
-by M. E. Lesk.
-.TL
+for
+.i h
+and call
 .b .TH
-.DE
-With
-.b ".TS H" ,
-ends the header portion of the table.
-.TL
-.b .TE
-.DE
-Table end.
-This table does not float;
-in fact,
-it is not even guaranteed to stay on one page
-if you use requests such as
-.b .sp
-intermixed with the text
-of the table.
-If you want it to float
-(or if you use requests
-inside the table),
-surround the entire table
-(including the
+within the table data after the heading rows.
+If you want a table to float,
+surround the
 .b .TS
 and
 .b .TE
-macros)
-with the macros
+calls with
 .b .(z
 and
-.b .)z .
+.b .)z
+calls.
+.TL
+.b .TH
+.DE
+With \(lq\c
+.b ".TS H" \(rq,
+end the
+.i \%@g@tbl
+table header.
+.TL
+.b .TE
+.DE
+End
+.i \%@g@tbl
+table.
 .TL
 .b .PS
 .i h