Updated Quick Start and Usage docs

[Sanjoy Mahajan]

[Sorry for the resend: I meant to send this to the list as well, just
in case I suggested anything silly that others notice. -SM]

Re: Quick start

Great document!  Some comments:

Under "Working Directory" on the top left: 

(a) "may not be present" -> "need not be present" or "might not be
present".  Whereas "may not" has as one of its implications that it is
forbidden ("defense d'exister", if my French grammar isn't too
mangled).  For example, "You may not travel without a passport."

(b) "these files can be safely copied by others".  There are two
problems:

First, 'unsafe' might worry the reader into thinking that if
someone copies the files, bad things could happen to your repository
(e.g. you give away secret cryptographic information).  Whereas by
safe/unsafe you mean that it's safe/unsafe *for the copier* because he
will get stable/buggy code.

Second, the reader might think "Okay, the working directory is safe to
copy but I wonder what's unsafe to copy?  Oh, the .hg directory,
because that's the other half of the diagram."  Whereas you mean that
the working repositories are unsafe to copy.  But the reader hasn't
read about them yet, so isn't likely to make that deduction right
away.

The "pull" arrow between the Public Repository and the Working
Repository is a bit confusing.  It's tail is in the source repository,
which is fine, but it's head is in the destination working directory.
But pull by itself won't change the working directory.  You need -u
for update.  Oh, wait it's okay because in the Working Repository, the
top half is the .hg.  But that's not obvious at first glance, so maybe
label it with a ".hg" somewhere.

Under "Working repository":

(a) "maybe integrated" -> "may be integrated".  

"to the project repository" -> "to the public repository" (no mention
of a project repository before)

Along with a few other small changes, perhaps: 

  When your changes are ready, you can push them to public repository so
  that they are available to other developers and may be integrated into
  the latest stable version.

Under "Basics"

(a) What is WIP?

(b) In "see what changed", I use plain "hg diff" with no options far
more than I give it either a file or (even less frequent) a revision
option.

(c) "messed up commit" -> "messed-up commit"

(d) "(and start over") is a bit frightening.  The reader might think
they have to start the whole repo over.

(e) [in the 'revision number' explanation at the bottom of the
column]: "and that your last commited" -> "and your last committed"

Under "Team work": I prefer it as one word, "Teamwork".  In "Prepare a
patch", "and the others" -> "others can", otherwise the reader thinks
there's a particular set of others you have in mind.  Can simplify
even more: "and others can review and apply the patch".  Better to
review first, then apply!


Under "Misc", 

(a) "previous/newer" -> "another"

(b) can get rid of "Explicitly" for tagging a revision.  Otherwise the
reader thinks "How do I implicitly tag a revision?"

Random stuff:

Is there space to give an example of "hg archive"?  e.g. "Prepare
release" as the heading.  But maybe more useful is an example of
importing a .tgz file and then doing 'hg add' (in the section in
creating a repository)?

Not sure if it's a pixel rounding problem, but the "h" in http://
doesn't left align with the "M" in Mercurial above it.

-Sanjoy

`Never underestimate the evil of which men of power are capable.'
         --Bertrand Russell, _War Crimes in Vietnam_, chapter 1.