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

> On 14-08-16 12:06 PM, Christian Couder wrote:
>
>> +The trailers are recognized in the input message using the following
>> +rules:
>> +
>> +* by default only lines that contains a ':' (colon) are considered
>
> s/contains/contain/

>> +  trailers,
>> +
>> +* the trailer lines must all be next to each other,
>> +
>> +* after them it's only possible to have some lines that contain only
>> +  spaces, and then a patch; the patch part is recognized using the
>> +  fact that its first line starts with '---' (three minus signs),
>
> Is that "starts with" or "consists solely of"?

>> +
>> +* before them there must be at least one line with only spaces.
>
> I had little bit of trouble parsing those three points, and it seems like a
> lot of text to describe something simple.  How about a single paragraph:
>
> Existing trailers are extracted from the input message by looking for a group
> of one or more lines that contain a colon (by default), where the group is
> preceded by one or more empty (or whitespace-only) lines.  The group must
> either be at the end of the message or be the last non-whitespace lines
> before a line that starts with '---' (three minus signs).

>> +Note that 'trailers' do not follow and are not intended to follow many
>> +rules for RFC 822 headers. For example they do not follow the line
>> +folding rules, the encoding rules and probably many other rules.
>> +
>> +OPTIONS
>> +-------
>> +--trim-empty::
>> +     If the <value> part of any trailer contains only whitespace,
>> +     the whole trailer will be removed from the resulting message.
>> +     This apply to existing trailers as well as new trailers.
>> +
>> +--trailer <token>[(=|:)<value>]::
>> +     Specify a (<token>, <value>) pair that should be applied as a
>> +     trailer to the input messages. See the description of this
>> +     command.
>> +
>> +CONFIGURATION VARIABLES
>> +-----------------------
>> +
>> +trailer.separators::
>> +     This option tells which characters are recognized as trailer
>> +     separators. By default only ':' is recognized as a trailer
>> +     separator, except that '=' is always accepted on the command
>> +     line for compatibility with other git commands.
>> ++
>> +The first character given by this option will be the default character
>> +used when another separator is not specified in the config for this
>> +trailer.
>> ++
>> +For example, if the value for this option is "%=$", then only lines
>> +using the format '<token><sep><value>' with <sep> containing '%', '='
>> +or '$' and then spaces will be considered trailers. And '%' will be
>> +the default separator used, so by default trailers will appear like:
>> +'<token>% <value>' (one percent sign and one space will appear between
>> +the token and the value).
>> +
>> +trailer.where::
>> +     This option tells where a new trailer will be added.
>> ++
>> +This can be `end`, which is the default, `start`, `after` or `before`.
>> ++
>> +If it is `end`, then each new trailer will appear at the end of the
>> +existing trailers.
>> ++
>> +If it is `start`, then each new trailer will appear at the start,
>> +instead of the end, of the existing trailers.
>> ++
>> +If it is `after`, then each new trailer will appear just after the
>> +last trailer with the same <token>.
>> ++
>> +If it is `before`, then each new trailer will appear just before the
>> +last trailer with the same <token>.
>
> It seems to me that it would be more sensible to make the new trailer appear
> before the *first* trailer with the same token.