overview.html: reorder sections to have a better conceptual flow

note: expects an id in s6-rc-compile.html for the source format.

1 files changed, 71 insertions, 74 deletions

diff --git a/doc/overview.html b/doc/overview.html
index 01ca88a..a871dc7 100644
--- a/doc/overview.html
+++ b/doc/overview.html
@@ -18,6 +18,49 @@
 
 <h1> s6-frontend: an overview </h1>
 
+<h2 id="concepts"> Concepts </h2>
+
+<p>
+ s6-frontend does not come with any innovating concepts &mdash; it's just a series
+of user-friendly wrappers around various commands in the s6 ecosystem, hiding
+the details of various options and installation directories. For instance:
+</p>
+
+<ul>
+ <li> Instead of running <tt>s6-svc -r /run/service/foobar</tt>, you run
+<tt>s6 process restart foobar</tt> </li>
+ <li> Instead of running <tt>s6-rc -d change foobar</tt>, you run
+<tt>s6 live stop foobar</tt> </li>
+ <li> Instead of running <tt>s6-rc-init /run/service &amp;&amp; s6-rc change default</tt>
+at boot time, you run <tt>s6 system boot</tt> </li>
+</ul>
+
+<p>
+ The most innovating change comes from the
+<a href="//skarnet.org/software/s6-rc/repodefs.html">repo</a> commands, in the
+version of <a href="//skarnet.org/software/s6-rc/">s6-rc</a> that is released at the
+same time as the first release of s6-frontend. The goals of the <em>repo</em> commands, which
+are wrapped by the <a href="s6_repository.html"><tt>s6 repository</tt></a> and
+<a href="s6_set.html"><tt>s6 set</tt></a> commands, are:
+</p>
+
+<ul>
+ <li> To provide a framework for distributions and system administrators to organize their
+text-format source definition directories, by defining places where service definitions
+should be stored </li>
+ <li> To allow local administrators to tailor what services they want to see in
+their live database, by providing intermediaries between the service stores and
+the live database called offline sets.
+<ul>
+<li> With <a href="s6_set.html#mask"><tt>s6 set mask</tt></a>, an administrator
+can make it so a service, though defined in a store, will not appear in the service
+database at all. <em>Unmasked</em> services appear in the live database, but are only started
+at boot time when they are <em>enabled</em> (or <em>essential</em>, but that property
+is best set in the service definition itself and never overridden). </li>
+</ul></li>
+ <li> To allow easy replacement of the current live database by a set that has been
+worked on. </li>
+</ul>
 <h2 id="contents"> Contents of the s6-frontend package </h2>
 
 <p>
@@ -57,8 +100,7 @@ capabilities, etc. </li>
 <p>
  In addition to the s6-frontend package and its dependencies, in order to
 make use of the <a href="s6.html"><tt>s6</tt></a> command, you will need
-<em>service definitions</em>: a set of directories, in a format understandable
-by <a href="//skarnet.org/software/s6-rc/s6-rc-compile.html">s6-rc-compile</a>,
+<em>service definitions</em> in the <a href="//skarnet.org/software/s6-rc/s6-rc-compile.html#source">s6-rc source format</a>
 describing various services that can run on a machine &mdash; long-running
 daemons, one-shot scripts, and "bundles" aliasing to a group of these services.
 </p>
@@ -66,11 +108,11 @@ daemons, one-shot scripts, and "bundles" aliasing to a group of these services.
 <p>
  If you are running s6-frontend from a distribution, the packages that provide
 these services should already have them defined, and the service definition
-directories should already made available in some pre-configured
+directories should already be available in some pre-configured
 <a href="//skarnet.org/software/s6-rc/repodefs#store">stores</a>. Your
 distribution should also have pre-installed everything you need in order
 for you to be able to use the <a href="s6.html"><tt>s6</tt></a> command to
-control the system. But if you are installing s6-frontend manually, or are
+control the system. However, if you are installing s6-frontend manually, or are
 the person <em>building</em> the distribution, here is what you need to do:
 </p>
 
@@ -106,14 +148,14 @@ administrators should do their local modifications in
 at build time with the <tt>--storelist</tt> configure option, or after
 installation in the s6-frontend configuration file, see below. </li>
  </ul> </li>
- <li> And then you need the service definitions themselves.
+ <li> Then you need the service definitions themselves.
   <ul>
    <li> Service definitions for a given daemon such as e.g. sshd should
 be written by the distribution that packages sshd and provided by the
-package manager when it installs sshd. Alternatively, they
-could be provided by the sshd upstream, but service definitions are
-<em>policy</em>, not <em>mechanism</em>, and we think policy is the realm
-of distributions, not of software authors. </li>
+package manager when it installs sshd. (The definitions could be provided by
+the sshd upstream, but service definitions are <em>policy</em> not
+<em>mechanism</em> and we think policy is the realm of distributions, not
+software authors.) </li>
    <li> Essential services, i.e. how to boot a machine and bring it to
 the state where it can accept logins and run services provided by packages,
 should be provided by the distribution in a specific package. </li>
@@ -122,18 +164,18 @@ should be provided by the distribution in a specific package. </li>
 itself. </li>
      <li> OpenRC also comes with a set of basic services: it provides some policy
 itself as well. </li>
-     <li> s6-frontend <em>does not</em> provides policy, but since basic service
-files are essential for people to use it, work is underway to write them; they
-will be provided in a separate package. In the meantime, you can find service
-definitions contributed by the community pretty much everywhere s6-rc is used.
-The s6-rc package comes with some
+     <li> s6-frontend <em>does not</em> provides policy, but work is underway to
+write these since basic service files are essential for people to use it. When
+complete they will be provided in a separate package. In the meantime, you can
+find service definitions contributed by the community pretty much everywhere
+s6-rc is used and the s6-rc package comes with some
 <a href="https://git.skarnet.org/cgi-bin/cgit.cgi/s6-rc/tree/examples/source">example
-service definitions</a>. </li>
+service definitions</a> as well. </li>
     </ul> </li>
   </ul> </li>
  <li> Define a <a href="s6-frontend.conf.html">configuration file</a>,
 located at <tt>/etc/s6-frontend.conf</tt> unless you modified the default at
-build time. If you go with all the defaults for all the packages in the s6
+build time. If you have gone with all the defaults for all the packages in the s6
 ecosystem, the configuration file can basically be empty; but you will probably
 at least want to define the <tt>storelist</tt> variable. </li>
  <li> Once your configuration file is ready, and all your services are in the
@@ -142,7 +184,7 @@ store, you need to initialize the repository:
 will create the repository and make a reference database with all the services
 in your stores. If it succeeds, congratulations! Your stores are <em>consistent</em>,
 i.e. they define a full set of services that can be used by the s6-rc service manager. </li>
- <li> Check that the default states of the service are what you want, with
+ <li> Check that the default states of the service are what you want with
 <a href="s6_set.html#status"><tt>s6 set status</tt></a>. If they're not, make the
 changes you need with various <a href="s6_set.html#enable"><tt>s6 set</tt></a> commands. </li>
  <li> Once you're happy with the set, commit your changes with
@@ -164,64 +206,20 @@ the way to reboot your system will be
 </ul>
 
 
-<h2 id="concepts"> Concepts </h2>
-
-<p>
- s6-frontend does not come with any innovating concepts &mdash; it's just a series
-of user-friendly wrappers around various commands in the s6 ecosystem, hiding
-the details of various options and installation directories. For instance:
-</p>
-
-<ul>
- <li> Instead of running <tt>s6-svc -r /run/service/foobar</tt>, you run
-<tt>s6 process restart foobar</tt> </li>
- <li> Instead of running <tt>s6-rc -d change foobar</tt>, you run
-<tt>s6 live stop foobar</tt> </li>
- <li> Instead of running <tt>s6-rc-init /run/service &amp;&amp; s6-rc change default</tt>
-at boot time, you run <tt>s6 system boot</tt> </li>
-</ul>
-
-<p>
- The most innovating change comes from the
-<a href="//skarnet.org/software/s6-rc/repodefs.html">repo</a> commands, in the
-version of <a href="//skarnet.org/software/s6-rc/">s6-rc</a> that is released at the
-same time as the first release of s6-frontend. The goals of the <em>repo</em> commands, which
-are wrapped by the <a href="s6_repository.html"><tt>s6 repository</tt></a> and
-<a href="s6_set.html"><tt>s6 set</tt></a> commands, are:
-</p>
-
-<ul>
- <li> To provide a framework for distributions and system administrators to organize their
-text-format source definition directories, by defining places where service definitions
-should be stored </li>
- <li> To allow local administrators to tailor what services they want to see in their
-live database, by providing an intermediary between the stores and the live database:
-offline sets. With <a href="s6_set.html#mask"><tt>s6 set mask</tt></a>, an administrator
-can make it so a service, though defined in a store, will not appear in the service
-database at all. <em>Unmasked</em> services appear in the live database, but are only started
-at boot time when they are <em>enabled</em> (or <em>essential</em>, but that property
-is best set in the service definition itself and never overridden). </li>
- <li> To allow easy replacement of the current live database by a set that has been
-worked on. </li>
-</ul>
-
 <h2 id="openrc"> Comparison with OpenRC </h2>
 
 <p>
  One of the design goals of s6-frontend is to provide a user interface to service
-management that is comparable to the one provided by OpenRC.
+management that is comparable to the one provided by OpenRC and should be
+similar in everyday usage barring the following differences.
 </p>
 
 <p>
- A fundamental difference between s6-frontend and OpenRC is that OpenRC always
+ The fundamental difference between s6-frontend and OpenRC is that OpenRC always
 works on <em>live services</em>, the ones that are currently running on the
 user's machine. It only has one <em>live database</em>, comprising several
 "runlevels" (sets of services meant to be run together), and manages its
-dependency tree dynamically.
-</p>
-
-<p>
- s6-frontend, on the other hand (and more accurately, this is the domain of
+dependency tree dynamically. On the other hand, s6-frontend (and, more accurately,
 the <a href="//skarnet.org/software/s6-rc/">s6-rc</a> service manager and its
 <a href="//skarnet.org/software/s6-rc/repodefs.html">repo</a> commands),
 separates the notion of <em>live database</em> and of <em>working set</em>
@@ -230,8 +228,8 @@ impacting the current machine state. You can <em>start</em> and <em>stop</em>
 live services, but you can only <em>enable</em> or <em>disable</em>
 &mdash; or <em>mask</em> &mdash; services on the working set. Enabling a
 service means that <em>next time you boot on the service database you are
-working on</em>, that service will be automatically started. <br>
- Once you have worked on a set of services, you can replace the live
+working on</em>, that service will be automatically started. <br />
+ Once you have worked on a set of services you can replace the live
 database with it; the old live database disappears entirely, and your
 working set (well, a copy of it) is now <em>live</em>.
 </p>
@@ -242,16 +240,15 @@ not need them. The <em>default bundle</em> specifies what services should
 be started at boot; other bundles (in the sense of s6-rc) can be defined
 in the stores, and the user can start and stop them at will, as well as
 start and stop individual services, dependencies notwithstanding. By
-default, all the services are accessible in the live database, but the
+default all the services are accessible in the live database but the
 user can choose to exclude certain services by <em>masking them</em> in
 a working set and then installing that set.
 </p>
 
 <p>
- These differences being given, s6-frontend should be very comparable to
-OpenRC in its everyday usage. Here is a table showing some correspondences;
-it is not meant to be exhaustive, but to show a representative enough sample
-of the kind of commands that can be worked with.
+ The following table shows some equivalencies between s6-frontend and OpenRC;
+it is not meant to be exhaustive but to show a representative enough sample of
+the kind of commands that can be worked with.
 </p>
 
 <table>
@@ -283,12 +280,12 @@ in which case it will give detailed information on its supervised instance. </td
    <tr>
     <td> <tt>rc-update add foobar</tt> </td>
     <td> <tt>s6 set enable foobar</tt> </td>
-    <td> See below. </td>
+    <td> Enable service <tt>foobar</tt> in the offline working set. </td>
    </tr>
    <tr>
     <td> <tt>rc-update del foobar</tt> </td>
     <td> <tt>s6 set disable foobar</tt> </td>
-    <td> See below. </td>
+    <td> Disable service <tt>foobar</tt> in the offline working set. </td>
    </tr>
    <tr>
     <td> <tt>rc-update show</tt> </td>