Little documentation update

INSTALL

@@ -4,6 +4,11 @@
 
 Build and runtime dependencies:
 
+Tools:
+
+- A C++14 compiler (clang >= 3.4 or gcc >= 4.9 for example)
+- CMake
+- ronn (optional) to build the man page
 
 Libraries:
 
@@ -34,11 +39,6 @@ Libraries:
  Provides the support for a systemd service of Type=notify. This is useful only
  if you are packaging biboumi in a distribution with Systemd.
 
-Tools:
-- A C++14 compiler (clang >= 3.4 or gcc >= 4.9 for example)
-- CMake
-- ronn (optional) to build the man page
-
 
 ==============
   Configure
@@ -67,10 +67,10 @@ or
 
 and respond to the questions when you are prompted to.
 
-You can select the poller used by biboumi, at compile-time, using the POLLER
+You can, for example, select the poller used by biboumi, at compile-time,
-cmake option.  Available values are:
+using the POLLER cmake option.  Available values are:
- POLL: use the standard poll(2). This is the default value because it works on all supported plateforms
+ EPOLL: use the Linux-specific epoll(7). This is the default on Linux.
- EPOLL: use the Linux-specific epoll(7)
+ POLL: use the standard poll(2). This is the default value on all non-Linux platforms.
 
 Example, configure the poller with cmake:
 % cmake . -DPOLLER=EPOLL
@@ -92,3 +92,12 @@ Example, configure the poller with cmake:
 - Install the software system-wide
 
 # make install
+
+
+=============
+     Run
+=============
+
+Run the software using the `biboumi` binary.  Read the documentation (the
+man page biboumi(1) or the “biboumi.1.md” file) for more information on how
+to use biboumi.

README

@@ -17,11 +17,11 @@ The goal is to provide a way to access most of IRC features using any XMPP
 client.  It doesn’t however try to provide a complete mapping of the
 features of both worlds simply because this is not useful and most probably
 impossible.  For example all IRC modes are not all translatable into an XMPP
-features.  Some of theme are (like +m (mute) or +o (operator) modes), but
+features.  Some of them are (like +m (mute) or +o (operator) modes), but
 some others are IRC-specific.  If IRC is the limiting factor (for example
 you cannot have a non-ASCII nickname on IRC) then biboumi doesn’t try to
 work around this issue: it just enforces the rules of the IRC server by
-telling the user that he/she must choose an ASCII nickname only.  An
+telling the user that he/she must choose an ASCII-only nickname.  An
 important goal is to keep the software (and its code) light and simple.
 
 ================

doc/biboumi.1.md

@@ -39,6 +39,7 @@ The configuration file uses a simple format of the form
   The hostname served by the XMPP gateway.  This domain must be configured in
   the XMPP server as an external component.  See the manual for your XMPP
   server for more information.
+  For prosody, see http://prosody.im/doc/components#adding_an_external_component
 
 `password` (mandatory)
 
@@ -76,6 +77,11 @@ log level without having to restart biboumi) by sending SIGUSR1 or SIGUSR2
 USAGE
 -----
 
+Biboumi acts as a server, it should be run as a daemon that lives in the
+background for as long as it is needed.  Note that biboumi does not
+daemonize itself, this task should be done by your init system (SysVinit,
+systemd, upstart).
+
 When started, biboumi connects, without encryption (see *SECURITY*), to the
 local XMPP server on the port `5347` and authenticates with the provided
 password.  Biboumi then serves the configured `hostname`: this means that