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<ipv4_reverse>`
- 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/`
- If it is a file name that has a manual page, link to the manual or some other definition:
- 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)
Choules comments
Regarding "namespace" versus "name space". Many places, including IETF documents, RFCs and popular, trusted websites (or is it web sites? ;) ) use both/either almost interchangeably. RFC 1034, for example, uses "namespace" once but "name space" 30 times. However, in other IETF documents (of which the RFCs are a set) "namespace" appears more often. So basically, go figure! I'd say either could be used, but be consistent. My personal choice would be namespace, but then I'm lazy and as it saves a whole character... ;)
Regarding "nameserver" versus "name server". Again, both are used, though "name server" might have the edge. Personally I'd go with nameserver.
Regarding "time-to-live" I'm a definite 'no' on hyphens. It's "time to live".
That's all, for now.