mirror of
https://github.com/isc-projects/bind9.git
synced 2026-03-15 15:12:56 -04:00
355aebc6df
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
|
||
|---|---|---|
| .. | ||
| .gitignore | ||
| dnssec-cds.c | ||
| dnssec-cds.rst | ||
| dnssec-dsfromkey.c | ||
| dnssec-dsfromkey.rst | ||
| dnssec-importkey.c | ||
| dnssec-importkey.rst | ||
| dnssec-keyfromlabel.c | ||
| dnssec-keyfromlabel.rst | ||
| dnssec-keygen.c | ||
| dnssec-keygen.rst | ||
| dnssec-revoke.c | ||
| dnssec-revoke.rst | ||
| dnssec-settime.c | ||
| dnssec-settime.rst | ||
| dnssec-signzone.c | ||
| dnssec-signzone.rst | ||
| dnssec-verify.c | ||
| dnssec-verify.rst | ||
| dnssectool.c | ||
| dnssectool.h | ||
| Makefile.am | ||