Jari Aalto venit, vidit, dixit 16.04.2010 13:46:
quoted text
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> jari.aalto@cante.net venit, vidit, dixit 15.04.2010 17:37:
>>
>>> From: Jari Aalto <jari.aalto@cante.net>
>>>
>>>
>>> Signed-off-by: Jari Aalto <jari.aalto@cante.net>
>>> ---
>>>  Documentation/git-send-email.txt |   36 ++++++++++++++++++++++++++++++++++--
>>>  1 files changed, 34 insertions(+), 2 deletions(-)
>>>
>>> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
>>> index ced35b2..8b33eb0 100644
>>> --- a/Documentation/git-send-email.txt
>>> +++ b/Documentation/git-send-email.txt
>>> @@ -299,8 +299,40 @@ sendemail.confirm::
>>>  	one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'
>>>  	in the previous section for the meaning of these values.
>>>  
>>> +EXAMPLES
>>> +--------
>>>  
>>> -Author
>>> +To batch send all patches to a mailig list, no copies to oneself,
>>> +messages in a relaxed single thread format (no nesting) and don't ask
>>> +any confirmations:
>>
>> That sentence is linguistically screwed, but...
> 
> Please improve. How would you explain the options and their explanations
> one-by-one as presented below?

By "but..." and the paragraph below I meant to say that there is no need
to pick on individual typos and such, because I don't favour the
approach anyways.

Looking at the send-email man page, I definitely agree with you that
there is room for improvement. For example, in the end there is a
configuration section listing only very few of the config options. The
reader could easily think these are the only ones. We tend to list them
in git-config's man page, which one may or may not like...

quoted text
> 
>>> +
>>> +	git send-email \
>>> +		--from $EMAIL \
>>> +		--to address@list.example.com \
>>> +		--suppress-cc=author \
>>> +		--suppress-from \
>>> +		--no-chain-reply-to \
>>> +		--confirm=never \
>>> +		outgoing/
>>> +
>>
>> ... I don't think this is a good example at all. All options are
>> explained in the man page, so what is the point in listing and
>> explaining some of them here?
> 
> Right, all the 31 options.
> 
>> If we really want an introductory example,
>> we want one with few options, where the default behaviour is explained.
> 
> I don't agree.
> 
> We need examples that use most of the options in combination so that the
> examples can practically "copy pasted / sliced off". The user can eaily
> reduce options he may not find useful from the examples.
> 
>     With too few options presented, he needs to skim through the whole
>     of 31 option explanations above and pray he finds what he needs.
> 
> Please suggest another example to be accompanied with this one. How do
> you use the git-send-email? What options? What you have configured in
> ~/.gitconfig?

I don't use any options besides --dry-run and --cc, which is the point
of the config options ;) In config I have to, smtpserver (pointing to an
msmtp-script), bcc, suppresscc, aliasesfile, aliastype, but that depends
on the project, of course (git.git here).

I just think that using all these options on the command line is very
atypical. It would be helpful to see the defaults in one place:

"Without any options, send-email will send patches (using
/usr/sbin/sendmail or /usr/lib/sendmail or localhost) using any from, cc
and subject lines contained in the patch files; you have to specify at
least --to, or else you will be prompted for it.

All defaults pertaining to composing and sending of the patch mails and
to automating this process can be changed with config options, see the
corresponding sections below."

I liked your format-patch example with merge-base, I just liked it
better in format-patch's man page ;)

Michael
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html