Update documentation.

doc/7-migrating-from-icinga-1x.md

@@ -2,60 +2,25 @@
 
 ## Configuration Migration
 
-There are plenty of differences and behavior changes introduced with the new
+The Icinga 2 configuration format introduces plenty of behavioral changes. In
-Icinga 2 configuration format. In order to ease migration from Icinga 1.x,
+order to ease migration from Icinga 1.x,
 Icinga 2 ships its own config conversion script.
 
 ### Configuration Conversion Script
 
 Due to the complexity of the Icinga 1.x configuration format the conversion
-script might not work for all the use cases out there.
+script might not currently work for all use cases.
-
-> **Note**
->
-> While automated conversion will quickly create a working Icinga 2 configuration
-> it does not keep the original organisation structure or any special kind of
-> group or template logic. Please keep that mind when using the script.
 
 The config conversion script provides support for basic Icinga 1.x
 configuration format conversion to native Icinga 2 configuration syntax.
 
 The conversion script tries to preserve your existing template structure and
-adds new templates where appropriate.
+adds new templates where appropriate. However, the original file structure is
-
+not preserved.
-The script will also detect the "attach service to hostgroup and put
-hosts as members" trick from 1.x and convert that into Icinga2's template
-system.
-
-Additionally the old "service with contacts and notification commands" logic
-will be converted into Icinga2's logic with new notification objects,
-allowing to define notifications directly on the service definition then.
-
-Commands will be split by type (Check, Event, Notification) and relinked where
-possible. The host's `check_command` is dropped, and a possible host check service
-looked up, if possible. Otherwise a new service object will be added and linked.
-
-Notifications will be built based on the service->contact relations, and
-escalations will also be merged into notifications, having times begin/end as
-additional attributes. Notification options will be converted into the new Icinga2
-logic.
-
-Dependencies and Parents are resolved into host and service dependencies with
-many objects tricks as well.
-
-Timeperiods will be converted as is, because Icinga2's ITL provides the legacy-timeperiod
-template which supports that format for compatibility reasons.
-
-Custom attributes like custom variables, `*_urls`, etc will be collected into the
-custom dictionary, while possible macros are automatically converted into the macro
-dictionary (freely definable macros in Icinga 2).
 
 The conversion script uses templates from the Icinga Template Library where
 possible.
 
-Regular expressions are not supported, also for the reason that this is optional
-in Icinga 1.x.
-
 > **Note**
 >
 > Please check the provided README file for additional notes and possible
@@ -67,7 +32,7 @@ in Icinga 1.x.
 
 ### Manual Config Conversion
 
-For a long term migration of your configuration you should consider recreating your
+For a long-term migration of your configuration you should consider re-creating
-configuration based on the Icinga 2 proposed way of doing configuration right.
+your configuration based on the Icinga 2 proposed way of doing configuration right.
 
 Please read the next chapter to get an idea about the differences between 1.x and 2.

doc/8-differences-between-icinga-1x-and-2.md

@@ -57,12 +57,11 @@ suffix does not matter as long as it matches the (wildcard) include expression.
 >
 > By convention the `.conf` suffix is used for Icinga 2 configuration files.
 
-
 ## Resource File and Global Macros
 
-Global macros such as for the plugin directory, or hidden passwords/community
+Global macros such as for the plugin directory, usernames and passwords can be
-strings can be set in the `resource.cfg` configuration file in Icinga 1.x. By
+set in the `resource.cfg` configuration file in Icinga 1.x. By convention the
-convention the `USER1` macro is used to define the directory for the plugins.
+`USER1` macro is used to define the directory for the plugins.
 
 Icinga 2 uses a global `IcingaMacros` variable which is set in the
 `conf.d/macros.conf` file:
@@ -79,6 +78,7 @@ Icinga 2 uses a global `IcingaMacros` variable which is set in the
 
 In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`)
 for inline comments.
+
 In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for
 multi-line comments) or starting with two slashes (`//`).
 
@@ -88,7 +88,7 @@ Object names must not contain a colon (`:`). Use the `display_name` attribute
 to specify user-friendly names which should be shown in UIs (supported by
 Icinga 1.x Classic UI and Web).
 
-Object names are not defined using attributes (e.g. `service_description` for
+Object names are not specified using attributes (e.g. `service_description` for
 hosts) like in Icinga 1.x but directly after their type definition.
 
     define service {
@@ -98,7 +98,6 @@ hosts) like in Icinga 1.x but directly after their type definition.
 
     object Service "localhost-ping4" { }
 
-
 ## Templates
 
 In Icinga 1.x templates are identified using `register 0`. Icinga 2 uses the
@@ -209,34 +208,31 @@ be used for host service relation building.
 > It's also possible to modify attributes in the host's service array inherited
 > from the host template. E.g. macros.
 
-
-
-
 ## Users
 
 Contacts have been renamed to Users (same for groups). A user does not
 only provide attributes and macros used for notifications, but is also
 used for authorization checks.
-The revamped notification logic removes the notification commands from
-the contacts (users) too.
 
-StatusDataWriter, IdoMySqlConnection and LivestatusListener will provide
+In Icinga 2 notification commands are not directly associated with users. Instead
-the contact and contactgroups attributes for services for compatibility
+the notification command is specified in `Notification` objects.
+
+The `StatusDataWriter`, `IdoMySqlConnection` and `LivestatusListener` types will
+provide the contact and contactgroups attributes for services for compatibility
 reasons. These values are calculated from all services, their notifications,
 and their users.
 
-
 ## Macros
 
 ### Command Macros
 
 If you have previously used Icinga 1.x you may already be familiar with
-user and argument macros (e.g., USER1 or ARG1). Unlike in Icinga 1.x macros
+user and argument macros (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x macros
 may have arbitrary names and arguments are no longer specified in the
-check_command setting.
+`check_command` setting.
 
-In Icinga 1.x the 2 argument macros will be passed onto the 'check_command'
+In Icinga 1.x argument macros are specified in the `check_command` attribute and
-attribute separated by an exclamation mark (!).
+are separated from the command name using an exclamation mark (`!`).
 
     define command {
         command_name  ping4
@@ -254,9 +250,10 @@ In Icinga 2
 
 ### Environment Macros
 
-The global configuration setting 'enable_environment_macros' does not exist in
+The global configuration setting `enable_environment_macros` does not exist in
 Icinga 2.
-Macros exported into the environment must be set using the 'export_macros' attribute
+
+Macros exported into the environment must be set using the `export_macros` attribute
 in command objects.
 
 
@@ -270,17 +267,20 @@ inherit their state from the service that is specified using the `check` attribu
 
 ### Check Output
 
-Icinga 2 does not make a difference between output (first line) and long_output
+Icinga 2 does not make a difference between `output` (first line) and
-(remaining lines) like in Icinga 1.x. Performance Data is provided separately.
+`long_output` (remaining lines) like in Icinga 1.x. Performance Data is
+provided separately.
 
-StatusDataWriter, IdoMysqlConnection, LivestatusListener split the raw output into
+The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
-output (first line) and long_output (remaining lines) for compatibility reasons.
+split the raw output into `output` (first line) and `long_output` (remaining
+lines) for compatibility reasons.
 
 ### Initial State
 
-Icinga 1.x uses max_service_check_spread to define a timerange where the initial
+Icinga 1.x uses the `max_service_check_spread` setting to specify a timerange
-state checks must have happened. Icinga 2 will use the retry_interval instead
+where the initial state checks must have happened. Icinga 2 will use the
-and check_interval / 5 if not defined.
+`retry_interval` setting instead and `check_interval` divided by 5 if
+`retry_interval` is not defined.
 
 ### Performance Data
 
@@ -288,21 +288,23 @@ There is no host performance data generated in Icinga 2 because there are no
 real host checks anymore. Therefore the PerfDataWriter will only write service
 performance data files.
 
-
 ## Commands
 
-Unlike in Icinga 1.x there are 3 different command types in Icinga 2: CheckCommand,
+Unlike in Icinga 1.x there are 3 different command types in Icinga 2:
-NotificationCommand, EventCommand.
+`CheckCommand`, `NotificationCommand` and EventCommand`.
-Previously it was possible to accidently use e.g. a notification command as event
+
-handler, generating problems with macro resolution and so on.
+For example in Icinga 1.x it is possible to accidently use a notification
-In Icinga 2 those types are separated and will generate an error on configuration
+command as an event handler which might cause problems depending on which
-validation if used in the wrong context.
+macros are used in the notification command.
+
+In Icinga 2 these command types are separated and will generate an error on
+configuration validation if used in the wrong context.
 
 While Icinga 2 still supports the complete command line in command objects, it's
 also possible to encapsulate all arguments into double quotes and passing them as
-array to the 'command_line' attribute i.e. for better readability.
+array to the `command_line` attribute i.e. for better readability.
 
-It's also possible to define default (argument) macros for the command itsself which
+It's also possible to define default (argument) macros for the command itself which
 can be overridden by a service (argument) macro.
 
 
@@ -378,8 +380,8 @@ Escalations in Icinga 1.x require a separated object matching on existing
 objects. Escalations happen between a defined start and end time which is
 calculated from the notification_interval:
 
-start = notification start + (notification_interval * first_notification)
+    start = notification start + (notification_interval * first_notification)
-end = notification start + (notification_interval * last_notification)
+    end = notification start + (notification_interval * last_notification)
 
 In theory first_notification and last_notification can be set to readable
 numbers. In practice users are manipulating those attributes in combination
@@ -394,7 +396,7 @@ In Icinga 1.x it's required to copy the contacts from the service notification
 to the escalation to garantuee the normal notifications once an escalation
 happens.
 That's not necessary with Icinga 2 only requiring an additional notification
-object for the escalation itsself.
+object for the escalation itself.
 
 ### Notification Options
 
@@ -407,13 +409,12 @@ All state and type filter use long names or'd with a pipe together
     notification_state_filter = (StateFilterWarning | StateFilterUnknown | StateFilterCritical),
     notification_type_filter = (NotificationProblem | NotificationRecovery | NotificationFlappingStart | NotificationFlappingEnd | NotificationDowntimeStart | NotificationDowntimeEnd | NotificationDowntimeRemoved)
 
-
 > **Note**
 >
-> Please note that 'NotificationProblem' as type is required for all problem
+> Please note that `NotificationProblem` as type is required for all problem
 > notifications.
 
-Icinga 2 adds more fine granular type filters for acknowledgements, downtime
+Icinga 2 adds more fine-grained type filters for acknowledgements, downtime
 and flapping type (start, end, ...).
 
 > **Note**
@@ -442,7 +443,7 @@ schema with dependencies and parent attributes for compatibility reasons.
 
 ## Flapping
 
-The Icinga 1.x logic on flapping detection uses the last 21 states of a service. This
+The Icinga 1.x flapping detection uses the last 21 states of a service. This
 value is hardcoded and cannot be changed. The algorithm on determining a flapping state
 is
 
@@ -481,7 +482,7 @@ Icinga 1.x IDOUtils was implemented from scratch as Icinga 2 feature which can b
 and enabled on-demand. The Icinga 1.x Livestatus addon is implemented as Icinga 2
 LivestatusListener. Icinga 1.x broker modules used for check distributions are replaced
 by the Icinga 2 cluster and distributed capabilities using the same protocol and security
-mechanisms as the Icinga 2 instance itsself.
+mechanisms as the Icinga 2 instance itself.
 
 Each feature can be created multiple times, i.e. having 3 IDO Mysql databases, 5 Performance
 Data Writers and 2 Livestatus Listeners (one listening on tcp, and one on unix sockets).
@@ -496,4 +497,4 @@ for max age of table entries.
 
 Icinga 2 features require a library to be loaded, and object configuration. In order to simplify
 the process of enabling/disabling these features Icinga 2 ships with two scripts inspired by
-Apache: i2enfeature and i2disfeature.
+Apache: `i2enfeature` and `i2disfeature`.

doc/BLACKLIST

@@ -1,3 +1,6 @@
 seperate
 logic
 magic
+revamp
+and so on
+itsself

doc/mkdoc.sh

@@ -1,12 +1,12 @@
 #!/bin/sh
 cd -- `dirname $0`
 
-for badword in $(cat BLACKLIST); do
+while read badword; do
-	if grep $badword *.md; then
+	if grep -i "$badword" *.md; then
 		echo "Documentation contains banned word."
 		exit 1
 	fi
-done
+done < BLACKLIST
 
 cat <<HTML
 <!DOCTYPE html>