[groff] 08/37: doc/groff.texi: Revise discussion of `\B' escape.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit beb5be8127a0fcd26f85851bd5d6eabac11d92ba
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Mar 7 12:29:47 2022 +1100

    doc/groff.texi: Revise discussion of `\B' escape.
    
    Clarify that it interpolates a value.  Add example of usage.  Help
    reader avoid having to leap forward to a discussion of register formats.
    
    Clarify: it is not the "entire expression" that needs to be surrounded
    by parentheses to permit use of spaces, just the (sub)expression that
    contains them.
    
    Add example of (formally) complex numeric expressions.
---
 doc/groff.texi | 40 +++++++++++++++++++++++++++++++++-------
 1 file changed, 33 insertions(+), 7 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index dd96bdd3..280a9838 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -5950,24 +5950,50 @@ In the foregoing example, we've used the @code{\Z} 
escape sequence
 (@pxref{Page Motions}) to restore the drawing position after formatting
 @samp{C}, then moved vertically to the first text baseline on the page.
 
-@codequotebacktick off
-@codequoteundirected off
-
 @Defesc {\\B, @code{'}, anything, @code{'}}
 @cindex numeric expression, valid
 @cindex valid numeric expression
-Return@tie{}1 if @var{anything} is a valid numeric expression; or@tie{}0
-if @var{anything} is empty or not a valid numeric expression.
+Interpolate@tie{}1 if @var{anything} is a valid numeric expression,
+and@tie{}0 otherwise.  You might use this escape sequence along with the
+@code{if} request to filter out invalid macro or string arguments.
+@xref{Conditionals and Loops}.
 @endDefesc
 
+@Example
+.\" Indent by amount given in first argument; assume ens.
+.de Indent
+.  if \B'\\$1' .in (n;\\$1)
+..
+@endExample
+
 A register interpolation used as an operand in an expression must have
-an Arabic format; see @ref{Assigning Register Formats}.
+an Arabic format; luckily, this is the default.  @xref{Assigning
+Register Formats}.
 @cindex space characters, in expressions
 @cindex expressions, and space characters
 Due to the way arguments are parsed, spaces are not allowed in
-expressions unless the entire expression is surrounded by parentheses.
+expressions unless the (sub)expression containing them is surrounded by
+parentheses.
 @xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}.
 
+@Example
+.nf
+.nr a 1+2 + 2+1
+\na
+    @error{} expected numeric expression, got a space
+    @result{} 3
+.nr a 1+(2 + 2)+1
+\na
+    @result{} 6
+@endExample
+
+The @code{nr} request (@pxref{Setting Registers}) expects up to two
+numeric expressions as arguments; a bare @samp{+} does not qualify, so
+our first attempt got a warning.
+
+@codequotebacktick off
+@codequoteundirected off
+
 
 @c =====================================================================