README_REPOSITORY

 --------
 
 Mercurial http://www.selenic.com/mercurial belongs to a new generation
 of source code management systems, following the paradigm of
 "distributed version control".  Compared to the old centralized model
-of CVS/SVN, this gives considerable more power and freedom in
+of CVS or SVN, this gives considerable more power and freedom in
 organizing the flow of changes, both between individual developers and
 designated pull/push areas that are shared with others.
 
 More power for the user also means more responsibility!  Due to its
 decentralized nature, changesets that have been published once,
-e.g. via push to a shared repository that is visible on the net,
+e.g. via "push" to a shared repository that is visible on the net,
 cannot be easily retracted from the public again.  Regular Mercurial
 operations are strictly monotonic, where changset transactions are
-only added, but never deleted.  There are special tools to "repair"
+only added, but never deleted.  There are special tools to manipulate
 individual repositories via non-monotonic actions, but this does not
-yet retrieve unwanted changesets that have escaped into the public.
+yet retrieve any changesets that have escaped into the public by
+accident.
 
-Only global operations like pull/push, unbundle/bundle etc. fall into
-this critical category; incoming/outgoing or in/out may help to
-inspect changesets before exchanging them globally.  Anything else in
-Mercurial is local to the user's repository clone (including
-commit/update/merge etc.) and is in fact much simpler and safer to use
-than the corresponding operations of CVS or SVN.
+Only global operations like "pull" / "push", "unbundle" / "bundle"
+etc. fall into this critical category.  Note that "incoming" /
+"outgoing" allow to inspect changesets before exchanging them
+globally.  Anything else in Mercurial is local to the user's
+repository clone (including "commit", "update", "merge" etc.) and is
+in fact much simpler and safer to use than the corresponding
+operations of CVS or SVN.
 
 
 Initial configuration
 =====================
 
-Never use any Mercurial version before 1.0!  At the moment, versions
-1.0, 1.0.1 and 1.0.2 all work equally well.
+Always use Mercurial version 1.0 or later, such as 1.0.1 or 1.0.2.
+The old 0.9.x versions do not work in a multi-user environment with
+shared file spaces.
 
 
-The public pull area of the Isabelle repository can be cloned like
-this:
+The official Isabelle repository can be cloned like this:
 
   hg clone http://isabelle.in.tum.de/repos/isabelle
 
 This will create a local directory "isabelle", unless an alternative
 name is specified.  The full repository meta-data and history of
 changes is in isabelle/.hg; local configuration for this clone can be
 added to isabelle/.hg/hgrc, but note that hgrc files are never copied
 by another clone operation!
 
-There is also ~/.hgrc for per-user Mercurial configuration.  The
+There is also $HOME/.hgrc for per-user Mercurial configuration.  The
 initial configuration should include at least an entry to identify
 yourself.  For example, something like this in /home/wenzelm/.hgrc:
 
   [ui]
   username = wenzelm
 
 Failing to configure the username correctly makes the system invent
-funny machine names that may persist eternally in the flow of
-changesets.
+funny machine names that may persist indefinitely in the public flow
+of changesets.
 
 In principle, user names can be chosen freely, but for longterm
 committers of the Isabelle repository the obvious choice is to keep
 with the old CVS naming scheme.
 
 
-There are other useful configuration to go into ~/.hgrc, e.g. defaults
-for common commands:
+There are other useful configuration to go into $HOME/.hgrc,
+e.g. defaults for common commands:
 
   [defaults]
   log = -l 10
 
 The next example shows how to install some Mercurial extension:

 =======================
 
 The entry point http://isabelle.in.tum.de/repos/isabelle is world
 readable, both via plain web browsing and the hg client as described
 above.  Anybody can produce a clone, change it arbitrarily, and then
-use regular mechanisms of Mercurial to report changes "upstream", say
+use regular mechanisms of Mercurial to report changes upstream, say
 via e-mail to someone with write access to that file space.  It is
-also quite easy to publish changed clones again on the web, using hg
-serve, or the hgweb.cgi or hgwebdir.cgi scripts that are included in
-the Mercurial distribution.
+also quite easy to publish changed clones again on the web, using the
+adhoc command "hg serve -v", or the hgweb.cgi or hgwebdir.cgi scripts
+that are included in the Mercurial distribution.
 
-This downstream/upstream mode of operation is quite common in the
+The downstream/upstream mode of operation is quite common in the
 distributed version control community, and works well for occasional
 changes produced by anybody out there.  Of course, upstream
 maintainers need to review and moderate changes being proposed, before
 pushing anything onto the official Isabelle repository at TUM.
 
 
-Direct pull/push access requires an account at TUM, with properly
-configured ssh access to the local machines (e.g. macbroy20,
-atbroy100).
+Write access to the Isabelle repository requires an account at TUM,
+with properly configured ssh access to the local machines
+(e.g. macbroy20, atbroy100).  You also need to be a member of the
+"isabelle" Unix group.
 
-The simple wrapper script /home/isabelle/mercurial/bin/hg provides a
-uniform view on the different Linux installations on the local
-network.  Thus it is advisable to add that directory to the shell PATH
-of the account at TUM:
+Sharing a locally modified clone then works as follows, using your
+user name instead of "wenzelm":
 
-  PATH="/home/isabelle/mercurial/bin:$PATH"
+  hg out ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
 
-Now a clone of the shared push/pull area can be produced like this,
-using your user name instead of "wenzelm":
+In fact, the "out" or "outgoing" command performs only a dry run: it
+displays the changesets that would get published.  An actual "push",
+with a lasting effect on the Isabelle repository, works like this:
 
-  hg clone ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
+  hg push ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
 
-In fact, the only difference to the previous clone of
-http://isabelle.in.tum.de/repos/isabelle is a different default
-pull/push path in isabelle/.hg/hgrc:
+
+Default paths for push and pull can be configure in isabelle/.hg/hgrc,
+for example:
 
   [paths]
   default = ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
 
-This means an earlier pull-only clone can be changed into a pull/push
-version by editing this single line of the internal repository
-configuration.
+Now "hg pull" or "hg push" will use that shared file space, unless a
+different URL is specified explicitly.
+
+When cloning a repository, the default path is set to the initial
+source URL.  So we could have cloned via that ssh URL in the first
+place, to get exactly to the same point:
+
+  hg clone ssh://wenzelm@atbroy100//home/isabelle-repository/repos/isabelle
 
 
 Content discipline
 ==================
 
-Old-style centralized version control is occasionally compared with a
-"library where everybody scribbles into the books".  Or seen the other
+Old-style centralized version control is occasionally compared to "a
+library where everybody scribbles into the books".  Or seen the other
 way round, the centralized model discourages individual
 experimentation (with local branches etc.), because everything is
 forced to happen on a shared file space.  With Mercurial, arbitrary
 variations on local clones are no problem, but care is required again
 when publishing changes eventually.

     Users should be aware that others will actually read what is
     written into log messages.
 
     The usual changelog presentation style for the Isabelle repository
     admits log entries that consist of several lines, but without the
-    special head line that is used in Mercurial projects elsewhere.
+    special headline that is used in Mercurial projects elsewhere.
     Since some display styles strip newlines from text, it is
     advisable to separate lines via punctuation, and not rely on
     two-dimensional presentation too much.
 
 
 Building Isabelle from the repository version
 =============================================
 
 Compared to a proper distribution or development snapshot, a
-repository version of Isabelle lacks proper version identifiers in
-various places, and some components produced by Admin/build.  After
-applying that script with suitable options, the regular user
-instructions for building and running Isabelle from sources apply.
+repository version of Isabelle lacks textual version identifiers in
+some sources and scripts, and various components produced by
+Admin/build are missing.  After applying that script with suitable
+arguments, the regular user instructions for building and running
+Isabelle from sources apply.
 
-Needless to say, the results from the build process must not be
-committed back into the repository!
+Needless to say, the results from the build process must not be added
+to the repository!
 
 
-Makarius 29-Nov-2008
+Makarius 30-Nov-2008