chiark / gitweb /
Clarify and shorten README.charset
authorIan Jackson <ian@liberator.relativity.greenend.org.uk>
Sat, 4 Jul 2009 16:23:04 +0000 (17:23 +0100)
committerIan Jackson <ian@liberator.relativity.greenend.org.uk>
Sat, 4 Jul 2009 16:23:04 +0000 (17:23 +0100)
pctb/README.charset

index 0d7f162..49bc9c7 100644 (file)
@@ -15,7 +15,7 @@ Recognition algorithm
 ---------------------
 
 We recognise the text in the commodity screen by doing exact matching
-of `glyph' bitmaps, against the bitmap in each cell in the commodity
+of `glyph' images, against the image in each cell in the commodity
 table.  We match from left to right.
 
 We do not insist that each glyph is followed by whitespace, and nor do
@@ -35,18 +35,42 @@ correct character.  The longest match rule will mean it will prefer
 the entry you have just made.
 
 
-Upper vs lower case - important note regarding `l' and `I'
-----------------------------------------------------------
+Matching context - Upper/Lower/Digit/Word dictionaries
+------------------------------------------------------
 
-We maintain separate dictionaries for upper case (Upper), lower case
-(Lower), and (initial portions of) mid-phrase words (Word).  At the
-beginning of each cell in the table, we expect uppercase; in the
-middle of a word we expect lowercase; and, unfortunately, after an
+We maintain separate dictionaries for the following types of glyph
+
+ Upper:
+     Upper case letters and ligatures starting with an
+     uppercase letter.  Punctuation excluding `>'.
+ Lower:
+     Lower case letters and ligatures starting with a
+     lowercase letter.
+ Digit:
+     Digits and the greater than sign `>' (which can also
+     appear in the quantity field in the commodity display)
+ Word:
+     Words (or initial parts of words) which start with `l'
+     or `I'.
+
+When you add an entry, you should add it to the appropriate dictionary
+for its matching context.  You can do this by selecting the
+appropriate radiobutton or by pressing one of letters U D L W (the
+initial letters of the contexts) after moving the cursor to the
+appropriate spot but before hitting `Return' to enter the text for the
+new entry.
+
+
+Note regarding `l' and `I'
+--------------------------
+
+At the beginning of each cell in the table, we expect uppercase; in
+the middle of a word we expect lowercase; and, unfortunately, after an
 inter-word gap, we are not sure.
 
 This is troublesome because `l' and `I' look identical on the screen.
-So any time we see a word starting with `l' or `I', the program has to
-ask about it.
+So any time we see an unfamiliar word starting with `l' or `I', the
+program has to ask about it.
 
 After an interword gap, we first search for a Word entry in the
 dictionary.  If there is a match we use it.  Otherwise we search both
@@ -54,11 +78,11 @@ the uppercase and lowercase dictionaries; if one matches and the other
 doesn't, or one matches a wider character than the other, we use it.
 If that fails to resolve the ambiguity we must ask.
 
-*Do not* make an entry in the character set dictionary mapping
-`vertical stick' to `l' or `I'.  Instead, select enough of the whole
-word in question that no word would start with the other letter, and
-enter the whole word or part of it as a new glyph as a new entry in
-the Word dictionary.
+Don't try to make an entry in the character set dictionary mapping
+`vertical stick' to `l' or `I'.  Instead, select the whole word (or
+enough of it that no different word would start with the other
+letter), and enter the whole thing as a new glyph in the Word
+dictionary.
 
 For example, in the supplied dictionary there is already a glyph for
 `Iron'; this is OK because there are no words which start `lron'.
@@ -76,11 +100,11 @@ recognised as.
 
 *You should check the alleged context before entering a character*.
 If it is wrong, you should fix it, rather that just making an entry
-for the uppercase letter in the lowercase dictionary.
+in the wrong dictionary.
 
-Instead, make a new glyph for the last letter of the previous word
-plus the (unusually narrow) inter-word space, and end that entry with
-a literal space ` '.
+When this happens, instead, make a new glyph for the last letter of
+the previous word plus the (unusually narrow) inter-word space, and
+end that entry with a literal space ` '.
 
 For example, you might find that `y<space>G' is treated as
 `y<??lowercase>' and the G doesn't get matched.  Select the `y<space>'
@@ -100,16 +124,19 @@ the top left corner of the `w' overlapping.  This is dealt with by
 matching the whole merged thing - select the region of the screen
 containing `yw' and define it as `yw'.
 
+Such a combined entry - a ligature - is only needed if the letters
+cannot be separated at all.  It's not needed if they merely abut.
+
 
 Fixing mistakes
 ---------------
 
-The OCR query UI allows you to delete things from the glyph
-dictionary.  However since you are not guaranteed to actually get an
-OCR query at all (and since it is not possible to override the
-presence of an entry in the master database with the absence of one in
-the local database), if the dictionary contains errors, you shouldn't
-rely on this.
+The OCR query UI allows you to delete things from the local glyph
+dictionary.  However you are not guaranteed to actually get an OCR
+query at all (and since it is not possible to override the presence of
+an entry in the master database with the absence of one in the local
+database).  So this is not a reliable feature for being able to fix
+errors.
 
 If you think you have made mistakes answering OCR queries (for
 example, the recognised data is wrong), you should delete the file
@@ -117,16 +144,17 @@ example, the recognised data is wrong), you should delete the file
 only use the centrally provided (and vetted) master file (which is
 automatically updated when you run the PCTB client, by default).
 
+Alternatively you can edit #local-char15#.txt with a text editor.  The
+format is not documented at the moment.
+
 
 Enabling interactive character set update
 -----------------------------------------
 
 Now that you have read this document, you should rerun your OCR job
-with the --edit-charset option.  You probably want to supply --same as
-well, to avoid having to wait for it to page through and recapture all
-the screenshots.  So, this time,
-   ./ypp-commodities --edit-charset --same
-and in future, just always run it with the --edit-charset option.
+with the --edit-charset option.  So
+   ./ypp-commodities --edit-charset
+In future, always run it with the --edit-charset option.
 
 With --edit-charset, when the OCR finds characters it does not
 understand, it will put up an OCR resolution query window.  This will
@@ -139,14 +167,6 @@ machinery works, and the possible mistakes you can make, before
 answering the program.  So *Please read this documentation*, which
 explains the meaning of the entries you make.
 
-You must specify the dictionary to which the new glyph should be
-added, by selecting the appropriate radiobutton or by pressing one of
-U D L W for Upper, Digit, Lower, Word.  Word is only correct
-right if the match failure is a new word starting with l or I (see
-above).  Upper or Lower is correct for single letters and ligatures.
-for new ligatures.  Use Upper for punctuation and Digit for `>' and
-digits.
-
 The character set updates you make will by default be submitted to my
 server so that they can be checked by me and shared with other users.
 See README.privacy.