(doc updates, mostly migration)

- migration and non-core reachable from master-toc now
  - migration flow changed.  install.mkd, migration section, is [migr]
    now, drives the whole thing now, links to g2migr
  - more details on how to wipe out old gitolite

plus some minor fixes

doc/g3-master-toc.mm

@@ -30,7 +30,7 @@
 <node CREATED="1333328156575" ID="ID_208746322" MODIFIED="1333465333727" TEXT="the actual install"/>
 <node CREATED="1333467553366" ID="ID_926614739" MODIFIED="1333467556140" TEXT="upgrading"/>
 <node CREATED="1333328592876" ID="ID_237795046" MODIFIED="1333466108368" TEXT="packaging gitolite"/>
-<node CREATED="1333327776230" ID="ID_1431739921" MODIFIED="1333467569937" TEXT="migrating"/>
+<node CREATED="1333327776230" ID="ID_1431739921" MODIFIED="1334308813624" TEXT="[migr][]ating"/>
 </node>
 <node CREATED="1333301194129" ID="ID_746196740" MODIFIED="1333471816303" POSITION="right" TEXT="[setup][]"/>
 <node CREATED="1333299674481" ID="ID_714407264" MODIFIED="1333528325006" POSITION="right" TEXT="gitolite [admin][]istration">
@@ -129,6 +129,15 @@
 </node>
 </node>
 </node>
+<node CREATED="1334308529127" ID="ID_1328767320" MODIFIED="1334308538750" POSITION="right" TEXT="[non-core][] programs shipped with gitolite">
+<node CREATED="1334308547171" ID="ID_1481929835" MODIFIED="1334308550136" TEXT="commands"/>
+<node CREATED="1334308552822" ID="ID_1632638638" MODIFIED="1334308556005" TEXT="syntactic sugar"/>
+<node CREATED="1334308559968" ID="ID_759401290" MODIFIED="1334308561948" TEXT="triggers"/>
+<node CREATED="1334308570911" ID="ID_118147118" MODIFIED="1334308585866" TEXT="([link][vref]: VREFs)"/>
+<node CREATED="1334308589293" ID="ID_843158319" MODIFIED="1334308591424" TEXT="special cases">
+<node CREATED="1334308633132" ID="ID_1213286105" MODIFIED="1334308757373" TEXT="[partial-copy][]: selective read control for branches"/>
+</node>
+</node>
 <node CREATED="1333300577608" ID="ID_583410113" MODIFIED="1333537235253" POSITION="right" TEXT="background info">
 <node CREATED="1333299088617" ID="ID_1919571562" MODIFIED="1333537208005" TEXT="[files and directories][files] involved in install+setup"/>
 <node CREATED="1333300378018" ID="ID_584192327" MODIFIED="1333536676126" TEXT="[auth][]entication versus authorisation">

doc/install.mkd

@@ -2,7 +2,7 @@
 
 <font color="red">**NOTE**: if you're migrating from g2, there are some
 settings that MUST be dealt with **before** running `gitolite setup`; please
-read the [g2 migration][g2migr] page and linked pages.</font>
+start [here][migr].  RTFM is *mandatory* for migrations.</font>
 
 ## notes and naming conventions
 
@@ -132,24 +132,64 @@ Creating a symlink doesn't need a separate program but 'install' also runs
   * The `Gitolite` directory can also be there, or it can be anywhere in
     perl's `@INC` path.
 
-## migrating
+## #migr migrating
 
-There are a lot of migration hints and notes; see links at the top of this
+<font color="gray">If you're migrating from gitosis, [this][gsmigr] is what
-document.
+you want to start with.</font>
 
-But here's the **bottom line** on migrating: nothing in any of the gitolite
+First things first: g2 will be supported for a good long time for critical
-install/setup/etc will ever touch the *data* in any repository except the
+bugs, although enhancements and new features won't happen.
-gitolite-admin repo.  The only thing it will normally touch is the `update`
-hook.
 
-So one fool-proof way of "migrating" from any older gitolite is this:
+If you're an existing (gitolite v1.x or v2.x) user, and wish to migrate , here
+are the steps:
 
-1.  Wipe out the old gitolite, but **carefully**
+### pre-migration
 
-      * clone `~/repositories/gitolite-admin.git` to someplace, then delete it
+1.  Check the [dev-status][] page to make sure all the features you want have
-        (and only it, none of the other repos!) from `~/repositories`
+    been implemented in g3.
-      * rename `~/.gitolite.rc` to something else
+
-      * move the ~/.gitolite/logs` directory somewhere else, then delete `~/.gitolite`
+2.  Read the [g2 migration][g2migr] page to see what changes affect you and
+    your users, and how much time it might take you to migrate.  (The closer
+    you were to a default install of the old gitolite, the less time a
+    migration will take.)
+
+### migration
+
+**Note**: nothing in any of the gitolite install/setup/etc will ever touch the
+*data* in any repository except the gitolite-admin repo.  The only thing it
+will normally touch in normal repos is the `update` hook.
+
+1.  Carefully wipe out the old gitolite
+
+      * the **code**
+
+          * delete or move away all the old gitolite scripts.  Check the path
+            to the gl-auth-command in `~/.ssh/authorized_keys` if you forgot
+            where you put them.
+
+          * delete or move away the two directories named in the two variables
+            `GL_PACKAGE_CONF` and `GL_PACKAGE_HOOKS` in `~/.gitolite.rc`
+
+      * the **rc file**
+
+          * rename `~/.gitolite.rc` to something else
+
+      * the **admin repo**
+
+          * clone `~/repositories/gitolite-admin.git` to someplace safe
+          * then delete `~/repositories/gitolite-admin.git`
+
+        (make sure you do not delete any other repos!)
+
+      * the **admin directory**
+
+          * if you need to preserve logs, move the ~/.gitolite/logs` directory
+            somewhere else
+
+          * if you added any custom hooks and wish to preserve them, move the
+            ~/.gitolite/hooks` directory somewhere else
+
+          * delete `~/.gitolite`
 
 2.  Read about [presetting][rc-preset] the rc file; if you're using any
     variables listed as requiring preset, follow those instructions to create

doc/migr.mkd

@@ -1,6 +0,0 @@
-# migrating to gitolite
-
-If you're an existing (gitolite v1.x or v2.x) user, start with the [g2
-migration][g2migr] page.
-
-If you're migrating from gitosis, [this][gsmigr] is what you want.

doc/non-core.mkd

@@ -1,5 +1,11 @@
 # non-core programs shipped with gitolite
 
+----
+
+[[TOC]]
+
+----
+
 ## commands
 
 A list of these commands can be obtained by running `gitolite help` on the
@@ -82,7 +88,7 @@ VREFs have their [own page][vref].
 
 ## special cases
 
-### #partial-copy partial-copy
+### #partial-copy partial-copy: selective read control for branches
 
 Git (and therefore gitolite) cannot do selective read control -- allowing
 someone to read branch A but not branch B.  It's the entire repo or nothing.
@@ -92,7 +98,10 @@ because they have their own git stack (and their own sshd, and so on) all in
 one big Java program.  Gerrit is *really* useful if you want code review to be
 part of the access control decision] </font>
 
-Gitolite can now help you do this, as follows:
+Gitolite can now help you do this.  Note that this is only for branches; you
+can't do this for files and directories.
+
+Here's how:
 
 1.  enable 'partial-copy' in the `PRE_GIT` section in the rc file.