* manual @ 2022-12-20 22:41 Ray Andrews 2022-12-21 0:43 ` manual Lawrence Velázquez ` (2 more replies) 0 siblings, 3 replies; 14+ messages in thread From: Ray Andrews @ 2022-12-20 22:41 UTC (permalink / raw) To: Zsh Users Daniel was interested in what I'd do with the 'set' man page. It has a completely different flavor but: 'set' has too many uses: 1): set [+] 2): set {+|-}s [STRING] [STRING] ... 3): set {+|-}s -A [ARRAY_NAME] [VALUE] 4): set +A [ARRAY_NAME] [VALUE] # sorting not available with '+A' 5): set {+|-}OPTION_NAME 6): set +o 7): set -o 8): set {+|-}o [OPTION_NAME] [OPTION_NAME] ... [--] ----------------------------------------------------------------------------- 1): set [+]: Print all parameters. If '+' is given print them without their values. Where usable: -s: Ascending sort of the input. +s: Descending sort of the input. 2): set {+|-}s [STRING] [STRING] ... : If no flags other than +s or -s are given then the arguments following 'set' are assigned to the positional parameters: Example: $ set one "two's company" three $ print -l -- $1 $2 $3 one two's company three 3,4) An array will be set. Notice there is no equal sign and the array members are NOT to be enclosed in parentheses. 3): set {+|-}s -A [ARRAY_NAME] [VALUE]: ARRAY_NAME is set to VALUE, completely erasing any former contents: 4): set +A [ARRAY_NAME] [VALUE]: ARRAY_NAME is overwritten by the new VALUE but not truncated if the new VALUE is shorter than the old. Example: $ set +s -A ARRAY_NAME A B C 'dee licious' $ typeset -p ARRAY_NAME typeset -a ARRAY_NAME=( 'dee licious' C B A ) # Sort is descending $ set +A ARRAY_NAME 1 2 3 $ typeset -p ARRAY_NAME typeset -a ARRAY_NAME=( 1 2 3 A ) # Only three elements overwritten. $ set +A ARRAY_NAME aaaa $ typeset -p ARRAY_NAME typeset -a ARRAY_NAME=( aaaa 2 3 A ) # Only first element overwritten. The processing of arguments after -A or +A depends on whether the option KSH_ARRAYS is set. If not set, all arguments following ARRAY_NAME are treated as values for the array, regardless of their form -- zsh will attempt no interpretation or expansion of the arguments. But if the option is set, normal option processing will occur and only 'regular' arguments are treated as values for the array. This means that: $ set -A array -x -- foo ... sets array to '-x -- foo' if KSH_ARRAYS is not set, but sets the array to 'foo' and turns on the option '-x' if it is set. Note that 'typeset -A' is quite different from 'set -A'! If you are copying an associative array to another array you must do this: $ typeset -A NEW_ARRAY $ set -A NEW_ARRAY OLD_ARRAY ... otherwise NEW_ARRAY will not be associative. Be warned. 5): set {+|-}[OPTION] Turn on|off a single OPTION. 6): set +o: Print all options and values formatted as commands. 7): set -o: Print all options and values as a nice columnized display. 8): set {+|-}o [OPTION] [OPTION} ... [--] Turn on|off the given OPTIONS. If the list is followed by '--' the positional parameters will be unset. COMMENTS ON MAN PAGE: argFor the meaning of the other flags, see zshoptions(1). WHAT OTHER FLAGS? For historical reasons, `set -' is treated as `set +xv' and `set - args' as `set +xv -- args' when in any other emulation mode than zsh's native mode. DON'T KNOW WHAT TO DO WITH THAT. If the -A flag is specified, name is set to an array containing the given args; if no name is specified, all arrays are printed together with their values. IS THAT CORRECT? SEEMS TO ME ALL PARAMETERS ARE PRINTED NOT JUST ARRAYS. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-20 22:41 manual Ray Andrews @ 2022-12-21 0:43 ` Lawrence Velázquez 2022-12-21 1:15 ` manual Ray Andrews 2022-12-21 2:00 ` manual Daniel Shahaf 2022-12-22 7:03 ` manual Lawrence Velázquez 2 siblings, 1 reply; 14+ messages in thread From: Lawrence Velázquez @ 2022-12-21 0:43 UTC (permalink / raw) To: Ray Andrews; +Cc: zsh-users On Tue, Dec 20, 2022, at 5:41 PM, Ray Andrews wrote: > If the -A flag is specified, name is set to an array > containing the given > args; if no name is specified, all arrays are printed > together with their > values. > > IS THAT CORRECT? It is correct. > SEEMS TO ME ALL PARAMETERS ARE PRINTED NOT JUST ARRAYS. This is incorrect. -- vq ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-21 0:43 ` manual Lawrence Velázquez @ 2022-12-21 1:15 ` Ray Andrews 2022-12-21 1:44 ` manual Lawrence Velázquez 0 siblings, 1 reply; 14+ messages in thread From: Ray Andrews @ 2022-12-21 1:15 UTC (permalink / raw) To: zsh-users On 2022-12-20 16:43, Lawrence Velázquez wrote: > args; if no name is specified, all arrays are printed >> together with their >> values. >> >> IS THAT CORRECT? > It is correct. > > > 0 /aWorking/Zsh/Source/Wk 2 $ set | grep red= > COMMAND0=$'set | grep red=\nset | grep red=\nset | grep red=\n' > Dred=$'\C-[[31m' > _red=$'%{\C-[[1;31m%}' > red=$'\C-[[31;1m' > > 0 /aWorking/Zsh/Source/Wk 2 $ typeset -p red > typeset red=$'\C-[[31;1m' red is scalar, no? ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-21 1:15 ` manual Ray Andrews @ 2022-12-21 1:44 ` Lawrence Velázquez 2022-12-21 4:15 ` manual Ray Andrews 0 siblings, 1 reply; 14+ messages in thread From: Lawrence Velázquez @ 2022-12-21 1:44 UTC (permalink / raw) To: zsh-users On Tue, Dec 20, 2022, at 8:15 PM, Ray Andrews wrote: > On 2022-12-20 16:43, Lawrence Velázquez wrote: >> args; if no name is specified, all arrays are printed >>> together with their >>> values. >>> >>> IS THAT CORRECT? >> It is correct. >> >> >> 0 /aWorking/Zsh/Source/Wk 2 $ set | grep red= >> COMMAND0=$'set | grep red=\nset | grep red=\nset | grep red=\n' >> Dred=$'\C-[[31m' >> _red=$'%{\C-[[1;31m%}' >> red=$'\C-[[31;1m' >> >> 0 /aWorking/Zsh/Source/Wk 2 $ typeset -p red >> typeset red=$'\C-[[31;1m' > > red is scalar, no? The command in question is "set -A", not "set". -- vq ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-21 1:44 ` manual Lawrence Velázquez @ 2022-12-21 4:15 ` Ray Andrews 0 siblings, 0 replies; 14+ messages in thread From: Ray Andrews @ 2022-12-21 4:15 UTC (permalink / raw) To: zsh-users On 2022-12-20 17:44, Lawrence Velázquez wrote: > > The command in question is "set -A", not "set". > Ah! I missed that in the manual as written. My own doc would have to be edited to include that. Anyway it was just an exercise. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-20 22:41 manual Ray Andrews 2022-12-21 0:43 ` manual Lawrence Velázquez @ 2022-12-21 2:00 ` Daniel Shahaf 2022-12-21 4:12 ` manual Ray Andrews ` (2 more replies) 2022-12-22 7:03 ` manual Lawrence Velázquez 2 siblings, 3 replies; 14+ messages in thread From: Daniel Shahaf @ 2022-12-21 2:00 UTC (permalink / raw) To: Ray Andrews; +Cc: Zsh Users Ray Andrews wrote on Tue, Dec 20, 2022 at 14:41:44 -0800: > Daniel was interested in what I'd do with the 'set' man page. It has a > completely different flavor but: > Thanks. I was hoping you'd send new text just for that one three-line paragraph, actually. Glad to see more, but I don't have time to review more, unfortunately, so I'll reply just to parts: > 3): set {+|-}s -A [ARRAY_NAME] [VALUE] > 4): set +A [ARRAY_NAME] [VALUE] # sorting not available with ⋮ > 3,4) An array will be set. Notice there is no equal sign and the array > members are NOT to be enclosed in parentheses. The last sentence goes without saying, for several reasons: - As a rule, the manual isn't in the business of describing what the syntax is not; the manual should describe what the syntax /is/. Putting =(…) there isn't nearly common enough an error to make an exception to the rule for. - The synopsis doesn't show any equals signs or parentheses. - «set» is a builtin. The basic syntax of calling builtins, functions, and external commands is documented elsewhere in the manual, and in the context of this section is assumed knowledge. The assumed knowledge includes the fact that calling any builtin, function, or external command with anything enclosed in parentheses would be a syntax error. To see this: . f() { } for i in "autoload" "f" "/usr/bin/env" "[["; do "$i" done The fourth one fails, because «[[» is a keyword, and results of expansion are not considered as keywords. All of the first three work, because they all follow exactly the same "list of shell words" syntax; the only difference between them is what relative order they are considered (looked up) in. (Functions are looked up first, which is why a function named "autoload" or "env" would shadow the builtin or the external command respectively.) > 3): set {+|-}s -A [ARRAY_NAME] [VALUE]: > ARRAY_NAME is set to VALUE, completely erasing any former contents: > Normally the manual would end such a sentence at the comma. Rule against surplusage, I guess ☺ > 4): set +A [ARRAY_NAME] [VALUE]: > ARRAY_NAME is overwritten by the new VALUE but not truncated if the new > VALUE is shorter than the old. > Unfortunately, as written this assumes the reader takes "overwriting" to be an operation that involves "truncation" at some point, and we can't assume the reader's mental model of overwriting is that. > Note that 'typeset -A' is quite different from 'set -A'! If you are copying > an > associative array to another array you must do this: > > $ typeset -A NEW_ARRAY > $ set -A NEW_ARRAY OLD_ARRAY > > ... otherwise NEW_ARRAY will not be associative. Be warned. Good point. Right now the docs of -A just say the parameter "is set to an array", which could be taken to mean it's forced to be a numerically-indexed array. So, that's a second issue in this section we should fix. > COMMENTS ON MAN PAGE: > > > argFor the meaning of the other flags, see zshoptions(1). > > WHAT OTHER FLAGS? > The synopsis just says «{+|-}options», with "options" in var() markup. That's unusual: most synopses spell out all valid flags. See <https://www.freebsd.org/cgi/man.cgi?ssh#SYNOPSIS> for example. That sentence is saying that the flags covered by the mentioned part of the synopsis are documented in zshoptions(1). > So, thanks again for the contribution. Let's try and focus please and the two specific issues identified («set -A» and types; «set -A» and prefixes). ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-21 2:00 ` manual Daniel Shahaf @ 2022-12-21 4:12 ` Ray Andrews 2022-12-21 4:43 ` manual Bart Schaefer 2022-12-21 9:38 ` manual Lawrence Velázquez 2 siblings, 0 replies; 14+ messages in thread From: Ray Andrews @ 2022-12-21 4:12 UTC (permalink / raw) To: zsh-users On 2022-12-20 18:00, Daniel Shahaf wrote: > The last sentence goes without saying, for several reasons: Even in the unlikely event that the devs were interested in my writing, it goes without saying that there will be edits. And obviously the devs have the last word on any issue, however: > - As a rule, the manual isn't in the business of describing what the > syntax is not; the manual should describe what the syntax /is/. > > Putting =(…) there isn't nearly common enough an error to make an > exception to the rule for. It's part of my philosophy to throw in 'helpful hints'. It's what makes a document actually helpful. OTOH, as you correctly say, manuals are not focused on that, and in any case it would have to be broadly agreed that any particular helpful hint is really needed. I needed it, but that's not sufficient. > The assumed knowledge includes the fact that calling any builtin, > function, or external command with anything enclosed in parentheses > would be a syntax error. First I've heard of that! Seemed to me 'obvious' that there'd be parentheses -- an array is being assigned.. Mind, again, my particular ignorance is no test of what's worth mentioning. > All of the first three work, because they all follow exactly the same > "list of shell words" syntax; the only difference between them is what > relative order they are considered (looked up) in. (Functions are > looked up first, which is why a function named "autoload" or "env" > would shadow the builtin or the external command respectively.) I need to know more about all that. > Normally the manual would end such a sentence at the comma. Rule > against surplusage, I guess ☺ Yes of course, but it was a first draft! Actually not even a draft, more like a sample of how I think a manual should be written. Lots of examples -- actual runnable code that could be pasted to the CL and run. Break up the synopsis into several lines, each one covering some specific subset of functionality. Give some thought to readability. Remember that people reading the doc are looking for usable information and the test of a doc is that it is helpful to the non-expert. And so on. > Unfortunately, as written this assumes the reader takes "overwriting" to > be an operation that involves "truncation" at some point, and we can't > assume the reader's mental model of overwriting is that. Indeed. It's clear to me but maybe not to the next guy. The main thing I was trying to communicate with that little effort is that it's the *example* that makes it clear, not the exposition. > That's unusual: most synopses spell out all valid flags Yes! Very lazy. And I took 'options' there to mean option names. Mind, it does actually work that way. > So, thanks again for the contribution. Let's try and focus please and > the two specific issues identified («set -A» and types; «set -A» and > prefixes). > After you mentioned it, I couldn't stop thinking about it, so had to give it a go. I was writing it in my dreams last night. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-21 2:00 ` manual Daniel Shahaf 2022-12-21 4:12 ` manual Ray Andrews @ 2022-12-21 4:43 ` Bart Schaefer 2022-12-21 14:04 ` manual Ray Andrews 2022-12-21 9:38 ` manual Lawrence Velázquez 2 siblings, 1 reply; 14+ messages in thread From: Bart Schaefer @ 2022-12-21 4:43 UTC (permalink / raw) To: Daniel Shahaf; +Cc: Ray Andrews, Zsh Users On Tue, Dec 20, 2022 at 6:00 PM Daniel Shahaf <d.s@daniel.shahaf.name> wrote: > > The synopsis just says «{+|-}options», with "options" in var() markup. > > That's unusual: most synopses spell out all valid flags. "No; it is too much. Let me sum up." -- Inigo Montoya There was for a long time an effort made to keep the first-line synopsis of each command short enough to fit on one line of "man" output. For a few commands that was impossible so we started adding explicit line breaks with the expectation that the reader would understand it was still all one command line. For some others there was no way to add a line break at a sensible place. In this particular case (as you noted) there's an entire other section already dedicated to the single-letter options that can be manipulated with "set" and another for the long names for "set -o". It might have been nice to be consistent about what was an "option" and what was a "flag" or a "switch", but those terms are thrown around colloquially with interpretation expected from context. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-21 4:43 ` manual Bart Schaefer @ 2022-12-21 14:04 ` Ray Andrews 2022-12-22 6:31 ` manual Lawrence Velázquez 0 siblings, 1 reply; 14+ messages in thread From: Ray Andrews @ 2022-12-21 14:04 UTC (permalink / raw) To: zsh-users On 2022-12-20 20:43, Bart Schaefer wrote: > In this particular case (as you noted) there's an entire other section > already dedicated to the single-letter options that can be manipulated Yabut they sent you to the head of an entire nother section of the manual. Avoiding an entire block of duplication could be OK but say something like: "There are many other 'set' switches that are duplicated in/for the 'setopt' command (q.v.) which you can read just below this entry." > with "set" and another for the long names for "set -o". Ah! Another thing I missed. It's far from clear that they're even talking about single-letter options. Why not say that? I spent about two hours reading, experimenting, re-writing, trying to get every bit of information out of that page and I missed 'set -A' (by itself) and single letter options entirely. Not to be too whiny but 'set' is a dogs breakfast of bad design. It is a bizarre bazaar of bits and pieces of semi-related functionality rather like a junk-shop or a gypsy camp. It's like jazz -- don't ask for a definition. > It might have been nice to be consistent about what was an "option" > and what was a "flag" or a "switch", but those terms are thrown around > colloquially with interpretation expected from context. More than nice. As discussed, manuals are not really focused on being helpful, but they should be absolutely consistent. Perhaps a bit of literary license is welcome in a paragraph of exposition, but in a synopsis, if the word is 'flag' then stick with flag throughout. I like 'switch' myself but that's DOSey. (A flag is a variable used to communicate some bit of information between one part of code an another IMHO.) Nope, the entire Linux word (no doubt UNIX too but I've never touched it) should be ashamed of itself for it's abominable documentation. Our manual is far from the worst. > ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-21 14:04 ` manual Ray Andrews @ 2022-12-22 6:31 ` Lawrence Velázquez 2022-12-22 14:20 ` manual Ray Andrews 0 siblings, 1 reply; 14+ messages in thread From: Lawrence Velázquez @ 2022-12-22 6:31 UTC (permalink / raw) To: zsh-users On Wed, Dec 21, 2022, at 9:04 AM, Ray Andrews wrote: > Yabut they sent you to the head of an entire nother section of the > manual. Avoiding an entire block of duplication could be OK but say > something like: "There are many other 'set' switches that are duplicated > in/for the 'setopt' command (q.v.) which you can read just below this > entry." It already says where to look. For the meaning of the other flags, see zshoptions(1). >> with "set" and another for the long names for "set -o". > Ah! Another thing I missed. It's far from clear that they're even > talking about single-letter options. Why not say that? That wouldn't hurt, but zshoptions(1) goes into this at some length. Some options also have one or more single letter names. There are two sets of single letter options: one used by default, and another used to emulate sh/ksh (used when the SH_OPTION_LETTERS option is set). The single letter options can be used on the shell command line, or with the `set', `setopt' and `unsetopt' builtins, as normal Unix options preceded by `-'. The sense of the single letter options may be inverted by using `+' instead of `-'. Some of the single letter option names refer to an option being off, in which case the inversion of that name refers to the option being on. For example, `+n' is the short name of `exec', and `-n' is the short name of its inversion, `noexec'. > I spent about > two hours reading, experimenting, re-writing, trying to get every bit of > information out of that page and I missed 'set -A' (by itself) and > single letter options entirely. The synopsis makes it quite clear that -A and +A can be used alone. set ... [ {+|-}A [ name ] ] ... The square brackets indicate that the enclosed items are optional. Thus the "name" option-argument is optional when using -A or +A, and -A and +A are themselves optional. -- vq ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-22 6:31 ` manual Lawrence Velázquez @ 2022-12-22 14:20 ` Ray Andrews 0 siblings, 0 replies; 14+ messages in thread From: Ray Andrews @ 2022-12-22 14:20 UTC (permalink / raw) To: zsh-users On 2022-12-21 22:31, Lawrence Velázquez wrote: > > It already says where to look. > > For the meaning of the other flags, see zshoptions(1). I know it. They send you to another section entirely which is 1487 lines long. Not very friendly. Please understand that it's my 'job' in a discussion like this to be crabby and snotty and hard to please. Devil's advocate is what I'm being. > Some options also have one or more single letter names. > There are two sets of single letter options: one used by > default, and another used to emulate sh/ksh (used when the > SH_OPTION_LETTERS option is set). The single letter options > can be used on the shell command line, or with the `set', > `setopt' and `unsetopt' builtins, as normal Unix options preceded > by `-'. > > The sense of the single letter options may be inverted by > using `+' instead of `-'. Some of the single letter option > names refer to an option being off, in which case the > inversion of that name refers to the option being on. For > example, `+n' is the short name of `exec', and `-n' is the > short name of its inversion, `noexec'. > That's quite well written. Throw in some examples and it's good. But one should not have to go hunting for that information. Unless ... there is some heavy reason why that's needed, in which case there should be a note to that effect: "( The subject of options is so extensive that it requires it's own elaboration and can't be fully explained here. Please see 'zshoptions' in the manual for a full development of the topic.)" ... or something like that. > > The synopsis makes it quite clear that -A and +A can be used alone. > > set ... [ {+|-}A [ name ] ] ... Clear to you but not to me. I missed it. The expert will always find the manual good enough but that's not the test. The test is whether the student found it good enough. (Mind, there will be times when the student, fallible human that he is, might miss something that really is well explained. And to be honest, I think that's the case here -- it is good enough, but overwhelmed as I was by everything else, I missed the easy part.) Again, I hardly expected to get it right the first time, that would be a miracle. It was a template. The only thing that matters is that I've got a few of you guys thinking about all this :-) ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-21 2:00 ` manual Daniel Shahaf 2022-12-21 4:12 ` manual Ray Andrews 2022-12-21 4:43 ` manual Bart Schaefer @ 2022-12-21 9:38 ` Lawrence Velázquez 2 siblings, 0 replies; 14+ messages in thread From: Lawrence Velázquez @ 2022-12-21 9:38 UTC (permalink / raw) To: zsh-users On Tue, Dec 20, 2022, at 9:00 PM, Daniel Shahaf wrote: > Let's try and focus please and > the two specific issues identified («set -A» and types; «set -A» and > prefixes). Here's an attempt. Instead of trying to address every possible case, I chose to describe the behavior in terms of other assignment constructs which (to my knowledge) operate equivalently. diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 56428a714..fca6db8e5 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -1687,13 +1687,19 @@ the description of tt(setopt) below for more information on the format. With tt(PLUS()o) they are printed in a form that can be used as input to the shell. -If the tt(-A) flag is specified, var(name) is set to an array containing -the given var(arg)s; if no var(name) is specified, all arrays are printed -together with their values. - -If tt(PLUS()A) is used and var(name) is an array, the -given arguments will replace the initial elements of that array; if no -var(name) is specified, all arrays are printed without their values. +If tt(-A) var(name) is specified, the var(arg)s are assigned to +var(name) as with `var(name)tt(=LPAR())var(arg) ...tt(RPAR())'. If +tt(-A) is specified without var(name), all arrays are printed together +with their values. + +If tt(PLUS()A) var(name) is specified, and var(name) is a normal array, +the var(arg)s are assigned to var(name) as with +`var(name)tt([1,)var(N)tt(]=LPAR())var(arg) ...tt(RPAR())' (or +`var(name)tt([0,)var(N)tt(-1]=LPAR())var(arg) ...tt(RPAR())' with +tt(KSH_ARRAYS) set), where var(N) is the number of var(arg)s provided. +If var(name) is not a normal array, tt(PLUS()A) var(name) behaves like +tt(-A) var(name). If tt(PLUS()A) is specified without var(name), all +arrays are printed without their values. The behaviour of arguments after tt(-A) var(name) or tt(PLUS()A) var(name) depends on whether the option tt(KSH_ARRAYS) is set. If it is not set, all -- vq ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-20 22:41 manual Ray Andrews 2022-12-21 0:43 ` manual Lawrence Velázquez 2022-12-21 2:00 ` manual Daniel Shahaf @ 2022-12-22 7:03 ` Lawrence Velázquez 2022-12-22 13:50 ` manual Ray Andrews 2 siblings, 1 reply; 14+ messages in thread From: Lawrence Velázquez @ 2022-12-22 7:03 UTC (permalink / raw) To: zsh-users On Tue, Dec 20, 2022, at 5:41 PM, Ray Andrews wrote: > Daniel was interested in what I'd do with the 'set' man page. It has a > completely different flavor but: > > 'set' has too many uses: > > 1): set [+] > 2): set {+|-}s [STRING] [STRING] ... > 3): set {+|-}s -A [ARRAY_NAME] [VALUE] > 4): set +A [ARRAY_NAME] [VALUE] # sorting not available > with '+A' > 5): set {+|-}OPTION_NAME > 6): set +o > 7): set -o > 8): set {+|-}o [OPTION_NAME] [OPTION_NAME] ... [--] Partitioning the synopsis isn't a bad idea, but your partition is misleading because most of the options you separated can actually be used together in a single "set" command. % print $options[ALIASES] $options[ERR_EXIT] on off % typeset -p argv typeset -a argv=( ) % set +o ALIASES -e foo bar baz % print $options[ALIASES] $options[ERR_EXIT] off on % typeset -p argv typeset -a argv=( foo bar baz ) % typeset -p arr || true typeset: no such variable: arr % set -o ALIASES +e -A arr v1 v2 v3 % print $options[ALIASES] $options[ERR_EXIT] on off % typeset -p arr typeset -a arr=( v1 v2 v3 ) POSIX.1-2017 does partition its synopsis [*], but later it has to explicitly explain that setting and unsetting attributes can be mixed in a single invocation because the synopsis implies otherwise. set [-abCefhmnuvx] [-o option] [argument...] set [+abCefhmnuvx] [+o option] [argument...] set -- [argument...] set -o set +o [*]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#set > 2): set {+|-}s [STRING] [STRING] ... : The term "string" is next to useless when discussing shell. Almost everything is what you might consider a string. > If no flags other than +s or -s are given then the arguments following > 'set' are assigned to the > positional parameters: As I already mentioned, this is incorrect. Options and positional parameters can be mixed in the same invocation. > 3): set {+|-}s -A [ARRAY_NAME] [VALUE]: > ARRAY_NAME is set to VALUE, completely erasing any former contents: > > 4): set +A [ARRAY_NAME] [VALUE]: > ARRAY_NAME is overwritten by the new VALUE but not truncated if the new > VALUE is shorter than the old. These are incorrect. Multiple arguments can be provided, all of which are assigned to the array. Additionally, -s and +s work with +A, and it is not clear what "value" is supposed to mean. > Note that 'typeset -A' is quite different from 'set -A'! If you are > copying an > associative array to another array you must do this: > > $ typeset -A NEW_ARRAY > $ set -A NEW_ARRAY OLD_ARRAY This example incorrectly implies that this should work: % typeset -A old_arr=(a 1 b 2 c 3) % typeset -A new_arr % set -A new_arr old_arr zsh: bad set of key/value pairs for associative array > 5): set {+|-}[OPTION] > Turn on|off a single OPTION. This incorrectly implies that it is not possible to enable options, disable options, and set positional parameters in the same invocation. > 8): set {+|-}o [OPTION] [OPTION} ... [--] > Turn on|off the given OPTIONS. If the list is followed by '--' the > positional > parameters will be unset. It is not possible to enable or disable multiple options this way. All but the first will actually be used as positional parameters. % set -o EXTENDED_GLOB ERR_EXIT % print $options[EXTENDED_GLOB] $options[ERR_EXIT] on off % typeset -p argv typeset -a argv=( ERR_EXIT ) Additionally, this incorrectly implies that the positional parameters can only be cleared after -o or +o. > For historical reasons, `set -' is treated as `set +xv' > and `set - args' as > `set +xv -- args' when in any other emulation mode than > zsh's native mode. > > DON'T KNOW WHAT TO DO WITH THAT. Leave it in? -- vq ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: manual 2022-12-22 7:03 ` manual Lawrence Velázquez @ 2022-12-22 13:50 ` Ray Andrews 0 siblings, 0 replies; 14+ messages in thread From: Ray Andrews @ 2022-12-22 13:50 UTC (permalink / raw) To: zsh-users On 2022-12-21 23:03, Lawrence Velázquez wrote: > Partitioning the synopsis isn't a bad idea, but your partition is > misleading because most of the options you separated can actually > be used together in a single "set" command. I'm pleased to have made as few mistakes as I did. There was no hope that I'd get it right the first time. It was just a sort of template/sample for my thoughts on how a manual page could be made more useful. Indeed the way functionalities can be piled on top of each other is why I called 'set' a dog's breakfast. IMHO we should have setopt (already do), setarray, and setparam. But I appreciate that set probably got that way by accretion -- over the years stuff got added on and there was no point at which anyone wanted to back out and rethink the thing from the ground up. London vs. Paris. As you say, a more broken up synopsis -- tho always the better way -- runs into trouble when functionalities can be piled on top of each other but with all sorts of ifs ands buts and maybees (like the way that '+s' works with '-A' but not with '+A'). It's something to explore how that might be handled. (Mostly by shaking out the commands themselves!) > POSIX.1-2017 does partition its synopsis [*], but later it has to > explicitly explain that setting and unsetting attributes can be > mixed in a single invocation because the synopsis implies otherwise. > > set [-abCefhmnuvx] [-o option] [argument...] > set [+abCefhmnuvx] [+o option] [argument...] > set -- [argument...] > set -o > set +o Ironically IMHO that's going too far. set [{+,-}abCefhmnuvx] [{+,-}o option] [argument...] ... would be quite tractable. (I myself prefer the comma to the pipe but that's just me.) Dunno, on the one hand I think that manuals should be quite rigid in their use of terminology and the syntax of things like synopses, OTOH there are times when you hafta just 'get it done' -- explain the thing however it needs to be explained and that might mean bending a rule as to synopsis grammar. Interesting questions! But we're out of time anyway. The only real test of/for any doc is whether or not it is useful to the people who might actually need to read it. That means force feeding it to newbies -- the way you force feed medicine to lab rats -- and then asking them if the document is understandable. If it is the doc is good, if not it needs work -- simple as that. I'm trying to be that lab rat. But there are so few of me. > 2): set {+|-}s [STRING] [STRING] ... : > The term "string" is next to useless when discussing shell. Almost > everything is what you might consider a string. That very well could be. In the world according to Ray, the manual would start with a glossary of terms which would have rigid usage throughout. Not 'flag' or 'switch' or 'option', pick one and define it exactly and use it exclusively. Note that even in my experimental run, I took 'option' to mean a switch (cuz it's often used that way) whereas in that case it meant a single letter OPTION -- which is not explained in any way. One could read that man-page and never know there is any such thing as a single-letter option. > As I already mentioned, this is incorrect. Options and positional > parameters can be mixed in the same invocation. No worries, it was just a dry run. You're taking it more seriously than I did. If ever a man-page were to be rewritten by me, it would be subject to checking and editing by knowledgeable people like yourself. I would never presume to have the final word on anything. We'd get it right on the 5th edit. But I do have a talent for clarity. >> DON'T KNOW WHAT TO DO WITH THAT. > Leave it in? As you would decide. I'm only saying I myself can't do anything with it. Good writing is a very difficult thing. Especially good technical writing and coders are notoriously bad at it. ^ permalink raw reply [flat|nested] 14+ messages in thread
end of thread, other threads:[~2022-12-22 14:21 UTC | newest] Thread overview: 14+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2022-12-20 22:41 manual Ray Andrews 2022-12-21 0:43 ` manual Lawrence Velázquez 2022-12-21 1:15 ` manual Ray Andrews 2022-12-21 1:44 ` manual Lawrence Velázquez 2022-12-21 4:15 ` manual Ray Andrews 2022-12-21 2:00 ` manual Daniel Shahaf 2022-12-21 4:12 ` manual Ray Andrews 2022-12-21 4:43 ` manual Bart Schaefer 2022-12-21 14:04 ` manual Ray Andrews 2022-12-22 6:31 ` manual Lawrence Velázquez 2022-12-22 14:20 ` manual Ray Andrews 2022-12-21 9:38 ` manual Lawrence Velázquez 2022-12-22 7:03 ` manual Lawrence Velázquez 2022-12-22 13:50 ` manual Ray Andrews
Code repositories for project(s) associated with this public inbox https://git.vuxu.org/mirror/zsh/ This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).