helptext upstream feedback

[Martin Geisler]

Fabian <fabian.kreutz+google at starnet.fi> writes:

Hi Fabian

Thank you for your suggestions!

> To 4.: Why not refer directly to the difference:
> "Unlike a centralized RCS, this operation is a local operation. See hg
> push for means to actively distribute your changes."

Good idea, I've put this into the help (fc4a3931e608).

> To 5.: So what then? I'll be on vacation for two weeks. After that I
> can go through all references in the english help texts, if you want.

I think it's more a matter of finding the one good term, if any.

> Here comes the next batch:
>
> 6. Help text for manifest: first and second paragraph are redundant:
> delete 1st.

I've merged them (a62fc8fe882f).

> 7. help text for merge: Circular definition of "merge" via the word
> "merge".
> Suggestion: all changes of the other revision since last common
> predecessor are applied to workdir.
> Mention that the new commit has two parents.
> "Changes" (i.e. editing a file) are allowed, but no hg add/rm/merge...

I've put something like this in (1cd3775e097c).

> 8. The targets of "see also"s are sometimes enclosed in double quotes,
> sometimes single quotes.

Thanks, I've changed them to single quotes (a8a719ff150a).

> 9. Help for pull could refer (see also) to "paths" (concerning
> default) and "incoming".
> Further the pull happens to *THE* local repo.

Good point (3d8252430e17).

> 10. Same for push and paths + outgoing.
> Further, it does not "help to move", but is rather the one way to
> actively move.*)

Yeah, I also think we should be more precise (20df260ae301).

> In the same paragraph a comma is missing and isn't it identical to a
> pull even if the dest is not local?

I think so. There might be an asymmetry where I can push from A to B,
but cannot pull from A into B due to firewalls, but apart from that I
believe it should be correct to say that push == "reversed pull".

>    This is the symmetrical operation for pull. It transfers the changes
>    from the current repository actively to a different one. If the
>    destination is local, this is identical to a pull in that directory
>    from the current one.

> The next paragraph could refer to --force

It could, but we don't want to encourage people to use the --force
option too often since it is usually the wrong thing to do.

> -r sends a revision, not a changeset

Agreed.

> *) Sorry! I'm so particular about this, because people from
> distributed RCSs (and those are a main target audience for the help
> texts) need definite guidance and not something that implies that
> you're supposed to do something else and this command only helps a
> bit. Especially push and pull need to state exactly what they are used
> for, rather than what they internally do.

I agree, we want to come across as clearly as possible to people who are
only used to centralized systems.

> 11. help for resolve: I don't get it and thus never understand the
> command.

I've only used it once -- unsuccessful merges seem to be quite rare! :-)

> I see that there has been discussion about this before in December.
> http://www.nabble.com/hg-resolve-td20932378.html
> BTW: The "usage" message is wrong, as it does not require a file.
> So, does it recreate a conflict?

Sort of -- it recreates the three-way merge situation. When you run 'hg
merge' changes are applied like described above, and these changes might
conflict. In that case there are three important revisions for a given
file: the working directory revision (A) the revision in the other head
(B) and the common base revision (C).

The resolve command will dig out these three revisions and launch your
configured merge program to do a three-way merge between them.

I've tried to improve the help text by describing when to use the -m
switch in order to keep manually resolved files (cab4a521a3fd).

> Finally you could mention that commit will refuse to work until all
> files are marked as resolved.

I've done this as well.

> As you can see in the above link, this is (also for me) a major point
> of confusion and frustration.

Yeah, it's a relatively new command so the documentation (the Hg book in
particular) doesn't mention it much.

-- 
Martin Geisler

VIFF (Virtual Ideal Functionality Framework) brings easy and efficient
SMPC (Secure Multiparty Computation) to Python. See: http://viff.dk/.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 196 bytes
Desc: not available
Url : http://selenic.com/pipermail/mercurial-devel/attachments/20090404/04c0e1ca/attachment.pgp