From c3321b13915e3b839da060f8dc63c68e31bcc360 Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Sun, 2 Oct 2011 13:58:19 +0100
Subject: [PATCH] hashsum.1: Write some notes about compatibility with GNU
 Coreutils.

---
 hashsum.1 | 51 ++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/hashsum.1 b/hashsum.1
index 7910807..bc956d0 100644
--- a/hashsum.1
+++ b/hashsum.1
@@ -26,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
@@ -295,6 +297,49 @@ 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 dsig (1),
-- 
2.11.0