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

Christian Couder [off-list ref] writes:

On Sat, Apr 5, 2014 at 12:42 AM, Junio C Hamano [off-list ref] wrote:

quoted

Junio C Hamano [off-list ref] writes:

quoted

Christian Couder [off-list ref] writes:
"The following features are planned but not yet implemented:
        - add more tests related to commands
        - add examples in documentation
        - integration with "git commit""

I was planning to merge the series to 'next', but perhaps we should
wait at least for the first two items (I do not think the third one
is necessary to block the series).

I will send soon a new version of the series with more tests and fixes.
It will also contains a patch that adds an empty line before the
trailers in the output if there is not already one.

Ah, yes, that one was mentioned in the reviews, I remember.

After that I plan to work on adding examples to the documentation.

OK, thanks.

First accepting both ':' and '=' means one can see the "git
interpret-trailers" as acting on trailers only. Not just on trailers
from the intput message and option parameters from the command line.

Sorry, you lost me.  What does "acting on trailers only" really
mean?  Do you mean the command should/can be run without any command
line options, pick up the existing "Signed-off-by:" and friends in
its input and emit its output, somehow taking these existing ones as
its instruction regarding how to transform the input to its output?

And second there is also a practical advantage, as the user can
copy-paste trailers directly from other messages into the command line
to pass them as arguments to "git interpret-trailers" without the need
to replace the ':' with '='. Even if this command is not often used
directly by users, it might simplify scripts using it.

Third there is a technical advantage which is that the code that
parses arguments from the command line can be the same as the code
that parses trailers from the input message.

I do not see these two as valid arguments to make the command line
more complex to the end users---who now need to know that only this
command treats its command line in a funny way, accepting a colon in
place of an equal sign.

A different way to sell a colon, e.g.

    Consider the instruction sed takes on its command line.
    (e.g. "sed 's/frotz/nitfol/' <xyzzy").  In the most general
    form, you would always give it as the value of an '-e' option
    (e.g. "sed -e 's/frotz/nitfol' <xyzzy"), but you are allowed to
    be loose in limited occassions.  "Key:value" is like that, and
    in the most general form, it actually needs to be spelled as
    "-e 'Key:value'".

is possible, but I do not think it is a particularly good analogy,
because what you have as the alternative is "Key=value", and not
"-e 'Key:value'", or "--Key=value" (the last would probably be the 
most natural way to express this).

From: Junio C Hamano <redacted>

Christian Couder [off-list ref] writes:

quoted

First accepting both ':' and '=' means one can see the "git
interpret-trailers" as acting on trailers only. Not just on trailers
from the intput message and option parameters from the command line.

Sorry, you lost me.  What does "acting on trailers only" really
mean?

It means that the command can seen as processing only trailers, (from
stdin and from its arguments), sorry if I used the wrong verb.

Do you mean the command should/can be run without any command
line options, pick up the existing "Signed-off-by:" and friends in
its input and emit its output, somehow taking these existing ones as
its instruction regarding how to transform the input to its output?

quoted

And second there is also a practical advantage, as the user can
copy-paste trailers directly from other messages into the command line
to pass them as arguments to "git interpret-trailers" without the need
to replace the ':' with '='. Even if this command is not often used
directly by users, it might simplify scripts using it.

Third there is a technical advantage which is that the code that
parses arguments from the command line can be the same as the code
that parses trailers from the input message.

I do not see these two as valid arguments to make the command line
more complex to the end users

I don't think that it makes the command more complex to the end users.

---who now need to know that only this
command treats its command line in a funny way, accepting a colon in
place of an equal sign.

It accepts both. So if they think that it is like a regular command,
which uses '=' for (key, value) pairs, it will work, and if they think
it works on trailers, which use ':' for (key, value) pairs, it will
also work.

A different way to sell a colon, e.g.

    Consider the instruction sed takes on its command line.
    (e.g. "sed 's/frotz/nitfol/' <xyzzy").  In the most general
    form, you would always give it as the value of an '-e' option
    (e.g. "sed -e 's/frotz/nitfol' <xyzzy"), but you are allowed to
    be loose in limited occassions.  "Key:value" is like that, and
    in the most general form, it actually needs to be spelled as
    "-e 'Key:value'".

is possible, but I do not think it is a particularly good analogy,
because what you have as the alternative is "Key=value", and not
"-e 'Key:value'", or "--Key=value" (the last would probably be the 
most natural way to express this).

The analogy that I would use is rather that Perl lets people use
's:foo:bar:' as well as 's=foo=bar=' instead of 's/foo/bar/' if they
prefer.