Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes
PATCH 1/1 Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes
Change (list|...) to <list|...> to denote required command. Adjust the 'save' command syntax to better reflect the call parameters:
[save] [message...] => [save [message...]].
--- Documentation/git-stash.txt | 4 ++-- 1 files changed, 2 insertions(+), 2 deletions(-)
Documentation/git-stash.txt +2 -2
@@ -8,8 +8,8 @@ git-stash - Stash the changes in a dirty working directory away SYNOPSIS -------- [verse] -'git-stash' (list | show [<stash>] | apply [<stash>] | clear) -'git-stash' [save] [message...] +'git-stash' <list | show [<stash>] | apply [<stash>] | clear> +'git-stash' [save [message...]] DESCRIPTION -----------
Signature · 5 lines
1.5.4-rc5.GIT-dirty -- Welcome to FOSS revolution: we fix and modify until it shines
PATCH 1/1 Documentation/git-stash.txt: Adjust SYNOPSIS command syntax
Change (list|...) to {list|...} to denote required commands. Adjust the 'save' command syntax to better reflect the call parameters:
[save] [message...] => [save [message...]].
---
***********************************************************************
This is reworked patch (No. 1)
***********************************************************************
Documentation/git-stash.txt | 4 ++-- 1 files changed, 2 insertions(+), 2 deletions(-)
Documentation/git-stash.txt +2 -2
@@ -8,8 +8,8 @@ git-stash - Stash the changes in a dirty working directory away SYNOPSIS -------- [verse] -'git-stash' (list | show [<stash>] | apply [<stash>] | clear) -'git-stash' [save] [message...] +'git-stash' {list | show [<stash>] | apply [<stash>] | clear} +'git-stash' [save [message...]] DESCRIPTION -----------
Signature · 1 line
1.5.4-rc5.GIT-dirty
Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntax
You know that I am not taking patches that are not fixes this deep into the release freeze, don't you?
I do not take patches early, and certainly I'll not take a patch that changes a single page to make it the _first and only_ user of the convention to use curly brace to delimit required alternates. It means now the whole manual set is less consistent.
Please let the discussion brew for a while, and after reaching a consensus on the list, send in a patch that changes parentheses to curly braces for _ALL_ manual pages (and does nothing else).
Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntax
In reply to Jari AaltoJari Aalto <[email protected]> writes:
I think it would beb better if you split this patch in two, as it deals with two separate issues, and in one case it doesn't deal with the issue fully
Quoted 1 line
Change (list|...) to {list|...} to denote required commands.
This is one thing, and I think when you are resubmitting this patch for discussion (with Cc: to the authors that introduced the (-a|-b) syntax) you should change (list|...) to {list|...} *everywhere* in the git manpages.
Quoted 3 lines
Adjust
the 'save' command syntax to better reflect the call parameters:
[save] [message...] => [save [message...]].
This is just simple bugfix in git-stash synopsis, and I think this patch would be accepted (especially now that it is after 1.5.4 released, and after feature freeze) without doubt.
Signature · 3 lines
Jakub Narebski Poland ShadeHawk on #git
PATCH 1/1 Documentation/git-stash.txt: Adjust SYNOPSIS command syntax (2)
Adjust the command syntax to better reflect the call parameters:
[save] [message...] => [save [<message>]].
---
Quoted 2 lines
[Jakub Narebski] I think it would beb better if you split this patch in two,
***********************************************************************
This is reworked patch (No. 2)
***********************************************************************
Documentation/git-stash.txt | 7 ++++--- 1 files changed, 4 insertions(+), 3 deletions(-)
Documentation/git-stash.txt +4 -3
@@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git-stash' (list | show [<stash>] | apply [<stash>] | clear) -'git-stash' [save] [message...] +'git-stash' [save [<message>]] DESCRIPTION -----------
@@ -36,11 +36,12 @@ is also possible). OPTIONS ------- -save:: +save [<message>]:: Save your local modifications to a new 'stash', and run `git-reset --hard` to revert them. This is the default action when no - subcommand is given. + subcommand is given. The <message> part is optional and gives + the description along with the stashed state. list::
Signature · 1 line
1.5.4-rc5.GIT-dirty
Quoted 3 lines · Jari Aalto
Change (list|...) to <list|...> to denote required command. Adjust the 'save' command syntax to better reflect the call parameters:
[save] [message...] => [save [message...]].
While I agree with the second change, i.e. the "[save [message...]]" part, I think that the first part is a mistake. Parentheses does not imply the optional part: brackets do; parentheses are meant to delimit the alternatives. Angle brackets if I understand correctly are meant to denote part which you have to enter, the user supplied info (the reast ou have to enter literally).
So IMVHO the SYNOPSIS for git-stash(1) should read:
SYNOPSIS
--------
[verse]
'git-stash' (list | show [<stash>] | apply [<stash>] | clear) 'git-stash' [save [<message>...]]
or
'git-stash' [save [<message...>]]
Quoted 3 lines
Signature · 1 line
Welcome to FOSS revolution: we fix and modify until it shines
Nice one. Can I add it to http://git.or.cz/gitwiki/FortuneCookies ?
Signature · 3 lines
Jakub Narebski Poland ShadeHawk on #git
* Fri 2008-02-01 Jakub Narebski <[email protected]>
* Message-Id: [email protected]
Quoted 8 lines
'git-stash' (list | show [<stash>] | apply [<stash>] | clear) 'git-stash' [save [<message>...]]
Angle brackets if I understand correctly are meant to denote part which you have to enter, the user supplied info (the reast ou have to enter literally).
Nowhere I have seen "(" parenheses to mean "required". The angle brackets are commonly used to tell that the part is to be required:
command <option> <file ...>
Reads:
command -l file.txt
Whereas this has no known meaning:
command (option) <file ...>
But this does:
command [option] <file ...>
That's why I suggested to use:
git stash <list | show [<stash>] | apply [<stash>] | clear> git stash [save [<message>...]]
The nesting of <'s is normal. The above reads:
1st line: You have to select one command, one of the alternatives listed inside <...>: either "list", "show" ...
2nd line: you can type 'git stash', 'git stash save' or supply additional message with the stash.
NOTE:
There exists curly braces notation that is sometimes used for "required" part, but that not very common elsewhere other than printed books from commercial vendors.
command {one|two|three}I would hesitate to select parentheses notation, which is relatively unknown to mean "required" in the context of command syntax SYNOPSIS.
Quoted 3 lines
Quoted 1 line
Welcome to FOSS revolution: we fix and modify until it shines
Nice one. Can I add it to http://git.or.cz/gitwiki/FortuneCookies ?
Sure,
Jari
Quoted 4 lines · Jari Aalto
* Fri 2008-02-01 Jakub Narebski <[email protected]>
* Message-Id: [email protected]Quoted 2 lines
Quoted 8 lines
Quoted 6 lines
'git-stash' (list | show [<stash>] | apply [<stash>] | clear) 'git-stash' [save [<message>...]]
Angle brackets if I understand correctly are meant to denote part which you have to enter, the user supplied info (the reast ou have to enter literally).
Nowhere I have seen "(" parenheses to mean "required".
The "(" parentheses does not mean "required". They do mean "group", just like for regular expressions. So "A (B | C)" means "A B" or "A C".
Quoted 8 lines
The angle brackets are commonly used to tell that the part is to be required:
command <option> <file ...>Reads:
command -l file.txt
No, the "<" angle brackets are meant to denote: substitute your own (user) input, and not use as literal value. So "command <option>" mean select one of options ant put it in place of "<option>"
Quoted 3 lines
Whereas this has no known meaning:
command (option) <file ...>
It doesn't have meaning if there is no alternative in "(" parentheses. So it makes sense to use:
command (subcmd1 | subcmd2) <file ...>
but not
command (option) <file ...>
Quoted 3 lines
But this does:
command [option] <file ...>
The "[" brackets mean both "optional" and "group" (to reduce number of parentheses-like operators).
Quoted 4 lines
That's why I suggested to use:
git stash <list | show [<stash>] | apply [<stash>] | clear> git stash [save [<message>...]]
I hope that I have explained above why I think it is wrong. IMHO the "<" angle brackets mean: substitute your own input, and are not meant for grouping (limiting where alternates start and where end).
Quoted 10 lines
NOTE:
There exists curly braces notation that is sometimes used for "required" part, but that not very common elsewhere other than printed books from commercial vendors.
command {one|two|three}I would hesitate to select parentheses notation, which is relatively unknown to mean "required" in the context of command syntax SYNOPSIS.
Lack of "[" brackets means required.
By the way, is the format used by SYNOPSIS in manpages somewhere specified, for example in some RFC, like BNF notation and BNF-like notation used by RFCs is?
Signature · 3 lines
Jakub Narebski Poland ShadeHawk on #git
* Fri 2008-02-01 Jakub Narebski <[email protected]>
* Message-Id: [email protected]
Quoted 13 lines
Quoted 11 lines · Jari Aalto
* Fri 2008-02-01 Jakub Narebski <[email protected]>
* Message-Id: [email protected]Quoted 8 lines
'git-stash' (list | show [<stash>] | apply [<stash>] | clear) 'git-stash' [save [<message>...]]
Angle brackets if I understand correctly are meant to denote part which you have to enter, the user supplied info (the reast ou have to enter literally).
Quoted 5 lines
Quoted 1 line
Nowhere I have seen "(" parenheses to mean "required".
The "(" parentheses does not mean "required". They do mean "group", just like for regular expressions. So "A (B | C)" means "A B" or "A C".
In regexp language yes, but in describing the command syntaxes, I do not have come accross this. Would you have descriptive examples?
Quoted 7 lines
Quoted 4 lines
The angle brackets are commonly used to tell that the part is to be required:
command <option> <file ...>No, the "<" angle brackets are meant to denote: substitute your own (user) input, and not use as literal value. So "command <option>" mean select one of options ant put it in place of "<option>"
The angles primarily denote "required", and secondarily that you put there there the asked input.
Quoted 1 line
command (subcmd1 | subcmd2) <file ...>
Tat is highly uncommon. In angle bracket notation this is unabiguous:
command <parameter1|parameter2> <file ...>
A B
In angles, it's clear that both A and B are required; in A, you must choose one.
Quoted 2 lines
The "[" brackets mean both "optional" and "group" (to reduce number of parentheses-like operators).
The bracket's primary meaning is to say "optional" in command definitions. They do not "group"; they nest -- saying that there are more "optionality" included.
Quoted 8 lines
Quoted 4 lines
That's why I suggested to use:
git stash <list | show [<stash>] | apply [<stash>] | clear> git stash [save [<message>...]]
I hope that I have explained above why I think it is wrong. IMHO the "<" angle brackets mean: substitute your own input, and are not meant for grouping (limiting where alternates start and where end).
Angle brackets do not mean "substitute your own input", but they deonote a requirement; how the requirement is filled is done according to the description in the documentation.
command <"save"|"load">
In unabiguous way to say that the choices for words are "save" and "load" of which one of them must be supplied.
The reason why angle angles are used is that they are shell redirection metacharacters --- which never appear in that quality in standard manual page SYNOPSIS. The angles cannot be understood in any other way than as a "requirement" in the command definition.
Jari
Signature · 1 line
Welcome to FOSS revolution: we fix and modify until it shines
Quoted 35 lines · Jari Aalto
* Fri 2008-02-01 Jakub Narebski <[email protected]>
* Message-Id: [email protected]Quoted 13 lines
Quoted 11 lines · Jari Aalto
* Fri 2008-02-01 Jakub Narebski <[email protected]>
* Message-Id: [email protected]Quoted 8 lines
'git-stash' (list | show [<stash>] | apply [<stash>] | clear) 'git-stash' [save [<message>...]]
Angle brackets if I understand correctly are meant to denote part which you have to enter, the user supplied info (the reast ou have to enter literally).
Quoted 5 lines
Quoted 1 line
Nowhere I have seen "(" parenheses to mean "required".
The "(" parentheses does not mean "required". They do mean "group", just like for regular expressions. So "A (B | C)" means "A B" or "A C".
In regexp language yes, but in describing the command syntaxes, I do not have come accross this. Would you have descriptive examples?
Quoted 7 lines
Quoted 4 lines
The angle brackets are commonly used to tell that the part is to be required:
command <option> <file ...>No, the "<" angle brackets are meant to denote: substitute your own (user) input, and not use as literal value. So "command <option>" mean select one of options ant put it in place of "<option>"
The angles primarily denote "required", and secondarily that you put there there the asked input.
Quoted 6 lines
Quoted 1 line
command (subcmd1 | subcmd2) <file ...>Tat is highly uncommon. In angle bracket notation this is unabiguous:
command <parameter1|parameter2> <file ...>
A B
Actually, I've never seen any less-than-greater-than used to group alternates command description of traditional manual pages. So I'd say both may be unusual, but yours is a lot more unusual.
For example, GNU 'tar' uses | for alternates, but it does not mark grouping:
SYNOPSIS
tar [ - ] A --catenate --concatenate | c --create | d --diff --compare
| --delete | r --append | t --list | u --update | x --extract --get [
options ] pathname [ pathname ... ]which is horribly confusing to read.
GNU 'cpio' makes it somewhat easier to read by listing subcommands separately:
SYNOPSIS
cpio {-o|--create} [-0acvABLV] [-C bytes] [-H format] [-M message] [-O
[[user@]host:]archive] [-F [[user@]host:]archive]
[--file=[[user@]host:]archive] [--format=format] [--message=message]
[--null] [--reset-access-time] [--verbose] [--dot] [--append] [--block-
size=blocks] [--dereference] [--io-size=bytes] [--quiet]
[--force-local] [--rsh-command=command] [--help] [--version] < name-
list [> archive]
cpio {-i|--extract} [-bcdfmnrtsuvBSV] [-C bytes] [-E file] [-H format]
...But when they have alternates, they use braces {} to group them.
Solaris 'tar' lists subcommand separately, and seems to use braces {} for grouping alternates:
SYNOPSIS
tar c [ bBeEfFhiklnopPqvwX [ 0-7 ] ] [ block ] [
tarfile ] [ exclude-file ] { -I include-file | -C direc- tory | file | file } ...
In our manual pages, less-than-greater-than around names are very often used to mark placeholders. If you want to say zero or more files, you would typically say:
command <file>...
Using something other than less-than-greater-than to group alternates would make things easier to differentiate. If we used braces {} it _might_ have been more similar to what other people have traditionally done.
* Fri 2008-02-01 Junio C Hamano <[email protected]>
* Message-Id: [email protected]
Quoted 2 lines
If we used braces {} it _might_ have been more similar to what other people have traditionally done.
I concur with { ... } (as earlier), I'll submit patches for those.
Jari
Signature · 1 line
Welcome to FOSS revolution: we fix and modify until it shines
* Fri 2008-02-01 Junio C Hamano <[email protected]>
* Message-Id: [email protected]
Quoted 4 lines
GNU 'cpio' makes it somewhat easier to read by listing subcommands separately:
SYNOPSIS
Quoted 9 lines
cpio {-o|--create} [-0acvABLV] [-C bytes] [-H format] [-M message] [-O
[[user@]host:]archive] [-F [[user@]host:]archive]
[--file=[[user@]host:]archive] [--format=format] [--message=message]
[--null] [--reset-access-time] [--verbose] [--dot] [--append] [--block-
size=blocks] [--dereference] [--io-size=bytes] [--quiet]
[--force-local] [--rsh-command=command] [--help] [--version] < name-
list [> archive]
cpio {-i|--extract} [-bcdfmnrtsuvBSV] [-C bytes] [-E file] [-H format]Yes, I previously presented that the other common syntax was using curly braces, like here. I think we shoudl select it.
Jari
Signature · 1 line
Welcome to FOSS revolution: we fix and modify until it shines
Quoted 15 lines · Jari Aalto
* Fri 2008-02-01 Jakub Narebski <[email protected]>
* Message-Id: [email protected]Quoted 13 lines
Quoted 11 lines · Jari Aalto
* Fri 2008-02-01 Jakub Narebski <[email protected]>
* Message-Id: [email protected]Quoted 8 lines
'git-stash' (list | show [<stash>] | apply [<stash>] | clear) 'git-stash' [save [<message>...]]
Angle brackets if I understand correctly are meant to denote part which you have to enter, the user supplied info (the reast ou have to enter literally).
Quoted 8 lines
Quoted 5 lines
Quoted 1 line
Nowhere I have seen "(" parenheses to mean "required".
The "(" parentheses does not mean "required". They do mean "group", just like for regular expressions. So "A (B | C)" means "A B" or "A C".
In regexp language yes, but in describing the command syntaxes, I do not have come accross this. Would you have descriptive examples?
It seems that I was mistaken about that. Junio suggestion of following others example and using "{}" curly brackets for grouping alternate choices is IMHO a good solution.
...or perhaps not. For example synopsis for git-branch uses this syntax.
Quoted 11 lines
Quoted 8 lines
Quoted 4 lines
The angle brackets are commonly used to tell that the part is to be required:
command <option> <file ...>No, the "<" angle brackets are meant to denote: substitute your own (user) input, and not use as literal value. So "command <option>" mean select one of options ant put it in place of "<option>"
The angles primarily denote "required", and secondarily that you put there there the asked input.
The "<>" angle brackets does not denote required. Not in git manpages, not in other manpages.
Quoted 3 lines
Quoted 1 line
command (subcmd1 | subcmd2) <file ...>That is highly uncommon.
Perhaps, but is used in git manpages.
Quoted 7 lines
In angle bracket notation this is unabiguous:
command <parameter1|parameter2> <file ...>
A BIn angles, it's clear that both A and B are required; in A, you must choose one.
THAT is highly uncommon.
Quoted 6 lines
Quoted 2 lines
The "[" brackets mean both "optional" and "group" (to reduce number of parentheses-like operators).
The bracket's primary meaning is to say "optional" in command definitions. They do not "group"; they nest -- saying that there are more "optionality" included.
They do group. "command [A|B]" means "command" or "command A" or "command B".
Quoted 9 lines
Quoted 8 lines
Quoted 4 lines
That's why I suggested to use:
git stash <list | show [<stash>] | apply [<stash>] | clear> git stash [save [<message>...]]
I hope that I have explained above why I think it is wrong. IMHO the "<" angle brackets mean: substitute your own input, and are not meant for grouping (limiting where alternates start and where end).
Quoted 8 lines
Angle brackets do not mean "substitute your own input", but they deonote a requirement; how the requirement is filled is done according to the description in the documentation.
command <"save"|"load">In unabiguous way to say that the choices for words are "save" and "load" of which one of them must be supplied.
In our (git) manual pages "<text>" denotes placeholders.
The traditional manpages use /italics/ (usually rendered as _underlined_ text on terminals) to denote placeholders (user supplied input).
I think we better decide on syntax used in SYNOPSIS section, and perhaps even document it CodingGuidelines
-- >8 --
Quoted 1 line
The SYNOPSIS section describes the usage of the command. In general, it should look very much like a traditional usage message. [...] By convention, optional arguments are surrounded by square brackets.
Quoted 1 line
From man(7)
SYNOPSIS briefly describes the command or function's interface. For
commands, this shows the syntax of the command and its argu- ments (including options); boldface is used for as-is text and italics are used to indicate replaceable arguments. Brackets ([]) surround optional arguments, vertical bars (|) separate choices, and ellipses (...) can be repeated.
Quoted 1 line
From manpages(5), Darwin documentation
MANUAL PAGE SYNTAX
In manual page syntax, anything in a normal text font is required text. Anything in a boldface font is a flag or a subcommand. Anything underlined is a user-specified argument such as a filename.
Any argument surrounded by brackets is considered to be optional. For example, [ filename ] would indicate an optional filename argument.
Flags, arguments, or subcommands separated by a vertical separator (|) are mutually exclusive. For example, if -a turns on an option and -b turns off the option, the syntax for this command might be -a | -b.
In some cases, you may even see entire groups of arguments wrapped with brackets and separated by a vertical separator. This is one way of show-ing showing ing that a command has more than one valid syntax. In other manual pages, this is expressed by having multiple lines in the synopsis, each of which begins with the command name. The separated format is more com-mon common mon (and more readable), but is not always possible for commands with particularly complex syntax.
Finally, the most important notational convention is the use of the ellipsis (...). This indicates that additional arguments may be added at this point. Depending on the author, you may see this written in one of two ways:
argument [ argument... ]
argument...
Some SYNOPSIS examples (where we use the following convention:
*bold*, _underlined_):
*patch* [_options_] [_originalfile_ [_patchfile_]] (shows nesting)
wget [_option_]... [_URL_]... (shows ellipsis)
rpm {-q|--query} [select-options] [query-options] (shows grouping)
date [-u|--utc|--universal] [MMDDhhmm[[CC]YY][.ss]] (alt + grouping)*kill [ -s* _signal_ *| -p ] [ -a ] [ -- ]* _pid_ ... (as above)
Inside yum(8), shows alternate which is also grouping
* clean [ packages | headers | metadata | cache | dbcache | all ]
Some SYNOPISIS examples from git manpages, in AsciiDoc syntax (sources):
'git-add' [-n] [-v] [-f] [--interactive | -i] [--patch | -p] [-u] [--refresh]
[--] <filepattern>...
'git-am' [--signoff] [--dotest=<dir>] [--keep] [--utf8 | --no-utf8]
[--3way] [--interactive] [--binary]
[--whitespace=<option>] [-C<n>] [-p<n>]
<mbox>|<Maildir>...'git-apply' [--stat] [--numstat] [--summary] [--check] [--index]
[--apply] [--no-add] [--build-fake-ancestor <file>] [-R | --reverse] [--allow-binary-replacement | --binary] [--reject] [-z] [-pNUM] [-CNUM] [--inaccurate-eof] [--cached] [--whitespace=<nowarn|warn|fix|error|error-all>] [--exclude=PATH] [--verbose] [<patch>...]
'git-branch' [--color | --no-color] [-r | -a]
[-v [--abbrev=<length> | --no-abbrev]] [--contains <commit>]
'git-branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>] 'git-branch' (-m | -M) [<oldbranch>] <newbranch>
'git-branch' (-d | -D) [-r] <branchname>...
Signature · 3 lines
Jakub Narebski Poland ShadeHawk on #git
* Fri 2008-02-01 Jakub Narebski <[email protected]>
* Message-Id: [email protected]
Quoted 3 lines
It seems that I was mistaken about that. Junio suggestion of following others example and using "{}" curly brackets for grouping alternate choices is IMHO a good solution.
That is another common syntax which I presented previously.
Quoted 3 lines
The traditional manpages use /italics/ (usually rendered as _underlined_ text on terminals) to denote placeholders (user supplied input).
That does not matter. The text should stand out as it it in environment, which do not render termcap or other terminal capabilities.
Quoted 1 line
Here are the POSIX/Susv guidelines for the manual pages, I've marked the relevant points with **....**. We were both right: Angles mean required and grouping.
I think Git's manual pages should follow standard notation. E.g. the use of parentheses should be replaced with curly braces.
Jari
-----------------------------------------------------------------------
http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11
12.1 Utility Argument Syntax
http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01
[...]
4. Frequently, names of parameters that **require** substitution by actual values are shown with embedded underscores. Alternatively, parameters are shown as follows:
<parameter name>
The angle brackets are used for the symbolic grouping of a phrase representing a single parameter and conforming applications shall not include them in data submitted to the utility.
[...]
7. Arguments or option-arguments enclosed in the '[' and ']' notation are **optional** and can be omitted. Conforming applications shall not include the '[' and ']' symbols in data submitted to the utility.
8. Arguments separated by the '|' vertical bar notation are **mutually-exclusive.**
9. Ellipses ( "..." ) are used to denote that one or **more** occurrences of an option or operand are allowed. When an option or an operand followed by ellipses is enclosed in brackets, **zero** or more options or operands can be specified.
utility_name [-g option_argument]...[operand...]
Quoted 7 lines · Jari Aalto
* Fri 2008-02-01 Jakub Narebski <[email protected]>
* Message-Id: [email protected]Quoted 3 lines
It seems that I was mistaken about that. Junio suggestion of following others example and using "{}" curly brackets for grouping alternate choices is IMHO a good solution.
That is another common syntax which I presented previously.
Well, at least rpm and cpio manpages uses it.
Quoted 6 lines
Quoted 3 lines
The traditional manpages use /italics/ (usually rendered as _underlined_ text on terminals) to denote placeholders (user supplied input).
That does not matter. The text should stand out as it it in environment, which do not render termcap or other terminal capabilities.
Nevertheless it would be nice if our AsciiDoc configuration generated italics or underline for manpage, and italics for HTML output for placeholders, *in addition* to using angle parentheses (angle braces) as delimites for placeholder parameters.
Quoted 5 lines
Quoted 1 line
Here are the POSIX/Susv guidelines for the manual pages, I've marked the relevant points with **....**. We were both right: Angles mean required and grouping.
Errr... as far as I understand angles means placeholders, i.e. user supplied input. You can use "[<file>...]" for optional placeholder; everything which is not inside brackets is required.
Quoted 2 lines
I think Git's manual pages should follow standard notation. E.g. the use of parentheses should be replaced with curly braces.
It is used quite frequently in git manpages. Using parentheses to delimit required alternate parts seems quite sensible.
Examples of usage:
'git-branch' (-m | -M) [<oldbranch>] <newbranch> 'git-branch' (-d | -D) [-r] <branchname>... 'git-commit' ... [(-c | -C) <commit> | -F <file> | -m <msg> | --amend] 'git-name-rev' ... ( --all | --stdin | <committish>... ) 'git-show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>] 'git-update-ref' [-m <reason>] (-d <ref> <oldvalue> | [--no-deref] <ref> <newvalue> [<oldvalue>])
and even stranger
'git-ls-files' ... (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\*
Note that in the POSIX/SUSV below parentheses / curly braces are not mentioned.
Quoted 12 lines
-----------------------------------------------------------------------
http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_1112.1 Utility Argument Syntax
http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01[...]
4. Frequently, names of parameters that **require** substitution by actual values are shown with embedded underscores. Alternatively, parameters are shown as follows:
Quoted 5 lines
<parameter name>
The angle brackets are used for the symbolic grouping of a phrase representing a single parameter and conforming applications shall not include them in data submitted to the utility.
This means that <param> denotes placeholder: parameter that requires **subsititution** (this part should be emphasized!). Such parameter might have multi-word name. Such parameter might be required, but might be optional.
Quoted 8 lines
[...]
7. Arguments or option-arguments enclosed in the '[' and ']' notation are **optional** and can be omitted. Conforming applications shall not include the '[' and ']' symbols in data submitted to the utility.8. Arguments separated by the '|' vertical bar notation are **mutually-exclusive.**
Note that is natural that '[' and ']' also are limits of mutualy exclusive parameters: "cmd [ A | B ]" means "cmd" or "cmd A" or "cmd B". It is not specified explicitely, but IMHO is quite natural. And it is what is used in different manpages, see examples I have provided in my previous post in this subthread.
Quoted 6 lines
9. Ellipses ( "..." ) are used to denote that one or **more** occurrences of an option or operand are allowed. When an option or an operand followed by ellipses is enclosed in brackets, **zero** or more options or operands can be specified.
utility_name[-g option_argument]...[operand...]
Note that one is not followed strictly, and one should take note of that. For example to make sure that everybody knows that it is zero or more one would use [<param>...], and to make use that it is one or more one would use "<param> [<param>...]", just to be sure.
I'm not for or against any form.
Signature · 3 lines
Jakub Narebski Poland ShadeHawk on #git
* Fri 2008-02-01 Jakub Narebski <[email protected]>
* Message-Id: [email protected]
Quoted 7 lines
Quoted 2 lines
he text should stand out as it it in environment, which do not render termcap or other terminal capabilities.
Nevertheless it would be nice if our AsciiDoc configuration generated italics or underline ...for manpage, and italics for HTML output for placeholders, *in addition* to using angle parentheses (angle braces) as delimites for placeholder parameters.
Sure, let's notify the asciidoc maintainer know about the wishes (CC'd)
Quoted 9 lines
Quoted 5 lines
http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html
Here are the POSIX/Susv guidelines for the manual pages, I've marked the relevant points with **....**. We were both right: Angles mean required and grouping.
Errr... as far as I understand angles means placeholders, i.e. user supplied input. You can use "[<file>...]" for optional placeholder; everything which is not inside brackets is required.
If you choose to use the "optional", then you are _required_ to fill in the mentioned item. The "[....]" is applied in your example as well. The angles always keep it's nature, which is a requirement:
4. Frequently, names of parameters that _require_ substitution(...)
<parameter name>
Quoted 4 lines
It is used quite frequently in git manpages. Using parentheses to delimit required alternate parts seems quite sensible.
'git-branch' (-m | -M) [<oldbranch>] <newbranch>
The change is small, but important. People look at the manual paged any will get the wrong impression on "the standard notation"
git-branch {-m | -M} [<oldbranch>] <newbranch>
= =
Change to use curlies
Quoted 2 lines
Note that in the POSIX/SUSV below parentheses / curly braces are not mentioned.
True. The precedence of curlies has however been set long ago in software books and in other Unix manaul pages.
Quoted 14 lines
Quoted 14 lines
-----------------------------------------------------------------------
http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_1112.1 Utility Argument Syntax
http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01[...]
4. Frequently, names of parameters that **require** substitution by actual values are shown with embedded underscores. Alternatively, parameters are shown as follows:
<parameter name>
Quoted 8 lines
Quoted 3 lines
The angle brackets are used for the symbolic grouping of a phrase representing a single parameter and conforming applications shall not include them in data submitted to the utility.
This means that <param> denotes placeholder: parameter that requires **subsititution** (this part should be emphasized!). Such parameter might have multi-word name. Such parameter might be required, but might be optional.
It's never optional. For optionality, there is specific notation. Everybody knows how to read these; what is required and what is not:
command <arg> <arg>
command <arg> [<message>]
command <arg> [-lbc]
The <message> here is symbolic and not to be taken literally, whereas text that is not eclosed inside angles, "-lbc", is to be taken literally and interpreted by the rules of "set of options".
Quoted 6 lines
Quoted 6 lines
[...]
7. Arguments or option-arguments enclosed in the '[' and ']' notation are **optional** and can be omitted. Conforming applications shall not include the '[' and ']' symbols in data submitted to the utility.
Quoted 8 lines
Quoted 2 lines
8. Arguments separated by the '|' vertical bar notation are **mutually-exclusive.**
Note that is natural that '[' and ']' also are limits of mutualy exclusive parameters: "cmd [ A | B ]" means "cmd" or "cmd A" or "cmd B". It is not specified explicitely, but IMHO is quite natural. And it is what is used in different manpages, see examples I have provided in my previous post in this subthread.
We are in all agreement on this one.
Quoted 11 lines
Quoted 6 lines
9. Ellipses ( "..." ) are used to denote that one or **more** occurrences of an option or operand are allowed. When an option or an operand followed by ellipses is enclosed in brackets, **zero** or more options or operands can be specified.
utility_name[-g option_argument]...[operand...]Note that one is not followed strictly, and one should take note of that. For example to make sure that everybody knows that it is zero or more one would use [<param>...], and to make use that it is one or more one would use "<param> [<param>...]", just to be sure.
That's what it says. Outside of "[]" the ellipses mean (1+), indiside "[]", by rules of the brackets, it means (0+). I forgot to paste the two examples. Here:
utility_name -f option_argument...[operand...] utility_name [-g option_argument]...[operand...]
Jari
Signature · 1 line
Welcome to FOSS revolution: we fix and modify until it shines
Quoted 6 lines · Jari Aalto
* Fri 2008-02-01 Jakub Narebski <[email protected]>
* Message-Id: [email protected]Quoted 3 lines
Quoted 2 lines
he text should stand out as it it in environment, which do not render termcap or other terminal capabilities.
Quoted 6 lines
Quoted 4 lines
Nevertheless it would be nice if our AsciiDoc configuration generated italics or underline ...for manpage, and italics for HTML output for placeholders, *in addition* to using angle parentheses (angle braces) as delimites for placeholder parameters.
Sure, let's notify the asciidoc maintainer know about the wishes (CC'd)
Errr... I'm not sure if it is generic enough. Although the POSIX/Susv you have quoted. together with man(7) / manpage(5) pages I have quoted seems to tell that it is so: POSIX/Susv talks about using angle brackets to denote placeholders (to be substituted), man/manpage talks about using italics/underline to denote placeholders.
So to say: I'm interested what AsciiDoc maintainers would say to that. I have added asciidoc-discuss to Cc:, but please cull it (and the asciidoc maintainer) from the Cc: list when replying.
Quoted 10 lines
Quoted 9 lines
Quoted 5 lines
http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html
Here are the POSIX/Susv guidelines for the manual pages, I've marked the relevant points with **....**. We were both right: Angles mean required and grouping.
Errr... as far as I understand angles means placeholders, i.e. user supplied input. You can use "[<file>...]" for optional placeholder; everything which is not inside brackets is required.
Quoted 7 lines
If you choose to use the "optional", then you are _required_ to fill in the mentioned item. The "[....]" is applied in your example as well. The angles always keep it's nature, which is a requirement:
4. Frequently, names of parameters that _require_ substitution(...)
<parameter name>
Excuse me, but item is "required" if it is not marked (by brackets, or by listing it as one of alternate calling conventions in separate lines) as "optional". So both in "cmd -A" and in "cmd <file>" parameters '-A' (literal) and '<file>' (to be substituted by filename) are required parameters, while both in "cmd [-A]" and in "cmd [<file>]" appropriate parameters are optional.
Angle brackets does not mean required parameters. Please read carefully; they denote parameters which _require substitution_ (note those _two_ words together), i.e. parameters that the user need to replace with appropriate input.
Quoted 11 lines
Quoted 4 lines
It is used quite frequently in git manpages. Using parentheses to delimit required alternate parts seems quite sensible.
'git-branch' (-m | -M) [<oldbranch>] <newbranch>
The change is small, but important. People look at the manual paged any will get the wrong impression on "the standard notation"
'git-branch' {-m | -M} [<oldbranch>] <newbranch>
= =
Change to use curlies
Perhaps. This I guess needs some discussion.
Nevertheless if / when we decide to change to this notation to delimit parts of alternates / mutually exclusive parts, we would want to do this in patch which changes only that, but changes it everywhere.
Quoted 5 lines
Quoted 2 lines
Note that in the POSIX/SUSV below parentheses / curly braces are not mentioned.
True. The precedence of curlies has however been set long ago in software books and in other Unix manaul pages.
I have checked a bit of manual pages (in Linux), and only very few use this convention. Do you have any statistics?
Quoted 18 lines
Quoted 18 lines
Quoted 17 lines
-----------------------------------------------------------------------
http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_1112.1 Utility Argument Syntax
http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01[...]
4. Frequently, names of parameters that **require** substitution by actual values are shown with embedded underscores. Alternatively, parameters are shown as follows:
<parameter name>
The angle brackets are used for the symbolic grouping of a phrase representing a single parameter and conforming applications shall not include them in data submitted to the utility.
Quoted 6 lines
Quoted 4 lines
This means that <param> denotes placeholder: parameter that requires **subsititution** (this part should be emphasized!). Such parameter might have multi-word name. Such parameter might be required, but might be optional.
It's never optional. For optionality, there is specific notation.
Again: it is required if it is not optional. There is no notation for required parts, except that they are not marked as optional. In the "cmd <file>" it is not angle brackets around <file> that denotes that this parameter is requires, it is lacks of "[" "]" brackets around parameter that tells it.
Quoted 9 lines
Everybody knows how to read these; what is required and what is not:
command <arg> <arg>
command <arg> [<message>]
command <arg> [-lbc]The <message> here is symbolic and not to be taken literally, whereas text that is not eclosed inside angles, "-lbc", is to be taken literally and interpreted by the rules of "set of options".
All true. And all what I wanted to tell.
Quoted 4 lines
Quoted 2 lines
Note that is natural that '[' and ']' also are limits of mutualy exclusive parameters: "cmd [ A | B ]" means "cmd" or "cmd A" or "cmd B".
We are in all agreement on this one.
Good.
Quoted 12 lines
Quoted 11 lines
Quoted 6 lines
9. Ellipses ( "..." ) are used to denote that one or **more** occurrences of an option or operand are allowed. When an option or an operand followed by ellipses is enclosed in brackets, **zero** or more options or operands can be specified.
utility_name[-g option_argument]...[operand...]Note that one is not followed strictly, and one should take note of that. For example to make sure that everybody knows that it is zero or more one would use [<param>...], and to make use that it is one or more one would use "<param> [<param>...]", just to be sure.
Quoted 6 lines
That's what it says. Outside of "[]" the ellipses mean (1+), indiside "[]", by rules of the brackets, it means (0+). I forgot to paste the two examples. Here:
utility_name-f option_argument...[operand...]utility_name[-g option_argument]...[operand...]
Ooops. Sorry. This time *I* haven't read this carefully enough.
Signature · 3 lines
Jakub Narebski Poland ShadeHawk on #git
* Sat 2008-02-02 Jakub Narebski <[email protected]>
* Message-Id: [email protected]
Quoted 11 lines
Quoted 5 lines
Quoted 1 line
4. Frequently, names of parameters that _require_ substitution(...)
<parameter name>
Excuse me, but item is "required" if it is not marked (...) Angle brackets does not mean required parameters. Please read carefully; they denote parameters which
_requiresubstitution_(note those _two_ words together), i.e. parameters that the user need to replace with appropriate input.
We're talking about the same subject. You emphasize the "substitution" aspect, which by nature of the context, is inherently present. If you read your paragraph, you also conclude "required" -- which I emphasised initially.
SYNOPSIS dyntax:
command option
Is inherently same as by spelling it more stronger:
command <option>
But different from
command "option"
The reason why I might be inclined to be on for angles is that they are commonly used in BNF, and thus familiar to many:
<A> ::= <B> <C>
Quoted 8 lines
Quoted 5 lines
Quoted 2 lines
Note that in the POSIX/SUSV below parentheses / curly braces are not mentioned.
True. The precedence of curlies has however been set long ago in software books and in other Unix manaul pages.
I have checked a bit of manual pages (in Linux), and only very few use this convention. Do you have any statistics?
If you have ever skimmed Unix program book manuals, say before Linux, in the Unix era, the industry quite feruently used angle curlies:
command [<options>] {save|load}Even today the braces are used to say "you must choose". E.g. in Oracle's SQL manuals. This is quite self explanatory for the basic SQL:
SELECT [DISTINCT] {*, column [AS ["<alias>"]], ...}
FROM <table>
;Quoted 28 lines
Quoted 12 lines
Quoted 12 lines
Quoted 12 lines
-----------------------------------------------------------------------
http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_1112.1 Utility Argument Syntax
http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01[...]
4. Frequently, names of parameters that **require** substitution by actual values are shown with embedded underscores. Alternatively, parameters are shown as follows:
Quoted 6 lines
Quoted 6 lines
Quoted 5 lines
<parameter name>
The angle brackets are used for the symbolic grouping of a phrase representing a single parameter and conforming applications shall not include them in data submitted to the utility.
Again: it is required if it is not optional. There is no notation for required parts, except that they are not marked as optional. In the "cmd <file>" it is not angle brackets around <file> that denotes that this parameter is requires, it is lacks of "[" "]" brackets around parameter that tells it.
Quoted 4 lines
command <arg> <arg>
command <arg> [<message>]
command <arg> [-lbc]
Quoted 5 lines
Quoted 3 lines
The <message> here is symbolic and not to be taken literally, whereas text that is not eclosed inside angles, "-lbc", is to be taken literally and interpreted by the rules of "set of options".
All true. And all what I wanted to tell.
I think we both read the instructions the same way. Perhaps our views do not differ. I'd be surprised, because that's the convention people are used to having read the notations so long.
Jari
Signature · 1 line
Welcome to FOSS revolution: we fix and modify until it shines
Quoted 14 lines · Jari Aalto
* Sat 2008-02-02 Jakub Narebski <[email protected]>
* Message-Id: [email protected]Quoted 11 lines
Quoted 5 lines
Quoted 1 line
4. Frequently, names of parameters that _require_ substitution(...)
<parameter name>
Excuse me, but item is "required" if it is not marked (...) Angle brackets does not mean required parameters. Please read carefully; they denote parameters which
_requiresubstitution_(note those _two_ words together), i.e. parameters that the user need to replace with appropriate input.
Quoted 4 lines
We're talking about the same subject. You emphasize the "substitution" aspect, which by nature of the context, is inherently present. If you read your paragraph, you also conclude "required" -- which I emphasised initially.
No, I would not. The fact that the parameter _requires substitution_ (is placeholder) is orthogonal (independent) of the fact if the parameter is required or optional. Angle brackets (and italic or underline) means "placeholder", while lack of angle brackets (and bold) means "literal". Square brackets means "optional", while lack of brackets means "required"
Quoted 11 lines
SYNOPSIS syntax:
command option
Is inherently same as by spelling it more stronger:
command <option>
But different from
command "option"
I would say that in
command option
the 'option' string is literal, while in
command <option>
you have to substitute actual option in the place of '<option>'. I don't think that "option" for literals is used in SYNOPSIS in manpages, even if this notation is used elsewhere (BNF, RFC).
Quoted 9 lines
Quoted 8 lines
Quoted 5 lines
Quoted 2 lines
Note that in the POSIX/SUSV below parentheses / curly braces are not mentioned.
True. The precedence of curlies has however been set long ago in software books and in other Unix manual pages.
I have checked a bit of manual pages (in Linux), and only very few use this convention. Do you have any statistics?
Quoted 6 lines
If you have ever skimmed Unix program book manuals, say before Linux, in the Unix era, the industry quite frequently used angle curlies:
command [<options>] {save|load}From what I can see in Linux manuals usually this is dealt by either
relying on generic placeholders, and describing optional parts in detailed description, e.g.
tar <operation> [options]
or by splitting synopsis into separate lines, each line dealing with alternate syntax, e.g.
install [OPTION]... SOURCE DEST (1st format)
install [OPTION]... SOURCE... DIRECTORY (2nd format)
install -d [OPTION]... DIRECTORY... (3rd format)But in some cases using alternates which are not optional (i.e. not [ A | B | C ]) is a better solution. In some cases grouping is natural and does not need delimiters, for example "--opt=A|B", but in some cases delimiters are required, either "(-d | -D)" or "{-d | -D}"
Quoted 6 lines
Even today the braces are used to say "you must choose". E.g. in Oracle's SQL manuals. This is quite self explanatory for the basic SQL:
SELECT [DISTINCT] {*, column [AS ["<alias>"]], ...} FROM <table> ;
I'm just more used to "(a | b)" from regular expressions, and AFAIK also BNFs, and "{a,b}", with comma ',' instead of vertical bar '|' to denote alternates (mutually exclusive parts), like in [some] shell globing, and in above documentation example.
This will be last post from me in this sub-thread. I think we have exhausted this part of discussion...
Signature · 3 lines
Jakub Narebski Poland ShadeHawk on #git