[groff] 18/19: [docs]: Update discussion of '|' operator.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 88cbc3f2b34de2b5bd5352221e41ee6c2e09fabb
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Nov 9 10:22:11 2021 +1100

    [docs]: Update discussion of '|' operator.
    
    Try to make examples of its use more illustrative and practical.
    
    Thanks to Peter Schaffter for the discussion in
    <https://lists.gnu.org/archive/html/groff/2021-10/msg00016.html> et
    sequentia.
---
 doc/groff.texi  | 82 ++++++++++++++++++++++++++++++++++-----------------------
 man/groff.7.man | 62 ++++++++++++++++++++++++++++++++++---------
 2 files changed, 99 insertions(+), 45 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index e207f79..d97f638 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -5730,49 +5730,65 @@ Here, leading plus and minus signs indicate increments 
and decrements.
 
 @xref{Setting Registers}, for some examples.
 
+@codequotebacktick on
+@codequoteundirected on
+
 @opindex |
 @cindex @code{|}, and page motion
-@cindex absolute position operator (@code{|})
-@cindex position, absolute, operator (@code{|})
-Similarly, a leading @samp{|} operator indicates an absolute position.
-For vertical movements, it specifies the distance from the top of the
-page; for horizontal movements, it gives the distance from the beginning
-of the @emph{input} line.
-
-Many escapes use positioning relative to the input line.  For example,
-this
-
-@Example
-This is a \h'|1.2i'test.
-
-This is a
-\h'|1.2i'test.
-@endExample
-
-@noindent
-produces
-
-@Example
-This is a   test.
-
-This is a             test.
+@cindex ``absolute'' position operator (@code{|})
+@cindex position, ``absolute'', operator (@code{|})
+@cindex boundary-relative motion operator (@code{|})
+@c "motion" and "operators" already indexed above
+Similarly, a leading @samp{|} operator indicates a motion relative not
+to the current position but to a boundary.  For vertical movements, it
+specifies a distance from the top of the page (or diversion); for
+horizontal ones, from the beginning of the @emph{input} line.  Some
+escape sequences
+@c XXX: which ones?
+reckon motions relative to the beginning of the input line.@footnote{As
+do tab stops, by default (@pxref{Tabs and Fields}).}  Most do not;
+@samp{|} tells them to do so.
+
+@Example
+Mind the \h'1.2i'gap.
+.br
+Mind the \h'|1.2i'gap.
+.br
+Mind the
+\h'|1.2i'gap.
+@c 13 spaces, 4 spaces, 13 spaces
+    @result{} Mind the             gap.
+    @result{} Mind the    gap.
+    @result{} Mind the             gap.
 @endExample
 
-The main usage of this feature is to define macros that act exactly at
-the place where called.
+The main use of this feature is to define macros whose scope is limited
+to the output they format.
 
 @Example
-.\" A simple macro to underline a word
-.de underline
-.  nop \\$1\l'|0\[ul]'
+.\" underline word $1 with trailing punctuation $2
+.de Underline
+.  nop \\$1\l'|0\[ul]'\\$2
 ..
+Typographical emphasis is best used
+.Underline sparingly .
 @endExample
 
 @noindent
-In the above example, @samp{|0} specifies a negative distance from the
-current position (at the end of the just emitted argument @code{\$1})
-back to the beginning of the input line.  Thus, the @samp{\l} escape
-draws a line from right to left.
+In the above example, @samp{|0} specifies a negative motion from the
+current position (at the end of the argument just emitted, @code{\$1})
+to the beginning of the input line.  Thus, the @samp{\l} escape sequence
+in this case draws a line from right to left.  A macro call occurs at
+the beginning of an input line;@footnote{Control structure syntax
+creates an exception to this rule, but is designed to remain useful:
+recalling our example, @samp{.if 1 .Underline this} would underline only
+``this'', precisely.  @xref{Conditionals and Loops}.} if the @code{|}
+operator were omitted, then the underline would be drawn to the
+beginning of the @emph{output} line, where many words might precede the
+macro argument.
+
+@codequotebacktick off
+@codequoteundirected off
 
 @Defesc {\\B, @code{'}, anything, @code{'}}
 @cindex numeric expression, valid
diff --git a/man/groff.7.man b/man/groff.7.man
index e3288df..44c17c3 100644
--- a/man/groff.7.man
+++ b/man/groff.7.man
@@ -828,8 +828,22 @@ Scale by 65536.
 .
 .P
 .B Numerical expressions
-are combinations of the numerical values defined above with the
-following arithmetical operators already defined in classical troff.
+are combinations of operators with the numerical values discussed above.
+.
+Arithmetic operators are parsed strictly from left to right;
+traditional algebraic precedence is not observed.
+.
+Use
+.B (
+and
+.B )
+to specify operator precedence.
+.
+Parentheses also permit the use of spaces between operators and their
+arguments.
+.
+Several operators were defined by AT&T
+.IR troff . \" AT&T
 .
 .
 .P
@@ -894,20 +908,50 @@ Logical not
 .
 .TPx
 .B (
-Grouping of expressions
+Begin expression group of higher precedence
 .
 .TPx
 .B )
-Close current grouping
+End expression group of higher precedence
 .
 .RE
 .PD
 .
 .
 .P
-Moreover,
+In many contexts,
+unary prefix operators are also available in contexts where they make
+sense.
+.
+.
+.RS
+.TP
+.B +
+.TQ
+.B \-
+Increment or decrement the argument implied by the request or escape
+sequence by the following expression.
+.
+.
+.TP
+.B |
+Interpret the following expression as a motion relative not to the
+current position but to a boundary.
+.
+For vertical movements,
+it specifies a distance from the top of the page
+(or diversion);
+for horizontal ones,
+from the beginning of the
+.I input
+line.
+.RE
+.
+.
+.P
+Furthermore,
 .I groff
-provides the following additional operators for numerical expressions.
+provides some additional arithmetic operators.
 .
 .
 .P
@@ -940,12 +984,6 @@ as the default scaling indicator.
 .PD
 .
 .
-.P
-For details see the
-.I groff
-Texinfo manual.
-.
-.
 .\" ====================================================================
 .SH "Control structures"
 .\" ====================================================================