From d4ce4dc23a189daae4310f9b727ea92454b734ab Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Tue, 31 Dec 2019 01:20:10 +0000
Subject:  Add s6-frontend-alias* documentation

---
 doc/s6-frontend-alias-chpst.html | 52 +++++++++++++++++++---
 doc/s6-frontend-alias-sv.html    | 35 ++++++++++++---
 doc/s6-frontend-alias.html       | 95 ++++++++++++++++++++++++++++++++++++++--
 3 files changed, 168 insertions(+), 14 deletions(-)

diff --git a/doc/s6-frontend-alias-chpst.html b/doc/s6-frontend-alias-chpst.html
index 6c2fe2d..8cfe011 100644
--- a/doc/s6-frontend-alias-chpst.html
+++ b/doc/s6-frontend-alias-chpst.html
@@ -16,25 +16,67 @@
 <a href="//skarnet.org/">skarnet.org</a>
 </p>
 
-<h1> The s6-frontend-alias-chpst program </h1>
+<h1> The <tt>s6-frontend-alias-chpst</tt> program </h1>
 
 <p>
-s6-frontend-alias-chpst
+<tt>s6-frontend-alias-chpst</tt> implements
+<a href="http://smarden.org/runit/">runit</a>'s
+<a href="http://smarden.org/runit/chpst.8.html">chpst</a> command
+by rewriting itself into a command line made of idiomatic
+chainloading <a href="//skarnet.org/software/s6/">s6</a> commands.
 </p>
 
 <h2> Interface </h2>
 
 <pre>
-     s6-frontend-alias-chpst
+     s6-frontend-alias-chpst [ -v ] [ -P ] [ -0 ] [ -1 ] [ -2 ] [ -u <em>user</em> ] [ -U <em>user</em> ] [ -b <em>argv0</em> ] [ -e <em>dir</em> ] [ -/ <em>root</em> ] [ -n <em>inc</em< ] [ -l|-L <em>lock</em> ] [ -m <em>bytes</em> ] [ -d <em>bytes</em> ] [ -o <em>n</em> ] [ -p <em>n</em> ] [ -f <em>bytes</em> ] [ -c <em>bytes</em> ] <em>prog...</em>
 </pre>
 
 <p>
+ When s6-frontend has been configured with the
+<tt>--enable-aliases-runit</tt> option, the
+<tt>s6-frontend-alias-chpst</tt> program is built, and at installation
+time, a <tt>chpst</tt> symbolic link is created, pointing to it.
 </p>
 
-<h2> Options </h2>
+<p>
+ <tt>s6-frontend-alias-chpst</tt> implements most of the functionality of
+<a href="http://smarden.org/runit/chpst.8.html">chpst</a>, as closely as
+possible. It does so by rewriting itself into a command line that may
+invoke one or more of the following programs:
+</p>
+
+<ul>
+ <li> The Unix <a href="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/nice.html">nice</a> command </li>
+ <li> The s6 <a href="//skarnet.org/software/s6/s6-setsid.html">s6-setsid</a> command </li>
+ <li> The s6 <a href="//skarnet.org/software/s6/s6-envdir.html">s6-envdir</a> command </li>
+ <li> The s6 <a href="//skarnet.org/software/s6/s6-setlock.html">s6-setlock</a> command </li>
+ <li> The s6 <a href="//skarnet.org/software/s6/s6-applyuidgid.html">s6-applyuidgid</a> command </li>
+ <li> The s6 <a href="//skarnet.org/software/s6/s6-envuidgid.html">s6-envuidgid</a> command </li>
+ <li> The s6 <a href="//skarnet.org/software/s6/s6-softlimit.html">s6-softlimit</a> command </li>
+ <li> The execline <a href="//skarnet.org/software/execline/fdclose.html">fdclose</a> command </li>
+ <li> The execline <a href="//skarnet.org/software/execline/exec.html">exec</a> command </li>
+ <li> The non-standard (but ubiquitous) Unix <a href="https://helpmanual.io/man8/chroot/">chroot</a> command </li>
+</ul>
+
+<h2> Notes </h2>
 
 <ul>
- <li> <tt>-v</tt>&nbsp;: verbose. </li>
+ <li> When the <tt>-v</tt> option is given,
+<tt>s6-frontend-alias-chpst</tt> prints an informational
+message to stderr, showing the entire command line it is going to execute into. </li>
+ <li> <tt>s6-frontend-alias-chpst</tt> is a convenience program, written
+so that runit users can keep using <tt>chpst</tt> while learning the
+corresponding idiomatic s6 commands. However, it is not an "official"
+interface. <tt>chpst</tt> acts as a big toolbox, whereas s6 prefers the
+"one function = one tool" philosophy. It is recommended that runit users
+who are new to s6 use the <tt>-v</tt> option to see how their <tt>chpst</tt>
+invocation translates into s6 parlance. </li>
+ <li> Some <tt>chpst -u</tt> invocations do not translate perfectly
+because s6 uses a slightly different model of acquiring user and group
+identity via
+<a href="//skarnet.org/software/s6/s6-envuidgid.html">s6-envuidgid</a>.
+This should not prevent <tt>chpst</tt> from working. </li>
 </ul>
 
 </body>
diff --git a/doc/s6-frontend-alias-sv.html b/doc/s6-frontend-alias-sv.html
index 8c1f92a..a619661 100644
--- a/doc/s6-frontend-alias-sv.html
+++ b/doc/s6-frontend-alias-sv.html
@@ -16,25 +16,50 @@
 <a href="//skarnet.org/">skarnet.org</a>
 </p>
 
-<h1> The s6-frontend-alias-sv program </h1>
+<h1> The <tt>s6-frontend-alias-sv</tt> program </h1>
 
 <p>
-s6-frontend-alias-sv
+<tt>s6-frontend-alias-sv</tt> implements
+<a href="http://smarden.org/runit/">runit</a>'s
+<a href="http://smarden.org/runit/sv.8.html">sv</a> command over a
+<a href="//skarnet.org/software/s6/">s6</a> supervision tree, via
+native <a href="//skarnet.org/software/s6/">s6</a> commands.
+
 </p>
 
 <h2> Interface </h2>
 
 <pre>
-     s6-frontend-alias-sv
+     s6-frontend-alias-sv [ -v ] [ -w <em>secs</em> ] <em>command</em> <em>services...</em>
 </pre>
 
 <p>
+ When s6-frontend has been configured with the
+<tt>--enable-aliases-runit</tt> option, the
+<tt>s6-frontend-alias-sv</tt> program is built, and at installation
+time, a <tt>sv</tt> symbolic link is created, pointing to it.
+</p>
+
+<p>
+ <tt>s6-frontend-alias-sv</tt> implements most of the functionality of
+<a href="http://smarden.org/runit/sv.8.html">sv</a>, as closely as
+possible. When some functionality cannot be emulated on a s6
+supervision tree, it prints an error message to stderr and exits 100.
 </p>
 
-<h2> Options </h2>
+<h2> Notes </h2>
 
 <ul>
- <li> <tt>-v</tt>&nbsp;: verbose. </li>
+ <li> <tt>s6-frontend-alias-sv</tt> is a convenience program, written
+so that runit users can keep using <tt>sv</tt> to control their
+s6 services. However, it is not an "official" interface, because there
+are a few fundamental differences between the conception of runit and
+the conception of s6 that make <tt>sv</tt> a poor fit to accurately
+interface with the advanced features of s6. It is recommended that
+<tt>sv</tt> users become familiar with idiomatic s6 commands such as
+<a href="//skarnet.org/software/s6/s6-svc.html">s6-svc</a>,
+<a href="//skarnet.org/software/s6/s6-svstat.html">s6-svstat</a>, and
+<a href="//skarnet.org/software/s6/s6-svwait.html">s6-svwait</a>. </li>
 </ul>
 
 </body>
diff --git a/doc/s6-frontend-alias.html b/doc/s6-frontend-alias.html
index 4e824c9..369c792 100644
--- a/doc/s6-frontend-alias.html
+++ b/doc/s6-frontend-alias.html
@@ -16,25 +16,112 @@
 <a href="//skarnet.org/">skarnet.org</a>
 </p>
 
-<h1> The s6-frontend-alias program </h1>
+<h1> The <tt>s6-frontend-alias</tt> program </h1>
 
 <p>
-s6-frontend-alias
+<tt>s6-frontend-alias</tt> is a multicall binary that implements
+functionality from the
+<a href="https://cr.yp.to/daemontools.html">daemontools</a> package,
+and/or from the
+<a href="http://smarden.org/runit/">runit</a> package, whenever
+possible, via 
+<a href="//skarnet.org/software/s6/">s6</a> commands.
 </p>
 
 <h2> Interface </h2>
 
 <pre>
-     s6-frontend-alias
+     s6-frontend-alias [ -v ] <em>daemontools_command</em> <em>args...</em>
+     s6-frontend-alias [ -v ] <em>runit_command</em> <em>args...</em>
+     <em>daemontools_command</em> <em>args...</em>
+     <em>runit_command</em> <em>args...</em>
 </pre>
 
 <p>
+<tt>s6-frontend-alias</tt> can be called as is: then it takes the command
+name as its argument. Or, it can be called directly as the wanted command.
+It finds the closest approximation of the command in the s6 world, and
+executes into it. When it cannot find a suitable idiomatic s6 version of
+the wanted command, it prints an explanatory message to stderr, then
+exits 100.
+</p>
+
+<p>
+<tt>s6-frontend-alias</tt> is only built when at least one of the
+<tt>--enable-alias-daemontools</tt> and <tt>--enable-alias-runit</tt>
+options have been given to configure at build time.
+</p>
+
+<p>
+When the <tt>--enable-alias-daemontools</tt> option has been given,
+the following commands are created at installation time as symbolic
+links to <tt>s6-frontend-alias</tt>, which recognizes them:
+</p>
+
+<ul>
+ <li> envdir </li>
+ <li> envuidgid </li>
+ <li> fghack </li>
+ <li> multilog </li>
+ <li> pgrphack </li>
+ <li> readproctitle </li>
+ <li> setlock </li>
+ <li> setuidgid </li>
+ <li> softlimit </li>
+ <li> supervise </li>
+ <li> svc </li>
+ <li> svok </li>
+ <li> svscan </li>
+ <li> svscanboot </li>
+ <li> svstat </li>
+ <li> tai64n </li>
+ <li> tai64nlocal </li>
+</ul>
+
+<p>
+When the <tt>--enable-alias-runit</tt> option has been given,
+the following commands are created at installation time as symbolic
+links to <tt>s6-frontend-alias</tt>, which recognizes them:
+</p>
+
+<ul>
+ <li> runit </li>
+ <li> runit-init </li>
+ <li> runsvdir </li>
+ <li> runsvchdir </li>
+ <li> runsv </li>
+ <li> svlogd </li>
+ <li> utmpset </li>
+</ul>
+
+<p>
+(The <tt>chpst</tt> and <tt>sv</tt> runit commands are recognized
+by <tt>s6-frontend-alias</tt>, but handled by specific programs,
+<a href="s6-frontend-alias-chpst.html">s6-frontend-alias-chpst</a> and
+<a href="s6-frontend-alias-sv.html">s6-frontend-alias-sv</a>, and the
+<tt>chpst</tt> and <tt>sv</tt> symbolic links point directly to those
+programs.)
 </p>
 
 <h2> Options </h2>
 
 <ul>
- <li> <tt>-v</tt>&nbsp;: verbose. </li>
+ <li> <tt>-v</tt>&nbsp;: verbose. When <tt>s6-frontend-alias</tt>
+is called under its own name and this option is given, it prints
+an explanatory message to stderr before executing into the
+corresponding idiomatic s6 command. </li>
+</ul>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> <tt>s6-frontend-alias</tt> is a convenience program, written
+so that daemontools and runit users can keep using their habits while
+transitioning to s6. However, it is not an "official" interface,
+because s6 is strictly more powerful than daemontools, and has a few
+significant fundamental differences with runit. Daemontools and runit
+users are still encouraged to learn and get used to the native
+s6 commands. </li>
 </ul>
 
 </body>
-- 
cgit v1.2.3