Christian Couder [off-list ref] writes:
quoted
quoted
+'git interpret-trailers' [--trim-empty] [--infile=file] [<token[=value]>...]
Would it be more consistent with existing documentation to format this as so?
[--infile=<file>] [<token>[=<value>]]...
No, it would be very inconsistent:
$ grep '\.\.\.\]' *.txt | wc -l
103
$ grep '\]\.\.\.' *.txt | wc -l
0
I have a feeling that you are missing the point Eric is making. The
value given to the --infile option can be anything, i.e. 'file'
there is a placeholder, hence "--infile=<file>" not "--infile=file"
as you wrote.
Also I think "[<token>[=<value>]]..." is the correct way to spell
that there can be 0 or more "<token>[=<value>]". "<token[=value]>"
in the original does not make any sense, as <> is meant to say "this
thing is a placeholder", and we do not try to say, with the string
inside <>, what shape that placeholder takes. In fact '=' part is
_not_ a placeholder but is required syntactically when you want to
supply a value to the token, so the original doubly is incorrect.
I find it a bad taste to allow unbound set of <token> on the LHS of
'=' on the command line, but that is a separate issue in the design,
not in the documentation of the design.
Thanks.
From: Junio C Hamano <redacted>
Subject: Re: [PATCH v3 17/17] Documentation: add documentation for 'git interpret-trailers'
Date: Mon, 27 Jan 2014 13:20:18 -0800
Christian Couder [off-list ref] writes:
quoted
quoted
quoted
+'git interpret-trailers' [--trim-empty] [--infile=file] [<token[=value]>...]
Would it be more consistent with existing documentation to format this as so?
[--infile=<file>] [<token>[=<value>]]...
No, it would be very inconsistent:
$ grep '\.\.\.\]' *.txt | wc -l
103
$ grep '\]\.\.\.' *.txt | wc -l
0
I have a feeling that you are missing the point Eric is making.
Yeah I realize I missed some of his points. Sorry about that.
The
value given to the --infile option can be anything, i.e. 'file'
there is a placeholder, hence "--infile=<file>" not "--infile=file"
as you wrote.
Ok, I agree with that.
Also I think "[<token>[=<value>]]..." is the correct way to spell
that there can be 0 or more "<token>[=<value>]".
Perhaps but it is not very consistent with what there is in other
synopsis strings. For example the commands that accept a path have a
synopsis that ends with "[--] [<path>...]" and not "[--] [<path>]...".
Perhaps [(<token>[=<value>])...] is more correct, but not worth the
added complexity.
"<token[=value]>"
in the original does not make any sense, as <> is meant to say "this
thing is a placeholder", and we do not try to say, with the string
inside <>, what shape that placeholder takes. In fact '=' part is
_not_ a placeholder but is required syntactically when you want to
supply a value to the token, so the original doubly is incorrect.
Yeah perhaps, except that in the code ':' is accepted instead of '=',
and the documention says that.
So perhaps [(<token>[(=|:)<value>])...] is even more correct.
I find it a bad taste to allow unbound set of <token> on the LHS of
'=' on the command line, but that is a separate issue in the design,
not in the documentation of the design.
I don't understand this sentence, sorry.
Thanks,
Christian.