6 files changed, 50 insertions, 31 deletions
diff --git a/doc/overview.html b/doc/overview.html
index fd544a7..2a90ee6 100644
--- a/doc/overview.html
+++ b/doc/overview.html
@@ -42,7 +42,7 @@ means bringing services up, or bringing services down.
 <p>
  Supervision suites manage <em>long-lived processes</em>, a.k.a
 <em>daemons</em>, and sometimes call them <em>services</em>.
-With s6-rc, those things are different: a long-lived process is
+With s6-rc, things are a little different: a long-lived process is
 also called a <em>longrun</em> and is a service, but a service
 does not have to be a longrun. There is a second kind of service,
 which is called a <em>oneshot</em>, and which represents a change
@@ -85,12 +85,13 @@ are both oneshots, both longruns, or a oneshot and a longrun.
 </p>
 
 <p>
- s6-rc also handles an additional kind of service: a <em>bundle</em>.
-A bundle is just a collection of oneshots or longruns, described
+ Oneshots and longruns are called <em>atomic services</em>.
+By opposition to atomic services, s6-rc also handles an
+additional kind of service that it calls a <em>bundle</em>.
+A bundle is just a collection of atomic services, described
 under a single name. A bundle definition can even contain other
 bundles, but ultimately a bundle will always represent a set of one
-or more oneshots or longruns. A oneshot or longrun is called an
-<em>atomic service</em>.
+or more atomic services.
 Bundle names can be used anywhere with the s6-rc user
 interface, and they will internally be converted to a set of
 atomic services. An atomic service can depend on a bundle: it will
@@ -147,8 +148,8 @@ supervision tree is up and running. s6-rc will only work
 if there is an active
 <a href="http://skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>
 process monitoring a
-<a href="http://skarnet.org/software/s6/scandir.html">scan</a>
-directory. On Linux, for instance, it is possible to achieve such a state
+<a href="http://skarnet.org/software/s6/scandir.html">scan
+directory</a>. On Linux, for instance, it is possible to achieve such a state
 by using an init created by the
 <a href="http://skarnet.org/software/s6-linux-init/s6-linux-init-maker.html">s6-linux-init-maker</a>
 tool: when control reaches stage 2, s6-svscan is guaranteed to run,
diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html
index 44327ba..6e539e4 100644
--- a/doc/s6-rc-compile.html
+++ b/doc/s6-rc-compile.html
@@ -159,14 +159,15 @@ character are ignored. The file defines the <em>direct dependencies</em> of
  It is unnecessary to manually define complete sets of dependencies in the
 <tt>dependency</tt> file, because
 <a href="s6-rc.html">s6-rc</a> will properly handle dependency chains.
-anyway. If <em>A</em> depends on <em>B</em>, no matter the underlying
+If <em>A</em> depends on <em>B</em>, no matter the underlying
 implementation of <em>B</em>, and the current implementation of <em>B</em>
 depends on <em>C</em>, then you should just put <em>B</em> in
 <tt><em>A</em>/dependencies</tt>; when starting the set,
 <a href="s6-rc.html">s6-rc</a> will start <em>C</em> first, then
 <em>B</em>, then <em>A</em>. If the underlying implementation of <em>B</em>
 changes and does not depend on <em>C</em>, then you will just have to
-modify the dependencies for <em>B</em>, not for <em>A</em>
+modify the dependencies for <em>B</em>, and the definition of <em>A</em>
+will still be correct.
 </p>
 
 <p>
@@ -182,13 +183,16 @@ complain and exit 1.
 <h4> For oneshots </h4>
 
 <ul>
- <li> Two mandatory regular files named <tt>up</tt> and <tt>down</tt>, which
+ <li> Two regular files named <tt>up</tt> and <tt>down</tt>, which
 must each contain a single Unix command line. The files will be interpreted by the
 <a href="http://skarnet.org/software/execline/execlineb.html">execlineb</a>
 lexer at compile time and the results will be stored into the
 compiled database in an internal form. <tt>up</tt> will be run when
 the service is started, and <tt>down</tt> will be executed when the service
-is stopped. </li>
+is stopped. <tt>up</tt> is mandatory, but <tt>down</tt> is optional;
+if no <tt>down</tt> file is provided in the source definition directory,
+then s6-rc will consider that the down transition for this service
+does nothing and always succeeds. </li>
 </ul>
 
 
@@ -255,7 +259,10 @@ about pipelines. </li>
  <li> A mandatory regular file named <tt>run</tt>, as well as optional files
 named <tt>finish</tt>, <tt>notification-fd</tt> and <tt>nosetsid</tt>. These
 files will be copied, or recreated, in the generated
-<a href="http://skarnet.org/software/s6/servicedir.html">service directory</a>.
+<a href="http://skarnet.org/software/s6/servicedir.html">service directory</a>:
+they are meant to be used by the
+<a href="http://skarnet.org/software/s6/s6-supervise.html">s6-supervise</a>
+process that will manage the longrun service. </li>
  <li> Optional directories named <tt>data</tt> and <tt>env</tt>. These will
 be copied verbatim into the generated service directory. </li>
  <li> An optional file named <tt>producer-for</tt>. If this file exists, then
diff --git a/doc/s6-rc-db.html b/doc/s6-rc-db.html
index a60658e..a9d8b9d 100644
--- a/doc/s6-rc-db.html
+++ b/doc/s6-rc-db.html
@@ -66,12 +66,15 @@ information to stdout, then exits 0. </li>
 compiled service database in <em>compiled</em> instead of
 the current live one. </li>
  <li> <tt>-l&nbsp;<em>live</em></tt>&nbsp;: assume the live
-state is in <em>live</em>. Default is
-<tt>/run/s6-rc</tt>. This option is ignored if the
-<tt>-c</tt> option has been given. </li>
+state is in <em>live</em>. This option is ignored if the
+<tt>-c</tt> option has been given. Default is
+<tt>/run/s6-rc</tt>. The default can be changed at package
+compilation time, by giving the <tt>--livedir=<em>live</em></tt>
+option to <tt>./configure</tt>. </li>
  <li> <tt>-u</tt>&nbsp;: for commands that use different data
 depending on whether it's about bringing the service up or down,
-select the "up" data. This option is ignored when it is irrelevant. </li>
+select the "up" data (this is the default). This option is
+ignored when it is irrelevant. </li>
  <li> <tt>-d</tt>&nbsp;: for commands that use different data
 depending on whether it's about bringing the service up or down,
 select the "down" data. This option is ignored when it is irrelevant. </li>
diff --git a/doc/s6-rc-init.html b/doc/s6-rc-init.html
index 39d11a7..3334525 100644
--- a/doc/s6-rc-init.html
+++ b/doc/s6-rc-init.html
@@ -35,7 +35,7 @@ invocation of the
  <li> <em>compiled</em>, <em>live</em> and <em>scandir</em> must be
 absolute paths. </li>
  <li> s6-rc-init expects to find a <em>compiled service database</em>
-in <em>compiled</tt>. It expects to be able to create a directory
+in <em>compiled</em>. It expects to be able to create a directory
 at <em>live</em>. It also expects that an instance of
 <a href="http://skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>
 is running on <em>scandir</em>. </li>
@@ -48,11 +48,12 @@ subdirectory of <em>live</em>, adds down files to the live copies
 and links them into <em>scandir</em>. It then triggers
 <a href="http://skarnet.org/software/s6/s6-svscan.html">s6-svscan</a>,
 which will pick up the new service directories and start
-http://skarnet.org/software/s6/s6-supervise.html">s6-supervise</a>
+<a href="http://skarnet.org/software/s6/s6-supervise.html">s6-supervise</a>
 processes on them - but the service themselves will not be started
 right away, because of the down files. </li>
  <li> s6-rc-init waits for all s6-supervise processes to be
 operational, then exits 0. </li>
+</ul>
 
 <h2> Options </h2>
 
@@ -70,7 +71,9 @@ Default is <tt>/etc/s6-rc/compiled</tt>. </li>
 the <em>live</em> directory, which should not exist prior to running
 s6-rc-init, but should be under a writable filesystem - likely a RAM
 filesystem. Default is
-<tt>/run/s6-rc</tt>. </li>
+<tt>/run/s6-rc</tt>. The default can be changed at compile time by
+giving the <tt>--livedir=<em>live</em></tt> option to
+<tt>./configure</tt>. </li>
 </ul>
 
 <h2> Typical usage </h2>
diff --git a/doc/s6-rc.html b/doc/s6-rc.html
index 75dba9a..1000159 100644
--- a/doc/s6-rc.html
+++ b/doc/s6-rc.html
@@ -50,7 +50,8 @@ change.
 
 <ul>
  <li> s6-rc expects to find a functional <em>live state</em> in
-<em>live</em> (by default <tt>/run/s6-rc</tt>). The live state is
+<em>live</em> (by default <tt>/run/s6-rc</tt>, unless changed when the package
+was compiled). The live state is
 normally created at boot time by
 <a href="s6-rc-init.html">s6-rc-init</a>. If the live state is
 invalid, s6-rc complains and exits 4. </li>
@@ -88,7 +89,8 @@ The s6-rc command operates on the selection.
 <ul>
  <li> <tt>-l&nbsp;<em>live</em></tt>&nbsp;: look for the
 live state in <em>live</em>. Default is
-<tt>/run/s6-rc</tt>. </li>
+<tt>/run/s6-rc</tt>. The default can be changed at compile-time by
+giving the <tt>--livedir=<em>live</em></tt> option to <tt>./configure</tt>. </li>
  <li> <tt>-a</tt>&nbsp;: add the current set of active services to
 the selection. This is useful for instance at
 shutdown time: <tt>s6-rc -da change</tt>
@@ -327,11 +329,11 @@ stored in the <tt>/zork</tt> directory instead of <tt>/run/s6-rc</tt>.
 <em>myservicebundle</em>, as well as everything that depends on them.
 </p>
 
-<pre> s6-rc -pun0 <em>myservicebundle</em> </pre>
+<pre> s6-rc -pun0 change <em>myservicebundle</em> </pre>
 <p>
  Prints what s6-rc would do to bring the state to <em>exactly</em>
 the contents of <em>myservicebundle</em> as well as its recursive
-dependencies, and pruning all the rest. Do not wait any extra time
+dependencies, and pruning all the rest. Does not wait any extra time
 between simulated transitions.
 </p>
 
diff --git a/doc/why.html b/doc/why.html
index f544e08..d392ab5 100644
--- a/doc/why.html
+++ b/doc/why.html
@@ -89,9 +89,9 @@ initialization scripts) and <em>longruns</em> (daemons), are needed.
  Unix distributions usually come with their own init systems and
 service managers; all of those have flaws one way or another. No
 widely spread init system gets things right, which is the main
-reason for the recent "init wars" - there are strong, valid reasons
-to support such or such init system, but <em>also</em> strong, valid
-reason to dislike it.
+reason for the recent "init wars" - no matter what init system you
+talk about, there are strong, valid reasons to like it and support it,
+and there are <em>also</em> strong, valid reasons to dislike it.
 </p>
 
 <p>
@@ -173,7 +173,9 @@ because Apple doesn't see fit to provide a documentation page for
 launchd) is very clear: it replaces init, rc, init.d/rc.d,
 SystemStarter, inetd, crontd, atd and watchdogd. It does all of this
 in process 1. And it uses XML for daemon configuration, so process 1
-has to link in a XML parsing library. </li>
+has to link in a XML parsing library. Is this the sleek, elegant
+design that Apple is usually known for? Stick to selling iPhones,
+guys. </li>
  <li> <a href="http://www.freedesktop.org/wiki/Software/systemd/">systemd</a>,
 the main protagonist (or antagonist) in the "init wars". It has the same
 problems as launchd, up by an order of magnitude;
@@ -200,9 +202,9 @@ architects were obviously not Unix experts, which is a shame when
 it's about creating a process 1 for Unix. This is apparent because: </li>
  <li> They have been designed like <em>application software</em>, not
 <em>system software</em>, which requires a fairly different set of
-skills, and careful attention to details - such as minimal software
-dependencies and shortness of code paths - that are not as important
-in application software. </li>
+skills, and careful attention to details
+that are not as important in application software, 
+such as minimal software dependencies and shortness of code paths. </li>
 </ul>
 
 <p>
@@ -226,7 +228,8 @@ readiness notification support, reproducible script execution, and
  <li> s6-rc is a <em>service manager</em>, i.e. the equivalent of
 <tt>sysv-rc</tt> or OpenRC. It is <em>not</em> an init system.
 <strong>You can run s6-rc with any init system of your choosing.</strong>
-Of course, s6-rc requires a s6 supervision tree to be running on
+Of course, s6-rc requires a
+<a href="http://skarnet.org/software/s6/">s6</a> supervision tree to be running on
 the system, since it delegates the management of longrun services
 to that supervision tree, but it does not require that s6 be the
 init system itself. s6-rc will work