Introduce new Sphinx role iscman for ISC manual pages

The new directive and role "iscman" allow to tag & reference man pages in our source tree. Essentially it is just namespacing for ISC man pages, but it comes with couple benefits. Differences from .. _man_program label we formerly used: - Does not expand :ref:`man_program` into full text of the page header. - Generates index entry with category "manual page". - Rendering style is closer to ubiquitous to the one produced by ``named`` syntax. Differences from Sphinx built-in :manpage: role: - Supports all builders with support for cross-references. - Generates internal links (unlike :manpage: which generates external URLs). - Checks that target exists withing our source tree.
2025-08-31 22:45:39 +00:00 · 2022-03-03 15:32:35 +01:00
parent ccc6378355
commit 7e7a946d44
35 changed files with 39 additions and 1 deletions
--- a/bin/check/named-checkconf.rst
+++ b/bin/check/named-checkconf.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: named-checkconf
 .. program:: named-checkconf
 .. _man_named-checkconf:

--- a/bin/check/named-checkzone.rst
+++ b/bin/check/named-checkzone.rst
@@ -13,6 +13,7 @@

 .. BEWARE: Do not forget to edit also named-compilezone.rst!

+.. iscman:: named-checkzone
 .. program:: named-checkzone
 .. _man_named-checkzone:

--- a/bin/check/named-compilezone.rst
+++ b/bin/check/named-compilezone.rst
@@ -13,6 +13,7 @@

 .. BEWARE: Do not forget to edit also named-checkzone.rst!

+.. iscman:: named-compilezone
 .. program:: named-compilezone
 .. _man_named-compilezone:

--- a/bin/confgen/ddns-confgen.rst
+++ b/bin/confgen/ddns-confgen.rst
@@ -13,6 +13,7 @@

 .. BEWARE: Do not forget to edit also tsig-keygen.rst!

+.. iscman:: ddns-confgen
 .. program:: ddns-confgen
 .. _man_ddns-confgen:

--- a/bin/confgen/rndc-confgen.rst
+++ b/bin/confgen/rndc-confgen.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: rndc-confgen
 .. program:: rndc-confgen
 .. _man_rndc-confgen:

--- a/bin/confgen/tsig-keygen.rst
+++ b/bin/confgen/tsig-keygen.rst
@@ -13,6 +13,7 @@

 .. BEWARE: Do not forget to edit also ddns-confgen.rst!

+.. iscman:: tsig-keygen
 .. program:: tsig-keygen
 .. _man_tsig-keygen:

--- a/bin/delv/delv.rst
+++ b/bin/delv/delv.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: delv
 .. program:: delv
 .. _man_delv:

--- a/bin/dig/dig.rst
+++ b/bin/dig/dig.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: dig
 .. program:: dig
 .. _man_dig:

--- a/bin/dig/host.rst
+++ b/bin/dig/host.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: host
 .. program:: host
 .. _man_host:

--- a/bin/dig/nslookup.rst
+++ b/bin/dig/nslookup.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: nslookup
 .. program:: nslookup
 .. _man_nslookup:

--- a/bin/dnssec/dnssec-cds.rst
+++ b/bin/dnssec/dnssec-cds.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: dnssec-cds
 .. program:: dnssec-cds
 .. _man_dnssec-cds:

--- a/bin/dnssec/dnssec-dsfromkey.rst
+++ b/bin/dnssec/dnssec-dsfromkey.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: dnssec-dsfromkey
 .. program:: dnssec-dsfromkey
 .. _man_dnssec-dsfromkey:

--- a/bin/dnssec/dnssec-importkey.rst
+++ b/bin/dnssec/dnssec-importkey.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: dnssec-importkey
 .. program:: dnssec-importkey
 .. _man_dnssec-importkey:

--- a/bin/dnssec/dnssec-keyfromlabel.rst
+++ b/bin/dnssec/dnssec-keyfromlabel.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: dnssec-keyfromlabel
 .. program:: dnssec-keyfromlabel
 .. _man_dnssec-keyfromlabel:

--- a/bin/dnssec/dnssec-keygen.rst
+++ b/bin/dnssec/dnssec-keygen.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: dnssec-keygen
 .. program:: dnssec-keygen
 .. _man_dnssec-keygen:

--- a/bin/dnssec/dnssec-revoke.rst
+++ b/bin/dnssec/dnssec-revoke.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: dnssec-revoke
 .. program:: dnssec-revoke
 .. _man_dnssec-revoke:

--- a/bin/dnssec/dnssec-settime.rst
+++ b/bin/dnssec/dnssec-settime.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: dnssec-settime
 .. program:: dnssec-settime
 .. _man_dnssec-settime:

--- a/bin/dnssec/dnssec-signzone.rst
+++ b/bin/dnssec/dnssec-signzone.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: dnssec-signzone
 .. program:: dnssec-signzone
 .. _man_dnssec-signzone:

--- a/bin/dnssec/dnssec-verify.rst
+++ b/bin/dnssec/dnssec-verify.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: dnssec-verify
 .. program:: dnssec-verify
 .. _man_dnssec-verify:

--- a/bin/named/named.conf.rst
+++ b/bin/named/named.conf.rst
@@ -11,6 +11,8 @@

 .. highlight: console

+.. iscman:: named.conf
+
 named.conf - configuration file for **named**
 ---------------------------------------------

--- a/bin/named/named.rst
+++ b/bin/named/named.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: named
 .. program:: named
 .. _man_named:

--- a/bin/nsupdate/nsupdate.rst
+++ b/bin/nsupdate/nsupdate.rst
@@ -9,6 +9,7 @@
 .. See the COPYRIGHT file distributed with this work for additional
 .. information regarding copyright ownership.

+.. iscman:: nsupdate
 .. program:: nsupdate
 .. _man_nsupdate:

--- a/bin/plugins/filter-a.rst
+++ b/bin/plugins/filter-a.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: filter-a
 .. _man_filter-a:

 filter-a.so - filter A in DNS responses when AAAA is present
--- a/bin/plugins/filter-aaaa.rst
+++ b/bin/plugins/filter-aaaa.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: filter-aaaa
 .. _man_filter-aaaa:

 filter-aaaa.so - filter AAAA in DNS responses when A is present
--- a/bin/rndc/rndc.conf.rst
+++ b/bin/rndc/rndc.conf.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: rndc.conf
 .. program:: rndc.conf
 .. _man_rndc.conf:

--- a/bin/rndc/rndc.rst
+++ b/bin/rndc/rndc.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: rndc
 .. program:: rndc
 .. _man_rndc:

--- a/bin/tools/arpaname.rst
+++ b/bin/tools/arpaname.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: arpaname
 .. program:: arpaname
 .. _man_arpaname:

--- a/bin/tools/dnstap-read.rst
+++ b/bin/tools/dnstap-read.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: dnstap-read
 .. program:: dnstap-read
 .. _man_dnstap-read:

--- a/bin/tools/mdig.rst
+++ b/bin/tools/mdig.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: mdig
 .. program:: mdig
 .. _man_mdig:

--- a/bin/tools/named-journalprint.rst
+++ b/bin/tools/named-journalprint.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: named-journalprint
 .. program:: named-journalprint
 .. _man_named-journalprint:

--- a/bin/tools/named-nzd2nzf.rst
+++ b/bin/tools/named-nzd2nzf.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: named-nzd2nzf
 .. program:: named-nzd2nzf
 .. _man_named-nzd2nzf:

--- a/bin/tools/named-rrchecker.rst
+++ b/bin/tools/named-rrchecker.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: named-rrchecker
 .. program:: named-rrchecker
 .. _man_named-rrchecker:

--- a/bin/tools/nsec3hash.rst
+++ b/bin/tools/nsec3hash.rst
@@ -11,6 +11,7 @@

 .. highlight: console

+.. iscman:: nsec3hash
 .. program:: nsec3hash
 .. _man_nsec3hash:

--- a/doc/arm/conf.py
+++ b/doc/arm/conf.py
@@ -81,8 +81,9 @@ class GitLabRefRole(ReferenceRole):
        raise ValueError


-def setup(_):
+def setup(app):
    roles.register_local_role('gl', GitLabRefRole(GITLAB_BASE_URL))
+    app.add_crossref_type('iscman', 'iscman', 'pair: %s; manual page')

 #
 # Configuration file for the Sphinx documentation builder.
--- a/doc/man/conf.py
+++ b/doc/man/conf.py
@@ -116,3 +116,6 @@ rst_epilog = """
 .. |named_pid| replace: ``@runstatedir@/named.pid``
 .. |session_key| replace: ``@runstatedir@/session.key``
 """
+
+def setup(app):
+    app.add_crossref_type('iscman', 'iscman', 'pair: %s; manual page')