upstream/bind9
1
0
Fork 0
mirror of https://github.com/isc-projects/bind9.git synced 2026-05-28 04:34:54 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

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

Browse source 
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
(cherry picked from commit bbb24264bb)
This commit is contained in:
Petr Špaček 2022-04-25 12:07:24 +02:00
parent 08feb4c23e
commit 355aebc6df
No known key found for this signature in database
GPG key ID: ABD587CDF06581AE
10 changed files with 111 additions and 74 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
bin/dnssec/dnssec-importkey.rst
View file

@ -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
~~~~~

18
bin/dnssec/dnssec-keyfromlabel.rst
View file

@ -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

19
bin/dnssec/dnssec-keygen.rst
View file

@ -237,10 +237,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-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
@ -262,16 +265,20 @@ explicitly prevent a date from being set, 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

30
bin/dnssec/dnssec-settime.rst
View file

@ -123,15 +123,18 @@ 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 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
@ -156,15 +159,18 @@ 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 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

20
bin/rndc/rndc.rst
View file

@ -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

12
doc/man/dnssec-importkey.1in
View file

@ -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

12
doc/man/dnssec-keyfromlabel.1in
View file

@ -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

12
doc/man/dnssec-keygen.1in
View file

@ -265,13 +265,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
@ -301,13 +301,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

20
doc/man/dnssec-settime.1in
View file

@ -134,19 +134,19 @@ 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 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
@ -173,19 +173,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

23
doc/man/rndc.8in
View file

@ -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