documentation fixups

doc/commands.mkd

@@ -1,26 +0,0 @@
-# gitolite "commands"
-
-Gitolite comes with several commands that users can run.  Remote user run the
-commands by saying:
-
-    ssh git@host command-name [args...]
-
-while on the server you can run
-
-    gitolite command [args...]
-
-Very few commands are designed to be run both ways, but it can be done, by
-checking for the presence of env var `GL_USER`.
-
-You can get a **list of available commands** by using the `help` command.
-Naturally, a remote user will see only a subset of what the server user will
-see.
-
-You add commands to the "allowed from remote" list by adding its name (or
-uncommenting it if it's already added but commented out) to the COMMANDS hash
-in the [rc][] file.
-
-If you write your own commands, put them in src/commands.
-
-**Note that this is also the place that all triggered programs go**.  In fact,
-all standalone programs related to gitolite go here.

doc/cust.mkd

@@ -1,23 +1,71 @@
 # customising gitolite
 
-Here are the ways you can customise gitolite on the server.
+Much of gitolite (g3)'s functionality comes from programs and scripts that are
+not considered "core".  This keeps the core simpler, and allows you to enhance
+gitolite for your own purposes without too much fuss.
 
-First, learn about:
+## types of non-core programs
 
-  * [git hooks][hooks] and [virtual refs][vref]
+There are 5 basic types of non-core programs.
 
-  * [commands][] for your [users][] to run own][dev-notes]
+  * *commands* can be run from the shell command line.  Those listed in the
+    COMMANDS hash of the rc file can also be run remotely.
+  * *hooks* are standard git hooks; see below.
+  * *sugar scripts* change the conf language for your convenience.  The word
+    sugar comes from "syntactics sugar".
+  * *triggers* are to gitolite what hooks are to git.  I just chose a
+    different name to avoid confusion and constant disambiguation in the docs.
+  * **VREFs** are extensions to the access control check part of gitolite.
 
-  * [triggers][] to be run by gitolite as various points in its execution
+## #commands gitolite "commands"
 
-  * [syntactic sugar][sugar] to change the conf language for your convenience
+Gitolite comes with several commands that users can run.  Remote user run the
+commands by saying:
 
-For all of the above:
+    ssh git@host command-name [args...]
 
-  * [edit the rc file][rc] to enable optional features that are shipped in a
+while on the server you can run
-    disabled state
 
-  * [write your own][dev-notes]
+    gitolite command [args...]
 
-(Note: "trigger" is the same concept as "hook", applied to gitolite; I just
+Very few commands are designed to be run both ways, but it can be done, by
-chose a different name to avoid constant ambiguity in documentation).
+checking for the presence of env var `GL_USER`.
+
+You can get a **list of available commands** by using the `help` command.
+Naturally, a remote user will see a much smaller list than the server user.
+
+You add commands to the "allowed from remote" list by adding its name (or
+uncommenting it if it's already added but commented out) to the COMMANDS hash
+in the [rc][] file.
+
+If you write your own commands, put them in src/commands.
+
+## #hooks hooks and gitolite
+
+Gitolite uses the `update` hook for all repos.  In addition, it uses the
+`post-update` hook for the gitolite-admin repo.
+
+If you want to add your own hook, it's easy as long as it's not the 'update'
+hook.  Just add it to `$HOME/.gitolite/hooks/common` and run `gitolite setup`.
+
+The rest is between you and 'man githooks' :-)
+
+## #sugar syntactic sugar
+
+Sugar scripts help you change the perceived syntax of the conf language.  The
+base syntax of the language is as described [here][conf], so sugar scripts
+take something *else* and convert it into that.
+
+That way, the admin sees additional features (like allowing continuation
+lines), while the parser in the core gitolite engine does not change.
+
+If you want to write your own sugar scripts, please read the "your own sugar"
+section in [dev-notes][] first then email me.
+
+## triggers
+
+Triggers have their own [document][triggers].
+
+## VREFs
+
+VREFs also have their own [document][vref].

doc/dev-notes.mkd

@@ -9,7 +9,7 @@ Hints for developers wishing to help migrate features over from g2 are
 Here are some random notes on developing hooks, commands, triggers, and sugar
 scripts.
 
-## environment variables
+## environment variables and other inputs
 
 In general, the following environment variables should always be available:
 
@@ -20,6 +20,9 @@ In general, the following environment variables should always be available:
 Commands invoked by a remote client will also have `GL_USER` set.  Hooks will
 have `GL_REPO` also set.
 
+Finally, note that triggers get a lot of relevant information as arguments;
+see [here][triggers] for details.
+
 ## APIs
 
 ### the shell API

doc/g2migr.mkd

@@ -73,7 +73,7 @@ put that contain the words "see docs":
         cd $HOME/repositories
         find . -type d -name "*.git" -prune | while read r
         do
-            mv \$r/gl-creater \$r/gl-creator
+            mv $r/gl-creater $r/gl-creator
         done 2>/dev/null
 
     Once you do this, the g2 will not work completely unless you change them

doc/hooks.mkd

@@ -1,9 +0,0 @@
-# hooks and gitolite
-
-Gitolite uses the `update` hook for all repos.  In addition, it uses the
-`post-update` hook for the gitolite-admin repo.
-
-If you want to add your own hook, it's easy as long as it's not the 'update'
-hook.  Just add it to `$HOME/.gitolite/hooks/common` and run `gitolite setup`.
-
-The rest is between you and 'man githooks' :-)

doc/list

@@ -14,11 +14,9 @@ minreq.mkd
 qi.mkd
 install.mkd
 add.mkd
-conf.mkd
 users.mkd
 
-rc.mkd
+conf.mkd
-cust.mkd
 
 group.mkd
 repo.mkd
@@ -26,13 +24,14 @@ rules.mkd
 refex.mkd
 write-types.mkd
 
-dev-notes.mkd
+rc.mkd
-commands.mkd
+
-hooks.mkd
+cust.mkd
 triggers.mkd
-sugar.mkd
 vref.mkd
 
+dev-notes.mkd
+
 misc.mkd
 pw.mkd
 testing.mkd

doc/sugar.mkd

@@ -1,11 +0,0 @@
-# syntactic sugar
-
-Sugar scripts help you change the perceived syntax of the conf language.  The
-base syntax of the language is as described [here][conf], so sugar scripts
-take something *else* and convert it into that.
-
-That way, the admin sees additional features (like allowing continuation
-lines), while the parser in the core gitolite engine does not change.
-
-If you want to write your own sugar scripts, please read the "your own sugar"
-section in [dev-notes][] first then email me.