[src/trunk]: src/usr.sbin/bind/named Use Sq, Dq; sort sections; new sentence,...

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/b954987a8963
branches:  trunk
changeset: 566757:b954987a8963
user:      wiz <wiz%NetBSD.org@localhost>
date:      Thu May 20 01:01:33 2004 +0000

description:
Use Sq, Dq; sort sections; new sentence, new line;
refer to DNSSec RFCs in SEE ALSO (since they are mentioned in the text;
XXX: text should be updated to refer to latest one only);
XXX: refers to BIND 8.

diffstat:

 usr.sbin/bind/named/named.conf.5 |  710 ++++++++++++++++++++++++--------------
 1 files changed, 437 insertions(+), 273 deletions(-)

diffs (truncated from 1544 to 300 lines):

diff -r 22a9ccebbb8d -r b954987a8963 usr.sbin/bind/named/named.conf.5
--- a/usr.sbin/bind/named/named.conf.5  Thu May 20 00:56:12 2004 +0000
+++ b/usr.sbin/bind/named/named.conf.5  Thu May 20 01:01:33 2004 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: named.conf.5,v 1.2 2004/05/20 00:26:19 wiz Exp $
+.\"     $NetBSD: named.conf.5,v 1.3 2004/05/20 01:01:33 wiz Exp $
 .\"
 .\" Copyright (c) 1999-2000 by Internet Software Consortium
 .\"
@@ -22,16 +22,19 @@
 .Nd configuration file for
 .Xr named 8
 .Sh OVERVIEW
-BIND 8 is much more configurable than previous release of BIND.  There
-are entirely new areas of configuration, such as access control lists
-and categorized logging.  Many options that previously applied to all
-zones can now be used selectively.  These features, plus a
-consideration of future configuration needs led to the creation of a
-new configuration file format.
+BIND 8 is much more configurable than previous release of BIND.
+There are entirely new areas of configuration, such as access
+control lists and categorized logging.
+Many options that previously applied to all
+zones can now be used selectively.
+These features, plus a consideration of future configuration needs
+led to the creation of a new configuration file format.
 .Ss General Syntax
 A BIND 8 configuration consists of two general features, statements
-and comments.  All statements end with a semicolon.  Many statements
-can contain substatements, which are each also terminated with a
+and comments.
+All statements end with a semicolon.
+Many statements can contain substatements, which are each also
+terminated with a
 semicolon.
 .Pp
 The following statements are supported:
@@ -65,11 +68,13 @@
 and
 .Ic options
 statements may only occur once per configuration, while the rest may
-appear numerous times.  Further detail on each statement is provided
+appear numerous times.
+Further detail on each statement is provided
 in individual sections below.
 .Pp
 Comments may appear anywhere that whitespace may appear in a BIND
-configuration file.  To appeal to programmers of all kinds, they can
+configuration file.
+To appeal to programmers of all kinds, they can
 be written in C, C++, or shell/perl constructs.
 .Pp
 C-style comments start with the two characters
@@ -81,7 +86,8 @@
 they can be used to comment only a portion of a line or to span
 multiple lines.
 .Pp
-C-style comments cannot be nested.  For example, the following is
+C-style comments cannot be nested.
+For example, the following is
 not valid because the entire comment ends with the first
 .Li */ :
 .Bd -literal -offset indent
@@ -97,7 +103,8 @@
 They cannot be continued across multiple physical lines; to have
 one logical comment span multiple lines, each line must use the
 .Li //
-pair.  For example:
+pair.
+For example:
 .Bd -literal -offset indent
 // This is the start of a comment.  The next line
 // is a new comment, even though it is logically
@@ -108,7 +115,8 @@
 character
 .Li #
 (hash or pound or number or octothorpe or whatever) and continue to
-the end of the physical line, like C++ comments.  For example:
+the end of the physical line, like C++ comments.
+For example:
 .Bd -literal -offset indent
 # This is the start of a comment.  The next line
 # is a new comment, even though it is logically
@@ -119,7 +127,8 @@
 you cannot use the
 .Li ;
 (semicolon) character to start a comment such as you would in a zone
-file.  The semicolon indicates the end of a configuration statement,
+file.
+The semicolon indicates the end of a configuration statement,
 so whatever follows it will be interpreted as the start of the next
 statement.
 .Ss Converting from BIND 4.9.x
@@ -129,7 +138,8 @@
 a shell script that is part of the BIND 8.2.x source kit.
 .Sh DOCUMENTATION DEFINITIONS
 Described below are elements used throughout the BIND configuration
-file documentation.  Elements which are only associated with one
+file documentation.
+Elements which are only associated with one
 statement are described only in the section describing that statement.
 .Bl -tag -width 0n
 .It Va acl_name
@@ -150,7 +160,8 @@
 section.
 .It Va dotted-decimal
 One or more integers valued 0 through 255 separated only by dots
-(``.''), such as
+.Pq Sq \&. ,
+such as
 .Li 123 ,
 .Li 45.67
 or
@@ -173,13 +184,18 @@
 through
 .Li 65535 ,
 with values below 1024 typically restricted to
-root-owned processes.  In some cases an asterisk (``*'') character
+root-owned processes.
+In some cases an asterisk
+.Pq Sq *
+character
 can be used as a place holder to select a random high-numbered port.
 .It Va ip_prefix
 An IP network specified in
 .Va dotted-decimal
-form, followed by  ``/''
-and then the number of bits in the netmask.  E.g.
+form, followed by
+.Sq /
+and then the number of bits in the netmask.
+E.g.,
 .Li 127/8
 is
 the network
@@ -197,7 +213,8 @@
 .It Va number
 A non-negative integer with an entire range limited by the range of a
 C language signed integer (2,147,483,647 on a machine with 32 bit
-integers).  Its acceptable value might further be limited by the
+integers).
+Its acceptable value might further be limited by the
 context in which it is used.
 .It Va size_spec
 A
@@ -234,7 +251,8 @@
 .Pp
 Integer storage overflow is currently silently ignored during
 conversion of scaled values, resulting in values less than intended,
-possibly even negative.  Using
+possibly even negative.
+Using
 .Li unlimited
 is the best way to safely set a really large number.
 .It Va yes_or_no
@@ -261,7 +279,8 @@
 .Ed
 .Ss Definition and Usage
 Address match lists are primarily used to determine access control for
-various server operations.  They are also used to define priorities
+various server operations.
+They are also used to define priorities
 for querying other nameservers and to set the addresses on which
 .Nm named
 will listen for queries.
@@ -277,7 +296,8 @@
 .It
 an
 .Va ip-prefix
-(in the '/'-notation),
+(in the
+.Sq / No Ns -notation ) ,
 .It
 A
 .Va key_id ,
@@ -294,15 +314,17 @@
 .Va address_match_list .
 .El
 .Pp
-Elements can be negated with a leading exclamation mark (``!''), and
-the match list names
+Elements can be negated with a leading exclamation mark
+.Pq Sq \&! ,
+and the match list names
 .Li any ,
 .Li none ,
 .Li localhost
 and
 .Li localnets
-are predefined.  More information on those names can be found in the
-description of the
+are predefined.
+More information on those names can be found in the description of
+the
 .Ic acl
 statement.
 .Pp
@@ -310,27 +332,31 @@
 .Ic key
 clause made the name of this syntactic element something of a
 misnomer, since security keys can be used to validate access without
-regard to a host or network address.  Nonetheless, the term ``address
-match list'' is still used throughout the documentation.
+regard to a host or network address.
+Nonetheless, the term
+.Dq address match list
+is still used throughout the documentation.
 .Pp
 When a given IP address or prefix is compared to an address match
-list, the list is traversed in order until an element matches.  The
-interpretation of a match depends on whether the list is being used
-for access control, defining
+list, the list is traversed in order until an element matches.
+The interpretation of a match depends on whether the list is being
+used for access control, defining
 .Ic listen-on
 ports, or as a topology, and whether the element was
 negated.
 .Pp
 When used as an access control list, a non-negated match allows access
-and a negated match denies access.  If there is no match at all in the
-list, access is denied.  The clauses
+and a negated match denies access.
+If there is no match at all in the list, access is denied.
+The clauses
 .Ic allow-query ,
 .Ic allow-transfer ,
 .Ic allow-update ,
 .Ic allow-recursion ,
 and
 .Ic blackhole
-all use address match lists like this.  Similarly, the
+all use address match lists like this.
+Similarly, the
 .Ic listen-on
 option will cause the server to not accept queries on any of the
 machine's addresses which do not match the list.
@@ -339,18 +365,21 @@
 .Ic topology
 option, a non-negated match returns a distance based on its position on
 the list (the closer the match is to the start of the list, the
-shorter the distance is between it and the server).  A negated match
-will be assigned the maximum distance from the server.  If there is no
+shorter the distance is between it and the server).
+A negated match
+will be assigned the maximum distance from the server.
+If there is no
 match, the address will get a distance which is further than any
 non-negated list element, and closer than any negated element.
 .Pp
 Because of the first-match aspect of the algorithm, an element that
 defines a subset of another element in the list should come before the
-broader element, regardless of whether either is negated.  For
-example, in
+broader element, regardless of whether either is negated.
+For example, in
 .Dl 1.2.3/24; !1.2.3.13
 the 1.2.3.13 element is completely useless, because the algorithm will
-match any lookup for 1.2.3.13 to the 1.2.3/24 element.  Using
+match any lookup for 1.2.3.13 to the 1.2.3/24 element.
+Using
 .Dl !1.2.3.13; 1.2.3/24
 fixes that problem by having 1.2.3.13 blocked by the negation but all
 other 1.2.3.* hosts fall through.
@@ -397,8 +426,8 @@
 statement is used to define as many channels and categories as are wanted.
 If there are multiple logging statements in a configuration, the first
 defined determines the logging, and warnings are issued for the
-others.  If there is no logging statement, the logging configuration
-will be:
+others.
+If there is no logging statement, the logging configuration will be:
 .Bd -literal
     logging {
         category default { default_syslog; default_debug; };
@@ -410,28 +439,32 @@
 .Pp
 The logging configuration is established as soon as the
 .Ic logging
-statement is parsed.  If you want to redirect
+statement is parsed.
+If you want to redirect
 messages about processing of the entire configuration file, the
 .Ic logging
-statement must appear first.  Even if you do not
+statement must appear first.
+Even if you do not
 redirect configuration file parsing messages, we recommend
 always putting the
 .Ic logging
 statement first so that this rule need not be consciously recalled if
 you ever do want the parser's messages relocated.
 .Ss The channel phrase
-All log output goes to one or more ``channels''; you can make as many
-of them as you want.
+All log output goes to one or more
+.Dq channels ;
+you can make as many of them as you want.
 .Pp
 Every channel definition must include a clause that says whether