From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 08 Apr 2014 21:26:40 GMT
Subject: Re: [PATCH v10 11/12] Documentation: add documentation for 'git interpret-trailers'
Message-ID: <xmqqmwfv3433.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20140406170204.15116.15559.chriscool@tuxfamily.org>

Christian Couder <chriscool@tuxfamily.org> writes:

> +Help add RFC 822-like headers, called 'trailers', at the end of the
> +otherwise free-form part of a commit message.

I think it is somewhat misleading to use the word "headers" like
that.  'trailers' look similar to RFC-822-headers but they come at
the end.  The sentence however reads as if they are "headers" that
look like RFC 822.  Perhaps shuffling words like so:

	Help adding 'trailers' lines, that look similar to RFC 822
	e-mail headers, at the end of the ...

would make it less confusing.

> +Some configuration variables control the way the `token` arguments are
> +applied to the message and the way any existing trailer in the message
> +is changed. They also make it possible to automatically add some
> +trailers.
> +
> +By default, a 'token=value' or 'token:value' argument will be added
> +only if no trailer with the same (token, value) pair is already in the
> +message. The 'token' and 'value' parts will be trimmed to remove
> +starting and trailing whitespace, and the resulting trimmed 'token'
> +and 'value' will appear in the message like this:
> +
> +------------------------------------------------
> +token: value
> +------------------------------------------------

Mental note: this does assume that the final output for the 'token'
is to have a line <label> that is followed by a colon ":", SP and
the value.

And the natural way to express that on the command line would be to
say "token: value", I would think, but let's just read on.

> +Note that 'trailers' do not follow and are not intended to follow many
> +rules that are in RFC 822. For example they do not follow the line
> +breaking rules, the encoding rules and probably many other rules.

s/that are in RFC 822/for RFC 822 headers/.
s/line breaking/line folding/. (see RFC 822, 3.1.1)

> +OPTIONS
> +-------
> +--trim-empty::
> +	If the 'value' part of any trailer contains only whitespace,
> +	the whole trailer will be removed from the resulting message.
> +
> +CONFIGURATION VARIABLES
> +-----------------------
> +
> +trailer.<token>.key::
> +	This 'key' will be used instead of 'token' in the

As `key` is something that is typed literally, it should be typeset
as `key` in the descriptive text.  I think other manpages spell the
placeholder as `<token>` (or '<token>', I am not sure which...).

> +	trailer. After some alphanumeric characters, it can contain
> +	some non alphanumeric characters like ':', '=' or '#' that will
> +	be used instead of ':' to separate the token from the value in
> +	the trailer, though the default ':' is more standard.

I assume that this is for things like

	bug #538

and the configuration would say something like:

	[trailer "bug"]
        	key = "bug #"

For completeness (of this example), the bog-standard s-o-b would
look like

	Signed-off-by: Christian Couder <chriscool@tuxfamily.org>

and the configuration for it that spell the redundant "key" would
be:

	[trailer "Signed-off-by"]
        	key = "Signed-off-by: "

Am I reading the intention correctly?

That is, when trailer.<token>.key is not defined, the value defaults
to "<token>: " (with one SP after the label and colon), and when it
is defined, the value can come directly after it.