From d69f1f58616113fa83d55cb641675eea62374e59 Mon Sep 17 00:00:00 2001
From: Richard Brooksby <rb@ravenbrook.com>
Date: Fri, 10 May 2013 18:29:36 +0100
Subject: [PATCH] Branching mminfo's guide.hex.trans to design.

Copied from Perforce
 Change: 181703
 ServerID: perforce.ravenbrook.com
---
 mps/design/guide.hex.trans.txt | 81 ++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 mps/design/guide.hex.trans.txt

diff --git a/mps/design/guide.hex.trans.txt b/mps/design/guide.hex.trans.txt
new file mode 100644
index 00000000000..39f4278a05e
--- /dev/null
+++ b/mps/design/guide.hex.trans.txt
@@ -0,0 +1,81 @@
+         GUIDE TO TRANSLITERATING THE ALPHABET INTO HEXADECIMAL
+                            guide.hex.trans
+                             incomplete doc
+                           gavinm 1997-04-11
+
+INTRODUCTION
+
+.scope: This document explains how to represent the alphabet as hexadecimal 
+digits.
+
+.readership: This document is intended for anyone devising arbitrary constants 
+which may appear in hex-dumps.
+
+.sources: This transliteration was supplied by RichardK in 
+mail.richardk.1997-04-07.13-44.
+
+
+TRANSLITERATION
+
+.forward: The chosen transliteration is as follows:
+  ABCDEFGHIJKLMNOPQRSTUVWXYZ
+  ABCDEF9811C7340BC6520F3812
+
+.backward: The backwards transliteration is as follows:
+  0 OU
+  1 IJY
+  2 TZ
+  3 MW
+  4 N
+  5 S
+  6 R
+  7 L
+  8 HX
+  9 G
+  A A
+  B BP
+  C CKQ
+  D D
+  E E
+  F FV
+
+.pad: If padding is required (to fill a hex constant length), you should use 
+9's, because G is rare and can usually be inferred from context.
+
+.punc: There is no formal scheme for spaces, or punctuation.  It is suggested 
+that you use 9 (as .pad).
+
+
+JUSTIFICATION
+
+.letters: The hexadecimal letters (A-F) are all formed by similarity of sound.  
+B and P sound similar, as do F and V, and C, K, & Q can all sound similar.
+
+.numbers: The numbers (0-9) are all formed by similarity of shape (but see 
+.trans.t).  Nevertheless, 1=IJY retains some similarity of sound.
+
+.trans.t: T is an exception to .numbers, but is such a common letter that it 
+deserves it.
+
+
+NOTES
+
+.change: This transliteration differs from the old transliteration used for 
+signatures (see design.mps.sig(0)), as follows: J:6->1; L:1->7; N:9->4; R:4->6; 
+W:8->3; X:5->8; Y:E->I.
+
+.problem.mw: There is a known problem that M and W are both common, map to the 
+same digit (3), and are hard to distinguish in context.
+
+.find.c: It is possible to find all 8-digit hexadecimal constants and how many 
+times they're used in C files, using the following Perl script:
+  perl5 -n -e 'BEGIN { %C=(); } if(/0x([0-9A-Fa-f]{8})/) { $C{$1} = +[] if(
+!defined($C{$1})); push(@{$C{$1}}, $ARGV); } END { foreach $H (sort(keys(%C)))
+{ printf "%3d %s %s\n", scalar(@{$C{$H}}), $H, join(", ", @{@C{$H}}); } }' *.c
+*.h
+
+.comment: It is a good idea to add a comment to any constant declaration 
+indicating the English version and which letters were selected (by 
+capitalisation), e.g.:  #define SpaceSig        ((Sig)0x5195BACE) /* SIGnature 
+SPACE */
+