Re: [PATCH v3 17/17] Documentation: add documentation for 'git interpret-trailers'

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 27, 2014, 21:20 UTC
Message-ID: <xmqqfvo9nmul.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20140127.213344.212708599170084659.chriscool@tuxfamily.org>

Christian Couder <chriscool@tuxfamily.org> writes:

Show 12 quoted lines

>>> +'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.