Update documentation.

Refs #5925

doc/1-about.md

@@ -63,4 +63,3 @@ Please get in touch with the Icinga team at [https://www.icinga.org/ecosystem/].
 ### Archive
 
 Please check the `ChangeLog` file.
-

doc/2.1-setting-up-icinga-2.md

@@ -115,7 +115,7 @@ directive makes sure that all of your own configuration files are included.
 
 ### <a id="constants-conf"></a> constants.conf
 
-The `constants.conf` constants file can be used to define global constants:
+The `constants.conf` configuration file can be used to define global constants:
 
     /**
      * This file defines global constants which can be used in
@@ -142,14 +142,12 @@ The `conf.d/localhost.conf` file contains our first host definition:
     }
 
 This defines the host `localhost`. The `import` keyword is used to import
-the `linux-server` template which takes care of setting up the `ping4` and
-`ping6` services for the host as well as adding the host to the `linux-servers`
-host group. 
+the `linux-server` template which takes care of setting up the host check
+as well as adding the host to the `linux-servers` host group. 
 
-The `vars` attribute can be used to define custom attributes that are available
-for all services which belong to this host. Most of the templates in the Icinga
-Template Library require an `address` custom attribute defined in the `vars`
-dictionary.
+The `vars` attribute can be used to define custom attributes which are available
+for check and notification commands. Most of the templates in the Icinga
+Template Library require an `address` custom attribute.
 
     object Service "icinga" {
       import "generic-service"

doc/2.3-setting-up-ido.md

@@ -212,5 +212,3 @@ You can enable the `ido-pgsql` feature configuration file using `icinga2-enable-
 After enabling the ido-pgsql feature you have to restart Icinga 2:
 
     # /etc/init.d/icinga2 restart
-
-

doc/2.5-setting-up-icinga2-uis.md

@@ -60,7 +60,6 @@ UI installation URL:
 > [commands](#differences-1x-2-commands) and [custom attributes](#differences-1x-2-macros)
 > renders the command expander invalid for example.
 
-
 ### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
 
 Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
@@ -114,8 +113,6 @@ Verify that your Icinga 1.x Web works by browsing to your Web installation URL:
   Debian        | [http://localhost/icinga-web](http://localhost/icinga-web)  | asked during installation
   all others    | [http://localhost/icinga-web](http://localhost/icinga-web)  | root/password
 
-
-
 ### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
 
 Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends.
@@ -130,9 +127,7 @@ further instructions.
 
 ### <a id="additional-visualization"></a> Additional visualization
 
-There are many addons in the wild which are using Icinga 1.x backends and
-are well integrated into user interfaces.
-
-The most famous ones are PNP or inGraph (graphing performance data), graphite, NagVis
-(network maps), etc.
+There are many visualization addons which can be used with Icinga 2.
 
+Some of the more popular ones are PNP, inGraph (graphing performance data),
+Graphite, and NagVis (network maps).

doc/2.7-running-icinga-2.md

@@ -114,5 +114,3 @@ You can disable features using the `icinga2-disable-feature` command:
 > **Note**
 >
 > The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not restart Icinga 2.
-
-

doc/3.01-hosts-and-services.md

@@ -29,8 +29,8 @@ Here is an example of a host object which defines two child services:
       check_command = "http_ip"
     }
 
-The example host `my-server1` creates two services which belong to this host:
-`ping4` and `http`.
+The example creates two services `ping4` and `http` which belong to the
+host `my-server1`.
 
 It also specifies that the host should perform its own check using the `hostalive`
 check command.

doc/3.03-custom-attributes-runtime-macros.md

@@ -1,17 +1,13 @@
 
-## <a id="custom-attributes"></a> Custom Attributes and Runtime Macros
-
-> **Note**
->
-> There is a limited set of special [global constants](#global-constants) which can be re-used and
-> also partly overridden such as `IcingaEnableChecks`. 
+## <a id="custom-attributes"></a> Custom Attributes
 
 ### <a id="runtime-custom-attributes"></a> Using Custom Attributes at Runtime
 
 Custom attributes may be used in command definitions to dynamically change how the command
 is executed.
-Additionally there are Icinga 2 features for example the `PerfDataWriter`
-using the available Custom attributes for output formatting.
+
+Additionally there are Icinga 2 features such as the `PerfDataWriter` type
+which use custom attributes to format their output.
 
 > **Tip**
 >
@@ -21,8 +17,8 @@ using the available Custom attributes for output formatting.
 > **Note**
 >
 > Custom attributes in command definitions or performance data templates are evaluated at
-> runtime when executing a command. These custom attributes cannot be used/accessed inside
-> the configuration objects to add references or similar unless stated otherwise.
+> runtime when executing a command. These custom attributes cannot be used elsewhere
+> (e.g. in other configuration attributes).
 
 Here is an example of a command definition which uses user-defined custom attributes:
 
@@ -219,6 +215,3 @@ The following macros are available in all executed commands:
   icinga.shortdatetime   | Current date and time. Example: `2014-01-03 11:23:08`
   icinga.date            | Current date. Example: `2014-01-03`
   icinga.time            | Current time including timezone information. Example: `11:23:08 +0000`
-
-
-

doc/3.04-notifications.md

@@ -1,22 +1,15 @@
 ## <a id="notifications"></a> Notifications
 
-Notifications on alerts are an integral part of your Icinga 2 monitoring application.
-There are many ways of getting a notification to the actual receiver - Email, XMPP,
-IRC, Twitter, etc. The default method for executing a notification command are
-plugin scripts used for notifications.
-These may either be shell commands to invoke a system call to the `mail` binary
-or your own script fetching available custom attribute values and doing proper formatting
-before sending the notification.
-Other mechanism will require writing the notification string into an api processing
-it there (for example ticket system integration).
+Notifications for service and host problems are an integral part of your
+monitoring setup.
 
-Such notification plugins are available from community users and professionals for
-example on the [MonitoringExchange](http://www.monitoringexchange.org) or the
-[Icinga Wiki](https://wiki.icinga.org). Or you'll write your own and share it. 
-    
-A notification requires one or more users (and/or user groups) who will be notified
-in case. These users must have all custom attributes defined which will be used in
-the `NotificationCommand` on execution.
+There are many ways of sending notifications, e.g. by e-mail, XMPP,
+IRC, Twitter, etc. On its own Icinga 2 does not know how to send notifications.
+Instead it relies on external mechanisms such as shell scripts to notify users.
+
+A notification specification requires one or more users (and/or user groups)
+who will be notified in case of problems. These users must have all custom
+attributes defined which will be used in the `NotificationCommand` on execution.
 
 TODO
 

doc/3.05-using-templates.md

@@ -1,11 +1,7 @@
 ## <a id="using-templates"></a> Using Templates
 
-Templates may be used to apply a set of similar settings to more than one
-object.
-
-For example, rather than manually creating a `ping` service object for each of
-your hosts you can use templates to avoid having to copy & paste parts of your
-configuration:
+Templates may be used to apply a set of identical attributes to more than one
+object:
 
     template Service "generic-service" {
       max_check_attempts = 3
@@ -14,19 +10,21 @@ configuration:
       enable_perfdata = true
     }
 
-    apply Service "ping4" {
+    object Service "ping4" {
       import "generic-service"
+
+      host_name = "localhost"
       check_command = "ping4"
-      assign where host.vars.address
     }
 
-    apply Service "ping6" {
+    object Service "ping6" {
       import "generic-service"
+
+      host_name = "localhost"
       check_command = "ping6"
-      assign where host.vars.address6
     }
 
-In this example both `ping4` and `ping6` services inherit properties from the
+In this example the `ping4` and `ping6` services inherit properties from the
 template `generic-service`.
 
 Objects as well as templates themselves can import an arbitrary number of