[PATCH 7/8] doc/bash.1: make code displays more portable

[G. Branden Robinson]

1.  Use `EX`/`EE` extension.

groff_man(7):
     .EX
     .EE    Begin and end example.  After .EX, filling is disabled and a
            constant‐width (monospaced) font is selected.  Calling .EE
            enables filling and restores the previous font.

            .EX and .EE are extensions introduced in Ninth Edition Unix.
            Documenter’s Workbench, Heirloom Doctools, and Plan 9
            troffs, and mandoc (since 1.12.2) also support them.
            Solaris troff does not.  See subsection “Use of extensions”
            in groff_man_style(7).

If the man(7) implementation doesn't support these, no harm is
done--only groff complains about undefined macros.  Calling one is a
no-op.  Consequently, invoke `nf` and `fi` within `EX` and `EE`, which
is redundant on systems that support the latter, but still gets the
desired effect elsewhere--but do this only for multi-line code displays;
it's not necessary for a one-liner.  Using the macros also avoids the
`CW` font portability problem.

2.  Use a relative inset for the "_completion_loader" code display, so
    it looks "displayed" even if the font family can't be changed.

3.  Adapt the "_completion_loader" code display to varying line lengths
    in the output device.  Indent function body by two spaces, not four.
    Use dirty *roff tricks to make the long lines wrap if the device is
    narrow (less than 80 ens width, which likely means a user-configured
    terminal or AT&T nroff, where the line length defaults to 65 ens).

This fixes the last of these warnings:

troff:./doc/bash.1:7422: warning: cannot select font 'CW'

...and no lines should be overset even on a legacy Unix system.

$ groff -rLL=65n -man -T ascii -P -cbou ./doc/bash.1 | wc -L
65
---
 doc/bash.1 | 34 ++++++++++++++++++++++++----------
 1 file changed, 24 insertions(+), 10 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index fff8a817..35c076f0 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -365,8 +365,9 @@ .SH INVOCATION
 behaves as if the following command were executed:
 .PP
 .RS
-.if t \f(CWif [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi\fP
-.if n if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
+.EX
+if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
+.EE
 .RE
 .PP
 but the value of the
@@ -1356,8 +1357,9 @@ .SH PARAMETERS
 argument, running
 .PP
 .RS
-.if t \f(CWdeclare \-n ref=$1\fP
+.EX
 .if n declare \-n ref=$1
+.EE
 .RE
 .PP
 inside the function creates a nameref variable \fBref\fP whose value is
@@ -7419,17 +7421,29 @@ .SS Programmable Completion
 file corresponding to the name of the command, the following default
 completion function would load completions dynamically:
 .PP
-\f(CW_completion_loader()
-.br
+.RS
+.EX
+.nf
+_completion_loader()
 {
+  . "/etc/bash_completion.d/$1.sh" \c
+.if \n(LL<80n \{\
+\e
 .br
-        . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
-.br
+.ti +4n
+.\}
+>/dev/null 2>&1 && return 124
 }
+complete \-D \-F _completion_loader \c
+.if \n(LL<80n \{\
+\e
 .br
-complete \-D \-F _completion_loader \-o bashdefault \-o default
-.br
-\fP
+.ti +4n
+.\}
+\-o bashdefault \-o default
+.fi
+.EE
+.RE
 .SH HISTORY
 When the
 .B \-o history
-- 
2.30.2

signature.asc
Description: PGP signature