Flesh out documentation and improve examples

3 files changed, 75 insertions, 51 deletions

diff --git a/catsit.8 b/catsit.8
index ae4de38..7448012 100644
--- a/catsit.8
+++ b/catsit.8
@@ -39,6 +39,9 @@ Set the path of the named pipe.
 .It Cm start
 Start any matching services
 which are not already started.
+Services scheduled for automatic restart
+are started immediately
+but their restart intervals are not reset.
 .
 .It Cm stop
 Stop any matching services
@@ -49,8 +52,12 @@ signal.
 .
 .It Cm restart
 Restart any matching services.
-Started services will first be stopped,
-then stopped services will be started.
+Started services will be stopped
+and started again.
+Stopped services will be started.
+Services scheduled for automatic restart
+will be started immediately
+and their restart intervals will be reset.
 .
 .It Cm status
 Log the current status of any matching services.
@@ -62,14 +69,21 @@ from the services list.
 .It Ar signal
 Send the named signal
 to the processes of any matching started services.
+Signal names are case-insensitive.
 .
 .It Ar service ...
 The list of services to operate on.
 Service names can include
-the shell-style pattern operators
-.Sy *?[] .
-Be sure to quote service name patterns
-so they are not interpreted by the shell.
+.Sy *?[]
+shell-style pattern operators.
+Patterns must be quoted
+to be interpreted by
+.Xr catsitd 8
+rather than the shell.
+Each service name pattern
+is operated on in order,
+but services matched by each pattern
+are in unspecified order.
 .El
 .
 .Sh ENVIRONMENT
@@ -89,9 +103,8 @@ The default path of the named pipe.
 .
 .Sh EXAMPLES
 .Bd -literal
-catsit start pounce/freenode
-catsit status '*'
-catsit USR1 'pounce/*'
+catsit restart pounce/freenode
+catsit INFO 'pounce/*'
 .Ed
 .
 .Sh SEE ALSO
diff --git a/catsit.conf.5 b/catsit.conf.5
index eee5ed2..c18f683 100644
--- a/catsit.conf.5
+++ b/catsit.conf.5
@@ -20,7 +20,8 @@ is one of the following:
 .It Cm # Ar comment ...
 Lines beinning with
 .Ql #
-and blank lines are ignored.
+as well as blank lines
+are ignored.
 .
 .It Cm % Ar command ...
 Lines beginning with
@@ -62,20 +63,21 @@ or which call
 .
 .Sh EXAMPLES
 .Bd -literal
-# Basic services:
-calico	calico -H irc.example.org /var/run/calico
-pounce/freenode	pounce /usr/local/etc/pounce/freenode.conf
-pounce/tilde	pounce /usr/local/etc/pounce/tilde.conf
-
 # Setting environment variables:
-% export PATH=$PATH:/usr/local/bin
+% export LANG=en_US.UTF-8
 
-# Using variables to expand service command lines:
-% pounce=/usr/local/bin/pounce
-% conf=/usr/local/etc/pounce
-pounce/freenode	$pounce $conf/freenode.conf
-pounce/tilde	$pounce $conf/tilde.conf
-.El
+# Expanding command lines with variables:
+% socks=/var/run/calico
+calico	calico -H irc.example.org $socks
+pounce	pounce -U $socks pounce.conf
+
+# Templating command lines using service names:
+pounce/freenode	pounce ${0#*/}.conf
+pounce/tilde	pounce ${0#*/}.conf
+
+# Privileged services:
+@scooper	kfcgi -d -U $USER -p ~/.local -- /bin/scooper
+.Ed
 .
 .Sh SEE ALSO
 .Xr catsitd 8
diff --git a/catsitd.8 b/catsitd.8
index e5e7290..ae89531 100644
--- a/catsitd.8
+++ b/catsitd.8
@@ -47,7 +47,7 @@ daemon spawns processes for a list of
 redirects their output to syslog,
 and restarts the processes when they exit
 according to their exit status.
-Exponential backoff is applied to restarts.
+Exponential backoff is applied to automatic restarts.
 .
 .Pp
 The list of services is defined in a
@@ -60,9 +60,9 @@ through a named pipe.
 The
 .Xr catsit 8
 utility is a wrapper
-around the named pipe,
+for writing to the named pipe,
 and its manual page
-describes the control command format.
+describes the control command syntax.
 .
 .Pp
 The arguments are as follows:
@@ -76,10 +76,12 @@ By default the working directory is
 .
 .It Fl c Ar control
 Set the path of the named pipe
-used for control.
+used for service control.
 .
 .It Fl d
 Do not run as a daemon.
+Log to standard error
+as well as syslog.
 .
 .It Fl f Ar config
 Set the path of the
@@ -92,7 +94,7 @@ Change group to
 before starting services.
 If
 .Fl u
-is used,
+is set,
 the default group is the user's group.
 .
 .It Fl p Ar pidfile
@@ -118,11 +120,12 @@ The default list contains the values of
 .Dv EX_USAGE ,
 .Dv EX_DATAERR ,
 .Dv EX_NOINPUT ,
-.Dv EX_OSFILE ,
+.Dv EX_OSFILE
+and
 .Dv EX_CANTCREAT
 defined in
 .Xr sysexits 3 .
-The exit statuses 127 and 126
+The exit statuses 126 and 127
 are always treated as stop exits.
 .
 .It Fl t Ar restart
@@ -137,36 +140,42 @@ The default interval is 1 second.
 Change user to
 .Ar user
 before starting services.
+Services which are
+.Em privileged
+are started without changing user.
+The
+.Xr catsit.conf 5
+manual page
+describes privileged services.
 .El
 .
 .Pp
-When the
+The
 .Nm
-daemon receives the
-.Dv HUP
-signal,
-the
+daemon takes the following actions
+in response to signals:
+.Bl -tag -width Ds
+.It Dv HUP
+The
 .Xr catsit.conf 5
 file is reloaded.
-Modified services
-are not automatically restarted,
-newly added services
-are not automatically started,
-and removed services
-are not automatically stopped.
-.
-.Pp
-When the
-.Nm
-daemon receives the
-.Dv TERM
-signal,
-the named pipe is closed,
-all services are stopped,
-and
+Services are not automatically
+started, stopped or restarted.
+Removed services can be dropped with
+.Xr catsit 8 .
+.
+.It Dv TERM
+The named pipe used for service control
+is closed and unlinked.
+All services are stopped,
+after which
 .Nm
 exits.
 .
+.It Dv INFO
+The current status of all services is logged.
+.El
+.
 .Sh ENVIRONMENT
 Services are started
 with empty environments
@@ -196,7 +205,7 @@ The default path of the
 file.
 .It Pa /var/run/catsitd.pipe
 The default path of the named pipe
-used for control.
+used for service control.
 .El
 .
 .Sh SEE ALSO