From 1e3982ebb17956daeaae322c485183135fc57b26 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Sat, 4 Nov 2017 14:50:10 +0000
Subject:  Update documentation, prepare for 0.4.0.0

---
 doc/index.html         |  4 ++--
 doc/s6-rc-compile.html | 47 +++++++++++++++++++++++++++++++++--------------
 doc/upgrade.html       | 17 +++++++++++++++++
 3 files changed, 52 insertions(+), 16 deletions(-)

(limited to 'doc')

diff --git a/doc/index.html b/doc/index.html
index 544fa85..5f1b401 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -48,7 +48,7 @@ scripts are also run in a controlled environment.
  <li> A POSIX-compliant system with a standard C development environment </li>
  <li> GNU make, version 3.81 or later </li>
  <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> version
-2.6.0.1 or later </li>
+2.6.1.0 or later </li>
  <li> <a href="//skarnet.org/software/execline/">execline</a> version
 2.3.0.3 or later </li>
  <li> <a href="//skarnet.org/software/s6/">s6</a> version
@@ -66,7 +66,7 @@ scripts are also run in a controlled environment.
 
 <ul>
  <li> The current released version of s6-rc is
-<a href="s6-rc-0.3.0.0.tar.gz">0.3.0.0</a>. </li>
+<a href="s6-rc-0.4.0.0.tar.gz">0.4.0.0</a>. </li>
  <li> Alternatively, you can checkout a copy of the
 <a href="//git.skarnet.org/cgi-bin/cgit.cgi/s6-rc/">s6-rc
 git repository</a>:
diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html
index 14bec2f..4065689 100644
--- a/doc/s6-rc-compile.html
+++ b/doc/s6-rc-compile.html
@@ -287,19 +287,20 @@ be copied verbatim into the generated service directory. </li>
 it must contain the name of another longrun service <em>servicelog</em>;
 <em>service</em> is then declared as a producer for <em>servicelog</em>.
 <em>servicelog</em> must also, in its own definition directory,
-be declared as a consumer for <em>service</em>. </li>
+be declared as a consumer for at least <em>service</em>. </li>
  <li> An optional file named <tt>consumer-for</tt>. If this file exists, then
-it must contain the name of another longrun service <em>serviceprod</em>;
-<em>service</em> is then declared as a consumer for <em>serviceprod</em>.
-<em>serviceprod</em> must also, in its own definition directory,
+it must contain a list of longrun services <em>serviceprod...</em>:
+<em>service</em> is then declared as a consumer for all the services
+in <em>serviceprod</em>. Each of those services
+must also, in its own definition directory,
 be declared as a producer for <em>service</em>. </li>
  <li> An optional file named <tt>pipeline-name</tt>. If this file exists
-along with a <tt>producer-for</tt> file, and there is no
-<tt>consumer-for</tt> file, then a bundle will automatically be
+along with a <tt>consumer-for</tt> file, and there is no
+<tt>producer-for</tt> file, then a bundle will automatically be
 created, named with the content of the <tt>pipeline-name</tt> file, and
-containing all the services in the pipeline that starts at <em>service</em>.
+containing all the services in the pipeline that ends at <em>service</em>.
 See below for more about pipelining. The <tt>pipeline-name</tt> file
-is ignored if <em>service</em> is not a first producer. </li>
+is ignored if <em>service</em> is not a last consumer. </li>
 </ul>
 
 <p>
@@ -342,12 +343,12 @@ indefinite number of longrun services this way.
 </p>
 
 <ul>
- <li> The first producer declares its direct consumer in a <tt>producer-for</tt> file. </li>
- <li> Intermediate services declare both their direct producer in their
+ <li> A producer declares its direct consumer in a <tt>producer-for</tt> file. </li>
+ <li> Intermediate services declare both their direct producers in their
 <tt>consumer-for</tt> file, and their direct consumer in their
 <tt>producer-for</tt> file. </li>
- <li> The last consumer only declares its direct producer in a <tt>consumer-for</tt> file. </li>
- <li> The first producer may declare a name for the whole pipeline, in
+ <li> The last consumer only declares its direct producers in a <tt>consumer-for</tt> file. </li>
+ <li> The last consumer may also declare a name for the whole pipeline, in
 its <tt>pipeline-name</tt> file. If it does so, then a bundle is automatically
 created with
 the given name, and it contains all the services in the pipeline. </li>
@@ -359,15 +360,33 @@ so that every producer's stdout is connected to its consumer's stdin, and
 that the pipes are not broken whenever one element in the chain dies.
 </p>
 
+<p>
+ A service can only be declared as a producer for <em>one</em> other
+services, but it can be declared as a consumer for several other
+services: the <em>consumer-for</em> can have several lines. This
+means that one service can only send its output to one consumer, but
+it can read its input from several producers. If there are several
+producers to a service, they will all write to the same Unix pipe
+that the service reads.
+</p>
+
+<p>
+ This means that what s6-rc calls <em>pipelines</em> are really
+<em>funnels</em>: you can collapse multiple data streams into
+a single data stream, at every step of your processing chain.
+The <em>pipeline</em> terminology remains for history reasons:
+previous versions of s6-rc could not handle multiple producers.
+</p>
+
 <p>
  s6-rc-compile checks for pipeline consistency. It must see a
-<tt>producer-for</tt> file in the producer's definition that is consistent
+<tt>producer-for</tt> file in the producers' definition that is consistent
 with the <tt>consumer-for</tt> file in the consumer's definition. It will
 detect and reject cycles as well as collisions.
 </p>
 
 <p>
- The pipe linking a producer with a consumer is created and stored at
+ The pipe linking a set of producers with a consumer is created and stored at
 run-time in a
 <a href="//skarnet.org/software/s6/s6-fdholder-daemon.html">s6-fdholder-daemon</a>
 instance managed by an automatically generated longrun service named
diff --git a/doc/upgrade.html b/doc/upgrade.html
index fa441d1..444b763 100644
--- a/doc/upgrade.html
+++ b/doc/upgrade.html
@@ -30,6 +30,23 @@ minor and bugfix version changes.
 
 <h1> What has changed in s6-rc </h1>
 
+<h2> in 0.4.0.0 </h2>
+
+<ul>
+ <li> <a href="//skarnet.org/software/skalibs/">skalibs</a>
+dependency bumped to 2.6.1.0. </li>
+ <li> <a href="s6-rc-compile.html">s6-rc-compile</a> now
+accepts multiple lines in a <tt>consumer-for</tt> file: a
+longrun can now have multiple producers, which means that
+pipelines are really funnels. The compiled databases <strong>are not</strong>
+compatible with previous versions, and the source databases
+<strong>are not</strong> compatible either, because the
+<tt>pipeline-name</tt> file must now be present in the definition of
+the final consumer of a pipeline, not in the definition of a first
+producer (to avoid ambiguity). Edit your databases and recompile
+them. </li>
+</ul>
+
 <h2> in 0.3.0.0 </h2>
 
 <ul>
-- 
cgit v1.3.1