On Thu, Sep 25, 2008 at 03:44:34PM -0500, Michael Witten wrote:
> 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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
