rec: Update docs for getting started and compiling.

I'm also making the mention of PowerDNS Recursor more consistent:
no ``the`` and either :program:`PowerDNS Recursor` or :program:`Recursor`.
Use short form if the long form was used already in a section or
it would become tedious to have the long form for another reason.

Fixes #11828, though the recursor.conf man page is not going to
happen anytime soon, as we lack the infrastructure for that and
maintaining both a .rst file and a man page would be a pain.

With released versions, pdns_recursor --config=default helps a bit.
In master pdns_recursor --config=[default|check|diff] was added.

diff --git a/pdns/recursordist/docs/appendices/compiling.rst b/pdns/recursordist/docs/appendices/compiling.rst
index 15ee104aa41bce8712b939194000c3e23f44aef1..73323838cf6f890b1f0009ff8fe2da5dd325570a 100644 (file)
--- a/pdns/recursordist/docs/appendices/compiling.rst
+++ b/pdns/recursordist/docs/appendices/compiling.rst
@@ -1,7 +1,7 @@
-Compiling the PowerDNS Recursor
-===============================
+Compiling :program:`PowerDNS Recursor`
+======================================
 
-As the PowerDNS Recursor is distributed with a configure script, compiling it is a matter of::
+As :program:`PowerDNS Recursor` is distributed with a configure script, compiling it is a matter of::
 
   tar xf pdns-recursor-$VERSION.tar.bz2
   cd pdns-recursor-$VERSION
@@ -26,11 +26,11 @@ These releases are PGP-signed with one of these key-ids:
 Dependencies
 ------------
 
-To build the PowerDNS Recursor, a C++ compiler with support for C++ 2011 is required.
-This means gcc 4.9 and newer and clang 3.5 and newer.
-Furthermore, the Makefiles require GNU make, not BSD make.
+To build :program:`PowerDNS Recursor`, a C++ compiler with support for C++ 2017 is required.
+This means ``gcc 5`` and newer and ``clang 5`` and newer.
+Furthermore, the Makefiles require GNU ``make``, not BSD ``make``.
 
-By default, the PowerDNS recursor requires the following libraries and headers:
+By default, the :program:`Recursor` requires the following libraries and headers:
 
 * `Boost <http://boost.org/>`_ 1.35 or newer
 * `Lua <http://www.lua.org/>`_ 5.1+ or `LuaJit <http://luajit.org/>`_
@@ -45,7 +45,7 @@ These will require additional dependencies
 ed25519 support with libsodium
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The PowerDNS Recursor can link with `libsodium <https://download.libsodium.org/doc/>`_ to support ed25519 (DNSSEC algorithm 15).
+The :program:`Recursor` can link with `libsodium <https://download.libsodium.org/doc/>`_ to support ed25519 (DNSSEC algorithm 15).
 To detect libsodium, use the ``--with-libsodium`` configure option.
 
 .. versionchanged:: 4.2.0
@@ -54,7 +54,7 @@ To detect libsodium, use the ``--with-libsodium`` configure option.
 ed25519 and ed448 support with libdecaf
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-`libdecaf <https://sourceforge.net/projects/ed448goldilocks/>`_ is a library that allows the PowerDNS Recursor to support ed25519 and Ed448 (DNSSEC algorithms 15 and 16).
+`libdecaf <https://sourceforge.net/projects/ed448goldilocks/>`_ is a library that allows :program:`Recursor` to support ed25519 and Ed448 (DNSSEC algorithms 15 and 16).
 To detect libdecaf, use the ``--with-libdecaf`` configure option.
 
 .. versionchanged:: 4.2.0
@@ -63,13 +63,13 @@ To detect libdecaf, use the ``--with-libdecaf`` configure option.
 Protobuf to emit DNS logs
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The PowerDNS Recursor can log DNS query information over :doc:`Protocol Buffers <../lua-config/protobuf>`.
+The :program:`Recursor` can log DNS query information over :doc:`Protocol Buffers <../lua-config/protobuf>`.
 
 This functionality from 4.5.0 and upwards, without needing any external library. Before 4.5.0, installing the  `protobuf <https://developers.google.com/protocol-buffers/>`_ library and compiler is required to enable this functionality. The configure script will automatically detect this and bump the Boost version dependency to 1.42. To disable building this functionality before 4.5.0, use ``--without-protobuf``.
 
-systemd notify support
-^^^^^^^^^^^^^^^^^^^^^^
+``systemd`` notify support
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 During configure, ``configure`` will attempt to detect the availability of `systemd or systemd-daemon <https://freedesktop.org/wiki/Software/systemd/>`_ headers.
-To force the use of systemd (and failing configure if the headers do not exist), use ``--enable-systemd``.
+To force the use of ``systemd`` (and failing configure if the headers do not exist), use ``--enable-systemd``.
 To set the directory where the unit files should be installed, use ``--with-systemd=/path/to/unit/dir``.

diff --git a/pdns/recursordist/docs/getting-started.rst b/pdns/recursordist/docs/getting-started.rst
index c61634befc3056ff187bf8d61775784dc4b32baa..9fb2cbdba08b92724414377b4cd2408594c15d80 100644 (file)
--- a/pdns/recursordist/docs/getting-started.rst
+++ b/pdns/recursordist/docs/getting-started.rst
@@ -1,45 +1,58 @@
 Getting Started
 ===============
-The PowerDNS Recursor can be installed on any modern unix-like system and is available in the software repositories for all major Linux distributions and BSDs.
+:program:`PowerDNS Recursor` can be installed on any modern unix-like system and is available in the software repositories for all major Linux distributions and BSDs.
 
 Installation
 ------------
-The Recursor is available for many platforms, instructions are provided here for several platforms.
+:program:`Recursor` is available for many platforms, instructions are provided here for several platforms.
 
-**note**: PowerDNS itself provides repositories for several Recursor versions for different operating systems.
-Checkout `the repositories <https://repo.powerdns.com>`_ for more information.
+.. note::
+  As distribution provided package repositories are not always up-to-date, PowerDNS itself provides repositories for several :program:`Recursor` versions for different operating systems.
+  Checkout `the repositories <https://repo.powerdns.com>`_ for more information.
 
 Debian-based distributions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
-On Debian, Ubuntu, Linux Mint and related distributions, running ``apt-get install pdns-recursor`` as root will install the Recursor.
+On Debian, Ubuntu, Linux Mint and related distributions, running ``apt-get install pdns-recursor`` as root will install :program:`Recursor`.
 
 Enterprise Linux
 ^^^^^^^^^^^^^^^^
 On Red Hat, CentOS and related distributions, ensure that `EPEL <https://fedoraproject.org/wiki/EPEL>`_ is available.
-To install the PowerDNS Recursor, run ``yum install pdns-recursor`` as root.
+To install :program:`Recursor`, run ``yum install pdns-recursor`` as root.
 
 FreeBSD
 ^^^^^^^
-On FreeBSD the Recursor is available through the `ports system <http://www.freshports.org/dns/powerdns-recursor>`_.
+On FreeBSD :program:`Recursor` is available through the `FreeBSD ports system <https://www.freshports.org/dns/powerdns-recursor>`_.
 Run ``pkg install powerdns-recursor`` as root to install.
 
 To compile yourself from ports, run ``cd /usr/ports/dns/powerdns-recursor/ && make install clean``.
 
-From Source
-^^^^^^^^^^^
-See :doc:`appendices/compiling` for instructions on how to build the PowerDNS Recursor from source.
+OpenBSD
+^^^^^^^
+On OpenBSDd, :program:`Recursor` is available through the `OpenBSD ports system <https://openports.se/net/powerdns_recursor>`_.
+Run ``pkg_add powerdns-recursor`` as root to install.
+
+MacOS
+^^^^^
+On MacOS :program:`Recursor` is available through `brew <https://brew.sh/>`_.
+Run ``brew install pdnsrec`` to install.
+
+Compiling From Source
+^^^^^^^^^^^^^^^^^^^^^
+See :doc:`appendices/compiling` for instructions on how to build :program:`Recursor` from source.
 
-Configuring the Recursor
-------------------------
+Configuring :program:`PowerDNS Recursor`
+----------------------------------------
 The configuration file is called ``recursor.conf`` and is located in the ``SYSCONFDIR`` defined at compile-time.
 This is usually ``/etc/powerdns``, ``/etc/pdns``, ``/etc/pdns-recursor``, ``/usr/local/etc`` or similar.
 
-Run ``pdns_recursor --config=default | grep config-dir`` to find this location on you installation.
+Run ``pdns_recursor --config=default | grep config-dir`` to find this location on your installation.
+Many packages provide a default configuration file that sets :ref:`setting-include-dir`.
+Consider putting local ``.conf`` files into this directory, to make it clear which settings were locally modified.
 
-The PowerDNS Recursor listens on the local loopback interface by default, this can be changed with the :ref:`setting-local-address` setting.
+:program:`Recursor` listens on the local loopback interface by default, this can be changed with the :ref:`setting-local-address` setting.
 
-Now access will need to be granted to the Recursor.
-The :ref:`setting-allow-from` setting lists the subnets that can communicate with the Recursor.
+Now access will need to be granted to the :program:`Recursor`.
+The :ref:`setting-allow-from` setting lists the subnets that can communicate with :program:`Recursor`.
 
 An example configuration is shown below.
 Change this to match the local infrastructure.
@@ -49,15 +62,15 @@ Change this to match the local infrastructure.
     local-address=192.0.2.25, 2001:DB8::1:25
     allow-from=192.0.2.0/24, 2001:DB8::1:/64
 
-After a restart of the Recursor, it will answer queries on 192.0.2.25 and 2001:DB8::1:25, but only for queries with a source address in the 192.0.2.0/24 and 2001:DB8::1:/64 networks.
+After a restart of :program:`Recursor`, it will answer queries on 192.0.2.25 and 2001:DB8::1:25, but only for queries with a source address in the 192.0.2.0/24 and 2001:DB8::1:/64 networks.
 
-The recursor is now ready to be used.
-For more options that can be set in ``recursor.conf`` see the :doc:`list of settings <settings>`.
-Guidance on interaction with the Recursor is documented in :doc:`operating the PowerDNS recursor <running>`.
-If dynamic answer generation is needed or policies need to be applied to queries, the :doc:`scripting manual <lua-scripting/index>` will come in handy.
+:program:`Recursor` is now ready to be used.
+For more options that can be set in ``recursor.conf`` see the :doc:`PowerDNS Recursor Settings<settings>`.
+Guidance on interaction with :program:`Recursor` is documented in :doc:`Operating PowerDNS Recursor<running>`.
+If dynamic answer generation is needed or policies need to be applied to queries, the :doc:`Scripting PowerDNS Recursor <lua-scripting/index>` will come in handy.
 
 Using Ansible
 -------------
-The PowerDNS Recursor can also be installed and configured with `Ansible <https://ansible.com>`_.
+:program:`PowerDNS Recursor` can also be installed and configured with `Ansible <https://ansible.com>`_.
 There is a `role available <https://github.com/PowerDNS/pdns_recursor-ansible/>`_ from the PowerDNS authors.
 

diff --git a/pdns/recursordist/docs/settings.rst b/pdns/recursordist/docs/settings.rst
index 8e6ff17a56267a3d27c6a44b9de4a8ab37edd4c2..8fbb49f57b3db38e10b5ca1231373fc59b7ffeb0 100644 (file)
--- a/pdns/recursordist/docs/settings.rst
+++ b/pdns/recursordist/docs/settings.rst
@@ -1101,7 +1101,7 @@ If the result of a probe is not yet available, the Recursor will contact the aut
 In that case no probe will be scheduled.
 
 
-Note::
+.. note::
   DoT probing is an experimental feature.
   Please test thoroughly to determine if it is suitable in your specific production environment before enabling.