README: Yet more updates

Signed-off-by: Gergely Nagy <algernon@balabit.hu>

1 files changed, 25 insertions, 26 deletions

diff --git a/README.rst b/README.rst
index 00708c3..5d30d59 100644
--- a/README.rst
+++ b/README.rst
@@ -3,41 +3,40 @@ What?
 
 The libumberlog library serves two purposes: it's either a drop-in
 replacement for the ``syslog()`` system call, in which case it turns
-the default syslog messages into CEE-enhanced messages, with a
-CEE-JSON payload, and some automatically discovered fields.
+the default syslog messages into `CEE\-enhanced messages`_, with a
+CEE-JSON payload, and some automatically discovered fields. Or, it can
+be used as a stand-alone library, that provides a ``syslog()``-like
+API, with the ability to add arbitrary key-value pairs to the
+resulting JSON payload.
 
-Or, it can be used as a stand-alone library, that provides a
-``syslog()``-like API, with the ability to add arbitrary key-value
-pairs to the resulting JSON payload.
+.. _CEE\-enhanced messages: #an-example
 
 Why?
 ====
 
-The primary goal of the library is to smoothly introduce people -
-administrators and developers alike - to structured logging. The
-library aims to not only replace the traditional ``syslog()`` system
-call, but to extend it too.
-
-The extensions (unless turned off) provide information not normally
-available via traditional syslog, such as a high-resolution timestamp,
-making them just that more useful.
+The legacy ``syslog()`` interface, while simple, is starting to show
+its age. It was meant to be an interface to construct free-form
+messages, targeted at human readers. However, in this time and age,
+the amount of logs generated by a busy system is, especially by a
+central log server in a larger environment does not lend itself well
+to manual processing.
+
+Instead, we rely more and more on programs to make sense out of the
+logs, to structure the free-form text into something that's easier to
+search and corellate, to filter on, and the existing interface does
+not make this easy. It wasn't written with computer-based
+post-processing in mind.
+
+This library is an attempt to smoothly introduce structured logging to
+administrators and developers alike, by taking a legacy interface,
+``syslog()``, and improving on it a little. Not only by enhancing the
+existing function, for example with a high-resolution timestamp, but
+by providing an extended, but still similar API to developers, to
+allow them to add more structure to their logs.
 
 How?
 ====
 
-All of this is accomplished in a way that allows for
-**LD_PRELOAD**-ing the library, either on a case-by-case basis, or
-system-wide, and seamlessly transform traditional syslog messages,
-without any further work required.
-
-Even better, the library provides new functions, that are modelled
-after the traditional ``syslog()`` API, but provide a few
-improvements, such as the ability to add arbitrary key-value pairs to
-the structured message, and reasonable error handling.
-
-More details
-============
-
 An example
 ----------