From 30aa93f3f41c98f129f23106e736d911cbaaf902 Mon Sep 17 00:00:00 2001
From: Daniel Friesel <derf@derf.homelinux.org>
Date: Sun, 2 May 2010 14:58:53 +0200
Subject: Update documentation

---
 bin/ct                   |  1 -
 man/5/caretaker.conf.pod | 82 ++++++++++++++++++++++++++++++++++++++----------
 man/7/caretaker.pod      |  6 ++--
 3 files changed, 69 insertions(+), 20 deletions(-)

diff --git a/bin/ct b/bin/ct
index 783a0a4..d984025 100755
--- a/bin/ct
+++ b/bin/ct
@@ -73,7 +73,6 @@ while [[ $1 == --* ]] {
 		--help) die "see '$0 help'\n" ;;
 
 		--packagedir)  PKG_DIR=$2; shift ;;
-		--packageroot) PKG_ROOT=$2; shift ;;
 		--checklinks-options) CL_OPTIONS+=$2; shift ;;
 		--) shift; break ;;
 		*) die "Unknown argument: '$1'\n" ;;
diff --git a/man/5/caretaker.conf.pod b/man/5/caretaker.conf.pod
index bf625a7..5fbbc3a 100644
--- a/man/5/caretaker.conf.pod
+++ b/man/5/caretaker.conf.pod
@@ -20,25 +20,14 @@ The text in (braces) refers to the ct commandline option with which the config
 setting may be overridden (if present).
 The text in [these braces] is the default value.
 
-=over
-
-=item B<PKG_ROOTS>=(I<url1> I<url2> I<...>)   (--packageroot I<url>)
-
-the package root paths, at least one must be set.
-I<url> may either be of the form C<protocol://host/path> or C</path>,
-the supported protocols are C<git> and C<ssh>.
-Note that pushing is not possible when the C<git> protocol is used.
-
-=item B<PKGLIST_PATH>=I<path>   [$PKG_PATH/pkglist]
+=head2 GENERAL OPTIONS
 
-path to pkglist on the package root, to generate the package list.
-In the default, $PKG_PATH means the path component of $PKG_ROOT.
+=over
 
-=item B<PKGLIST_LOCAL>=I<boolean>   [0]
+=item B<PKG_ROOTS>=(I<name1> I<name2> I<...>)
 
-If true, B<PKLIST_PATH> will always be executed on the local machine, regardless
-of where the B<PKG_ROOT> lies. For possible uses of this setting, see
-L<caretaker(7)/"THE PACKAGE LIST">
+The package roots to use, at least one must be set.
+For the package root definitions, see below.
 
 =item B<PKG_DIR>=I<path>   (--packagedir I<path>)   [$HOME/packages]
 
@@ -100,6 +89,48 @@ Example: function pkg_hook_post-update {clear_line; echo "Hello from package $1!
 
 =back
 
+=head2 ROOT-SPECIFIC OPTIONS
+
+Each package root is defined as a function, more precisely,
+C<< function pkgroot_I<name> { I<content> } >>.
+You need at least one package root, and it must be enabled by putting its
+I<name> into B<PKG_ROOTS> (see above).
+
+The I<content> consists of variables like above.
+
+=over
+
+=item B<PKG_PROTO>=I<protocol>
+
+Protocol to use. May be anything understood by git, e.g. file, git, ssh, http,
+etc. Note that by default only file and ssh are supported, for other protocols
+you will have to write your own pkglist script
+
+=item B<PKG_USER>=I<username>
+
+If B<PKG_PROTO> supports authentication, sets the login username.  If
+authentication is not required/supported, don't set this or leave it empty
+
+=item B<PKG_HOST>=I<hostname>
+
+Remote host to connect to.  Leave empty if you use the "file" protocol
+
+=item B<PKG_PATH>=I<path>
+
+Absolute path in which your repositories are stored. E.g.
+"/home/derf/var/packages_root"
+
+=item B<PKGLIST_PATH>=I<path>   [$PKG_PATH/pkglist]
+
+Path to the script generating the package list.
+
+=item B<PKGLIST_LOCAL>=I<boolean>   [0]
+
+If true, execute the package list on the local machine. Otherwise (e.g. wit
+the ssh protocol) it will be executed on the remote host.
+
+=back
+
 =head2 COLOURS
 
 Colours are defined in the same way as options. They take an ANSI escape code
@@ -117,6 +148,25 @@ Colour for warning and error messages (default: red)
 
 =back
 
+=head1 EXAMPLE
+
+    PKG_ROOTS=(aneurysm)
+
+    function pkgroot_aneurysm {
+        PKG_PROTO=ssh
+        PKG_HOST=aneurysm
+        PKG_PATH=${HOME}/var/packages_root
+    }
+
+    # This will not be used, but may be enabled by appending it to the
+    # PKG_ROOTS array. In this case we use a custom list script which does not
+    # require PKG_USER / PKG_HOST / PKG_PATH to be set.
+    function pkgroot_github {
+        PKG_PROTO=https
+        PKGLIST_LOCAL=1
+        PKGLIST_PATH=${HOME}/libexec/pkglist-github
+    }
+
 =head1 SEE ALSO
 
 L<ct>(1), L<checklinks>(1)
diff --git a/man/7/caretaker.pod b/man/7/caretaker.pod
index 6569f59..9146437 100644
--- a/man/7/caretaker.pod
+++ b/man/7/caretaker.pod
@@ -66,10 +66,10 @@ for which package.
 
 It consists of one line per package, each line containing three or four items separated
 by a single whitespace.  The first item is the package name, the second one the
-repository type (DVCS), the third the current revision; in the remote list, the fourth
-is the package root to which this package belongs.  Example:
+repository type (DVCS), the third the current revision; in the remote list,
+the fourth is the URI used to access this package.  Example:
 
-  caretaker git 82d716d01dee0329af7df5e67b55558fe3ff1466 git://git.tabularazor.org/~derf
+  caretaker git 82d716d01dee0329af7df5e67b55558fe3ff1466 git://derf.homelinux.org/caretaker
 
 The package list is generated by the script set in the config var $PKGLIST_PATH,
 by default F<examples/pkglist>.  Depending on $PKGLIST_LOCAL and $PKG_ROOT, it
-- 
cgit v1.2.3