Corrections to config and installation, improved troubleshooting and config reference.

refs #1877

doc/configuration.texi

 @node Knot DNS Configuration, Running Knot DNS, Knot DNS Installation, Top
 @chapter Knot DNS Configuration
 
-In this chapter we provide suggested configuration and explain the meaning of individual configuration options.
+In this chapter we provide suggested configurations and explain the meaning of individual configuration options.
 
 @menu
 * Minimal configuration::       
@@ -47,14 +47,15 @@ zones @{
 	
 @end example
 
-Let's now go step by step through this minimal configuration file:
+@page
+Now let's go step by step through this minimal configuration file:
 
 @enumerate 
 
 @item
 In @code{@ref{system}} statement we have configured @code{@ref{storage}}
-directory where Knot DNS will store compiled zone files, it's
-@ref{pidfile} and for slave zone also their journal files.
+directory where Knot DNS will store compiled zone files, 
+PID file and for slave zone also their journal files.
 
 @item
 The @code{@ref{interfaces}} statement defines interfaces where Knot
@@ -64,32 +65,33 @@ on port 53 and second IPv6 called @code{second_int} also listening on
 port 53, which is the default port for the DNS.
 
 @item
-The @code{@ref{log}} statement defines the destination where Knot DNS
-will send it's log messages.  In this example we told Knot DNS to send
-its log messages with priority @code{debug}, @code{warning} and
-@code{notice} into the syslog. If you omit this sections, all levels
-will printed to either @code{stdout} or @code{stderr}, and the levels
+The @code{@ref{log}} statement defines the log facilities for Knot DNS.
+In this example we told Knot DNS to send its log messages with the severities
+@code{debug}, @code{warning} and @code{notice} into the syslog.
+If you omit this sections, all severities will printed to
+either @code{stdout} or @code{stderr}, and the severities
 from the @code{warning} and more serious to syslog. You can find all
 possible combinations in the @ref{log}.
 
 @item
 The @code{@ref{zones}} statement is the one probably most important,
-because it defines the zones Knot DNS will serve.  In its most simple
+because it defines the zones that Knot DNS will serve.  In its most simple
 form you define zone by it's name and defined the filename where Knot
 DNS can find the zone contents. You can turn on more detailed semantic
 checks of zone file in this statement. Refer to @code{@ref{zones List of zone semantic checks}} to see
 which checks are enabled by default and which are optional. If Knot is
 being run as a master server, experimental feature @code{ixfr-from-differences}
-can be enabled to create IXFR changesets from changest made to master zone file.
+can be enabled to create IXFR changesets from changes made to the master zone file.
 See @ref{Controlling running daemon} for more information.
 @end enumerate
 
+@page
 @node Slave configuration
 @section Slave configuration
 
-Knot DNS doesn't strictly differ master and slave zones.
+Knot DNS doesn't strictly differ between master and slave zones.
 The only requirement is to have @code{xfr-in} @code{@ref{zones}} statement set for given zone,
-thus both allowing incoming XFR from that remote and also using it as the
+thus allowing both incoming XFR from that remote and using it as the
 zone master. Also, you can specify relative paths for zone file and in that case,
 zone files will be bootstrapped over AXFR and placed in the storage directory,
 specified in @code{@ref{storage}}.
@@ -107,10 +109,12 @@ zones @{
 @}
 @end example
 
-You can also use TSIG for access control. For this, you need to specify the key
-and assign it to the remote. Supported algorithms for TSIG key are:
-hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, hmac-sha512.
-Secret is written in base64 encoded format. @code{@ref{keys}}
+You can also use TSIG for access control. For this, you need to configure a TSIG key
+and assign it to a remote.
+Supported algorithms for TSIG key are:@*
+@code{hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, hmac-sha512}
+@*
+Key secret is written in a base64 encoded format. @code{@ref{keys}}
 
 @example
 keys @{
@@ -130,11 +134,12 @@ zones @{
 
 As of now it is not possible to associate multiple keys with a remote.
 
+@page
 @node Master configuration
 @section Master configuration
 
 By default, zones are treated as master as long as they don't have the @code{xfr-in} set.
-You can specify which remotes to allow outgoing XFR and NOTIFY @code{@ref{zones}}.
+You can specify which remotes to allow for outgoing XFR and NOTIFY @code{@ref{zones}}.
 
 @example
 remotes @{
@@ -173,7 +178,7 @@ zones @{
 @section Configuring multiple interfaces
 
 Knot DNS support binding to multiple available interfaces in the @code{@ref{interfaces}}.
-You can also use the special addresses for "any address" like @code{0.0.0.0} or @code{[::]}.
+@*You can also use the special addresses for "any address" like @code{0.0.0.0} or @code{[::]}.
 
 @example
 interfaces @{

doc/installation.texi

@@ -12,7 +12,7 @@
 @section Required build environment
 
 GCC at least 4.1 is strictly required for atomic builtins, but 4.2 or newer is recommended.
-Another requirement is _GNU_SOURCE support, otherwise it adapts to the compiler available features.
+Another requirement is @code{_GNU_SOURCE} support, otherwise it adapts to the compiler available features.
 Clang should work, but it is not officially supported.
 
 Knot DNS build system relies on these standard tools:
@@ -47,13 +47,13 @@ libcap-ng, at least 0.6.4 (optional library)
 @end itemize
 
 If libcap-ng library is available, Knot DNS will take advantage of 
-the POSIX 1003.1e capabilites(7) by sandboxing the communication threads.
-Most rights are stripped from the communication threads for security reasons.
+the POSIX 1003.1e capabilites(7) by sandboxing the exposed threads.
+Most rights are stripped from the exposed threads for security reasons.
 
 You can probably find OpenSSL and zlib libraries already included in
 your system or distribution.  If not, zlib resides at
-@url{http://zlib.net/}, and OpenSSL can be found at
-@url{http://www.openssl.org/}.
+@url{http://zlib.net}, and OpenSSL can be found at
+@url{http://www.openssl.org}.
 
 @menu
 * Userspace RCU::               
@@ -70,12 +70,13 @@ live at the same time, and by monitoring the data structure
 accesses to detect grace periods after which memory reclamation
 is possible.  (@url{http://lttng.org/urcu,Userspace RCU})
 
-Binary packages for Debian can be found under liburcu1 for the
-library and liburcu-dev for development files.
+Binary packages for Debian can be found under @code{liburcu1} for the
+library and @code{liburcu-dev} for development files.
 
 Minimum supported version of Userspace RCU library is 0.5.4,
-but we recommend using latest available version.  It is crucial especially on non-Linux systems as we got some compatibility
-patches accepted in later releases of Userspace RCU.
+but we recommend using latest available version.
+It is crucial especially on non-Linux systems, as we got some compatibility
+patches accepted to later releases of Userspace RCU.
 OpenBSD,NetBSD and OS X platforms are supported from version 0.7.0.
 
 @node Installation from the sources
@@ -102,10 +103,13 @@ For all available options run:
 @command{./configure --help}
 @end example
 
-If you have trouble with unknown syscalls under valgrind, disable recvmmsg with
-@command{./configure --enable-recvmmsg=no}.
-Also, it has been reported that some platforms have broken LTO (Link time optimizations)
-support, you can disable that by @command{./configure --enable-lto=no}.
+If you have trouble with unknown syscalls under valgrind, disable recvmmsg by
+adding a parameter @command{--enable-recvmmsg=no} to configure.
+
+Knot DNS has also support for link time optimizations.
+You can enable it by the configure parameter @command{./configure --enable-lto=no}.
+It is however disabled by default as it is known to be broken in some compiler
+versions and may result in an unexpected behavior.
 
 If you want to add debug messages, there are two steps to do that.
 First you have to enable modules you are interested in.
@@ -113,6 +117,7 @@ Available are: @code{server, zones, xfr, packet, dname, rr, ns, hash, compiler}.
 You can combine multiple modules as a comma-separated list.
 Then you can narrow the verbosity of the debugging message by specifying the
 verbosity as @code{brief, verbose, details}.
+
 For example:
 @example
 $ ./configure --enable-debug=server,packet --enable-debuglevel=brief
@@ -247,6 +252,7 @@ Running this sequence of command will ensure that you will
 install the Knot DNS on your system and keep it up-to-date
 in the future, when new version are released.
 
+@page
 @node Installing Knot DNS RPMs on Fedora
 @subsection Installing Knot DNS RPMs on Fedora
 
@@ -263,6 +269,13 @@ gpgcheck=0
 gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-network.cz
 @end example
 
+When you have added a new repository, you can install Knot DNS as a
+regular package.
+
+@example
+$ yum install knot
+@end example
+
 @node Installing Knot DNS from ports on FreeBSD
 @subsection Installing Knot DNS from ports on FreeBSD
 

doc/reference.texi

@@ -108,7 +108,7 @@ system @{
 @subsubsection pidfile
 @vindex pidfile
 
-Specifies custom pidfile location.
+Specifies a custom PID file location.
 
 Default value: @file{knot.pid} in @code{@ref{storage}} directory.
 
@@ -139,9 +139,10 @@ system @{
 
 System @kbd{user} or @kbd{user}.@kbd{group} under which the Knot DNS
 is run after starting and binding to interfaces.
-Only aplicable if your system knows how to handle Linux capabilities (@pxref{Required libraries}).
+Linux capabilities (@pxref{Required libraries}) are employed if supported
+and this configuration option is set.
 
-Default value: root.root
+Default value: @kbd{root.root}
 
 @example
 system @{
@@ -199,7 +200,7 @@ TSIG.  It consists of its @kbd{name}, @kbd{algorithm} and @kbd{key} contents.
 
 Supported algoritms:
 
-@multitable @columnfractions 1
+@itemize
 @item
 hmac-md5
 @item
@@ -212,7 +213,7 @@ hmac-sha256
 hmac-sha384
 @item
 hmac-sha512
-@end multitable
+@end itemize
 
 You need to use bind or ldns utils to generate TSIG keys. Unfortunately, Knot DNS does not have any own generation utilities yet.
 
@@ -310,7 +311,7 @@ Short form:
 @example
 
 interfaces @{
-  my_second_ip 198.51.100.1@@53;
+  my_second_ip @{ address 198.51.100.1@@53; @}
 @}
 	
 @end example
@@ -320,7 +321,7 @@ Short form without port (defaults to 53):
 @example
 
 interfaces @{
-  my_third_ip 203.0.113.1;
+  my_third_ip @{ address 203.0.113.1; @}
 @}
 	
 @end example
@@ -413,9 +414,9 @@ remotes @{
     address 127.0.0.1; 
     port 53531;       
     key key0.server0;
-    via ipv4;       
-    via 82.35.64.59;    # IPv4
-    via [::cafe];       # IPv6
+    via ipv4;             # reference to 'remotes'
+    # via 82.35.64.59;    # direct IPv4
+    # via [::cafe];       # direct IPv6
   @}
 
   # Format 2:
@@ -690,7 +691,9 @@ logging categories to choose from. Each log
 message has its severity and user can configure severities for each
 log destination.
 
-In case of missing log section, @emph{errors} from all categories will be logged to @emph{stderr} and to @emph{syslog}. No other severities shall be logged!
+In case of missing log section, severities from @kbd{warning} and more serious
+will be logged to both @kbd{stderr} and @kbd{syslog}. The @kbd{info} and @kbd{notice}
+severities will be logged to the @kbd{stdout}.
 
 @node log_name
 @subsubsection @kbd{log_name}

doc/requirements.texi

@@ -34,7 +34,7 @@ and CAS (i586 and newer).
 @section Memory requirements
 
 Knot DNS implementation focuses on performance and thus can
-be very demanding for memory.  The rough estimate for memory
+be quite demanding for memory.  The rough estimate for memory
 requirements is 5-7 times of the size of the zone in text
 format.  Again this is only an estimate and you are advised to do
 your own measurements before deploying Knot DNS into production.
@@ -47,7 +47,6 @@ twice the amount of memory for the duration of incoming transfers.
 @section Supported operating system
 
 Knot DNS itself is written in a portable way, but it depends on
-userspace-rcu library, which is the main constraint when it
+several libraries. Namely userspace-rcu, which could be a constraint when it
 comes to the operating system support.  As far as we know the
-Knot DNS and userspace-rcu library can be compiled and run on
-Linux, FreeBSD, OpenBSD, NetBSD and Mac OS X.
+Knot DNS can be compiled and run on Linux, FreeBSD, OpenBSD, NetBSD and Mac OS X.

doc/running.texi

@@ -20,7 +20,7 @@ $ knotc -a -c knot.conf start|reload|restart
 
 The tool @code{knotc} is designed as a front-end for user, making it easier
 to do everything from zone compilation to controlling the server daemon.
-To communicate with the binary, it reads the process PID from the @emph{pidfile} specified in the configuration and sends POSIX signals to it.
+To communicate with the binary, it reads the PID from the @emph{PID file} specified in the configuration @ref{pidfile} and sends POSIX signals to it.
 If you want to control the daemon directly, use @code{SIGINT} to quit the process or @code{SIGHUP} to reload configuration. Signal @code{SIGUSR2} is currently used to refresh slave zones.
 
 @example
@@ -58,7 +58,7 @@ Actions:
  compile   Compile zones (accepts specific zones, see above).
 @end example
 
-But if you want to run Knot DNS daemon directly, you can use @code{knotd} binary
+If you want to run Knot DNS daemon directly, you can use @code{knotd} binary
 to do that. It accepts just configuration file and option to run in background.
 @example
 Usage: knotd [parameters]

doc/troubleshooting.texi

@@ -39,28 +39,33 @@ be very useful as well.
 @node Generating backtrace
 @section Generating backtrace
 
-There are several ways to achieve that, the most common is to run
-the binary in a @code{gdb} debugger or attach to it.
+There are several ways to achieve that, the most common way is to leave core
+dumps and then extract a backtrace from it.
+This doesn't affect any server operation, you just need to make sure
+the OS is configured to generate them.
+
 @example
-$ gdb --args knotd -c knot.conf
-(gdb) run
+$ ulimit -c unlimited # enable unlimited core dump size
 ...
-Program received signal SIGSEGV.
-(gdb) bt
+$ gdb $(which knotd) core.<KNOT_PID>   # start gdb on a core dump
+(gdb) thread apply all bt    # extract backtrace from all threads
 (gdb) q
 @end example
 
-Or attach to the running program.
+If the error is repeatable, you can run the binary in a @code{gdb} debugger
+or attach the debugger to the running process. The backtrace from a running
+process is generally useful when debugging problems like stuck process and similar.
 @example
 $ knotc -c knot.conf start
 $ sudo gdb --pid <KNOT_PID>
 (gdb) continue
 ...
-Program received signal SIGSEGV.
-(gdb) bt
+(gdb) thread apply all bt
 (gdb) q
 @end example
 
+
+
 @node Debug messages
 @section Debug messages