Re: [PATCH v12 11/11] Documentation: add documentation for 'git interpret-trailers'

From: Junio C Hamano <gitster@pobox.com>
Date: May 28, 2014, 19:44 UTC
Message-ID: <xmqqa9a1d6xn.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20140525053223.5329.28002.chriscool@tuxfamily.org>

Christian Couder <chriscool@tuxfamily.org> writes:

Show 12 quoted lines

> +trailer.<token>.key::
> +	This `key` will be used instead of <token> in the
> +	trailer. After the last alphanumeric character, this variable
> +	can contain some non alphanumeric characters, like for example
> +	`'%'` (one percent sign), `' = '` (one space followed by one
> +	equal sign and then one space), `' #'` (one space followed by
> +	one number sign) or even just `' '` (one space), that will be
> +	used to separate the <token> from the <value> in the
> +	trailer. The default separator, `': '` (one colon followed by
> +	one space), which is the usual standard, is added only if the
> +	last character in `key` is alphanumeric, so watch out for
> +	unwanted trailing spaces in this variable.

Perhaps corollary to the other review comment to this patch, I think this is overly complex without giving more value to the users than it causes confusion.

If the goal is to allow random syntax on the output side, why do you even need to list percent, pound, etc., when you can just say "The key is emitted and then your value" and the user will get exactly what they specified to be emitted?

Any magic applied on top (namely, we would add ": " only in certain circumstances) only makes things unnecessarily complex; I think your having to say "so watch out for..." is a clear indication of that.

If we use the "separator", so that we can recognise a line with an unseen key as a trailer we do not know about, we should stick to just a single standard one ':' and I think it is OK to add a missing ": " by magic if that is the direction we are going to take, though.