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

From: Junio C Hamano <[email-masked]>
Date: Wed, 28 May 2014 12:44:36 -0700

Christian Couder <[email-masked]> writes:

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