[PATCH] resolve: updated help with info about merge tools

[Mads Kiilerich]

On 10/15/2010 01:14 PM, Erik Zielke wrote:
> diff -r 4bca87c29445 -r 66b3736fc045 doc/hgrc.5.txt
> --- a/doc/hgrc.5.txt	Thu Oct 14 22:53:17 2010 +0200
> +++ b/doc/hgrc.5.txt	Fri Oct 15 13:14:22 2010 +0200
> @@ -858,14 +858,24 @@
>      The conflict resolution program to use during a manual merge.
>      There are some internal tools available:
>
> +    ``internal:merge``
> +        Uses the internal non-interactive merge tool for
> +        merging files.
...

The changes looks nice, but wouldn't it be better to describe all the 
merge options and internal tools in the merge-tools section? (Or in a 
new help topic...)

> diff -r 4bca87c29445 -r 66b3736fc045 mercurial/commands.py
> --- a/mercurial/commands.py	Thu Oct 14 22:53:17 2010 +0200
> +++ b/mercurial/commands.py	Fri Oct 15 13:14:22 2010 +0200
> @@ -2951,6 +2951,13 @@
>       merge conflicts. You must use :hg:`resolve -m ...` before you can
>       commit after a conflicting merge.
>
> +    It is possible to use different merge tools, either internal
> +    or external. The internal tools are ``internal:merge``, ``internal:fail``,
> +    ``internal:local``, ``internal:other``, ``internal:dump``, and
> +    ``internal:dump``, and can be set by the configuring the ui.merge
> +    configuration setting. See :hg:`config` and the hgrc(5) man page for more
> +    information on how to set configuration values.
> +
>       Returns 0 on success, 1 if any files fail a resolve attempt.
>       """

The same text is just as relevant (or even more) in the merge help. Why 
should it be in the resolve help?

I am however not sure we want this level of detail in the help text. The 
merge tool configuration tools usually just works and the internal tools 
are for special uses, so describing it here might confuse ordinary users 
more than it helps. It could perhaps be an admonition.

Especially the reference to 'hg config' is _very_ helpful, but the help 
would become very verbose if we consistenly should go into that level of 
detail everywhere.

The reference to ui.merge is only one side of the story, so it might be 
a bit misleading to just tell the simple story. I think it would be nice 
to have more of the information on 
http://mercurial.selenic.com/wiki/MergeProgram and 
http://mercurial.selenic.com/wiki/MergeToolConfiguration available in 
the help or man page - especially regarding how merge tools are chosen.

(A slightly related note: The poor windows users don't know what a man 
page is and we don't have a good cross-platform way to reference it. 
Perhaps the man pages could be available as help topics too - and thus 
also in the hgweb help?)

/Mads