doc: use NOTE and WARNING sphinx construction

48b47784 · Daniel Salzman · 910337ca · 48b47784 · 48b47784 · 48b47784
Commit 48b47784 authored 8 years ago by Daniel Salzman
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -625,21 +625,23 @@ you want to do the former. The configuration comprises only a
 :ref:`mod-dnstap_sink` path parameter, which can be either a file or
 a UNIX socket::

-    mod-dnstap:
-      - id: capture_all
-        sink: /tmp/capture.tap
+   mod-dnstap:
+     - id: capture_all
+       sink: /tmp/capture.tap

-    template:
-      - id: default
-        global-module: mod-dnstap/capture_all
+   template:
+     - id: default
+       global-module: mod-dnstap/capture_all

-Note: to be able to use a Unix socket you need an external program to create it.
-Knot DNS connects to it as a client using the libfstrm library. It operates
-exactly like syslog. See `here
-<https://www.nlnetlabs.nl/bugs-script/show_bug.cgi?id=741#c10>`_ for
-more details.
+.. NOTE::
+   To be able to use a Unix socket you need an external program to create it.
+   Knot DNS connects to it as a client using the libfstrm library. It operates
+   exactly like syslog. See `here
+   <https://www.nlnetlabs.nl/bugs-script/show_bug.cgi?id=741#c10>`_ for
+   more details.

-Note: dnstap log files can also be created or read using ``kdig``.
+.. NOTE::
+   Dnstap log files can also be created or read using ``kdig``.

 .. _dnstap: http://dnstap.info/

@@ -737,8 +739,9 @@ uses of this feature:
 * Local zones (poor man's "views"), rest is forwarded to the public-facing server
 * etc.

-*Note: The module does not alter the query/response as the resolver would,
-and the original transport protocol is kept as well.*
+.. NOTE::
+   The module does not alter the query/response as the resolver would,
+   and the original transport protocol is kept as well.

 The configuration is straightforward and just a single remote server is
 required::
@@ -794,9 +797,9 @@ And we query the nameserver with the following:
   $ kdig IN AAAA ipv6.myrecord.com
     ... returns NOERROR, ::1

-*Note: An entry in the database matches anything at the same or a lower domain
+An entry in the database matches anything at the same or a lower domain
 level, i.e. 'myrecord.com' matches 'a.a.myrecord.com' as well.
-This can be utilized to create catch-all entries.*
+This can be utilized to create catch-all entries.

 You can also add authority information for the entries, provided you create
 SOA + NS records for a name, like so:
@@ -817,7 +820,7 @@ In this case, the responses will:
   the example)*, but not the RR type *(this is to allow the synthesis of
   negative responses)*

-*Note: The SOA record applies only to the 'myrecord.com.', not to any other
+The SOA record applies only to the 'myrecord.com.', not to any other
 record (not even those of its subdomains). From this point of view, all records
 in the database are unrelated and not hierarchical. The idea is to provide
 subtree isolation for each entry.*
@@ -846,7 +849,8 @@ Here is an example on how to use the module:
   ipv6.myrecord.com.      AAAA RDATA=22B  ipv6_query      10.0.0.1
   myrecord.com.           A RDATA=10B     -               -

-  *Note: The database may be modified later on while the server is running.*
+.. NOTE::
+   The database may be modified later on while the server is running.

 * Configure the query module::

@@ -858,8 +862,8 @@ Here is an example on how to use the module:
     - id: default
       global-module: mod-rosedb/default

-  *Note: The module accepts just one parameter – the path to the directory where
-  the database will be stored.*
+The module accepts just one parameter – the path to the directory where
+the database will be stored.

 * Start the server:


--- a/doc/man/knot.conf.5in
+++ b/doc/man/knot.conf.5in
@@ -497,7 +497,12 @@ A template identifier.
 Specifies a path of the persistent timer database. The path can be specified
 as a relative path to the \fIdefault\fP template \fI\%storage\fP\&.
 .sp
-\fICaution:\fP This option is only available in the \fIdefault\fP template.
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+This option is only available in the \fIdefault\fP template.
+.UNINDENT
+.UNINDENT
 .sp
 \fIDefault:\fP \fI\%storage\fP/timers
 .SS global\-module
@@ -505,7 +510,12 @@ as a relative path to the \fIdefault\fP template \fI\%storage\fP\&.
 An ordered list of references to query modules in the form
 \fImodule_name/module_id\fP\&. These modules apply to all queries.
 .sp
-\fICaution:\fP This option is only available in the \fIdefault\fP template.
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+This option is only available in the \fIdefault\fP template.
+.UNINDENT
+.UNINDENT
 .sp
 \fIDefault:\fP not set
 .SH ZONE SECTION
@@ -675,8 +685,13 @@ flush). This is applicable when the zone is updated via IXFR, DDNS or automatic
 DNSSEC signing. In order to disable automatic zonefile synchronization, \-1 value
 can be used (manual zone flush is still possible).
 .sp
-\fICaution:\fP If you are serving large zones with frequent updates where
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+If you are serving large zones with frequent updates where
 the immediate sync with a zone file is not desirable, increase the value.
+.UNINDENT
+.UNINDENT
 .sp
 \fIDefault:\fP 0 (immediate)
 .SS ixfr\-from\-differences
@@ -685,8 +700,13 @@ If enabled, the server creates zone differences from changes you made to the
 zone file upon server reload. This option is relevant only if the server
 is a master server for the zone.
 .sp
-\fICaution:\fP This option has no effect with enabled
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+This option has no effect with enabled
 \fI\%dnssec\-signing\fP\&.
+.UNINDENT
+.UNINDENT
 .sp
 \fIDefault:\fP off
 .SS max\-journal\-size
@@ -698,7 +718,12 @@ Maximum size of the zone journal file.
 .sp
 If enabled, automatic DNSSEC signing for the zone is turned on.
 .sp
-\fICaution:\fP Cannot be enabled on a slave zone.
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+Cannot be enabled on a slave zone.
+.UNINDENT
+.UNINDENT
 .sp
 \fIDefault:\fP off
 .SS kasp\-db
@@ -727,10 +752,15 @@ Possible values:
 \fBunixtime\fP – The serial is set to the current unix time
 .UNINDENT
 .sp
-\fICaution:\fP If your serial was in other than unix time format, be careful
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+If your serial was in other than unix time format, be careful
 with the transition to unix time.  It may happen that the new serial will
 be \(aqlower\(aq than the old one. If this is the case, the transition should be
 done by hand (see RFC 1982).
+.UNINDENT
+.UNINDENT
 .sp
 \fIDefault:\fP increment
 .SS module
@@ -888,8 +918,13 @@ Possible values:
 .sp
 A record owner prefix.
 .sp
-\fICaution:\fP \fIprefix\fP doesn’t allow dots, address parts in the synthetic names are
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The value doesn’t allow dots, address parts in the synthetic names are
 separated with a dash.
+.UNINDENT
+.UNINDENT
 .sp
 \fIDefault:\fP empty
 .SS origin

--- a/doc/migration.rst
+++ b/doc/migration.rst
@@ -26,7 +26,9 @@ server configuration:
   .. NOTE::
      If dynamic updates (DDNS) are enabled for the given zone, you
      might need to freeze the zone before flushing it. That can be done
-      similarly: ``rndc freeze example.com``
+      similarly::
+
+      $ rndc freeze example.com

 2. Copy the fresh zone file into the zones storage directory of Knot
   DNS. Its default location is ``/var/lib/knot``.

--- a/doc/operation.rst
+++ b/doc/operation.rst
@@ -52,9 +52,10 @@ Also the configuration database can be exported into a textual file::

    $ knotc conf-export output.conf

-*Caution:* The import and export commands access the configuration database
-directly, without any interaction with the server. So it is strictly
-recommended to perform these operations when the server is not running.
+.. WARNING::
+   The import and export commands access the configuration database
+   directly, without any interaction with the server. So it is strictly
+   recommended to perform these operations when the server is not running.

 .. _Dynamic configuration:

@@ -67,7 +68,8 @@ the server must be started with a specified configuration database location
 or with the default database initialized. Otherwise all the changes to the
 configuration will be temporary (until the server stop).

-*Note:* The database can be :ref:`imported<Configuration database>` in advance.
+.. NOTE::
+   The database can be :ref:`imported<Configuration database>` in advance.

 Most of the commands get an item name and value parameters. The item name is
 in the form of ``section[identifier].name``. If the item is multivalued,
@@ -88,7 +90,8 @@ to get all section identifiers or to get a specific configuration item::
    $ knotc conf-read 'zone.domain'
    $ knotc conf-read 'zone[example.com].master'

-*Caution:* The following operations don't work on OpenBSD!
+.. WARNING::
+   The following operations don't work on OpenBSD!

 Modifying operations require an active configuration database transaction.
 Just one transaction can be active at a time. Such a transaction then can
@@ -107,10 +110,12 @@ section identifier or to add a value to all identified sections::
    $ knotc conf-set 'zone[example.com]'
    $ knotc conf-set 'zone.slave' 'slave2'

-*Note:* Also the include operation can be performed. A non-absolute file
-location is relative to the server binary path, not to the control binary path!::
+.. NOTE::
+   Also the include operation can be performed. A non-absolute file
+   location is relative to the server binary path, not to the control binary
+   path!::

-    $ knotc conf-set 'include' '/tmp/new_zones.conf'
+      $ knotc conf-set 'include' '/tmp/new_zones.conf'

 To unset the whole configuration or to unset the whole configuration section
 or to unset an identified section or to unset an item or to unset a specific

--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -574,7 +574,8 @@ timer-db
 Specifies a path of the persistent timer database. The path can be specified
 as a relative path to the *default* template :ref:`storage<zone_storage>`.

-*Caution:* This option is only available in the *default* template.
+.. NOTE::
+   This option is only available in the *default* template.

 *Default:* :ref:`storage<zone_storage>`/timers

@@ -586,7 +587,8 @@ global-module
 An ordered list of references to query modules in the form
 *module_name/module_id*. These modules apply to all queries.

-*Caution:* This option is only available in the *default* template.
+.. NOTE::
+   This option is only available in the *default* template.

 *Default:* not set

@@ -771,8 +773,9 @@ flush). This is applicable when the zone is updated via IXFR, DDNS or automatic
 DNSSEC signing. In order to disable automatic zonefile synchronization, -1 value
 can be used (manual zone flush is still possible).

-*Caution:* If you are serving large zones with frequent updates where
-the immediate sync with a zone file is not desirable, increase the value.
+.. NOTE::
+   If you are serving large zones with frequent updates where
+   the immediate sync with a zone file is not desirable, increase the value.

 *Default:* 0 (immediate)

@@ -785,8 +788,9 @@ If enabled, the server creates zone differences from changes you made to the
 zone file upon server reload. This option is relevant only if the server
 is a master server for the zone.

-*Caution:* This option has no effect with enabled
-:ref:`dnssec-signing<zone_dnssec-signing>`.
+.. NOTE::
+   This option has no effect with enabled
+   :ref:`dnssec-signing<zone_dnssec-signing>`.

 *Default:* off

@@ -806,7 +810,8 @@ dnssec-signing

 If enabled, automatic DNSSEC signing for the zone is turned on.

-*Caution:* Cannot be enabled on a slave zone.
+.. NOTE::
+   Cannot be enabled on a slave zone.

 *Default:* off

@@ -844,10 +849,11 @@ Possible values:
 - ``increment`` – The serial is incremented according to serial number arithmetic
 - ``unixtime`` – The serial is set to the current unix time

-*Caution:* If your serial was in other than unix time format, be careful
-with the transition to unix time.  It may happen that the new serial will
-be \'lower\' than the old one. If this is the case, the transition should be
-done by hand (see RFC 1982).
+.. NOTE::
+   If your serial was in other than unix time format, be careful
+   with the transition to unix time.  It may happen that the new serial will
+   be \'lower\' than the old one. If this is the case, the transition should be
+   done by hand (see RFC 1982).

 *Default:* increment

@@ -1037,8 +1043,9 @@ prefix

 A record owner prefix.

-*Caution:* *prefix* doesn’t allow dots, address parts in the synthetic names are
-separated with a dash.
+.. NOTE::
+   The value doesn’t allow dots, address parts in the synthetic names are
+   separated with a dash.

 *Default:* empty


--- a/doc/requirements.rst
+++ b/doc/requirements.rst
@@ -36,10 +36,11 @@ memory demanding. The rough estimate for memory requirements is
 an estimate and you are advised to do your own measurements before
 deploying Knot DNS to production.

-Also note that to ensure uninterrupted serving of the zone, Knot DNS
-employs a Read-Copy-Update mechanism instead of locking and thus
-requires twice the amount of memory for the duration of incoming
-transfers.
+.. NOTE::
+   To ensure uninterrupted serving of the zone, Knot DNS
+   employs the Read-Copy-Update mechanism instead of locking and thus
+   requires twice the amount of memory for the duration of incoming
+   transfers.

 Operating system
 ================