From ca0601a883d9f6f80b4bbc61c955b185e37e1501 Mon Sep 17 00:00:00 2001 From: Suzanne Goldlust Date: Fri, 10 Nov 2023 17:01:31 +0000 Subject: [PATCH] Create BIND 9 Style Guide --- BIND-9-Style-Guide.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 BIND-9-Style-Guide.md diff --git a/BIND-9-Style-Guide.md b/BIND-9-Style-Guide.md new file mode 100644 index 0000000..57b1214 --- /dev/null +++ b/BIND-9-Style-Guide.md @@ -0,0 +1,34 @@ +As originally discussed in #3169, this is an attempt at a style guide for the BIND ARM and other related documents. + +### Commands +* Names of statements/blocks/directives in the configuration file should be links to their definition, i.e. not just double backticks: + * `` :namedconf:ref:`options` `` + * `` :ref:`reverse-mapped zone file` `` +* Names of programs should be links to their manual page or some other definition: + * `` :iscman:`named` `` + * `` :iscman:`named-checkconf` `` +* File names have two options: + * If it is a file name that has a manual page, link to the manual or some other definition: + * `` :iscman:`named.conf` `` + * `` :iscman:`rndc.conf` `` + * If it does NOT have a definition in the ARM (e.g. paths like /etc/bind), use `:file:` syntax for standard Sphinx highlighting. That way we can change it at any time and have it consistent: + * `` :file:`/etc/bind/keys/example.com/` `` +* DNS record types (`A`, `AAAA`, etc.) do not need special highlighting. + +In the vast majority of cases, a link can use this simple syntax without needing to think about what type of "object" it is: + +``` +:any:`name` +``` + +and Sphinx should automatically find its definition. + +### Text +* Present tense rather than future (“BIND does X” rather than “BIND will do X”) +* Unix (not UNIX) +* Backward compatibility (not backwards) +* Namespace (not name space) +* Name server (not nameserver) +* Time-to-live +* RRset (not rrset) +* Failover (not fail-over) \ No newline at end of file