Try to improve help options text for basic commands

[Faheem Mitha]

On Sat, 21 Nov 2009 18:25:53 +0200, timeless <timeless at gmail.com> wrote:
> 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.)

+1 on saying something about DAGs. I think including something about
the DAG in the help would be a very good idea. Set up some
terminology, then it can be referenced in the rest of the help. This
has the big advantage of being precise, then we won't need to have
arguments about whether the wording is good enough.

hg help DAG

anyone?

>> '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).

Agreed. Currently the help text is not very consistent about
this. Eg. 'hg backout' says nothing about the possibility of multiple
-r args, though it accepts them.

>>> +           _('a remote changeset intended to be added')),
>>
>> Should match clone/pull/bundle.
>
> I'm trying to ensure they're consistent (minus directionality).

                                                 Regards, Faheem.