[PATCH 1/2] cosmit: Remove trailing whitespaces in expn.yo

[PATCH 1/2] cosmit: Remove trailing whitespaces in expn.yo

[ivan tkachenko]

---
 Doc/Zsh/expn.yo | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index c218ded05..eea147bde 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -84,7 +84,7 @@ vindex(histchars, use of)
 A history expansion begins with the first character of the tt(histchars)
 parameter, which is `tt(!)' by default, and may occur anywhere on the
 command line, including inside double quotes (but not inside single quotes
-tt('...') or C-style quotes tt($'...') nor when escaped with a backslash).  
+tt('...') or C-style quotes tt($'...') nor when escaped with a backslash).
 
 The first character is followed by an optional event designator
 (ifzman(see )noderef(Event Designators)) and then an optional word
@@ -496,7 +496,7 @@ which treats var(arg) as a file name and replaces it with the file's
 contents.
 
 The tt(=) form is useful as both the tt(/dev/fd) and the named pipe
-implementation of tt(<LPAR())var(...)tt(RPAR()) have drawbacks.  In 
+implementation of tt(<LPAR())var(...)tt(RPAR()) have drawbacks.  In
 the former case, some programmes may automatically close the file
 descriptor in question before examining the file on the command line,
 particularly if this is necessary for security reasons such as when the
@@ -511,7 +511,7 @@ information using a pipe, so that programmes that expect to lseek
 Also note that the previous example can be more compactly and
 efficiently written (provided the tt(MULTIOS) option is set) as:
 
-example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) ifzman(\ 
+example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) ifzman(\
 )tt(> >LPAR())var(process1)tt(RPAR() > >LPAR())var(process2)tt(RPAR()))
 
 The shell uses pipes instead of FIFOs to implement the latter
@@ -974,7 +974,7 @@ If the tt(MULTIBYTE) option is set and the number is greater than 127
 )
 item(tt(%))(
 Expand all tt(%) escapes in the resulting words in the same way as in
-prompts (see 
+prompts (see
 ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\
 ifnzman(noderef(Prompt Expansion))). If this flag is given twice,
 full prompt expansion is done on the resulting words, depending on the
@@ -1729,7 +1729,7 @@ This produces the result tt(b).  First, the inner substitution
 tt("${foo}"), which has no array (tt(@)) flag, produces a single word
 result tt("bar baz").  The outer substitution tt("${(@)...[1]}") detects
 that this is a scalar, so that (despite the `tt((@))' flag) the subscript
-picks the first character. 
+picks the first character.
 )
 item(tt("${${(@)foo}[1]}"))(
 This produces the result `tt(bar)'.  In this case, the inner substitution
@@ -1763,7 +1763,7 @@ sect(Command Substitution)
 cindex(command substitution)
 cindex(substitution, command)
 A command enclosed in parentheses preceded by a dollar sign, like
-`tt($LPAR())...tt(RPAR())', or quoted with grave 
+`tt($LPAR())...tt(RPAR())', or quoted with grave
 accents, like `tt(`)...tt(`)', is replaced with its standard output, with
 any trailing newlines deleted.
 If the substitution is not enclosed in double quotes, the
@@ -2461,7 +2461,7 @@ qualifiers are also not applied in ordinary pattern matching.
 )
 item(tt(u))(
 Respect the current locale in determining the presence of multibyte
-characters in a pattern, provided the shell was compiled with 
+characters in a pattern, provided the shell was compiled with
 tt(MULTIBYTE_SUPPORT).  This overrides the tt(MULTIBYTE)
 option; the default behaviour is taken from the option.  Compare tt(U).
 (Mnemonic: typically multibyte characters are from Unicode in the UTF-8
@@ -2712,18 +2712,18 @@ expected, if combined with a `tt(=)', the value given must match the
 file-modes exactly, with a `tt(PLUS())', at least the bits in the
 given number must be set in the file-modes, and with a `tt(-)', the
 bits in the number must not be set. Giving a `tt(?)' instead of a
-octal digit anywhere in the number ensures that the corresponding bits 
+octal digit anywhere in the number ensures that the corresponding bits
 in the file-modes are not checked, this is only useful in combination
 with `tt(=)'.
 
 If the qualifier `tt(f)' is followed by any other character anything
-up to the next matching character (`tt([)', `tt({)', and `tt(<)' match 
+up to the next matching character (`tt([)', `tt({)', and `tt(<)' match
 `tt(])', `tt(})', and `tt(>)' respectively, any other character
 matches itself) is taken as a list of comma-separated
 var(sub-spec)s. Each var(sub-spec) may be either an octal number as
 described above or a list of any of the characters `tt(u)', `tt(g)',
 `tt(o)', and `tt(a)', followed by a `tt(=)', a `tt(PLUS())', or a
-`tt(-)', followed by a list of any of the characters `tt(r)', `tt(w)', 
+`tt(-)', followed by a list of any of the characters `tt(r)', `tt(w)',
 `tt(x)', `tt(s)', and `tt(t)', or an octal digit. The first list of
 characters specify which access rights are to be checked. If a `tt(u)'
 is given, those for the owner of the file are used, if a `tt(g)' is
@@ -2732,7 +2732,7 @@ of other users, and the `tt(a)' says to test all three groups. The
 `tt(=)', `tt(PLUS())', and `tt(-)' again says how the modes are to be
 checked and have the same meaning as described for the first form
 above. The second list of characters finally says which access rights
-are to be expected: `tt(r)' for read access, `tt(w)' for write access, 
+are to be expected: `tt(r)' for read access, `tt(w)' for write access,
 `tt(x)' for the right to execute the file (or to search a directory),
 `tt(s)' for the setuid and setgid bits, and `tt(t)' for the sticky
 bit.
@@ -2741,7 +2741,7 @@ Thus, `tt(*(f70?))' gives the files for which the owner has read,
 write, and execute permission, and for which other group members have
 no rights, independent of the permissions for other users. The pattern
 `tt(*(f-100))' gives all files for which the owner does not have
-execute permission, and `tt(*(f:gu+w,o-rx:))' gives the files for which 
+execute permission, and `tt(*(f:gu+w,o-rx:))' gives the files for which
 the owner and the other members of the group have at least write
 permission, and for which other users don't have read or execute
 permission.
@@ -2942,7 +2942,7 @@ item(tt([)var(beg)[tt(,)var(end)]tt(]))(
 specifies which of the matched filenames should be included in the
 returned list. The syntax is the same as for array
 subscripts. var(beg) and the optional var(end) may be mathematical
-expressions. As in parameter subscripting they may be negative to make 
+expressions. As in parameter subscripting they may be negative to make
 them count from the last match backward. E.g.: `tt(*(-OL[1,3]))'
 gives a list of the names of the three largest files.
 )
-- 
2.33.0

[PATCH 2/2] Add ${==spec} syntax more discoverable in docs

[ivan tkachenko]

---
 Doc/Zsh/expn.yo | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index eea147bde..0ab11af9d 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -895,7 +895,8 @@ happening later.  If word splitting is also in effect the
 tt($var[)var(N)tt(]) may themselves be split into different list
 elements.
 )
-item(tt(${=)var(spec)tt(}))(
+xitem(tt(${=)var(spec)tt(}))
+item(tt(${==)var(spec)tt(}))(
 pindex(SH_WORD_SPLIT, toggle)
 cindex(field splitting, sh style, parameter)
 cindex(sh, field splitting style, parameter)
-- 
2.33.0

Re: [PATCH 2/2] Add ${==spec} syntax more discoverable in docs

[Lawrence Velázquez]

On Wed, Sep 22, 2021, at 5:17 PM, ivan tkachenko wrote:
> -item(tt(${=)var(spec)tt(}))(
> +xitem(tt(${=)var(spec)tt(}))
> +item(tt(${==)var(spec)tt(}))(

This might also be useful for ${^^spec} and ${~~spec}.

-- 
vq

Re: [PATCH 2/2] Add ${==spec} syntax more discoverable in docs

[ivan tkachenko]

[-- Attachment #1: Type: text/html, Size: 646 bytes --]

[PATCH 1/2] cosmit: Remove trailing whitespaces in expn.yo

[ivan tkachenko]

---
 Doc/Zsh/expn.yo | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index c218ded05..eea147bde 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -84,7 +84,7 @@ vindex(histchars, use of)
 A history expansion begins with the first character of the tt(histchars)
 parameter, which is `tt(!)' by default, and may occur anywhere on the
 command line, including inside double quotes (but not inside single quotes
-tt('...') or C-style quotes tt($'...') nor when escaped with a backslash).  
+tt('...') or C-style quotes tt($'...') nor when escaped with a backslash).
 
 The first character is followed by an optional event designator
 (ifzman(see )noderef(Event Designators)) and then an optional word
@@ -496,7 +496,7 @@ which treats var(arg) as a file name and replaces it with the file's
 contents.
 
 The tt(=) form is useful as both the tt(/dev/fd) and the named pipe
-implementation of tt(<LPAR())var(...)tt(RPAR()) have drawbacks.  In 
+implementation of tt(<LPAR())var(...)tt(RPAR()) have drawbacks.  In
 the former case, some programmes may automatically close the file
 descriptor in question before examining the file on the command line,
 particularly if this is necessary for security reasons such as when the
@@ -511,7 +511,7 @@ information using a pipe, so that programmes that expect to lseek
 Also note that the previous example can be more compactly and
 efficiently written (provided the tt(MULTIOS) option is set) as:
 
-example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) ifzman(\ 
+example(tt(paste <LPAR()cut -f1) var(file1)tt(RPAR() <LPAR()cut -f3) var(file2)tt(RPAR()) ifzman(\
 )tt(> >LPAR())var(process1)tt(RPAR() > >LPAR())var(process2)tt(RPAR()))
 
 The shell uses pipes instead of FIFOs to implement the latter
@@ -974,7 +974,7 @@ If the tt(MULTIBYTE) option is set and the number is greater than 127
 )
 item(tt(%))(
 Expand all tt(%) escapes in the resulting words in the same way as in
-prompts (see 
+prompts (see
 ifzman(EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\
 ifnzman(noderef(Prompt Expansion))). If this flag is given twice,
 full prompt expansion is done on the resulting words, depending on the
@@ -1729,7 +1729,7 @@ This produces the result tt(b).  First, the inner substitution
 tt("${foo}"), which has no array (tt(@)) flag, produces a single word
 result tt("bar baz").  The outer substitution tt("${(@)...[1]}") detects
 that this is a scalar, so that (despite the `tt((@))' flag) the subscript
-picks the first character. 
+picks the first character.
 )
 item(tt("${${(@)foo}[1]}"))(
 This produces the result `tt(bar)'.  In this case, the inner substitution
@@ -1763,7 +1763,7 @@ sect(Command Substitution)
 cindex(command substitution)
 cindex(substitution, command)
 A command enclosed in parentheses preceded by a dollar sign, like
-`tt($LPAR())...tt(RPAR())', or quoted with grave 
+`tt($LPAR())...tt(RPAR())', or quoted with grave
 accents, like `tt(`)...tt(`)', is replaced with its standard output, with
 any trailing newlines deleted.
 If the substitution is not enclosed in double quotes, the
@@ -2461,7 +2461,7 @@ qualifiers are also not applied in ordinary pattern matching.
 )
 item(tt(u))(
 Respect the current locale in determining the presence of multibyte
-characters in a pattern, provided the shell was compiled with 
+characters in a pattern, provided the shell was compiled with
 tt(MULTIBYTE_SUPPORT).  This overrides the tt(MULTIBYTE)
 option; the default behaviour is taken from the option.  Compare tt(U).
 (Mnemonic: typically multibyte characters are from Unicode in the UTF-8
@@ -2712,18 +2712,18 @@ expected, if combined with a `tt(=)', the value given must match the
 file-modes exactly, with a `tt(PLUS())', at least the bits in the
 given number must be set in the file-modes, and with a `tt(-)', the
 bits in the number must not be set. Giving a `tt(?)' instead of a
-octal digit anywhere in the number ensures that the corresponding bits 
+octal digit anywhere in the number ensures that the corresponding bits
 in the file-modes are not checked, this is only useful in combination
 with `tt(=)'.
 
 If the qualifier `tt(f)' is followed by any other character anything
-up to the next matching character (`tt([)', `tt({)', and `tt(<)' match 
+up to the next matching character (`tt([)', `tt({)', and `tt(<)' match
 `tt(])', `tt(})', and `tt(>)' respectively, any other character
 matches itself) is taken as a list of comma-separated
 var(sub-spec)s. Each var(sub-spec) may be either an octal number as
 described above or a list of any of the characters `tt(u)', `tt(g)',
 `tt(o)', and `tt(a)', followed by a `tt(=)', a `tt(PLUS())', or a
-`tt(-)', followed by a list of any of the characters `tt(r)', `tt(w)', 
+`tt(-)', followed by a list of any of the characters `tt(r)', `tt(w)',
 `tt(x)', `tt(s)', and `tt(t)', or an octal digit. The first list of
 characters specify which access rights are to be checked. If a `tt(u)'
 is given, those for the owner of the file are used, if a `tt(g)' is
@@ -2732,7 +2732,7 @@ of other users, and the `tt(a)' says to test all three groups. The
 `tt(=)', `tt(PLUS())', and `tt(-)' again says how the modes are to be
 checked and have the same meaning as described for the first form
 above. The second list of characters finally says which access rights
-are to be expected: `tt(r)' for read access, `tt(w)' for write access, 
+are to be expected: `tt(r)' for read access, `tt(w)' for write access,
 `tt(x)' for the right to execute the file (or to search a directory),
 `tt(s)' for the setuid and setgid bits, and `tt(t)' for the sticky
 bit.
@@ -2741,7 +2741,7 @@ Thus, `tt(*(f70?))' gives the files for which the owner has read,
 write, and execute permission, and for which other group members have
 no rights, independent of the permissions for other users. The pattern
 `tt(*(f-100))' gives all files for which the owner does not have
-execute permission, and `tt(*(f:gu+w,o-rx:))' gives the files for which 
+execute permission, and `tt(*(f:gu+w,o-rx:))' gives the files for which
 the owner and the other members of the group have at least write
 permission, and for which other users don't have read or execute
 permission.
@@ -2942,7 +2942,7 @@ item(tt([)var(beg)[tt(,)var(end)]tt(]))(
 specifies which of the matched filenames should be included in the
 returned list. The syntax is the same as for array
 subscripts. var(beg) and the optional var(end) may be mathematical
-expressions. As in parameter subscripting they may be negative to make 
+expressions. As in parameter subscripting they may be negative to make
 them count from the last match backward. E.g.: `tt(*(-OL[1,3]))'
 gives a list of the names of the three largest files.
 )
-- 
2.33.0

[PATCH 2/2] Make Parameter Expansion syntax more discoverable in docs

[ivan tkachenko]

It affects all three occurrences of double-flags in Parameter Expansion
sub-section:

 * ${^^spec}
 * ${==spec}
 * ${~~spec}
---
 Doc/Zsh/expn.yo | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/Doc/Zsh/expn.yo b/Doc/Zsh/expn.yo
index eea147bde..d40d1b439 100644
--- a/Doc/Zsh/expn.yo
+++ b/Doc/Zsh/expn.yo
@@ -872,7 +872,8 @@ of the string tt($-) and the array tt($*) respectively.  If
 tt(POSIX_IDENTIFIERS) is set, then braces are required for
 the tt(#) to be treated in this fashion.
 )
-item(tt(${^)var(spec)tt(}))(
+xitem(tt(${^)var(spec)tt(}))
+item(tt(${^^)var(spec)tt(}))(
 pindex(RC_EXPAND_PARAM, toggle)
 cindex(array expansion style, rc)
 cindex(rc, array expansion style)
@@ -895,7 +896,8 @@ happening later.  If word splitting is also in effect the
 tt($var[)var(N)tt(]) may themselves be split into different list
 elements.
 )
-item(tt(${=)var(spec)tt(}))(
+xitem(tt(${=)var(spec)tt(}))
+item(tt(${==)var(spec)tt(}))(
 pindex(SH_WORD_SPLIT, toggle)
 cindex(field splitting, sh style, parameter)
 cindex(sh, field splitting style, parameter)
@@ -911,7 +913,8 @@ Note that splitting is applied to var(word) in the assignment forms
 of var(spec) em(before) the assignment to var(name) is performed.
 This affects the result of array assignments with the tt(A) flag.
 )
-item(tt(${~)var(spec)tt(}))(
+xitem(tt(${~)var(spec)tt(}))
+item(tt(${~~)var(spec)tt(}))(
 pindex(GLOB_SUBST, toggle)
 Turn on the tt(GLOB_SUBST) option for the evaluation of
 var(spec); if the `tt(~)' is doubled, turn it off.  When this option is
-- 
2.33.0

Re: [PATCH 2/2] Add ${==spec} syntax more discoverable in docs

[Daniel Shahaf]

ivan tkachenko wrote on Thu, 23 Sep 2021 12:31 +00:00:
> Also, I'd like to note that other sections of the Expansion chapter 
> such as "14.3.1 Parameter Expansion Flags" need some template 
> decorations too. I mean, try to search the page for, let's say, a 
> letter "t".

+1.  We _could_ add parentheses around the flags, e.g.,
«item(+LPAR()%+RPAR())» rather than «item(%)», so grepping for one-letter
flags would be easier.  We already do this in the prompt expansion
expandos documentation, for instance.  Would you like to do the honours?

FWIW, I think most of us generally search for «t» as a whole word, or
use the man page and search for /^ *t\>/ (or perhaps fgrep the
documentation sources for «item(tt(t»…).

> Unless you are a *NIX shell guru and know exactly where and 
> what to look for, you are toast.

Well, one does need to know what part of the documentation to read, but
that doesn't require or imply being a guru.

> Readability and discoverability of this documentation can/should be
> improved by a lot.

Any specific observations or suggestions?

Cheers,

Daniel