Documenting "--" (was Re: Glob problem)

Documenting "--" (was Re: Glob problem)

[Bart Schaefer]

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 <S>
and <Z> 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").

Otherwise this all looks accurate.

Re: Documenting "--" (was Re: Glob problem)

[Peter Stephenson]

On Wed, 23 Oct 2013 09:01:31 -0700
Bart Schaefer <schaefer@brasslantern.com> 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 <S>
> and <Z> 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

Re: Documenting "--" (was Re: Glob problem)

[Bart Schaefer]

On Oct 23,  5:16pm, Peter Stephenson wrote:
}
} diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
} index 1d9fe68..6f33c02 100644

Looks fine to me.