Use unique program + option names for link anchors to support Sphinx 1.8.5

Sphinx "standard domain" provides directive types ".. program::" and
".. option::" to create link anchor for a program name + option combination.
These can be referenced using :ref:`program option` syntax.

The problem is that Sphinx 1.8.5 (e.g. in Ubuntu 18.04) generates
conflicting link targets if a page contains two option directives
starting with the same word, e.g.:

.. program:: dnssec-settime
.. option:: -P date
.. option:: -P ds date

The reason is that option directive consumes only first word as "option
name" (-P) and all the rest is considered "option argument" (date, ds
date). Newer versions of Sphinx (e.g. 4.5.0) handle this by creating
numbered link anchors, but older versions warn and BIND build system
turns the warning into a hard error.

To handle that we use method recommended by Sphinx maintainer:
https://github.com/sphinx-doc/sphinx/issues/10218#issuecomment-1059925508
As a bonus it provides more accurate link anchors for sub-options.

Alternatives considered:
- Replacing standard domain definition of .. option - causes more
  problems, see BIND issue #3294.
- Removing hyperlinks for options - that would be a step back.

Fixes: #3295

diff --git a/bin/dnssec/dnssec-importkey.rst b/bin/dnssec/dnssec-importkey.rst
index b8b70d13fdd555bf058ed7caf7f2d97f2df598c9..d79b61112390081cc6832e075fabe1be8efdd50c 100644 (file)
--- a/bin/dnssec/dnssec-importkey.rst
+++ b/bin/dnssec/dnssec-importkey.rst
@@ -95,10 +95,13 @@ explicitly prevent a date from being set, use ``none`` or ``never``.
    that date, the key is included in the zone but is not used
    to sign it.
 
-.. option:: -P sync date/offset
+   .. program:: dnssec-importkey -P
+   .. option:: sync date/offset
 
-   This option sets the date on which CDS and CDNSKEY records that match this key
-   are to be published to the zone.
+      This option sets the date on which CDS and CDNSKEY records that match this key
+      are to be published to the zone.
+
+.. program:: dnssec-importkey
 
 .. option:: -D date/offset
 
@@ -106,10 +109,14 @@ explicitly prevent a date from being set, use ``none`` or ``never``.
    key is no longer included in the zone. (However, it may remain in the key
    repository.)
 
-.. option:: -D sync date/offset
+   .. program:: dnssec-importkey -D
+   .. option:: sync date/offset
+
+      This option sets the date on which the CDS and CDNSKEY records that match this
+      key are to be deleted.
+
+.. program:: dnssec-importkey
 
-   This option sets the date on which the CDS and CDNSKEY records that match this
-   key are to be deleted.
 
 Files
 ~~~~~

diff --git a/bin/dnssec/dnssec-keyfromlabel.rst b/bin/dnssec/dnssec-keyfromlabel.rst
index c5d79ea612f114dd100345a0ac5882f8890ba36f..1178213b1c3855cbb3bca3cdb293fd6d249394b4 100644 (file)
--- a/bin/dnssec/dnssec-keyfromlabel.rst
+++ b/bin/dnssec/dnssec-keyfromlabel.rst
@@ -194,10 +194,13 @@ explicitly prevent a date from being set, use ``none`` or ``never``.
    to sign it. If not set, and if the :option:`-G` option has not been used, the
    default is the current date.
 
-.. option:: -P sync date/offset
+   .. program:: dnssec-keyfromlabel -P
+   .. option:: sync date/offset
 
-   This option sets the date on which CDS and CDNSKEY records that match this key
-   are to be published to the zone.
+      This option sets the date on which CDS and CDNSKEY records that match this key
+      are to be published to the zone.
+
+.. program:: dnssec-keyfromlabel
 
 .. option:: -A date/offset
 
@@ -223,10 +226,13 @@ explicitly prevent a date from being set, use ``none`` or ``never``.
    key is no longer included in the zone. (However, it may remain in the key
    repository.)
 
-.. option:: -D sync date/offset
+   .. program:: dnssec-keyfromlabel -D
+   .. option:: sync date/offset
 
-   This option sets the date on which the CDS and CDNSKEY records that match this
-   key are to be deleted.
+      This option sets the date on which the CDS and CDNSKEY records that match this
+      key are to be deleted.
+
+.. program:: dnssec-keyfromlabel
 
 .. option:: -i interval
 

diff --git a/bin/dnssec/dnssec-keygen.rst b/bin/dnssec/dnssec-keygen.rst
index 2c1df3b521a88fac6ea34235a3bb8853404247cb..995170ab07aceedde3df1d88edce226f4a267d35 100644 (file)
--- a/bin/dnssec/dnssec-keygen.rst
+++ b/bin/dnssec/dnssec-keygen.rst
@@ -244,10 +244,13 @@ To unset a date, use ``none`` or ``never``.
    to sign it. If not set, and if the :option:`-G` option has not been used, the
    default is the current date.
 
-.. option:: -P sync date/offset
+   .. program:: dnssec-keygen -P
+   .. option:: sync date/offset
 
-   This option sets the date on which CDS and CDNSKEY records that match this key
-   are to be published to the zone.
+      This option sets the date on which CDS and CDNSKEY records that match this key
+      are to be published to the zone.
+
+.. program:: dnssec-keygen
 
 .. option:: -A date/offset
 
@@ -269,16 +272,20 @@ To unset a date, use ``none`` or ``never``.
    key is still included in the zone, but it is not used to
    sign it.
 
+
 .. option:: -D date/offset
 
    This option sets the date on which the key is to be deleted. After that date, the
    key is no longer included in the zone. (However, it may remain in the key
    repository.)
 
-.. option:: -D sync date/offset
+   .. program:: dnssec-keygen -D
+   .. option:: sync date/offset
 
-   This option sets the date on which the CDS and CDNSKEY records that match this
-   key are to be deleted.
+      This option sets the date on which the CDS and CDNSKEY records that match this
+      key are to be deleted.
+
+.. program:: dnssec-keygen
 
 .. option:: -i interval
 

diff --git a/bin/dnssec/dnssec-settime.rst b/bin/dnssec/dnssec-settime.rst
index a9b1283c4ae26350e7e57cc4daa48aebe212abc1..057ceea3aa873c33ed7d653a3d7f37d0a6f3bc3c 100644 (file)
--- a/bin/dnssec/dnssec-settime.rst
+++ b/bin/dnssec/dnssec-settime.rst
@@ -130,15 +130,18 @@ To unset a date, use ``none`` or ``never``.
    that date, the key is included in the zone but is not used
    to sign it.
 
-.. option:: -P ds date/offset
+   .. program:: dnssec-settime -P
+   .. option:: ds date/offset
 
-   This option sets the date on which DS records that match this key have been
-   seen in the parent zone.
+      This option sets the date on which DS records that match this key have been
+      seen in the parent zone.
 
-.. option:: -P sync date/offset
+   .. option:: sync date/offset
 
-   This option sets the date on which CDS and CDNSKEY records that match this key
-   are to be published to the zone.
+      This option sets the date on which CDS and CDNSKEY records that match this key
+      are to be published to the zone.
+
+.. program:: dnssec-settime
 
 .. option:: -A date/offset
 
@@ -163,15 +166,18 @@ To unset a date, use ``none`` or ``never``.
    key is no longer included in the zone. (However, it may remain in the key
    repository.)
 
-.. option:: -D ds date/offset
+   .. program:: dnssec-settime -D
+   .. option:: ds date/offset
 
-   This option sets the date on which the DS records that match this key have
-   been seen removed from the parent zone.
+      This option sets the date on which the DS records that match this key have
+      been seen removed from the parent zone.
 
-.. option:: -D sync date/offset
+   .. option:: sync date/offset
 
-   This option sets the date on which the CDS and CDNSKEY records that match this
-   key are to be deleted.
+      This option sets the date on which the CDS and CDNSKEY records that match this
+      key are to be deleted.
+
+.. program:: dnssec-settime
 
 .. option:: -S predecessor key
 

diff --git a/bin/rndc/rndc.rst b/bin/rndc/rndc.rst
index c5f2b29281c928365ac85b3a3c0402145d674acd..e3faad0819a9d7af078658767133fec25e7759a3 100644 (file)
--- a/bin/rndc/rndc.rst
+++ b/bin/rndc/rndc.rst
@@ -418,9 +418,12 @@ Currently supported commands are:
 
    This command reloads the configuration file and zones.
 
-.. option:: reload zone [class [view]]
+   .. program:: rndc reload
+   .. option:: zone [class [view]]
 
-   This command reloads the given zone.
+   If a zone is specified, this command reloads only the given zone.
+
+.. program:: rndc
 
 .. option:: retransfer zone [class [view]]
 
@@ -587,16 +590,21 @@ Currently supported commands are:
 
    See also :option:`rndc freeze`.
 
-.. option:: trace
+.. option:: trace [level]
 
-   This command increments the server's debugging level by one.
+   If no level is specified, this command increments the server's debugging
+   level by one.
 
-.. option:: trace level
+   .. program:: rndc trace
+   .. option:: level
 
-   This command sets the server's debugging level to an explicit value.
+      If specified, this command sets the server's debugging level to the
+      provided value.
 
    See also :option:`rndc notrace`.
 
+.. program:: rndc
+
 .. option:: tsig-delete keyname [view]
 
    This command deletes a given TKEY-negotiated key from the server. This does not

diff --git a/doc/man/dnssec-importkey.1in b/doc/man/dnssec-importkey.1in
index b751c2bb051868dffadf08149bc8805bb194a79d..c2dde9b269f95fa50217d6dae17aadc07f5fb3ea 100644 (file)
--- a/doc/man/dnssec-importkey.1in
+++ b/doc/man/dnssec-importkey.1in
@@ -105,26 +105,26 @@ explicitly prevent a date from being set, use \fBnone\fP or \fBnever\fP\&.
 This option sets the date on which a key is to be published to the zone. After
 that date, the key is included in the zone but is not used
 to sign it.
-.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
 .TP
-.B \-P sync date/offset
+.B sync date/offset
 This option sets the date on which CDS and CDNSKEY records that match this key
 are to be published to the zone.
 .UNINDENT
+.UNINDENT
 .INDENT 0.0
 .TP
 .B \-D date/offset
 This option sets the date on which the key is to be deleted. After that date, the
 key is no longer included in the zone. (However, it may remain in the key
 repository.)
-.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
 .TP
-.B \-D sync date/offset
+.B sync date/offset
 This option sets the date on which the CDS and CDNSKEY records that match this
 key are to be deleted.
 .UNINDENT
+.UNINDENT
 .SH FILES
 .sp
 A keyfile can be designed by the key identification \fBKnnnn.+aaa+iiiii\fP

diff --git a/doc/man/dnssec-keyfromlabel.1in b/doc/man/dnssec-keyfromlabel.1in
index fb0b2f6891e79e409f4557fec3d3cb35dc3717be..82cd29f206cfe345f8cf28836fa731d41c13623e 100644 (file)
--- a/doc/man/dnssec-keyfromlabel.1in
+++ b/doc/man/dnssec-keyfromlabel.1in
@@ -217,13 +217,13 @@ This option sets the date on which a key is to be published to the zone. After
 that date, the key is included in the zone but is not used
 to sign it. If not set, and if the \fI\%\-G\fP option has not been used, the
 default is the current date.
-.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
 .TP
-.B \-P sync date/offset
+.B sync date/offset
 This option sets the date on which CDS and CDNSKEY records that match this key
 are to be published to the zone.
 .UNINDENT
+.UNINDENT
 .INDENT 0.0
 .TP
 .B \-A date/offset
@@ -251,13 +251,13 @@ sign it.
 This option sets the date on which the key is to be deleted. After that date, the
 key is no longer included in the zone. (However, it may remain in the key
 repository.)
-.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
 .TP
-.B \-D sync date/offset
+.B sync date/offset
 This option sets the date on which the CDS and CDNSKEY records that match this
 key are to be deleted.
 .UNINDENT
+.UNINDENT
 .INDENT 0.0
 .TP
 .B \-i interval

diff --git a/doc/man/dnssec-keygen.1in b/doc/man/dnssec-keygen.1in
index d516f8ee331e7e6c7d923c5d54f7fdea1bacd1d8..672ecbc4bfe4457afacb3ce9e43a6c56e67a114d 100644 (file)
--- a/doc/man/dnssec-keygen.1in
+++ b/doc/man/dnssec-keygen.1in
@@ -272,13 +272,13 @@ This option sets the date on which a key is to be published to the zone. After
 that date, the key is included in the zone but is not used
 to sign it. If not set, and if the \fI\%\-G\fP option has not been used, the
 default is the current date.
-.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
 .TP
-.B \-P sync date/offset
+.B sync date/offset
 This option sets the date on which CDS and CDNSKEY records that match this key
 are to be published to the zone.
 .UNINDENT
+.UNINDENT
 .INDENT 0.0
 .TP
 .B \-A date/offset
@@ -308,13 +308,13 @@ sign it.
 This option sets the date on which the key is to be deleted. After that date, the
 key is no longer included in the zone. (However, it may remain in the key
 repository.)
-.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
 .TP
-.B \-D sync date/offset
+.B sync date/offset
 This option sets the date on which the CDS and CDNSKEY records that match this
 key are to be deleted.
 .UNINDENT
+.UNINDENT
 .INDENT 0.0
 .TP
 .B \-i interval

diff --git a/doc/man/dnssec-settime.1in b/doc/man/dnssec-settime.1in
index 8adf9754588b51dcc2a1421f25a73a4d6f092154..f8dd6386c44981f0a607289f71ae58265cd990b1 100644 (file)
--- a/doc/man/dnssec-settime.1in
+++ b/doc/man/dnssec-settime.1in
@@ -141,19 +141,19 @@ To unset a date, use \fBnone\fP or \fBnever\fP\&.
 This option sets the date on which a key is to be published to the zone. After
 that date, the key is included in the zone but is not used
 to sign it.
-.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
 .TP
-.B \-P ds date/offset
+.B ds date/offset
 This option sets the date on which DS records that match this key have been
 seen in the parent zone.
 .UNINDENT
-.INDENT 0.0
+.INDENT 7.0
 .TP
-.B \-P sync date/offset
+.B sync date/offset
 This option sets the date on which CDS and CDNSKEY records that match this key
 are to be published to the zone.
 .UNINDENT
+.UNINDENT
 .INDENT 0.0
 .TP
 .B \-A date/offset
@@ -180,19 +180,19 @@ sign it.
 This option sets the date on which the key is to be deleted. After that date, the
 key is no longer included in the zone. (However, it may remain in the key
 repository.)
-.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
 .TP
-.B \-D ds date/offset
+.B ds date/offset
 This option sets the date on which the DS records that match this key have
 been seen removed from the parent zone.
 .UNINDENT
-.INDENT 0.0
+.INDENT 7.0
 .TP
-.B \-D sync date/offset
+.B sync date/offset
 This option sets the date on which the CDS and CDNSKEY records that match this
 key are to be deleted.
 .UNINDENT
+.UNINDENT
 .INDENT 0.0
 .TP
 .B \-S predecessor key

diff --git a/doc/man/rndc.8in b/doc/man/rndc.8in
index d47670a89e36af8124e87fbbdba4864908bf4832..29daa0ceeefad98cd46c0f7a4cfe730493be0084 100644 (file)
--- a/doc/man/rndc.8in
+++ b/doc/man/rndc.8in
@@ -455,11 +455,12 @@ This command schedules zone maintenance for the given zone.
 .TP
 .B reload
 This command reloads the configuration file and zones.
-.UNINDENT
-.INDENT 0.0
+.INDENT 7.0
 .TP
-.B reload zone [class [view]]
-This command reloads the given zone.
+.B zone [class [view]]
+.UNINDENT
+.sp
+If a zone is specified, this command reloads only the given zone.
 .UNINDENT
 .INDENT 0.0
 .TP
@@ -641,13 +642,15 @@ See also \fI\%rndc freeze\fP\&.
 .UNINDENT
 .INDENT 0.0
 .TP
-.B trace
-This command increments the server\(aqs debugging level by one.
-.UNINDENT
-.INDENT 0.0
+.B trace [level]
+If no level is specified, this command increments the server\(aqs debugging
+level by one.
+.INDENT 7.0
 .TP
-.B trace level
-This command sets the server\(aqs debugging level to an explicit value.
+.B level
+If specified, this command sets the server\(aqs debugging level to the
+provided value.
+.UNINDENT
 .sp
 See also \fI\%rndc notrace\fP\&.
 .UNINDENT