On 16 August 2017 at 10:20, Jeff King <peff@xxxxxxxx> wrote: > On Tue, Aug 15, 2017 at 01:26:53PM +0200, Martin Ågren wrote: > >> > This command reads some patches or commit messages from either the >> > -<file> arguments or the standard input if no <file> is specified. Then >> > -this command applies the arguments passed using the `--trailer` >> > -option, if any, to the commit message part of each input file. The >> > -result is emitted on the standard output. >> > +<file> arguments or the standard input if no <file> is specified. If >> > +`--parse` is specified, the output consists of the parsed trailers. >> > + >> > +Otherwise, the this command applies the arguments passed using the >> > +`--trailer` option, if any, to the commit message part of each input >> > +file. The result is emitted on the standard output. >> >> "the this" > > Thanks. > >> I think I get why you use --parse above (and in the synopsis), although >> it kind of feels like it should be --only-input or perhaps "--only-input >> (or --parse)". > > I really wanted to point people to --parse as the go-to option for the > parsing mode for the sake of simplicity (in fact I initially considered > not even exposing them at all). And I hoped that if they jumped to the > definition of --parse, that would lead them to the other options. > > I dunno. I agree it is does not read particularly well. Probably the > whole description section could be rewritten to cover the newly dual > nature of the command a bit better. But I didn't want to disrupt the > existing flow too much. Certainly. It's not like I can offer a "better" way. After thinking about this some more, I think this is a good example of "less is more". It's possibly less precise or complete in some sense, but it's probably much more useful and readable.
