added two "documentation map" pictures!

sitaramc · Dec 23, 2012 · 3641d1b · 3641d1b
1 parent 80f7742
commit 3641d1b
Show file tree

Hide file tree

Showing 12 changed files with 217 additions and 36 deletions.
diff --git a/advanced.gv b/advanced.gv
@@ -0,0 +1,34 @@
+digraph G {
+
+    node [ shape = box ]
+    edge [ color = gray ]
+
+    gitolite [ label = "gitolite\nadvanced admnistration" style = filled fillcolor = lightblue ]
+    node [ fontcolor = darkgreen color = darkgreen ]
+    "server-side" -> "the RC file"
+    gitolite -> "server-side" -> "your own hooks"
+
+    node [ fontcolor = blue color = blue ]
+    gitolite -> "client-side"
+    "client-side" -> "conf file" -> "basic features"
+    "basic features" -> "access rules"
+    "basic features" -> options
+    "basic features" -> "git-config"
+    of1 [ label = "other features" ]
+    "conf file" -> of1
+    of1 -> "personal branches"
+    of1 -> delegation
+    of1 -> "'wild' repos\n(ad hoc, user-created, repos)"
+
+    node [ fontcolor = red color = red ]
+    of2 [ label = "other features" ]
+    gitolite -> of2
+    of2 -> "gitweb and\ngit-daemon"
+    of2 -> "mirroring"
+    cust [ label = "customising\ngitolite" ]
+    of2 -> cust
+    cust -> "types of non-core\nprograms"
+    ncs [ style=filled fillcolor=cyan label = "non-core programs\nshipped with gitolite" ]
+    cust -> ncs
+    cust -> "writing your own"
+}
diff --git a/basic.gv b/basic.gv
@@ -0,0 +1,43 @@
+digraph G {
+
+    node [ shape = box ]
+    edge [ color = gray ]
+
+    emergency [ style = filled fillcolor = red label = "stuck?\nDON'T panic!" ]
+    node [ fontcolor = blue color = blue ]
+    introduction [ fontcolor = blue color = blue label = "introduction\nwhat, why, ..." ]
+    user [ label = "what your USERS\nneed to know"]
+    emergency -> introduction [ style = invis ]
+    introduction -> "doc index" [ style = invis ]
+    "doc index" -> user [ style = invis ]
+    emergency
+
+    node [ fontcolor = red color = red ]
+    minreq [ label = "minimum requirements" ]
+    try [ label = "trying it out\nsafely" ]
+    node [ fontcolor = darkgreen color = darkgreen ]
+    run [ label = "using gitolite" ]
+    quick [ label = "quick\ninstall/setup/clone" ]
+    detailed [ label = "(detailed)" ]
+    admin [ label = "basic administration" ]
+    v2 [ fontcolor = gray color = gray label = "migrating from v2" ]
+
+    gitolite [ label = "gitolite basics" style = filled fillcolor = lightblue ]
+    gitolite [ label = "gitolite\nbasic install and use" style = filled fillcolor = lightblue ]
+    gitolite -> minreq
+    gitolite -> try
+    gitolite -> v2
+    gitolite -> run
+
+    run -> quick
+    quick -> detailed [ label = "failed?" ]
+    detailed -> install
+    detailed -> setup
+    detailed -> clone
+
+    run -> admin
+
+    admin -> "add users"
+    admin -> "add repos"
+    admin -> "access control rules"
+}
diff --git a/cust.mkd b/cust.mkd
@@ -22,7 +22,7 @@ TOC
 
 ----
 
-## introduction
+## #ncintro introduction
 
 There are 5 basic types of non-core programs.
 

diff --git a/emergencies.mkd b/emergencies.mkd
@@ -6,6 +6,15 @@
 
 ----
 
+## install/setup issues
+
+Most install/setup issues are caused by lack of ssh knowledge.  Ssh is a
+complex beast, and -- unless you are using the [http][] mode -- can cause
+problems for people who are not familiar with its quirks.
+
+**Be prepared to spend some time reading the [ssh][] documentation that comes
+with gitolite**.
+
 ## #lost-key lost admin key/access
 
 If you lost your gitolite **admin** key or access, here's what you do.  We'll

diff --git a/html/advanced.html b/html/advanced.html
@@ -0,0 +1,38 @@
+<html>
+<head>
+<title>gitolite -- advanced documentation map</title>
+</head>
+<body>
+
+<p>
+
+<strong>This map does NOT cover ALL the documentation available.  The <a
+href="master-toc.html">master table of contents</a> is where you should expect
+to find everything.</strong>
+
+</p>
+
+<hr />
+
+<img src="images/advanced.png" usemap="#advanced">
+<map name="advanced">
+  <area shape="rect" href="wild.html" coords="652,397,880,447" />
+  <area shape="rect" href="dev-notes.html" coords="969,299,1115,347" />
+  <area shape="rect" href="non-core.html" coords="772,299,943,346" />
+  <area shape="rect" href="cust.html#tncp" coords="601,298,747,348" />
+  <area shape="rect" href="cust.html" coords="804,200,912,249" />
+  <area shape="rect" href="mirroring.html" coords="688,201,778,248" />
+  <area shape="rect" href="external.html" coords="557,199,662,250" />
+  <area shape="rect" href="special.html" coords="619,103,739,149" />
+  <area shape="rect" href="deleg.html" coords="530,398,625,445" />
+  <area shape="rect" href="special.html#pers" coords="353,398,504,446" />
+  <area shape="rect" href="git-config.html" coords="236,398,328,446" />
+  <area shape="rect" href="options.html" coords="137,398,210,446" />
+  <area shape="rect" href="rules.html" coords="4,397,111,445" />
+  <area shape="rect" href="admin.html#conf" coords="452,200,533,248" />
+  <area shape="rect" href="admin.html#adminrepo" coords="444,104,540,151" />
+  <area shape="rect" href="cust.html#hooks" coords="289,200,427,248" />
+  <area shape="rect" href="rc.html" coords="162,200,263,248" />
+  <area shape="rect" href="admin.html#server" coords="307,102,408,149" />
+</map></body>
+</html>
diff --git a/html/basic.html b/html/basic.html
@@ -0,0 +1,35 @@
+<html>
+<head>
+<title>gitolite -- basic documentation map</title>
+</head>
+<body>
+
+<p>
+
+<strong>This map does NOT cover ALL the documentation available.  The <a
+href="master-toc.html">master table of contents</a> is where you should expect
+to find everything.</strong>
+
+</p>
+
+<hr />
+
+<img src="images/basic.png" usemap="#basic">
+<map name="basic">
+  <area shape="rect" href="admin.html#adminrepo" coords="790,330,951,375" />
+  <area shape="rect" href="repos.html" coords="675,330,764,375" />
+  <area shape="rect" href="users.html" coords="559,328,648,376" />
+  <area shape="rect" href="clone.html" coords="550,429,620,476" />
+  <area shape="rect" href="setup.html" coords="453,430,523,475" />
+  <area shape="rect" href="install.html" coords="356,429,428,476" />
+  <area shape="rect" href="qi.html" coords="425,207,576,258" />
+  <area shape="rect" href="install.html#migr" coords="661,106,818,154" />
+  <area shape="rect" href="testing.html#trying" coords="388,106,495,156" />
+  <area shape="rect" href="install.html#req" coords="168,108,363,156" />
+  <area shape="rect" href="user.html" coords="6,329,158,378" />
+  <area shape="rect" href="master-toc.html" coords="35,209,126,255" />
+  <area shape="rect" href="index.html" coords="22,107,143,156" />
+  <area shape="rect" href="index.html" coords="400,6,568,54" />
+  <area shape="rect" href="emergencies.html" coords="19,5,145,56" />
+</map></body>
+</html>
diff --git a/images/advanced.png b/images/advanced.png
diff --git a/images/basic.png b/images/basic.png
diff --git a/index.mkd b/index.mkd
@@ -6,6 +6,12 @@ fine-grained access control and many more powerful features.
 Here's more on [what][] it is, [how][] it works, [why][] you might need it,
 and [who][] else is using it.
 
+**If you think there's too much documentation, try this different way of
+accessing the [basic][] stuff and the [advanced][] stuff.**
+
+[basic]: basic.html
+[advanced]: advanced.html
+
 <font color="gray">
 
 ## #g2 (for older gitolite (v1.x and v2.x) users)

diff --git a/install.mkd b/install.mkd
@@ -42,8 +42,9 @@ Notes:
 ### your skills
 
   * If you're installing gitolite, you're a "system admin", like it or not.
-    Ssh is therefore a necessary skill.  Please take the time to learn at
-    least enough to get passwordless access working.
+    Since most people use the ssh mode, **[ssh][]** is therefore a necessary
+    skill.  Please take the time to learn at least enough to get passwordless
+    access working.
 
   * You also need to be somewhat familiar with git itself.  You cannot
     administer a whole bunch of git repositories if you don't know the basics
@@ -56,8 +57,9 @@ Notes:
 
 ### server
 
-  * Any Unix system with a posix compatible "sh".
-  * Git version 1.6.6 or later.
+  * Any Unix system with a posix compatible "sh" and a **sane** file system.
+  * Git version 1.6.6 or later.  (Git 1.7.8 or later if you want to run the
+    test suite).
   * Perl 5.8.8 or later.
   * Openssh (almost any version).  Optional if you're using [smart
     http][http].

diff --git a/master-toc.mkd b/master-toc.mkd
@@ -127,7 +127,7 @@ since there are so many of them**.
 ## customising gitolite
 
   * [customisation][cust] overview
-      * introduction
+      * [introduction][ncintro]
       * [where][ncloc] do you put custom code?
           * ([link][pushcode]: updating code via the admin repo)
       * [types][nctypes] of non-core programs

diff --git a/testing.mkd b/testing.mkd
@@ -1,17 +1,52 @@
-# testing gitolite
+# trying out gitolite safely
 
-The test suite should run fine on most recent Linuxes and Unixes.  Although
-gitolite itself should work fine with any git after 1.6.6 or so, the test
-suite requires git 1.7.8 or later.
-
-Here's how to *run* the tests.
+## #trying trying out gitolite
 
-<font color="red">**WARNING: they will clobber lots of things in your `$HOME`,
+<font color="red">**WARNING: this will clobber lots of things in your `$HOME`,
 so be sure to use a throwaway userid**.</font>
 
+It's easy to take gitolite for a trial run, in ssh mode, and play with all of
+its features (except mirroring).
+
+Create a **throw-away userid**, log in to it, then run these commands:
+
     git clone git://github.com/sitaramc/gitolite
     cd gitolite
-    prove
+    prove t/ssh*
+
+You will get an error that forces you to read `t/README` and set an env var
+before the test can proceed.  This is intentional; I've had people who don't
+pay attention to the "data loss" warning, and then complain that it was not
+prominent enough.  Forcing them to read a much smaller document appears to
+focus their attention better!
+
+If it doesn't work, read the testing section below to see if your system
+satisfies the conditions required for doing this.
+
+If it works, you get a gitolite installation with 7 gitolite users ("admin",
+and "u1" through "u6").
+
+Don't forget that the client and the server are all on the same user on the
+same machine; we're *simulating* 7 gitolite users using ssh keys!  (How?
+Maybe `~/.ssh/config` will give you a hint).
+
+URLs look like `user:repo`, so for example you can clone the admin repo by
+`git clone admin:gitolite-admin`.  Remote commands look like `ssh u1 info`.
+
+So start by cloning the admin repo, and try out whatever you want!
+
+## testing gitolite
+
+<font color="red">**WARNING: this will clobber lots of things in your `$HOME`,
+so be sure to use a throwaway userid**.</font>
+
+Trying out gitolite safely is really a subset of running the test suite.  If
+you want to run the full test suite, just do as above, except instead of
+running `prove t/ssh*` you just run `prove`.
+
+The test suite should run fine on most recent Linuxes and Unixes.  Although
+gitolite itself should work fine with any git after 1.6.6 or so, the test
+suite requires git 1.7.8 or later.
 
 Make sure:
 
@@ -20,7 +55,7 @@ Make sure:
 
 Gitolite's test suite is mostly written using [tsh][] -- the "testing shell".
 Take a look at some of the scripts and you will see what it looks like.  It
-has a few quirks and nuances; if you really care, email me.
+has a few quirks and nuances, but it's fine for what I need here.
 
 [tsh]: http://github.com/sitaramc/tsh
 
@@ -31,24 +66,3 @@ would otherwise take.
 
 If you think that defeats the purpose of the testing, you haven't read
 [this][auth] yet.
-
-## #trying trying out gitolite
-
-It's easy to take gitolite for a trial run, in ssh mode, and play with all of
-its features (except mirroring).
-
-Create a **throw-away userid**, log in to it, then do what the "testing
-gitolite" section above says, except instead of running `prove`, you run
-`prove t/ssh*`.
-
-When this is done, you get a gitolite installation with 7 gitolite users
-("admin", and "u1" through "u6").
-
-Don't forget that the client and the server are all on the same user on the
-same machine; we're *simulating* 7 gitolite users using ssh keys!  (How?
-Maybe `~/.ssh/config` will give you a hint).
-
-URLs look like `user:repo`, so for example you can clone the admin repo by
-`git clone admin:gitolite-admin`.  Remote commands look like `ssh u1 info`.
-
-So start by cloning the admin repo, and try out whatever you want!