1.1 --- a/en/tour-basic.tex	Thu Mar 22 00:07:01 2007 -0700
     1.2 +++ b/en/tour-basic.tex	Sun May 27 09:48:47 2007 -0700
     1.3 @@ -358,21 +358,41 @@
     1.4  
     1.5  \subsection{Setting up a username}
     1.6  
     1.7 -When you try to run \hgcmd{commit} for the first time, it may succeed
     1.8 -immediately, or it may fail with an error message that looks like
     1.9 -this.
    1.10 -\interaction{tour.commit-no-user}
    1.11 -If it succeeds for you, the chances are that either you already have a
    1.12 -file called \sfilename{.hgrc} in your home directory, or an
    1.13 -environment variable set named \envar{EMAIL}.
    1.14 -
    1.15 -When you commit, Mercurial wants to know what your name is, so that it
    1.16 -can record it.  If you have created a \sfilename{.hgrc} file, it will
    1.17 -look in there.  If it doesn't find something suitable, it will see if
    1.18 -your \envar{EMAIL} address is set.  If neither of these is present, it
    1.19 -will produce the error message you can see above.
    1.20 +When you try to run \hgcmd{commit} for the first time, it is not
    1.21 +guaranteed to succeed.  Mercurial records your name and address with
    1.22 +each change that you commit, so that you and others will later be able
    1.23 +to tell who made each change.  Mercurial tries to automatically figure
    1.24 +out a sensible username to commit the change with.  It will attempt
    1.25 +each of the following methods, in order:
    1.26 +\begin{enumerate}
    1.27 +\item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
    1.28 +  command on the command line, followed by a username, this is always
    1.29 +  given the highest precedence.
    1.30 +\item If you have set the \envar{HGUSER} environment variable, this is
    1.31 +  checked next.
    1.32 +\item If you create a file in your home directory called
    1.33 +  \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
    1.34 +  used next.  To see what the contents of this file should look like,
    1.35 +  refer to section~\ref{sec:tour-basic:username} below.
    1.36 +\item If you have set the \envar{EMAIL} environment variable, this
    1.37 +  will be used next.
    1.38 +\item Mercurial will query your system to find out your local user
    1.39 +  name and host name, and construct a username from these components.
    1.40 +  Since this often results in a username that is not very useful, it
    1.41 +  will print a warning if it has to do this.
    1.42 +\end{enumerate}
    1.43 +If all of these mechanisms fail, Mercurial will fail, printing an
    1.44 +error message.  In this case, it will not let you commit until you set
    1.45 +up a username.
    1.46 +
    1.47 +You should think of the \envar{HGUSER} environment variable and the
    1.48 +\hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
    1.49 +\emph{override} Mercurial's default selection of username.  For normal
    1.50 +use, the simplest and most robust way to set a username for yourself
    1.51 +is by creating a \sfilename{.hgrc} file; see below for details.
    1.52  
    1.53  \subsubsection{Creating a Mercurial configuration file}
    1.54 +\label{sec:tour-basic:username}
    1.55  
    1.56  To set a user name, use your favourite editor to create a file called
    1.57  \sfilename{.hgrc} in your home directory.  Mercurial will use this