Suboptimal documentation?

[Kastner Masilko, Friedrich]

> From: Mercurial [mailto:mercurial-bounces at selenic.com] On Behalf Of Alan Mackenzie
>
> hg help branch (and the corresponding bit in the man page) says:
> 
>     With no argument, show the current branch name. With one argument,
>     set the working directory branch name (the branch will not exist in the
>     repository until the next commit). Standard practice recommends that
>     primary development take place on the 'default' branch.
> 
> Although one can work through this to a meaning, it is surely more opaque
> than it need be.  hg branch _creates_ a branch; it does not rename the
> current branch (which is a possible interpretation of "set the working
> directory branch name").
> 
> How about the following replacement for the second sentence:
> 
>     With one argument, create a new branch with that name.  The branch
>     will exist in the repository after the next commit.

I think that this replacement is giving misleading information. "hg branch" is not creating a new branch. Not even necessarily a new named-branch. All it does is marking the working directory with a name, and this is described with the current text as good as it gets IMHO.

Perhaps it would be better to reference a new topic page that describes the named-branches concept in more detail, showing the various situations that this node-coloring can establish (multiple heads/roots, scattered branch nodes, etc.).

Regards,
Fritz

P.S.: Don’t get discouraged by the communication style of the Grumpy Old Leader(TM). I'm sure ideas, suggestions, and positive criticism are still welcome on this list, even if this exists: http://mercurial.selenic.com/wiki/mpm/moot .


Development Engineering Software Suite
Festo Gesellschaft m.b.H.
Linzer Strasse 227
Austria - 1140 Wien

Firmenbuch Wien
FN 38435y
UID: ATU14650108

Tel: +43(1)91075-198
Fax: +43(1)91075-282
www.festo.at

Der Inhalt dieser E-Mail und moeglicher Anhaenge sind ausschliesslich fuer den bezeichneten Adressaten bestimmt.
Jede Form der Kenntnisnahme, Veroeffentlichung, Vervielfaeltigung oder Weitergabe des Inhalts dieser E-Mail und
moeglicher Anhaenge durch unberechtigte Dritte ist unzulaessig. Wir bitten Sie, sich mit dem Absender der E-Mail in
Verbindung zu setzen, falls Sie nicht der Adressat dieser E-Mail sind sowie das Material von Ihrem Computer zu loeschen.

This e-mail and any attachments are confidential and intended solely for the addressee. The perusal, publication, copying or
dissemination of the contents of this e-mail by unauthorised third parties is prohibited. If you are not the intended recipient of this
e-mail, please delete it and immediately notify the sender.