doc: update documentation for hook-scripts and all hook points

Follow-up to b62c975.

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

doc/plugins.md

@@ -35,10 +35,19 @@ For your convenience a set of *optional* plugins are available:
   _Optional plugin._
 
 * *hook-scripts.so*: Trigger the execution of scripts from plugin hook
-  points (see [Hooks](#hooks)).  Scripts are located in
+  points (see [Hooks](#hooks)).  _Optional plugin._
-  `/libexec/finit/hook` by default, this can be build-time customized
+
-  by using the `--with-hook-scripts-path=PATH` argument to
+  This plugin is particularly useful for early boot debugging that needs
-  `configure`.  _Optional plugin._
+  to take place before regular services are available.
+
+  For example, say that you want to enable some kernel tracing before
+  modules are loaded. With hook scripts, you can just drop in a shell
+  script in `/libexec/finit/hook/mount/all/` that will poke the right
+  control files in tracefs.
+
+  Scripts are located in `/libexec/finit/hook` by default, this can be
+  customized at build-time using the `--with-hook-scripts-path=PATH`
+  argument to `configure`.
 
 * *hotplug.so*: Setup and start either udev or mdev hotplug daemon, if
   available.  Enabled by default.
@@ -94,43 +103,52 @@ state, etc.  Available hook points are:
 Hooks
 -----
 
+In the below listings, the first label is the hook point for a C plugin,
+the second is the condition name and hook script path.
+
 ### Bootstrap Hooks
 
-* `HOOK_BANNER`: The very first point at which a plugin can run.
+* `HOOK_BANNER`, `hook/sys/banner`: The very first point at which a
-  Intended to be used as a banner replacement.  Essentially this runs
+  plugin can run.  Intended to be used as a banner replacement.
-  just before entering runlevel S.  Assume nothing is available, so
+  Essentially this runs just before entering runlevel S.  Assume nothing
-  be prepared to use absolute paths, etc.
+  is available, so be prepared to use absolute paths, etc.
 
-* `HOOK_ROOTFS_UP`: When `finit.conf` has been read and `/` has is
+* `HOOK_ROOTFS_UP`, `hook/mount/root`: When `finit.conf` has been read
-  mounted — very early
+  and `/` has is mounted — very early
 
-* `HOOK_BASEFS_UP`: All of `/etc/fstab` is mounted, swap is available
+* `HOOK_MOUNT_ERROR`, `hook/mount/error`: executed if `mount -a` fails
-  and default init signals are setup
 
-* `HOOK_NETWORK_UP`: System bootstrap, runlevel S, has completed and
+* `HOOK_MOUNT_POST`, `hook/mount/post`: always executed after `mount -a`
-  networking is up (`lo` is up and the `network` script has run)
 
-* `HOOK_SVC_UP`: All services in the active runlevel has been launched
+* `HOOK_BASEFS_UP`, `hook/mount/all`: All of `/etc/fstab` is mounted,
+  swap is available and default init signals are setup
 
-* `HOOK_SYSTEM_UP`: All services *and* everything in `/etc/finit.d`
+* `HOOK_NETWORK_UP`, `hook/net/up`: System bootstrap, runlevel S, has
-  has been launched
+  completed and networking is up (`lo` is up and the `network` script
+  has run)
+
+* `HOOK_SVC_UP`, `hook/svc/up`: All services in the active runlevel have
+  been launched
+
+* `HOOK_SYSTEM_UP`, `hook/sys/up`: All services *and* everything in
+  `/etc/finit.d` has been launched
 
 ### Runtime Hooks
 
-* `HOOK_SVC_RECONF`: Called when the user has changed something in the
+* `HOOK_SVC_RECONF`, N/A: Called when the user has changed something in
-  `/etc/finit.d` directory and issued `SIGHUP`.  The hook is called when
+  the `/etc/finit.d` directory and issued `SIGHUP`.  The hook is called
-  all modified/removed services have been stopped.  When the hook has
+  when all modified/removed services have been stopped.  When the hook
-  completed, Finit continues to start all modified and new services.
+  has completed, Finit continues to start all modified and new services.
 
-* `HOOK_RUNLEVEL_CHANGE`: Called when the user has issued a runlevel
+* `HOOK_RUNLEVEL_CHANGE`, N/A: Called when the user has issued a
-  change.  The hook is called when services not matching the new
+  runlevel change.  The hook is called when services not matching the
-  runlevel have been been stopped.  When the hook has completed, Finit
+  new runlevel have been been stopped.  When the hook has completed,
-  continues to start all services in the new runlevel.
+  Finit continues to start all services in the new runlevel.
 
 ### Shutdown Hooks
 
-* `HOOK_SHUTDOWN`: Called at shutdown/reboot, right before all
+* `HOOK_SHUTDOWN`, `hook/sys/shutdown`: Called at shutdown/reboot, right
-  services are sent `SIGTERM`
+  before all services are sent `SIGTERM`
 
 Plugins like `tty.so` extend finit by acting on events, they are called
 I/O plugins and are called from the finit main loop when `poll()`