{"thread":{"id":"11812","subject":"[PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","startedAt":"2008-02-01T10:04:15Z","lastAt":"2008-02-02T15:25:45Z","messageCount":19,"participants":["Jari Aalto","Jakub Narebski","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"67020","messageId":"7ihp802o.fsf@blue.sea.net","threadId":"11812","inReplyTo":null,"subject":"[PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-01T10:04:15Z","receivedAt":"2008-02-01T10:04:15Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Change (list|...) to <list|...> to denote required command. Adjust\nthe 'save' command syntax to better reflect the call parameters:\n[save] [message...] => [save [message...]].\n\nSigned-off-by: Jari Aalto <jari.aalto AT cante.net>\n---\n Documentation/git-stash.txt |    4 ++--\n 1 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 9889806..e713e48 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -8,8 +8,8 @@ git-stash - Stash the changes in a dirty working directory away\n SYNOPSIS\n --------\n [verse]\n-'git-stash' (list | show [<stash>] | apply [<stash>] | clear)\n-'git-stash' [save] [message...]\n+'git-stash' <list | show [<stash>] | apply [<stash>] | clear>\n+'git-stash' [save [message...]]\n \n DESCRIPTION\n -----------\n-- \n1.5.4-rc5.GIT-dirty\n\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"67025","messageId":"m37iho9b70.fsf@localhost.localdomain","threadId":"11812","inReplyTo":"7ihp802o.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-02-01T11:19:03Z","receivedAt":"2008-02-01T11:19:03Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jari Aalto <jari.aalto@cante.net> writes:\n\n> Change (list|...) to <list|...> to denote required command. Adjust\n> the 'save' command syntax to better reflect the call parameters:\n> [save] [message...] => [save [message...]].\n\nWhile I agree with the second change, i.e. the \"[save [message...]]\"\npart, I think that the first part is a mistake.  Parentheses does not\nimply the optional part: brackets do; parentheses are meant to\ndelimit the alternatives.  Angle brackets if I understand correctly\nare meant to denote part which you have to enter, the user supplied\ninfo (the reast ou have to enter literally).\n\nSo IMVHO the SYNOPSIS for git-stash(1) should read:\n\nSYNOPSIS\n--------\n[verse]\n'git-stash' (list | show [<stash>] | apply [<stash>] | clear)\n'git-stash' [save [<message>...]]\n\nor\n\n'git-stash' [save [<message...>]]\n\n> -- \n> Welcome to FOSS revolution: we fix and modify until it shines\n> \n\nNice one. Can I add it to http://git.or.cz/gitwiki/FortuneCookies ?\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"67027","messageId":"1w7w966m.fsf@blue.sea.net","threadId":"11812","inReplyTo":"m37iho9b70.fsf@localhost.localdomain","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-01T13:06:57Z","receivedAt":"2008-02-01T13:06:57Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"* Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>\n* Message-Id: m37iho9b70.fsf@localhost.localdomain\n>\n>\n> 'git-stash' (list | show [<stash>] | apply [<stash>] | clear)\n> 'git-stash' [save [<message>...]]\n>\n> Angle brackets if I understand correctly are meant to denote part\n> which you have to enter, the user supplied info (the reast ou have to\n> enter literally).\n\nNowhere I have seen \"(\" parenheses to mean \"required\". The angle\nbrackets are commonly used to tell that the part is to be required:\n\n    command <option> <file ...>\n\nReads:\n\n    command -l file.txt\n\nWhereas this has no known meaning:\n\n    command (option) <file ...>\n\nBut this does:\n\n    command [option] <file ...>\n\nThat's why I suggested to use:\n\n    git stash <list | show [<stash>] | apply [<stash>] | clear>\n    git stash [save [<message>...]]\n\nThe nesting of <'s is normal. The above reads:\n\n    1st line: You have to select one command, one of the alternatives\n    listed inside <...>: either \"list\", \"show\" ...\n\n    2nd line: you can type 'git stash', 'git stash save' or supply\n    additional message with the stash.\n\nNOTE:\n\nThere exists curly braces notation that is sometimes used for\n\"required\" part, but that not very common elsewhere other than\nprinted books from commercial vendors.\n\n    command {one|two|three}\n\nI would hesitate to select parentheses notation, which is relatively unknown\nto mean \"required\" in the context of command syntax SYNOPSIS.\n\n>> Welcome to FOSS revolution: we fix and modify until it shines\n>\n> Nice one. Can I add it to http://git.or.cz/gitwiki/FortuneCookies ?\n\nSure,\nJari\n"},{"id":"67031","messageId":"m33asc94xn.fsf@localhost.localdomain","threadId":"11812","inReplyTo":"1w7w966m.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-02-01T13:35:01Z","receivedAt":"2008-02-01T13:35:01Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jari Aalto <jari.aalto@cante.net> writes:\n\n> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>\n> * Message-Id: m37iho9b70.fsf@localhost.localdomain\n> >\n> >\n> > 'git-stash' (list | show [<stash>] | apply [<stash>] | clear)\n> > 'git-stash' [save [<message>...]]\n> >\n> > Angle brackets if I understand correctly are meant to denote part\n> > which you have to enter, the user supplied info (the reast ou have to\n> > enter literally).\n> \n> Nowhere I have seen \"(\" parenheses to mean \"required\". \n\nThe \"(\" parentheses does not mean \"required\". They do mean \"group\",\njust like for regular expressions. So \"A (B | C)\" means \"A B\" or\n\"A C\".\n\n> The angle brackets are commonly used to tell that the part is to be\n> required:\n> \n>     command <option> <file ...>\n> \n> Reads:\n> \n>     command -l file.txt\n\nNo, the \"<\" angle brackets are meant to denote: substitute your own\n(user) input, and not use as literal value. So \"command <option>\"\nmean select one of options ant put it in place of \"<option>\"\n\n> Whereas this has no known meaning:\n> \n>     command (option) <file ...>\n\nIt doesn't have meaning if there is no alternative in \"(\"\nparentheses. So it makes sense to use:\n\n      command (subcmd1 | subcmd2) <file ...>\n\nbut not\n\n      command (option) <file ...>\n\n> But this does:\n> \n>     command [option] <file ...>\n\nThe \"[\" brackets mean both \"optional\" and \"group\" (to reduce number of\nparentheses-like operators).\n \n> That's why I suggested to use:\n> \n>     git stash <list | show [<stash>] | apply [<stash>] | clear>\n>     git stash [save [<message>...]]\n\nI hope that I have explained above why I think it is wrong. IMHO the\n\"<\" angle brackets mean: substitute your own input, and are not meant\nfor grouping (limiting where alternates start and where end).\n\n> NOTE:\n> \n> There exists curly braces notation that is sometimes used for\n> \"required\" part, but that not very common elsewhere other than\n> printed books from commercial vendors.\n> \n>     command {one|two|three}\n> \n> I would hesitate to select parentheses notation, which is relatively unknown\n> to mean \"required\" in the context of command syntax SYNOPSIS.\n\nLack of \"[\" brackets means required.\n\n\nBy the way, is the format used by SYNOPSIS in manpages somewhere\nspecified, for example in some RFC, like BNF notation and BNF-like\nnotation used by RFCs is?\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"67043","messageId":"k5lo716v.fsf@blue.sea.net","threadId":"11812","inReplyTo":"m33asc94xn.fsf@localhost.localdomain","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-01T22:37:44Z","receivedAt":"2008-02-01T22:37:44Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"* Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>\n* Message-Id: m33asc94xn.fsf@localhost.localdomain\n> Jari Aalto <jari.aalto@cante.net> writes:\n>\n>> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>\n>> * Message-Id: m37iho9b70.fsf@localhost.localdomain\n>> >\n>> >\n>> > 'git-stash' (list | show [<stash>] | apply [<stash>] | clear)\n>> > 'git-stash' [save [<message>...]]\n>> >\n>> > Angle brackets if I understand correctly are meant to denote part\n>> > which you have to enter, the user supplied info (the reast ou have to\n>> > enter literally).\n>> \n>> Nowhere I have seen \"(\" parenheses to mean \"required\". \n>\n> The \"(\" parentheses does not mean \"required\". They do mean \"group\",\n> just like for regular expressions. So \"A (B | C)\" means \"A B\" or\n> \"A C\".\n\nIn regexp language yes, but in describing the command syntaxes, I do not\nhave come accross this. Would you have descriptive examples?\n\n>> The angle brackets are commonly used to tell that the part is to be\n>> required:\n>> \n>>     command <option> <file ...>\n> No, the \"<\" angle brackets are meant to denote: substitute your own\n> (user) input, and not use as literal value. So \"command <option>\"\n> mean select one of options ant put it in place of \"<option>\"\n\nThe angles primarily denote \"required\", and secondarily that you put\nthere there the asked input.\n\n\n>       command (subcmd1 | subcmd2) <file ...>\n\nTat is highly uncommon. In angle bracket notation this is unabiguous:\n\n        command <parameter1|parameter2> <file ...>\n                A                       B\n\nIn angles, it's clear that both A and B are required; in A, you must\nchoose one.\n\n> The \"[\" brackets mean both \"optional\" and \"group\" (to reduce number of\n> parentheses-like operators).\n\nThe bracket's primary meaning is to say \"optional\" in command\ndefinitions. They do not \"group\"; they nest -- saying that there are\nmore \"optionality\" included.\n\n>> That's why I suggested to use:\n>> \n>>     git stash <list | show [<stash>] | apply [<stash>] | clear>\n>>     git stash [save [<message>...]]\n>\n> I hope that I have explained above why I think it is wrong. IMHO the\n> \"<\" angle brackets mean: substitute your own input, and are not meant\n> for grouping (limiting where alternates start and where end).\n\nAngle brackets do not mean \"substitute your own input\", but they deonote\na requirement; how the requirement is filled is done according to the\ndescription in the documentation.\n\n    command <\"save\"|\"load\">\n\nIn unabiguous way to say that the choices for words are \"save\" and\n\"load\" of which one of them must be supplied.\n\nThe reason why angle angles are used is that they are shell redirection\nmetacharacters --- which never appear in that quality in standard manual\npage SYNOPSIS. The angles cannot be understood in any other way than as\na \"requirement\" in the command definition.\n\nJari\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"67048","messageId":"7vejbw8die.fsf@gitster.siamese.dyndns.org","threadId":"11812","inReplyTo":"k5lo716v.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-02-01T23:26:17Z","receivedAt":"2008-02-01T23:26:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jari Aalto <jari.aalto@cante.net> writes:\n\n> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>\n> * Message-Id: m33asc94xn.fsf@localhost.localdomain\n>> Jari Aalto <jari.aalto@cante.net> writes:\n>>\n>>> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>\n>>> * Message-Id: m37iho9b70.fsf@localhost.localdomain\n>>> >\n>>> >\n>>> > 'git-stash' (list | show [<stash>] | apply [<stash>] | clear)\n>>> > 'git-stash' [save [<message>...]]\n>>> >\n>>> > Angle brackets if I understand correctly are meant to denote part\n>>> > which you have to enter, the user supplied info (the reast ou have to\n>>> > enter literally).\n>>> \n>>> Nowhere I have seen \"(\" parenheses to mean \"required\". \n>>\n>> The \"(\" parentheses does not mean \"required\". They do mean \"group\",\n>> just like for regular expressions. So \"A (B | C)\" means \"A B\" or\n>> \"A C\".\n>\n> In regexp language yes, but in describing the command syntaxes, I do not\n> have come accross this. Would you have descriptive examples?\n>\n>>> The angle brackets are commonly used to tell that the part is to be\n>>> required:\n>>> \n>>>     command <option> <file ...>\n>> No, the \"<\" angle brackets are meant to denote: substitute your own\n>> (user) input, and not use as literal value. So \"command <option>\"\n>> mean select one of options ant put it in place of \"<option>\"\n>\n> The angles primarily denote \"required\", and secondarily that you put\n> there there the asked input.\n>\n>>       command (subcmd1 | subcmd2) <file ...>\n>\n> Tat is highly uncommon. In angle bracket notation this is unabiguous:\n>\n>         command <parameter1|parameter2> <file ...>\n>                 A                       B\n\nActually, I've never seen any less-than-greater-than used to\ngroup alternates command description of traditional manual\npages.  So I'd say both may be unusual, but yours is a lot more\nunusual.\n\nFor example, GNU 'tar' uses | for alternates, but it does not\nmark grouping:\n\n  SYNOPSIS\n    tar  [ - ] A --catenate --concatenate | c --create | d --diff --compare\n    | --delete | r --append | t --list | u --update | x --extract  --get  [\n    options ] pathname [ pathname ... ]\n\nwhich is horribly confusing to read.\n\nGNU 'cpio' makes it somewhat easier to read by listing\nsubcommands separately:\n\n  SYNOPSIS\n    cpio  {-o|--create} [-0acvABLV] [-C bytes] [-H format] [-M message] [-O\n    [[user@]host:]archive]            [-F            [[user@]host:]archive]\n    [--file=[[user@]host:]archive]   [--format=format]  [--message=message]\n    [--null] [--reset-access-time] [--verbose] [--dot] [--append] [--block-\n    size=blocks]      [--dereference]      [--io-size=bytes]      [--quiet]\n    [--force-local] [--rsh-command=command] [--help]  [--version]  <  name-\n    list [> archive]\n\n    cpio  {-i|--extract} [-bcdfmnrtsuvBSV] [-C bytes] [-E file] [-H format]\n    ...\n\nBut when they have alternates, they use braces {} to group them.\n\nSolaris 'tar' lists subcommand separately, and seems to use\nbraces {} for grouping alternates:\n\n  SYNOPSIS\n    tar  c   [   bBeEfFhiklnopPqvwX   [  0-7  ]  ]  [ block ]  [\n    tarfile ]  [ exclude-file ]  { -I include-file  |  -C direc-\n    tory  | file  | file }  ...\n\n\nIn our manual pages, less-than-greater-than around names are\nvery often used to mark placeholders.  If you want to say zero\nor more files, you would typically say:\n\n\tcommand <file>...\n\nUsing something other than less-than-greater-than to group\nalternates would make things easier to differentiate.  If we\nused braces {} it _might_ have been more similar to what other\npeople have traditionally done.\n"},{"id":"67054","messageId":"m3y7a46vmf.fsf@localhost.localdomain","threadId":"11812","inReplyTo":"k5lo716v.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-02-02T00:38:08Z","receivedAt":"2008-02-02T00:38:08Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jari Aalto <jari.aalto@cante.net> writes:\n\n> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>\n> * Message-Id: m33asc94xn.fsf@localhost.localdomain\n>> Jari Aalto <jari.aalto@cante.net> writes:\n>>\n>>> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>\n>>> * Message-Id: m37iho9b70.fsf@localhost.localdomain\n>>>>\n>>>>\n>>>> 'git-stash' (list | show [<stash>] | apply [<stash>] | clear)\n>>>> 'git-stash' [save [<message>...]]\n>>>>\n>>>> Angle brackets if I understand correctly are meant to denote part\n>>>> which you have to enter, the user supplied info (the reast ou have to\n>>>> enter literally).\n>>> \n>>> Nowhere I have seen \"(\" parenheses to mean \"required\". \n>>\n>> The \"(\" parentheses does not mean \"required\". They do mean \"group\",\n>> just like for regular expressions. So \"A (B | C)\" means \"A B\" or\n>> \"A C\".\n> \n> In regexp language yes, but in describing the command syntaxes, I do not\n> have come accross this. Would you have descriptive examples?\n\nIt seems that I was mistaken about that. Junio suggestion of following\nothers example and using \"{}\" curly brackets for grouping alternate\nchoices is IMHO a good solution.\n\n...or perhaps not. For example synopsis for git-branch uses this syntax.\n\n>>> The angle brackets are commonly used to tell that the part is to be\n>>> required:\n>>> \n>>>     command <option> <file ...>\n>>\n>> No, the \"<\" angle brackets are meant to denote: substitute your own\n>> (user) input, and not use as literal value. So \"command <option>\"\n>> mean select one of options ant put it in place of \"<option>\"\n> \n> The angles primarily denote \"required\", and secondarily that you put\n> there there the asked input.\n\nThe \"<>\" angle brackets does not denote required. Not in git manpages,\nnot in other manpages.\n\n>>       command (subcmd1 | subcmd2) <file ...>\n> \n> That is highly uncommon. \n\nPerhaps, but is used in git manpages.\n\n> In angle bracket notation this is unabiguous:\n> \n>         command <parameter1|parameter2> <file ...>\n>                 A                       B\n> \n> In angles, it's clear that both A and B are required; in A, you must\n> choose one.\n\nTHAT is highly uncommon.\n\n>> The \"[\" brackets mean both \"optional\" and \"group\" (to reduce number of\n>> parentheses-like operators).\n> \n> The bracket's primary meaning is to say \"optional\" in command\n> definitions. They do not \"group\"; they nest -- saying that there are\n> more \"optionality\" included.\n\nThey do group. \"command [A|B]\" means \"command\" or \"command A\" or\n\"command B\".\n\n>>> That's why I suggested to use:\n>>> \n>>>     git stash <list | show [<stash>] | apply [<stash>] | clear>\n>>>     git stash [save [<message>...]]\n>>\n>> I hope that I have explained above why I think it is wrong. IMHO the\n>> \"<\" angle brackets mean: substitute your own input, and are not meant\n>> for grouping (limiting where alternates start and where end).\n> \n> Angle brackets do not mean \"substitute your own input\", but they deonote\n> a requirement; how the requirement is filled is done according to the\n> description in the documentation.\n> \n>     command <\"save\"|\"load\">\n> \n> In unabiguous way to say that the choices for words are \"save\" and\n> \"load\" of which one of them must be supplied.\n\nIn our (git) manual pages \"<text>\" denotes placeholders.\n\nThe traditional manpages use /italics/ (usually rendered as\n_underlined_ text on terminals) to denote placeholders (user supplied\ninput).\n\nI think we better decide on syntax used in SYNOPSIS section, and\nperhaps even document it CodingGuidelines\n\n\n-- >8 --\n\n>From http://www.linux.com/articles/34212\n\n  The SYNOPSIS section describes the usage of the command. In general,\n  it should look very much like a traditional usage message. [...]\n  By convention, optional arguments are surrounded by square brackets.\n\n>From man(7)\n\n  SYNOPSIS    briefly describes the command or function's  interface.   For\n              commands,  this shows the syntax of the command and its argu-\n              ments (including options); boldface is used  for  as-is  text\n              and  italics  are  used  to  indicate  replaceable arguments.\n              Brackets ([]) surround optional arguments, vertical bars  (|)\n              separate  choices,  and  ellipses (...) can be repeated.\n\n>From manpages(5), Darwin documentation\n\n MANUAL PAGE SYNTAX\n     In manual page syntax, anything in a normal text font is required\n     text.  Anything in a boldface font is a flag or a subcommand.\n     Anything underlined is a user-specified argument such as a\n     filename.\n\n     Any argument surrounded by brackets is considered to be optional.\n     For example, [ filename ] would indicate an optional filename\n     argument.\n\n     Flags, arguments, or subcommands separated by a vertical\n     separator (|) are mutually exclusive.  For example, if -a turns\n     on an option and -b turns off the option, the syntax for this\n     command might be -a | -b.\n\n     In some cases, you may even see entire groups of arguments\n     wrapped with brackets and separated by a vertical separator. This\n     is one way of show-ing showing ing that a command has more than\n     one valid syntax.  In other manual pages, this is expressed by\n     having multiple lines in the synopsis, each of which begins with\n     the command name.  The separated format is more com-mon common\n     mon (and more readable), but is not always possible for commands\n     with particularly complex syntax.\n\n     Finally, the most important notational convention is the use of\n     the ellipsis (...).  This indicates that additional arguments may\n     be added at this point.  Depending on the author, you may see\n     this written in one of two ways:\n\n     argument [ argument... ]\n\n     argument...\n\n\nSome SYNOPSIS examples (where we use the following convention:\n*bold*, _underlined_):\n\n  *patch* [_options_] [_originalfile_ [_patchfile_]]    (shows nesting)\n  wget [_option_]... [_URL_]...                         (shows ellipsis)\n  rpm {-q|--query} [select-options] [query-options]     (shows grouping)\n  date [-u|--utc|--universal] [MMDDhhmm[[CC]YY][.ss]]   (alt + grouping)\n  *kill [ -s* _signal_ *| -p ] [ -a ] [ -- ]* _pid_ ... (as above)\n\nInside yum(8), shows alternate which is also grouping\n  * clean [ packages | headers | metadata | cache | dbcache | all ]\n\n\nSome SYNOPISIS examples from git manpages, in AsciiDoc syntax (sources):\n\n'git-add' [-n] [-v] [-f] [--interactive | -i] [--patch | -p] [-u] [--refresh]\n          [--] <filepattern>...\n\n'git-am' [--signoff] [--dotest=<dir>] [--keep] [--utf8 | --no-utf8]\n         [--3way] [--interactive] [--binary]\n         [--whitespace=<option>] [-C<n>] [-p<n>]\n         <mbox>|<Maildir>...\n\n'git-apply' [--stat] [--numstat] [--summary] [--check] [--index]\n\t  [--apply] [--no-add] [--build-fake-ancestor <file>] [-R | --reverse]\n\t  [--allow-binary-replacement | --binary] [--reject] [-z]\n\t  [-pNUM] [-CNUM] [--inaccurate-eof] [--cached]\n\t  [--whitespace=<nowarn|warn|fix|error|error-all>]\n\t  [--exclude=PATH] [--verbose] [<patch>...]\n\n'git-branch' [--color | --no-color] [-r | -a]\n\t   [-v [--abbrev=<length> | --no-abbrev]]\n\t   [--contains <commit>]\n'git-branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]\n'git-branch' (-m | -M) [<oldbranch>] <newbranch>\n'git-branch' (-d | -D) [-r] <branchname>...\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"67062","messageId":"y7a45e1h.fsf@blue.sea.net","threadId":"11812","inReplyTo":"7vejbw8die.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-02T01:43:06Z","receivedAt":"2008-02-02T01:43:06Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"* Fri 2008-02-01 Junio C Hamano <gitster@pobox.com>\n* Message-Id: 7vejbw8die.fsf@gitster.siamese.dyndns.org\n> GNU 'cpio' makes it somewhat easier to read by listing\n> subcommands separately:\n>\n>   SYNOPSIS\n>     cpio  {-o|--create} [-0acvABLV] [-C bytes] [-H format] [-M message] [-O\n>     [[user@]host:]archive]            [-F            [[user@]host:]archive]\n>     [--file=[[user@]host:]archive]   [--format=format]  [--message=message]\n>     [--null] [--reset-access-time] [--verbose] [--dot] [--append] [--block-\n>     size=blocks]      [--dereference]      [--io-size=bytes]      [--quiet]\n>     [--force-local] [--rsh-command=command] [--help]  [--version]  <  name-\n>     list [> archive]\n>\n>     cpio  {-i|--extract} [-bcdfmnrtsuvBSV] [-C bytes] [-E file] [-H format]\n\nYes, I previously presented that the other common syntax was using curly\nbraces, like here. I think we shoudl select it.\n\nJari\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"67063","messageId":"tzks5d8d.fsf@blue.sea.net","threadId":"11812","inReplyTo":"m3y7a46vmf.fsf@localhost.localdomain","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-02T02:00:34Z","receivedAt":"2008-02-02T02:00:34Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"* Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>\n* Message-Id: m3y7a46vmf.fsf@localhost.localdomain\n> It seems that I was mistaken about that. Junio suggestion of following\n> others example and using \"{}\" curly brackets for grouping alternate\n> choices is IMHO a good solution.\n\nThat is another common syntax which I presented previously.\n\n> The traditional manpages use /italics/ (usually rendered as\n> _underlined_ text on terminals) to denote placeholders (user supplied\n> input).\n\nThat does not matter. The text should stand out as it it in environment,\nwhich do not render termcap or other terminal capabilities.\n\n> From http://www.linux.com/articles/34212\n\nHere are the POSIX/Susv guidelines for the manual pages, I've marked the\nrelevant points with **....**. We were both right: Angles mean required\nand grouping.\n\nI think Git's manual pages should follow standard notation. E.g. the\nuse of parentheses should be replaced with curly braces.\n\nJari\n\n-----------------------------------------------------------------------\nhttp://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11\n\n12.1 Utility Argument Syntax\nhttp://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01\n\n    [...]\n\n    4. Frequently, names of parameters that **require** substitution by\n    actual values are shown with embedded underscores. Alternatively,\n    parameters are shown as follows:\n\n        <parameter name>\n\n    The angle brackets are used for the symbolic grouping of a phrase\n    representing a single parameter and conforming applications shall\n    not include them in data submitted to the utility.\n\n    [...]\n    7. Arguments or option-arguments enclosed in the '[' and ']'\n    notation are **optional** and can be omitted. Conforming applications\n    shall not include the '[' and ']' symbols in data submitted to the\n    utility.\n\n    8. Arguments separated by the '|' vertical bar notation are\n    **mutually-exclusive.**\n\n    9. Ellipses ( \"...\" ) are used to denote that one or **more**\n    occurrences of an option or operand are allowed. When an option or\n    an operand followed by ellipses is enclosed in brackets, **zero** or\n    more options or operands can be specified.\n\n        utility_name [-g option_argument]...[operand...]\n"},{"id":"67066","messageId":"myqk5cgf.fsf@blue.sea.net","threadId":"11812","inReplyTo":"7vejbw8die.fsf@gitster.siamese.dyndns.org","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-02T02:17:20Z","receivedAt":"2008-02-02T02:17:20Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"* Fri 2008-02-01 Junio C Hamano <gitster@pobox.com>\n* Message-Id: 7vejbw8die.fsf@gitster.siamese.dyndns.org\n\n> If we used braces {} it _might_ have been more similar to what other\n> people have traditionally done.\n\nI concur with { ... } (as earlier), I'll submit patches for those.\n\nJari\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"67067","messageId":"ir185c73.fsf@blue.sea.net","threadId":"11812","inReplyTo":"7ihp802o.fsf@blue.sea.net","subject":"[PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntax","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-02T02:22:56Z","receivedAt":"2008-02-02T02:22:56Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Change (list|...) to {list|...} to denote required commands. Adjust\nthe 'save' command syntax to better reflect the call parameters:\n[save] [message...] => [save [message...]].\n\nSigned-off-by: Jari Aalto <jari.aalto AT cante.net>\n---\n ***********************************************************************\n This is reworked patch (No. 1)\n ***********************************************************************\n\n Documentation/git-stash.txt |    4 ++--\n 1 files changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 9889806..8e343d8 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -8,8 +8,8 @@ git-stash - Stash the changes in a dirty working directory away\n SYNOPSIS\n --------\n [verse]\n-'git-stash' (list | show [<stash>] | apply [<stash>] | clear)\n-'git-stash' [save] [message...]\n+'git-stash' {list | show [<stash>] | apply [<stash>] | clear}\n+'git-stash' [save [message...]]\n \n DESCRIPTION\n -----------\n-- \n1.5.4-rc5.GIT-dirty\n"},{"id":"67068","messageId":"m3tzks6qfm.fsf@localhost.localdomain","threadId":"11812","inReplyTo":"tzks5d8d.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-02-02T02:30:18Z","receivedAt":"2008-02-02T02:30:18Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jari Aalto <jari.aalto@cante.net> writes:\n\n> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>\n> * Message-Id: m3y7a46vmf.fsf@localhost.localdomain\n> > It seems that I was mistaken about that. Junio suggestion of following\n> > others example and using \"{}\" curly brackets for grouping alternate\n> > choices is IMHO a good solution.\n> \n> That is another common syntax which I presented previously.\n\nWell, at least rpm and cpio manpages uses it.\n \n> > The traditional manpages use /italics/ (usually rendered as\n> > _underlined_ text on terminals) to denote placeholders (user supplied\n> > input).\n> \n> That does not matter. The text should stand out as it it in environment,\n> which do not render termcap or other terminal capabilities.\n\nNevertheless it would be nice if our AsciiDoc configuration generated\nitalics or underline for manpage, and italics for HTML output for\nplaceholders, *in addition* to using angle parentheses (angle braces)\nas delimites for placeholder parameters.\n\n> > From http://www.linux.com/articles/34212\n> \n> Here are the POSIX/Susv guidelines for the manual pages, I've marked the\n> relevant points with **....**. We were both right: Angles mean required\n> and grouping.\n\nErrr... as far as I understand angles means placeholders, i.e. user\nsupplied input. You can use \"[<file>...]\" for optional placeholder;\neverything which is not inside brackets is required.\n\n> I think Git's manual pages should follow standard notation. E.g. the\n> use of parentheses should be replaced with curly braces.\n\nIt is used quite frequently in git manpages. Using parentheses to\ndelimit required alternate parts seems quite sensible. \n\nExamples of usage:\n\n  'git-branch' (-m | -M) [<oldbranch>] <newbranch>\n  'git-branch' (-d | -D) [-r] <branchname>...\n  'git-commit' ... [(-c | -C) <commit> | -F <file> | -m <msg> | --amend]\n  'git-name-rev' ... ( --all | --stdin | <committish>... )\n  'git-show-branch' (-g|--reflog)[=<n>[,<base>]] [--list] [<ref>]\n  'git-update-ref' [-m <reason>] (-d <ref> <oldvalue> | [--no-deref] <ref> <newvalue> [<oldvalue>])\n\nand even stranger\n\n  'git-ls-files' ... (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\\*\n\nNote that in the POSIX/SUSV below parentheses / curly braces are not\nmentioned.\n\n> -----------------------------------------------------------------------\n> http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11\n> \n> 12.1 Utility Argument Syntax\n> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01\n> \n>     [...]\n> \n>     4. Frequently, names of parameters that **require** substitution by\n>     actual values are shown with embedded underscores. Alternatively,\n>     parameters are shown as follows:\n> \n>         <parameter name>\n> \n>     The angle brackets are used for the symbolic grouping of a phrase\n>     representing a single parameter and conforming applications shall\n>     not include them in data submitted to the utility.\n\nThis means that <param> denotes placeholder: parameter that requires\n**subsititution** (this part should be emphasized!). Such parameter\nmight have multi-word name. Such parameter might be required, but\nmight be optional.\n \n>     [...]\n>     7. Arguments or option-arguments enclosed in the '[' and ']'\n>     notation are **optional** and can be omitted. Conforming applications\n>     shall not include the '[' and ']' symbols in data submitted to the\n>     utility.\n> \n>     8. Arguments separated by the '|' vertical bar notation are\n>     **mutually-exclusive.**\n\nNote that is natural that '[' and ']' also are limits of mutualy\nexclusive parameters: \"cmd [ A | B ]\" means \"cmd\" or \"cmd A\" or \"cmd B\".\nIt is not specified explicitely, but IMHO is quite natural. And it is\nwhat is used in different manpages, see examples I have provided in my\nprevious post in this subthread.\n\n>     9. Ellipses ( \"...\" ) are used to denote that one or **more**\n>     occurrences of an option or operand are allowed. When an option or\n>     an operand followed by ellipses is enclosed in brackets, **zero** or\n>     more options or operands can be specified.\n> \n>         utility_name [-g option_argument]...[operand...]\n\nNote that one is not followed strictly, and one should take note of\nthat. For example to make sure that everybody knows that it is zero or\nmore one would use [<param>...], and to make use that it is one or\nmore one would use \"<param> [<param>...]\", just to be sure.\n\nI'm not for or against any form.\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"67070","messageId":"7vlk646pn9.fsf@gitster.siamese.dyndns.org","threadId":"11812","inReplyTo":"ir185c73.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntax","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-02-02T02:47:06Z","receivedAt":"2008-02-02T02:47:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"You know that I am not taking patches that are not fixes this\ndeep into the release freeze, don't you?\n\nI do not take patches early, and certainly I'll not take a patch\nthat changes a single page to make it the _first and only_ user\nof the convention to use curly brace to delimit required\nalternates.  It means now the whole manual set is less\nconsistent.\n\nPlease let the discussion brew for a while, and after reaching a\nconsensus on the list, send in a patch that changes parentheses\nto curly braces for _ALL_ manual pages (and does nothing else).\n"},{"id":"67092","messageId":"ejbv6813.fsf@blue.sea.net","threadId":"11812","inReplyTo":"m3tzks6qfm.fsf@localhost.localdomain","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-02T09:07:36Z","receivedAt":"2008-02-02T09:07:36Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"* Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>\n* Message-Id: m3tzks6qfm.fsf@localhost.localdomain\n\n>> he text should stand out as it it in environment,\n>> which do not render termcap or other terminal capabilities.\n>\n> Nevertheless it would be nice if our AsciiDoc configuration generated\n> italics or underline ...for manpage, and italics for HTML output for\n> placeholders, *in addition* to using angle parentheses (angle braces)\n> as delimites for placeholder parameters.\n\nSure, let's notify the asciidoc maintainer know about the wishes (CC'd)\n\n>> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html\n>>\n>> Here are the POSIX/Susv guidelines for the manual pages, I've marked the\n>> relevant points with **....**. We were both right: Angles mean required\n>> and grouping.\n>\n> Errr... as far as I understand angles means placeholders, i.e. user\n> supplied input. You can use \"[<file>...]\" for optional placeholder;\n> everything which is not inside brackets is required.\n\nIf you choose to use the \"optional\", then you are _required_ to fill in\nthe mentioned item. The \"[....]\" is applied in your example as well. The\nangles always keep it's nature, which is a requirement:\n\n    4. Frequently, names of parameters that _require_ substitution(...)\n\n        <parameter name>\n\n> It is used quite frequently in git manpages. Using parentheses to\n> delimit required alternate parts seems quite sensible.\n>\n>   'git-branch' (-m | -M) [<oldbranch>] <newbranch>\n\nThe change is small, but important. People look at the manual paged any\nwill get the wrong impression on \"the standard notation\"\n\n    git-branch {-m | -M} [<oldbranch>] <newbranch>\n               =       =\n               Change to use curlies\n\n> Note that in the POSIX/SUSV below parentheses / curly braces are not\n> mentioned.\n\nTrue. The precedence of curlies has however been set long ago in\nsoftware books and in other Unix manaul pages.\n\n>> -----------------------------------------------------------------------\n>> http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11\n>> \n>> 12.1 Utility Argument Syntax\n>> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01\n>> \n>>     [...]\n>> \n>>     4. Frequently, names of parameters that **require** substitution by\n>>     actual values are shown with embedded underscores. Alternatively,\n>>     parameters are shown as follows:\n>> \n>>         <parameter name>\n>> \n>>     The angle brackets are used for the symbolic grouping of a phrase\n>>     representing a single parameter and conforming applications shall\n>>     not include them in data submitted to the utility.\n>\n> This means that <param> denotes placeholder: parameter that requires\n> **subsititution** (this part should be emphasized!). Such parameter\n> might have multi-word name. Such parameter might be required, but\n> might be optional.\n\nIt's never optional. For optionality, there is specific notation.\nEverybody knows how to read these; what is required and what is not:\n\n    command <arg> <arg>\n    command <arg> [<message>]\n    command <arg> [-lbc]\n\nThe <message> here is symbolic and not to be taken literally, whereas\ntext that is not eclosed inside angles, \"-lbc\", is to be taken\nliterally and interpreted by the rules of \"set of options\".\n\n>>     [...]\n>>     7. Arguments or option-arguments enclosed in the '[' and ']'\n>>     notation are **optional** and can be omitted. Conforming applications\n>>     shall not include the '[' and ']' symbols in data submitted to the\n>>     utility.\n>> \n>>     8. Arguments separated by the '|' vertical bar notation are\n>>     **mutually-exclusive.**\n>\n> Note that is natural that '[' and ']' also are limits of mutualy\n> exclusive parameters: \"cmd [ A | B ]\" means \"cmd\" or \"cmd A\" or \"cmd B\".\n> It is not specified explicitely, but IMHO is quite natural. And it is\n> what is used in different manpages, see examples I have provided in my\n> previous post in this subthread.\n\nWe are in all agreement on this one.\n\n>>     9. Ellipses ( \"...\" ) are used to denote that one or **more**\n>>     occurrences of an option or operand are allowed. When an option or\n>>     an operand followed by ellipses is enclosed in brackets, **zero** or\n>>     more options or operands can be specified.\n>> \n>>         utility_name [-g option_argument]...[operand...]\n>\n> Note that one is not followed strictly, and one should take note of\n> that. For example to make sure that everybody knows that it is zero or\n> more one would use [<param>...], and to make use that it is one or\n> more one would use \"<param> [<param>...]\", just to be sure.\n\nThat's what it says. Outside of \"[]\" the ellipses mean (1+), indiside\n\"[]\", by rules of the brackets, it means (0+). I forgot to paste the\ntwo examples. Here:\n\n    utility_name -f option_argument...[operand...]\n    utility_name [-g option_argument]...[operand...]\n\nJari\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"67098","messageId":"m3prvf7ku2.fsf@localhost.localdomain","threadId":"11812","inReplyTo":"ejbv6813.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-02-02T09:45:50Z","receivedAt":"2008-02-02T09:45:50Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jari Aalto <jari.aalto@cante.net> writes:\n\n> * Fri 2008-02-01 Jakub Narebski <jnareb@gmail.com>\n> * Message-Id: m3tzks6qfm.fsf@localhost.localdomain\n> \n>>> he text should stand out as it it in environment,\n>>> which do not render termcap or other terminal capabilities.\n>>\n>> Nevertheless it would be nice if our AsciiDoc configuration generated\n>> italics or underline ...for manpage, and italics for HTML output for\n>> placeholders, *in addition* to using angle parentheses (angle braces)\n>> as delimites for placeholder parameters.\n> \n> Sure, let's notify the asciidoc maintainer know about the wishes (CC'd)\n\nErrr... I'm not sure if it is generic enough.  Although the POSIX/Susv\nyou have quoted. together with man(7) / manpage(5) pages I have quoted\nseems to tell that it is so: POSIX/Susv talks about using angle\nbrackets to denote placeholders (to be substituted), man/manpage talks\nabout using italics/underline to denote placeholders.\n\nSo to say: I'm interested what AsciiDoc maintainers would say to that.\nI have added asciidoc-discuss to Cc:, but please cull it (and the\nasciidoc maintainer) from the Cc: list when replying.\n\n>>> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html\n>>>\n>>> Here are the POSIX/Susv guidelines for the manual pages, I've marked the\n>>> relevant points with **....**. We were both right: Angles mean required\n>>> and grouping.\n>>\n>> Errr... as far as I understand angles means placeholders, i.e. user\n>> supplied input. You can use \"[<file>...]\" for optional placeholder;\n>> everything which is not inside brackets is required.\n> \n> If you choose to use the \"optional\", then you are _required_ to fill in\n> the mentioned item. The \"[....]\" is applied in your example as well. The\n> angles always keep it's nature, which is a requirement:\n> \n>     4. Frequently, names of parameters that _require_ substitution(...)\n> \n>         <parameter name>\n\nExcuse me, but item is \"required\" if it is not marked (by brackets, or\nby listing it as one of alternate calling conventions in separate\nlines) as \"optional\". So both in \"cmd -A\" and in \"cmd <file>\"\nparameters '-A' (literal) and '<file>' (to be substituted by filename)\nare required parameters, while both in \"cmd [-A]\" and in \n\"cmd [<file>]\" appropriate parameters are optional.\n\nAngle brackets does not mean required parameters. Please read\ncarefully; they denote parameters which _require substitution_ (note\nthose _two_ words together), i.e. parameters that the user need to\nreplace with appropriate input.\n\n>> It is used quite frequently in git manpages. Using parentheses to\n>> delimit required alternate parts seems quite sensible.\n>>\n>>   'git-branch' (-m | -M) [<oldbranch>] <newbranch>\n> \n> The change is small, but important. People look at the manual paged any\n> will get the wrong impression on \"the standard notation\"\n> \n>     'git-branch' {-m | -M} [<oldbranch>] <newbranch>\n>                  =       =\n>                  Change to use curlies\n\nPerhaps. This I guess needs some discussion.\n\nNevertheless if / when we decide to change to this notation to delimit\nparts of alternates / mutually exclusive parts, we would want to do\nthis in patch which changes only that, but changes it everywhere.\n\n>> Note that in the POSIX/SUSV below parentheses / curly braces are not\n>> mentioned.\n> \n> True. The precedence of curlies has however been set long ago in\n> software books and in other Unix manaul pages.\n\nI have checked a bit of manual pages (in Linux), and only very few use\nthis convention. Do you have any statistics?\n\n>>> -----------------------------------------------------------------------\n>>> http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11\n>>> \n>>> 12.1 Utility Argument Syntax\n>>> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01\n>>> \n>>>     [...]\n>>> \n>>>     4. Frequently, names of parameters that **require** substitution by\n>>>     actual values are shown with embedded underscores. Alternatively,\n>>>     parameters are shown as follows:\n>>> \n>>>         <parameter name>\n>>> \n>>>     The angle brackets are used for the symbolic grouping of a phrase\n>>>     representing a single parameter and conforming applications shall\n>>>     not include them in data submitted to the utility.\n>>\n>> This means that <param> denotes placeholder: parameter that requires\n>> **subsititution** (this part should be emphasized!). Such parameter\n>> might have multi-word name. Such parameter might be required, but\n>> might be optional.\n> \n> It's never optional. For optionality, there is specific notation.\n\nAgain: it is required if it is not optional. There is no notation for\nrequired parts, except that they are not marked as optional. In the\n\"cmd <file>\" it is not angle brackets around <file> that denotes that\nthis parameter is requires, it is lacks of \"[\" \"]\" brackets around\nparameter that tells it.\n\n> Everybody knows how to read these; what is required and what is not:\n> \n>     command <arg> <arg>\n>     command <arg> [<message>]\n>     command <arg> [-lbc]\n> \n> The <message> here is symbolic and not to be taken literally, whereas\n> text that is not eclosed inside angles, \"-lbc\", is to be taken\n> literally and interpreted by the rules of \"set of options\".\n\nAll true. And all what I wanted to tell.\n\n>> Note that is natural that '[' and ']' also are limits of mutualy\n>> exclusive parameters: \"cmd [ A | B ]\" means \"cmd\" or \"cmd A\" or \"cmd B\".\n> \n> We are in all agreement on this one.\n\nGood.\n \n>>>     9. Ellipses ( \"...\" ) are used to denote that one or **more**\n>>>     occurrences of an option or operand are allowed. When an option or\n>>>     an operand followed by ellipses is enclosed in brackets, **zero** or\n>>>     more options or operands can be specified.\n>>> \n>>>         utility_name [-g option_argument]...[operand...]\n>>\n>> Note that one is not followed strictly, and one should take note of\n>> that. For example to make sure that everybody knows that it is zero or\n>> more one would use [<param>...], and to make use that it is one or\n>> more one would use \"<param> [<param>...]\", just to be sure.\n> \n> That's what it says. Outside of \"[]\" the ellipses mean (1+), indiside\n> \"[]\", by rules of the brackets, it means (0+). I forgot to paste the\n> two examples. Here:\n> \n>     utility_name -f option_argument...[operand...]\n>     utility_name [-g option_argument]...[operand...]\n\nOoops. Sorry. This time *I* haven't read this carefully enough.\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"67100","messageId":"m3lk637j3k.fsf@localhost.localdomain","threadId":"11812","inReplyTo":"ir185c73.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntax","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-02-02T10:23:19Z","receivedAt":"2008-02-02T10:23:19Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jari Aalto <jari.aalto@cante.net> writes:\n\nI think it would beb better if you split this patch in two,\nas it deals with two separate issues, and in one case it doesn't\ndeal with the issue fully\n\n> Change (list|...) to {list|...} to denote required commands.\n\nThis is one thing, and I think when you are resubmitting this patch\nfor discussion (with Cc: to the authors that introduced the (-a|-b)\nsyntax) you should change (list|...) to {list|...} *everywhere* in the\ngit manpages.\n\n> Adjust\n> the 'save' command syntax to better reflect the call parameters:\n> [save] [message...] => [save [message...]].\n\nThis is just simple bugfix in git-stash synopsis, and I think this\npatch would be accepted (especially now that it is after 1.5.4\nreleased, and after feature freeze) without doubt.\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"},{"id":"67134","messageId":"tzkr4fqz.fsf_-_@blue.sea.net","threadId":"11812","inReplyTo":"m3lk637j3k.fsf@localhost.localdomain","subject":"[PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntax (2)","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-02T14:03:48Z","receivedAt":"2008-02-02T14:03:48Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"Adjust the command syntax to better reflect the call parameters:\n[save] [message...] => [save [<message>]].\n\nSigned-off-by: Jari Aalto <jari.aalto AT cante.net>\n---\n > [Jakub Narebski] I think it would beb better if you split this patch\n > in two,\n\n ***********************************************************************\n This is reworked patch (No. 2)\n ***********************************************************************\n\n Documentation/git-stash.txt |    7 ++++---\n 1 files changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 9889806..cd0dc1b 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -9,7 +9,7 @@ SYNOPSIS\n --------\n [verse]\n 'git-stash' (list | show [<stash>] | apply [<stash>] | clear)\n-'git-stash' [save] [message...]\n+'git-stash' [save [<message>]]\n \n DESCRIPTION\n -----------\n@@ -36,11 +36,12 @@ is also possible).\n OPTIONS\n -------\n \n-save::\n+save [<message>]::\n \n \tSave your local modifications to a new 'stash', and run `git-reset\n \t--hard` to revert them.  This is the default action when no\n-\tsubcommand is given.\n+\tsubcommand is given. The <message> part is optional and gives\n+\tthe description along with the stashed state.\n \n list::\n \n-- \n1.5.4-rc5.GIT-dirty\n"},{"id":"67135","messageId":"k5ln4eef.fsf@blue.sea.net","threadId":"11812","inReplyTo":"m3prvf7ku2.fsf@localhost.localdomain","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jari Aalto","fromEmail":"jari.aalto@cante.net","sentAt":"2008-02-02T14:32:56Z","receivedAt":"2008-02-02T14:32:56Z","isPatch":true,"sender":{"key":"jari.aalto@cante.net","avatar":"https://avatars.githubusercontent.com/u/34601?v=4"},"body":"* Sat 2008-02-02 Jakub Narebski <jnareb@gmail.com>\n* Message-Id: m3prvf7ku2.fsf@localhost.localdomain\n>>>> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html\n>> \n>>     4. Frequently, names of parameters that _require_ substitution(...)\n>> \n>>         <parameter name>\n>\n> Excuse me, but item is \"required\" if it is not marked (...)\n> Angle brackets does not mean required parameters. Please read\n> carefully; they denote parameters which _require substitution_ (note\n> those _two_ words together), i.e. parameters that the user need to\n> replace with appropriate input.\n\nWe're talking about the same subject. You emphasize the \"substitution\"\naspect, which by nature of the context, is inherently present. If you\nread your paragraph, you also conclude \"required\" -- which I emphasised\ninitially.\n\nSYNOPSIS dyntax:\n\n    command option\n\nIs inherently same as by spelling it more stronger:\n\n    command <option>\n\nBut different from\n\n    command \"option\"\n\nThe reason why I might be inclined to be on for angles is that they are\ncommonly used in BNF, and thus familiar to many:\n\n    <A> ::= <B> <C>\n\n>>> Note that in the POSIX/SUSV below parentheses / curly braces are not\n>>> mentioned.\n>> \n>> True. The precedence of curlies has however been set long ago in\n>> software books and in other Unix manaul pages.\n>\n> I have checked a bit of manual pages (in Linux), and only very few use\n> this convention. Do you have any statistics?\n\nIf you have ever skimmed Unix program book manuals, say before Linux, in\nthe Unix era, the industry quite feruently used angle curlies:\n\n    command [<options>] {save|load}\n\nEven today the braces are used to say \"you must choose\". E.g. in Oracle's\nSQL manuals. This is quite self explanatory for the basic SQL:\n\n    SELECT [DISTINCT] {*, column [AS [\"<alias>\"]], ...}\n    FROM   <table>\n    ;\n\n>>>> -----------------------------------------------------------------------\n>>>> http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap01.html#tag_01_11\n>>>> \n>>>> 12.1 Utility Argument Syntax\n>>>> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html#tag_12_01\n>>>> \n>>>>     [...]\n>>>> \n>>>>     4. Frequently, names of parameters that **require** substitution by\n>>>>     actual values are shown with embedded underscores. Alternatively,\n>>>>     parameters are shown as follows:\n>>>> \n>>>>         <parameter name>\n>>>> \n>>>>     The angle brackets are used for the symbolic grouping of a phrase\n>>>>     representing a single parameter and conforming applications shall\n>>>>     not include them in data submitted to the utility.\n>>>\n> Again: it is required if it is not optional. There is no notation for\n> required parts, except that they are not marked as optional. In the\n> \"cmd <file>\" it is not angle brackets around <file> that denotes that\n> this parameter is requires, it is lacks of \"[\" \"]\" brackets around\n> parameter that tells it.\n>\n>>     command <arg> <arg>\n>>     command <arg> [<message>]\n>>     command <arg> [-lbc]\n>> \n>> The <message> here is symbolic and not to be taken literally, whereas\n>> text that is not eclosed inside angles, \"-lbc\", is to be taken\n>> literally and interpreted by the rules of \"set of options\".\n>\n> All true. And all what I wanted to tell.\n\nI think we both read the instructions the same way. Perhaps our views do\nnot differ. I'd be surprised, because that's the convention people are\nused to having read the notations so long.\n\nJari\n\n-- \nWelcome to FOSS revolution: we fix and modify until it shines\n"},{"id":"67137","messageId":"m38x23753j.fsf@localhost.localdomain","threadId":"11812","inReplyTo":"k5ln4eef.fsf@blue.sea.net","subject":"Re: [PATCH] Documentation/git-stash.txt: Adjust SYNOPSIS command syntaxes","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2008-02-02T15:25:45Z","receivedAt":"2008-02-02T15:25:45Z","isPatch":true,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Jari Aalto <jari.aalto@cante.net> writes:\n\n> * Sat 2008-02-02 Jakub Narebski <jnareb@gmail.com>\n> * Message-Id: m3prvf7ku2.fsf@localhost.localdomain\n>>>>> http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html\n>>> \n>>>     4. Frequently, names of parameters that _require_ substitution(...)\n>>> \n>>>         <parameter name>\n>>\n>> Excuse me, but item is \"required\" if it is not marked (...)\n>> Angle brackets does not mean required parameters. Please read\n>> carefully; they denote parameters which _require substitution_ (note\n>> those _two_ words together), i.e. parameters that the user need to\n>> replace with appropriate input.\n> \n> We're talking about the same subject. You emphasize the \"substitution\"\n> aspect, which by nature of the context, is inherently present. If you\n> read your paragraph, you also conclude \"required\" -- which I emphasised\n> initially.\n\nNo, I would not.  The fact that the parameter _requires substitution_\n(is placeholder) is orthogonal (independent) of the fact if the\nparameter is required or optional.  Angle brackets (and italic or\nunderline) means \"placeholder\", while lack of angle brackets (and\nbold) means \"literal\".  Square brackets means \"optional\", while lack\nof brackets means \"required\"\n\n> SYNOPSIS syntax:\n> \n>     command option\n> \n> Is inherently same as by spelling it more stronger:\n> \n>     command <option>\n> \n> But different from\n> \n>     command \"option\"\n\nI would say that in\n\n      command option\n\nthe 'option' string is literal, while in\n\n      command <option>\n\nyou have to substitute actual option in the place of '<option>'.\nI don't think that \"option\" for literals is used in SYNOPSIS in\nmanpages, even if this notation is used elsewhere (BNF, RFC).\n\n>>>> Note that in the POSIX/SUSV below parentheses / curly braces are not\n>>>> mentioned.\n>>> \n>>> True. The precedence of curlies has however been set long ago in\n>>> software books and in other Unix manual pages.\n>>\n>> I have checked a bit of manual pages (in Linux), and only very few use\n>> this convention. Do you have any statistics?\n> \n> If you have ever skimmed Unix program book manuals, say before Linux, in\n> the Unix era, the industry quite frequently used angle curlies:\n> \n>     command [<options>] {save|load}\n\n>From what I can see in Linux manuals usually this is dealt by either\nrelying on generic placeholders, and describing optional parts in\ndetailed description, e.g.\n\n      tar <operation> [options]\n\nor by splitting synopsis into separate lines, each line dealing with\nalternate syntax, e.g.\n\n       install [OPTION]... SOURCE DEST           (1st format)\n       install [OPTION]... SOURCE... DIRECTORY   (2nd format)\n       install -d [OPTION]... DIRECTORY...       (3rd format)\n\nBut in some cases using alternates which are not optional (i.e. not \n[ A | B | C ]) is a better solution. In some cases grouping is natural\nand does not need delimiters, for example \"--opt=A|B\", but in some\ncases delimiters are required, either \"(-d | -D)\" or \"{-d | -D}\"\n\n> Even today the braces are used to say \"you must choose\". E.g. in Oracle's\n> SQL manuals. This is quite self explanatory for the basic SQL:\n> \n>     SELECT [DISTINCT] {*, column [AS [\"<alias>\"]], ...}\n>     FROM   <table>\n>     ;\n\nI'm just more used to \"(a | b)\" from regular expressions, and AFAIK\nalso BNFs, and \"{a,b}\", with comma ',' instead of vertical bar '|' to\ndenote alternates (mutually exclusive parts), like in [some] shell\nglobing, and in above documentation example.\n\nThis will be last post from me in this sub-thread. I think we have\nexhausted this part of discussion...\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"}]}