i18n: i18n-diff-auditor: add usage message

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

diff --git a/i18n-diff-auditor b/i18n-diff-auditor
index 363103fccf01e7a4f7bfc47894330d6c56fe2066..341733b41e43cd9b908db75da2a215ace49e67c6 100755 (executable)
--- a/i18n-diff-auditor
+++ b/i18n-diff-auditor
@@ -4,6 +4,37 @@
 # Copyright (C)2018 Ian Jackson
 # GPLv3+, NO WARRANTY, see below.
 #
+#
+# Usage:
+#  something like this
+#  git-log -n1 -p | ./i18n-diff-auditor -D 2>&1 |less -j10 +/'^!.*'
+#
+# -D is for debug.  Currently only one level.
+#
+# Output is the relevant diff hunks, with each line prepended with
+# space for ok lines and ! for questionable ones, and with relevant
+# diff lines prepended with lines starting !! (and lines starting #
+# for debug output), so ovrall:
+#
+#   !! <message>   reasoning for subsequent questionable diff line(s)
+#   !+             diff line found to be questionable
+#   !-             diff line found to be questionable
+#    @@@ etc.      diff furniture
+#    +             diff line checked and ok
+#    -             diff line checked and ok
+#   # <stuff>      debug output (normally precedes relevant output)
+#
+# Changes are generally marked as ok if they correspond to a known
+# intended code change pattern.  (That includes changing error calls
+# to different error calls.)  If they don't correspond to any known
+# pattern, they are "questionable" and the first thing that doesn't
+# match the most common pattern is reported.
+#
+# Might be useful for projects other than dgit, provided it uses
+# the same gettext aliases (__ f_ i_) and similar error calls
+# (die, confess, fail).
+#
+#
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or