[groff] 18/38: [docs]: Revise discussion of tabs and leaders.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ca9b3276792c073964112f3c96e65ae0192318b5
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Aug 29 17:28:42 2022 -0500

    [docs]: Revise discussion of tabs and leaders.
    
    * doc/groff.texi (Tab Stops): Rename subsection/node from this...
      (Tabs and Leaders): ...to this.  Discuss leaders forthrightly.  They
      are part of *roff syntax and it was nagging me that I characterized
      the presentation of roff syntax as complete without dealing with them.
      Correct erroneous description of where the default tab stops are.
      This information was incorrect in a different way in groff 1.22.4
      ("tab stops are initially located every half inch across the page").
      This error goes back to the creation of our Texinfo manual in 1999.
      Illustrate leader usage in example alongside tabs.
    
    * man/groff.7.man (Syntax characters): Mention CTRL+A.  (Blissfully,
      this is one of the few fixed points between ASCII and code page 1047.)
    
      (Tabs and leaders): Add section, synced with above Texinfo content.
---
 doc/groff.texi  | 53 +++++++++++++++++++++++++++--------------------------
 man/groff.7.man | 40 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+), 26 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index ffca1d4be..d31f5596c 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -4880,7 +4880,7 @@ inter-sentence space.
 * Sentences::
 * Breaking::
 * Adjustment::
-* Tab Stops::
+* Tabs and Leaders::
 * Requests and Macros::
 * Macro Packages::
 * Input Encodings::
@@ -5139,7 +5139,7 @@ This is discussed in @ref{Manipulating Filling and 
Adjustment}.
 
 @c ---------------------------------------------------------------------
 
-@node Adjustment, Tab Stops, Breaking, Text
+@node Adjustment, Tabs and Leaders, Breaking, Text
 @subsection Adjustment
 
 @cindex extra spaces between words
@@ -5153,43 +5153,44 @@ Filling and Adjustment}.
 
 @c ---------------------------------------------------------------------
 
-@node Tab Stops, Input Conventions, Adjustment, Text
-@subsection Tab Stops
+@node Tabs and Leaders, Input Conventions, Adjustment, Text
+@subsection Tabs and Leaders
 
 @cindex horizontal tab character
-@cindex tab stops
-@cindex stops, tab
 @cindex tab character
 @cindex character, horizontal tab
-GNU @code{troff} translates horizontal tab characters, also called
-simply ``tabs'', in the input into movements to the next tab stop.
-These tab stops are by default located every half inch measured from the
-current position on the input line.  With them, simple tables can be
-made.@footnote{``Tab'' is short for ``tabulation'', revealing the term's
-origin as a spacing mechanism for table arrangement.}  However, this
-method can be deceptive, as the appearance (and width) of the text in an
-editor and the results from GNU @code{troff} can vary greatly,
-particularly when proportional typefaces are used.
-
-A tab character does not cause a break and therefore does not interrupt
-filling.  We use an arrow @arrow{} below to indicate an input tab
-character.
+@cindex leader character
+@cindex character, leader
+@cindex tab stops
+@cindex stops, tab
+GNU @code{troff} translates input horizontal tab characters (``tabs'')
+and @key{Control+A} characters (``leaders'') into movements to the next
+tab stop.  Tabs simply move to the next tab stop; leaders place enough
+periods to fill the space.  Tab stops are by default located every half
+inch measured from the drawing position corresponding to the beginning
+of the input line; see @ref{Page Geometry}.   Tabs and leaders do not
+cause breaks and therefore do not interrupt filling.  Below, we use
+arrows @arrow{} and bullets @bullet{} to indicate input tabs and
+leaders, respectively.
 
 @Example
 1
-@arrow{} 2 @arrow{} 3 @arrow{} 4
-@arrow{} @arrow{} 5
-@result{} 1         2       3       4                 5
+@arrow{} 2 @arrow{} 3 @bullet{} 4
+@arrow{} @bullet{} 5
+@result{} 1         2       3.......4         ........5
 @endExample
 
-GNU @code{troff} provides sufficient facilities for sophisticated table
-composition; see @ref{Tabs and Fields}.  There are many details to track
-when using such low-level features, so most users turn to the
+Tabs and leaders lend themselves to table construction.@footnote{``Tab''
+is short for ``tabulation'', revealing the term's origin as a spacing
+mechanism for table arrangement.} The tab and leader glyphs can be
+configured, and further facilities for sophisticated table composition
+are available; see @ref{Tabs and Fields}.  There are many details to
+track when using such low-level features, so most users turn to the
 @cite{tbl@r{(1)}} preprocessor for table construction.
 
 @c ---------------------------------------------------------------------
 
-@node Requests and Macros, Macro Packages, Tab Stops, Text
+@node Requests and Macros, Macro Packages, Tabs and Leaders, Text
 @subsection Requests and Macros
 
 We have now encountered almost all of the syntax there is in the
diff --git a/man/groff.7.man b/man/groff.7.man
index 71541fafb..2c7f5ab07 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -488,6 +488,13 @@ It ends the argument (list).
 .
 .
 .P
+Additionally,
+the Control+A character (U+0001) in text is interpreted as a
+.I leader
+(see below).
+.
+.
+.P
 Horizontal white space characters are significant to
 .I groff,
 but trailing spaces on text lines are ignored.
@@ -552,6 +559,39 @@ next defined tab stop.
 .
 .
 .\" ====================================================================
+.SH "Tabs and leaders"
+.\" ====================================================================
+.
+.\" BEGIN Keep (roughly) parallel with groff.texi node "Tabs and
+.\" Leaders".
+The formatter interprets input horizontal tab characters
+(\[lq]tabs\[rq]) and Control+A characters (\[lq]leaders\[rq]) into
+movements to the next tab stop.
+.
+Tabs simply move to the next tab stop;
+leaders place enough periods to fill the space.
+.
+Tab stops are by default located every half inch measured from the
+drawing position corresponding to the beginning of the input line;
+see section \[lq]Page geometry\[rq] of
+.MR roff 7 .
+.
+Tabs and leaders do not cause breaks and therefore do not interrupt
+filling.
+.
+Tab stops can be configured with the
+.B ta
+request,
+and tab and leader glyphs with the
+.B tc
+and
+.B lc
+requests,
+respectively.
+.\" END Keep (roughly) parallel with groff.texi node "Tabs and Leaders".
+.
+.
+.\" ====================================================================
 .SH "Line continuation"
 .\" ====================================================================
 .