XyWrite Keyboard Documentor v.2 (2022-10-18)
********************************************

This is the second much improved version of my XyWrite Keyboard Documentor. As in version 1, there are two command-line Windows programs: KBD2KT.EXE and KT2KBD.EXE. Both programs are designed to work in the same directory as the input and output files. If installed as an optional component of the XyWrite Update or Service Pack, they reside in the XyWrite folder for easy access.

KBD2KT.EXE
========== 

Syntax: KBD2KT filename[.kbd] (extension optional)

Mandatory limitation of .KBD file format in TABLES section:

NNN=kbd_commands (= normal setting(s) for key NNN, LAST ONE ACTIVE!)
;NNN=comment (= commented-out line(s) at key position NNN)
;END (or ;EOF) optionally as last line

These appear as follows in the KT file:

40-chr-long-explanatory_prefix:;KB;                     (Section before tables as is)           
40-chr-long-explanatory_prefix:KEYS=105                 (Section before tables as is)
Unshift------------+----------:TABLE=                   (Table lines with horizontal line)
40-chr-long-explanatory_prefix: 99=                     (added blank line when no line with that number in table)
40-chr-long-explanatory_prefix: 99=comment              (from ;99=comment)
40-chr-long-explanatory_prefix: 99=kbd_commands         (from 99=kbd_commands, inactive)
40-chr-long-explanatory_prefix: 99=kbd_commands         (from 99=kbd_commands, inactive)
40-chr-long-explanatory_prefix:99=kbd_commands          (from 99=kbd_commands, ACTIVE)
CAS===========================:;END OF KBD FILE         (Last line with double line and end comment text uppercased if it begins with ;END or ;EOF)

The end result looks like this when converted back to KBD file with KT2KBD.EXE (lines with a preceding space are not carried over):

;KB;                            (Section before tables as is)           
KEYS=105                        (Section before tables as is)
TABLE=                          (Table line as is)
99=kbd_commands                 (from 99=kbd_commands, ACTIVE; any lines preceded by space in KT file dropped)
;END OF KBD FILE                (Last line as is if it begins with ;end or ;eof)

The .KBD file used as input must stick to the above format due to automatic numerical sorting of each TABLE section of the .KBD file. Automatic sorting means that all keys and comment lines with the same number are gathered together, thus avoiding multiple inadvertent key definitions. It means also that you can use as input .KBD files which have NNN= key definitions and/or ;NNN= comment lines in any order within a table. It is important to notice that when there are multiple normal setting(s) for key NNN, the last one in the table is left active, others are commented out by KBD2KT.EXE for clarity. Explicitly made ;NNN= comment lines always precede the actual key definition. To keep the comments preceded by ; in their proper places, the syntax of KBD2KT.EXE requires that there is only one ; sign followed key number NNN and = sign, ALL THIS WITHOUT INTERVENING SPACES! However, there is one derogation from this, strings ';END' or ';EOF' are allowed on the last line.

KBD2KT.EXE produces a file in .KT Keyboard Documentor text format. In this version, KBD2KT is more capable than before, it adds shift-state modifier labels as appropriate. KBD2KT recognizes the following shift state names: UNSHIFT (which is blank), ALT, CTRL, SHIFT, CAPS, KAPS, MENU, HOTKEY, CYR and GREEK; the latter two are reserved for Cyrillic and Greek with CYR+SHIFT and GREEK+SHIFT, too). Usual combinations in any order (e.g. CTRL+ALT, CTRL+ALT+SHIFT, etc.) are also supported, they show as formatted labels (e.g. CtrlAlt) or even multiple labeling separated by a comma (e.g. CTRL+ALT+SHIFT,ALT+SHIFT becomes CAS,AS). It is also possible to use any other names for tables (e.g. German users can use STRG for CTRL, STRG+ALT shows as a STRGALT label; LATVIAN+SHIFT shows as LATVIANSH). When converted to a KT label, the maximum total length of a custom KBD table name is limited to 10 (when it contains a + sign) or 9 characters (without a +), any surplus characters are truncated in the custom KT label. KBD2KT does not overwrite an existing .KT file with the same basename. Instead, you have to rename, move or delete the corresponding .KT file before proceeding. KBD2KT and KT2KBD have a line length limitation of 500 characters net (i.e. without the 40 character long prefixed comment) (if you require more, contact the author for a custom version). Both programs can handle more key definitions than the 105 normally present in .KBD files.

After running KBD2KT, the .KT file can be edited by XyWrite but an external editor can be even better particularly if XyWrite produces error messages when the file is called on screen. EditPad programs (both Pro and Lite which is free) have even a syntax-coloring scheme for these files (download it from EditPad site https://bit.ly/3rxvSzg or from inside EditPad, Options, Configure file types, Colors and syntax tab). In EditPad or Notepad++, configure the .KT files as IBM ASCII (CP437). If there are characters missing from a shift-state section, empty disabled key definitions will be supplied for easier editing. Remove the space between the colon and key number to enable the key definition. You can store alternative key definitions by duplicating the line in question and putting a space in front of the disabled key definition. This is better than commenting-out with a semi-colon as these lines do not clutter the actual .KBD file. Note that if you accidentally put two or several definitions with the same number in a table without commenting them out, the last one prevails. Always use overtype to add descriptions to the prefixed columns of the .KT file, otherwise the .KT file may become corrupt.

With the advent of the XyWrite Service Pack, this utility can be used to prepare CP-specific .KBD files. Make a copy of the standard US XyWrite 4 keyboard file, prepare a .KT file, and fill it in using Insert, Special Character or Insert, Accents menus of the CP-specific variant of your choice.

By appending new table definitions to the end of an existing .KBD file (see below) and running KBD2KT blank tables with all the key positions will be prepared for you to fill in with new character definitions. (New tables need also new shifting key definitions, e.g., CYR=84,T:R makes the PrintScreen key a toggle for Russian and displays an 'R' when on). 

Enter in .KBD file:
TABLE=CYR
TABLE=CYR+SHIFT

And you will get this in .KT after running KBD2KT:
Cyr-------------------+----------------:TABLE=CYR
Cyr       Esc         |                : 1=
Cyr       1           |                : 2=
etc.

CyrShift--------------+----------------:TABLE=CYR+SHIFT
CyrShift  Esc         |                : 1=
CyrShift  1           |                : 2=
etc.

KT2KBD.EXE
==========

Syntax  : KT2KBD filename[.kt] (extension optional)

KT2KBD.EXE prepares a ready-to-use .KBD file by removing the prefixed columns of the .KT format and stripping out disabled key definitions (i.e. those with a space between the colon and the key number). First KT2KBD backs up the target .KBD file to .BAK if a .KBD file with the same name exists. Then it writes a new .KBD file. As KT2KBD is designed to be run after each modification of keyboard definitions, it overwrites an existing .KBD file without warning.

File included for testing and playing around before committing yourself to this approach: empty.kbd. Run 'KBD2KT empty' to prepare a simple KT file, add key definitions to ": nnn=" lines and enable them by removing the space in ": nnn=". Then run KT2KBD empty to make a new version of empty.kbd.

A ready-to-use KT file that corresponds to the KBD file of the product installed is also available in the XyWrite installation folder.

Contact:
********

Contact me if you have questions or suggestions: Kari Eveli (lexitec@lexitec.fi)

Download location for this package: http://www.lexitec.fi/xywrite/utility.html
It can also be added via vDosPlus XyWrite Update (v. 5.02) or vDosPlus XyWrite Service Pack (v. 5.03) installers as an optional component.

Have fun!

****
