Description uplift (#92)

Added some (actually a lot of) missing descriptions to documentation
pages.

Fixes: #25

_data/navigation.yml

@@ -836,13 +836,13 @@ admin-guide-nav:
         url: /admin-guide/120_Parser/014_panos_parser/001_Panos_parser_options
     - title: "Sudo parser"
       url: /admin-guide/120_Parser/015_sudo_parser
+    - title: "MariaDB parser"
+      url: /admin-guide/120_Parser/016_mariadb_parser
     - title: "PostgreSQL parser"
       url: /admin-guide/120_Parser/016_PostgreSQL_csvlog_parser/README
       subnav:
       - title: "PostgreSQL csvlog parser options"
         url: /admin-guide/120_Parser/016_PostgreSQL_csvlog_parser/001_PostgreSQL_parser_options
-    - title: "MariaDB parser"
-      url: /admin-guide/120_Parser/016_mariadb_parser
     - title: "metrics-probe()"
       url: /admin-guide/120_Parser/017_metrics_probe_parser/README
       subnav:

doc/_admin-guide/010_Introduction_to_syslog-ng/001_What_syslog-ng_is_not.md

@@ -1,11 +1,11 @@
 ---
 title: What {{ site.product.short_name }} is not
 id: adm-intro-whatnot
+description: >-
+    The {{ site.product.short_name }} application is not log analysis software. It can filter
+    log messages and select only the ones matching certain criteria. It can
+    even convert the messages and restructure them to a predefined format,
+    or parse the messages and segment them into different fields. But
+    {{ site.product.short_name }} cannot interpret and analyze the meaning behind the messages,
+    or recognize patterns in the occurrence of different messages.
 ---
-
-The {{ site.product.short_name }} application is not log analysis software. It can filter
-log messages and select only the ones matching certain criteria. It can
-even convert the messages and restructure them to a predefined format,
-or parse the messages and segment them into different fields. But
-{{ site.product.short_name }} cannot interpret and analyze the meaning behind the messages,
-or recognize patterns in the occurrence of different messages.

doc/_admin-guide/010_Introduction_to_syslog-ng/003_Who_uses_syslog-ng.md

@@ -1,12 +1,13 @@
 ---
 title: Who uses {{ site.product.short_name }}?
 id: adm-intro-who
+description: >-
+    The {{ site.product.short_name }} application is used worldwide by companies and
+    institutions who collect and manage the logs of several hosts, and want
+    to store them in a centralized, organized way.
 ---
 
-The {{ site.product.short_name }} application is used worldwide by companies and
-institutions who collect and manage the logs of several hosts, and want
-to store them in a centralized, organized way. Using {{ site.product.short_name }} is
-particularly advantageous for:
+Using {{ site.product.short_name }} is particularly advantageous for:
 
 - Internet Service Providers
 

doc/_admin-guide/010_Introduction_to_syslog-ng/004_Supported_platforms.md

@@ -1,14 +1,14 @@
 ---
 title: Supported platforms
 id: adm-intro-supp
+description: >-
+    The {{ site.product.short_name }} application is highly
+    portable and is known to run on a wide range of hardware architectures
+    (x86, x86_64, SUN Sparc, PowerPC 32 and 64, Alpha, ARM64) and operating
+    systems, including Linux, BSD, Solaris, IBM AIX, HP-UX, macOS,
+    Cygwin, and others.
 ---
 
-The {{ site.product.short_name }} application is highly
-portable and is known to run on a wide range of hardware architectures
-(x86, x86_64, SUN Sparc, PowerPC 32 and 64, Alpha, ARM64) and operating
-systems, including Linux, BSD, Solaris, IBM AIX, HP-UX, macOS,
-Cygwin, and others.
-
 - The [[source code|gh-syslog-ng]] of {{ site.product.name }} is released under the GPLv2 license
 
 - For the available binary installation packages, see {{ site.product.name }} installation packages.

doc/_admin-guide/010_Introduction_to_syslog-ng/README.md

@@ -1,8 +1,8 @@
 ---
 title: Introduction to syslog-ng
 id: adm-intro
+description: >-
+    This chapter introduces the {{ site.product.name }} application in
+    a non-technical manner, discussing how and why is it useful, and the
+    benefits it offers to an existing IT infrastructure.
 ---
-
-This chapter introduces the {{ site.product.name }} application in
-a non-technical manner, discussing how and why is it useful, and the
-benefits it offers to an existing IT infrastructure.

doc/_admin-guide/020_The_concepts_of_syslog-ng/003_Global_objects.md

@@ -1,6 +1,8 @@
 ---
 title: Global objects
 id: adm-conc-glob
+description: >-
+    This section explains some basic terminology used in {{ site.product.short_name }}. 
 ---
 
 ## Source driver

doc/_admin-guide/030_Installing_syslog-ng/001_Compiling_options.md

@@ -1,6 +1,8 @@
 ---
 title: Compiling options of {{ site.product.short_name }}
 id: adm-inst-compopt
+description: >-
+    This chapter describes the compiling options of {{ site.product.short_name }}.
 ---
 
 When compiling {{ site.product.short_name }} from source, you can use the following

doc/_admin-guide/030_Installing_syslog-ng/002_Uninstalling_syslog-ng.md

@@ -1,6 +1,8 @@
 ---
 title: Uninstalling {{ site.product.short_name }}
 id: adm-inst-uninst
+description: >-
+    This chapter gives you instructions about the uninstallation of {{ site.product.short_name }}.
 ---
 
 If you need to uninstall {{ site.product.short_name }} for some reason, you have the

doc/_admin-guide/030_Installing_syslog-ng/003_Configuring_MSSQL_server.md

@@ -1,14 +1,16 @@
 ---
-title: Configuring Microsoft SQL Server to accept logs from syslog-ng
+title: Configuring Microsoft SQL Server to accept logs from {{ site.product.short_name }}
 short_title: Configuring MSSQL Server
 id: adm-inst-mssql
+description: >-
+    This chapter explains how to configure an MSSQL Server to work with {{ site.product.short_name }}.
 ---
 
 {% assign crumb = page.url | split: '/' %}
 {% assign img_folder = crumb[-2] | prepend: '/assets/images/admin-guide/'%}
 
 Complete the following steps to configure your Microsoft SQL Server to
-enable remote logins and accept log messages from syslog-ng.
+enable remote logins and accept log messages from {{ site.product.short_name }}.
 
 1. Start the SQL Server Management Studio application. Select
     **Start \> Programs \> Microsoft SQL Server 2005 \> SQL Server

doc/_admin-guide/040_Quick-start_guide/000_Configuring_syslog-ng_on_client_hosts.md

@@ -2,9 +2,11 @@
 title: Configuring {{ site.product.short_name }} on client hosts
 id: adm-qs-client-conf
 description: >-
-    To configure {{ site.product.short_name }} on a client host, complete the following steps.
+    This section explains how to configure {{ site.product.short_name }} on a client host.
 ---
 
+To configure {{ site.product.short_name }} on a client host, complete the following steps.
+
 ## Steps
 
 1. Install the {{ site.product.short_name }} application on the host. For details

doc/_admin-guide/040_Quick-start_guide/001_Configuring_syslog-ng_on_server_hosts.md

@@ -2,9 +2,11 @@
 title: Configuring {{ site.product.short_name }} on server hosts
 id: adm-qs-server-conf
 description: >-
-    To configure {{ site.product.short_name }} on a server host, complete the following steps.
+    This section explains how to configure {{ site.product.short_name }} on a server host.
 ---
 
+To configure {{ site.product.short_name }} on a server host, complete the following steps.
+
 ## Steps
 
 1. Install the {{ site.product.short_name }} application on the host. For details

doc/_admin-guide/040_Quick-start_guide/002_Configuring_syslog-ng_relays/README.md

@@ -1,6 +1,81 @@
 ---
 title: Configuring {{ site.product.short_name }} relays
-id: adm-qs-conf
+id: adm-qs-relay-conf
 description: >-
     This section describes how to configure {{ site.product.short_name }} as a relay.
 ---
+
+To configure {{ site.product.short_name }} as a relay, complete the following steps:
+
+1. Install the {{ site.product.short_name }} application on the host. For details on
+    installing {{ site.product.short_name }} on specific operating systems, see
+    Installing syslog-ng.
+2. Configure the network sources that collect the log messages sent by
+    the clients.
+
+3. Create a network destination that points to the {{ site.product.short_name }} server.
+
+4. Create a log statement connecting the network sources to the
+    {{ site.product.short_name }} server.
+
+5. Configure the local sources that collect the log messages of the
+    relay host.
+
+6. Create a log statement connecting the local sources to the syslog-ng
+    server.
+
+7. Enable the keep-hostname() and disable the chain-hostnames()
+    options. (For details on how these options work, see
+    chain-hostnames()
+
+    **NOTE:** It is recommended to use these options on your {{ site.product.short_name }}
+    server as well.
+    {: .notice--info}
+
+8. Set filters and options (for example, TLS encryption) as necessary.
+
+    **NOTE:** By default, the {{ site.product.short_name }} server will treat the relayed
+    messages as if they were created by the relay host, not the host
+    that originally sent them to the relay. In order to use the original
+    hostname on the {{ site.product.short_name }} server, use the **keep-hostname(yes)**
+    option both on the {{ site.product.short_name }} relay and the {{ site.product.short_name }} server. This
+    option can be set individually for every source if needed.
+    {: .notice--info}
+
+    If you are relaying log messages and want to resolve IP addresses to
+    hostnames, configure the first relay to do the name resolution.
+
+    Example: A simple configuration for relays
+
+    The following is a simple configuration file that collects local and
+    incoming log messages and forwards them to a logserver using the
+    IETF-syslog protocol.
+
+    ```config
+    @version: 3.38
+    @include "scl.conf"
+
+    options {
+        time-reap(30);
+        mark-freq(10);
+        keep-hostname(yes);
+        chain-hostnames(no);
+    };
+
+    source s_local {
+        system(); internal();
+    };
+
+    source s_network {
+        syslog(transport(tcp));
+    };
+
+    destination d_syslog_tcp {
+        syslog("192.168.1.5" transport("tcp") port(2010));
+    };
+
+    log {
+        source(s_local); source(s_network);
+        destination(d_syslog_tcp);
+    };
+    ```

doc/_admin-guide/050_The_configuration_file/000_Location_of_the_config_file.md

@@ -2,10 +2,12 @@
 title: Location of the {{ site.product.short_name }} configuration file
 id: adm-conf-loc
 description: >-
-    To configure {{ site.product.short_name }}, edit the syslog-ng.conf file with any
-    regular text editor application.
+    This section describes the location of {{ site.product.short_name }} configuration file.
 ---
 
+To configure {{ site.product.short_name }}, edit the syslog-ng.conf file with any
+regular text editor application.
+
 The location of the configuration file depends on how you installed
 {{ site.product.short_name }}. Native packages of a platform (like the ones downloaded
 from Linux repositories) typically place the configuration file under

doc/_admin-guide/050_The_configuration_file/001_Configuration_syntax.md

@@ -1,6 +1,9 @@
 ---
 title: The configuration syntax in detail
 id: adm-conf-syn
+description: >-
+    This chapter describes the configuration syntax of {{ site.product.short_name }}, with configuration
+    examples.
 ---
 
 Every {{ site.product.short_name }} configuration file must begin with a line containing the

doc/_admin-guide/050_The_configuration_file/002_Syntax_notes.md

@@ -1,6 +1,9 @@
 ---
 title: Notes about the configuration syntax
 id: adm-conf-syn-notes
+description: >-
+    Things to consider when editing a {{ site.product.short_name }}
+    configuration file. 
 ---
 
 When you are editing the {{ site.product.short_name }} configuration file, note the

doc/_admin-guide/050_The_configuration_file/006_Modules_in_syslog-ng/000_Loading_modules.md

@@ -2,10 +2,12 @@
 title: Loading modules
 id: adm-mod-loading
 description: >-
-    The {{ site.product.name }} application loads every available
-    module during startup.
+    This chapter describes how modules are loaded in {{ site.product.name }}.
 ---
 
+The {{ site.product.name }} application loads every available
+module during startup.
+
 To load a module that is not loaded automatically, include the following
 statement in the {{ site.product.short_name }} configuration file:
 

doc/_admin-guide/050_The_configuration_file/README.md

@@ -2,4 +2,6 @@
 title: The {{ site.product.short_name }} configuration file
 short_title: The configuration file
 id: adm-conf-file
+description: >-
+    This chapter describes the configuration file of {{ site.product.short_name }}, with location, syntax, examples. 
 ---

doc/_admin-guide/060_Sources/000_Default-network-drivers/000_Default-network-drivers_options.md

@@ -2,9 +2,11 @@
 title: default-network-drivers() source options
 max_conn_default: 10
 id: adm-src-def-netw-opt
+description: >-
+    This section describes the options of the default-network-drivers() source in {{ site.product.short_name }}.
 ---
 
-The systemd-journal() driver has the following options.
+The default-network-drivers() source has the following options.
 
 {% include doc/admin-guide/options/ca-dir.md %}