Re: A documentation coincidence

[G. Branden Robinson]

At 2024-10-11T12:36:47-0400, Chet Ramey wrote:
> On 10/8/24 12:24 PM, G. Branden Robinson wrote:
> > What a coincidence!  I was preparing a big batch of updates myself.
> > Attached for your edification, not so much for integration, as I'm
> > sure many of them won't apply now.
> 
> Thanks for these. I'll take a look and see what applies.

Some of them are still in sketchy, notes-to-self form, and may lack the
amount of justification/background I normally offer.  Feel free to ask
for clarification.

> The docs always get some love as part of the release process. I decided
> to give them a more thorough overhaul this cycle.

Shotts will have to revise his book again... ;-)

Regards,
Branden


signature.asc
Description: PGP signature

A documentation coincidence

[G. Branden Robinson]

Hi Chet,

I just saw this pass by:

  commit 9d1eb43fdd363137dd687bc411b14ab4946f939c (HEAD -> devel, origin/devel)
  Author: Chet Ramey 
  Date:   Tue Oct 8 09:52:21 2024 -0400

  First set of documentation updates to man page, texinfo manual

What a coincidence!  I was preparing a big batch of updates myself.
Attached for your edification, not so much for integration, as I'm sure
many of them won't apply now.

Reckon I'll see how your updates settle out before restarting this work.

Good to see the docs getting some love.

Regards,
Branden


bash.1-patches.tar.gz
Description: application/gzip


signature.asc
Description: PGP signature

Re: Readline Documentation

[G. Branden Robinson]

At 2024-09-13T15:24:15-0400, Chet Ramey wrote:
> It has no effects in its default state. If you don't change it, nothing
> happens. If you change it, you change `bell-style' instead.
> 
> > The fact that its usage continues suggests documenting it as
> > deprecated would be beneficial.
> 
> Maybe. Or maybe it's just time to remove it once and for all.

I am reminded of
. :)

Regards,
Branden


signature.asc
Description: PGP signature

Re: Potentially misleading documentation of SECONDS variable

[G. Branden Robinson]

At 2024-08-07T10:07:23-0400, Chet Ramey wrote:
> On 8/6/24 12:25 PM, Koichi Murase wrote:
> 
> > diff --git a/doc/bash.1 b/doc/bash.1
> > index 1f0a23d3..3ace21e9 100644
> > --- a/doc/bash.1
> > +++ b/doc/bash.1
> > @@ -2091,7 +2091,7 @@ the value returned upon subsequent
> >   references is
> >   the number of seconds since the assignment plus the value assigned.
> >   The number of seconds at shell invocation and the current time are always
> > -determined by querying the system clock.
> > +determined by querying the system clock at the resolution of a second.
> 
> This is not unreasonable.

At the risk of splitting hairs, I would cast the added phrase as:

"at a resolution of one second".

I think that's more idiomatic, but I might read too many kibitzers and
nit pickers.

Regards,
Branden


signature.asc
Description: PGP signature

a groff convenience for quoting man pages (was: if source command.sh & set -e issue)

[G. Branden Robinson]

Hi Chet,

At 2024-07-26T11:18:57-0400, Chet Ramey wrote:
> The man page says, about this scenario:
> 
> "The  shell  does  not  exit if the command that fails is
>  part of the command list immediately following  a  while
>  or  until  keyword, part of the test following the if or
>  elif reserved words, part of any command executed  in  a
>  &&  or || list except the command following the final &&
>  or ||, any command in a pipeline but the last, or if the
>  command's  return  value is being inverted with !.  If a
>  compound command other than a subshell  returns  a  non-
>  zero  status because a command failed while -e was being
>  ignored, the shell does not exit."

Like you, I frequently have reason to quote man pages to people.  The
adjustment of lines ends up looking a bit weird for people who read
email using a proportional font.[1]  If you're running groff 1.23.0
(released July 2023) on the machine you send email from, you can tell it
to suppress adjustment to both margins on the fly, without changing any
configuration files or defaults.

I have a shell function called "mailman"--merrily colliding with the
name of other software I don't personally use.

# As gman, but format for email.
mailman () {
local cmd=
case "$1" in
(-*)
opts="$opts $1"
shift
;;
esac

set -- $(man -w "$@")
cmd=$(zcat --force "$@" | \
  grog -Tutf8 -b -ww -P -cbou -rU0 -rLL=72n -rHY=0 -dAD=l \
   $opts)
zcat --force "$@" | $cmd | less
}

There are many conveniences packed into that function.  I'm happy to
elaborate further; follow-ups might be better sited on the groff list
than bug-bash.

Regards,
Branden

[1] ...such as those accursed with GMail, which has proudly refused to
support an option for rendering emails in monospace for 20+ years,
because everyone at Google is smarter than you


signature.asc
Description: PGP signature

Re: [PATCH v2 5/8] builtins/source: parse the -i option

[G. Branden Robinson]

At 2024-05-20T03:42:04+0700, Robert Elz wrote:
> My memory is hopeless, and I'm sure someone on the list can supply the
> correct attribution, but one of the big name CS people once said
> something along the lines of "perfection isn't when there's nothing
> left to add, but when there's nothing left to remove".

That would be Antoine de Saint-Exupéry, author of _La Petit Prince_,
which you may have read as a child, or read to children at some point.

Wikipedia says he was a "writer, poet, and aviator".

A reminder, were one needed, that intellectual silos are costly!  :)

(I only had this factoid ready at hand because Peter Schaffter, author
of the mom macro package for groff, uses it in his .signature file.)

Regards,
Branden


signature.asc
Description: PGP signature

Re: [PATCH v2 5/8] builtins/source: parse the -i option

[G. Branden Robinson]

At 2024-05-16T11:36:50-0400, Chet Ramey wrote:
> On 5/15/24 6:27 PM, Robert Elz wrote:
> > and any attempt to use a relative path (and you
> > can exclude ./anything or ../anything from that if you prefer - ie:
> 
> Those are not relative paths.

!

POSIX 1003.1-202x/D4, §3.311 defines "relative pathname" thus:

"A pathname not beginning with a  character."

Can you clarify?  Does Bash have its own definition of this term?
Does it need to?

Regards,
Branden


signature.asc
Description: PGP signature

Re: 5.3-alpha: the `jobs' builtin prints foreground dead jobs with function substitutions

[G. Branden Robinson]

At 2024-05-02T16:30:09+0300, Oğuz wrote:
> On Thu, May 2, 2024 at 3:55 PM Chet Ramey  wrote:
> > A paraphrase of what?
> 
> Issue 7 says this:
> 
> By default, the jobs utility shall display the status of all stopped
> jobs, running background jobs and all jobs whose status has changed
> and have not been reported by the shell.
> 
> And Issue 8 draft, this:
> 
> By default, the jobs utility shall display the status of all
> background jobs, both running and suspended, and all jobs whose status
> has changed and have not been reported by the shell.
> 
> The latter, which seems to be a paraphrase of the former,

Your choice of term puzzles me.  I'd call it a "revision".

The standard isn't trying to quote itself, formally or ad hoc.  It has
altered the language of the specification.

Regards,
Branden


signature.asc
Description: PGP signature

Re: [PATCH v2 04/18] doc/bash.1: improve typography of ellipses

[G. Branden Robinson]

Hi Martin,

At 2024-04-12T14:55:22+1200, Martin D Kealey wrote:
> On Thu, 1 Feb 2024 at 07:54, G. Branden Robinson <
> g.branden.robin...@gmail.com> wrote:
> 
> > v2: Prevent confclit with PATCH v2 01/18.
> > Apply ellipsis advice from groff_man_style(7).
> > • The dummy character escape sequence \& follows the ellipsis when
> > further text will follow after space on the output line, keeping its
> > last period from being interpreted as the end of a sentence and
> > causing additional inter‐sentence space to be placed after it.
> 
> Is there a reason why we're still using a triple period/full-stop
> “...” (\u002e) instead of an actual ellipsis “…” (\u2026)?

Yes.  Portability to troffs that don't support GNU troff extensions.

 • Why doesn’t the package provide a string to insert an ellipsis?

[...]
   There is an ellipsis code point in Unicode, and some fonts have
   an ellipsis glyph, which some man pages have accessed in a non‐
   portable way with the font‐dependent \N escape sequence.  We
   discourage the use of these; on terminals, they may crowd the
   dots into a half‐width character cell, and will not render at all
   if the output device doesn’t have the glyph.  In syntax synopses,
   missing ellipses can mislead the reader.  Dots and space are
   universally supported.

When AT&T troff finally dies or is abandoned by projects (like Bash and
ncurses) currently maintaining portability to System V hosts (like
Solaris 10), that might be a good time to reconsider the foregoing
point.

But likely not with a *roff _string_, for reasons I elided.

Regards,
Branden


signature.asc
Description: PGP signature

Re: [PATCH 06/13] lib/readline/doc/history.3: Drop microtypography.

[G. Branden Robinson]

At 2024-04-01T09:27:27-0400, Chet Ramey wrote:
> On 3/28/24 5:11 PM, G. Branden Robinson wrote:
> > Now that we're using a correct caret/circumflex/hat glyph on
> > modern typesetters (and terminals with a Unicode repertoire), drop the
> > thicket of partial-line motion and type size-altering escape sequences,
> > certain to frighten and confuse any unfrozen caveman page authors.
> 
> I'm almost positive this came from an original BSD csh(1) man page.

Checking minnie @ TUHS, I don't see it in /usr/man/man1/csh.1 in 3BSD,
2.9BSD (which actually came later), 4BSD, or 4.4BSD.  Given those
samples, I didn't check others.

Also I should retract a concession I made.  This patch doesn't regress
the typography on AT&T troff on typesetters (or nroff to whatever line
and daisy-wheel printers people still have in service)--that was an
assumption I made.  Rather, my patch improves it.

Looking closely at the original *roff, the reason is obvious (to those
poor souls trained in reading *roff):

.B \d\s+2\*^\s-2\u\fIstring1\fP\d\s+2\*^\s-2\u\fIstring2\fP\d\s+2\*^\s-2\u
.Q !!:s\d\s+2\*^\s-2\u\fIstring1\fP\d\s+2\*^\s-2\u\fIstring2\fP\d\s+2\*^\s-2\u

If those are supposed to be _superscripts_, they're backwards.  The
"move up half line" (\u) and "move down half line" (\d) escape sequences
are swapped.

Demonstrator man(7) document and PostScript output from DWB 3.3, Solaris
10, and Heirloom Doctools troffs attached.

Regards,
Branden
.TH foo 1 2024-04-02 "groff test suite"
.ie \n(.g .ds ^ \(ha
.el   .ds ^ ^
.
.de Q
.ie \n(.g \(lq\\$1\(rq\\$2
.el \{\
.  if t ``\\$1''\\$2
.  if n "\\$1"\\$2
.\}
..
.SH Name
microtypography \- a demonstration of a change to
.IR history (3)
formatting
.SH Description
.SS Formerly
.TP
.B \d\s+2\*^\s-2\u\fIstring1\fP\d\s+2\*^\s-2\u\fIstring2\fP\d\s+2\*^\s-2\u
Quick substitution.  Repeat the last command, replacing
.I string1
with
.IR string2 .
Equivalent to
.Q !!:s\d\s+2\*^\s-2\u\fIstring1\fP\d\s+2\*^\s-2\u\fIstring2\fP\d\s+2\*^\s-2\u
(see \fBModifiers\fP below).
.SS Now
.TP
.B \*^\fIstring1\fP\*^\fIstring2\fP\*^
Quick substitution.  Repeat the last command, replacing
.I string1
with
.IR string2 .
Equivalent to
.Q !!:s\*^\fIstring1\fP\*^\fIstring2\fP\*^
(see \fBModifiers\fP below).


microtypography.dwb.ps
Description: PostScript document


microtypography.solaris10.ps
Description: PostScript document


microtypography.heirloom.ps
Description: PostScript document


signature.asc
Description: PGP signature

[PATCH 13/13] doc/bash.1: Trivially refactor *roff markup.

[G. Branden Robinson]

Use `\fP` to restore previous font in places where it adequately
returns to roman face rather than the explicit `\fR` (which can clobber
the "previous font selection" datum in the formatter).
---
 doc/bash.1 | 30 +++---
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 323356c7..eeff6b63 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -89,7 +89,7 @@ .SH COPYRIGHT
 .if t Bash is Copyright \(co 1989-2023 by the Free Software Foundation, Inc.
 .SH DESCRIPTION
 .B Bash
-is an \fBsh\fR-compatible command language interpreter that
+is an \fBsh\fP-compatible command language interpreter that
 executes commands read from the standard input or from a file.
 .B Bash
 also incorporates useful features from the \fIKorn\fP and \fIC\fP
@@ -103,9 +103,9 @@ .SH DESCRIPTION
 can be configured to be POSIX-conformant by default.
 .SH OPTIONS
 All of the single-character shell options documented in the
-description of the \fBset\fR builtin command, including \fB\-o\fP,
+description of the \fBset\fP builtin command, including \fB\-o\fP,
 can be used as options when the shell is invoked.
-In addition, \fBbash\fR
+In addition, \fBbash\fP
 interprets the following options when it is invoked:
 .PP
 .PD 0
@@ -5958,10 +5958,10 @@ .SH READLINE
 builtin.
 .SS "Readline Notation"
 In this section, the Emacs-style notation is used to denote
-keystrokes.  Control keys are denoted by C\-\fIkey\fR, e.g., C\-n
+keystrokes.  Control keys are denoted by C\-\fIkey\fP, e.g., C\-n
 means Control\-N.  Similarly,
 .I meta
-keys are denoted by M\-\fIkey\fR, so M\-x means Meta\-X.  (On keyboards
+keys are denoted by M\-\fIkey\fP, so M\-x means Meta\-X.  (On keyboards
 without a
 .I meta
 key, M\-\fIx\fP means ESC \fIx\fP, i.e., press the Escape key
@@ -7841,11 +7841,11 @@ .SS Event Designators
 or ( (when the \fBextglob\fP shell option is enabled using
 the \fBshopt\fP builtin).
 .TP
-.B !\fIn\fR
+.B !\fIn\fP
 Refer to command line
 .IR n .
 .TP
-.B !\-\fIn\fR
+.B !\-\fIn\fP
 Refer to the current command minus
 .IR n .
 .TP
@@ -7853,12 +7853,12 @@ .SS Event Designators
 Refer to the previous command.  This is a synonym for
 .Q !\-1 .
 .TP
-.B !\fIstring\fR
+.B !\fIstring\fP
 Refer to the most recent command preceding the current position in the
 history list starting with
 .IR string .
 .TP
-.B !?\fIstring\fR\fB[?]\fR
+.B !?\fIstring\fP[?]
 Refer to the most recent command preceding the current position in the
 history list containing
 .IR string .
@@ -7903,7 +7903,7 @@ .SS Word Designators
 word.
 .TP
 .I n
-The \fIn\fRth word.
+The \fIn\fPth word.
 .TP
 .B \*^
 The first argument.  That is, word 1.
@@ -7914,15 +7914,15 @@ .SS Word Designators
 .TP
 .B %
 The first word matched by the most recent
-.Q ?\fIstring\fR?'
+.Q ?\fIstring\fP?'
 search,
 if the search string begins with a character that is part of a word.
 .TP
 .I x\fB\-\fPy
 A range of words;
-.Q \-\fIy\fR
+.Q \-\fIy\fP
 abbreviates
-.Q 0\-\fIy\fR .
+.Q 0\-\fIy\fP .
 .TP
 .B *
 All of the words but the zeroth.
@@ -8005,7 +8005,7 @@ .SS Modifiers
 the last
 .I string
 in a
-.B !?\fIstring\fR\fB[?]\fR
+.B !?\fIstring\fP[?]
 search.
 If
 .I new
@@ -12287,7 +12287,7 @@ .SH BUG REPORTS
 .PP
 .PD 0
 .TP 20
-The version number of \fBbash\fR
+The version number of \fBbash\fP
 .TP
 The hardware and operating system
 .TP
-- 
2.30.2


signature.asc
Description: PGP signature

[PATCH 11/13] [man pages]: Make comment more informative.

[G. Branden Robinson]

Double quotes aren't any easier to use with AT&T troff just because you
tuck them inside a string definition.  (The _name_ of the string doesn't
matter; that gets interpolated before "quote removal", if you will.)

https://www.gnu.org/software/groff/manual/groff.html.node/Calling-Macros.html
---
 doc/bash.1  | 2 +-
 lib/readline/doc/history.3  | 2 +-
 lib/readline/doc/readline.3 | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index c3253b09..a32fb88c 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -47,7 +47,7 @@
 .\}
 .el \{\
 .ds ' '
-.ds " ""\" two adjacent quotes and no space before this comment
+.ds " ""\" not usable in macro arguments on AT&T troff (DWB, Solaris 10)
 .ds ^ ^
 .ds ~ ~
 .\}
diff --git a/lib/readline/doc/history.3 b/lib/readline/doc/history.3
index 111cdbf6..ff21029f 100644
--- a/lib/readline/doc/history.3
+++ b/lib/readline/doc/history.3
@@ -18,7 +18,7 @@
 .\}
 .el \{\
 .ds ' '
-.ds " ""\" two adjacent quotes and no space before this comment
+.ds " ""\" not usable in macro arguments on AT&T troff (DWB, Solaris 10)
 .ds ^ ^
 .ds ~ ~
 .\}
diff --git a/lib/readline/doc/readline.3 b/lib/readline/doc/readline.3
index 438da117..bdd0243b 100644
--- a/lib/readline/doc/readline.3
+++ b/lib/readline/doc/readline.3
@@ -18,7 +18,7 @@
 .\}
 .el \{\
 .ds ' '
-.ds " ""\" two adjacent quotes and no space before this comment
+.ds " ""\" not usable in macro arguments on AT&T troff (DWB, Solaris 10)
 .ds ^ ^
 .ds ~ ~
 .\}
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 12/13] doc/bash.1: Fix *roff style nit.

[G. Branden Robinson]

While font mounting position 3 is usually assigned a bold typeface, it
seems a bit fragile to not explicitly ask for bold.  The concept of
mounting positions is also not something man page authors typically need
to think about.
---
 doc/bash.1 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index a32fb88c..323356c7 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -3918,8 +3918,8 @@ .SS Word Splitting
 of
 .BR  .
 .PP
-Explicit null arguments (\^\f3\*"\^\*"\fP or
-\^\f3\*'\^\*'\fP\^) are retained
+Explicit null arguments (\^\fB\*"\^\*"\fP or
+\^\fB\*'\^\*'\fP\^) are retained
 and passed to commands as empty strings.
 Unquoted implicit null arguments, resulting from the expansion of
 parameters that have no values, are removed.
@@ -4244,7 +4244,7 @@ .SS Quote Removal
 characters
 .BR \e ,
 .BR \*' ,
-and \^\f3\*"\fP\^ that did not result from one of the above
+and \^\fB\*"\fP\^ that did not result from one of the above
 expansions are removed.
 .SH REDIRECTION
 Before a command is executed, its input and output
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 10/13] lib/readline/doc/history.3: Make `EX` and `EE` man(7) macros usable on DWB troff.

[G. Branden Robinson]

This prevents lines in the displayed struct definition from oversetting
on DWB troff.

Diff of rendering (DWB only):

@@ -10150,11 +10150,11 @@
The state of the History library is encapsulated into a sin-
gle structure:

-/*
- * structure for passing around the state of history
- */
-typedef struct _hist_state {
-  HIST_ENTRY **entries; /* pointer to entry records */
+   /*
+* structure for passing around the state of history
+*/
+   typedef struct _hist_state {
+ HIST_ENTRY **entries; /* pointer to entry records */

@@ -10169,11 +10169,11 @@

-  int offset;   /* current record */
-  int length;   /* number of records in list */
-  int size; /* capacity of list in records */
-  int flags;
-} HISTORY_STATE;
+ int offset;   /* current record */
+ int length;   /* number of records in list */
+ int size; /* capacity of list in records */
+ int flags;
+   } HISTORY_STATE;

If the flags member includes HS_STIFLED, the history has
@@ -10774,9 +10774,9 @@
When using the form keyname:function-name or macro, keyname
is the name of a key spelled out in English.  For example:

- Control-u: universal-argument
- Meta-Rubout: backward-kill-word
- Control-o: "> output"
+Control-u: universal-argument
+Meta-Rubout: backward-kill-word
+Control-o: "> output"

In the above example, C-u is bound to the function
@@ -10792,9 +10792,9 @@
be used, as in the following example, but the symbolic char-
acter names are not recognized.

- "\C-u": universal-argument
- "\C-x\C-r": re-read-init-file
- "\e[11~": "Function Key 1"
+"\C-u": universal-argument
+"\C-x\C-r": re-read-init-file
+"\e[11~": "Function Key 1"

In this example, C-u is again bound to the function
@@ -11327,10 +11327,10 @@
  key sequence that quotes the current or previous
  word in bash:

-  $if Bash
-  # Quote the current or previous word
-  "\C-xq": "\eb\"\ef\""
-  $endif
+ $if Bash
+ # Quote the current or previous word
+ "\C-xq": "\eb\"\ef\""
+ $endif

 variable
---
 lib/readline/doc/history.3 | 12 
 1 file changed, 12 insertions(+)

diff --git a/lib/readline/doc/history.3 b/lib/readline/doc/history.3
index d36c454d..111cdbf6 100644
--- a/lib/readline/doc/history.3
+++ b/lib/readline/doc/history.3
@@ -23,6 +23,18 @@
 .ds ~ ~
 .\}
 .
+.\" Fix broken EX/EE macros on DWB troff.
+.\" Detect it: only DWB sets up a `)Y` register.
+.if \n()Y \{\
+.\" Revert the undesired changes to indentation.
+.am EX
+.in -5n
+..
+.am EE
+.in +5n
+..
+.\}
+.
 .\" File Name macro.  This used to be `.PN', for Path Name,
 .\" but Sun doesn't seem to like that very much.
 .\"
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 07/13] lib/readline/doc/history.3: Fix hyphen-minus signs.

[G. Branden Robinson]

Use a *roff minus sign for minus signs and the `-` character in email
addresses.
---
 lib/readline/doc/history.3 | 8 
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/lib/readline/doc/history.3 b/lib/readline/doc/history.3
index 30b4d7be..40b85b20 100644
--- a/lib/readline/doc/history.3
+++ b/lib/readline/doc/history.3
@@ -514,7 +514,7 @@ .SS Searching the History List
 If \fIstring\fP is found, then
 the current history index is set to that history entry, and the value
 returned is the offset in the line of the entry where
-\fIstring\fP was found.  Otherwise, nothing is changed, and a -1 is
+\fIstring\fP was found.  Otherwise, nothing is changed, and a \-1 is
 returned.
 .PP
 .F2 int history_search_prefix "const char *string" "int direction"
@@ -524,13 +524,13 @@ .SS Searching the History List
 through previous entries, otherwise through subsequent entries.
 If \fIstring\fP is found, then the
 current history index is set to that entry, and the return value is 0.
-Otherwise, nothing is changed, and a -1 is returned.
+Otherwise, nothing is changed, and a \-1 is returned.
 .PP
 .F3 int history_search_pos "const char *string" "int direction" "int pos"
 Search for \fIstring\fP in the history list, starting at \fIpos\fP, an
 absolute index into the list.  If \fIdirection\fP is negative, the search
 proceeds backward from \fIpos\fP, otherwise forward.  Returns the absolute
-index of the history element where \fIstring\fP was found, or -1 otherwise.
+index of the history element where \fIstring\fP was found, or \-1 otherwise.
 .SS Managing the History File
 The History library can read the history from and write it to a file.
 This section documents the functions for managing a history file.
@@ -728,7 +728,7 @@ .SH BUG REPORTS
 bug report to \fIbug\-readline\fP@\fIgnu.org\fP.
 If you have a fix, you are welcome to mail that
 as well!  Suggestions and `philosophical' bug reports may be mailed
-to \fPbug-readline\fP@\fIgnu.org\fP or posted to the Usenet
+to \fPbug\-readline\fP@\fIgnu.org\fP or posted to the Usenet
 newsgroup
 .BR gnu.bash.bug .
 .PP
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 09/13] lib/readline/doc/history.3: Revise inline struct.

[G. Branden Robinson]

This unfilled block of text was oversetting the line on DWB nroff, which
uses a line length of 65n (just like Seventh Edition Unix nroff).

Recast comments to occupy less space.

Also bracket this inline code display with `EX`/`EE` macros; this sets
the code in a monospace/constant-width font on platforms supporting this
Ninth Edition Unix/groff man(7) extension, and does nothing elsewhere.
---
 lib/readline/doc/history.3 | 12 +++-
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/lib/readline/doc/history.3 b/lib/readline/doc/history.3
index 7b6ab73b..d36c454d 100644
--- a/lib/readline/doc/history.3
+++ b/lib/readline/doc/history.3
@@ -372,16 +372,18 @@ .SS History Storage
 The state of the History library is encapsulated into a single structure:
 .PP
 .nf
+.EX
 /*
- * A structure used to pass around the current state of the history.
+ * structure for passing around the state of history
  */
 typedef struct _hist_state {
-  HIST_ENTRY **entries; /* Pointer to the entries themselves. */
-  int offset;   /* The location pointer within this array. */
-  int length;   /* Number of elements within this array. */
-  int size; /* Number of slots allocated to this array. */
+  HIST_ENTRY **entries; /* pointer to entry records */
+  int offset;   /* current record */
+  int length;   /* number of records in list */
+  int size; /* capacity of list in records */
   int flags;
 } HISTORY_STATE;
+.EE
 .fi
 .PP
 If the flags member includes \fBHS_STIFLED\fP, the history has been
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 04/13] lib/readline/doc/history.3: Replace blank lines with macro calls.

[G. Branden Robinson]

When formatting for typesetters, a blank input line produces 1 vee (one
line height, basically) of vertical space, but the default
inter-paragraph distance in man(7) is 0.4v.

Fixes numerous style warnings from "nroff -rCHECKSTYLE=3 -man" in groff
1.23.0 of the following form.

an.tmac:lib/readline/doc/history.3:xxx: style: blank line in input
---
 lib/readline/doc/history.3 | 93 +++---
 1 file changed, 46 insertions(+), 47 deletions(-)

diff --git a/lib/readline/doc/history.3 b/lib/readline/doc/history.3
index 266d91f6..76703833 100644
--- a/lib/readline/doc/history.3
+++ b/lib/readline/doc/history.3
@@ -393,89 +393,89 @@ .SS Initializing History and State Management
 This section describes functions used to initialize and manage
 the state of the History library when you want to use the history
 functions in your program.
-
+.PP
 .F1 void using_history void
 Begin a session in which the history functions might be used.  This
 initializes the interactive variables.
-
+.PP
 .F1 "HISTORY_STATE *" history_get_history_state void
 Return a structure describing the current state of the input history.
-
+.PP
 .F1 void history_set_history_state "HISTORY_STATE *state"
 Set the state of the history list according to \fIstate\fP.
 .SS History List Management
 These functions manage individual entries on the history list, or set
 parameters managing the list itself.
-
+.PP
 .F1 void add_history "const char *string"
 Place \fIstring\fP at the end of the history list.  The associated data
 field (if any) is set to \fBNULL\fP.
 If the maximum number of history entries has been set using
 \fBstifle_history()\fP, and the new number of history entries would exceed
 that maximum, the oldest history entry is removed.
-
+.PP
 .F1 void add_history_time "const char *string"
 Change the time stamp associated with the most recent history entry to
 \fIstring\fP.
-
+.PP
 .F1 "HIST_ENTRY *" remove_history "int which"
 Remove history entry at offset \fIwhich\fP from the history.  The
 removed element is returned so you can free the line, data,
 and containing structure.
-
+.PP
 .F1 "histdata_t" free_history_entry "HIST_ENTRY *histent"
 Free the history entry \fIhistent\fP and any history library private
 data associated with it.  Returns the application-specific data
 so the caller can dispose of it.
-
+.PP
 .F3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" 
"histdata_t data"
 Make the history entry at offset \fIwhich\fP have \fIline\fP and \fIdata\fP.
 This returns the old entry so the caller can dispose of any
 application-specific data.  In the case
 of an invalid \fIwhich\fP, a \fBNULL\fP pointer is returned.
-
+.PP
 .F1 void clear_history "void"
 Clear the history list by deleting all the entries.
-
+.PP
 .F1 void stifle_history "int max"
 Stifle the history list, remembering only the last \fImax\fP entries.
 The history list will contain only \fImax\fP entries at a time.
-
+.PP
 .F1 int unstifle_history "void"
 Stop stifling the history.  This returns the previously-set
 maximum number of history entries (as set by \fBstifle_history()\fP).
 history was stifled.  The value is positive if the history was
 stifled, negative if it wasn't.
-
+.PP
 .F1 int history_is_stifled "void"
 Returns non-zero if the history is stifled, zero if it is not.
 .SS Information About the History List
 These functions return information about the entire history list or
 individual list entries.
-
+.PP
 .F1 "HIST_ENTRY **" history_list "void"
 Return a \fBNULL\fP terminated array of \fIHIST_ENTRY *\fP which is the
 current input history.  Element 0 of this list is the beginning of time.
 If there is no history, return \fBNULL\fP.
-
+.PP
 .F1 int where_history "void"
 Returns the offset of the current history element.
-
+.PP
 .F1 "HIST_ENTRY *" current_history "void"
 Return the history entry at the current position, as determined by
 \fBwhere_history()\fP.  If there is no entry there, return a \fBNULL\fP
 pointer.
-
+.PP
 .F1 "HIST_ENTRY *" history_get "int offset"
 Return the history entry at position \fIoffset\fP.
 The range of valid values of \fIoffset\fP starts at \fBhistory_base\fP
 and ends at \fBhistory_length\fP \- 1.
 If there is no entry there, or if \fIoffset\fP is outside the valid
 range, return a \fBNULL\fP pointer.
-
+.PP
 .F1 "time_t" history_get_time "HIST_ENTRY *"
 Return the time stamp associated with the history entry passed as the argument.
-
+.PP
 .F1 int history_total_bytes "void"
 Return the number of bytes that the primary history entries are using.
 This function returns the sum of the lengths of all the lines in the
@@ -483,18 +483,18 @@ .SS Information About the History List
 .SS Moving Around the History List
 These functions allow the current index into the history list to be
 set or changed.
-
+.PP
 .F1 int history_set_pos "int pos"
 Set the current history offset to \fIpos\fP, an absolute index
 into the list.
 Returns 1 on success, 0 if \fIpos\fP is less than zero or

[PATCH 08/13] lib/readline/doc/history.3: Fix font thinko.

[G. Branden Robinson]

Replace no-op font selection escape sequence with what appears to have
been intended.
---
 lib/readline/doc/history.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/readline/doc/history.3 b/lib/readline/doc/history.3
index 40b85b20..7b6ab73b 100644
--- a/lib/readline/doc/history.3
+++ b/lib/readline/doc/history.3
@@ -728,7 +728,7 @@ .SH BUG REPORTS
 bug report to \fIbug\-readline\fP@\fIgnu.org\fP.
 If you have a fix, you are welcome to mail that
 as well!  Suggestions and `philosophical' bug reports may be mailed
-to \fPbug\-readline\fP@\fIgnu.org\fP or posted to the Usenet
+to \fIbug\-readline\fP@\fIgnu.org\fP or posted to the Usenet
 newsgroup
 .BR gnu.bash.bug .
 .PP
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 05/13] lib/readline/doc/history.3: Fix style minutia.

[G. Branden Robinson]

Set a period in the intended face (roman, not bold).

Stop breaking a line in the middle of a sentence without motivation.

Diff of rendering:

(groff Git, 1.23.0, 1.22.4; mandoc; Heirloom Doctools nroff)
- G  Apply the following “s”
- or “&” modifier once to each word in the event line.
+ G  Apply the following “s” or “&” modifier once to each word in the
+event line.

Fixes (from "nroff -rCHECKSTYLE=3 -man" using groff 1.23.0):
an.tmac:lib/readline/doc/history.3:73: style: .BR expects at least 2 arguments, 
got 1
an.tmac:lib/readline/doc/history.3:320: style: 1 leading space(s) on input line
---
 lib/readline/doc/history.3 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/readline/doc/history.3 b/lib/readline/doc/history.3
index 76703833..56d910cd 100644
--- a/lib/readline/doc/history.3
+++ b/lib/readline/doc/history.3
@@ -70,7 +70,7 @@ .SH DESCRIPTION
 .SH "HISTORY EXPANSION"
 The history library supports a history expansion feature that
 is identical to the history expansion in
-.BR bash.
+.BR bash .
 This section describes what syntax features are available.
 .PP
 History expansions introduce words from the history list into
@@ -317,7 +317,7 @@ .SS Modifiers
 .B G
 Apply the following
 .Q \fBs\fP
- or
+or
 .Q \fB&\fP
 modifier once to each word in the event line.
 .PD
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 06/13] lib/readline/doc/history.3: Drop microtypography.

[G. Branden Robinson]

Now that we're using a correct caret/circumflex/hat glyph on
modern typesetters (and terminals with a Unicode repertoire), drop the
thicket of partial-line motion and type size-altering escape sequences,
certain to frighten and confuse any unfrozen caveman page authors.

I expect this to slightly regress the quality of output on AT&T nroff
and troff (DWB and Solaris 10) when sending output to a line printer or
other device capable of half-line motions, and to typesetters.

The dropped escape sequences have never had effect on character-cell
video terminals.
---
 lib/readline/doc/history.3 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/readline/doc/history.3 b/lib/readline/doc/history.3
index 56d910cd..30b4d7be 100644
--- a/lib/readline/doc/history.3
+++ b/lib/readline/doc/history.3
@@ -150,13 +150,13 @@ .SS Event Designators
 If \fIstring\fP is missing, the string from the most recent search is used;
 it is an error if there is no previous search string.
 .TP
-.B \d\s+2\*^\s-2\u\fIstring1\fP\d\s+2\*^\s-2\u\fIstring2\fP\d\s+2\*^\s-2\u
+.B \*^\fIstring1\fP\*^\fIstring2\fP\*^
 Quick substitution.  Repeat the last command, replacing
 .I string1
 with
 .IR string2 .
 Equivalent to
-.Q !!:s\d\s+2\*^\s-2\u\fIstring1\fP\d\s+2\*^\s-2\u\fIstring2\fP\d\s+2\*^\s-2\u
+.Q !!:s\*^\fIstring1\fP\*^\fIstring2\fP\*^
 (see \fBModifiers\fP below).
 .TP
 .B !#
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 01/13] lib/readline/doc/history.3: Fix failure to render on DWB and Solaris 10 troff.

[G. Branden Robinson]

The following syntax is killing the page on AT&T troff.  You get the
header and footer and nothing else--just an ocean of blank space.

.de Fn1

With traditional roff eyeballs, this is interpreted the same as this:

.deFn1

or:

.de Fn 1

...which may at last make the problem clear.  Identifiers are only two
characters maximum in AT&T roff.  Because a macro named `1` was never
subsequently called, the entire remainder of the page got scooped into a
never-ending macro definition and would not render.
---
 lib/readline/doc/history.3 | 74 +++---
 1 file changed, 37 insertions(+), 37 deletions(-)

diff --git a/lib/readline/doc/history.3 b/lib/readline/doc/history.3
index 7a760019..4f1af5fe 100644
--- a/lib/readline/doc/history.3
+++ b/lib/readline/doc/history.3
@@ -38,17 +38,17 @@
 ..
 .ds lp \fR\|(\fP
 .ds rp \fR\|)\fP
-.\" FnN return-value fun-name N arguments
-.de Fn1
+.\" Fn return-value fun-name n arguments
+.de F1
 \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3\fP\\*(rp
 .br
 ..
-.de Fn2
+.de F2
 .if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4\fP\\*(rp
 .if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4\fP\\*(rp
 .br
 ..
-.de Fn3
+.de F3
 .if t \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3,\|\\$4,\|\\$5\fP\|\\*(rp
 .if n \fI\\$1\fP \fB\\$2\fP \\*(lp\fI\\$3, \\$4, \\$5\fP\\*(rp
 .br
@@ -395,61 +395,61 @@ .SS Initializing History and State Management
 the state of the History library when you want to use the history
 functions in your program.
 
-.Fn1 void using_history void
+.F1 void using_history void
 Begin a session in which the history functions might be used.  This
 initializes the interactive variables.
 
-.Fn1 "HISTORY_STATE *" history_get_history_state void
+.F1 "HISTORY_STATE *" history_get_history_state void
 Return a structure describing the current state of the input history.
 
-.Fn1 void history_set_history_state "HISTORY_STATE *state"
+.F1 void history_set_history_state "HISTORY_STATE *state"
 Set the state of the history list according to \fIstate\fP.
 
 .SS History List Management
 These functions manage individual entries on the history list, or set
 parameters managing the list itself.
 
-.Fn1 void add_history "const char *string"
+.F1 void add_history "const char *string"
 Place \fIstring\fP at the end of the history list.  The associated data
 field (if any) is set to \fBNULL\fP.
 If the maximum number of history entries has been set using
 \fBstifle_history()\fP, and the new number of history entries would exceed
 that maximum, the oldest history entry is removed.
 
-.Fn1 void add_history_time "const char *string"
+.F1 void add_history_time "const char *string"
 Change the time stamp associated with the most recent history entry to
 \fIstring\fP.
 
-.Fn1 "HIST_ENTRY *" remove_history "int which"
+.F1 "HIST_ENTRY *" remove_history "int which"
 Remove history entry at offset \fIwhich\fP from the history.  The
 removed element is returned so you can free the line, data,
 and containing structure.
 
-.Fn1 "histdata_t" free_history_entry "HIST_ENTRY *histent"
+.F1 "histdata_t" free_history_entry "HIST_ENTRY *histent"
 Free the history entry \fIhistent\fP and any history library private
 data associated with it.  Returns the application-specific data
 so the caller can dispose of it.
 
-.Fn3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" 
"histdata_t data"
+.F3 "HIST_ENTRY *" replace_history_entry "int which" "const char *line" 
"histdata_t data"
 Make the history entry at offset \fIwhich\fP have \fIline\fP and \fIdata\fP.
 This returns the old entry so the caller can dispose of any
 application-specific data.  In the case
 of an invalid \fIwhich\fP, a \fBNULL\fP pointer is returned.
 
-.Fn1 void clear_history "void"
+.F1 void clear_history "void"
 Clear the history list by deleting all the entries.
 
-.Fn1 void stifle_history "int max"
+.F1 void stifle_history "int max"
 Stifle the history list, remembering only the last \fImax\fP entries.
 The history list will contain only \fImax\fP entries at a time.
 
-.Fn1 int unstifle_history "void"
+.F1 int unstifle_history "void"
 Stop stifling the history.  This returns the previously-set
 maximum number of history entries (as set by \fBstifle_history()\fP).
 history was stifled.  The value is positive if the history was
 stifled, negative if it wasn't.
 
-.Fn1 int history_is_stifled "void"
+.F1 int history_is_stifled "void"
 Returns non-zero if the history is stifled, zero if it is not.
 
 .SS Information About the History List
@@ -457,30 +457,30 @@ .SS Information About the History List
 These functions return information about the entire history list or
 individual list entries.
 
-.Fn1 "HIST_ENTRY **" history_list "void"
+.F1 "HIST_ENTRY **" history_list "void"
 Return a \fBNULL\fP terminated array of \fIHIST_ENTRY *\fP which is the
 current input history.  Element 0 of this list is the beginning of time.
 If there is no history, return \fBNULL\fP.
 
-.Fn1 int where_history "void"
+.F1 int where_history "void"
 Re

[PATCH 03/13] lib/readline/doc/history.3: Drop spacing around (sub)section headings.

[G. Branden Robinson]

When formatting for typesetters, a blank input line produces 1 vee (one
line height, basically) of vertical space, but the default
inter-paragraph distance in man(7) is 0.4v.  Second, the package always
puts inter-paragraph spacing before a (sub)section heading anyway.
Third, forcing vertical space after a (sub)section heading is
nonidiomatic.

Fixes numerous style warnings from "nroff -rCHECKSTYLE=3 -man" in groff
1.23.0 of the following form.

an.tmac:lib/readline/doc/history.3:xxx: style: blank line in input
---
 lib/readline/doc/history.3 | 13 -
 1 file changed, 13 deletions(-)

diff --git a/lib/readline/doc/history.3 b/lib/readline/doc/history.3
index 4f1af5fe..266d91f6 100644
--- a/lib/readline/doc/history.3
+++ b/lib/readline/doc/history.3
@@ -67,7 +67,6 @@ .SH DESCRIPTION
 History library is able to keep track of those lines, associate arbitrary
 data with each line, and utilize information from previous lines in
 composing new ones.
-.PP
 .SH "HISTORY EXPANSION"
 The history library supports a history expansion feature that
 is identical to the history expansion in
@@ -404,7 +403,6 @@ .SS Initializing History and State Management
 
 .F1 void history_set_history_state "HISTORY_STATE *state"
 Set the state of the history list according to \fIstate\fP.
-
 .SS History List Management
 These functions manage individual entries on the history list, or set
 parameters managing the list itself.
@@ -451,9 +449,7 @@ .SS History List Management
 
 .F1 int history_is_stifled "void"
 Returns non-zero if the history is stifled, zero if it is not.
-
 .SS Information About the History List
-
 These functions return information about the entire history list or
 individual list entries.
 
@@ -484,9 +480,7 @@ .SS Information About the History List
 Return the number of bytes that the primary history entries are using.
 This function returns the sum of the lengths of all the lines in the
 history.
-
 .SS Moving Around the History List
-
 These functions allow the current index into the history list to be
 set or changed.
 
@@ -507,9 +501,7 @@ .SS Moving Around the History List
 If the possibly-incremented history offset refers to a valid history
 entry, return a pointer to that entry;
 otherwise, return a \fBNULL\fP pointer.
-
 .SS Searching the History List
-
 These functions allow searching of the history list for entries containing
 a specific string.  Searching may be performed both forward and backward
 from the current history position.  The search may be \fIanchored\fP,
@@ -539,7 +531,6 @@ .SS Searching the History List
 absolute index into the list.  If \fIdirection\fP is negative, the search
 proceeds backward from \fIpos\fP, otherwise forward.  Returns the absolute
 index of the history element where \fIstring\fP was found, or -1 otherwise.
-
 .SS Managing the History File
 The History library can read the history from and write it to a file.
 This section documents the functions for managing a history file.
@@ -574,9 +565,7 @@ .SS Managing the History File
 \fInlines\fP lines.
 If \fIfilename\fP is \fBNULL\fP, then \fI\*~/.history\fP is truncated.
 Returns 0 on success, or \fBerrno\fP on failure.
-
 .SS History Expansion
-
 These functions implement history expansion.
 
 .F2 int history_expand "const char *string" "char **output"
@@ -623,9 +612,7 @@ .SS History Expansion
 Extract a string segment consisting of the \fIfirst\fP through \fIlast\fP
 arguments present in \fIstring\fP.  Arguments are split using
 \fBhistory_tokenize()\fP.
-
 .SS History Variables
-
 This section describes the externally-visible variables exported by
 the GNU History Library.
 
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 02/13] doc/bash.1: Fix groff man(7) style warnings.

[G. Branden Robinson]

Diff of rendering (ignoring differences in character set, default line
length, and a font selection affecting only a period):

(groff Git, 1.23.0, 1.22.4; mandoc; Heirloom Doctools nroff; DWB nroff)

- expansion, word splitting, pathname expansion, and quote removal .
+ expansion, word splitting, pathname expansion, and quote removal.

Fixes style warnings from groff 1.23.0 "nroff -rCHECKSTYLE=3 -man":
an.tmac:./doc/bash.1:3033: style: .IR expects at least 2 arguments, got 1
an.tmac:./doc/bash.1:6302: style: .BR expects at least 2 arguments, got 1
an.tmac:./doc/bash.1:6454: style: .BR expects at least 2 arguments, got 1
---
 doc/bash.1 | 9 ++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 65bd81ce..c3253b09 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -3030,7 +3030,7 @@ .SH EXPANSION
 .IR "word splitting" ,
 .IR "pathname expansion" ,
 and
-.IR "quote removal .
+.IR "quote removal" .
 .PP
 The order of expansions is:
 brace expansion;
@@ -6299,7 +6299,7 @@ .SS "Readline Variables"
 .\" finesse.  We require `\c`, and while the single-font macros don't
 .\" honor input trap continuation, the font alternation macros do.
 .TP
-.BR comment\-begin\ (\c
+.BR comment\-begin\ ( \c
 .Q \fB#\fP \fB)\fP
 The string that is inserted when the readline
 .B insert\-comment
@@ -6450,8 +6450,11 @@ .SS "Readline Variables"
 locale contains eight-bit characters.
 This variable is dependent on the \fBLC_CTYPE\fP locale category, and
 may change if the locale is changed.
+.\" Tucking multiple macro calls into a paragraph tag requires some
+.\" finesse.  We require `\c`, and while the single-font macros don't
+.\" honor input trap continuation, the font alternation macros do.
 .TP
-.BR isearch\-terminators\ (\c
+.BR isearch\-terminators\ ( \c
 .Q \fBC\-[C\-J\fP \fB)\fP
 The string of characters that should terminate an incremental
 search without subsequently executing the character as a command.
-- 
2.30.2



signature.asc
Description: PGP signature

Re: Debian bug #929178: wrong trap displayed inside functions

[G. Branden Robinson]

At 2024-03-25T21:05:02+0300, Oğuz wrote:
> On Mon, Mar 25, 2024 at 8:38 PM G. Branden Robinson
>  wrote:
> > [1]
> > [1] http...
> 
> I keep seeing this. Why don't you guys just paste the link?

I believe I am.

https://lists.gnu.org/archive/html/bug-bash/2024-03/msg00207.html

And if that gets munched too...

https:
lists.gnu.org
archive
html
bug-bash
2024-03
msg00207.html

Reconstruct with appropriately placed slashes.

Maybe your MUA or other email provider is, uh, "protecting" you.

(Granted, that link I shared earlier should be handled with lead-lined
gloves.  It's entirely _too_ safe for work.)

Regards,
Branden


signature.asc
Description: PGP signature

Re: Debian bug #929178: wrong trap displayed inside functions

[G. Branden Robinson]

At 2024-03-25T19:13:39+0200, Oğuz wrote:
> On Mon, Mar 25, 2024 at 7:18 PM Gioele Barabucci  wrote:
> > Just for reference, neither dash nor busybox sh preserve the
> > caller's trap:
> 
> I don't know why you think they are relevant. dash doesn't even support
> `x=$(trap)', which is mandated by POSIX to work;

It would seem to be relevant to its _maintainers_...

dash(1):

DESCRIPTION
 dash is the standard command interpreter for the system.  The
 current version of dash is in the process of being changed to
 conform with the POSIX 1003.2 and 1003.2a specifications for the
 shell.

Maybe they would accept patches for better conformance.

> and busybox sh is a bare-bones shell for small, embedded systems.

True, but if you want a shell for embedded systems with a real luster to
it, you've gotta grab Toybox, which, whatever its technical merits (or
lack thereof), glistens with 0BSD true freedom.  We can't be tying the
hands of America's entreprenurial innovators, like whoever's running
Google these days, with worries about liability for copyright
infrigement--not while they have intellectual property rights that they
vigorously safeguard from the chiseling proles, parasites one and all.

Remember, Big Business is America's most persecuted minority.[1]

Regards,
Branden

[1] https://courses.aynrand.org/works/americas-persecuted-minority-big-business/


signature.asc
Description: PGP signature

Re: Rendering the Bash man page with commercial Unix/System V nroff

[G. Branden Robinson]

[self-follow-up]

At 2024-02-12T13:00:43-0600, G. Branden Robinson wrote:
> I'm also attaching a sample document that people can use to test the
> nroff(1)/man(7) on their system.

If I had a nickel for every time I forget the attachment...

> Here's how I tested it with groff, mandoc(1), Heirloom Doctools, and
> DWB 3.3.  The location of your installed groff will likely differ.
> 
> $ ~/groff-stable/bin/nroff -t -man manexercise.man
> $ mandoc manexercise.man | ul
> $ ./bin/tbl manexercise.man | ./bin/nroff  -man | ul
> $ DWBHOME=. ./bin/tbl manexercise.man | DWBHOME=. ./bin/nroff  -man | ul
> 
> (The pipe through ul(1) is necessary with non-GNU nroffs to convert the
> output from Model 37-oriented overstriking sequences to the escape
> sequences suitable to produce varying font styles on the terminal.  AT&T
> nroff preceded termcap and terminfo by several years and as far as I
> know, no one ever migrated it to use either one, even long after
> teletypewriters were abandoned as terminal devices.  If your system
> doesn't have ul(1), use col(1).)

Regards,
Branden


manexercise.man
Description: manexercise.man


signature.asc
Description: PGP signature

Re: Rendering the Bash man page with commercial Unix/System V nroff

[G. Branden Robinson]

Hi Chet,

At 2024-02-12T14:45:30-0500, Chet Ramey wrote:
> On 2/12/24 2:00 PM, G. Branden Robinson wrote:
> > I see that most of my proposed man page changes from the recent
> > series landed in the devel branch.  Thanks!
> > 
> > I did notice that this one and its follow-up did not.  Was that on
> > purpose?  Is there something I can do to improve the patch?
> 
> I just ran out of steam.

Oh!  That possibility had not occurred to me.  :-O

> > The reason I submitted 17/18 and 18/18 is because, out of the box,
> > Solaris 10 nroff won't render the special characters \(ha and \(ti,
> > which does some violence to the Bash man page.[1]
> 
> I wonder if there's a way to make Solaris use the pre-formatted
> nroffed versions of the man pages that are in the bash distribution.

In theory, maybe.  (These are historically called "cat pages", because
you can cat(1) them and not get a face full of *roff syntax.)  But...

1.  The Solaris 10 system to which I have access (via the FSF France's
compiler farm) seems to be configured to not use /usr/share/man/cat*
directories.  Not for the _system_ (more on this later).

2.  /opt/csw/share/man/man1 seems to have a more modern Bash man page in
it, 4.3.  That's good.  But no /opt/csw/share/man/cat* directories
are present, either.

3.  They don't appear to be part of the relevant Solaris packages.

  $ egrep 'bash\.[0-9]+' /var/sadm/install/contents
  /opt/csw/share/man/man1/bash.1 f none 0644 root bin 299110 17440 
1424016035 CSWbash
  /usr/share/man/man1/bash.1 f none 0444 root bin 250091 11343 1344856607 
SUNWsfman
  /usr/share/man/man1/rbash.1 f none 0444 root bin 612 48562 1344856608 
SUNWsfman

I therefore don't think you're going to have any luck unless you can (1)
get Solaris 10 to restore(?) support for cat pages; (2) get whoever's in
charge of preparing Solaris packages to rebuild Bash's packages to
include the cat page; and (3) convince the people involved in (2) to do
this for a system that is on the ragged, unraveling telomere of support.

Maybe (1) isn't an issue.  Maybe there's a system-configgy option that
enables cat pages.  And maybe package installation payloads are filtered
by it, taking care of (2).  That leaves barrier (3).

But if you're only concerned about people doing their own builds of Bash
from source, I think the answer is yes!

I scp'ed the doc/bash.{1,0} files from my Git checkout of the Bash devel
branch to the Solaris 10 host, placing them in $HOME/share/man/man1 and
$HOME/share/man/cat1, respectively.

$ man -M $HOME/share/man bash

(equivalently,

MANPATH=$HOME/share/man man bash
)

...worked fine, taking noticeable time to render and showing me a Bash
5.3 page.

Running it again rendered much faster.  I looked, and the system man(1)
apparently ran catman(1) for me.

Unfortunately that means it wasn't the pre-formatted version, but one
rendered by rotten old Solaris 10 nroff.

$ man -M ./share/man bash | grep '<<='
 = *= /= %= += -= <<= >>= &= = |=

--- should be ~= ^

So I clobbered it.

$ cp $HOME/share/man/cat1/bash.0 $HOME/share/man/cat1/bash.1

Lo and behold, I get a good result--complete with working boldface, not
just italics^Wunderlining.[1]

The ~= shows up correctly, but I can't illustrate that with an obvious
grep because the overstriking sequences defeat my simple pattern.

Unfortunately (depending on how you look at it), touch(1)ing the bash.1
source document provokes catman(1) into replacing the pre-rendered page.

So I guess what you might want to do is have the installation procedure
on Solaris 10 install bash.0 as $DESTDIR/share/man/cat1/bash.1.  (I
haven't looked into Bash's build process at all.)

Does this help, or influence your appetite for maximal portability vs.
sending a bouquet to the funeral service I'm holding for System V troff?

Regards,
Branden

[1] I can't account for why DWB 3.3 nroff, a fairly close relative of
Solaris 10 troff, (correctly) overstrikes characters with themselves
to produce bold when rendering for a Teletype Model 37, while
Solaris 10 troff does not.  Nor do I mean to look into it.  But I do
find it a pretty ironic defect given the depth of SunOS 4.0's
commitment to expanded use of boldface in man pages.[2]  But I
remember that front in the Unix wars.  Many champions of SunOS 4
viewed Solaris with the deepest contempt.  I guess this aspect of
Kernighan *roff simply fell off of Solaris and no one put it back.

[2] https://lists.gnu.org/archive/html/groff/2023-08/msg5.html
https://lists.gnu.org/archive/html/groff-commit/2023-08/msg00030.html


signature.asc
Description: PGP signature

Rendering the Bash man page with commercial Unix/System V nroff (was: [PATCH 17/18] doc/bash.1: migrate to strings for troublesome characters)

[G. Branden Robinson]

Hi Chet,

I see that most of my proposed man page changes from the recent series
landed in the devel branch.  Thanks!

I did notice that this one and its follow-up did not.  Was that on
purpose?  Is there something I can do to improve the patch?

The reason I submitted 17/18 and 18/18 is because, out of the box,
Solaris 10 nroff won't render the special characters \(ha and \(ti,
which does some violence to the Bash man page.[1]

Here are two examples.

At 2024-01-31T02:43:45-0600, G. Branden Robinson wrote:
> Diff of rendering (DWB):
[...]
> - An additional binary operator, =, is available, with
> + An additional binary operator, =~, is available, with
> 
> - string.  Anchor the pattern using the  and $ regular
> + string.  Anchor the pattern using the ^ and $ regular

The fix for DWB 3.3 is really straightforward.

$ diff -u lib/nterm/tab.man{,.new}
--- lib/nterm/tab.man   2024-02-12 05:30:56.265300808 -0600
+++ lib/nterm/tab.man.new   2024-02-12 11:53:28.357145394 -0600
@@ -26,6 +26,8 @@
 left   ""

 charset
+ha 1 ^
+ti 1 ~
 em 1 -
 hy 1 -
 \- 1 -

I just now tested this on a real Solaris 10 host, and as expected, it is
consistent with Documenter's Workbench (DWB) 3.3 behavior.  Solaris 10
troff seems to still default its nroff output to the Teletype Model
37.[2]  So one could do the same thing for the "tab.37" file in
/usr/share/lib/nterm.

$ diff -u tab.37*
--- tab.37  Mon Feb 12 19:07:35 2024
+++ tab.37.new  Mon Feb 12 19:07:58 2024
@@ -26,6 +26,8 @@
 left   ""

 charset
+ha 1 ^
+ti 1 ~
 em 1 -
 hy 1 -
 \- 1 -

But I admit I wasn't able to actually test this since I don't have root
privileges on the Solaris 10 host I'm using, and AT&T nroff doesn't
offer a way to point it at a user-specified set of driving tables.[3]

On the other hand, Solaris 10 troff is the only data point I have of a
deployed system still using a System V troff.  And I don't know if any
people using System V Unices care anymore about good man page rendering.

(As far as I know, the _only_ use case for DWB 3.3 troff, a System V
troff, is for retrocomputing and historical research.  It's invaluable
to me for the latter purpose.)

My plan had been to discontinue offering advice for man(7) document
portability to System V troffs like DWB and Solaris's once Oracle
finally EOBed Solaris 10, but they keep staying its execution.[4]
And maybe there is no point waiting for that day if that Solaris 10
lives only in lights-out environments where no one reads man pages.[5]

So maybe I should discontinue that sort of advice now instead of
waiting.  Chet, what would you prefer with respect to Bash?

So I'm looping in the groff list to try and get any users of such
systems to speak up.

I'm also attaching a sample document that people can use to test the
nroff(1)/man(7) on their system.

Here's how I tested it with groff, mandoc(1), Heirloom Doctools, and DWB
3.3.  The location of your installed groff will likely differ.

$ ~/groff-stable/bin/nroff -t -man manexercise.man
$ mandoc manexercise.man | ul
$ ./bin/tbl manexercise.man | ./bin/nroff  -man | ul
$ DWBHOME=. ./bin/tbl manexercise.man | DWBHOME=. ./bin/nroff  -man | ul

(The pipe through ul(1) is necessary with non-GNU nroffs to convert the
output from Model 37-oriented overstriking sequences to the escape
sequences suitable to produce varying font styles on the terminal.  AT&T
nroff preceded termcap and terminfo by several years and as far as I
know, no one ever migrated it to use either one, even long after
teletypewriters were abandoned as terminal devices.  If your system
doesn't have ul(1), use col(1).)

Anyway, Chet, let me know how much portability you'd like for Bash's man
pages in the next release and I'll do my best to assist.

Regards,
Branden

[1] The Bash available on Solaris 10 is 3.2; its man page uses the older
convention of employing ^ and ~ literally, which does _different_
violence to man page rendering for the presumably more numerous
users on other POSIX systems employing UTF-8-capable terminal
emulators, or those actually typesetting the manual.

[2] Per the following experiment.

.TH foo 1 2024-02-12 "groff test suite"
.SH Name
foo \- frobnicate a bar
.SH Description
We're rendering this page for device \*(.T.

And fair enough--that's consistent with Seventh Edition Unix, if
impressively un-useful for decades now.

[3] This is an old bit of terminology particular to AT&T troff/nroff.
https://www.ibm.com/docs/en/aix/7.2?topic=n-nroff-command

[4] 
https://blogs.oracle.com/solaris/post/new-end-date-of-extended-support-for-oracle-solaris-10-and-113
[5] Solaris 11 uses groff 1.22.3.


signature.asc
Description: PGP signature

[PATCH v2 04/18] doc/bash.1: improve typography of ellipses

[G. Branden Robinson]

v2: Prevent confclit with PATCH v2 01/18.

Apply ellipsis advice from groff_man_style(7).

 •  The dummy character escape sequence \& follows the ellipsis when
further text will follow after space on the output line, keeping
its last period from being interpreted as the end of a sentence
and causing additional inter‐sentence space to be placed after
it.  See subsection “Portability” below.
[...]
 \&Dummy character.  Insert at the beginning of an input
   line to prevent a dot or apostrophe from being
   interpreted as beginning a roff control line.  Append to
   an end‐of‐sentence punctuation sequence to keep it from
   being recognized as such.

 \|Thin space (one‐sixth em on typesetters, zero‐width on
   terminals); a non‐breaking space.  Used primarily in
   ellipses (“.\|.\|.”) to space the dots more pleasantly on
   typesetters like dvi, pdf, and ps.

Break some long input lines.

 \newline  Join the next input line to the current one.  Except for
   the update of the input line counter (used for diagnostic
   messages and related purposes), a series of lines ending
   in backslash‐newline appears to groff as a single input
   line.  Use this escape sequence to split excessively long
   input lines for document maintenance.

Set the ellipsis in roman instead of bold in the few cases where it
wasn't already.  As far as I can tell, it is never employed as a literal
in this man page.

Set some Bash literal syntax in bold, not roman, namely command
"$(( ))" and arithmetic "(( ))" substitutions.

Use \(dq special character escape sequence to smuggle a double quote
into paragraph tags that call macros.  (All the *roffs I have ready
access to [groff, Heirloom Doctools, DWB 3.3], plus mandoc(1) support
this special character, but Seventh Edition Unix troff does not, and a
grep of Solaris 10 troff suggests it doesn't either.  This man page
already uses `aq`, which is no _more_ portable than `dq`--DWB 3.3
supports `aq` on _fewer_ output devices, in fact.)
---
 doc/bash.1 | 132 +++--
 1 file changed, 78 insertions(+), 54 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 0f6192fc..5484e496 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -559,7 +559,8 @@ .SS Pipelines
 The format for a pipeline is:
 .RS
 .PP
-[\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP] 
\fIcommand2\fP ... ]
+[\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP]
+\fIcommand2\fP .\|.\|.\& ]
 .RE
 .PP
 The standard output of
@@ -857,7 +858,8 @@ .SS Compound Commands
 the entire conditional expression.
 .RE
 .TP
-\fBfor\fP \fIname\fP [ [ \fBin\fP [ \fIword ...\fP ] ] ; ] \fBdo\fP \fIlist\fP 
; \fBdone\fP
+\fBfor\fP \fIname\fP [ [ \fBin\fP [ \fIword .\|.\|.\&\fP ] ] ; ] \
+\fBdo\fP \fIlist\fP ; \fBdone\fP
 The list of words following \fBin\fP is expanded, generating a list
 of items.
 The variable \fIname\fP is set to each element of this list
@@ -919,8 +921,9 @@ .SS Compound Commands
 .IR list ,
 or zero if no commands were executed.
 .TP
-\fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \
-... ) \fIlist\fP ;; ] ... \fBesac\fP
+\fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP \
+[ \fB|\fP \fIpattern\fP ] .\|.\|.\& ) \fIlist\fP ;; ] .\|.\|.\& \
+\fBesac\fP
 A \fBcase\fP command first expands \fIword\fP, and tries to match
 it against each \fIpattern\fP in turn, using the matching rules
 described under
@@ -950,7 +953,7 @@ .SS Compound Commands
 last command executed in \fIlist\fP.
 .TP
 \fBif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; \
-[ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \
+[ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] .\|.\|.\& \
 [ \fBelse\fP \fIlist\fP; ] \fBfi\fP
 The
 .B if
@@ -1319,8 +1322,9 @@ .SH PARAMETERS
 .B integer
 attribute set, then
 .I value
-is evaluated as an arithmetic expression even if the $((...)) expansion is
-not used (see
+is evaluated as an arithmetic expression even if the
+.BR $(( .\|.\|.\& ))
+expansion is not used (see
 .B "Arithmetic Expansion"
 below).
 Word splitting and pathname expansion are not performed.
@@ -1427,7 +1431,7 @@ .SS Special Parameters
 .SM
 .B IFS
 special variable.  That is, "\fB$*\fP" is equivalent
-to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP", where
+to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP.\|.\|.", where
 .I c
 is the first character of the value of the
 .SM
@@ -1452,7 +1456,7 @@ .SS Special Parameters
 When the
 expansion occurs within double quotes, each parameter expands to a
 separate word.  That is, "\fB$@\fP" is equivalent to
-"\fB$1\fP"\ "\fB$2\fP"\ ...
+"\fB$1\fP"\ "\fB$2\fP"\ .\|.\|.
 If the double-quoted expansion occurs within a word, the expansion of
 the first parameter is joined with the beginning part of the original
 word, and the expansion of t

[PATCH v2 01/18] doc/bash.1: fix rendering error on old *roffs

[G. Branden Robinson]

Hi Chet,

Sorry--I need to update 2 of the items in this series.

v2: Fix a goof where I regressed the escaped hyphen in "self-insert".

The man(7) in Seventh Edition Unix (1979) accepted at most six arguments
to any macro.  Documenter's Workbench 3.3 troff retains this limitation,
as do at least some System V troffs that survive in commercial Unix
(such as Solaris 10 troff).

Quote the mulitiplicity of arguments so that they will appear.

Also simplify a similar case which was using the unadjustable space
escape sequence `\ ` to work around the same problem.  Since a paragraph
tag normally doesn't break or adjust anyway, the usage was mysterious.
Drop the backslashes and quote the tag as one big argument instead.

Diff of rendering (DWB):

 ||   logical OR
 expr?expr:expr
  conditional operator
-= *= /= %= += -=
+= *= /= %= += -= <<= >>= &= = |=
  assignment
 expr1 , expr2
  comma
---
 doc/bash.1 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index bd916b28..e218ae43 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -4860,7 +4860,7 @@ .SH "ARITHMETIC EVALUATION"
 .B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP
 conditional operator
 .TP
-.B = *= /= %= += \-= <<= >>= &= \(ha= |=
+.B "= *= /= %= += \-= <<= >>= &= \(ha= |="
 assignment
 .TP
 .B \fIexpr1\fP , \fIexpr2\fP
@@ -6902,7 +6902,7 @@ .SS Commands for Changing Text
 .B tab\-insert (C\-v TAB)
 Insert a tab character.
 .TP
-.B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...)
+.B "self\-insert (a, b, A, 1, !, ...)"
 Insert the character typed.
 .TP
 .B transpose\-chars (C\-t)
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 17/18] doc/bash.1: migrate to strings for troublesome characters

[G. Branden Robinson]

Diff of rendering (DWB):

- sonal initialization file /.bashrc if the shell is
+ sonal initialization file ~/.bashrc if the shell is

- files /.bash_profile, /.bash_login, or /.profile.  By
- default, bash reads these files when it is invoked as a
+ files ~/.bash_profile, ~/.bash_login, or ~/.profile.
+ By default, bash reads these files when it is invoked

- An additional binary operator, =, is available, with
+ An additional binary operator, =~, is available, with

- string.  Anchor the pattern using the  and $ regular
+ string.  Anchor the pattern using the ^ and $ regular

[many more occurrences]

Unfortunately (on DWB only)...

- parameter expands to a separate word.  That is, "$@" is
- equivalent to "$1" "$2" ...  If the double-quoted
- expansion occurs within a word, the expansion of the
- first parameter is joined with the beginning part of
- the original word, and the expansion of the last param-
- eter is joined with the last part of the original word.
- When there are no positional parameters, "$@" and $@
+ parameter expands to a separate word.  That is, $@ is
+ equivalent to $1  "$2" ...  If the double-quoted expan-
+ sion occurs within a word, the expansion of the first
+ parameter is joined with the beginning part of the
+ original word, and the expansion of the last parameter
+ is joined with the last part of the original word.
+ When there are no positional parameters, $@ and $@

-exceptions   to   this   are  the  expansions  of  "$@"  and
-"${name[@]}", and, in  most  cases,  $*  and  ${name[*]}  as
-explained above (see PARAMETERS).
+exceptions  to this are the expansions of $@ and ${name[@]},
+and, in most cases, $* and  ${name[*]}  as  explained  above
+(see PARAMETERS).

However, that is addressed by the next patch in this series.
---
 doc/bash.1 | 200 -
 1 file changed, 107 insertions(+), 93 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 61e9b758..2ee6c119 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -38,6 +38,20 @@
 .\" .el \\*(]X\h|\\n()Iu+\\n()Ru\c
 .\" .}f
 .\" ..
+.
+.ie \n(.g \{\
+.ds ' \(aq
+.ds " \(dq
+.ds ^ \(ha
+.ds ~ \(ti
+.\}
+.el \{\
+.ds ' '
+.ds " ""\" two adjacent quotes and no space before this comment
+.ds ^ ^
+.ds ~ ~
+.\}
+.
 .\"
 .\" File Name macro.  This used to be `.PN', for Path Name,
 .\" but Sun doesn't seem to like that very much.
@@ -213,7 +227,7 @@ .SH OPTIONS
 Execute commands from
 .I file
 instead of the standard personal initialization file
-.I \(ti/.bashrc
+.I \*~/.bashrc
 if the shell is interactive (see
 .SM
 .B INVOCATION
@@ -231,10 +245,10 @@ .SH OPTIONS
 Do not read either the system-wide startup file
 .FN /etc/profile
 or any of the personal initialization files
-.IR \(ti/.bash_profile ,
-.IR \(ti/.bash_login ,
+.IR \*~/.bash_profile ,
+.IR \*~/.bash_login ,
 or
-.IR \(ti/.profile .
+.IR \*~/.profile .
 By default,
 .B bash
 reads these files when it is invoked as a login shell (see
@@ -244,7 +258,7 @@ .SH OPTIONS
 .TP
 .B \-\-norc
 Do not read and execute the personal initialization file
-.I \(ti/.bashrc
+.I \*~/.bashrc
 if the shell is interactive.
 This option is on by default if the shell is invoked as
 .BR sh .
@@ -343,8 +357,8 @@ .SH INVOCATION
 with the \fB\-\-login\fP option, it first reads and
 executes commands from the file \fI/etc/profile\fP, if that
 file exists.
-After reading that file, it looks for \fI\(ti/.bash_profile\fP,
-\fI\(ti/.bash_login\fP, and \fI\(ti/.profile\fP, in that order, and reads
+After reading that file, it looks for \fI\*~/.bash_profile\fP,
+\fI\*~/.bash_login\fP, and \fI\*~/.profile\fP, in that order, and reads
 and executes commands from the first one that exists and is readable.
 The
 .B \-\-noprofile
@@ -353,18 +367,18 @@ .SH INVOCATION
 When an interactive login shell exits,
 or a non-interactive login shell executes the \fBexit\fP builtin command,
 .B bash
-reads and executes commands from the file \fI\(ti/.bash_logout\fP, if it
+reads and executes commands from the file \fI\*~/.bash_logout\fP, if it
 exists.
 .PP
 When an interactive shell that is not a login shell is started,
 .B bash
-reads and executes commands from \fI\(ti/.bashrc\fP, if that file exists.
+reads and executes commands from \fI\*~/.bashrc\fP, if that file exists.
 This may be inhibited by using the
 .B \-\-norc
 option.
 The \fB\-\-rcfile\fP \fIfile\fP option will force
 .B bash
-to read and execute commands from \fIfile\fP instead of \fI\(ti/.bashrc\fP.
+to read and execute commands from \fIfile\fP instead of \fI\*~/.bashr

[PATCH 16/18] doc/bash.1: fix latent formatting problem

[G. Branden Robinson]

Dialing up groff 1.23.0 man(7)'s "CHECKSTYLE" warning feature provoked
the following diagnostic.

an.tmac:doc/bash.1:8043: style: 1 leading space(s) on input line

Leading spaces are warned about because they cause the line to break,
which is often a surprise to man page authors when text is filled.

Here, it doesn't matter because this is a paragraph tag and a break has
just happened anyway.  The reason this is termed a leading space
nevertheless when there appears to be stuff preceding it on the line
demands explanation, and offers an illustrative example of why macro
package features should be preferred over formatter ones where possible.

groff's Texinfo manual explains:
 '\f' is not tokenized when GNU 'troff' reads its input; it instead
 updates the environment.

On historical troffs, the tokenization of whatever is at the beginning
of an input line is coupled with the bit of parser state that decides
whether it is "at the beginning of the line".  Therefore, on these
troffs, the formatter thinks it is still at the beginning of the input
line after it processes any number of `\f` escape sequences there (along
with `\s`, `\H`, `\S`, and groff's `\F`, `\m`, `\M`, and `\R`).[1]  This
isn't troff's greatest hit, which is why GNU troff doesn't couple these.
But it must be kept in mind for AT&T-compatible troffs.  (GNU troff's
"compatibility mode" respects this quirk, so it applies to groff
installations on Solaris 10/11, where the formatter is configured to
operate in compatibility mode by default.)

Here's the rendered result fix, with diff annotation:
-  .  filename [arguments]
+ .  filename [arguments]
  source filename [arguments]

[1] Now that I've enumerated these, forget you ever saw them for the
purpose of man page composition; they are either not portable or do
nothing on a terminal anyway.  Try to forget `\f`, too.  ;-)
---
 doc/bash.1 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/bash.1 b/doc/bash.1
index ec1f8ce1..61e9b758 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -8049,7 +8049,7 @@ .SH "SHELL BUILTIN COMMANDS"
 redirections.
 The return status is zero.
 .TP
-\fB .\| \fP \fIfilename\fP [\fIarguments\fP]
+\fB\&.\| \fP \fIfilename\fP [\fIarguments\fP]
 .PD 0
 .TP
 \fBsource\fP \fIfilename\fP [\fIarguments\fP]
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 18/18] doc/bash.1: work around limitation of AT&T troff

[G. Branden Robinson]

Diff of rendering (DWB):

- parameter expands to a separate word.  That is, $@ is
- equivalent to $1  "$2" ...  If the double-quoted expan-
- sion occurs within a word, the expansion of the first
- parameter is joined with the beginning part of the
- original word, and the expansion of the last parameter
- is joined with the last part of the original word.
- When there are no positional parameters, $@ and $@
+ parameter expands to a separate word.  That is, "$@" is
+ equivalent to "$1" "$2" ...  If the double-quoted
+ expansion occurs within a word, the expansion of the
+ first parameter is joined with the beginning part of
+ the original word, and the expansion of the last param-
+ eter is joined with the last part of the original word.
+ When there are no positional parameters, "$@" and $@

-exceptions  to this are the expansions of $@ and ${name[@]},
-and, in most cases, $* and  ${name[*]}  as  explained  above
-(see PARAMETERS).
+exceptions   to   this   are  the  expansions  of  "$@"  and
+"${name[@]}", and, in  most  cases,  $*  and  ${name[*]}  as
+explained above (see PARAMETERS).
---
 doc/bash.1 | 11 ++-
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 2ee6c119..2eb76d7c 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -1476,16 +1476,16 @@ .SS Special Parameters
 When the expansion occurs within double quotes,
 each parameter expands to a separate word.
 That is,
-.B \*"$@\*"
+.B \&\*"$@\*" \" keep leading \& for AT&T troff
 is equivalent to
-.B \*"$1\*"\ \*"$2\*"
+.B \&\*"\&$1\&\*"\ \*"$2\*" \" keep leading \& for AT&T troff
 \&.\|.\|.
 If the double-quoted expansion occurs within a word, the expansion of
 the first parameter is joined with the beginning part of the original
 word, and the expansion of the last parameter is joined with the last
 part of the original word.
 When there are no positional parameters,
-.B \*"$@\*"
+.B \&\*"$@\*" \" keep leading \& for AT&T troff
 and
 .B $@
 expand to nothing (i.e., they are removed).
@@ -3053,9 +3053,10 @@ .SH EXPANSION
 can increase the number of words of the expansion; other expansions
 expand a single word to a single word.
 The only exceptions to this are the expansions of
-.B \*"$@\*"
+.B \&\*"$@\*" \" keep leading \& for AT&T troff
 and
-.BR \*"${\fIname\fP[@]}\*" ,
+.B \&\*"${\fIname\fP[@]}\*"\c \" keep leading \& for AT&T troff
+.BR \& , \" .BR + \& + \*" doesn't work with AT&T troff
 and, in most cases, \fB$*\fP and \fB${\fP\fIname\fP\fB[*]}\fP
 as explained above (see
 .SM
-- 
2.30.2


signature.asc
Description: PGP signature

[PATCH 15/18] doc/bash.1: favor `TP` over `IP` for tagged paragraphs

[G. Branden Robinson]

In the forthcoming groff 1.24.0, I get the following bad rendering:

versionThe version test may be used to perform comparisons
   against specific readline  versions.   The  version

This is due to a pending change.

commit cba927a37a749cf912a183496002d8545d7619d5
Author: G. Branden Robinson 
Date:   Mon Nov 20 08:33:57 2023 -0600

[man]: Don't enforce tag separation on `IP`.

The tags to `IP` macros are often very short, as with bullets or list
enumerators (and in fact we encourage this practice in our style advice,
promoting `TP` for definition lists and similar).  We therefore don't
want to enforce the `TS` tag separation for them.  `.IP \[bu] 2n` is a
perfectly cromulent usage pattern.

* tmac/an.tmac: Add new Boolean-valued register,
  `an*enforce-tag-separation` to control this aspect of state.
  Initialize it true.
  (an-write-paragraph-tag): Multiply `TS` by this register to apply
  enforcement (or not).
  (IP): Temporarily clear register while setting paragraph.

* tmac/groff_man.7.man.in (Paragraphing macros, Options):
* NEWS: Update documentation.

(`IP` still won't let the tag and the text _overlap_, but they can abut,
as seen above.  This is potentially not objectionable when using
punctuation instead of words for tags; as noted, the `TP` macro is a
better fit for the latter.  `TP` is also more flexible, permitting macro
calls in the tag.)

Diff of rendering (groff Git):

-versionThe version test may be used to perform comparisons against
+version
+   The version test may be used to perform comparisons against

- $endif This command, as seen in the previous example, terminates an $if
+ $endif
+This command, as seen in the previous example, terminates an $if
 command.
---
 doc/bash.1 | 27 ++-
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 93855546..ec1f8ce1 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -6585,7 +6585,8 @@ .SS "Readline Conditional Constructs"
 compilation features of the C preprocessor which allows key
 bindings and variable settings to be performed as the result
 of tests.  There are four parser directives used.
-.IP \fB$if\fP
+.TP
+.B $if
 The
 .B $if
 construct allows bindings to be made based on the
@@ -6594,14 +6595,16 @@ .SS "Readline Conditional Constructs"
 extends to the end of the line;
 unless otherwise noted, no characters are required to isolate it.
 .RS
-.IP \fBmode\fP
+.TP
+.B mode
 The \fBmode=\fP form of the \fB$if\fP directive is used to test
 whether readline is in emacs or vi mode.
 This may be used in conjunction
 with the \fBset keymap\fP command, for instance, to set bindings in
 the \fIemacs\-standard\fP and \fIemacs\-ctlx\fP keymaps only if
 readline is starting out in emacs mode.
-.IP \fBterm\fP
+.TP
+.B term
 The \fBterm=\fP form may be used to include terminal-specific
 key bindings, perhaps to bind the key sequences output by the
 terminal's function keys.  The word on the right side of the
@@ -6614,7 +6617,8 @@ .SS "Readline Conditional Constructs"
 and
 .IR sun\-cmd ,
 for instance.
-.IP \fBversion\fP
+.TP
+.B version
 The \fBversion\fP test may be used to perform comparisons against
 specific readline versions.
 The \fBversion\fP expands to the current readline version.
@@ -6634,7 +6638,8 @@ .SS "Readline Conditional Constructs"
 is assumed to be \fB0\fP.
 The operator may be separated from the string \fBversion\fP
 and from the version number argument by whitespace.
-.IP \fBapplication\fP
+.TP
+.B application
 The \fBapplication\fP construct is used to include
 application-specific settings.  Each program using the readline
 library sets the \fIapplication name\fP, and an initialization
@@ -6653,7 +6658,8 @@ .SS "Readline Conditional Constructs"
 .fi
 .EE
 .RE
-.IP \fIvariable\fP
+.TP
+.I variable
 The \fIvariable\fP construct provides simple equality tests for readline
 variables and values.
 The permitted comparison operators are \fI=\fP, \fI==\fP, and \fI!=\fP.
@@ -6663,13 +6669,16 @@ .SS "Readline Conditional Constructs"
 Both string and boolean variables may be tested. Boolean variables must be
 tested against the values \fIon\fP and \fIoff\fP.
 .RE
-.IP \fB$endif\fP
+.TP
+.B $endif
 This command, as seen in the previous example, terminates an
 \fB$if\fP command.
-.IP \fB$else\fP
+.TP
+.B $else
 Commands in this branch of the \fB$if\fP directive are executed if
 the test fails.
-.IP \fB$include\fP
+.TP
+.B $include
 This directive takes a single filename as an argument and reads commands
 and bindings from that file.  For example, the following directive
 would read \fI/etc/inputrc\fP:
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 14/18] doc/bash.1: apply new `Q` quotation macro

[G. Branden Robinson]

Instead of variously using `this' and ``that'' quotation styles (mostly
the former), and which which render ugly on systems that hack up groff's
character mappings to force ` and ' to the grave accent (U+0060) and
neutral apostrophe (U+0027), respectively,[1] employ the new Q macro for
all (knock wood) quotation applications.

[1] For futher background (with a generous helping of opinion), see
.

Diff of rendering (groff):

- reserved word if the next token begins with a ‘-’.  The TIMEFORMAT 
variable
+ reserved word if the next token begins with a “-”.  The TIMEFORMAT 
variable

-character of the IFS special variable.  That is, "$*" is equivalent
-to "$1c$2c...", where c is the first character of the value of the
+character of the IFS special variable.  That is, “$*” is equivalent
+to “$1c$2c...”, where c is the first character of the value of the

-implicit ‘*’ is appended).  Each pattern is tested against the line
+implicit “*” is appended).  Each pattern is tested against the line

- comment-begin (‘‘#’’)
+ comment-begin (“#”)

- isearch-terminators (‘‘C-[C-J’’)
+ isearch-terminators (“C-[C-J”)

[many more occurrences like these]

Diff of rendering (mandoc):

-   recognize time as a reserved word if the next token begins with a `-'.
+   recognize time as a reserved word if the next token begins with a “-”.

-   comment-begin (``#'')
+   comment-begin (“#”)

[many more occurrences like these]

Diff of rendering (Heirloom Doctools, DWB):

-   recognize time as a reserved word if the next token begins with a `-'.
+   recognize time as a reserved word if the next token begins with a "-".

-   comment-begin (``#'')
-  The string that is inserted when the readline insert-comment
-  command is executed.  This command is bound to M-# in emacs mode
-  and to # in vi command mode.
+   comment-begin (
+  "#") The string that is inserted when the readline
+  insert-comment command is executed.  This command is bound to
+  M-# in emacs mode and to # in vi command mode.

[many more occurrences like these]

That break is unfortunate.  It's a long story.
https://lists.gnu.org/archive/html/groff/2022-06/msg00026.html
---
 doc/bash.1 | 222 +
 1 file changed, 156 insertions(+), 66 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 3854d561..93855546 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -598,7 +598,8 @@ .SS Pipelines
 terminates.
 The \fB\-p\fP option changes the output format to that specified by POSIX.
 When the shell is in \fIposix mode\fP, it does not recognize
-\fBtime\fP as a reserved word if the next token begins with a `\-'.
+\fBtime\fP as a reserved word if the next token begins with a
+.Q \- .
 The
 .SM
 .B TIMEFORMAT
@@ -1430,8 +1431,13 @@ .SS Special Parameters
 with the value of each parameter separated by the first character of the
 .SM
 .B IFS
-special variable.  That is, "\fB$*\fP" is equivalent
-to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP.\|.\|.", where
+special variable.
+That is,
+.Q \fB$*\fP
+is equivalent
+to
+.Q \fB$1\fP\fIc\fP\fB$2\fP\fIc\fP.\|.\|. ,
+where
 .I c
 is the first character of the value of the
 .SM
@@ -2396,14 +2402,18 @@ .SS Shell Variables
 A colon-separated list of patterns used to decide which command lines
 should be saved on the history list.  Each pattern is anchored at the
 beginning of the line and must match the complete line (no implicit
-`\fB*\fP' is appended).  Each pattern is tested against the line
-after the checks specified by
+.Q \fB*\fP
+is appended).
+Each pattern is tested against the line after the checks specified by
 .SM
 .B HISTCONTROL
 are applied.
-In addition to the normal shell pattern matching characters, `\fB&\fP'
-matches the previous history line.  `\fB&\fP' may be escaped using a
-backslash; the backslash is removed before attempting a match.
+In addition to the normal shell pattern matching characters,
+.Q \fB&\fP
+matches the previous history line.
+.Q \fB&\fP
+may be escaped using a backslash;
+the backslash is removed before attempting a match.
 The second and subsequent lines of a multi-line compound command are
 not tested, and are added to the history regardless of the value of
 .SM
@@ -2566,7 +2576,8 @@ .SS Shell Variables
 .B MAILPATH
 A colon-separated list of filenames to be checked for mail.
 The message to be printed when mail arrives in a particular file
-may be specified by separating the filename from the message with a `?'.
+may be specified by separating the filename from the message with a
+.Q ? .
 When used in the text of the message, \fB$_\fP expands to the name of
 the current mailfile.
 Example:
@@ -2798,18 +2809,23 @@ .SS Shell Variables
 .B HISTORY EXPANSION
 bel

[PATCH 13/18] doc/bash.1: bracket displayed examples with EX/EE

[G. Branden Robinson]

This will set them in Courier with modern formatters* when they render
to a typesetting device or to HTML, and does no damage on ancient ones.

Diff of rendering (groff, Heirloom Doctools, mandoc):

-MAILPATH='/var/mail/bfox?"You have mail":~/shell-mail?"$_ has
-mail!"'
+MAILPATH='/var/mail/bfox?"You have mail":~/shell-mail?"$_ has 
mail!"'

DWB adds vertical space, indents, and doesn't render the ~ characters.
A fix for the last comes later in this patch series.
---
 doc/bash.1 | 10 --
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 81c3153e..3854d561 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -2572,7 +2572,9 @@ .SS Shell Variables
 Example:
 .RS
 .PP
+.EX
 \fBMAILPATH\fP=\(aq/var/mail/bfox?\(dqYou have 
mail\(dq:\(ti/shell\-mail?\(dq$_ has mail!\(dq\(aq
+.EE
 .PP
 .B Bash
 can be configured to supply
@@ -6035,11 +6037,13 @@ .SS "Readline Key Bindings"
 are not recognized.
 .PP
 .RS
+.EX
+.nf
 \(dq\eC\-u\(dq: universal\-argument
-.br
 \(dq\eC\-x\eC\-r\(dq: re\-read\-init\-file
-.br
 \(dq\ee[11\(ti\(dq: \(dqFunction Key 1\(dq
+.fi
+.EE
 .RE
 .PP
 In this example,
@@ -6585,12 +6589,14 @@ .SS "Readline Conditional Constructs"
 key sequence that quotes the current or previous word in \fBbash\fP:
 .PP
 .RS
+.EX
 .nf
 \fB$if\fP Bash
 # Quote the current or previous word
 \(dq\eC\-xq\(dq: \(dq\eeb\e\(dq\eef\e\(dq\(dq
 \fB$endif\fP
 .fi
+.EE
 .RE
 .IP \fIvariable\fP
 The \fIvariable\fP construct provides simple equality tests for readline
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 12/18] doc/bash.1: fix unescaped hyphen

[G. Branden Robinson]

Diff of rendering (groff):

- reserved word if the next token begins with a ‘‐’.  The TIMEFORMAT 
variable
+ reserved word if the next token begins with a ‘-’.  The TIMEFORMAT 
variable
---
 doc/bash.1 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/bash.1 b/doc/bash.1
index ffbc97f4..81c3153e 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -598,7 +598,7 @@ .SS Pipelines
 terminates.
 The \fB\-p\fP option changes the output format to that specified by POSIX.
 When the shell is in \fIposix mode\fP, it does not recognize
-\fBtime\fP as a reserved word if the next token begins with a `-'.
+\fBtime\fP as a reserved word if the next token begins with a `\-'.
 The
 .SM
 .B TIMEFORMAT
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 11/18] doc/bash.1: drop unneeded quotes from macro args

[G. Branden Robinson]

A *roff macro argument need be quoted only if it contains spaces (and
spaces within escape sequences don't count; for Ossanna/Kernighan troff,
that codicil applies only to the unadjustable break escape sequence,
`\ `, which this document uses occasionally--`\~` is preferable but not
as portable).
---
 doc/bash.1 | 16 
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index e278c7c3..ffbc97f4 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -2253,7 +2253,7 @@ .SS Shell Variables
 .B EMACS
 If \fBbash\fP finds this variable in the environment when the shell starts
 with value
-.Q "t" ,
+.Q t ,
 it assumes that the shell is running in an Emacs shell buffer and disables
 line editing.
 .TP
@@ -2295,7 +2295,7 @@ .SS Shell Variables
 .B FIGNORE
 is excluded from the list of matched filenames.
 A sample value is
-.Q ".o:\(ti" .
+.Q .o:\(ti .
 .TP
 .B FUNCNEST
 If set to a numeric value greater than 0, defines a maximum function
@@ -2654,14 +2654,14 @@ .SS Shell Variables
 .SM
 .B PROMPTING
 below) and used as the primary prompt string.  The default value is
-.Q "\es\-\ev\e$\ " .
+.Q \es\-\ev\e$\  .
 .TP
 .B PS2
 The value of this parameter is expanded as with
 .SM
 .B PS1
 and used as the secondary prompt string.  The default is
-.Q ">\ " .
+.Q >\  .
 .TP
 .B PS3
 The value of this parameter is used as the prompt for the
@@ -2684,7 +2684,7 @@ .SS Shell Variables
 is replicated multiple times, as necessary, to indicate multiple
 levels of indirection.
 The default is
-.Q "+\ " .
+.Q +\  .
 .TP
 .B SHELL
 This variable expands to the full pathname to the shell.
@@ -5586,7 +5586,7 @@ .SH "JOB CONTROL"
 .Q "stty tostop" ,
 write to the terminal.
 Background processes which attempt to read from (write to when
-.Q "tostop"
+.Q tostop
 is in effect) the terminal are sent a
 .SM
 .B SIGTTIN (SIGTTOU)
@@ -6175,7 +6175,7 @@ .SS "Readline Variables"
 The default value is the string that puts the terminal in standout mode,
 as obtained from the terminal's terminfo description.
 A sample value might be
-.Q "\ee[01;33m" .
+.Q \ee[01;33m .
 .TP
 .B active\-region\-end\-color
 A string variable that
@@ -6191,7 +6191,7 @@ .SS "Readline Variables"
 The default value is the string that restores the terminal from standout mode,
 as obtained from the terminal's terminfo description.
 A sample value might be
-.Q "\ee[0m" .
+.Q \ee[0m .
 .TP
 .B bell\-style (audible)
 Controls what happens when readline wants to ring the terminal bell.
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 10/18] doc/bash.1: completely boldface inline literals

[G. Branden Robinson]

When discussing literals like
  "$@"
...boldface the double quotes too.
---
 doc/bash.1 | 15 ++-
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 200cf00e..e278c7c3 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -1453,15 +1453,20 @@ .SS Special Parameters
 In contexts where word splitting is not performed,
 this expands to a single word
 with each positional parameter separated by a space.
-When the
-expansion occurs within double quotes, each parameter expands to a
-separate word.  That is, \(dq\fB$@\fP\(dq is equivalent to
-\(dq\fB$1\fP\(dq\ \(dq\fB$2\fP\(dq\ .\|.\|.
+When the expansion occurs within double quotes,
+each parameter expands to a separate word.
+That is,
+.B \(dq$@\(dq
+is equivalent to
+.B \(dq$1\(dq\ \(dq$2\(dq
+\&.\|.\|.
 If the double-quoted expansion occurs within a word, the expansion of
 the first parameter is joined with the beginning part of the original
 word, and the expansion of the last parameter is joined with the last
 part of the original word.
-When there are no positional parameters, "\fB$@\fP" and
+When there are no positional parameters,
+.B \(dq$@\(dq
+and
 .B $@
 expand to nothing (i.e., they are removed).
 .TP
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 09/18] doc/bash.1: stop attempting literal ASCII ' use

[G. Branden Robinson]

Almost all other "literal" uses of the apostrophe were already migrated
to `\(aq` instead.

groff_man_style(7):
 ... Some escape sequences are however required for correct
 typesetting even in man pages and usually do not cause portability
 problems.

 Several of these render glyphs corresponding to punctuation code
 points in the Unicode basic Latin range (U+–U+007F) that are
 handled specially in roff input; the escape sequences below must be
 used to render them correctly and portably when documenting
 material that uses them as literals—namely, any of the set ' - \ ^
 ` ~ (apostrophe, dash or hyphen‐minus, backslash, caret, grave
 accent, tilde).

 \(aq   Basic Latin neutral apostrophe.  Some output devices format
“'” as a right single quotation mark.
---
 doc/bash.1 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/bash.1 b/doc/bash.1
index b666f63c..200cf00e 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -8054,7 +8054,8 @@ .SH "SHELL BUILTIN COMMANDS"
 initialization file such as
 .IR .inputrc ,
 but each binding or command must be passed as a separate argument;
-e.g., '\(dq\eC\-x\eC\-r\(dq: re\-read\-init\-file'.
+e.g.,
+\(aq\(dq\eC\-x\eC\-r\(dq: re\-read\-init\-file\(aq.
 In the following descriptions, output available to be re-read is formatted
 as commands that would appear in a
 .B readline
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 08/18] doc/bash.1: stop attempting literal ASCII " use

[G. Branden Robinson]

Migrate uses of the double quote (U+0022) as a literal to \(dq special
character escape sequence.  Generally these weren't _wrong_, but the man
page author then has to remember that they change their meaning when
they are placed inside macro arguments.

groff_man_style(7):
 ... Some escape sequences are however required for correct
 typesetting even in man pages and usually do not cause portability
 problems.

 \(dq   Basic Latin quotation mark (double quote).  Use in macro
calls to prevent ‘"’ from being interpreted as beginning a
quoted argument, or simply for readability.

   .TP
   .BI "split \(dq" text \(dq
---
 doc/bash.1 | 42 +-
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index f21aeb52..b666f63c 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -379,7 +379,7 @@ .SH INVOCATION
 .PP
 .RS
 .EX
-if [ \-n "$BASH_ENV" ]; then . "$BASH_ENV"; fi
+if [ \-n \(dq$BASH_ENV\(dq ]; then . \(dq$BASH_ENV\(dq; fi
 .EE
 .RE
 .PP
@@ -1159,7 +1159,7 @@ .SH QUOTING
 characters:
 .BR $ ,
 .BR \` ,
-\^\fB"\fP\^,
+\^\fB\(dq\fP\^,
 .BR \e ,
 or
 .BR  .
@@ -1455,8 +1455,8 @@ .SS Special Parameters
 with each positional parameter separated by a space.
 When the
 expansion occurs within double quotes, each parameter expands to a
-separate word.  That is, "\fB$@\fP" is equivalent to
-"\fB$1\fP"\ "\fB$2\fP"\ .\|.\|.
+separate word.  That is, \(dq\fB$@\fP\(dq is equivalent to
+\(dq\fB$1\fP\(dq\ \(dq\fB$2\fP\(dq\ .\|.\|.
 If the double-quoted expansion occurs within a word, the expansion of
 the first parameter is joined with the beginning part of the original
 word, and the expansion of the last parameter is joined with the last
@@ -2567,7 +2567,7 @@ .SS Shell Variables
 Example:
 .RS
 .PP
-\fBMAILPATH\fP=\(aq/var/mail/bfox?"You have mail":\(ti/shell\-mail?"$_ has 
mail!"\(aq
+\fBMAILPATH\fP=\(aq/var/mail/bfox?\(dqYou have 
mail\(dq:\(ti/shell\-mail?\(dq$_ has mail!\(dq\(aq
 .PP
 .B Bash
 can be configured to supply
@@ -3016,7 +3016,7 @@ .SH EXPANSION
 can increase the number of words of the expansion; other expansions
 expand a single word to a single word.
 The only exceptions to this are the expansions of
-"\fB$@\fP" and "\fB${\fP\fIname\fP\fB[@]}\fP",
+\(dq\fB$@\fP\(dq and \(dq\fB${\fP\fIname\fP\fB[@]}\fP\(dq,
 and, in most cases, \fB$*\fP and \fB${\fP\fIname\fP\fB[*]}\fP
 as explained above (see
 .SM
@@ -3857,7 +3857,7 @@ .SS Word Splitting
 of
 .BR  .
 .PP
-Explicit null arguments (\^\f3"\^"\fP or \^\f3\(aq\^\(aq\fP\^) are retained
+Explicit null arguments (\^\f3\(dq\^\(dq\fP or \^\f3\(aq\^\(aq\fP\^) are 
retained
 and passed to commands as empty strings.
 Unquoted implicit null arguments, resulting from the expansion of
 parameters that have no values, are removed.
@@ -4182,7 +4182,7 @@ .SS Quote Removal
 characters
 .BR \e ,
 .BR \(aq ,
-and \^\f3"\fP\^ that did not result from one of the above
+and \^\f3\(dq\fP\^ that did not result from one of the above
 expansions are removed.
 .SH REDIRECTION
 Before a command is executed, its input and output
@@ -6002,7 +6002,7 @@ .SS "Readline Key Bindings"
 .br
 Meta-Rubout: backward-kill-word
 .br
-Control-o: "> output"
+Control-o: \(dq> output\(dq
 .RE
 .LP
 In the above example,
@@ -6019,7 +6019,7 @@ .SS "Readline Key Bindings"
 .Q "> output"
 into the line).
 .PP
-In the second form, \fB"keyseq"\fP:\^\fIfunction\-name\fP or \fImacro\fP,
+In the second form, \fB\(dqkeyseq\(dq\fP:\^\fIfunction\-name\fP or \fImacro\fP,
 .B keyseq
 differs from
 .B keyname
@@ -6030,11 +6030,11 @@ .SS "Readline Key Bindings"
 are not recognized.
 .PP
 .RS
-"\eC\-u": universal\-argument
+\(dq\eC\-u\(dq: universal\-argument
 .br
-"\eC\-x\eC\-r": re\-read\-init\-file
+\(dq\eC\-x\eC\-r\(dq: re\-read\-init\-file
 .br
-"\ee[11\(ti": "Function Key 1"
+\(dq\ee[11\(ti\(dq: \(dqFunction Key 1\(dq
 .RE
 .PP
 In this example,
@@ -6065,8 +6065,8 @@ .SS "Readline Key Bindings"
 .B \e\e
 backslash
 .TP
-.B \e"
-literal "
+.B \e\(dq
+literal \(dq
 .TP
 .B \e\(aq
 literal \(aq
@@ -6117,7 +6117,7 @@ .SS "Readline Key Bindings"
 Unquoted text is assumed to be a function name.
 In the macro body, the backslash escapes described above are expanded.
 Backslash will quote any other character in the macro text,
-including " and \(aq.
+including \(dq and \(aq.
 .PP
 .B Bash
 allows the current readline key bindings to be displayed or modified
@@ -6583,7 +6583,7 @@ .SS "Readline Conditional Constructs"
 .nf
 \fB$if\fP Bash
 # Quote the current or previous word
-"\eC\-xq": "\eeb\e"\eef\e""
+\(dq\eC\-xq\(dq: \(dq\eeb\e\(dq\eef\e\(dq\(dq
 \fB$endif\fP
 .fi
 .RE
@@ -7469,7 +7469,7 @@ .SS Programmable Completion
 .nf
 _completion_loader()
 {
-  . "/etc/bash_completion.d/$1.sh" \c
+  . \(dq/etc/bash_completion.d/$1.sh\(dq \c
 .if \n(LL<80n \{\
 \e
 .br
@@ -8054,7 +8054,7 @@ .SH "SHELL BUILTIN COMMANDS"
 initialization file such as
 .IR .inputrc ,
 but each binding or command must b

[PATCH 07/18] doc/bash.1: stop attempting literal ASCII ^ use

[G. Branden Robinson]

Almost all other "literal" uses of the caret were already migrated to
`\(ha` instead.

groff_man_style(7):
 ... Some escape sequences are however required for correct
 typesetting even in man pages and usually do not cause portability
 problems.

 Several of these render glyphs corresponding to punctuation code
 points in the Unicode basic Latin range (U+–U+007F) that are
 handled specially in roff input; the escape sequences below must be
 used to render them correctly and portably when documenting
 material that uses them as literals—namely, any of the set ' - \ ^
 ` ~ (apostrophe, dash or hyphen‐minus, backslash, caret, grave
 accent, tilde).

 \(ha   Basic Latin circumflex accent (“hat”).  Some output devices
format “^” as U+02C6 (modifier letter circumflex accent).
---
 doc/bash.1 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/bash.1 b/doc/bash.1
index f18816fc..f21aeb52 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -6839,7 +6839,7 @@ .SS Commands for Manipulating the History
 .B HISTORY EXPANSION
 below for a description of history expansion.
 .TP
-.B history\-expand\-line (M\-^)
+.B history\-expand\-line (M\-\(ha)
 Perform history expansion on the current line.
 See
 .SM
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 06/18] doc/bash.1: fix markup nit

[G. Branden Robinson]

Remove trailing whitespace from lines.  They shouldn't matter to
*roff,[1] but "git diff" shows them as distractingly radioactive.

Diff of rendering (Heirloom Doctools, DWB):

-  referred to as the region. When this variable is set to On,
+  referred to as the region.  When this variable is set to On,
   readline allows certain commands to designate the region as
-  active. When the region is active, readline highlights the text
+  active.  When the region is active, readline highlights the text

[1] Today I learned that AT&T troff's end-of-sentence detection is
actually broken by trailing spaces, as seen above.
---
 doc/bash.1 | 64 +++---
 1 file changed, 32 insertions(+), 32 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 058e6a18..f18816fc 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -2418,7 +2418,7 @@ .SS Shell Variables
 .TP
 .B HISTTIMEFORMAT
 If this variable is set and not null, its value is used as a format string
-for 
+for
 .IR strftime (3)
 to print the time stamp associated with each history
 entry displayed by the \fBhistory\fP builtin.
@@ -2678,7 +2678,7 @@ .SS Shell Variables
 .B PS4
 is replicated multiple times, as necessary, to indicate multiple
 levels of indirection.
-The default is 
+The default is
 .Q "+\ " .
 .TP
 .B SHELL
@@ -3403,7 +3403,7 @@ .SS Parameter Expansion
 .IR parameter ,
 then the result of the expansion is the expanded value of
 .I parameter
-with the shortest matching pattern (the 
+with the shortest matching pattern (the
 .Q #
 case) or the longest matching pattern (the
 .Q ##
@@ -3441,7 +3441,7 @@ .SS Parameter Expansion
 .IR parameter ,
 then the result of the expansion is the expanded value of
 .I parameter
-with the shortest matching pattern (the 
+with the shortest matching pattern (the
 .Q %
 case) or the longest matching pattern (the
 .Q %%
@@ -3483,7 +3483,7 @@ .SS Parameter Expansion
 .B Pattern Matching
 below.
 In the first form above, only the first match is replaced.
-If there are two slashes separating \fIparameter\fP and \fIpattern\fP 
+If there are two slashes separating \fIparameter\fP and \fIpattern\fP
 (the second form above), all matches of \fIpattern\fP are
 replaced with \fIstring\fP.
 If \fIpattern\fP is preceded by \fB#\fP (the third form above),
@@ -3703,7 +3703,7 @@ .SS Command Substitution
 word would usually require.
 .PP
 Any side effects of \fIcommand\fP take effect immediately
-in the current execution environment and persist in the current 
+in the current execution environment and persist in the current
 environment after the command completes (e.g., the \fBexit\fP builtin
 will exit the shell).
 .PP
@@ -3854,7 +3854,7 @@ .SS Word Splitting
 .SM
 .B IFS
 is unset, word splitting behaves as if it contained the default value
-of 
+of
 .BR  .
 .PP
 Explicit null arguments (\^\f3"\^"\fP or \^\f3\(aq\^\(aq\fP\^) are retained
@@ -3868,7 +3868,7 @@ .SS Word Splitting
 non-null, the null argument is removed.
 That is, the word
 .Q "\-d\(aq\^\(aq"
-becomes 
+becomes
 .Q \-d
 after word splitting and null argument removal.
 .PP
@@ -3921,7 +3921,7 @@ .SS Pathname Expansion
 .Q .\&
 and
 .Q ..\& ,
-the pattern must begin with 
+the pattern must begin with
 .Q .\&
 (for example,
 .Q .?\& ),
@@ -4577,7 +4577,7 @@ .SH ALIASES
 replaces the word with the alias value, and reads that value as if it
 had been read instead of the word.
 The shell doesn't look at any characters following the word before
-attempting alias substitution. 
+attempting alias substitution.
 .PP
 The characters \fB/\fP, \fB$\fP, \fB\`\fP, and \fB=\fP and
 any of the shell \fImetacharacters\fP or quoting characters
@@ -5489,7 +5489,7 @@ .SH SIGNALS
 .B SIGINT
 to all processes in that process group.
 .PP
-When \fBbash\fP is running without job control enabled and receives 
+When \fBbash\fP is running without job control enabled and receives
 .SM
 .B SIGINT
 while waiting for a foreground command, it waits until that foreground
@@ -6159,7 +6159,7 @@ .SS "Readline Variables"
 .PP
 .PD 0
 .TP
-.B active\-region\-start\-color   
+.B active\-region\-start\-color
 A string variable that controls the text color and background when displaying
 the text in the active region (see the description of
 \fBenable\-active\-region\fP below).
@@ -6169,13 +6169,13 @@ .SS "Readline Variables"
 This variable is reset to the default value whenever the terminal type changes.
 The default value is the string that puts the terminal in standout mode,
 as obtained from the terminal's terminfo description.
-A sample value might be 
+A sample value might be
 .Q "\ee[01;33m" .
 .TP
-.B active\-region\-end\-color 
+.B active\-region\-end\-color
 A string variable that
 .Q undoes
-the effects of \fBactive\-region\-start\-color\fP 
+the effects of \fBactive\-region\-start\-color\fP
 and restores
 .Q normal
 terminal display appearance after displaying text in the active region.
@@ -6195,

[PATCH 04/18] doc/bash.1: improve typography of ellipses

[G. Branden Robinson]

Apply ellipsis advice from groff_man_style(7).

 •  The dummy character escape sequence \& follows the ellipsis when
further text will follow after space on the output line, keeping
its last period from being interpreted as the end of a sentence
and causing additional inter‐sentence space to be placed after
it.  See subsection “Portability” below.
[...]
 \&Dummy character.  Insert at the beginning of an input
   line to prevent a dot or apostrophe from being
   interpreted as beginning a roff control line.  Append to
   an end‐of‐sentence punctuation sequence to keep it from
   being recognized as such.

 \|Thin space (one‐sixth em on typesetters, zero‐width on
   terminals); a non‐breaking space.  Used primarily in
   ellipses (“.\|.\|.”) to space the dots more pleasantly on
   typesetters like dvi, pdf, and ps.

Break some long input lines.

 \newline  Join the next input line to the current one.  Except for
   the update of the input line counter (used for diagnostic
   messages and related purposes), a series of lines ending
   in backslash‐newline appears to groff as a single input
   line.  Use this escape sequence to split excessively long
   input lines for document maintenance.

Set the ellipsis in roman instead of bold in the few cases where it
wasn't already.  As far as I can tell, it is never employed as a literal
in this man page.

Set some Bash literal syntax in bold, not roman, namely command
"$(( ))" and arithmetic "(( ))" substitutions.

Use \(dq special character escape sequence to smuggle a double quote
into paragraph tags that call macros.  (All the *roffs I have ready
access to [groff, Heirloom Doctools, DWB 3.3], plus mandoc(1) support
this special character, but Seventh Edition Unix troff does not, and a
grep of Solaris 10 troff suggests it doesn't either.  This man page
already uses `aq`, which is no _more_ portable than `dq`--DWB 3.3
supports `aq` on _fewer_ output devices, in fact.)
---
 doc/bash.1 | 132 +++--
 1 file changed, 78 insertions(+), 54 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 9562d830..5484e496 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -559,7 +559,8 @@ .SS Pipelines
 The format for a pipeline is:
 .RS
 .PP
-[\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP] 
\fIcommand2\fP ... ]
+[\fBtime\fP [\fB\-p\fP]] [ ! ] \fIcommand1\fP [ [\fB|\fP\(bv\fB|&\fP]
+\fIcommand2\fP .\|.\|.\& ]
 .RE
 .PP
 The standard output of
@@ -857,7 +858,8 @@ .SS Compound Commands
 the entire conditional expression.
 .RE
 .TP
-\fBfor\fP \fIname\fP [ [ \fBin\fP [ \fIword ...\fP ] ] ; ] \fBdo\fP \fIlist\fP 
; \fBdone\fP
+\fBfor\fP \fIname\fP [ [ \fBin\fP [ \fIword .\|.\|.\&\fP ] ] ; ] \
+\fBdo\fP \fIlist\fP ; \fBdone\fP
 The list of words following \fBin\fP is expanded, generating a list
 of items.
 The variable \fIname\fP is set to each element of this list
@@ -919,8 +921,9 @@ .SS Compound Commands
 .IR list ,
 or zero if no commands were executed.
 .TP
-\fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP [ \fB|\fP \fIpattern\fP ] \
-... ) \fIlist\fP ;; ] ... \fBesac\fP
+\fBcase\fP \fIword\fP \fBin\fP [ [(] \fIpattern\fP \
+[ \fB|\fP \fIpattern\fP ] .\|.\|.\& ) \fIlist\fP ;; ] .\|.\|.\& \
+\fBesac\fP
 A \fBcase\fP command first expands \fIword\fP, and tries to match
 it against each \fIpattern\fP in turn, using the matching rules
 described under
@@ -950,7 +953,7 @@ .SS Compound Commands
 last command executed in \fIlist\fP.
 .TP
 \fBif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; \
-[ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] ... \
+[ \fBelif\fP \fIlist\fP; \fBthen\fP \fIlist\fP; ] .\|.\|.\& \
 [ \fBelse\fP \fIlist\fP; ] \fBfi\fP
 The
 .B if
@@ -1319,8 +1322,9 @@ .SH PARAMETERS
 .B integer
 attribute set, then
 .I value
-is evaluated as an arithmetic expression even if the $((...)) expansion is
-not used (see
+is evaluated as an arithmetic expression even if the
+.BR $(( .\|.\|.\& ))
+expansion is not used (see
 .B "Arithmetic Expansion"
 below).
 Word splitting and pathname expansion are not performed.
@@ -1427,7 +1431,7 @@ .SS Special Parameters
 .SM
 .B IFS
 special variable.  That is, "\fB$*\fP" is equivalent
-to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP\fB...\fP", where
+to "\fB$1\fP\fIc\fP\fB$2\fP\fIc\fP.\|.\|.", where
 .I c
 is the first character of the value of the
 .SM
@@ -1452,7 +1456,7 @@ .SS Special Parameters
 When the
 expansion occurs within double quotes, each parameter expands to a
 separate word.  That is, "\fB$@\fP" is equivalent to
-"\fB$1\fP"\ "\fB$2\fP"\ ...
+"\fB$1\fP"\ "\fB$2\fP"\ .\|.\|.
 If the double-quoted expansion occurs within a word, the expansion of
 the first parameter is joined with the beginning part of the original
 word, and the expansion of the last parameter is joined with the last
@

[PATCH 05/18] doc/bash.1: prevent space where undesired

[G. Branden Robinson]

groff_man_style(7):
 \cEnd a text line without inserting space or attempting a
   break.  Normally, if filling is enabled, the end of a
   text line is treated like a space; an output line may
   break there (if it does not, troff inserts an adjustable
   space); if filling is disabled, the line will break
   there, as in .EX/.EE examples.  The next line is
   interpreted as usual and can include a macro call
   (contrast with \newline). ...

Not changing the following occurrence, because it seems purposeful
and/or useful.

arithmetic commands (
.BR (( .\|.\|.\& ))
)

Diff of rendering (everywhere):

--e The maximum scheduling priority ( “nice”).
+-e The maximum scheduling priority (“nice”).

- as a set of options to the shopt builtin ( compat31, compat32, compat40,
+ as a set of options to the shopt builtin (compat31, compat32, compat40,
---
 doc/bash.1 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 5484e496..058e6a18 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -11510,7 +11510,7 @@ .SH "SHELL BUILTIN COMMANDS"
 The maximum size of a process's data segment
 .TP
 .B \-e
-The maximum scheduling priority (
+The maximum scheduling priority (\c
 .Q nice ).
 .TP
 .B \-f
@@ -11740,7 +11740,7 @@ .SH "SHELL BUILTIN COMMANDS"
 process or job waited for.
 .SH "SHELL COMPATIBILITY MODE"
 Bash-4.0 introduced the concept of a \fIshell compatibility level\fP,
-specified as a set of options to the shopt builtin (
+specified as a set of options to the shopt builtin (\c
 .BR compat31 ,
 .BR compat32 ,
 .BR compat40 ,
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 03/18] doc/bash.1: fix latent bug in `QN` macro

[G. Branden Robinson]

Whether it arises will depend on word placement and line length.

*roff has a simplistic notion of what a "word" is.

groff_man_style(7):
 ... The formatter troff(1) collects words from the input and fills
 output lines with as many as will fit.  Words are separated by
 spaces and newlines.  A transition to a new output line is called a
 break.  When formatted, a word may be broken at hyphens, at \% or
 \: escape sequences (see subsection “Portability” below), or at
 predetermined locations if automatic hyphenation is enabled (see
 the -rHY option in section “Options” below). ...

The input

.  if t \%``\%\\$1''\\$2

...tells the formatter that a hyphenation break is permitted after the
opening double quotation mark, like “‐
this”.  A hyphenation control escape sequence at the _beginning_ of a
word is treated specially.

groff_man_style(7):
 \%Control hyphenation.  The location of this escape
   sequence within a word marks a hyphenation point,
   supplementing groff’s automatic hyphenation patterns.  At
   the beginning of a word, it suppresses any hyphenation
   breaks within except those specified with \%.
---
 doc/bash.1 | 8 +---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 1c495378..9562d830 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -41,7 +41,8 @@
 .\"
 .\" File Name macro.  This used to be `.PN', for Path Name,
 .\" but Sun doesn't seem to like that very much.
-.\" The \% is to prevent the filename from hyphenation.
+.\"
+.\" \% at the beginning of a word protects it from hyphenation.
 .\"
 .de FN
 \%\fI\|\\$1\|\fP
@@ -57,11 +58,12 @@
 .  if n "\\$1"\\$2
 .\}
 ..
+.\" As Q, but don't permit automatic hyphenation of contents.
 .de QN
 .ie \n(.g \%\(lq\\$1\(rq\\$2
 .el \{\
-.  if t \%``\%\\$1''\\$2
-.  if n \%"\%\\$1"\\$2
+.  if t \%``\\$1''\\$2
+.  if n \%"\\$1"\\$2
 .\}
 ..
 .SH NAME
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 02/18] doc/bash.1: fix bug in new `Q` macro

[G. Branden Robinson]

I didn't pay close enough attention to Documenter's Workbench 3.3 troff
output when submitting the original version of this macro.  Add a
necessary backslash to escape the newline at the beginning of a
conditional block.  This omission was causing DWB to put a blank line on
the output every time it hit a "Q" macro call.  This did not delete any
text from the output, but it was surely ugly.

Diff of rendering (DWB):
- one with the highest index) is
-
- "main".  This variable exists only when a shell func-
- tion is executing.  Assignments to FUNCNAME have no
- effect.  If FUNCNAME is unset, it loses its special
- properties, even if it is subsequently reset.
+ one with the highest index) is "main".  This variable
+ exists only when a shell function is executing.
+ Assignments to FUNCNAME have no effect.  If FUNCNAME is
+ unset, it loses its special properties, even if it is
+ subsequently reset.
---
 doc/bash.1 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index b02e7527..1c495378 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -52,14 +52,14 @@
 .\"
 .de Q
 .ie \n(.g \(lq\\$1\(rq\\$2
-.el \{
+.el \{\
 .  if t ``\\$1''\\$2
 .  if n "\\$1"\\$2
 .\}
 ..
 .de QN
 .ie \n(.g \%\(lq\\$1\(rq\\$2
-.el \{
+.el \{\
 .  if t \%``\%\\$1''\\$2
 .  if n \%"\%\\$1"\\$2
 .\}
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 01/18] doc/bash.1: fix rendering error on old *roffs

[G. Branden Robinson]

The man(7) in Seventh Edition Unix (1979) accepted at most six arguments
to any macro.  Documenter's Workbench 3.3 troff retains this limitation,
as do at least some System V troffs that survive in commercial Unix
(such as Solaris 10 troff).

Quote the mulitiplicity of arguments so that they will appear.

Also simplify a similar case which was using the unadjustable space
escape sequence `\ ` to work around the same problem.  Since a paragraph
tag normally doesn't break or adjust anyway, the usage was mysterious.
Drop the backslashes and quote the tag as one big argument instead.

Diff of rendering (DWB):

 ||   logical OR
 expr?expr:expr
  conditional operator
-= *= /= %= += -=
+= *= /= %= += -= <<= >>= &= = |=
  assignment
 expr1 , expr2
  comma
---
 doc/bash.1 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index bd916b28..b02e7527 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -4860,7 +4860,7 @@ .SH "ARITHMETIC EVALUATION"
 .B \fIexpr\fP?\fIexpr\fP:\fIexpr\fP
 conditional operator
 .TP
-.B = *= /= %= += \-= <<= >>= &= \(ha= |=
+.B "= *= /= %= += \-= <<= >>= &= \(ha= |="
 assignment
 .TP
 .B \fIexpr1\fP , \fIexpr2\fP
@@ -6902,7 +6902,7 @@ .SS Commands for Changing Text
 .B tab\-insert (C\-v TAB)
 Insert a tab character.
 .TP
-.B self\-insert (a,\ b,\ A,\ 1,\ !,\ ...)
+.B "self-insert (a, b, A, 1, !, ...)"
 Insert the character typed.
 .TP
 .B transpose\-chars (C\-t)
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 8/8] doc/bash.1: fix erroneous escape sequences

[G. Branden Robinson]

troff:doc/bash.1:10090: warning: ignoring escape character before '+'
troff:doc/bash.1:11896: warning: ignoring escape character before 'P'
---
 doc/bash.1 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 35c076f0..9d44a6d4 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -10087,7 +10087,7 @@ .SH "SHELL BUILTIN COMMANDS"
 .TP
 \fBset \-o\fP
 .TP
-\fBset \+o\fP
+\fBset +o\fP
 .PD
 Without options, display the name and value of each shell variable
 in a format that can be reused as input
@@ -11893,7 +11893,7 @@ .SH "SHELL COMPATIBILITY MODE"
 arithmetic expressions used as indexed array subscripts can be
 expanded more than once
 .IP \(bu
-\fBtest \-v\fP, when given an argument of \fBA[@]\fP, where \fBA\P is
+\fBtest \-v\fP, when given an argument of \fBA[@]\fP, where \fBA\fP is
 an existing associative array, will return true if the array has any set
 elements.
 Bash-5.2 will look for and report on a key named \fB@\fP.
-- 
2.30.2


signature.asc
Description: PGP signature

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

[G. Branden Robinson]

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

groff_man(7):
 .EX
 .EEBegin 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

[PATCH 6/8] doc/bash.1: use page-local `FN` macro for file name

[G. Branden Robinson]

The page defines it; might as well use it.
---
 doc/bash.1 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 8943e01e..fff8a817 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -2107,7 +2107,7 @@ .SS Shell Variables
 This variable expands to a 32-bit pseudo-random number each time it is
 referenced.
 The random number generator is not linear on systems that support
-\f(CW/dev/urandom\fP
+.FN /dev/urandom
 or
 .IR \%arc4random (3),
 so each returned number has no relationship to the numbers preceding it.
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 5/8] doc/bash.1: add man page cross references

[G. Branden Robinson]

Cross-reference arc4random(3) and stty(1) man pages.  Protect the former
from hyphenation.

Also break an input line after a sentence.
---
 doc/bash.1 | 12 +++-
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index f532d628..8943e01e 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -2105,9 +2105,12 @@ .SS Shell Variables
 .TP
 .B SRANDOM
 This variable expands to a 32-bit pseudo-random number each time it is
-referenced. The random number generator is not linear on systems that
-support \f(CW/dev/urandom\fP or \fIarc4random\fP, so each returned number
-has no relationship to the numbers preceding it.
+referenced.
+The random number generator is not linear on systems that support
+\f(CW/dev/urandom\fP
+or
+.IR \%arc4random (3),
+so each returned number has no relationship to the numbers preceding it.
 The random number generator cannot be seeded, so assignments to this
 variable have no effect.
 If
@@ -6834,8 +6837,7 @@ .SS Commands for Changing Text
 .TP
 .B \fIend\-of\-file\fP (usually C\-d)
 The character indicating end-of-file as set, for example, by
-.if t \f(CWstty\fP.
-.if n ``stty''.
+.IR stty (1).
 If this character is read when there are no characters
 on the line, and point is at the beginning of the line, readline
 interprets it as the end of input and returns
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 4/8] doc/bash.1: make quoted trailing spaces unbreakable

[G. Branden Robinson]

By luck, at present, input like

times, as necessary, to indicate multiple
levels of indirection.  The default is
.Q "+\ " .

does not get set as

times, as necessary, to indicate multiple
levels of indirection.  The default is “+
”.

by any of groff {1.22.4,1.23.0,git}, mandoc, Heirloom Doctools, or DWB
3.3 nroffs using their default line lengths...but it could, without this
patch.

In my opinion, it is not necessary to make _internal_ spaces in a
quotation unbreakable.  Thus I leave cases like

.Q "bind \-x"

alone.
---
 doc/bash.1 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index b1257639..f532d628 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -2624,14 +2624,14 @@ .SS Shell Variables
 .SM
 .B PROMPTING
 below) and used as the primary prompt string.  The default value is
-.Q "\es\-\ev\e$ " .
+.Q "\es\-\ev\e$\ " .
 .TP
 .B PS2
 The value of this parameter is expanded as with
 .SM
 .B PS1
 and used as the secondary prompt string.  The default is
-.Q "> " .
+.Q ">\ " .
 .TP
 .B PS3
 The value of this parameter is used as the prompt for the
@@ -2653,7 +2653,7 @@ .SS Shell Variables
 .B PS4
 is replicated multiple times, as necessary, to indicate multiple
 levels of indirection.  The default is
-.Q "+ " .
+.Q "+\ " .
 .TP
 .B SHELL
 This variable expands to the full pathname to the shell.
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 3/8] doc/bash.1: define and use "Q" quotation macro

[G. Branden Robinson]

...instead of assuming the availability of a font named `CW`, and using
inconsistent quotation conventions when rendering to terminals with
nroff(1).

This resolves 25 instances of the following warning from groff 1.23.0.

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

To extract the most salient points from a lengthy discussion on Perl's
GitHub site[1]:

1.  "CW" is not a portable font name.
2.  There is no portable way to ask troff whether a font is available.

Further, and this is more a matter of taste and opinion, some
typographical authorities deprecate changes of font family in running
text.  (This is similar to typographers' and technical writers' advice
not to change the typeface often, for instance with frequent use of
italics and, especially, bold.  But this latter horse is probably locked
_out_ of the barn for man pages.)  Contrast with use of different font
families for "displays", that is, text that is set off by vertical
separation (and often indentation) from its surroundings.

With a macro, it is more straightforward to tackle another portability
problem: the availability of special character escape sequences for
doubled typographer's quotes.  groff has supported these for 30+ years;
and mandoc and Heirloom Doctools do as well.  But they are not portable
to System V or DWB troff, let alone the Seventh Edition Unix troff that
BSD employed until replacing it with groff in the early 1990s.

Therefore, define a quotation macro as follows:

A.  Bracket the first argument with `lq` and `rq` special character
escape sequences if the formatter is groff;
B.  ...with `` and '' on a non-groff troff typesetter;
C.  ...with " and " on a non-groff nroff program.
D.  Accept a second argument for abutting, trailing punctuation,
similarly to man(7)'s font alternation macros (and groff's `ME`,
`UE`, and `MR` extensions).

Furthermore:
E.  Drop font style changes, no longer necessary to mark the text now
that quotation is reliable.
F.  Use dummy character escape sequence \& after quoted, word-ending
dots to avoid erroneous insertion of inter-sentence space.[2]  (See
particularly bash(1)'s subsection "Pathname Expansion".)
G.  Fix outright missing closing quotation in description of "enable"
built-in.

mandoc maintainer Ingo Schwarze gravely warns man page authors against
defining macros, but (1) mandoc _does_ support them if they're not too
complex, like this [I tested]; (2) he'd rather that any given man page
be written in mdoc(7) instead, a heavy lift for a document of bash(1)'s
mass even if such were desired by its maintainer and/or user community;
(3) at some point, portability demands of legacy systems militate for
such things (and all legacy troffs are considerably more flexible than
mandoc(1)); and (4) an alternative approach, perhaps using autoconf(1)
to check the host's troff(1), nroff(1), and man(7) for features and
constructing a man page at build time using soelim(1), is conceivable,
and I'm willing to assist with that if it sounds promising.

Exhibits of visible change (UTF-8, which groff and mandoc produce,
follows):

-ement (the one with the highest index) is "main".  This variable 
ex‐
+ement (the one with the highest index) is “main”.  This variable 
ex‐

-will write the trace output generated when set -x is enabled to 
that
+will write the trace output generated when “set -x” is enabled to

-mand.  The default value is ‘‘’’.
+mand.  The default value is “”.

- ‘‘.’’  at the start of a name or immediately following a slash must be
+ “.” at the start of a name or immediately following a slash must be 
matched

[The foregoing item was rendered with left adjustment; observe that the
quoted dot is no longer treated as ending a sentence.]

-name, as if the command were ‘‘enable -f name name .  The return
+name, as if the command were “enable -f  name name”.  The return

[1] https://github.com/Perl/perl5/issues/21239
[2] https://www.gnu.org/software/groff/manual/groff.html.node/Sentences.html
---
 doc/bash.1 | 234 ++---
 1 file changed, 131 insertions(+), 103 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index ed67e4b0..b1257639 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -43,7 +43,15 @@
 .\" but Sun doesn't seem to like that very much.
 .\"
 .de FN
-\fI\|\\$1\|\fP
+\%\fI\|\\$1\|\fP
+..
+.\" quotation macro
+.de Q
+.ie \n(.g \(lq\\$1\(rq\\$2
+.el \{
+.  if t ``\\$1''\\$2
+.  if n "\\$1"\\$2
+.\}
 ..
 .SH NAME
 bash \- GNU Bourne-Again SHell
@@ -1868,8 +1876,7 @@ .SS Shell Variables
 The element with index 0 is the name of any currently-executing
 shell function.
 The bottom-most element (the one with the highest index) is
-.if t \f(CW"main"\fP.
-.if n "main".
+.Q main .
 This variable exists only when a shell function is executing.
 Assignments to
 .SM
@@ -2009,8 +2016,7 @@ .SS Shell Variables
 .TP
 .B RE

[PATCH 2/8] doc/bash.1: fix unescaped hyphens

[G. Branden Robinson]

---
 doc/bash.1 | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/bash.1 b/doc/bash.1
index 8c2fa229..ed67e4b0 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -6132,7 +6132,7 @@ .SS "Readline Variables"
 treated specially by the kernel's terminal driver to their  
 readline equivalents.
 These override the default readline bindings described here.
-Type \f(CWstty -a\fP at a bash prompt to see your current terminal settings,
+Type \f(CWstty \-a\fP at a bash prompt to see your current terminal settings,
 including the special control characters (usually \fBcchars\fP).
 .TP
 .B blink\-matching\-paren (Off)
@@ -7397,7 +7397,7 @@ .SS Programmable Completion
 .br
 }
 .br
-complete \-D \-F _completion_loader -o bashdefault -o default
+complete \-D \-F _completion_loader \-o bashdefault \-o default
 .br
 \fP
 .SH HISTORY
-- 
2.30.2



signature.asc
Description: PGP signature

[PATCH 0/8] doc/bash.1: silence groff warnings, fix style issues

[G. Branden Robinson]

With this series of changes, bash(1) formats quiescently for me using
groff 1.23.0 with the following command line.

nroff -ww -rCHECKSTYLE=1 -man -z doc/bash.1

Regards,
Branden


signature.asc
Description: PGP signature

[PATCH 1/8] doc/bash.1: use consistent inter-paragraph spacing

[G. Branden Robinson]

Historically in man(7), the inter-paragraph spacing (equivalently, the
spacing before section and subsection headings, and the value of the PD
register) is 0.4v (or four tenths of a "vee", the distance between
vertically adjacent text baselines) on typesetters, and 1v on terminals
(that is, a blank line).[1]

1.  Replace `sp` requests with `PP` calls for paragraphs that should not
be (specially) indented.

2.  Replace `sp` requests with `IP` calls for each paragraph that
continues a discussion begun with a tagged paragraph (`TP`) and
therefore should be indented the same as its predecessor.

3.  Add `PD` calls to restore normal inter-paragraph spacing when
separating them inside doubly-nested tagged paragraphs where the
outer layer of tagged paragraphs disables inter-paragraph spacing
with `PD 0`.  (The difficulty/tedium of managing such things, as
well as the "presentationalism" of the `PD` macro is why
groff_man_style(7) deprecates it.  But it does have the virtue of
being portable to all man(7) implementations thanks to its presence
in Seventh Edition Unix man(7) (1979).)

I would like to say that this commit produces no change in nroff-mode
output on any implementation, but that's not quite the case.

Replacing `.sp 0.5` with `PP` caused the amount of inter-paragraph space
to round up to 1v on groff and mandoc.  This measurement "floors" on
nroff traditionally, rounding to zero, as the following command shows.

  printf '.TH foo 1\n.SH Name\na\n.sp 0.5\nb\n' | nroff -man | cat -s

(Use any nroff you like, or simply "mandoc".)

* groff Git
* groff 1.23.0
* groff 1.22.4

The following three implementations show progressively greater, but
arguably not alarming, differences.

* mandoc 1.14.6

As above, plus:

Incorrectly suppresses the restored (non-zero) paragraph spacing at the
following points.

$ sed -n 800,805p doc/bash.1
in decreasing order of precedence:
.IP
.RS
.PD 0
.TP
.B ( \fIexpression\fP )
$ sed -n 8303,8308p doc/bash.1
builtin is invoked.
.IP
.RS
.PD 0
.TP 8
\fB\-o\fP \fIcomp-option\fP

* Heirloom Doctools

As above, plus:

a.  Appears to _fix_ a font selection problem when output piped through
ul(1) from the Debian "bsdextrautils" 2.36.1 package; the following
lines are no longer set in a "dim" style on xterm(1).

if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi

declare -n ref=$1

b.  The same lines were already getting a blank line rendered after (but
not before) them, unlike groff(1) and mandoc(1).

c.  The following line is now also styled consistently with its
successors, instead of being set in a "dim" style.

BASH_VERSINFO[0]The major version number (the release).

(When not piped through "less -R", "BASH_VERSINFO[", "]", and
"release" appear in reverse video rather than a dim font.)

d.  The blank line that should render in the following is incorrectly
suppressed.

$ sed -n 2671,2675p doc/bash.1
braces denote optional portions.
.PP
.RS
.PD 0
.TP 10

e.  The "(expression)" and "-o comp-option" lines mentioned under mandoc
above are set with an _extra_ blank line, instead of mandoc's none.

f.  A blank line no longer renders at the paragraph break in the
following.  This is correct because at this point in the page (where
paragraph tagging is 3 levels deep), the configured inter-paragraph
spacing is zero.  (Whether that is _intended_, and what style rules
are supposed to apply at various levels of tag nesting, are not
clear to me.)

$ sed -n 10286,10291p doc/bash.1
.B xtrace
Same as
.BR \-x .
.PP
If
.B \-o

* Documenter's Workbench 3.3

As Heirloom, plus:

g.  Because the number of lines in the formatted output changes, the
pagination changes as well (as it does with groff(1) when the
`-rcR=0` option is used when rendering man pages).

h.  The foregoing furthermore changes the parity of line adjustment.
(In other words, spaces that "justify" the line are sometimes
inserted from the opposite end.)

[1] Here is my support for my claim, thanks to TUHS.

I elided literal bell characters from System III sources; the resulting
syntax is invalid.  (It was an effort to cope with the prospect of macro
arguments containing embedded double-quotes, but the means of such
embedding was so esoteric in AT&T troff that few users acquired the
skill.)

--
HISTORY/MAN/1979-01-v7/tmac.an:.de PD
HISTORY/MAN/1979-01-v7/tmac.an-.if t .nr )P .4v
HISTORY/MAN/1979-01-v7/tmac.an-.if n .nr )P 1v
HISTORY/MAN/1979-01-v7/tmac.an-.if !"\\$1"" .nr )P \\$1v
--
HISTORY/MAN/1980-03-3BSD/tmac.an.new:.de PD
HISTORY/MAN/1980-03-3BSD/tmac.an.new-.if t .nr )P .4v
HISTORY/MAN/1980-03-3BSD/tmac.an.new-.if n .nr )P 1v
HISTORY/MAN/1980-03-3BSD/tmac.an.new-.if !"\\$1"" .nr )P \\$1v
--
HISTORY/MAN/1980-06-SystemIII/an.src:.dePD
HISTORY/MAN/1980-06-SystemIII/an.src-.ift .nr PD .4v
HISTORY/MAN/1980-06-SystemIII/an.src-.ifn .nr PD 1v
HISTORY/MAN/1980-06-SystemIII/an.src-.if!\\$1 .nr PD \\$1v
--
HISTOR

Re: Make reverse-i-search failure joltingly clear

[G. Branden Robinson]

At 2023-12-11T15:09:26+0800, Dan Jacobson wrote:
> Type ^R and some string,
> At the point while we are typing that the search fails, all that
> happens is the word "failed" gets added at front,

Not for me.  I also get a visual bell for each character I add to the
pattern once the match fails.

You might make sure the (visual/audible) bell in your terminal emulator
is enabled.

Regards,
Branden


signature.asc
Description: PGP signature

the portability of seq(1) (was: Idea: jobs(1) -i to print only :%ID:s)

[G. Branden Robinson]

At 2023-11-10T10:54:52-0800, Eric Pruitt wrote:
> On Fri, Nov 10, 2023 at 01:22:54PM -0500, Greg Wooledge wrote:
> > It most definitely is *not* everywhere.  It's part of GNU coreutils,
> > and is generally not present on any system that does't use those
> > (BSDs and commercial Unixes for example).
> 
> From _seq(1)_ on FreeBSD:
> 
> > The seq command first appeared in Version 8 AT&T UNIX. A seq command
> > appeared in NetBSD 3.0, and was ported to FreeBSD 9.0. This command
> > was based on the command of the same name in Plan 9 from Bell Labs
> > and the GNU core utilities. The GNU seq command first appeared in
> > the 1.13 shell utilities release.
> 
> From _seq(1)_ on OpenBsd:
> 
> > A seq command appeared in Version 8 AT&T UNIX. This version of seq
> > appeared in NetBSD 3.0 and was ported to OpenBSD 7.1.

That leaves NetBSD (data point requested), and I stumbled into seq's
absence when building groff 1.23.0 release candidates for Solaris 10
(maybe 11 too).

https://git.savannah.gnu.org/cgit/groff.git/tree/HACKING?h=1.23.0#n98

Regards,
Branden


signature.asc
Description: PGP signature

Re: [PATCH] repair recent, ill-conceived man page changes

[G. Branden Robinson]

Hi Chet,

At 2023-10-11T10:22:44-0400, Chet Ramey wrote:
> On 10/11/23 5:08 AM, G. Branden Robinson wrote:
> > Please consider reverting the following recent changes to the bash
> > man page.  Bjarni should have run them by the groff list first,
> > because some of them are ill-considered.
> 
> OK. I'm trying to understand them myself; please take my comments in
> that spirit.

No worries.  My concern with some of the changes is that they risk
mystifying people who encounter them ("`kern`?  `ss`?  `lg`?  What are
those?") without delivering concrete benefit, typographical or
otherwise.  groff_man_style(7), as of groff 1.23.0, attempts to document
all of the *roff syntax a man page author is ever likely to need, and
strives _not_ to introduce any other *roff features or typesetting
concepts.[0]

> > +.\" suggested by Bjarni Ingi Gislason 
> > +.if n \{\
> > +.kern 0
> > +.ss 12 0
> > +.\}
> > 
> > The above change is half pointless and half intrusive.
> > 
> > A) No formatter for terminal output devices ("nroff mode", which is
> > tested by "if n" performs kerning.  So that's a no-op.
> > 
> > B) The amount of intersentence spacing, for man pages, is matter of
> >the _reader's_ taste and should be left to them.  mandoc(1)
> >ignores this request and I'm glad it does.  So that, too, is a
> >no-op with that formatter.
> 
> Is his intent here to force French spacing instead of English spacing?

Yes, if you understand "French spacing" to mean "the space between
sentences is the same as the space between words".  Frustratingly,
"French spacing" has multiple incompatible meanings.[1]

> How does groff deal with input where the number of spaces after a
> period varies?

roff(7) and the groff Texinfo manual cover this--clearly, I hope.  If
not, blame me because the language is mine, and I'll try to improve it.

(groff 1.23.0; UTF-8 follows)

   A roff formatter attempts to detect boundaries between sentences,
   and supplies additional inter‐sentence space between them.  It
   flags certain characters (normally “!”, “?”, and “.”) as
   potentially ending a sentence.  When the formatter encounters one
   of these end‐of‐sentence characters at the end of an input line,
   or one of them is followed by two (unescaped) spaces on the same
   input line, it appends an inter‐word space followed by an inter‐
   sentence space in the output.  The dummy character escape
   sequence \& can be used after an end‐of‐sentence character to
   defeat end‐of‐sentence detection on a per‐instance basis.
   Normally, the occurrence of a visible non‐end‐of‐sentence
   character (as opposed to a space or tab) immediately after an
   end‐of‐sentence character cancels detection of the end of a
   sentence.  However, several characters are treated transparently
   after the occurrence of an end‐of‐sentence character.  That is, a
   roff does not cancel end‐of‐sentence detection when it processes
   them.  This is because such characters are often used as footnote
   markers or to close quotations and parentheticals.  The default
   set is ", ', ), ], *, \[dg], \[dd], \[rq], and \[cq].  The last
   four are examples of special characters, escape sequences whose
   purpose is to obtain glyphs that are not easily typed at the
   keyboard, or which have special meaning to the formatter (like
   \).

That reads a bit better with font style changes, so "man 7 roff" might
be preferable.

> My personal writing style has changed from two spaces to one over a
> number of years, and the man page reflects that.

For _input_, it's a good idea to either break lines at the ends of
sentences, or put two spaces after them.  This is so that the formatter
knows where the ends of the sentences are.  Like TeX, *roff is not smart
to know where the sentence boundary/ies are in "C. A. R. Hoare next came
to the U.S. Linux kernel developers have yet to absorb his lessons."

For output, the amount of inter-sentence space is configurable; that
is what the `ss` request does.[2]  For man pages, I strongly urge all
authors to leave the issue alone so as to respect readers' preferences.
Since authors' will differ, this is the only way to achieve
consistency.[3]

People can get pretty passionate about this, and complain of their
eyeballs being violated when the "wrong" amount of inter-sentence space
is employed in a document they're reading.  Some people bring this
passion even to man page _source_ documents, and the only recourse in
that event is to break input lines at the ends of sentences.  This has
also been Brian Kernighan's advice to troff users since the 1970s.[4

[PATCH] repair recent, ill-conceived man page changes

[G. Branden Robinson]

Hi Chet,

Please consider reverting the following recent changes to the bash man
page.  Bjarni should have run them by the groff list first, because some
of them are ill-considered.

Bjarni,

I regret that I must repeat myself.[1]

Please do not offer yourself as an authority on correct man page
composition when you don't know what you're talking about and have filed
bug reports complaining of that fact.

https://savannah.gnu.org/bugs/?64238

You got some things right here, and some wrong; please stick to those
you got right.

diff --git a/doc/bash.1 b/doc/bash.1
index 0f23d480..24170efe 100644
--- a/doc/bash.1
+++ b/doc/bash.1
@@ -5,14 +5,19 @@
 .\"Case Western Reserve University
 .\"chet.ra...@case.edu
 .\"
-.\"Last Change: Wed Sep 13 15:39:24 EDT 2023
+.\"Last Change: Fri Oct  6 16:41:20 EDT 2023
 .\"
+.\" suggested by Bjarni Ingi Gislason 
+.if n \{\
+.kern 0
+.ss 12 0
+.\}

The above change is half pointless and half intrusive.

A) No formatter for terminal output devices ("nroff mode", which is
   tested by "if n" performs kerning.  So that's a no-op.

B) The amount of intersentence spacing, for man pages, is matter of the
   _reader's_ taste and should be left to them.  mandoc(1) ignores this
   request and I'm glad it does.  So that, too, is a no-op with that
   formatter.

@@ -511,8 +516,13 @@ .SH "RESERVED WORDS"
 .if t .RS
 .PP
 .B
-.if n ! case  coproc  do done elif else esac fi for function if in select then 
until while { } time [[ ]]
-.if t !casecoprocdodoneelifelseesacfifor   
 functionifinselectthenuntilwhile{}time
[[]]
+.if n ! case  coproc  do done elif else esac fi for function if in select \
+then until while { } time [[ ]]
+.if t \{\
+.lg 0
+ !casecoprocdodoneelifelseesacfifor
functionifinselectthenuntilwhile{}time
[[]]
+.lg 1
+.\}

This change is pointless because no ligatures are defined for any of the
letter pairs in the text in any known formatter (the ligature for "ct",
like that for "st" [not seen here] is archaic in English typography and
seldom seen in digital fonts).  Moreover, this request sequence clobbers
the user's selected ligature mode, which might have been 2 prior to the
".lg 0" control line.  This hunk should be reverted.

@@ -11629,7 +11638,7 @@ .SH "SHELL COMPATIBILITY MODE"
 .BR compat41 ,
 and so on).
 There is only one current
-compatibility level -- each option is mutually exclusive.
+compatibility level \(en each option is mutually exclusive.
 The compatibility level is intended to allow users to select behavior
 from previous versions that is incompatible with newer versions
 while they migrate scripts to use current features and

An en-dash is not the correct glyph: an em-dash is.  As it happens, the
"en" special character identifier is less portable than "em" to boot.
See section "History" of groff_char(7).

Authorities differ on whether space should surround em dashes; from what
I have seen, a majority favor omitting them, and that is what I do in
the groff man pages, but I cannot say it is more than a matter of taste.

(A man page's "Name" section is a special case, and the "-", "--",
"\(en", or "\(em" that separates the page's topic(s) from the summary
description _must_ be bracketed by spaces for makewhatis(8) and mandb(8)
to reliably interpret them.)

@@ -11940,7 +11983,7 @@ .SH "SEE ALSO"
 \fIPortable Operating System Interface (POSIX) Part 2: Shell and Utilities\fP, 
IEEE --
 http://pubs.opengroup.org/onlinepubs/9699919799/
 .TP
-http://tiswww.case.edu/\(tichet/bash/POSIX -- a description of posix mode
+http://tiswww.case.edu/\(tichet/bash/POSIX \(en a description of posix mode
 .TP
 \fIsh\fP(1), \fIksh\fP(1), \fIcsh\fP(1)
 .TP

As with the previous \(en -> \(em remark.  Also we can see that another
double-hyphen in the context was carelessly left inconsistent.

I find nothing amiss with the other changes.

Chet, I'm happy to prepare a patch reflecting the above recommendations
(against the "devel" branch at git.sv.gnu.org:/srv/git/bash.git).  Let
me know.

Regards,
Branden

[1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1036826#33


signature.asc
Description: PGP signature

formatting man pages in email (was: Assignment to RO variable)

[G. Branden Robinson]

At 2023-08-15T23:24:31-0500, Dennis Williamson wrote:
> From man bash:
> 
> readonly [-aAf] [-p] [name[=word] ...]
>   The given names are marked readonly; the values of these
> names may not be changed by subsequent assignment.  If the -f option is
> supplied, the functions
>   corresponding to the names are so marked.  The -a option

That man page quotation came out somewhat awkwardly.

I often find myself quoting man pages in email, so I have a shell
function for this scenario.  I call it "mailman", fully aware that
that's also the name of mailing list manager.  (Even if I ran it, I
wouldn't ever do so at an interactive shell prompt, because it's a
daemon.)

mailman () {
local cmd= opts=
case "$1" in
(-*)
opts="$opts $1"
shift
;;
esac

set -- $(man -w "$@")
cmd=$(zcat --force "$@" | \
grog -Tutf8 -b -ww -P -cbou -rU0 -rLL=72n -rHY=0 -dAD=l)
zcat --force "$@" | $cmd | less
}

This relies upon man-db man(1)'s `-w` option to locate the requested
pages (and it does the right thing if you specify file names, not just
page topics).

It also uses grog(1), much improved in groff 1.23.0 (released 5 July),
to figure out which preprocessor(s) and macro package the document
needs.

I'll walk through those groff options.

* `-Tutf8` formats for a UTF-8 terminal.
* `-P -cbou` passes options to grotty(1) to turn off all ISO
  6429/ECMA-48 escape sequences, _and_ all overstriking sequences; their
  formatting effects won't come through in plain text email anyway.
* `-rHY=0` turns off hyphenation.
* `-rLL=72n` sets the line length to 72 ens (character cells), which
  helps prevent ugly line wrapping.

Two options are new groff 1.23 features.

* `-rU0` turns off hyperlink support, so that any URIs in the man page
  will be formatted as text.  This is a new groff 1.23.0 feature.
* `-dAD=l` turns off adjustment (the spreading of output lines).

Two more options are ones I use, but maybe only maintainers of man pages
want them.

* `-b` produces backtraces for any formatter warnings or errors.
* `-ww` turns on all formatter warnings.

I hope people find this useful.


signature.asc
Description: PGP signature

Re: comments inside command subst are handled inconsistently

[G. Branden Robinson]

At 2023-07-31T16:08:31+0200, Denys Vlasenko wrote:
> There is no reason to innovate in tools such as sed, awk, or sh.

These are terrible examples to use; look at the history of all three.

> They have fossilized.

No, they've been _standardized_.  POSIX acknowledges that the common set
of expected functionality evolves; often to add features (see the
much-needed additions to standard make(1) in POSIX Issue 8, currently in
draft), but also to shrink in some necessary ways.  I think the Austin
Group (the POSIX team) deprecated gets() before WG14 (the C standard
committee) did.

> For example, you can add floating-point math to sh. This would be
> innovation.  This would also break many thousands of existing scripts,
> while being nowhere near enough for most serious uses of floating
> point calculations, both in speed and features.  Not a good idea.

It was done in ksh93.

Regards,
Branden


signature.asc
Description: PGP signature

Re: [PATCH] fix bind -X quoting

[G. Branden Robinson]

At 2023-07-31T09:30:30-0400, Chet Ramey wrote:
> Rather than embed more and more shell-specific output formats that
> readline doesn't parse into readline itself, I'm more inclined to add
> a hook to allow an application to print the value of a key binding
> itself.
[...]
> This would allow us, for instance, to really go wild and make `bind
> -X' display a series of `bind -x' commands to recreate the macro
> bindings.

I'm unlikely to be doing any of the work, but big +1 on this.  This
would be a valuable inspection and troubleshooting tool.  ("What does
bash _think_ I've got bound to this?")

Regards,
Branden


signature.asc
Description: PGP signature

Re: comments inside command subst are handled inconsistently

[G. Branden Robinson]

Hi Denys,

At 2023-07-31T13:38:00+0200, Denys Vlasenko wrote:
> On 7/28/23 19:51, Martin D Kealey wrote:
> > On the other hand, since everyone has now had 36+ years to update
> > their scripts to get rid of backticks,
> 
> I don't know about others, but I missed the memo that `` is
> deprecated.

The definitive "takedown" of `` is in Tom Duff's memo describing his
"rc" shell, which dates back to 1988-1991 or thereabouts.  (I wish I
could put a more precise date on it.)[1]

I'm attaching a copy for your edification.  Any use of a Bourne-derived
shell should read it and consider its points.

> The "function" keyword, for example. Why does it even exists?  It adds
> no functionality. When you use it, the only effect you get is that now
> your script requires bash to work properly.
> 
> (searching the net... looks like it's historic, added for
> compatibility with ksh).

Yes.  It'd be a better world if both `` quoting _and_ the "function"
keyword were retired.

Regards,
Branden

[1] It's possible Steve Bourne knew better but was pressured into
implementing the lexically simpler `` approach to command
substitution instead of recursively calling the parser (as Chet
pointed out) because it would be more performant.  John Mashey, the
author of the predecessor Unix shell (and successor to Ken
Thompson's original Unix shell) has gone on record as "goading"
Bourne into doing questionable things in the quest for speed.

https://www.in-ulm.de/~mascheck/bourne/segv.html


rc_A Shell for Plan 9 and Unix Systems_Duff.pdf
Description: rc_shell_tom_duff.pdf


signature.asc
Description: PGP signature

Re: Tilde (~) in bash(1) is typeset incorrectly as Unicode character

[G. Branden Robinson]

Hi Chet,

At 2023-07-29T13:16:55-0400, Chet Ramey wrote:
> On 7/28/23 3:28 PM, G. Branden Robinson wrote:
> > Sorry about that.  I fat-fingered it.
> > 
> > An 'n' is needed after the second backslash, because we're interpolating
> > a register value.
> 
> Thanks. I probably could have figured it out, but I figured I'd go to
> the expert.

The expert has let you down twice now.  :(

> That eliminates the warning, but unfortunately produces output that
> looks like this
> 
>~.nr need_eo_h 1 NAME
>bash - GNU Bourne-Again SHell
> 
>~.nr need_eo_h 1 SYNOPSIS
>bash [options] [command_string | file]
> 
> So something weird is happening with .SH. It doesn't matter whether I
> set it to 0 or 1 in bash.1. I'll just hold off on these definitions
> for now.

That _is_ weird.  I'll set aside some time to do this properly with a
dump of the page before and after to ensure no undesired changes.

This _looked_ like it should be trivial.  I should have known better.

Regards,
Branden


signature.asc
Description: PGP signature

Re: Tilde (~) in bash(1) is typeset incorrectly as Unicode character

[G. Branden Robinson]

Hi Chet,

At 2023-07-28T15:15:48-0400, Chet Ramey wrote:
> Applying the patch without any other changes to bash.1 results in
> 
> $ groff -Tascii -P -c -I/usr/local/src/bash/bash-20230728/doc -man
> /usr/local/src/bash/bash-20230728/doc/bash.1 > bash.0
> troff: /usr/local/src/bash/bash-20230728/doc/bash.1:26: warning: numeric
> expression expected (got a special character)
> 
> Where line 26 is the
> 
> .if \n(.g:(\(.f=0) \{\
> 
> test. This is macOS running groff-1.22.4 from MacPorts.

Sorry about that.  I fat-fingered it.

An 'n' is needed after the second backslash, because we're interpolating
a register value.

$ uname -a
Darwin gcc104.fsffrance.org 21.6.0 Darwin Kernel Version 21.6.0: Mon Aug 22 
20:20:05 PDT 2022; root:xnu-8020.140.49~2/RELEASE_ARM64_T8101 arm64
$ groff --version | head -n 1
GNU groff version 1.19.2
$ cat < .if \n(.g:(\n(.f=0) .tm this is groff or mandoc
> EOF
this is groff or mandoc

No syntax goof and no warning here.  (-ww turns on _all_ warnings.)

\n(xx is 50-year-old syntax and supported by all *roffs.

I apologize for my clumsiness.

Regards,
Branden


signature.asc
Description: PGP signature

Re: Tilde (~) in bash(1) is typeset incorrectly as Unicode character

[G. Branden Robinson]

Hi Chet,

At 2023-07-27T11:54:19-0400, Chet Ramey wrote:
> On 7/26/23 11:35 AM, G. Branden Robinson wrote:
> > Many projects don't need to worry about such extreme portability in
> > their man pages, but GNU Bash arguably does.  (I'm open to
> > correction.)
> 
> It's an ongoing struggle. There are projects (e.g., a 4.3BSD
> preservation effort) that request such accommodations, but it's
> becoming more difficult to support them.

I hear you.  Developing groff involves a bit of legacy awareness itself!

> > Furthermore, in the *roff language itself, as originally implemented
> > by Joe Ossanna (and re-implemented by Brian Kernighan) there is no
> > good way to test for the existence of a special character.[...]
> > 
> > As a first stab at it, I'd divide the world into two camps: (a)
> > groff and mandoc(1), and (b) everything else, and not worry about
> > (b).
> 
> I'd consider that, but, as you point out, there are some legacy Unix
> systems that still ship old versions of troff and associated tools.

I was unclear.  By "not worry about (b)", I meant "just define the
string contents as the same old ASCII character".  In retrospect I'm not
sure how anyone was supposed to figure that out from what I typed.

But that is in fact what I did in my suggested patch.  So it should be
highly portable, and I'm happy to support it.

> > The bash(1) man page has an extensive preamble already that still
> > includes a workaround for 4.3BSD(!), so adding a little bit to it to
> > accommodate systems developed since 1990 might not be too
> > disruptive.
> > 
> > I'm attaching a straw man diff to the bash(1) page.  If Chet likes
> > it, I'm happy to prepare one against the bash devel branch.
> 
> Thanks. I'll probably apply some variant of this to the set of man
> pages that need it.

Cool.

> > bash(1) also attempts to select a font named "CW" in places, which
> > is another portability problem (it's a Unix System III [and later]
> > troff font name that was available on _some_ output devices).  But
> > I'd like to see how we get over this bridge before I try to cross
> > that one.  :)
> 
> (For others reading, it's the constant width font, usually Courier.)

This history of the "CW" font name in *roff is becoming clearer to me
and I know of no other narrative about it, so I'm recording this for
posterity--and to invoke Cunningham's Law.[0]

To be precise, it is, or resembles, Courier roman (that is: upright, not
slanted; and of medium stroke weight).  On some output devices,
Documenter's Workbench 3.3 troff (ca. 1990) supported the Courier family
using the names C, CI, CB, and CX (roman, italic, bold, bold-italic).[1]
It also made the roman style available as "CW"--I assume for backward
compatibility with Unix System III (1980), where the brand-new
device-independent troff supported a phototypesetter that featured a
Courier-ish font and offered tools supporting it.[2]  This history is
pretty murky, though; this was commercial Unix troff and licenses for it
were expensive.  That is, I conjecture, the reason that BSD Unix had no
device-independent troff until it adopted groff in the Net/2 release
(1991).[3]  Therefore, device-independent troff font names tended not to
be portable to BSD Unix--not that they were often portable across output
devices anyway, a problem largely tamed nowadays by (1) the dominance of
the PostScript and PDF specifications in this sector, which establish a
base set of workaday typefaces; and (2) groff's insistence on
portability for a base set of font names wherever possible.[4]

Per the copyright page of the first edition of _The C Programming
Language_ (1978), Kernighan & Ritchie must have gotten the monospaced
font into the book because they acquired photographic plates for the
Graphic Systems (by then, Wang) C/A/T in a Courier face (apparently, in
roman only, because no other style was used).  This preceded
device-independent troff[5].  Perhaps by then, a tradition of calling
this face "CW" was entrenched--but I've yet to see any evidence of it in
Seventh Edition Unix (1979).  Possibly its only application was in the
troff sources for the book itself (and the related "C Reference
Manual"), which Prentice-Hall still treats like a trade secret.

> I haven't received any bug reports about that, and groff and mandoc
> both support it, so I'm inclined to leave it alone.

You might start to receive them; stock groff 1.23.0 now produces
font-related diagnostics in many situations where groff 1.22.4 and
earlier did not.[6]  Colin Watson has patched Debian's groff-base
package to suppress this one when man pages are being formatted for
te

Re: Tilde (~) in bash(1) is typeset incorrectly as Unicode character

[G. Branden Robinson]

Hi Thomas,

At 2023-07-26T10:47:05+0200, Thomas ten Cate wrote:
> In the bash manual page (`man bash`), the ASCII tilde character '~'
> (0x7e) is replaced by the Unicode character '˜' (U+02DC SMALL TILDE):
> 
> $ man bash | grep 'additional binary operator'
>   An additional binary operator, =˜, is available,
> 
> The same happens for the use of ~ as a shorthand for the home
> directory. This makes the manual page incorrect, and difficult to
> search.
> 
> It looks like there is an ASCII tilde character in the man page's
> source code:
> 
> $ gunzip -c /usr/share/man/man1/bash.1.gz | grep 'additional
> binary operator'
> An additional binary operator, \fB=~\fP, is available, with the same
> 
> I don't know the first thing about groff, but `man groff_char`
> suggests that ~ is indeed rendered as "modifier tilde", and that one
> should write \(ti to obtain an actual tilde character.

I know a little about groff.  Your advice is fine for man pages that
target only groff[1] and/or mandoc[2], but not Heirloom Doctools
troff,[3] neatroff[4] or Plan 9 troff (in its original form or as
maintained in Plan 9 from User Space[5]), and not legacy implementations
descended from AT&T troff that are, as far as I can tell, unmaintained
by the few Unix System V vendors that still exist.[6][7]

Many projects don't need to worry about such extreme portability in
their man pages, but GNU Bash arguably does.  (I'm open to correction.)

Furthermore, in the *roff language itself, as originally implemented by
Joe Ossanna (and re-implemented by Brian Kernighan) there is no good
way to test for the existence of a special character.[8]

As a first stab at it, I'd divide the world into two camps: (a) groff
and mandoc(1), and (b) everything else, and not worry about (b).

The bash(1) man page has an extensive preamble already that still
includes a workaround for 4.3BSD(!), so adding a little bit to it to
accommodate systems developed since 1990 might not be too disruptive.

I'm attaching a straw man diff to the bash(1) page.  If Chet likes it,
I'm happy to prepare one against the bash devel branch.

bash(1) also attempts to select a font named "CW" in places, which is
another portability problem (it's a Unix System III [and later] troff
font name that was available on _some_ output devices).  But I'd like to
see how we get over this bridge before I try to cross that one.  :)

> I'm guessing the manpage is generated from texinfo, so if this is
> actually a bug in texinfo, feel free to forward this email to
> bug-texinfo at gnu.org.

I don't think that's actually true.  As far as I know, Chet maintains
Bash's Texinfo docs and man pages in parallel by hand.

Regards,
Branden

[1] https://www.gnu.org/software/groff/
[2] https://mandoc.bsd.lv/
[3] https://github.com/n-t-roff/heirloom-doctools
[4] https://github.com/aligrudi/neatroff
[5] https://github.com/9fans/plan9port

[6] HP-UX 11 appears to still ship an AT&T/DWB or System V troff.
Solaris 10 does, but it is nearing end-of-life and Solaris 11
replaced its troff (of similar lineage as HP-UX's) with groff.

[7] It is also not hard to make AT&T-descended troffs support the
`ha` and `ti` special characters.  For instance, here's a patch to
Documenter's Workbench (DWB) 3.3 troff's "Latin1" output device.

--- R.orig  2023-07-26 09:55:30.527340674 -0500
+++ R   2023-07-26 09:58:49.658662373 -0500
@@ -68,6 +68,7 @@
 bs "
 ]  33  3   93
 ^  33  2   147
+ha "
 ---47  2   94
 ---50  1   95
 `  33  2   96
@@ -101,6 +102,7 @@
 ---20  2   124
 }  48  3   125
 ~  33  2   148
+ti "
 ---54  0   126
 \` 33  2   145
 ga "

But even after 30+ years since groff emerged on the scene, I'm not
aware of a single such troff having done this.

[8] A clever *roff hacker could try using the output comparison operator
and width computation escape sequence to measure of a candidate
special character, but this would not be reliable.  The output
drivers of AT&T device-independent troff appear to format
unrecognized characters as blanks (putting horizontal motions on the
output).  (groff does not, throwing an error diagnostic instead.)[9]
But if a special character did exist and happened to be the same
width as such a blank character, this test would produce a false
negative.  Worse, on nroff-mode devices, including the terminal
emulators that 99% of all man page reading is done, _all_ glyphs are
the same width, so you'd get false negatives all the time.

[9] This is a groff/AT&T troff difference that I don't think is
documented by groff.  Maybe I should fix that.
--- bash.1.orig	2023-07-26 10:19:18.770924818 -0500
+++ bash.1	2023-07-26 10:22:48.554457262 -0500
@@ -26,6 +26,22 @@
 .if !rzY .nr zY 0 \" avoid a warning about an undefined register
 .if \n(zZ=1 .ig zZ
 .if \n(zY=1 .ig zY
+.

Re: Should Use Straight Single Quote instead of Curved

[G. Branden Robinson]

At 2023-05-06T08:06:40+, Shynur Xie wrote:
> Should Use Straight Single Quote instead of Curved
> 
> View this page
> 
> in browser:
> 
> > Character sequences of the form $’string’ are treated as a special
> > kind of single quotes.
> 
> should be
> 
> > Character sequences of the form $'string' are treated as a special
> > kind of single quotes.

Here's a patch.

diff --git a/doc/bashref.texi b/doc/bashref.texi
index 3263a73c..74548126 100644
--- a/doc/bashref.texi
+++ b/doc/bashref.texi
@@ -475,8 +475,8 @@ @node Top
 @subsubsection ANSI-C Quoting
 @cindex quoting, ANSI

-Character sequences of the form $'@var{string}' are treated as a special
-kind of single quotes.
+Character sequences of the form @code{$'@var{string}'} are treated as a
+special kind of single quotes.
 The sequence expands to @var{string}, with backslash-escaped characters
 in @var{string} replaced as specified by the ANSI C standard.
 Backslash escape sequences, if present, are decoded as follows:

Regards,
Branden


signature.asc
Description: PGP signature

Re: Arithmetic expression: evaluation order bug

[G. Branden Robinson]

At 2023-01-04T10:22:15-0500, Chet Ramey wrote:
> On 12/30/22 3:44 PM, Steffen Nurpmeso wrote:
> 
> > Digital, logical, liberal, yuck :)
> 
> We channeling Supertramp here?

🤣

Some listen to the birds in the trees singing so happily...

..and some spend their years watching the moon bear wank himself off.

Regards,
Branden


signature.asc
Description: PGP signature

Re: [bash 4] 'test -v 1' is never true

[G. Branden Robinson]

Hi Alex,

At 2022-11-25T22:02:46+0100, Alejandro Colomar wrote:
> I wrote a script, and am trying it on many systems.  On RHEL8, which
> has bash 4, it didn't work.  I could reduce the problem to the
> following command, which never returns true:
> 
> test -v 1;
> 
> In Debian Sid, where I develop, and where I have bash 5, that works
> fine, and is true if the function or script in which it is has any
> arguments.  On zsh(1) it also works fine.
> 
> Is this a known bug in bash?
> The exact version where I can reproduce it is 4.4.20(1)-release
> (x86_64-redhat-linux-gnu).

I don't think it is a bug.  It is unspecified behavior according to
POSIX.

"-v" is not an operator according to POSIX, and I don't recall seeing it
in any shell.  It is therefore interpreted as a string argument.

  The algorithm for determining the precedence of the operators and the
  return value that shall be generated is based on the number of
  arguments presented to test. (However, when using the "[...]" form,
  the right-bracket final argument shall not be counted in this
  algorithm.)

  In the following list, $1, $2, $3, and $4 represent the arguments
  presented to test:

  0 arguments:
  Exit false (1).
  1 argument:
  Exit true (0) if $1 is not null; otherwise, exit false.
  2 arguments:

  If $1 is '!', exit true if $2 is null, false if $2 is not
  null.

  If $1 is a unary primary, exit true if the unary test is true,
  false if the unary test is false.

  Otherwise, produce unspecified results.

https://pubs.opengroup.org/onlinepubs/009695299/utilities/test.html

Regards,
Branden


signature.asc
Description: PGP signature

Re: Light weight support for JSON

[G. Branden Robinson]

At 2022-08-28T15:52:55-0400, Lawrence Velázquez wrote:
> On Sun, Aug 28, 2022, at 2:56 PM, G. Branden Robinson wrote:
> > How about next July, when JSON is as exactly old as the Bourne shell
> > was when JSON was deployed?
> 
> I do not find "well *actually* JSON is old too!!!" to be particularly
> persuasive, either.

It's a perfectly valid rejoinder to a claim that the format is too novel
to be seriously considered.  That you don't regard it as persuasive is
consistent with your protest not being a rational one in the first
place; one doesn't get reasoned out of what one wasn't reasoned into.

> I should have foreseen that the offhand "of the month" jab would
> get undue attention compared to my actual objection, which is against
> giving one data format uniquely first-class support.  That's on me.

That's right.  Don't pad your brief with makeweight objections,
particularly when their ultimate weight is feeble.

> Sick burn, pal.  Excuse me while I take out my dentures or whatever.

Fortunately for you, I reckon that even with mushmouthed enunciation,
the kids wont't have any trouble understanding that you want them to get
off your lawn.

Why stomp on the newbies' ideas with two feet when one will do?

Regards,
Branden


signature.asc
Description: PGP signature

Re: Light weight support for JSON

[G. Branden Robinson]

At 2022-08-28T14:11:25-0400, Lawrence Velázquez wrote:
> I do not think bash needs to sprout functionality to support every
> data-exchange format of the month.

This sentiment is illustrative of the logarithmic memory scale of
grognards.  The Bourne shell was first released as part of Version 7
Unix in January 1979.[1]  22 years and three months later, in April
2001, Douglas Crockford and Chip Morningstar sent the first JSON
message.[2]

> A loadable module might be okay, I guess.

How about next July, when JSON is as exactly old as the Bourne shell was
when JSON was deployed?

> Why are people so allergic to just using specific utilities for
> specific tasks, as appropriate?  (This question is rhetorical.
> Please do not respond with an impassioned plea about why JSON is
> so special that it deserves first-class shell support.  It's not.)

I won't litigate this point, but your concept of novelty is distorted
beyond any standard reasonable in the computer industry.  If we are only
as young as we feel, you must feel geriatric in the extreme.

Regards,
Branden

[1] https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7
[2] https://www.toptal.com/web/json-vs-xml-part-1


signature.asc
Description: PGP signature

Re: Documentation Error

[G. Branden Robinson]

At 2022-06-08T12:05:06-0500, mcmuffin6o wrote:
> In section 3.5.3 Shell Parameter Expansion:
> 
> In the sixth paragraph it correctly states that "Bash tests for a
> parameter that is unset *or* null" when you use the colon. It later
> attempts to restate this but fails by saying "if the colon is
> included, the operator tests for both parameter's existence *and* that
> its value is not null"

This is an application of DeMorgan's Law to English prose.  I will
translate the clauses into pseudo-C.

"Bash tests for a parameter that is unset *or* null"

if ((!set) || (!has_content))

"the operator tests for both parameter's existence *and* that its value
is not null"

if (set && has_content)

Regards,
Branden


signature.asc
Description: PGP signature

[PATCH] Prefer non-gender specific pronouns

[G. Branden Robinson]

Hi Chet,

Here you go, if you're inclined.  Minimally invasive and decidedly
non-revolutionary in terms on English lexicon.

Patch attached.

At 2021-06-05T23:29:58-0400, Lawrence Velázquez wrote:
>   doc/oldbash.texi
>   178:manual.  Brian and Diane would like to thank Chet Ramey for his
>   9138:# The alternative explanation is that his frequent use of the

My "git grep" didn't turn this file up anyway.  Maybe I'm on the wrong
branch?

> That's three.  Pretty tractable for anyone so inclined.  (Didn't
> look at source code comments or anything.)

Thanks, Lawrence!

Regards,
Branden
From 2f831676ea69b64c4a8a44be7a675253e78527ce Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" 
Date: Sun, 6 Jun 2021 14:22:41 +1000
Subject: [PATCH] [docs]: Adopt gender-indifferent language.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Noted by Vipul Kumar and Lawrence Velázquez on the bug-bash list[1].

[1] https://lists.gnu.org/archive/html/bug-bash/2021-06/msg8.html
---
 doc/bashref.texi | 2 +-
 lib/readline/doc/rltech.texi | 2 +-
 lib/readline/doc/rluser.texi | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/bashref.texi b/doc/bashref.texi
index 9e23f586..7ba3c448 100644
--- a/doc/bashref.texi
+++ b/doc/bashref.texi
@@ -7671,7 +7671,7 @@ The restricted shell mode is only one component of a useful restricted
 environment. It should be accompanied by setting @env{PATH} to a value
 that allows execution of only a few verified commands (commands that
 allow shell escapes are particularly vulnerable), leaving the user
-in a non-writable directory other than his home directory after login,
+in a non-writable directory other than @env{HOME} after login,
 not allowing the restricted shell to execute shell scripts, and cleaning
 the environment of variables that cause some commands to modify their
 behavior (e.g., @env{VISUAL} or @env{PAGER}).
diff --git a/lib/readline/doc/rltech.texi b/lib/readline/doc/rltech.texi
index bbf57c23..c3567a61 100644
--- a/lib/readline/doc/rltech.texi
+++ b/lib/readline/doc/rltech.texi
@@ -1611,7 +1611,7 @@ main (int c, char **v)
 
 Signals are asynchronous events sent to a process by the Unix kernel,
 sometimes on behalf of another process.  They are intended to indicate
-exceptional events, like a user pressing the interrupt key on his terminal,
+exceptional events, like a user pressing the interrupt key on the terminal,
 or a network connection being broken.  There is a class of signals that can
 be sent to the process currently reading input from the keyboard.  Since
 Readline changes the terminal attributes when it is called, it needs to
diff --git a/lib/readline/doc/rluser.texi b/lib/readline/doc/rluser.texi
index 26b0ff07..62df6ceb 100644
--- a/lib/readline/doc/rluser.texi
+++ b/lib/readline/doc/rluser.texi
@@ -339,7 +339,7 @@ Although the Readline library comes with a set of Emacs-like
 keybindings installed by default, it is possible to use a different set
 of keybindings.
 Any user can customize programs that use Readline by putting
-commands in an @dfn{inputrc} file, conventionally in his home directory.
+commands in an @dfn{inputrc} file, conventionally in @env{HOME}.
 The name of this
 @ifset BashFeatures
 file is taken from the value of the shell variable @env{INPUTRC}.  If
-- 
2.20.1



signature.asc
Description: PGP signature

Re: loadables/rm not POSIX compliant

[G. Branden Robinson]

At 2019-05-28T17:01:52+0200, Tim Rühsen wrote:
> Since distributions like Debian doesn't deliver binaries from
> examples/,

That doesn't sound accurate to me.  The Debian Policy Manual, §12.6,
encourages the shipping of examples:

https://www.debian.org/doc/debian-policy/ch-docs.html#examples

In fact, the bash-doc package contains dozens of examples.  However, I
don't see anything named "rm".  (I'm looking at bash-doc 5.0-4 in Debian
10, "buster".)

> how can we get the rm loadable into builtins/ ? (What is
> missing that has to be done).

I suggest you file a wishlist bug--or update an existing one, as
appropriate--requesting the shipment of the rm loadable as an example if
it's being omitted from the set of artifacts produced by the bash source
build.

Debian may not want to push the loadable into the default configuration
for similar reasons that Chet doesn't as the upstream.  But if it's
shipped, the user can enable it discretionarily.

Regards,
Branden


signature.asc
Description: PGP signature

Re: readline: How to unbind _all_ keys

[G. Branden Robinson]

At 2019-05-19T16:43:41+0200, Henning wrote:
> I don't like to have dozens of key bindings I never use. Currently I
> am issuing lots of lots of bind -r/-u commands to get rid of the
> default bindings. This slows down console startup unnecessarily.
> 
> I would really like to have an inputrc command like $removeall or
> something like bind -r/-u all.
> Or is there something undocumented for this purpose?
> 
> And yes, I know, it's soo dangerous.

Not dangerous--pointless.  You might as well just close standard input.

Remember that "self-insert" is a binding.

If you removed all bindings, no keystrokes would do _anything_.

You'll also need a binding for "accept-line", or you have no way to tell
readline you're done entering a command.

I think what you're asking for is some switch to just rebind all keys to
"self-insert", except for C-j and C-m, which would go to "accept-line".
This, I can imagine maybe having some utility.  I can't speak for Chet,
however.

Regards,
Branden


signature.asc
Description: PGP signature

Re: Should [[ -v 1 ]] be supported?

[G. Branden Robinson]

At 2018-12-27T19:47:08-0600, Peng Yu wrote:
> On Thu, Dec 27, 2018 at 7:37 PM G. Branden Robinson
> > As others have noted, if you are worried about marginal performance
> > impacts this small, margin you are probably writing in the wrong
> > language, or distracting yourself with tiny details when you do not even
> > know the cyclomatic complexity of your code or the big-O classification
> > of your algorithms.
> >
> > Attack those problems first, and see what you discover.
> 
> The problem is that bash is not systematically profiled for
> performance at all. I am doing it step it by step.

You're whacking moles.  Use a profiler.  That's what they're for.

https://www.thegeekstuff.com/2012/08/gprof-tutorial/

> There are many more that I have already tested. You can not dismiss
> this one just because it may not have a large impact.

Yes, I can.  You need to identify where bash is _actually_ spending most
of its execution time, and a profiler can help you do that.

You also need to establish acceptance criteria.  All but the most
finely-tuned code can be made more performant; often raw performance
comes at a cost, such as the abandonment of memory safety.  Aliasing
problems are one example in software, and the Spectre and Meltdown
suites of cache-related timing attacks are an examples from hardware.

What is it you're trying to achieve?  State your goal in terms that are
"SMART":

(S)pecific
(M)easurable
(A)ttainable
(R)easonable
(T)imely

Just the first four would be a good start.

Regards,
Branden


signature.asc
Description: PGP signature

Re: How to compile hashlib.c for testing?

[G. Branden Robinson]

At 2018-12-27T17:34:49-0800, Eduardo Bustamante wrote:
> On Thu, Dec 27, 2018 at 5:15 PM Peng Yu  wrote:
> (...)
> > Since the main() function is already there, why there is not already
> > an easy way to compile it? How do you do unit-testing then for the
> > code?
> 
> This is very easy to figure out from the source code, right :)?
> 
> (Hint: there is no "unit" testing in bash)

Au contraire!  :-D

https://github.com/kward/shunit2

Regards,
Branden


signature.asc
Description: PGP signature

Re: Should [[ -v 1 ]] be supported?

[G. Branden Robinson]

At 2018-12-27T19:24:22-0600, Peng Yu wrote:
> > I don't believe that at all. The number of positional parameters is kept
> > anyway. It's not recalculated when you compare it to another number, so
> > it's just as fast as a simple comparison of two integers.
> 
> Getting the number $# is slow.

By what metric, and how do you know?

Regards,
Branden


signature.asc
Description: PGP signature

Re: Should [[ -v 1 ]] be supported?

[G. Branden Robinson]

At 2018-12-27T18:39:26-0600, Peng Yu wrote:
> What I meant in my original email is that I want something for testing
> if there is a command line argument (one or more, the exact number
> does not matter). $# gives more than that info, because it tells not
> only whether is any command line argument, but also how many. This
> could lead to slower performance if the goal is to just test if there
> is an argument.

You should look into how integer comparisons are done in hardware.

For instance, comparison and subtraction operations are often comparable
(or even identical) in cycle count because they both perform a
subtraction "under the hood".  You need to be programming in assembly
language to influence execution at such depths.

See, e.g.,

https://www.quora.com/What-is-the-difference-between-cmp-and-sub-instruction-in-8086microprocessor

As others have noted, if you are worried about marginal performance
impacts this small, margin you are probably writing in the wrong
language, or distracting yourself with tiny details when you do not even
know the cyclomatic complexity of your code or the big-O classification
of your algorithms.

Attack those problems first, and see what you discover.

Regards,
Branden


signature.asc
Description: PGP signature

Re: Bash-5.0-beta2 available for download

[G. Branden Robinson]

gcc -c   -DHAVE_CONFIG_H -DSHELL  -I. -I..  -I.. -I../include -I../lib -I.  
-DDEBUG  -g -O2 -Wno-parentheses -Wno-format-security evalstring.c
evalstring.c: In function ‘parse_and_execute_cleanup’:
evalstring.c:150:7: warning: implicit declaration of function 
‘unfreeze_jobs_list’; did you mean ‘unfreeeze_jobs_list’? 
[-Wimplicit-function-declaration]
   unfreeze_jobs_list ();
   ^~
   unfreeeze_jobs_list

--- jobs.h.orig 2018-11-27 18:35:43.205649329 -0500
+++ jobs.h  2018-11-27 18:35:51.049574540 -0500
@@ -260,7 +260,7 @@
 extern void run_sigchld_trap __P((int));
 
 extern int freeze_jobs_list __P((void));
-extern void unfreeeze_jobs_list __P((void));
+extern void unfreeze_jobs_list __P((void));
 extern void set_jobs_list_frozen __P((int));
 extern int set_job_control __P((int));
 extern void without_job_control __P((void));

-- 
Regards,
Branden


signature.asc
Description: PGP signature

variable containing syntax error in conditional expression reports no diagnostics

[g . branden . robinson]

Configuration Information [Automatically generated, do not change]:
Machine: x86_64
OS: linux-gnu
Compiler: gcc
Compilation CFLAGS:  -DPROGRAM='bash' -DCONF_HOSTTYPE='x86_64' 
-DCONF_OSTYPE='linux-gnu' -DCONF_MACHTYPE='x86_64-unknown-linux-gnu' 
-DCONF_VENDOR='unknown' -DLOCALEDIR='/users/brarobin/share/locale' 
-DPACKAGE='bash' -DSHELL -DHAVE_CONFIG_H   -I.  -I. -I./include -I./lib   -g -O2
uname output: Linux cc-dev-2 2.6.18-404.el5 #1 SMP Sat Mar 7 04:14:13 EST 2015 
x86_64 x86_64 x86_64 GNU/Linux
Machine Type: x86_64-unknown-linux-gnu

Bash Version: 4.3
Patch Level: 30
Release Status: release

Description:
I get a [[ ]] test failure with no error diagnostic, tricking me
into thinking the test legitimately failed when the culprit was
really a bad regex.

Repeat-By:
Constrast:

$ [[ foo =~ ) ]] && echo match || echo no match
bash: syntax error in conditional expression: unexpected token `)'
bash: syntax error near `)'

$ REGEX=')'
$ $ [[ foo =~ $REGEX ]] && echo match || echo no match
no match

end