[groff] 05/16: doc/meref.me.in: Update and revise.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit e18faa41df213256507ae0b2233148653ee53348
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Sep 5 07:24:36 2023 -0500

    doc/meref.me.in: Update and revise.
    
    * Document that the `np` and `bu` macros use non-configurable
      indentation amounts.
    * Document refer(1) preprocessor tokens `.[` and `.]`.
    * Use the *roff term "titles" after it has been introduced.
    * Migrate terminology: "typesetting [output] devices" -> "typesetters".
    * Migrate terminology: "terminal [output] devices" -> "terminals".
    * Sneak away from explicit mention of ISO 6429 escape sequences in
      anticipation of Lennart Jablonka's terminfo work on grotty.
    * Clarify use of `TH` with tbl(1).
    * Add "flyback" term to `PF`, `IF`, `GF` descriptions.
    * Use `#` instead of `|` in example of `++` macro usage; the former sets
      better in Times.
    * Suggest use of `pdfswitchtopage` macro when discussing table of
      contents.
    * Describe `ep` macro more tersely.  (I needed the space.)
    * Tighten descriptions of super- and subscripting strings.
---
 doc/meref.me.in | 62 ++++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 39 insertions(+), 23 deletions(-)

diff --git a/doc/meref.me.in b/doc/meref.me.in
index bc5eb626e..a049d6256 100644
--- a/doc/meref.me.in
+++ b/doc/meref.me.in
@@ -329,6 +329,7 @@ and reset to 1 by
 .b .sh ,
 and
 .b .sx .
+The indentation amount is not configurable.
 .TL
 .b .bu
 .DE
@@ -340,6 +341,7 @@ between adjacent bulleted paragraphs,
 .\" TODO: Move the following application note to meintro.me.in or some
 .\" future non-introductory me(7) usage manual.
 enabling the construction of compact itemized lists.
+The indentation amount is not configurable.
 .sh 1 "Sectioning"
 .pp
 Numbered sections
@@ -600,14 +602,14 @@ to the (nominal) bottom of the text.
 \*(ME uses \*T's environment 0 for body text,
 1 for keeps
 (see below),
-and 2 for headers and footers.
+and 2 for titles.
 The default line length is two inches less than the page width
 (e.g.,
 6.5i on U.S.\& letter paper).
 The default page offset
 (left margin)
 is determined by the output device;
-it is typically 1.0i on typesetting devices and 0 on terminals.
+it is typically 1.0i on typesetters and 0 on terminals.
 .TL
 .b .xl
 .i \(+-n
@@ -1247,7 +1249,7 @@ It has no effect in \*N mode.
 .DE
 Underline
 .i W.
-On typesetting output devices,
+On typesetters,
 this is true underlining,
 in contrast to the
 .b .ul
@@ -1255,7 +1257,7 @@ request,
 which changes to the
 .q "underline font"
 (usually italics in \*G).
-On terminal output devices,
+On terminals,
 .i W
 is surrounded by underscores.
 This argument should not be subject to adjustment,
@@ -1271,12 +1273,11 @@ is reliable only when filling is disabled.
 Set
 .i W
 in a box.
-On typesetting output devices,
+On typesetters,
 .i W
 is surrounded by rules (lines).
-On terminal output devices,
-.i W
-is simulated with ISO\~6429 color escape sequences
+On terminals,
+boxing is simulated with device escape sequences
 or surrounded by vertical bars.
 It is not marked specially on
 .i groff 's
@@ -1289,6 +1290,18 @@ or breaking;
 is reliable only when filling is disabled.
 .sh 1 "Preprocessor Support"
 .TL
+.b .[
+.DE
+Begin
+.i \%@g@refer (1)
+bibliographic reference.
+.TL
+.b .]
+.DE
+End
+.i \%@g@refer (1)
+bibliographic reference.
+.TL
 .b .EQ
 .i A
 .i T
@@ -1361,7 +1374,7 @@ is
 you can call
 .b .TH
 after some table rows
-to repeat them across columns or pages.
+to repeat them as headings at the tops of pages or columns.
 If you want a table to float,
 surround the
 .b .TS
@@ -1415,7 +1428,7 @@ leaving the drawing position at the bottom of the picture.
 .DE
 End
 .i \%@g@pic
-picture,
+picture with flyback,
 leaving the drawing position at the top of the picture.
 .TL
 .b .IS
@@ -1442,7 +1455,7 @@ leaving the drawing position at the bottom of the picture.
 .DE
 End
 .i ideal
-picture,
+picture with flyback,
 leaving the drawing position at the top of the picture.
 .TL
 .b .GS
@@ -1473,7 +1486,7 @@ leaving the drawing position at the bottom of the picture.
 .DE
 End
 .i \%@g@grn
-picture,
+picture with flyback,
 leaving the drawing position at the top of the picture.
 .sh 1 "Formal Documents"
 .TL
@@ -1558,7 +1571,7 @@ backslashes must precede
 .)f
 For example,
 \[lq]\c
-.b ".++ RA |||\eEn(ch.%|" \[rq]
+.b ".++ RA ###\eEn(ch.%#" \[rq]
 numbers appendices and pages as
 .bi A .\c
 .bi n
@@ -1582,6 +1595,9 @@ at the end of the paper,
 so that the table of contents
 can be collected and put out;
 this material can then be resequenced
+by the
+.b pdfswitchtopage
+macro (for PDF output),
 by a tool that processes the output format,
 or physically moved
 to the beginning of the printed document.
@@ -1735,10 +1751,10 @@ the text from a figure.
 .DE
 End this page,
 but do not begin the next page.
-Useful for forcing out footnotes,
-but other than
-that hardly ever used.
-Must be followed by a
+.\" Useful for forcing out footnotes,
+.\" but other than
+.\" that hardly ever used.
+Follow it with a
 .b .bp
 request or the end of input.
 .\" dead-tree pagination
@@ -1893,8 +1909,8 @@ Interpolate delayed text number surrounded by square 
brackets:
 .ST {
 .DE
 Begin superscripting:
-move upward and reduce the type size.
-The line height is increased above by
+move upward and reduce type size.
+The line height increases above by
 .NR (sx
 [0.2m]
 to accommodate the superscript.
@@ -1904,7 +1920,7 @@ output a left square bracket.
 .ST }
 .DE
 End superscripting:
-reverse the motion and type size change of
+reverse motion and type size change of
 .ST { .
 In \*N mode,
 output a right square bracket.
@@ -1926,8 +1942,8 @@ output a right square bracket.
 .ST <
 .DE
 Begin subscripting:
-move downward and reduce the type size.
-The line height is increased below by
+move downward and reduce type size.
+The line height increases below by
 .NR (sx
 to accommodate the subscript.
 In \*N mode,
@@ -1936,7 +1952,7 @@ output a left angle bracket.
 .ST >
 .DE
 End subscripting:
-reverse the motion and type size change of
+reverse motion and type size change of
 .ST < .
 In \*N mode,
 output a right angle bracket.