some more fixups

.gitignore

@@ -1,2 +1 @@
 site/
-gen-docs/

bin/build

@@ -7,10 +7,12 @@ die() { echo "$@"; exit 1; }
 
 [ -f mkdocs.yml ] || die "are you sure you're in the right directory?"
 
+[ -d .git/gen-docs ] && mv .git/gen-docs .
 [ "$1" = "clean" ] && rm -rf gen-docs
 mkdir -p gen-docs/{code,contrib,css}
 rsync -a docs/code gen-docs
 rsync -a docs/css  gen-docs
+cp docs/gitweb.conf.html gen-docs
 
 cd docs
 
@@ -27,7 +29,7 @@ done
 
 # generate mkd with vim-syntax; this step is slow, but this is the simplest
 # way to support gitolite syntax highlighting in arbitrary markdown.
-for f in `find . -name "*.mkd"`
+for f in `find . -name "*.mkd" | sort`
 do
     [ -f ../gen-docs/$f ] && [ ../gen-docs/$f -nt $f ] && continue
     echo -n >&2 $f...
@@ -38,3 +40,10 @@ done
 # build site
 cd ..
 ~/.local/bin/mkdocs build
+
+# move them out of my way for normal use (some of my scripts are not
+# gitignore-aware)
+mv gen-docs .git
+
+echo next, run:
+echo 'rm -rf ../sitaramc.github.com/gitolite; mv site ../sitaramc.github.com/gitolite; cd ../sitaramc.github.com'

docs/build-docs.mkd

@@ -10,10 +10,8 @@ install and get going).
 # building the docs
 
 *   Make sure the tree is not dirty.
-*   Run `bin/build`; take a few seconds and grabs the screen; just deal!
+*   Run `bin/build`; takes a few seconds and grabs the screen, sorry!
 *   Deploy `site/`
-*   Run `git checkout -f` to clean out the in-place changes done by the
-    syntax highlighting -- you **don't** want to check them in!
 
 # what doesn't work in mkdocs
 
@@ -34,8 +32,11 @@ several levels deep.  The only way to have a document rendered without putting
 it on the nav bar is not to even list a page hierarchy, which makes them all
 come out in alphabetical order, which is useless for a project of this size.
 
-Ironically, this doc will never be rendered -- you'll only see it in the
-source repo.
+The mailing list has some workarounds, but at the moment I am not using them.
+I'd already added all the documents willy-nilly anyway.
+
+Except, ironically, *this* document; this will never be rendered -- you'll
+only see it in the source repo.
 
 ## `foo bar` split across lines
 

docs/concepts.mkd

@@ -3,9 +3,11 @@
 ----
 
 <span class="box-r">(I assume you're at least somewhat familiar with **git**
-itself.  If not, the ["before you start..."](req) page has a list of topics
+itself.  If not, the ["before you start..."][req] page has a list of topics
 that you need to be familiar with, in order to use gitolite.)</span>
 
+[req]: install#before-you-start-pre-requisites
+
 This page will help newcomers get used to what we're talking about elsewhere.
 It also explains the special `gitolite-admin` repo and how it is used to do te
 day-to-day management of a gitolite server.

docs/conf.mkd

@@ -260,8 +260,8 @@ commonly used permissions are:
     branches or tags
   * `-` (the minus sign), to **deny** access.
 
-<span class="gray">There are also other, less commonly used, [types of
-permissions][write-types].</span>
+!!! danger ""
+    There are also other, less commonly used, [types of permissions][write-types].
 
 [write-types]: conf-2/#appendix-1-different-types-of-write-operations
 

docs/contrib/putty.mkd

@@ -9,7 +9,7 @@ If you need more help with putty or component programs I suggest looking at [the
 
 **If you are not already using Putty for SSH it is recommended you do _NOT_ use it with msysgit.**
 
-**Please note that this only covers the client side of things, and does not involve server side components to troubleshooting. For that, please see the [ssh-troubleshooting document](sts).**
+**Please note that this only covers the client side of things, and does not involve server side components to troubleshooting. For that, please see the [ssh-troubleshooting document](../sts).**
 
 <a name="msysgit_setup"/>
 

docs/contrib/sskm.mkd

@@ -9,7 +9,7 @@ Follow this guide to add keys to or remove keys from your account. Note that you
 
 The key management is done using a command called `sskm`.  This command must be enabled for remote use by the admin (see [here][commands] for more on this).
 
-[commands]: non-core#gitolite-commands
+[commands]: ../non-core#gitolite-commands
 
 ----
 
@@ -242,5 +242,5 @@ command:
     by undoing the delete, will cause the key to effectively move to the root
     of the key store (i.e., the `keydir` directory in the gitolite-admin repo).
 
-[multi-key]: basic-admin#multiple-keys-per-user
+[multi-key]: ../basic-admin#multiple-keys-per-user
 

docs/contrib/ukm.mkd

@@ -13,11 +13,11 @@ must be enabled for remote use by both the [sysadmin](#SYSADMIN) and the
 [gitolite-admin](#GA) (see [here][commands] for more on this) or look
 below.
 
-[commands]: non-core#gitolite-commands
-[auth]: concepts/#authentication-and-authorisation
-[users]: basic-admin/#addremove-users
-[multi-key]: basic-admin#multiple-keys-per-user
-[perms]: user/#setget-additional-permissions-for-repos-you-created
+[commands]: ../non-core#gitolite-commands
+[auth]: ../concepts/#authentication-and-authorisation
+[users]: ../basic-admin/#addremove-users
+[multi-key]: ../basic-admin#multiple-keys-per-user
+[perms]: ../user/#setget-additional-permissions-for-repos-you-created
 
 
 ----
@@ -79,7 +79,7 @@ access.)
 ## Users that want more control over who can access their repositories
 
 Suppose the [gitolite administrator](#GA) of a research institute has
-set up gitolite to provide [wild repositories](wild) for example with
+set up gitolite to provide [wild repositories](../wild) for example with
 a `gitolite.conf` like this.
 
     repo gitolite-admin
@@ -144,7 +144,7 @@ the `ENABLE` array, i.e.,
 
     ENABLE => [ ..., 'ukm', ... ],
 
-in [.gitolite.rc](rc). (That's the preferred way for gitolite starting
+in [.gitolite.rc](../rc). (That's the preferred way for gitolite starting
 with version v3.4.)
 
 Instead of the above (in particular in gitolite v3.0-v3.3), add
@@ -159,7 +159,7 @@ them requires different values in the respective config files.
 
 There are two files where `ukm` must be configured.
 
-  * [.gitolite.rc](rc) (managed by a [sysadmin](#SYSADMIN) of the gitserver)
+  * [.gitolite.rc](../rc) (managed by a [sysadmin](#SYSADMIN) of the gitserver)
   * `gitolite-admin/conf/gitolite.conf` (managed by a
     [gitolite administrator](#GA))
 
@@ -188,7 +188,7 @@ managers to start a hierarchy of new users with the same rights as the
 initial users.
 
 The [system administrator](#SYSADMIN) must configure `ukm` for
-[guest key managers](#GKM) in [.gitolite.rc](rc) by adding something
+[guest key managers](#GKM) in [.gitolite.rc](../rc) by adding something
 like
 
     UKM_CONFIG => { FORBIDDEN_GUEST_PATTERN => qr(FORBIDDEN-PATTERN), },
@@ -277,7 +277,7 @@ multiple keys. It's a security issue. (Suppose Alice has added a guest
 MrBad all the permissions that `foo@example.org` has.)
 
 The [system administrator](#SYSADMIN) must enable `ukm` for
-[self key managers](#EKM) in [.gitolite.rc](rc) by adding
+[self key managers](#EKM) in [.gitolite.rc](../rc) by adding
 
     UKM_CONGFIG => { SELFKEY_MANAGEMENT => 1, },
 
@@ -456,7 +456,7 @@ probably fail. Then simply redo the command after a while.
 # Glossary
 
 * **sysadmin**<a id="SYSADMIN"></a>:
-  A person who is able to edit the [.gitolite.rc](rc) file on
+  A person who is able to edit the [.gitolite.rc](../rc) file on
   the server machine.
 
 * **gitolite administrator**<a id="GA"></a>:
@@ -522,7 +522,7 @@ did.
 # Ideas
 
 The command `ukm` has been created with also having the
-`keysubdirs-as-groups` [syntactic sugar](non-core) in mind. If a
+`keysubdirs-as-groups` [syntactic sugar](../non-core) in mind. If a
 [super key manager](#SKM) manages the respective keys in
 sub-directories with names `guest-key-managers/` and
 `self-key-managers/`, respectively, he/she can use the `ukm` command

docs/gitweb-daemon.mkd

@@ -2,7 +2,7 @@
 
 ----
 
-!!! danger "Note:"
+!!! danger ""
 
     Gitolite does **not** install or configure gitweb/git-daemon -- that is a
     one-time setup you must do separately.

docs/index.mkd

@@ -25,16 +25,16 @@ refused politely.  Well, if you insist... buy the book :-) </span>
 
 In general, the sections (see links in the navigation bar at the top) should
 be fairly self-explanatory, and reading through the documentation as it flows
-(i.e., using the "Next" link at the top of each page) should work fine.  There
-are some forward references here and there, but you can ignore those links on
-a first pass.
+(i.e., using the "Next" link at the top right of each page) should work fine.
+There are some forward references here and there, but you can ignore those
+links on a first pass.
 
-**In addition**,
+!!! danger "In addition:"
 
-*   there's a **[[fool proof setup]]** guide with detailed help showing one
+    There's a **[[fool proof setup]]** guide with detailed help showing one
     fool-proof way to install, as long as you follow instructions faithfully!
 
-*   once you've installed and setup, there's the **[[cookbook]]** with recipes
+    Once you've installed and setup, there's the **[[cookbook]]** with recipes
     for common tasks.
 
 # TROUBLESHOOTING

docs/install.mkd

@@ -1,16 +1,18 @@
-# before you start... (pre-requisites)
+# install and setup
 
 ----
 
-!!! danger "Notes:"
+!!! danger ""
     This page is about an ssh mode installation.  It should work for most
     people, but if you are an absolute newbie to Unix etc., you may want to
-    look into a very detailed, step-by-step, [fool-proof](fool_proof_setup)
-    set of instructions.
+    click [here](fool_proof_setup) for a very detailed, step-by-step,
+    hopefully fool-proof set of instructions.
 
     If ssh is not your thing, there's a different page for [http mode](http)
     installation.
 
+# before you start... (pre-requisites)
+
 ## your skills
 
 *   Please DO read the [concepts and terminology](concepts) page before doing

docs/quick_install.mkd

@@ -2,10 +2,10 @@
 
 ----
 
-!!! note "Note:"
-    If your Unix-fu and ssh-fu are good, this will work for you.  If it
-    doesn't, click the "next" button up there on the right for a more
-    leisurely, detailed, drive through the install process.
+!!! danger ""
+    If your Unix-fu and ssh-fu are good, this will work for you.  Otherwise,
+    please click the "next" button up there on the right for a more leisurely,
+    detailed, drive through the install process.
 
 ## distro package install
 

docs/testing.mkd

@@ -9,7 +9,7 @@ userid**.</font>
 Running gitolite's test suite is really just a superset of [trying it out
 safely][trying].
 
-[trying]: req.mkd#trying-out-gitolite-safely
+[trying]: install#trying-out-gitolite-safely
 
 To run the full test suite, create a **throw-away userid**, log in to it, then
 run these commands:
@@ -47,7 +47,7 @@ otherwise take.
 If you think that defeats the purpose of the testing, you haven't read
 [this][auth] yet.
 
-# appendix 1 -- the clobber list {#clobber}
+# appendix 1 -- the clobber list
 
 When you [try out gitolite][trying] or run the test suite, the following files
 and directories in your \$HOME are potentially clobbered.
@@ -59,3 +59,5 @@ and directories in your \$HOME are potentially clobbered.
     repositories/
     .ssh/
 
+[auth]: concepts/#authentication-and-authorisation
+[clobber]: testing#appendix-1-the-clobber-list

docs/vref-2.mkd

@@ -145,3 +145,5 @@ deal with the issue that when you push a new tag or branch, the "old" part
 is all 0's, and unless you consider `--all` existing branches and tags it
 becomes meaningless in terms of "number of new files" etc.
 
+[write-types]: conf-2/#appendix-1-different-types-of-write-operations
+