Further improve runparts/hook script docs, add limitations

Issue #320

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>

doc/config.md

@@ -638,6 +638,33 @@ files, or scripts, in the directory are called, in alphabetic order.
 The scripts in this directory are executed at the very end of runlevel
 `S`, [bootstrap][].
 
+**Limitations:**
+
+Scripts called from `runparts`, or hook scripts (see below), are limited
+in what they can do and expect from Finit:
+
+  1. Finit is single threaded and all scripts executed from these two
+     mechanisms are limited to file system operations (early or late
+	 hooks may not have write access!) and standard UNIX programs.
+  2. Thus, it is *not possible* to call `initctl` to query status of
+     services since that calls Finit over the `/run/finit/socket`.
+  3. Confusingly enough, there are some commands to `initctl` that are
+     available; `ls`, `enable`, `disable`, `touch`, `create`, `delete`,
+     and all the `cond` commands.  Because all these are basically just
+     wrappers for manipulating files (again, write access for early/late
+     hooks may not be available.)
+
+Also, similar to the `/etc/rc.local` shell script, make sure that all
+your services and programs either terminate or start in the background
+or you will block Finit.
+
+> **Note:** `runparts` scrips are only read and executed in runlevel S
+> ([bootstrap][]).  See [hook scripts](plugins.md#hooks) for other ways
+> to run scripts at certain points during the complete lifetime of the
+> system.
+
+**Recommendataions:**
+
 It can be beneficial to use `01-name`, `02-othername`, etc., to ensure
 the scripts are started in that order, e.g., if there is a dependency
 order between scripts.  Symlinks to existing daemons can talso be used,
@@ -649,12 +676,6 @@ be called with an extra argument, `start` and `stop`, respectively.
 E.g., `S01foo` will be called as `S01foo start`.  Of course, `S01foo`
 and `K01foo` may be a symlink to to `another/directory/foo`.
 
-Similar to the `/etc/rc.local` shell script, make sure that all your
-services and programs either terminate or start in the background or
-you will block Finit.
-
-> **Note:** only read and executed in runlevel S ([bootstrap][]).
-
 [run-parts(8)]: http://manpages.debian.org/cgi-bin/man.cgi?query=run-parts
 
 

doc/plugins.md

@@ -8,7 +8,8 @@ Hooks & Plugins
   * [Shutdown Hooks](#shutdown-hooks)
 
 Finit can be extended to add general functionality in the form of I/O
-monitors, or hook plugins.
+monitors, or hook plugins.  It is even possible to run scripts at these
+hook points, see below.
 
 The following sections detail existing plugins and hook points.  For
 more information, see the plugins listed below.
@@ -109,7 +110,7 @@ a plain shell script, or program, that does a very small dedicated job
 at the below hook points.
 
 See [Run-parts Scripts](config.md#run-parts-scripts) for details on the
-requirements, and possibilities, of hook scripts.
+requirements, possibilities, and *limitations* of hook scripts.
 
 **Example:**