Re: [PATCH RFC 4/6] Docs: send-email: Option order the same in man page and usage text

From: Jeff King <peff@peff.net>
Date: Sep 26, 2008, 22:40 UTC
Message-ID: <20080926224032.GA24817@coredump.intra.peff.net>
In-Reply-To: <1222375476-32911-4-git-send-email-mfwitten@mit.edu>

On Thu, Sep 25, 2008 at 03:44:34PM -0500, Michael Witten wrote:

Show 6 quoted lines

> The man page seems to have listed the options in alphabetical order,
> while the usage text used what I would consider an `intuitive' order
> that groups related items and presents them in the order peopl think
> when writing an email.
> 
> The manual page has been updated to mirror this order.

I think overall this serious is well-intentioned the results look sane to me (I diffed the manpage and usage text before and after).

My only concerns are:

  4/6: I am not sure about making the order of options the same, as the
       two formats serve different purposes. I think "git send-email
       --foo" should present the options based on commonality of use.
       You clearly got the usage wrong, so I think it is helping you to
       figure out quickly what you probably meant.

       The manpage, on the other hand, is a comprehensive reference and
       so should probably be alphabetized for easy reading.

       That being said, I find the length of the current usage statement
       somewhat ridiculous. I wonder if it would be better still to just
       mention in the usage the overall syntax (i.e., "send-email
       [options] <file | directory>", the few most common options (with
       minimal description), and then refer to the manpage for complete.
       With the goal of taking no more than 10 or so lines (the current
       output is 71 lines!).

  5/6: This isn't really a documentation patch, as it adds a new config
       option. I think the result is reasonable, but it was a surprise
       after reading the rest of the series.

       I was also going to complain that there was no entry in
       Documentation/config.txt for the new option, but I see that none
       of the sendemail options are there. Maybe while you are working
       on this, it is worth factoring them out to send-email-options.txt
       and including it in both git-send-email.txt and config.txt.

-Peff