From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 21634 invoked by alias); 27 Jul 2015 14:03:02 -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: 35931 Received: (qmail 11026 invoked from network); 27 Jul 2015 14:02:58 -0000 X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on f.primenet.com.au X-Spam-Level: X-Spam-Status: No, score=-2.7 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,RCVD_IN_DNSWL_LOW autolearn=ham autolearn_force=no version=3.4.0 DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d= daniel.shahaf.name; h=content-type:date:from:in-reply-to :message-id:mime-version:references:subject:to:x-sasl-enc :x-sasl-enc; s=mesmtp; bh=pbR6u+CvGUH/4Ii2QYBzSIUQKCc=; b=it6dJd D7CjgPTi31Du0T8aNeZBd+sCaRiZ1GV1jSyLsRQ8H1SOPoy8N+7vV4uCYCOfM1vQ i5d4QJ33VOxGRwgYdx7cJ2NOv9fOufpk6n4P8mJrc+kmIZ9HXKWigPz4mevTxR7u ZKHB1aD9xI1jnbA/x7bUr754moKa0X4ryL5w0= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d= messagingengine.com; h=content-type:date:from:in-reply-to :message-id:mime-version:references:subject:to:x-sasl-enc :x-sasl-enc; s=smtpout; bh=pbR6u+CvGUH/4Ii2QYBzSIUQKCc=; b=afLvB ZHkWs1x/PzbkQrMfj5d3L5RFhuZzXuyST9btp0REwueO8v1YEf4SoFD86fng6Ekk WABMWm2llJm39UCTGwcsYdq4D6vbB3ARtppwzjjcKm3LCF7AhietOiYcEFCOVqkN WeT7M8+q0n7NMRyZ3ztIetPhh6w4UWVk8GH8w8= X-Sasl-enc: JC+Xu7Lmta+SX/ooI7g29W5/jA66BT2zsylW0zxlbxLR 1438005134 Date: Mon, 27 Jul 2015 13:52:12 +0000 From: Daniel Shahaf To: zsh-workers@zsh.org Subject: Re: [PATCH] _arguments docs: Add options overview and sections Message-ID: <20150727135212.GD2239@tarsus.local2> References: <20150716232032.GE2032@tarsus.local2> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20150716232032.GE2032@tarsus.local2> User-Agent: Mutt/1.5.21 (2010-09-15) Daniel Shahaf wrote on Thu, Jul 16, 2015 at 23:20:32 +0000: > Attached for review. The first patch conslidates the documentation of > all of _arguments' options in one place; that patch is 90% moving text > around and 10% minor text changes. The second patch divides the long > help docstring into "subsections". Here's an additional patch following Oliver's review (thanks!). Possible further enhancements: - Clarify terminology throughout: option/flag/argument/switch, as referring to _arguments' argv or to the analyzed command line's. - Clarify documentation of -C Cheers, Daniel diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo index a53de8b..290c85f 100644 --- a/Doc/Zsh/compsys.yo +++ b/Doc/Zsh/compsys.yo @@ -3534,7 +3534,7 @@ conventions. em(Options overview) -Options to tt(_arguments) itself must be in separate words, i.e., tt(-s -w), +Options to tt(_arguments) itself must be in separate words, i.e. tt(-s -w), not tt(-sw). The options are followed by var(spec)s that describe options and arguments of the analyzed command. var(spec)s that describe option flags must precede var(spec)s that describe non-option ("positional" or "normal") @@ -3549,8 +3549,9 @@ being analyzed, and is described in detail below. The var(opts) for the that `tt(-s)' following `tt(-)tt(-)' has a distinct meaning from `tt(-s)' preceding `tt(-)tt(-)', and both may appear. -The options tt(-s), tt(-S), tt(-A) affect the parsing of the command line, -and are useful for commands with standard option parsing. +The option switches tt(-s), tt(-S), tt(-A), tt(-w), and tt(-W) affect how +tt(_arguments) parses the analyzed command line's options. These switches are +useful for commands with standard argument parsing. The options of tt(_arguments) have the following meanings: @@ -3558,7 +3559,7 @@ startitem() item(tt(-n))( With this option, tt(_arguments) sets the parameter tt(NORMARG) to the position of the first normal argument in the tt($words) array, -i.e., the position after the end of the options. If that argument +i.e. the position after the end of the options. If that argument has not been reached, tt(NORMARG) is set to tt(-1). The caller should declare `tt(integer NORMARG)' if the tt(-n) option is passed; otherwise the parameter is not used. @@ -3572,10 +3573,9 @@ option name (the `tt(-xy)' option). Options beginning with a single hyphen or plus sign are eligible for stacking; words beginning with two hyphens are not. -This is suitable for standard GNU options. -Note that tt(-s) after tt(-)tt(-) has a different meaning, and is documented -below. +Note that tt(-s) after tt(-)tt(-) has a different meaning, which is documented +in the segment entitled `Deriving var(spec) forms from the help output'. ) item(tt(-w))( In combination with tt(-s), allow option stacking @@ -3624,13 +3624,11 @@ execute var(action)s. This is discussed in detail below. ) item(tt(-M) var(matchspec))( -Use var(matchspec) as the match specification to use to -completion option names and values. The default var(matchspec) is: - +Use the match specification var(matchspec) for completing option names and values. +The default var(matchspec) allows partial word completion after `tt(_)' and +`tt(-)', such as completing `tt(-f-b)' to `tt(-foo-bar)'. The default +var(matchspec) is: example(tt(r:|[_-]=* r:|=*)) - -which allows partial word completion after `tt(_)' and `tt(-)', for example -`tt(-f-b)' can be completed to `tt(-foo-bar)'. ) enditem() @@ -3756,7 +3754,7 @@ xitem(tt(:*)var(pattern)tt(::)var(message)tt(:)var(action)) item(tt(:*)var(pattern)tt(:::)var(message)tt(:)var(action))( This describes multiple arguments. Only the last var(optarg) for an option taking multiple arguments may be -given in this form. If the var(pattern) is empty (i.e., tt(:*:)), all +given in this form. If the var(pattern) is empty (i.e. tt(:*:)), all the remaining words on the line are to be completed as described by the var(action); otherwise, all the words up to and including a word matching the var(pattern) are to be completed using the var(action). @@ -4005,7 +4003,7 @@ A useful alternative is often an option specification with rest-arguments (as in `tt(-foo:*:...)'); here the option tt(-foo) swallows up all remaining arguments as described by the var(optarg) definitions. -em(Intuiting var(spec) forms from the help output) +em(Deriving var(spec) forms from the help output) The option `tt(-)tt(-)' allows tt(_arguments) to work out the names of long options that support the `tt(-)tt(-help)' option which is standard in many