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 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 47 insertions(+), 5 deletions(-)

(limited to 'doc/s6-frontend-alias-chpst.html')

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>
-- 
cgit v1.3.1