Makefile.m4: Remove mplimits.[ch] on clean.

[u/mdw/catacomb] / hashsum.1

diff --git a/hashsum.1 b/hashsum.1
index f500d25..bc956d0 100644 (file)
--- a/hashsum.1
+++ b/hashsum.1
@@ -12,9 +12,11 @@
 hashsum \- compute and verify cryptographic checksums of files
 .SH SYNOPSIS
 .B hashsum
-.RB [ \-f0ecbv ]
+.RB [ \-f0ecbpv ]
 .RB [ \-a
 .IR algorithm ]
+.RB [ \-E
+.IR encoding ]
 .IR files ...
 .SH DESCRIPTION
 The
@@ -24,10 +26,12 @@ files.  A number of hashing algorithms are available.
 .PP
 The
 .B hashsum
-program's options and output are designed to be upwardly compatible with
-the GNU
+program's options and output were originally designed to be upwardly
+compatible with the GNU
 .BR md5sum (1)
-program.
+program, but the two have diverged somewhat.  See the
+.B "COMPATIBILITY NOTES"
+section of this manual for details.
 .PP
 Usually,
 .B hashsum
@@ -52,6 +56,9 @@ successfully.
 .B "\-u, \-\-usage"
 Prints a brief usage summary to standard output and exits successfully.
 .TP
+.BR "\-l, \-\-list " [ \fIitem ...]
+Show lists of hash functions and encodings supported.
+.TP
 .BI "\-a, \-\-algorithm=" alg
 Use the hash algorithm
 .IR alg .
@@ -60,9 +67,20 @@ see
 .B "Hashing algorithms"
 below.
 .TP
-.B "\-l, \-\-list"
-Prints a space-separated list of available hashing algorithms to
-standard output and exits successfully.
+.BI "\-E, \-\-encoding=" encoding
+Use the given
+.I encoding
+to represent hashes in the output.  This is not interoperable with other
+programs, but it's handy, e.g., for building sha1 URNs.  The encodings
+recognized are
+.B hex
+(the default),
+.B base64
+and
+.BR base32 .
+Type
+.B hashsum \-\-list enc
+for a list of supported encodings.
 .TP
 .B "\-f, \-\-files"
 Each input file is considered to be a list of filenames which should be
@@ -106,6 +124,10 @@ Assume that the files to be hashed are binary files.  This doesn't make
 any difference in Unix systems, although it might on other platforms
 which draw a distinction.
 .TP
+.B "\-p, \-\-progress"
+Display a progress indicator while hashing large files.  The progress
+indicator is written to standard error.
+.TP
 .B "\-v, \-\-verbose"
 In conjunction with the
 .B \-c
@@ -126,25 +148,25 @@ A
 .I directive
 begins with a hash
 .RB (` # ')
-character.  Two directives are currently understood:
+character.  These directives are currently understood:
 .TP
 .BI "#hash " alg
 Subsequent hashes in this file were generated using the algorithm
 .IR alg .
 .TP
+.BI "#encoding " encoding
+Subsequent hashes in this file are represented using the named
+.IR encoding .
+.TP
 .BI "#escape"
 Filenames in subsequence lines are written using the `escaped' format,
 described below.
 .PP
 A
 .I "file line"
-consists of a hash, in hexadecimal, followed by a space, a
+consists of a hash, in the requested encoding, followed by a space, a
 .IR flag ,
-and the filename.  If the current hash algorithm produces
-.IR n -bit
-output, there must be
-.IR n /4
-hex digits of hash in a file line.  The
+and the filename.  The
 .I flag
 is either a star
 .RB (` * ')
@@ -275,7 +297,53 @@ option,
 will emit a
 .RB ` #hash '
 directive in its output.
+.SH "COMPATIBILITY NOTES"
+Once upon a time, there was only the
+.BR md5sum (1)
+utility.  As its name suggested, it calculated MD5 hashes of files.  MD5
+was shown to be weak, so the author wrote
+.B hashsum
+to do the same job with other, hopefully stronger, hash functions.  The
+original
+.B hashsum
+program tried hard to be compatible with GNU
+.BR md5sum (1),
+but the latter has itself changed in incompatible ways since then;
+.B hashsum
+has intentionally not changed to match.
+.PP
+The following
+.B hashsum
+features are not found in the GNU Coreutils hashing utilities.
+.hP
+Filename escaping (the
+.B \-e
+option).
+.hP
+Magic comment lines in hash data to indicate algorithm selection, hash
+encoding, and filename escaping.
+.hP
+Base-64 and Base-32 output.
+.PP
+Other differences are as follows.
+.hP
+Originally, if GNU
+.B md5sum
+was invoked without any filename arguments, it would print only the hash
+of its stdin to stdout, which was very convenient for scripts which
+manipulate hashes in nontrivial ways.  This behaviour was later changed,
+and now the GNU Coreutils hashing utilities always print a filename or
+.RB ` \- '
+after the hash.  The
+.B hashsum
+program follows the original
+.B md5sum
+behaviour, and doesn't print a filename if no files were listed on the
+command line.
 .SH "SEE ALSO"
-.BR md5sum (1).
+.BR md5sum (1),
+.BR dsig (1),
+.BR catsign (1),
+.BR catcrypt (1).
 .SH "AUTHOR"
-Mark Wooding, <mdw@nsict.org>
+Mark Wooding, <mdw@distorted.org.uk>