DOUBLE BYTE CHARACTERS MAP FOR OS/2
| Version 1.4 (released 2010-02-20)

| DBCSMAP is a fairly simple character map program that is designed to support
| double-byte characters.  That is to say, it supports both Unicode (Plane 0)
| text plus as a number of specific East Asian codepages.

  Conventional OS/2 character map programs support only single-byte characters,
  which is generally sufficient for Western languages, but suddenly becomes
| inadequate when you need access to the vast Unicode character set, or writing
| systems like Chinese, Japanese, or Korean (collectively known as 'CJK').
| DBCSMAP is designed to fill in this gap.


REQUIREMENTS:

  DBCSMAP should work on OS/2 Warp 4 and higher, or OS/2 Warp 3 with the latest
| FixPaks installed.  IBM APAR PJ31908 for PMMERGE.DLL (applicable to Warp 4 
| and up) is strongly recommended due to a codepage switching bug in earlier 
| versions (see below under "Bugs/Limitations").

| You must have a font installed which contains the characters you want to see.
| So you need either a Unicode font with comprehensive CJK support (which is 
| recommended), or else specific fonts for Korean, Chinese, and/or Japanese, in
| order to be able to view those respective character sets.  By default, 
  DBCSMAP will attempt to use the Unicode font "Times New Roman MT 30", which
  should be present on most OS/2 systems.  (Under Warp 4 and Warp 3, this may
  require you to install IBM Java 1.1.8, which includes this font.)

  Since WSeB, OS/2 comes with several other Unicode fonts capable of displaying
  many double-byte characters.  "Times New Roman WT xx" is a proportional serif
  font, and "Monotype Sans Duospace WT xx" is a monospaced sans-serif font.
  You can also get comprehensive Unicode fonts from other sources; commonly-
  encountered ones include "Bitstream Cyberbit" and "Arial Unicode MS".

  Obviously, whatever application you paste the character into must be capable
  of displaying characters in the selected DBCS codepage, and should be using
  a font containing that character.

  Refer to the program help for more information.


INSTALLATION

  Copy DBCSMAP.EXE to any directory, and either run it from there or create a
  program object for it.  Copy DBCSMAP.HLP to a directory on your HELP path.

  NOTE: if you want to use the Korean codepage 949 with this program, you may
  wish to obtain the updated codepage 949 available from Ken Borgendale's OS/2
  Internationalization website (http://www.borgendale.com/uls.htm).


USAGE

  When you run DBCSMAP.EXE, you will see a 256-cell character grid on the right
  side of the window, and a set of controls on the left.  These are described in
  detail in the program help; to summarize briefly:

  * The "Encoding" panel allows you to select the codepage (character encoding);
    use the "Leading byte" selector to view double-byte characters beginning
    with the specified (hexadecimal) byte value.  The range of available leading
    bytes varies depending on the current codepage.

  * The "Selected character" panel shows an enlarged image of whatever character
    is currently selected (if any), with the byte values corresponding to that
    character shown immediately below (in both hexadecimal and decimal formats).
    (If the character is coloured dark blue instead of black, it indicates that
    it had to be rescaled down slightly in order to fit into the preview panel.)

| * The "Copied characters" panel provides some clipboard controls, including a
|   preview of the current clipboard buffer contents.

  You can change the font used for character display through the "Options" menu.


Copying and Pasting Characters

  The first time you copy a character to the clipboard after starting DBCSMAP,
  any previous clipboard contents will be replaced.  However, DBCSMAP remembers
  characters that have already been copied since it was started, and appends
  newly-copied characters onto the previous ones.  The "Clear" button erases
| the current clipboard contents; the "Delete" button erases only the last
| character.
 
| (Note that if you use an external program to clear or replace the clipboard
| contents while DBCSMAP is running, any characters previously copied with
| DBCSMAP will reappear the next time you copy a character, unless you use the
| "Clear" button as well.)
 
  Each character is copied as a raw multi-byte value representing its semantic
  value in the currently-selected codepage (if it exists); if the option is
| enabled, they are also copied as Unicode UCS-2 values in a format supported
| by Mozilla and OpenOffice.org (2.4 and up).  See the program help for
| detailed information (including examples).

  When you paste copied characters into another application, they will be
  rendered according to whatever codepage and font that application is using.
  (If these aren't capable of displaying the characters, you will most likely
  see only meaningless gibberish).

  Rich Walsh's "CPPal" utility (available on Hobbes) is very handy for forcibly
  setting a PM application's codepage on the fly.  Be warned, though, that some
  PM controls (especially MLEs) don't handle switching from an SBCS to a DBCS
  codepage like this very well.


NOTE FOR FREETYPE/2 USERS

  If you use recent versions (1.20 and later) of the FreeType/2 replacement
  TrueType font driver, you should enable the "force Unicode encoding" option
  by running the UNIENC.CMD script that comes with the driver.

  These versions of FreeType/2 implement some special logic to try and work 
  around some problems with CJK character handling under DBCS versions of 
  OS/2.  As a side effect, however, many non-ASCII characters may not display 
  correctly (or at all) if either
   - the current font is not a Unicode font.
   - the current process codepage is DBCS (e.g. 932, 949), and you are 
     attempting to view characters from a different codepage (e.g. Unicode).

  In addition, these versions typically disable Unicode encoding entirely if
  the font has fewer than 3,072 glyphs.  This may also result in non-ASCII
  (or at least non-UGL) glyphs failing to display.

  Enabling FreeType/2's "force Unicode" option eliminates these problems.

  Note that the above does not apply to version 1.10 from Michal Necasek 
  (although his last release may also disable Unicode encoding for fonts with
  fewer than 2,048 glyphs).


BUGS/LIMITATIONS

  * You cannot currently select a bitmap font for display.

  * If you select a non-Unicode font with a specific CJK encoding (e.g. PMJPN,
    PMKOR, BIG5, etc.) then characters will only display correctly under the
|   corresponding codepage.  Also, the characters will not display at all in
|   the clipboard viewer, which always uses Unicode for display.  Unicode
|   characters will only display correctly if you use a Unicode font (which 
|   is recommended).

| * The preview panel showing the current clipboard contents does not currently
|   support scrolling; once the visible area has filled up with characters, no
|   further characters can be seen.  In addition, a maximum of 512 characters
|   can be displayed in this control.

  * You will not be able to display characters under codepages which are not
    installed on your system (as may be the case for 938 and 944).  You can
    install missing DBCS codepage(s) from the \OS2IMAGE\FI\FONTS directory of
    the WSeB/MCP/ACP/eCS CD-ROM.

| * If you do not have a version of PMMERGE.DLL with BLDLEVEL 14.106 or
|   higher, you may be affected by a bug in Presentation Manager's Unicode
|   font support.  Specifically, after running DBCSMAP (or any other program
|   which changes the message-queue codepage internally) a large number of
|   times, non-ASCII characters will suddenly cease to be displayed properly
|   throughout the system.  If this problem occurs, only rebooting will resolve
|   it.

    This is caused by a bug in PMMERGE.DLL which seems to be triggered by using
|   Unicode fonts specifically.  There are two solutions that I am aware of:
|     - As mentioned, install IBM APAR PJ31908 (available to registered 
|       eComStation users), which provides a fix; this is recommended.
      - Alternatively, enabling DBCSMAP to use the Innotek Font Engine (tested 
        with v2.60) apparently circumvents enough of PM's normal code to render
        it immune.  (This does have the side effect of slightly slowing down 
        rendering, but on modern systems it should be barely noticeable.)  You
        can do this (if the Font Engine is installed) by opening the OS/2
        Registry Editor and adding a new key called "dbcsmap.exe" under
        "HKEY_LOCAL_MACHINE\SOFTWARE\InnoTek\InnoTek Font Engine\Applications".
        Under that key, add a new DWORD value called "Enabled", and set its 
        value to 0x00000001 (1 decimal).


TODO

  * Improve the clipboard preview window with a scrollbar, etc.
  * Add an "Edit" menu.
  * Add an option to view information about the current font.
  * (Possibly) Support bitmap fonts.


HISTORY

| 1.4 (2010-02-20)
|  * New clipboard viewer control.
|  * Renamed 'Copy' button to 'Add' in order to clarify its behaviour with 
|    respect to the (now-visible) clipboard buffer.
|  * Added 'Delete' button to delete one character from the clipboard (the
|    Backspace key now also does this).
|  * Changed program icon.
|  * Some other minor GUI tweaks.

  1.3 (2007-05-19)
   * Tweaked glyph sizing & positioning logic within preview panel.
   * Various fixes & improvements to font selection logic.  Selection of bitmap
     fonts is now disabled entirely.
   * Fixed loading of default help panel.

  1.21 (2007-03-28)
   * A failure to switch codepages no longer causes the program to exit.

  1.2 (2007-03-22)
   * Invalid secondary-byte values for the CJK codepages are now identified; 
     the corresponding character cells are shaded in grey.
   * Various DBCSMAP settings (including window size/position, font, and the
     current codepage selections) are now saved.
   * Some minor cosmetic tweaks.

  1.1 (2007-03-15)
   * The individual CJK codepages now render text directly, instead of
     converting it into Unicode first.  This should allow non-Unicode CJK
     fonts to display correctly under their own codepages.
   * Now using UniQueryUconvObject() instead of DosQueryDBCSEnv() to identify
     valid leading-byte values.  This fixes the "garbled text" problem that
     some earlier versions had with codepage 949.

  1.0 (2007-02-24)
   * Some more (very minor) code cleanup.
   * Implemented online help.

  0.9 (2007-02-08)
   * Massive internal code cleanup and optimization.
   * Rewrote codepage logic to use Unicode conversion APIs instead of
     WinSetCp().  This MAY reduce the frequency of the "codepage switching"
     bug, although it won't eliminate it entirely.
   * Glyphs should now be correctly centred in their cells.
   * Major improvements to font sizing logic.  Should now look good on most,
     if not all, resolutions.
   * Fixed bug with control resizing when restoring from minimized state.
   * Implemented the hooks for online help (but no actual help file yet)...
   * Removed most English language dependencies from code (for potential
     future internationalization support).
   * "Clear" button now disables/enables itself when appropriate (I hope).
   * Fixed the program icon appearance for low resolutions.

  0.8 (2007-02-04)
   * Data is now also copied to the clipboard under the "text/unicode" format.

  0.7 (2007-02-01)
   * Multiple characters can now be copied at once.
   * Unicode is now rendered using UPF-8 (a.k.a. "PM Unicode", codepage 1207).
     This remedies previous problem with slow Unicode text rendering.
   * Replaced the glyph preview window with a custom control that avoids bugs
     in static text control.
   * Now overriding PM valueset text rendering in character grid control (i.e.
     owner draw) to fix display bugs with Unicode text.
   * Restored "style" selector to font dialog.
   * Significant internal code cleanup.

  0.6 (2007-01-03)
   * Added codepage 1208 (UTF-8).
   * F3 now exits the program.
   * A few other improvements here and there.

  0.5 (2006-04-02)
   * Double-clicking on a character now copies it to the clipboard.
   * The window is now dynamically resizeable.
   * 'Clipping' problem on high-DPI resolutions fixed.
   * The font size used in the character map control is now set dynamically
     according to the current window size.

  0.4 (2005-09-16)
   * First public release.


NOTICES

  DBCSMAP: Double Byte Character Map for OS/2 PM
  (C) 2005-2010 Alex Taylor

    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 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA