Some documentation updates

3 files changed, 64 insertions, 10 deletions

diff --git a/doc/faq.html b/doc/faq.html
index 2fe7acd..692c7f7 100644
--- a/doc/faq.html
+++ b/doc/faq.html
@@ -25,10 +25,13 @@
 Why not put all the information for a service in a single file? </h3>
 
 <p>
- Because parsing sucks. Writing parsers is an annoying, ungrateful task;
-and automatic parser generators produce big and inefficient code. For
+ Because parsing sucks. Writing parsers is an annoying, ungrateful task,
+with significant risks of bugs and security holes;
+and automatic parser generators produce big and inefficient code - and
+they are not immune to bugs or security holes either. For
 security, efficiency and maintainability reasons, I prefer to focus my
-efforts on code that actually does stuff, not parsing code.
+efforts on code that actually does stuff, not code that parses a text
+file.
 </p>
 
 <p>
@@ -206,5 +209,47 @@ for.
  When in doubt, use bundles.
 </p>
 
+<h2> Mechanism vs. policy </h2>
+
+<h3> s6-rc feels bare: there are tools, but no wrappers, no pre-packaged
+scripts to boot my machines, no default runlevels. By comparison, OpenRC
+provides a complete default set of scripts! </h3>
+
+<p>
+ In the world of software development, it is important to distinguish
+<em>mechanism</em> from <em>policy</em>. Mechanism is "how do I perform
+the job", and should, theoretically, be addressed by software authors.
+Policy is "what are the details of the job I perform, where should I
+put my files, what conventions do I use", and should, theoretically, be
+addressed by <em>Unix distributions</em>.
+</p>
+
+<p>
+ Like the rest of <a href="http://skarnet.org/software/">skarnet.org
+software</a>, s6-rc aims to provide <em>mechanism, not policy</em>:
+it is OS-agnostic and distribution-agnostic. Providing boot scripts,
+or anything of this kind, would go against this principle; it is
+possible that a policy defined by software conflicts with a
+policy defined by a distribution, for instance the provided boot
+scripts do not match the distribution's needs, and so the distributors
+have to patch the software!
+</p>
+
+<p>
+ The s6-rc tools only provide mechanism, so they can be used as is by
+individual users, or by a distribution. They do not need to be patched.
+It is up to distributions to provide their own policy surrounding those
+tools, including complete service databases. It is literally the
+distributors' job!
+</p>
+
+<p>
+ OpenRC is a different case, because it was developed <em>by</em> and
+<em>for</em> a Linux distribution, so with that in mind, the OpenRC
+developers did not have to think much about separating mechanism from policy.
+It works very well for Gentoo and Gentoo-derived distributions; but it
+requires more work to use OpenRC outside of that frame.
+</p>
+
 </body>
 </html>
diff --git a/doc/s6-rc-update.html b/doc/s6-rc-update.html
index fc049b4..1e56ba2 100644
--- a/doc/s6-rc-update.html
+++ b/doc/s6-rc-update.html
@@ -32,7 +32,7 @@ s6-rc-update will do its best on its own, but it lets the user
 give it instructions to handle
 difficult cases; and rather than implement doubtful
 heuristics, it will fail with an error message in
-situations it really cannot solve.
+situations it cannot solve.
 </p>
 
 <h2> Interface </h2>
@@ -254,13 +254,21 @@ be the same argument that was given to the
 booted. In other words: it should be the name of the symbolic link pointing
 to the real directory containing the live information, not the name of the
 real directory. </li>
- <li> The old compiled service database is left unchanged, and the new compiled
+ <li> If a longrun service is renamed from <em>oldname</em> to <em>newname</em>,
+but not restarted, the
+<a href="http://skarnet.org/software/s6/s6-supervise.html">s6-supervise</a>
+process in charge of it will still show up in the process list as
+<tt>s6-supervise <em>oldname</em></tt>. This is purely cosmetic. To make
+s6-supervise pick up the new name, make sure to restart the service when
+invoking s6-rc-update. </li>
+ <li> After a s6-rc-update invocation, the old compiled service database
+is left unchanged where it was, and the new compiled
 service database is used in-place. If the machine is rebooted, the
 <a href="s6-rc-init.html">s6-rc-init</a> invocation will still boot on the
 old compiled unless more work is performed. It is recommended to keep a
 <tt>current</tt> symbolic link to the current compiled, to always
 <a href="s6-rc-init.html">s6-rc-init</a> on <tt>current</tt>, and to
-make <tt>current</tt> point to the new compiled right after a s6-rc-update
+make <tt>current</tt> a link to the new compiled right after a s6-rc-update
 invocation. </li>
 </ul>
 
diff --git a/doc/s6-rc.html b/doc/s6-rc.html
index 5cdf720..8eb0753 100644
--- a/doc/s6-rc.html
+++ b/doc/s6-rc.html
@@ -223,10 +223,11 @@ it will exit 1. </li>
 <h4> Longrun transitions </h4>
 
 <p>
- Transitions for longrun services are simple: s6-rc removes or create
-a down file, then sends a command
+ Transitions for longrun services are simple: s6-rc removes or creates
+a <tt>./down</tt> file in the live service directory for the longrun
+service, then sends a command
 to the supervision tree to start or stop the service. (A service that
-is considered down by s6-rc will have a down file in its live service
+is considered down by s6-rc will have a <tt>./down</tt> file in its live service
 directory; a service that is considered up by s6-rc will not.) The
 transition is considered successful as soon as the daemon dies (for
 down transitions), or becomes up and
@@ -236,7 +237,7 @@ readiness notification, the
 <a href="http://skarnet.org/software/s6/s6-svc.html">s6-svc</a>
 command that is invoked by s6-rc will print a warning message, and
 the transition will be considered successful as soon as the daemon
-is up, i.e. as soon as the <tt>run</tt> script is executed by
+is up, i.e. as soon as the <tt>./run</tt> script is executed by
 <a href="http://skarnet.org/software/s6/s6-supervise.html">s6-supervise</a>.
 </p>