Updated help to talk about new features.

source/org/thdl/tib/input/jskad_doc.html

@@ -17,6 +17,9 @@
    <li><a href="#copypaste">Copying and Pasting</a></li>
    <li><a href="#wylietotmw">Converting Wylie to Tibetan</a></li>
    <li><a href="#tmwtowylie">Converting Tibetan to Wylie</a></li>
+   <li><a href="#ttot">Converting Tibetan to Tibetan</a></li>
+   <li><a href="#converter">GUI Converter</a></li>
+   <li><a href="#viewer">External Viewers</a></li>
    <li><a href="#keyboards">Changing Keyboards</a></li>
    <li><a href="#preferences">Preferences</a></li>
    <li><a href="#thanks">Thanks</a></li>
@@ -48,7 +51,8 @@ Jskad is launched via Java Web Start.&nbsp; Java Web Start is a
 technology from Sun which allows users to launch Java applications
 directly from a web browser.&nbsp; Java Web Start is supported by
 Windows, Linux, Solaris, and Mac OS X 10.1, and so Jskad should work
-on all of these platforms.
+on all of these platforms.&nbsp; (You don't need Java Web Start, but
+it does make upgrades much easier.)
 </p>
 
 <p>
@@ -65,8 +69,10 @@ computer.
 Note that to run Jskad you no longer need to have the <a
 href="http://iris.lib.virginia.edu/tibet/tools/tmw.html">Tibetan
 Machine Web</a> family of fonts installed; they are now embedded in
-Jskad itself.&nbsp; But if you wish to copy and paste into another
+Jskad itself along with the <a
-application, then you do need the <a
+href="http://iris.lib.virginia.edu/tibet/tools/tm.html">Tibetan
+Machine</a> family of fonts.&nbsp; But if you wish to copy and paste
+into another application, then you do need the <a
 href="http://iris.lib.virginia.edu/tibet/tools/tmw.html">Tibetan
 Machine Web</a> family of fonts installed.
 </p>
@@ -89,9 +95,7 @@ Runtime v. 1.4</a>.
 
 <p>
 When you fire up Jskad, a glitz-free window will pop up in the center
-of your screen.&nbsp; Start typing and you'll get Tibetan.&nbsp; If
+of your screen.&nbsp; Start typing and you'll get Tibetan.
-you get garbage instead, that probably means that you haven't <a
-href="#install">installed the TibetanMachineWeb fonts</a>.
 </p>
 
 <p>
@@ -105,30 +109,36 @@ Edit, Tools, and Help.
 'File' provides basic options for opening, closing, saving, and
 printing Rich Text Format (RTF) documents.&nbsp; To start a new
 document, choose 'New'.&nbsp; To open an already existing document,
-choose 'Open'.&nbsp; In either case, if there is any text in the
+choose 'Open' or select from the list of recently opened
-current Jskad window, a new window will be opened up.&nbsp; To close a
+documents.&nbsp; In any case, if there is any text in the current
-Jskad window, choose 'Close' or press the 'X' button.&nbsp; To close
+Jskad window, a new window will be opened up.&nbsp; To close a Jskad
-all Jskad windows, choose 'Exit'.&nbsp; You will be prompted to save
+window, choose 'Close' or press the 'X' button.&nbsp; To close all
-if you haven't already done so.
+Jskad windows, choose 'Exit'.&nbsp; You will be prompted to save if
+you haven't already done so.
 </p>
 
 <p>
-To save, choose 'Save' or 'Save As'.&nbsp; Like other applications,
+To save in Rich Text Format, choose 'Save' or 'Save As'.&nbsp; Like
-'Save' saves under the current name, while 'Save As' lets you save
+other applications, 'Save' saves under the current name, while 'Save
-under a new name.
+As' lets you save under a new name.
 </p>
 
 <p>
 The 'Edit' menu lets you cut, copy, and paste Tibetan text and set
 document preferences.&nbsp; These topics are covered elsewhere, in <a
 href="#copypaste">Copying and Pasting</a>, <a href="#tibetan">Typing
-Tibetan</a>, and <a href="#english">Typing English</a>.
+Tibetan</a>, <a href="#english">Typing English</a>, and <a
+href="#preferences">Preferences</a>.
 </p>
 
 <p>
-The 'Tools' menu provides options to help users who are <a
+The 'Tools' menu provides options to help users who are converting
+Tibetan from one form to another and who wish to view the current
+document in an external viewer, such as Microsoft Word.
+
+<!-- FIXME DLC <a
 href="#wylietotmw">Converting Wylie to Tibetan</a> and <a
-href="#tmwtowylie">Converting Tibetan to Wylie</a>.
+href="#tmwtowylie">Converting Tibetan to Wylie</a>. -->
 </p>
 
 <p>
@@ -177,10 +187,10 @@ default point size for Tibetan text is 36.&nbsp; To change this go to
 With Jskad you are not restricted to just typing Tibetan.&nbsp; You
 can also type English or other European languages.&nbsp; If you are in
 Tibetan-entry mode, you can switch to Roman entry-mode by selection
-"Roman" from the "Input mode:" drop-down box.&nbsp; If this doesn't
+"Roman" from the "Input mode:" drop-down box.&nbsp; (If this doesn't
-get you into Roman-entry mode, then Roman entry-mode has been
+get you into Roman-entry mode, then Roman entry-mode has been disabled
-programmatically disabled by your alterations to your
+by your alterations to your <tt>my_thdl_preferences.txt</tt> file and
-<tt>my_thdl_preferences.txt</tt> file.
+you should use 'Edit-&gt;Clear Preferences'.)
 </p>
 
 <p>
@@ -196,11 +206,11 @@ selecting 'Preferences' from the 'Edit' menu.
 <h3>Copying and Pasting</h3>
 
 <p>
-Jskad supports RTF copy and paste.&nbsp; That means that you can copy
+Jskad supports RTF copy and paste.&nbsp; That means, among other
-Tibetan back and forth between Microsoft Word and Jskad.&nbsp; To do
+things, that you can copy Tibetan back and forth between Microsoft
-so, you can use standard keyboard shortcuts (Ctrl-A for select all,
+Word and Jskad.&nbsp; To do so, you can use standard keyboard
-Ctrl-X for cut, Ctrl-C for copy, and Ctrl-V for paste).&nbsp; Note
+shortcuts (Ctrl-A for select all, Ctrl-X for cut, Ctrl-C for copy, and
-that you must have the <a
+Ctrl-V for paste).&nbsp; Note that you must have the <a
 href="http://iris.lib.virginia.edu/tibet/tools/tmw.html">Tibetan
 Machine Web</a> family of fonts installed on your computer for
 applications besides Jskad to be aware of them.
@@ -222,18 +232,34 @@ snippet of Tibetan again, copy again, and then paste into Excel.
 
 <p>
 One of the most useful features of Jskad is its ability to convert
-from Extended Wylie to Tibetan.&nbsp; There are three ways to do this:
+from Extended Wylie to Tibetan.&nbsp; <em>Note that there are several
+known bugs with this conversion, so study your output.</em>&nbsp;
+There are three ways to do this:
 </p>
 
 <ol>
 <li><b>Copy and Paste from Another Application</b>
-<br>Copy a block of Wylie text from Microsoft Word, and then paste it in Jskad.
+
+<br>Copy a block of Wylie text from Microsoft Word, and then paste it
+in Jskad.</li>
 
 <p><li><b>Select Text and Convert to Tibetan</b>
-<br>Select the block of text you want to convert, and then choose 'Tools - Convert Wylie to Tibetan' from the menu bar.&nbsp; Note that if you try to convert a chunk of text in which Tibetan text is surrounded by Wylie, the Wylie will convert, and the Tibetan will remain unchanged.
+
+<br>Select the block of text you want to convert, and then choose
+'Tools - Convert Selection - Convert Wylie to Tibetan' from the menu
+bar.&nbsp; Note that if you try to convert a chunk of text in which
+Tibetan text is surrounded by Wylie, the Wylie will convert, and the
+Tibetan will remain unchanged.</li>
 
 <p><li><b>Import Wylie and Save as RTF</b>
-<br>Choose 'Tools - Import Wylie as Tibetan' from the menu bar.&nbsp; You will be prompted to 'Import Wylie'.&nbsp; Use the file chooser to select a .txt (text) file which contains nothing but Extended Wylie.&nbsp; Then you'll be prompted to 'Save as Tibetan'.&nbsp; Type a new name for your document.&nbsp; If the Wylie is valid, it will be converted and saved as RTF.&nbsp; This document can then be opened in Jskad.
+
+<br>Choose 'Tools - Import Wylie as Tibetan' from the menu bar.&nbsp;
+You will be prompted to 'Import Wylie'.&nbsp; Use the file chooser to
+select a .txt (text) file which contains nothing but Extended
+Wylie.&nbsp; Then you'll be prompted to 'Save as Tibetan'.&nbsp; Type
+a new name for your document.&nbsp; If the Wylie is valid, it will be
+converted and saved as RTF.&nbsp; This document can then be opened in
+Jskad.</li>
 </ol>
 
 <p>
@@ -265,20 +291,142 @@ computer knows that it is!
 <p>
 Another useful feature of Jskad is its ability to convert from Tibetan
 to Extended Wylie.&nbsp; Simply select the Tibetan you want to
-convert, and then choose 'Tools - Convert Tibetan to Wylie' from the
+convert, and then choose 'Tools - Convert Selection - Convert Tibetan
-menu bar.&nbsp; The text will be converted, and will appear as Wylie
+to Wylie' from the menu bar.&nbsp; The text will be converted, and
-in the default Roman font and point size (see <a
+will appear (if you are using 'Tools - Convert Selection - Convert
-href="#english">Typing English</a>).&nbsp; Jskad is fairly smart about
+Tibetan to Wylie') as Wylie in the default Roman font and point size
-determining which Tibetan letter is the root letter when there is
+(see <a href="#english">Typing English</a>).&nbsp; Alternatively, <a
-ambiguity.
+href="#converter">launch the Converter</a> and use it to convert whole
+documents with ease.
 </p>
 
 <p>
-Remember that Jskad only works with the TibetanMachineWeb family of
+Jskad is very smart about determining which Tibetan letter is the root
-fonts.&nbsp; Therefore, it will only recognize TibetanMachineWeb as
+letter when there is ambiguity.&nbsp; (It compares against a
-Tibetan.&nbsp; Any other Tibetan fonts will be assumed to be
+hard-coded list of words for the ambiguous three-consonant cases, such
-non-Tibetan.&nbsp; Note that you can convert TibetanMachine to
+as '-g-s).&nbsp; Jskad always produces 100% unambiguous Wylie, which
-TibetanMachineWeb and then convert that to Wylie if need be.
+you can feel certain will be read back in later as the very same
+Tibetan you started with.&nbsp; (Although, at this time, the
+Wylie-to-Tibetan side of the equation is not nearly as well tested,
+and in fact has known bugs.)
+</p>
+
+<p>
+Remember that Jskad only works fully with the TibetanMachineWeb family
+of fonts.&nbsp; (It can open TibetanMachine documents for viewing and
+for converting to TibetanMachineWeb, but you cannot type in new
+TibetanMachine.)&nbsp; Therefore, it will only recognize
+TibetanMachineWeb as Tibetan.&nbsp; Any other Tibetan fonts will be
+assumed to be non-Tibetan.&nbsp; Note that you can convert
+TibetanMachine to TibetanMachineWeb and then convert that to Wylie if
+need be.
+</p>
+
+<p>
+<center><font size="-1"><a href="#top">Back to top</a></font></center>
+</p>
+
+<a name="ttot"></a>
+<h3>Converting Tibetan to Tibetan</h3>
+
+<p>
+  Jskad also has the ability to convert from one digital form of
+  Tibetan to another, with perfect results (as far as we know).&nbsp;
+  You can convert Tibetan Machine Web to Tibetan Machine (use 'Tools -
+  Convert All - Convert Tibetan to TM') and vice versa (use 'Tools -
+  Convert All - Convert TM to Tibetan').&nbsp; You can also convert
+  Tibetan Machine Web to Unicode (using 'Tools - Convert All - Convert
+  Tibetan to Unicode').&nbsp; To convert Tibetan Machine to Unicode,
+  simply convert from Tibetan Machine to Tibetan Machine Web and then
+  convert from Tibetan Machine Web to Unicode.
+</p>
+
+<p>
+  To convert whole documents the easy way, just launch the <a
+  href="#converter">converter</a>.
+</p>
+
+<p>
+<center><font size="-1"><a href="#top">Back to top</a></font></center>
+</p>
+
+<a name="converter"></a>
+<h3>GUI Converter</h3>
+
+<p>
+  Jskad features a built-in converter with a user-friendly graphical
+  user interface.&nbsp; This converter does not show you the documents
+  as it is converting, though it allows you to view documents in an <a
+  href="#viewer">external RTF file viewer</a> using the 'Open With...'
+  button.
+</p>
+
+<p>
+  The converter handles all exceptional cases well.&nbsp; Thus, if the
+  converter says that it succeeded, it really did succeed
+  perfectly.&nbsp; You can rest assured that at least one character
+  was converted (it being a common error to open a Tibetan Machine
+  file and select a TMW-&gt;Wylie conversion), and that each character
+  in the original document was correctly converted to a character in
+  the new document.&nbsp; Even uncommon errors like running out of
+  memory are skillfully handled.
+</p>
+
+<p>
+  The TM-&gt;TMW and TMW-&gt;TM conversions have been hand-verified
+  using a document that lists each TMW glyph and its TM equivalent,
+  and two bugs in Java's RTF support have been worked around.&nbsp;
+  Moreover, the TM&lt;-&gt;TMW tables were input by two separate teams
+  and results compared.&nbsp; JUnit tests are used to verify that bugs
+  do not sneak into future revisions.&nbsp; Ask David Chandler to
+  elaborate on the verification and validation for the conversions,
+  but the bottom line is that there are no known bugs in the
+  TM-&gt;TMW, TMW-&gt;TM, TMW-&gt;Wylie, or TMW-&gt;Unicode
+  conversions.
+</p>
+
+<p>
+  The user interface is fairly straightforward, except for the 'Find
+  Some/All' options, which are used to create a list of the characters
+  that are not in the desired font.&nbsp; These options are for those
+  who want to be sure that they are converting a document that really
+  is wholly in Tibetan Machine or Tibetan Machine Web.
+</p>
+
+<p>
+  At present, the TMW-&gt;Unicode conversion converts to the Ximalaya
+  font.&nbsp; If users ask for it, the converter can easily be
+  extended to convert to the font of the user's choice.<!-- FIXME:
+  what about 0020, 2003, 54xx, etc.?  Allow for specifying the fonts
+  for those ranges separately. -->
+</p>
+
+<!-- FIXME: expound! -->
+
+<p>
+<center><font size="-1"><a href="#top">Back to top</a></font></center>
+</p>
+
+<a name="viewer"></a>
+<h3>External Viewers</h3>
+
+<p>
+  Jskad allows you to view an RTF document with an external viewer,
+  such as Microsoft Word.&nbsp; To use this feature, just select the
+  menu item 'Tools - Open With External Viewer...'.&nbsp; The first
+  time you use this command, it will ask you to locate a program to
+  view RTF files.  Navigate to the program of your choice, such as
+  "C:\Program Files\Microsoft Office\Office10\WINWORD.EXE".&nbsp; This
+  program must be set up to accept the path of the RTF file as the
+  sole command-line argument.
+</p>
+
+<p>
+  On subsequent invocations of the 'Tools - Open With External
+  Viewer...' menu item, you will not be asked to choose the program
+  again.&nbsp; If you wish to change programs, you must either
+  manually edit your <tt>my_thdl_preferences.txt</tt> file or use
+  'Edit - Clear Preferences'.
 </p>
 
 <p>
@@ -308,8 +456,6 @@ target="_blank">Tibetan Computer Company Keyboard #2</a></li>
 <li><a
 href="http://iris.lib.virginia.edu/tibet/tools/jskad_docs/Sambhota_keymap_one.rtf"
 target="_blank">Sambhota Keymap One</a></li>
-
-<li>Pre-alpha ACIP keyboard.</li>
 </ol>
 
 <p>
@@ -367,11 +513,17 @@ The following are some common problems:
 </p>
 
 <ul>
-<li><b>I get garbage when I type Tibetan.</b>
+<li><b>I can't open a document I converted using Jskad.&nbsp; It opens
+fine in Microsoft Word, but not in Jskad itself.</b>
 
-<br>This shouldn't happen now that the fonts are bundled inside
+<br>Java's RTF support is poor, so when Jskad converts a document,
-Jskad's JAR.&nbsp; But if it does, make sure the TibetanMachineWeb fonts
+e.g. from Tibetan Machine to Tibetan Machine Web, sometimes Jskad
-are installed.&nbsp; See <a href="#install">Running Jskad</a>.
+cannot open the Tibetan Machine Web output.&nbsp; Microsoft Word can
+open it, though.&nbsp; The solution is to do any further work on the
+hard-to-handle document from within Jskad's converter (i.e., the
+converter that comes up when you choose 'Tools - Launch
+Converter...').&nbsp; You might have luck with opening the
+hard-to-handle document in MS Word and saving as RTF.</li>
 
 <p><li><b>When I paste Tibetan into another application, it shows up
 as garbage like <tt>0C-&lt;m=-0+{;-{</tt>.</b>
@@ -383,7 +535,7 @@ into doesn't support RTF copying and pasting.&nbsp; To work around
 this latter problem, try pasting into an application that does support
 RTF copy and paste (such as Microsoft Word), and then select the
 Tibetan from there, copy it again, and paste into the third
-application.
+application.</li>
 
 <p><li><b>The vowels don't look right.</b>
 
@@ -392,7 +544,7 @@ href="http://developer.java.sun.com/developer/bugParade/bugs/4498203.html"
 target="_blank">Java Bug Id 4498203</a>, Tibetan vowels do not display
 properly in some versions of Java.&nbsp; Problematic versions include
 1.3.0-02, 1.3.1, and the 1.4 beta 2.&nbsp; Uninstall Java, and
-reinstall Java 1.4.&nbsp; The vowels should look better.
+reinstall Java 1.4.&nbsp; The vowels should look better.</li>
 
 <p><li><b>I can't convert from Wylie to Tibetan.</b>
 
@@ -403,18 +555,27 @@ sure you aren't using any illegal characters such as Microsoft Word's
 'smart quotes'.&nbsp; If smart quotes occur in your Microsoft Word
 document, you can eliminate them by choosing the 'Save As Text Only'
 option under 'Save'.&nbsp; Be warned that 'Save As Text Only With Line
-Breaks' does not remove smart quotes.
+Breaks' does not remove smart quotes.&nbsp; Finally, be aware that
+there are known bugs with the Wylie-to-Tibetan conversions; you may
+have run into a bug.</li>
 
 <p><li><b>I opened up an RTF document in Jskad and some of the formatting was lost.</b>
 
 <br>Java's RTF support has some problems.&nbsp; Therefore not all
 formatting information will be retained when an RTF file is opened in
-Jskad.
+Jskad.</li>
 
 <p><li><b>Jskad runs slow or is error-prone on my Mac.</b>
 
 <br>We are aware of this problem, and hope that things will get better
-as both Jskad and Apple's implementation of Java improve.
+as both Jskad and Apple's implementation of Java improve.</li>
+
+<p><li><b>I get garbage when I type Tibetan.</b>
+
+<br>This shouldn't happen now that the fonts are bundled inside
+Jskad's JAR.&nbsp; But if it does, make sure the TibetanMachineWeb fonts
+are installed.&nbsp; See <a href="#install">Running Jskad</a>.</li>
+
 </ul>
 
 <p>