From d13066ca5bb9d57230a8d02fb37b4d29bd072296 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20=C5=A0pa=C4=8Dek?= Date: Thu, 3 Mar 2022 15:32:35 +0100 Subject: [PATCH] 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. (cherry picked from commit 7e7a946d4446e6a91fb994a8c2456289e8bf6e42) --- bin/check/named-checkconf.rst | 1 + bin/check/named-checkzone.rst | 1 + bin/check/named-compilezone.rst | 1 + bin/confgen/ddns-confgen.rst | 1 + bin/confgen/rndc-confgen.rst | 1 + bin/confgen/tsig-keygen.rst | 1 + bin/delv/delv.rst | 1 + bin/dig/dig.rst | 1 + bin/dig/host.rst | 1 + bin/dig/nslookup.rst | 1 + bin/dnssec/dnssec-cds.rst | 1 + bin/dnssec/dnssec-dsfromkey.rst | 1 + bin/dnssec/dnssec-importkey.rst | 1 + bin/dnssec/dnssec-keyfromlabel.rst | 1 + bin/dnssec/dnssec-keygen.rst | 1 + bin/dnssec/dnssec-revoke.rst | 1 + bin/dnssec/dnssec-settime.rst | 1 + bin/dnssec/dnssec-signzone.rst | 1 + bin/dnssec/dnssec-verify.rst | 1 + bin/named/named.conf.rst | 2 ++ bin/named/named.rst | 1 + bin/nsupdate/nsupdate.rst | 1 + bin/plugins/filter-a.rst | 1 + bin/plugins/filter-aaaa.rst | 1 + bin/rndc/rndc.conf.rst | 1 + bin/rndc/rndc.rst | 1 + bin/tools/arpaname.rst | 1 + bin/tools/dnstap-read.rst | 1 + bin/tools/mdig.rst | 1 + bin/tools/named-journalprint.rst | 1 + bin/tools/named-nzd2nzf.rst | 1 + bin/tools/named-rrchecker.rst | 1 + bin/tools/nsec3hash.rst | 1 + doc/arm/conf.py | 3 ++- doc/man/conf.py | 3 +++ 35 files changed, 39 insertions(+), 1 deletion(-) diff --git a/bin/check/named-checkconf.rst b/bin/check/named-checkconf.rst index 99b15d41df..e79debb20f 100644 --- 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: diff --git a/bin/check/named-checkzone.rst b/bin/check/named-checkzone.rst index 25b9585a95..a28b970b1e 100644 --- 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: diff --git a/bin/check/named-compilezone.rst b/bin/check/named-compilezone.rst index 8d947c7407..6e10bbe2d0 100644 --- 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: diff --git a/bin/confgen/ddns-confgen.rst b/bin/confgen/ddns-confgen.rst index 2a290bcc57..7585e8c06f 100644 --- 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: diff --git a/bin/confgen/rndc-confgen.rst b/bin/confgen/rndc-confgen.rst index 5a5925fe77..7b165cb332 100644 --- 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: diff --git a/bin/confgen/tsig-keygen.rst b/bin/confgen/tsig-keygen.rst index 65582e2f08..4c7e8875ad 100644 --- 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: diff --git a/bin/delv/delv.rst b/bin/delv/delv.rst index 466bf5eb70..cb32f9bb5f 100644 --- a/bin/delv/delv.rst +++ b/bin/delv/delv.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: delv .. program:: delv .. _man_delv: diff --git a/bin/dig/dig.rst b/bin/dig/dig.rst index c2b51b1512..bcd9167332 100644 --- a/bin/dig/dig.rst +++ b/bin/dig/dig.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: dig .. program:: dig .. _man_dig: diff --git a/bin/dig/host.rst b/bin/dig/host.rst index 55ca5baec9..4299c874dc 100644 --- a/bin/dig/host.rst +++ b/bin/dig/host.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: host .. program:: host .. _man_host: diff --git a/bin/dig/nslookup.rst b/bin/dig/nslookup.rst index 04cebd6a17..08350194ca 100644 --- a/bin/dig/nslookup.rst +++ b/bin/dig/nslookup.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: nslookup .. program:: nslookup .. _man_nslookup: diff --git a/bin/dnssec/dnssec-cds.rst b/bin/dnssec/dnssec-cds.rst index 31cfbb3b40..3eb5384449 100644 --- 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: diff --git a/bin/dnssec/dnssec-dsfromkey.rst b/bin/dnssec/dnssec-dsfromkey.rst index ca8d54a632..3d5cae2ddc 100644 --- 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: diff --git a/bin/dnssec/dnssec-importkey.rst b/bin/dnssec/dnssec-importkey.rst index e22f06f032..5c939a9fe3 100644 --- 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: diff --git a/bin/dnssec/dnssec-keyfromlabel.rst b/bin/dnssec/dnssec-keyfromlabel.rst index 98d94876b4..87d3e37c94 100644 --- 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: diff --git a/bin/dnssec/dnssec-keygen.rst b/bin/dnssec/dnssec-keygen.rst index 78358294d5..40c54e3fb0 100644 --- 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: diff --git a/bin/dnssec/dnssec-revoke.rst b/bin/dnssec/dnssec-revoke.rst index ef41812ee8..f8f4c99ca2 100644 --- 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: diff --git a/bin/dnssec/dnssec-settime.rst b/bin/dnssec/dnssec-settime.rst index 7ddaeb6b35..56b973ac3e 100644 --- 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: diff --git a/bin/dnssec/dnssec-signzone.rst b/bin/dnssec/dnssec-signzone.rst index 8f1518e708..3ca6944f06 100644 --- 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: diff --git a/bin/dnssec/dnssec-verify.rst b/bin/dnssec/dnssec-verify.rst index ae97feefb0..1b4c3316e1 100644 --- 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: diff --git a/bin/named/named.conf.rst b/bin/named/named.conf.rst index ef63be1184..75a24b6a31 100644 --- 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** --------------------------------------------- diff --git a/bin/named/named.rst b/bin/named/named.rst index 072cb48761..8e7b334a6f 100644 --- a/bin/named/named.rst +++ b/bin/named/named.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: named .. program:: named .. _man_named: diff --git a/bin/nsupdate/nsupdate.rst b/bin/nsupdate/nsupdate.rst index 35c05f1905..dbefcd7521 100644 --- 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: diff --git a/bin/plugins/filter-a.rst b/bin/plugins/filter-a.rst index 31802120f3..4650d6dca7 100644 --- 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 diff --git a/bin/plugins/filter-aaaa.rst b/bin/plugins/filter-aaaa.rst index 8b63f5729b..d2ec514947 100644 --- 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 diff --git a/bin/rndc/rndc.conf.rst b/bin/rndc/rndc.conf.rst index 4b239eafc5..26ef20c12a 100644 --- 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: diff --git a/bin/rndc/rndc.rst b/bin/rndc/rndc.rst index ec96bf963e..21c80eb316 100644 --- a/bin/rndc/rndc.rst +++ b/bin/rndc/rndc.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: rndc .. program:: rndc .. _man_rndc: diff --git a/bin/tools/arpaname.rst b/bin/tools/arpaname.rst index ffe711f732..5ccd4e3264 100644 --- a/bin/tools/arpaname.rst +++ b/bin/tools/arpaname.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: arpaname .. program:: arpaname .. _man_arpaname: diff --git a/bin/tools/dnstap-read.rst b/bin/tools/dnstap-read.rst index 107162beea..db34606add 100644 --- 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: diff --git a/bin/tools/mdig.rst b/bin/tools/mdig.rst index 3bf85f2991..b56e318b62 100644 --- a/bin/tools/mdig.rst +++ b/bin/tools/mdig.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: mdig .. program:: mdig .. _man_mdig: diff --git a/bin/tools/named-journalprint.rst b/bin/tools/named-journalprint.rst index 2fb08f5cac..2d9caab89f 100644 --- 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: diff --git a/bin/tools/named-nzd2nzf.rst b/bin/tools/named-nzd2nzf.rst index aaffc73966..be2c5ee2ea 100644 --- 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: diff --git a/bin/tools/named-rrchecker.rst b/bin/tools/named-rrchecker.rst index 84ab388093..4ff3b27fa9 100644 --- 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: diff --git a/bin/tools/nsec3hash.rst b/bin/tools/nsec3hash.rst index 58550e1b25..2429e317d0 100644 --- a/bin/tools/nsec3hash.rst +++ b/bin/tools/nsec3hash.rst @@ -11,6 +11,7 @@ .. highlight: console +.. iscman:: nsec3hash .. program:: nsec3hash .. _man_nsec3hash: diff --git a/doc/arm/conf.py b/doc/arm/conf.py index 4c3640fae3..947138f535 100644 --- 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. diff --git a/doc/man/conf.py b/doc/man/conf.py index 929155c07b..dd472411dd 100644 --- 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')