Document a pipe-to-sort and justify the lack of a special CIDR sort.

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

diff --git a/doc/man1/hath.1 b/doc/man1/hath.1
index 0316c56a3ada9fc131940a8c91d541daeda2aa25..85978353ab0bdd6ff43dd2876d610ce561d697fe 100644 (file)
--- a/doc/man1/hath.1
+++ b/doc/man1/hath.1
@@ -101,6 +101,21 @@ Use the \(dqdig\(dq command to look up the PTR records for a netblock:
 4.0.41.198.in-addr.arpa. 897   IN      PTR     a.root-servers.net.
 6.0.41.198.in-addr.arpa. 900   IN      PTR     rs.internic.net.
 .fi
+.P
+Sort the \(dqreduced\(dq output:
+
+.nf
+.I $ echo \(dq192.168.0.100/24 192.167.1.200/24\(dq | hath reduced | sort
+192.167.1.200/24
+192.168.0.100/24
+.fi
+
+Sorting the output only makes sense for the \(dqreduced\(dq mode. In
+that mode, two output CIDRs cannot have same the numeric address and a
+different mask: one of them would contain the other, and the redundant
+one would be eliminated. As a result, there is no need for a special
+CIDR sort; the lexical or numerical sort provided by the \(dqsort\(dq
+utility will produce the same results as a more intelligent sort.
 .SH OPTIONS
 
 .IP \fB\-\-barriers\fR,\ \fB\-b\fR
@@ -119,6 +134,7 @@ Without \fB\-\-barriers\fR, you can match things you shouldn't:
 .fi
 
 Using \fB\-\-barriers\fR can prevent this:
+
 .nf
 .I $ echo 127.0.0.100 | grep -P $(echo 127.0.0.1/32 | hath -b)
 .I $ echo $?
@@ -127,10 +143,26 @@ Using \fB\-\-barriers\fR can prevent this:
 
 But, this may also cause the regex to match something that isn't an IP
 address:
+
 .nf
 .I $ echo x127.0.0.1x | grep -Po $(echo 127.0.0.1/32 | hath -b)
 x127.0.0.1x
 .fi
+
+.IP \fB\-\-normalize\fR,\ \fB\-n\fR
+(reduced mode only)
+
+Normalize the output representation of CIDRs by zeroing the host
+bits. This option only has an effect in \(dqreduced\(dq mode, because
+in the \(dqduped\(dq or \(dqdiffed\(dq modes, it would be confusing to
+see CIDRs that you did not input in the first place being removed.
+
+.nf
+.I $ echo 127.0.0.1/8 | hath reduced
+127.0.0.1/8
+.I $ echo 127.0.0.1/8 | hath reduced --normalize
+127.0.0.0/8
+.fi
 .SH BUGS
 
 Send bugs to michael@orlitzky.com.