Add a man page.

diff --git a/CHANGES b/CHANGES
index d9ba52ebaa99ecc0fe312cef241239514a488c3a..a82591dcb204848839e812871ef6c53ff9fa6e08 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -1,6 +1,7 @@
 New in version 0.8
 ==================
 
+* Add a man (1) page
 * Dropped "-x" flag; the return code is always non-zero on error now.
 * Warn about IP addresses in hostname fields
 * Add support for SRV records

diff --git a/valtz.1 b/valtz.1
new file mode 100644 (file)
index 0000000..5fd6ec7
--- /dev/null
+++ b/valtz.1
@@ -0,0 +1,155 @@
+.TH valtz 1
+
+.SH NAME
+valtz \- Validate tinydns-data files.
+
+.SH SYNOPSIS
+
+Validate one or more tinydns-data files:
+
+  \fBvaltz\fR [\fB-r\fR] [\fB-R\fR] [\fB-i\fR] \fItinydns-file1\fR [\fItinydns-file2 ...\fR]
+
+Filter bad lines out of one or more tinydns-data files:
+
+  \fBvaltz\fR [\fB-HiIqrRst\fR] [\fB-T \fItypes\fR\fR] -f \fItinydns-file1\fR [\fItinydns-file2 ...\fR]
+
+Filter bad lines using filter configuration files:
+
+  \fBvaltz\fR [\fB-fHiIqrRst\fR] [\fB-T \fItypes\fR\fR] -F \fIfilter-file1\fR [\fIfilter-file2 ...\fR]
+
+Show the built-in help:
+
+  \fBvaltz\fR -h
+
+.SH OPTIONS
+
+.IP \fB-h\fR
+Display usage summary.
+.IP \fB-f\fR
+Filter out invalid lines and write the rest to stdout.
+.IP \fB-F\fR
+Treat the program's arguments as filter configuration files rather than
+as tinydns-data files. See the ADVANCED FILTERING section below for more
+information.
+.IP \fB-r\fR
+Allow "fqdn" fields to be empty, thereby denoting the root.
+When using ADVANCED FILTERING, this is the default behavior for "deny" filters,
+and can be obtained explicitly for "allow" filters by specifying "allow ."
+.IP \fB-R\fR
+Allow "mname" and "p" fields to be empty. This is probably not very
+useful.
+.IP \fB-i\fR
+Allow "ip" fields to be empty. These lines do not generate any records.
+.IP \fB-I\fR (filtering only)
+Include rejected lines as comments in output.
+.IP \fB-q\fR (filtering only)
+Do not print valid lines to standard out.
+.IP \fB-s\fR
+-s Don't skip files ending with ",v", "~", ".bak", ".log", ".old", ".swp", and ".tmp".
+.IP \fB-t\fR (filtering only)
+Don't ignore comment lines (beginning with a "#" character).
+.IP \fB-T \fItypes\fR\fR (advanced filtering only)
+Specify additional allowed record types, on top of the ones
+allowed by the filter configuration files.
+
+.SH OUTPUT
+When validating, ideally no output is generated. Any errors are
+printed to standard error.
+.P
+When filtering, the acceptable lines are printed to standard out.
+
+.SH EXIT CODE
+The exit code will be 0 if nothing has gone wrong. If a validation
+error occurs, the return value is incremented by 1. If a disallowed
+record type is encountered, the return value is incremented by 2.
+
+.SH ADVANCED FILTERING
+When the \fB-F\fR flag is used, valtz performs "advanced filtering"
+controlled by filter configuration files that are specified on the
+command line. These files contain one or more of the following
+directives, each of which may appear only once unless otherwise
+specified:
+.IP \fBzonefile\ \fIpaths\fR\fR
+Directly specifies the tinydns-data files to which this filter
+applies.
+.IP \fBzonefile\ file:\fIzonelist\fR\fR
+Indirectly specifies the tinydns-data files to which this filter
+applies, by referencing another \fIzonelist\fR that contains one path
+(to a tinydns-data file) per line.
+.IP \fBextralog\ \fIlogfile\fR\fR
+Log errors to \fIlogfile\fR in addition to printing them to standard
+error. Useful when you have many tinydns-data files and want to keep
+their results separate.
+.IP \fBdeny\ \fIpattern\fR\fR
+Place the filter in "implicit allow" mode, so that all records are
+allowed unless their "fqdn" is explicitly matched by the
+perl-compatible regular expression \fIpattern\fR. May appear more than
+once.
+.IP \fBdeny\ file:\fIdenylist\fR\fR
+Place the filter in "implicit allow" mode, so that all records are
+allowed unless their "fqdn" is explicitly matched by a line in
+\fIdenylist\fR, which should contain one perl-compatible regular
+expression per line. May appear more than once.
+.IP \fBallow\ \fIpattern\fR\fR
+Place the filter in "implicit deny" mode, so that all records are
+denied unless their "fqdn" is explicitly matched by the
+perl-compatible regular expression \fIpattern\fR. May appear more than
+once.
+.IP \fBallow\ file:\fIallowlist\fR\fR
+Place the filter in "implicit deny" mode, so that all records are
+denied unless their "fqdn" is explicitly matched by a line in
+\fIallowlist\fR, which should contain one perl-compatible regular
+expression per line. May appear more than once.
+.IP \fBallowtype\ \fItypes\fR\fR
+Specifies a whitespace-separated list allowed record types. When used,
+even comment lines (type "#") must explicitly be allowed if you want
+to include them in the output. Valid record types are "%", ".", "&",
+"=", "+", "@", "#", "-", "'", "^", "C", "S", "Z", and ":".
+
+.SH EXAMPLES
+
+.IP \[bu] 2
+Validate a file without errors:
+
+.nf
+.I $ valtz example.org.tinydns
+.I $ echo $?
+0
+.fi
+
+.IP \[bu] 2
+Validate a file \fBwith\fR errors:
+
+.nf
+.I $ valtz example.com.tinydns
+File example.com.tinydns
+  line 5; err 1 !example.com.::127.0.0.1:
+    unknown record type: #21
+.I $ echo $?
+1
+.fi
+
+.IP \[bu] 2
+Filter invalid lines out of the given file:
+
+.nf
+.I $ valtz -f example.com.tinydns 2>/dev/null
+Zexample.com.:dns1.example.com.:admin.example.com.:
+&example.com.::dns1.example.com.:
+&example.com.::dns2.example.com.:
++example.com.:127.0.0.1:
+Cwww.example.com.:example.com.:
+.fi
+
+.IP \[bu] 2
+Use advanced filtering with a configuration file that drops everything
+except SOA and A records (of type "Z" and "+", respectively):
+
+.nf
+.I $ cat keep-SOA-A-records.valtz
+zonefile example.com.tinydns
+allowtype Z +
+.I $ valtz -F keep-SOA-A-records.valtz 2>/dev/null
+Zexample.com.:dns1.example.com.:admin.example.com.:
++example.com.:127.0.0.1:
+.fi