Re: SHELLOPTS environment variable causes shell options to cascade

At 2025-01-05T18:59:57+1000, Martin D Kealey wrote: > On Sun, 5 Jan 2025 at 15:18, Oğuz wrote: > > This is documented in the manual: > > In other words, it's broken by design. Well, pull out of your back pocket what you've been coyly keeping from us--a programming language that occupies global o

Re: [PATCH 9/9] doc/bash.1: Resync w/ lib/readline/doc/readline.3.

At 2024-12-31T13:05:30-0500, Chet Ramey wrote: > On 12/30/24 8:16 PM, G. Branden Robinson wrote: > Since I maintain six separate documents, the style I choose usually > depends on the style for the document where a particular piece of text > originates. Fair, but having different l

Re: [PATCH 6/9] Slightly revise documentation of POSIX mode.

At 2024-12-31T12:35:15-0500, Chet Ramey wrote: > On 12/30/24 8:29 PM, G. Branden Robinson wrote: > > At 2024-12-30T12:40:48-0500, Chet Ramey wrote: > > > On 12/16/24 12:48 PM, G. Branden Robinson wrote: > > > > * doc/bash.1: Introduce "POSIX mode" earli

Re: [PATCH 5/9] doc/bash.1: Stop manipulating adjustment.

I need to correct a point in my own explanation. No revision to the patch itself is necessary. At 2024-12-16T11:48:15-0600, G. Branden Robinson wrote: > Since AT&T troff also lacks a feature for hyphenless discretionary > breaks (groff's `\%`), I of course meant `\:` here. If yo

Re: [PATCH 6/9] Slightly revise documentation of POSIX mode.

Hi Chet, At 2024-12-30T12:40:48-0500, Chet Ramey wrote: > On 12/16/24 12:48 PM, G. Branden Robinson wrote: > > * doc/bash.1: Introduce "POSIX mode" earlier in the document. Set > > the word "POSIX" in small caps (as traditionally done for acronyms) > &g

Re: [PATCH 9/9] doc/bash.1: Resync w/ lib/readline/doc/readline.3.

Hi Chet, At 2024-12-30T11:23:06-0500, Chet Ramey wrote: > On 12/16/24 12:48 PM, G. Branden Robinson wrote: > > > Favor man(7) font selection/alternation macros over roff(7) font > > selection escape sequences. > > In general, I don't do this when it makes the man

Re: [PATCH 3/9] doc/bash.1, doc/bashref.texi: Align wording.

At 2024-12-30T11:12:12-0500, Chet Ramey wrote: > On 12/16/24 12:47 PM, G. Branden Robinson wrote: > > The > > @option{--norc} > > -option inhibits this behavior, and the > > -@option{--rcfile} > > -option makes Bash use a different file instead of > >

[PATCH 9/9] doc/bash.1: Resync w/ lib/readline/doc/readline.3.

Break lines in similar places; this eases diffing. Apply wording change that didn't get reflected in bash.1, and correct inadvertently boldfaced text. Favor man(7) font selection/alternation macros over roff(7) font selection escape sequences. --- doc/bash.1 | 15 ++-

[PATCH 8/9] doc/bash.1: Recast lead sentence.

Mention (Stephen) Bourne and his shell's origin in Unix. The Bourne shell, like the rest of Seventh Edition Unix, has been Free Software (albeit GPL-incompatible) for a couple of decades now. It should therefore be okay to more clearly cite precedent without RMS materializing to chide us for utte

[PATCH 6/9] Slightly revise documentation of POSIX mode.

* doc/bash.1: Introduce "POSIX mode" earlier in the document. Set the word "POSIX" in small caps (as traditionally done for acronyms) to parallel the typesetting of the "bashref" Texinfo manual. Also set the phrase "POSIX mode" in italics, but only on the introduction of the term. Do not

[PATCH 7/9] Improve bash.1 man page/bashref.texi alignment.

Break lines in the same places for ease of diffing and maintenance. Parallelize/copy material to align the documents more closely. Favor man(7) font selection/alternation macros over roff(7) font selection escape sequences. Protect more literals from hyphenation. Quote the `+=` operator in the

[PATCH 5/9] doc/bash.1: Stop manipulating adjustment.

Unfortunately, the *roff `ad` request doesn't work like everyone seems to think it does. When invoked without an argument, it does not mean "restore whatever the previous adjustment mode was before I invoked `na` to turn off adjustment". Instead, it means "make sure lines are adjusted regardless

[PATCH 2/9] doc/bash.1: Document approach to conditional text.

--- doc/bash.1 | 5 - 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/bash.1 b/doc/bash.1 index e58c1e8a..54ebb696 100644 --- a/doc/bash.1 +++ b/doc/bash.1 @@ -7,7 +7,10 @@ .\" .\"Last Change: Thu Dec 12 13:37:07 EST 2024 .\" -.\" bash_builtins, strip all but Builtins s

[PATCH 4/9] doc/bash.1: Fix macro usage nit.

We want the comma in roman, not bold. an.tmac:doc/bash.1:9432: style: .BR expects at least 2 arguments, got 1 (Use `-r CHECKSTYLE=4` with groff 1.23.0 to obtain the foregoing style warning.) --- doc/bash.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/bash.1 b/doc/bash.

[PATCH 3/9] doc/bash.1, doc/bashref.texi: Align wording.

* Perform Kemper notectomy. * Break lines in the same places to ease diffing. * Align verb tenses. --- doc/bash.1 | 11 ++- doc/bashref.texi | 28 2 files changed, 22 insertions(+), 17 deletions(-) diff --git a/doc/bash.1 b/doc/bash.1 index 54ebb696..676

[PATCH 1/9] Adjust style of "export-completions" documentation.

* doc/bash.1: + Drop explicit `sp` request in favor of inter-paragraph spacing. + Set items returned by Readline command as bulleted list. + Identify "N" as the parameter replaced by the number of matches. + Set "readline" in boldface, for consistency with rest of page. + Set parameters "

Re: [PATCH 09/25] doc/bashref.texi: Favor present tense over future.

24-11-21T22:21:07-0600, G. Branden Robinson wrote: > --- > doc/bashref.texi | 103 +-- > 1 file changed, 54 insertions(+), 49 deletions(-) > > diff --git a/doc/bashref.texi b/doc/bashref.texi > index ffaa863b..74581695 100644 > ---

[PATCH 03/25 v2] doc/bash.1: Clarify program/man page reference.

At 2024-11-22T07:09:27-0500, Greg Wooledge wrote: > On Thu, Nov 21, 2024 at 22:19:13 -0600, G. Branden Robinson wrote: > > diff --git a/doc/bash.1 b/doc/bash.1 > > index 23a8dbd6..6c864eab 100644 > > --- a/doc/bash.1 > > +++ b/doc/bash.1 > > @@ -6962,7 +6962,8 @@

[PATCH 22/25] doc/bash.1: Drop extraneous interword spaces.

--- doc/bash.1 | 4 ++-- doc/bashref.texi | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/bash.1 b/doc/bash.1 index dd58e0d1..160c7b50 100644 --- a/doc/bash.1 +++ b/doc/bash.1 @@ -4102,7 +4102,7 @@ .SS Word Splitting and passed to commands as empty strings. Unquo

[PATCH 14/25] doc/bash.1: Set `-@` argument to `cd` in bold.

It's literal, just like the options `-L`, `-P`, and `-e`. --- doc/bash.1 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/bash.1 b/doc/bash.1 index 342ad823..d547c330 100644 --- a/doc/bash.1 +++ b/doc/bash.1 @@ -8987,9 +8987,9 @@ .SH "SHELL BUILTIN COMMANDS" call stack.

[PATCH 23/25] Fix which/that grammar nit.

Use "that", not "which", with restrictive clause. --- doc/bash.1 | 2 +- lib/readline/doc/readline.3 | 2 +- lib/readline/doc/rluser.texi | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/bash.1 b/doc/bash.1 index 160c7b50..f44d156e 100644 --- a/doc/bash

[PATCH 25/25] Style redirection operators consistently.

In bash.1, set them in bold like other operators in this document. Also escape their hyphens. Use `Q` local quotation macro to quote individual characters of a redirection operator where these are called out for discussion. This is also a better parallel with bashref.texi's use of the Texinfo `s

[PATCH 11/25] Synchronize comments on *roff syntax.

Clarify what's "not usable", and make parallel between the man pages. --- doc/bash.1 | 6 -- lib/readline/doc/history.3 | 9 - lib/readline/doc/readline.3 | 9 - 3 files changed, 20 insertions(+), 4 deletions(-) diff --git a/doc/bash.1 b/doc/bash.1 index 036a

[PATCH 15/25] lib/readline/doc/*.3: Use local `Q` macro for quotation.

--- lib/readline/doc/history.3 | 8 ++-- lib/readline/doc/readline.3 | 4 +++- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/lib/readline/doc/history.3 b/lib/readline/doc/history.3 index e236bb15..381d1fb5 100644 --- a/lib/readline/doc/history.3 +++ b/lib/readline/doc/history

[PATCH 21/25] Improve presentation of symbolic character names.

Since so many are synonymous, say so and organize them into pairs. Sync rluser.texi's wording with that of bash.1 and readline.3. --- doc/bash.1 | 28 +--- lib/readline/doc/readline.3 | 28 +--- lib/readline/doc/rluser.texi | 28 +

[PATCH 24/25] doc/bash.1: Protect some literals from hyphenation.

Fixes: $ nroff -rLL=80n -man -Tascii doc/bash.1 | grep -E '(FUNC|INPU)-' ists only when a shell function is executing. Assignments to FUNC- BASH_SOURCE to describe the call stack. For instance, ${FUNC- inputrc file). The name of this file is taken from the val

[PATCH 20/25] Fix missing interword spaces.

--- doc/bash.1 | 3 ++- lib/readline/doc/readline.3 | 3 ++- lib/readline/doc/rluser.texi | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/doc/bash.1 b/doc/bash.1 index fe87c7e7..c6d60aa9 100644 --- a/doc/bash.1 +++ b/doc/bash.1 @@ -6448,7 +6448,8 @@ .SS "

[PATCH 19/25] Spell key sequences with spaces, not hyphens.

The hyphen indicates simultaneity, not sequence. Also use Texinfo `kbd` command to denote key strokes in parallel material in rluser.texi. --- doc/bash.1 | 9 ++--- lib/readline/doc/readline.3 | 9 ++--- lib/readline/doc/rluser.texi | 7 +-- 3 files changed, 17 inse

[PATCH 18/25] Style keyboard literals consistently.

Use italics for them, not bold, to align with the preponderance of usage. Also use man(7) font style alternation macros instead of *roff escape sequences for adjacent roman and italic type. In groff man(7), this gets you automatic italic corrections. Sync rluser.texi's input line break points wi

[PATCH 16/25] Document common arrow key bindings.

--- doc/bash.1 | 4 lib/readline/doc/readline.3 | 2 ++ lib/readline/doc/rluser.texi | 4 3 files changed, 10 insertions(+) diff --git a/doc/bash.1 b/doc/bash.1 index d547c330..658bed68 100644 --- a/doc/bash.1 +++ b/doc/bash.1 @@ -7251,9 +7251,11 @@ .SS Commands for M

[PATCH 17/25] Respell "C-J" with a lowercase j.

...like every other documented Control+letter combination. --- doc/bash.1 | 6 +++--- lib/readline/doc/readline.3 | 6 +++--- lib/readline/doc/rluser.texi | 4 ++-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/bash.1 b/doc/bash.1 index 658bed68..f700a736 10

[PATCH 13/25] lib/readline/doc/history.3: Use consistent style.

Set `struct _hist_entry` declaration in a constant-width face on typesetters as is already done with `struct _hist_state`. --- lib/readline/doc/history.3 | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/readline/doc/history.3 b/lib/readline/doc/history.3 index 09d5ee21..e236bb15 100644 --

[PATCH 12/25] lib/readline/doc/history.3: Silence groff warning.

...without interfering with the test for DWB man(7) we do subsequently. Fixes: $ nroff -ww -z -man ./lib/readline/doc/history.3 troff:./lib/readline/doc/history.3:29: warning: register ')Y' not defined --- lib/readline/doc/history.3 | 1 + 1 file changed, 1 insertion(+) diff --git a/lib/readline

[PATCH 09/25] doc/bashref.texi: Favor present tense over future.

--- doc/bashref.texi | 103 +-- 1 file changed, 54 insertions(+), 49 deletions(-) diff --git a/doc/bashref.texi b/doc/bashref.texi index ffaa863b..74581695 100644 --- a/doc/bashref.texi +++ b/doc/bashref.texi @@ -554,7 +554,7 @@ @node Top Prefixing a

[PATCH 10/25] doc/bash.1: Remove stray *roff syntax.

No string named `/` is defined in this document. Fixes: troff:./doc/bash.1:5221: warning: macro '/' not defined --- doc/bash.1 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/bash.1 b/doc/bash.1 index 9223dd46..036ab2ae 100644 --- a/doc/bash.1 +++ b/doc/bash.1 @@ -52

[PATCH 08/25] doc/bashref.texi: Use typesetter's quotation marks.

--- doc/bashref.texi | 7 --- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/bashref.texi b/doc/bashref.texi index e8db1bfe..ffaa863b 100644 --- a/doc/bashref.texi +++ b/doc/bashref.texi @@ -7068,9 +7068,10 @@ @node Top The @samp{numeric} specifier treats names consisting

[PATCH 05/25] doc/bash.1, doc/bashref.texi: Resync.

Break lines in similar places; this eases diffing. Also apply wording changes that didn't get reflected in bashref.texi or bash.1, preferring whichever edit was more recent. --- doc/bash.1 | 74 +-- doc/bashref.texi | 153 +--

[PATCH 07/25] doc/bashref.texi: Add internal cross reference.

bash.1 has one in the same place. --- doc/bashref.texi | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/bashref.texi b/doc/bashref.texi index 2be71c2d..e8db1bfe 100644 --- a/doc/bashref.texi +++ b/doc/bashref.texi @@ -8435,6 +8435,7 @@ @node Top declare -a @var{name} @end example @noinde

[PATCH 06/25] doc/bash.1: Resync with lib/readline/doc/readline.3.

Break lines in similar places; this eases diffing. Apply wording change that didn't get reflected in bash.1, and correct inadvertently boldfaced text. --- doc/bash.1 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/bash.1 b/doc/bash.1 index 9afddaf3..9223dd46 100644 -

[PATCH 03/25] doc/bash.1: Clarify program/man page reference.

This way the novice is less likely to think the plain English word "more" is meant here. --- doc/bash.1 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/bash.1 b/doc/bash.1 index 23a8dbd6..6c864eab 100644 --- a/doc/bash.1 +++ b/doc/bash.1 @@ -6962,7 +6962,8 @@ .SS "Readlin

[PATCH 04/25] doc/bash.1, doc/bashref.texi: Align wording.

* Perform Kemper notectomy. * Break lines in the same places to ease diffing. * Align verb tenses. --- doc/bash.1 | 11 ++- doc/bashref.texi | 40 ++-- 2 files changed, 32 insertions(+), 19 deletions(-) diff --git a/doc/bash.1 b/doc/bash.1 index 6

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

Also ensure the controlling registers are initialized without changing their values, avoiding groff "reg" warnings. Similarly, define the end macros used as end macros in `ig` requests as empty, avoiding groff "mac" warnings. Fixes: $ nroff -ww -z -man ./doc/bash.1 troff:./doc/bash.1:13: warning:

[PATCH 01/25] Adjust style of "export-completions" documentation.

* doc/bash.1: + Drop explicit `sp` request in favor of inter-paragraph spacing. + Set items returned by Readline command as bulleted list. + Identify "N" as the parameter replaced by the number of matches. + Set "readline" in boldface, for consistency with rest of page. + Set parameters "

Re: bug-bash Digest, Vol 264, Issue 28

At 2024-11-16T18:52:12-0800, Wiley Young wrote: > | From: Martin D Kealey > > | "In the general case I agree; man > > | pages should be reference > > | manuals, not tutorials" > > We should value others' contributions. This statement implies that we lack a means of evaluating contribut

Re: A documentation coincidence

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&#x

A documentation coincidence

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 o

Re: Readline Documentation

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.

Re: Potentially misleading documentation of SECONDS variable

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 > >

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

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

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

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 le

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

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 pa

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

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 n

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

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). > > • Th

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

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 mot

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

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(-) dif

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

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 --- d

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

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 deletion

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

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

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

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

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

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 pl

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

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

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

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/hi

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

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 ev

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

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 r

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

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 ar

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

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

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

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 spli

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

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/ms

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

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 PO

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

[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,

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

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 foll

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

, 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 bina

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

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

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

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 s

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

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

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

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

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

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 beginnin

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

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 defin

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

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 w

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

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!"' +

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

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

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

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). -

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

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

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

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

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

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 sequ

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

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 corr

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

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

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

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 in

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

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 adjustabl

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

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 newli

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

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

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

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 a

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

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.

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

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 in

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

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 pseud

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

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/b

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

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,

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

...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 mos

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

--- 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 eq

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

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

  1   2   >