README: Further updates, clarification and additions on, e.g., running finit.

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

README.rst

@@ -4,19 +4,17 @@
 
 Welcome to finit!
 
-This is a heavily extended version of the original /sbin/init replacement
+This is an extremely fast /sbin/init replacement with focus on small
-finit_.  The original was a reimplementation of the EeePC "fastinit" daemon
+embedded GNU/Linux systems.  Based on Claudio Matsuoka's original finit_
-based on its system calls with gaps filled with frog DNA.
+with I/O, service and hook plugin extensions.  The original was a
+reimplementation of the EeePC fastinit_ daemon based on its system
+calls with gaps filled with frog DNA.
 
-Focus of this extended version is on small embedded GNU/Linux systems and
+In the world of finit we write C plugins that hook into and extend the
-headless miniature servers with a need for extremely fast boot.  In such
+``main()`` loop of ``/sbin/init``, this is what gives the system its raw
-environments configurations rarely change and setup is rather static and
+performance and the user full control.
-straight forward.
 
-In the world of finit we write C "scripts" to boot our system, this is what
+If you chose finit you know what you want, a fast no hassles boot!
-gives the system its raw performance and the user full control.
-
-If you chose finit you know what you want, a fast boot with no hassle.
 
 
 Features
@@ -41,33 +39,35 @@ plugins with either hooks or I/O demands.
 /etc/finit.conf
 ---------------
 
-Contrary to most script based init alternatives (SysV init_, upstart_, OpenRC_
+Contrary to most script based init alternatives (`SysV init`_, upstart_,
-and the likes) finit reads its configuration from /etc/finit.conf, see the
+OpenRC_ and the likes) finit instead reads its configuration from
-source code for available options.
+``/etc/finit.conf``, see the source code for available options.
 
-When running ''make install'' no default ''/etc/finit.conf'' will be
+When running ``make install`` no default ``/etc/finit.conf`` will be
 provided since the system requirements differ too much.  Try out the
-Debian 6.0 example /usr/share/doc/finit/finit.conf configuration that is
+Debian 6.0 example ``/usr/share/doc/finit/finit.conf`` configuration
-capable of service monitoring SSH, sysklogd, gdm and a console getty!
+that is capable of service monitoring SSH, sysklogd, gdm and a console
+getty!
 
 
 /etc/finit.d
 ------------
 
-At the end of the boot, when networking and all services are up, finit calls
+At the end of the boot, when networking and all services are up, finit
-its built-in run-parts(8) on the /etc/finit.d/ directory, akin to how the
+calls its built-in run-parts(8) on the ``/etc/finit.d/`` directory, akin
-/ec/rc.local file works in most other inits, only finit runs a directory of
+to how the ``/ec/rc.local`` file works in most other inits, only finit
-scripts.  This replaces the earlier /usr/sbin/services.sh support of the
+runs a directory of scripts.  This replaces the earlier
-original finit_.
+``/usr/sbin/services.sh`` support of the original finit_.
 
 
 Rebooting and Halting
 ---------------------
 
 Finit handles SIGUSR1 and SIGUSR2 for reboot and halt, and listens to
-/dev/initctl so standard Linux reboot and halt commands should also
+``/dev/initctl`` so standard Linux reboot and halt commands should also
 work.
 
+
 Building
 --------
 
@@ -99,16 +99,16 @@ what is built and where resulting binaries are installed.
    Standard LIBLIBS are inherited from the build enviornmant.
 
 **prefix=**
-   Base prefix path for all files, except ''sbinbdir'' and ''sysconfdir''.
+   Base prefix path for all files, except ``sbinbdir`` and ``sysconfdir``.
-   Used in concert with the ''DESTDIR'' variable. Defaults to /usr
+   Used in concert with the ``DESTDIR`` variable. Defaults to ``/usr``
 
 **sbindir=**
    Path to where resulting binaries should install to. Used in concert
-   with the ''DESTDIR'' variable. Defaults to /sbin
+   with the ``DESTDIR`` variable. Defaults to ``/sbin``
 
 **sysconfdir=**
    Path to where finit configuration files should install to. Used in
-   concert with the ''DESTDIR'' variable.  Defaults to /etc, but is
+   concert with the ``DESTDIR`` variable.  Defaults to ``/etc``, but is
    currently unused.
 
 **PLUGINS=**
@@ -116,12 +116,12 @@ what is built and where resulting binaries are installed.
 
 **plugindir=**
    Absolute path to where finit should look for dynamically loadable plugins
-   at runtime. At installation prepended by ''DESTDIR'' and ''prefix''.
+   at runtime. At installation prepended by ``DESTDIR`` and ``prefix``.
-   Defaults to /lib/finit/plugins
+   Defaults to ``/lib/finit/plugins``
 
 **DESTDIR=**
    Used by packagers and distributions when building a relocatable
-   bundle of files. Alwawys prepended to the ''prefix'' destination
+   bundle of files. Alwawys prepended to the ``prefix`` destination
    directory.
 
 **Example**::
@@ -147,23 +147,40 @@ what is built and where resulting binaries are installed.
     INSTALL /tmp/finit/dst/lib/finit/plugins/hwclock.so
   make: Leaving directory `/home/troglobit/finit-1.3'
 
-In this example the finit-1.3.tar.xz archive is unpacked to the user's
+In this example the `finit-1.3.tar.xz`_ archive is unpacked to the user's
 home directory, built and installed to a temporary staging directory.
-The enviroment variables ''prefix'', ''DESTDIR'' and ''PLUGINS'' are all
+The enviroment variables ``prefix``, ``DESTDIR`` and ``PLUGINS`` are all
 changed to suit this particular build.
 
 
+Running
+-------
+
+The default install does not setup finit as the system default
+``/sbin/init``, neither does it setup an initial ``/etc/finit.conf``.
+
+It is assumed that users of finit are competent enough to either setup
+finit as their default ``/sbin/init`` or alter their respective Grub,
+LOADLIN, LILO, U-Boot/Barebox or RedBoot boot loader configuration to
+give the kernel the following extra command line::
+
+  init=/sbin/finit
+
+
 Debugging
 ---------
 
-Add finit_debug, or --debug, to the kernel command line to enable trace
+Add ``finit_debug``, or ``--debug``, to the kernel command line to
-messages.  A console getty is always started, see the file finit.h for
+enable trace messages.  A console getty is always started, see the file
-more useful comile-time tweaks.
+``finit.h`` for more useful comile-time tweaks::
+
+  init=/sbin/finit --debug
+
 
 Contact
 -------
 
-Finit is maintained collaborativly at https://github.com/troglobit/finit —
+Finit is maintained collaborativly at http://github.com/troglobit/finit —
 please file a bug report, clone it, or send pull requests for bug fixes and
 proposed extensions, or become a co-maintainer by contacting the main author.
 
@@ -171,7 +188,8 @@ Regards
  /Joachim Nilsson <troglobit@gmail.com>
 
 .. _finit: http://helllabs.org/finit/
-.. _init: http://savannah.nongnu.org/projects/sysvinit
+.. _fastinit: http://wiki.eeeuser.com/boot_process:the_boot_process
+.. _`SysV init`: http://savannah.nongnu.org/projects/sysvinit
 .. _upstart: http://upstart.ubuntu.com/
 .. _openrc: http://www.gentoo.org/proj/en/base/openrc/
-
+.. _`finit-1.3.tar.xz`: http://github.com/downloads/troglobit/finit/finit-1.3.tar.xz