From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15999 invoked by alias); 23 Oct 2013 16:16:44 -0000 Mailing-List: contact zsh-workers-help@zsh.org; run by ezmlm Precedence: bulk X-No-Archive: yes List-Id: Zsh Workers List List-Post: List-Help: X-Seq: 31873 Received: (qmail 13310 invoked from network); 23 Oct 2013 16:16:38 -0000 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on f.primenet.com.au X-Spam-Level: X-Spam-Status: No, score=-6.9 required=5.0 tests=BAYES_00,RCVD_IN_DNSWL_HI, SPF_HELO_PASS autolearn=ham version=3.3.2 X-AuditID: cbfec7f5-b7ef66d00000795a-c0-5267f6633387 Date: Wed, 23 Oct 2013 17:16:34 +0100 From: Peter Stephenson To: zsh-workers@zsh.org Subject: Re: Documenting "--" (was Re: Glob problem) Message-id: <20131023171634.0619dcc8@pwslap01u.europe.root.pri> In-reply-to: <131023090131.ZM9876@torch.brasslantern.com> References: <65DB21EB-86B6-479C-8F25-35B9B832CFD5@gmail.com> <5266BFF6.4050004@oracle.com> <20131023.051117.47078782.ghostrevery@gmail.com> <91F9ED9F-B198-403B-9FE1-FF40DE960C1C@gmail.com> <20131023144700.43a7849a@pwslap01u.europe.root.pri> <131023090131.ZM9876@torch.brasslantern.com> Organization: Samsung Cambridge Solution Centre X-Mailer: Claws Mail 3.7.9 (GTK+ 2.22.0; i386-redhat-linux-gnu) MIME-version: 1.0 Content-type: text/plain; charset=US-ASCII Content-transfer-encoding: 7bit X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFuplluLIzCtJLcpLzFFi42I5/e/4Fd3kb+lBBs8nCVgcbH7I5MDoserg B6YAxigum5TUnMyy1CJ9uwSujKffT7AUTJKv+LfkGWsD40LJLkZODgkBE4nTcz6yQNhiEhfu rWfrYuTiEBJYyiix9NUpsISQwHImiWXTxEBsFgFViYe3/7CD2GwChhJTN81mBLFFBMQlzq49 D1YvDDS049Z2VhCbV8BeYvrvQ2wgNqeApcTn5+vZIRbcYJK4u7yTCSTBL6AvcfXvJyaIK+wl Zl45wwjRLCjxY/I9sKHMAloSm7c1sULY8hKb17xlnsAoMAtJ2SwkZbOQlC1gZF7FKJpamlxQ nJSea6RXnJhbXJqXrpecn7uJERKEX3cwLj1mdYhRgINRiYdX40N6kBBrYllxZe4hRgkOZiUR 3h13gUK8KYmVValF+fFFpTmpxYcYmTg4pRoYBdz85/nrRjk/ftzcsmWOXr5INPNsUeWGx4K8 p33trtza86mz870xl8OcF5MWnl3TUX2o5NmbthuBxmf+hVz6MK3336yi4pqQhbzHJ5V7pfPY rIkS31xv1LqpY9Uid/3zb3o2tXuxPEk88j/Xq2n3Aa/LavNmGpiWF/ceM005IGss+3/hg0cB SizFGYmGWsxFxYkA+nm6bSACAAA= On Wed, 23 Oct 2013 09:01:31 -0700 Bart Schaefer wrote: > Redirected to zsh-workers. > > On Oct 23, 2:47pm, Peter Stephenson wrote: > } > } Some of the regulars can tell me if the following looks right. > > Apologies if the following is too nit-picky ... > > } +Some shell builtin commands take options as given in invidiual entries. > > Am I correct in understanding "given" here to mean "described"? If so, > just say "described". > > } +Some shell builtin commands also take options that begin with `tt(+)' > } +instead of `tt(-)'. These commands are indicated in the list below. > > The word "indicated" here makes me expect something similar to the > and markings in the options list, which obviously isn't what you > mean. > > } +Options must appear in a group before any non-option arguments; > > "Options (and their individual arguments, if any) ..." ? Also the whole > document could probably use a consistency check, because sometimes we > use the term "flags" to differentiate command options from setopts, and > other times we don't. Maybe it would suffice to point out that "flags" > and "options" are the same thing and we use flags when there would be > confusion (such as when describing the "-o option" flag of "emulate"). diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo index 1d9fe68..6f33c02 100644 --- a/Doc/Zsh/builtins.yo +++ b/Doc/Zsh/builtins.yo @@ -28,6 +28,40 @@ See ifzman(the section `Zle Builtins' in zmanref(zshzle))\ ifnzman(noderef(Zle Builtins)). )\ )\ + +Some shell builtin commands take options as described in individual +entries; these are often referred to in the list below as `tt(flags)' to +avoid confusion with shell options, which may also have an effect on the +behaviour of builtin commands. In this introductory section, +`tt(option)' always has the meaning of an option to a command that should +be familiar to most command line users. + +Typically, options are single letters preceded by a hyphen (tt(-)). +Options that take an argument accept it either immediately following the +option letter or after white space, for example `tt(print -C3 *)' or +`tt(print -C 3 *)' are equivalent. Arguments to options are not the +same as arguments to the command; the documentation indicates which is +which. Options that do not take an argument may be combined in a single +word, for example `tt(print -ca *)' and `tt(print -c -a *)' are +equivalent. + +Some shell builtin commands also take options that begin with `tt(+)' +instead of `tt(-)'. The list below makes clear which commands these +are. + +Options (together with their individual arguments, if any) must appear +in a group before any non-option arguments; once the first non-option +argument has been found, option processing is terminated. + +All builtin commands other than precommand modifiers, even those that +have no options, can be given the argument `tt(--)' to terminate option +processing. This indicates that the following words are non-option +arguments, but is otherwise ignored. This is useful in cases where +arguments to the command may begin with `tt(-)'. For historical +reasons, most builtin commands also recognize a single `tt(-)' in a +separate word for this purpose; note that this is less standard and +use of `tt(--) is recommended. + startitem() prefix(-) findex(.) @@ -68,7 +102,7 @@ to be checked for alias expansion. If the tt(-g) flag is present, define a global alias; global aliases are expanded even if they do not occur in command position. -If the tt(-s) flags is present, define a suffix alias: if the command +If the tt(-s) flag is present, define a suffix alias: if the command word on a command line is in the form `var(text)tt(.)var(name)', where var(text) is any non-empty string, it is replaced by the text `var(value) var(text)tt(.)var(name)'. Note that var(name) is treated as