Version bump again, include the man page in the source distribution.

[hath.git] / doc / man1 / hath.1

diff --git a/doc/man1/hath.1 b/doc/man1/hath.1
new file mode 100644 (file)
index 0000000..7006ac3
--- /dev/null
+++ b/doc/man1/hath.1
@@ -0,0 +1,99 @@
+.TH hath 1
+
+.SH NAME
+hath \- Manipulate network blocks in CIDR notation
+
+.SH SYNOPSIS
+
+\fBhath\fR [\fBregexed|reduced|duped|diffed\fR] [\fB\-h\fR] [\fB-i \fIFILE\fR] \fI<input>\fR
+
+.SH INPUT
+
+.P
+The \fIinput\fR (default: stdin) should be a list of CIDR blocks,
+separated by whitespace. Empty lines will be ignored, but otherwise,
+malformed entries will cause an error to be displayed.
+
+.SH DESCRIPTION
+
+.P
+Hath is a Haskell program for working with network blocks in CIDR
+notation. When dealing with blocks of network addresses, there are a
+few things that one usually wants to do with them:
+
+.IP \[bu] 2
+Create a regular expression matching the CIDR block(s). This is
+because grep will throw up if you feed it CIDR.
+
+.IP \[bu]
+Combine small blocks into larger ones. For example, if you have two
+consecutive /24s, they might combine into a larger /23.
+
+.IP \[bu]
+View the result of block combination in a useful way.
+
+.P
+Hath does just that. It takes as its input (via stdin, or a file with
+the -i parameter) a list of CIDR blocks.
+
+.SH MODES
+
+.P
+Hath currently has four modes:
+
+.IP \[bu] 2
+\fBRegexed\fR
+
+This computes a (Perl-compatible) regular expression matching
+the input CIDR blocks. It's the default mode of operation.
+
+.nf
+.B $ hath <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+([^\.0-9](10)\.(0)\.(0)\.(0)[^\.0-9]|[^\.0-9](10)\.(0)\.(1)
+\.(0)[^\.0-9])
+
+.IP \[bu]
+\fBReduced\fR
+
+This combines small blocks into larger ones where possible, and
+eliminates redundant blocks. The output should be equivalent to
+the input, though.
+
+.nf
+.B $ hath reduced <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+10.0.0.0/23
+
+.IP \[bu]
+\fBDuped\fR
+
+Shows only the blocks that would be removed by reduce; that is, it
+shows the ones that would get combined into larger blocks or are
+simply redundant.
+
+.nf
+.B $ hath duped <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+10.0.0.0/24
+10.0.1.0/24
+
+.IP \[bu]
+\fBDiffed\fR
+
+Shows what would change if you used reduce. Uses diff-like
+notation.
+
+.nf
+.B $ hath diffed <<< \(dq10.0.0.0/24 10.0.1.0/24\(dq
+-10.0.0.0/24
+-10.0.1.0/24
++10.0.0.0/23
+
+.P
+Each of the modes also supports a present-tense flavor; the following
+are equivalent to their counterparts: \fBregex\fR, \fBreduce\fR,
+\fBdupe\fR, \fBdiff\fR.
+
+.SH OPTIONS
+
+.IP \fB\-\-input\fR,\ \fB\-i\fR
+Specify the input file containing a list of CIDRs, rather than using
+stdin (the default).