[PATCH 02/25] doc/bash.1: Document approach to conditional text.

[G. Branden Robinson]

Also ensure the controlling registers are initialized without changing
their values, avoiding groff "reg" warnings.  Similarly, define the end
macros used as end macros in `ig` requests as empty, avoiding groff
"mac" warnings.

Fixes:
$ nroff -ww -z -man ./doc/bash.1
troff:./doc/bash.1:13: warning: register 'zZ' not defined
troff:./doc/bash.1:14: warning: register 'zY' not defined
troff:./doc/bash.1:8611: warning: macro 'zZ' not defined
troff:./doc/bash.1:12894: warning: macro 'zY' not defined

Background from groff's Texinfo manual:

5.7 Comments
============
...
 -- Request: .ig [end]
     Ignore input until, in the current conditional block (if any),(2)
     (*note Comments-Footnote-2::) the macro END is called at the start
     of a control line, or the control line '..' is encountered if END
     is not specified.  'ig' is parsed as if it were a macro definition,
     but its contents are discarded, not stored.(3)  (*note
     Comments-Footnote-3::)

5.24 Writing Macros
===================
...
 -- Request: .de name [end]
     Define a macro NAME, replacing the definition of any existing
     request, macro, string, or diversion called NAME.  If NAME already
     exists as an alias, the target of the alias is redefined; recall
     *note Strings::.  GNU 'troff' enters copy mode,(1) (*note Writing
     Macros-Footnote-1::) storing subsequent input lines as the macro
     definition.  If the optional second argument is not specified, the
     definition ends with the control line '..' (two dots).
     Alternatively, END identifies a macro whose call syntax at the
     start of a control line ends the definition of NAME; END is then
     called normally.  A macro definition must end in the same
     conditional block (if any) in which it began (recall *note
     Conditional Blocks::).  Spaces or tabs are permitted after the
     control character in the line containing this ending token (either
     '.' or 'END'), but a tab immediately after the token prevents its
     recognition as the end of a macro definition.  The macro END can be
     called with arguments.(2)  (*note Writing Macros-Footnote-2::)
---
 doc/bash.1 | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index f68eecc3..23a8dbd6 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -7,9 +7,17 @@
 .\"
 .\"    Last Change: Fri Nov 15 17:55:48 EST 2024
 .\"
-.\" bash_builtins, strip all but Built-Ins section
-.\" avoid a warning about an undefined register
-.\" .if !rzY .nr zY 0
+.\" The bash_builtins page strips all sections except "SHELL BUILT-IN
+.\" COMMANDS".  The rbash page strips all sections except "RESTRICTED
+.\" SHELL".  Use *roff registers to control this and a few phrases
+.\" conditional on the page's identity.
+.\"
+.\" Ensure the registers are initialized to avoid groff warnings.
+.nr zZ +0
+.nr zY +0
+.\" Ensure the macros/strings are initialized to avoid groff warnings.
+.ds zZ \" empty
+.ds zY \" empty
 .if \n(zZ=1 .ig zZ
 .if \n(zY=1 .ig zY
 .TH BASH 1 "2024 November 15" "GNU Bash 5.3"
-- 
2.30.2

signature.asc
Description: PGP signature