CONTENTS ======== 1. Introduction 2. Overview 3. Routines 3.1 Utility Routines 3.2 Kanji Routines 3,3 Known bugs 1. Introduction --------------- The Amiga Kanji utilities library is a set of C functions to provide C programmers easy output of character strings with kanji characters. The functions AK_Text(), AK_putchar(), AK_puts(), and AK_printf() operate similarly as their standard counterpart functions but they recognize and display strings with kanji characters in JIS X0208 ('83 or '78), EUC, or SJIS encodings. To use a program that uses the routines in the Amiga Kanji utilities library simply install the fonts. Under Kickstart 1.3, either copy the fonts in the kanji/ directory into your FONTS: directory or assign FONTS: to kanji/. Under 2.04, simply "Assign FONTS: kanji/ add". These functions was been written assuming the supplied kanji fonts would be used (i.e., the font names are hard coded into the routines). These fonts are non-proportional and the ASCII font is half as wide as the kanji fonts. If you use fonts from another system where this isn't true, it will look strange with these routines. You can replace the ASCII font if you wish. But be sure it's fixed width and that the width is at least half of the height, i.e., the 16 font should be at least 8 wide. An optional kanji configuration file, "kanji.cfg", can be in the current directory or in the S: directory. This allows setting some of the defaults for the routines. In particular, the routines will usually guess at the kanji encoding of a string, but they might incorrectly guess a string is EUC encoded when it's actually SJIS encoded because the SJIS and EUC encodings have overlapping codes. This can be overcome by setting the default encoding in the kanji.cfg file. Because of the way kanji is output to the CLI window, the CLI copy and paste under 2.0 will grab the EUC encodings for japanese text. 2. Overview ----------- The Amiga Kanji utilities consists of: kanji/ - a directory of 41 fonts for the JIS X0208 character set. These are arranged so that characters with the same 7 highest bits in their code would be in the same font. I chose this scheme because both the 1st and 2nd byte of the JIS code ranged from 32 to 127. This way, I could pack more characters per font while only needing a simple conversion from JIS to my internal character code. utils/ - source and binaries for utility programs to convert an X Window Bitmap Distribution Font to a set of Amiga fonts, and a crude kanji printing utility. AKlib/ - directory for the Amiga kanji routines which contains: AK.h - Header file for Amiga kanji routine library. This file should only be used by the internal files for the library. AK.c - source code for the kanji routines. AK_con.c - source code for routines to find the CLI Console and it's window. These were copied and modified from ConPackets.c from source examples found on the Fish disks. AK_globals.h - header files for programs that will use the kanji routines. This contains the global variables access by the routines. Be sure this is only included once. Makefile lmkfile - Makefiles for Lattice and gcc The basic way the kanji is displayed to the standard output: - get the JIS code for the character. - find and load the font for the character. - get the current position of the cursor to figure out where to draw the kanji character. - print ASCII character for EUC bytes of the kanji character (these are just blanks in the ASCII font). - draw the kanji character in the space. Printing ASCII blanks under the kanji moves the cursor so that the standard output functions (putchar(), puts(), printf()) can still be used together with the kanji routines. Note about the ASCII Fonts: the fonts in the directory kanji/ascii are used as the ASCII fonts. They are defined for the ASCII characters (i.e. characters 32 to 127). Amiga characters 128 to 255 should be blank. This is because non-ASCII Amiga characters would confuse the kanji decoder. In a SJIS encoding, any byte > 159 is interpreted as the 1st byte of a kanji. Likewise, in EUC encoding, any byte > 127 is interpreted as a byte of a kanji. Be sure to read JIS.doc to learn more about the kanji encodings if you need to update these routines for more recent encodings. 3. Routines ----------- 3.1 Utility Routines -------------------- int AK_init(struct Window *wind, int font_size, BOOL no_kanji) Opens the libraries. Sets global vars/pointers. Loads the kanji fonts. "font_size" is the pixel height of the font to look for. This can be overridden font size set in the config file. If "no_kanji" is FALSE, all kanji fonts are opened (41 fonts total). Else if "no_kanji" is TRUE, only 3 fonts (ASCII and kana) are initially opened (the others will be opened on demand). If only low level output, AK_Text(), is going to be used, then the Window shoould be passed in "wind". Otherwise, the console window and ConUnit will be looked for. Returns -1, if there was a problem. ===== void AK_cleanup(STRPTR message); Shutdown: close libraries and fonts. "message" is an optional message to print to the standard error output. ===== int AK_getconfig(void); Get settings from the configuration file (S:kanji.cfg or kanji.cfg) Call this routine after AK_init()! Returns -1 if there was a problem, 0 otherwise. ===== *** private routines, don't worry about these *** LONG findWindow(void); LONG sendpkt(); Copied from ConPackets.c. These are used by AK_init() to find the window and ConUnit of the current CLI and set global variables AK_window and AK_conUnit. ===== 3.2 Kanji Routines ------------------- int AK_strlen(unsigned char *astr); Returns the number of printable characters in a kanji string. A kanji character counts as 2 characters. This is useful for figuring out the actual displayed length of the string. For JIS encodings, the special sequences don't count as printable characters. ===== int AK_putchar(unsigned short ch); Print a character (ASCII or kanji) to the standard output. Note that "ch" is a 16-bit (2 bytes) value. Returns EOF if there was a problem. ===== int AK_puts(unsigned char *astr); Print a string follow by a newline to the standard output. Note that "astr" is a string of 'unsigned' bytes. Returns EOF if there was a problem. ===== int AK_printf(char *format, ...); Formatted output. Functions the same as "printf" but strings can have kanji characters in them. Returns EOF if there was a problem. ===== void AK_Text(struct RastPort *rp, unsigned char *astr, int len); Print a text string in a rastport. "rp" is the RastPort to output to. "astr" is the string to output. "len" is the number of characters from the string that will be printed. ===== AK_kanji_type AK_guess_encoding(STRPTR a_str); Guess the encoding of a string (JIS, EUC, SJIS). This function might incorrectly guess a string is EUC encoded when it's actually SJIS encoded because the SJIS and EUC encodings have overlapping codes. Returns the type of encoding. ===== void AK_get_cursor_pos(int *xpix, int *ypix); Sets the global variables AK_ccol and AK_crow to the current cursor position. Converts the current kanji cursor position to pixel coordinates. The coordinates are returned in 'xpix' and 'ypix'. The calculations assume that the ASCII font, AK_font[0], is the default font for the console. ===== int AK_decode_char(unsigned char *jbyte1, unsigned char *jbyte2, unsigned short rawcode, AK_kanji_type encoding); Decode a character to two JIS bytes. "rawcode" should be the 2-byte (16 bit) value of 1 character. "encoding" specifies the type of kanji encoding of the "rawcode" value. The JIS code for the character is returned in "jbyte1" and "jbyte2", "jbyte is the high order byte. If the "rawcode" isn't valid, -1 is returned. ===== * private, your shouldn't need to directly use * int _AK_char(struct RastPort *rp, unsigned short ch); Print a single text char in rastport. "rp" is the RastPort to output to. "ch" is the JIS character to output. AK_Text() repeatedly calls this function to output a string. ===== * private, your shouldn't need to directly use * int _AK_prtstr(unsigned char *astr); Prints a kanji string. Guesses at the encoding of the string, if currently unknown. Figures out when to print 1-byte as an ASCII character or 2-bytes as a kanji character. Calls AK_putchar() repeatedly to print the string. AK_puts() and AK_printf() call this function. AK_Text() works nearly identically as this function. 3.3 Known bugs. ------------------- - kana/kanji are not refreshed properly in a CLI window because kanji bitmaps are directly drawn to the window's RastPort, while blank characters are printed to the console, Intuition refreshes the kana with blanks instead. - if fonts are loaded on demand and memory runs out, the printing routines will fail to get the fonts they need and output "garbage" characters (the "out of font" character).