Try to improve help options text for basic commands

[timeless]

On Sat, Nov 21, 2009 at 12:42 AM, Matt Mackall <mpm at selenic.com> wrote:
>> +    working directory has two parents, you must explicitly specify a
>> +    revision.
>
> I think this would be better as 'which revision'. Not sure dropping 'to
> revert to' improves matters, barring prudish avoidance of dangling
> prepositions.

I was being prudish. Using "which revision" or "which parent revision"
or "the parent revision" would work.
or perhaps "the desired revision".

Suggestions welcome.

>> -           _('a changeset up to which you would like to bundle')),
>> +           _('a changeset intended to be added to the destination')),
>
> I think this should be much closer to what we've used for clone -r. ie:
>
> 'bundle only the specified revisions and ancestors'

my problem with "only" is that it's wrong :).
If my base includes a given changeset then it won't be included :).
And each individual argument only involves a single revision.

I really think that the help for bundle (and perhaps push/pull) needs
to remind people in the body that it involves DAGs.
(And I probably should have included that in this changeset, but I was
being hasty -- an error indeed.)

> 'do not check out a working copy'

sounds good

>> -           _('clone only the specified revisions and ancestors')),
>> +           _('include the specified changeset')),
>
> Doesn't mention ancestors, possibility of multiple arguments or ranges,
> or that everything else is excluded.

This again really needs to rely on the body text. People need to
understand that selecting a point on the graph they are naturally
selecting its ancestors but are not selecting descendants unless some
other point they've selected does.

Somehow the help text needs to indicate which options are
multiplicable and which aren't. Sometimes -r can be used more than
once (pull, push, clone), sometimes it can't (cat, ann).

>> +           _('a remote changeset intended to be added')),
>
> Should match clone/pull/bundle.

I'm trying to ensure they're consistent (minus directionality).