[PATCH 1/2] doc/s6-rc-compile.html: document bundle flattening

[PATCH 1/2] doc/s6-rc-compile.html: document bundle flattening

[Adam Joseph]

This commit adds a single sentence explaining that nested bundles
are flattened by s6-rc-compile; the fact that one bundle contains
another (rather than merely happening to contain all the atomics
that the latter contains) is not preserved by s6-rc-compile.

Although this is the most reasonable handling it is not the only
possible handling.  I had to read the source code in order to make
sure that bundle nesting was not represented in the output of
s6-rc-compile, and figured that adding a mention of this fact to the
documentation might save others the trouble.

More importantly, the special rules for singleton bundles (see next
patch in series) depend on this flattening behavior.

Signed-off-by: Adam Joseph <adam@westernsemico.com>
---
 doc/s6-rc-compile.html | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html
index e1ad82b..ef06893 100644
--- a/doc/s6-rc-compile.html
+++ b/doc/s6-rc-compile.html
@@ -136,6 +136,9 @@ deprecated. </li>
 <tt>contents</tt> file.
 However, if s6-rc-compile detects a cycle in bundle definitions, it will
 complain and exit 1.
+Bundles are flattened during compilation: a parent bundle which
+contains a child bundle will be compiled as if the parent bundle had
+directly included the child bundle's contents.
 </p>
 
 <h3> For atomic services </h3>
-- 
2.41.0

[PATCH 2/2] doc: define "singleton bundle", document special rules

[Adam Joseph]

While reviewing the source code for s6-rc-update I noticed that it
has special handling for singleton bundles; these are not explicitly
defined in the documentation, nor is this behavior described.  This
commit does so.

Signed-off-by: Adam Joseph <adam@westernsemico.com>
---
 doc/s6-rc-compile.html |  9 +++++++++
 doc/s6-rc-update.html  | 13 ++++++++-----
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html
index ef06893..0c7301b 100644
--- a/doc/s6-rc-compile.html
+++ b/doc/s6-rc-compile.html
@@ -141,6 +141,15 @@ contains a child bundle will be compiled as if the parent bundle had
 directly included the child bundle's contents.
 </p>
 
+<p>
+A <i>singleton bundle</i> is a bundle which contains exactly one
+atomic after flattening.  This distinction is important
+to <tt>s6-rc-update</tt>, which allows renaming of singleton bundles
+(but not other bundles), and which considers a singleton bundle to
+be of the same type (oneshot or longrun) as the atomic it contains
+for purposes of avoiding unnecessary restarts.
+</p>
+
 <h3> For atomic services </h3>
 
 <ul>
diff --git a/doc/s6-rc-update.html b/doc/s6-rc-update.html
index 0883a22..49aa16a 100644
--- a/doc/s6-rc-update.html
+++ b/doc/s6-rc-update.html
@@ -149,8 +149,10 @@ service to be restarted in the following cases:
  <li> The service has disappeared in the new compiled. In this case, the
 old service will simply be stopped. </li>
  <li> The service has changed types: a oneshot becomes a longrun, a longrun
-becomes a oneshot, or an atomic service becomes a bundle. In this case, the
-old service will be stopped, then the new service will be started. </li>
+becomes a oneshot, or an atomic service becomes a non-singleton bundle. In this case, the
+old service will be stopped, then the new service will be started.
+Note that singleton bundles are considered to be the same type
+as the single atomic they contain.</li>
  <li> The service has a dependency to a service that must restart, or to an
 old service that must stop, or to a new service that did not previously
 exist or that was previously down. </li>
@@ -202,8 +204,8 @@ can be quoted, that <tt>#</tt> comments are recognized, etc.
 </p>
 
 <p>
- The first word in a line must be the name of an "old" atomic service, i.e.
-an atomic service contained in the current live database. The remaining
+ The first word in a line must be the name of an "old" atomic service or singleton bundle, i.e.
+an atomic service (or bundle containing exactly one atomic service) contained in the current live database. The remaining
 words in the line are instructions telling s6-rc-update how to convert
 that service.
 </p>
@@ -216,7 +218,8 @@ line must be the new name of the service in the new database: s6-rc-update
 will then rename it. It is possible
 to rename an atomic service to another atomic service or a bundle, but no
 matter whether a service is renamed or not, changing its type will force a
-restart.
+restart.  Note that singleton bundles are considered to be the same type as
+the atomic they contain.
 </p>
 
 <h4> Restarting </h4>
-- 
2.41.0