This is mule-ucs.info, produced by makeinfo version 4.6 from
mule-ucs.texi.

START-INFO-DIR-ENTRY
* Mule-UCS::                Lisp-based Unicode support for Emacsen.
END-INFO-DIR-ENTRY

   This file documents the XEmacs package distribution of Mule-UCS, a
package providing efficient Lisp-based coding support (specifically,
Unicode) for Emacs and XEmacs.

   Copyright (C) 1997 MIYASHITA Hisashi Copyright (C) 2001, 2002 Free
Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "Copying" and "GNU General Public License"
are included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.


File: mule-ucs.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)

Mule-UCS User Manual
********************

Mule-UCS is a character code translator.  It provides functions to
translate from any character set to any other, and construct new coding
systems easily.  It requires the MUltiLingual extensions to Emacs
(MULE), including extended CCL facilities.  These functions are
provided by XEmacs (versions 21.2.36 and later), GNU Emacs (versions
20.3 and later), Emacs patched to use Mule 3.0, and Meadow.

   Mule-UCS was designed and implemented by Miyashita Hisashi (HIMI)
<himi@bird.scphys.kyoto-u.ac.jp>

   This is version $Revision: 1.6 $ of the Mule-UCS manual, last
updated on 25 January 2002.  It documents the XEmacs package
distribution of Mule-UCS.  It should be applicable to other versions of
Mule-UCS with slight changes.  Please report errors and variations
among platforms to Stephen Turnbull <stephen@xemacs.org>, for
incorporation in future versions of this manual.

   IMPORTANT NOTE; Mule-UCS translates from Unicode to XEmacs' internal
Mule encoding, and vice-versa.  This internal encoding does not have a
mapping for every Unicode code point, so if you are using any code point
that is remotely obscure, there's a good chance it will be trashed, and
you will lose data.  Examples of such code points are U+264A WHITE
SMILING FACE and U+201A SINGLE LOW-9 QUOTATION MARK, the latter as often
used in Central Europe.

   Mule-UCS is discussed on the mailing lists for Mule at `m17n.org'.

* Menu:

* Copying::                     Mule-UCS Copying conditions.
* Overview::                    What Mule-UCS can and cannot do.

For the end user:
* Obtaining Mule-UCS::          How to obtain Mule-UCS.
* History::                     History of Mule-UCS
* Installation::                Installing Mule-UCS with your (X)Emacs.
* Configuration::               Configuring Mule-UCS for use.
* Design of Mule-UCS::          How it works.

For the developer:


File: mule-ucs.info,  Node: Copying,  Next: Overview,  Prev: Top,  Up: Top

Mule-UCS Copying conditions
***************************

Copyright (C) 1998, 1999, 2000 Free Software Foundation, Inc.

   This file is part of the XEmacs distribution of Mule-UCS.

   Mule-UCS 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, or (at your option) any
later version.

   Mule-UCS 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 XEmacs; see the file COPYING. If not, write to the Free
Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.


File: mule-ucs.info,  Node: Overview,  Next: Obtaining Mule-UCS,  Prev: Copying,  Up: Top

An overview of Mule-UCS
***********************

After the installation of Mule-UCS into your Emacs, you will be able to
access Unicode files transparently.  All that is needed is to load the
`un-define' library.  Mule-UCS implements rather low-level functions,
and once loaded, the user should never notice that coding systems
implemented via Mule-UCS are any different from those implemented in C
or CCL.

   Mule-UCS contains large tables, and takes about 4 seconds to load on
a 450MHz Pentium III notebook.  Thus if your use of Unicode is at all
regular, it is recommended that the Mule-UCS Unicode coding systems be
loaded by including

     (require 'un-define)

in your init file.  Otherwise, you must load `un-define' by hand, using
`load-library'.  Also, by default XEmacs does not autodetect Unicode.
For the most common case, UTF-8, include

     (set-coding-priority-list '(utf-8))
     (set-coding-category-system 'utf-8 'utf-8)

in your init file.  UTF-8 has a very characteristic signature; false
negatives and positives should be very rare.

   Autodetecting 16-bit wide-char versions of Unicode is not currently
implemented in XEmacs itself.  Mule-UCS provides some utilities in the
`un-tools' library, but these are of unknown reliability.

   Since Mule-UCS uses regular Mule code internally, and does not
create an internal Mule charset for UCS, your normal input methods,
whether native (Wnn), Lisp + backend (new Tamago), all in Lisp (Quail),
or XIM-based (kinput2) should work with Unicode files without any
change in your setup or habits.  Input methods supported by terminals
(cxterm, localized keyboards) should also work (if they work on the
native Chinese!) as long as the terminal coding system is set properly
by `set-terminal-coding-system'.

   Mule-UCS was written by a Japanese and thus gives priority to
Japanese by default.  This means that Unicode characters that are
unified from various Asian character sets (eg, the single horizontal
stroke meaning "one" is present in all of them) will be presented in
the Mule buffer as Japanese characters, and displayed with a Japanese
font.  _No information will be lost or corrupted_ as long as you _save
back to Unicode_.  (That's what "unification" means.)

   However, if you wish to use Mule-UCS to translate Unicode to national
subsets other than ASCII, Latin-1, and Japanese, you must change the
priorities.  This also allows you to satisfy cultural preferences for
glyph styles by defaulting to an appropriate font.  Use
`un-define-change-charset-order'.  For the common case of the Latin
character sets, where by international standard as well as common
practice characters common to more than one character set are considered
identical (not "unified" as for the Han characters in Unicode), the
`latin-unity' package will probably be of use.

   (Mule-UCS does not understand Plane 14 tags.  Therefore attempts to
translate multilingual texts into non-Unicode encodings such as ISO 2022
will have to be done by hand.)

   That is all that most users of Mule-UCS need to know--but make sure
you've read the warning at the start of this document about losing data!

   Mule-UCS is still under development and any problems you encounter,
trivial or major, should be reported to the Mule-UCS developers.  Use
the standard package bug address <mule-ucs-bugs@xemacs.org>.

Behind the scenes
.................

This section tries to explain what goes on behind the scenes when you
visit a file encoded in Unicode with Mule-UCS.

   #### to be written


File: mule-ucs.info,  Node: Obtaining Mule-UCS,  Next: History,  Prev: Overview,  Up: Top

Obtaining Mule-UCS.
*******************

Mule-UCS is freely available on the Internet and the latest release may
be downloaded from `ftp://ftp.m17n.org/pub/mule/Mule-UCS/'. This
release includes the full documentation and code for Mule-UCS, suitable
for installation.  The current version is 0.84 `KOUGETSUDAI', and is in
the file `Mule-UCS-0.84.tar.gz'.

   For the especially brave, Mule-UCS is available from CVS. The CVS
version is the latest version of the code and may contain incomplete
features or new issues. Use these versions at your own risk.

   Follow the example session below:

     $ cvs -d:pserver:anonymous@cvs.meadowy.org:/cvsroot login
     (Logging in to anonymous@cvs.meadowy.org)
     CVS password: <RET>
     ...
     
     $ cvs -z3 -d:pserver:anonymous@cvs.meadowy.org:/cvsroot co mule-ucs

   You should now have a directory `mule-ucs' containing the latest
version of Mule-UCS. You can fetch the latest updates from the
repository by issuing the command:

     $ cd mule-ucs
     $ cvs update -d

   Mule-UCS is also available as an XEmacs package.  *Note Packages:
(xemacs)Packages.


File: mule-ucs.info,  Node: History,  Next: Installation,  Prev: Obtaining Mule-UCS,  Up: Top

History of Mule-UCS
*******************

Development was started in late 1997.  The earliest net releases were
done in about July 1999.


File: mule-ucs.info,  Node: Installation,  Next: Configuration,  Prev: History,  Up: Top

Installing Mule-UCS into Emacs or XEmacs
****************************************

Since Mule-UCS is only an Emacs Lisp library, you have only to
byte-compile `*.el' files and install them to the location refered by
`load-path'.

   You can use `mucs-comp.el' at the top directory.  Enter the
following command line:

     emacs(xemacs) -q --no-site-file -batch -l mucs-comp.el

   If you use Meadow, enter the following:

     Meadow95(NT) -q --no-site-file -batch -l mucs-comp.el

   Then you will obtain byte-compiled emacs-lisp files.  Finally, you
should install the files in the lisp directory to your `site-lisp'
directory.


File: mule-ucs.info,  Node: Configuration,  Next: Design of Mule-UCS,  Prev: Installation,  Up: Top

Configuring Mule-UCS for use
****************************

if your use of Unicode is at all regular, it is recommended that the
Mule-UCS Unicode coding systems be loaded by including

     (require 'un-define)

in your init file.  Otherwise, you must load `un-define' by hand, using
`load-library'.  Also, by default XEmacs does not autodetect Unicode.
For the most common case, UTF-8, include

     (set-coding-priority-list '(utf-8))
     (set-coding-category-system 'utf-8 'utf-8)

in your init file.  UTF-8 has a very characteristic signature; false
negatives and positives should be very rare.

   Autodetecting 16-bit wide-char versions of Unicode is not currently
implemented in XEmacs itself.  Mule-UCS provides some utilities in the
`un-tools' library, but these are of unknown reliability.

   That is all that most users of Mule-UCS need to know--but make sure
you've read the warning at the start of this document about losing data!


File: mule-ucs.info,  Node: Design of Mule-UCS,  Prev: Configuration,  Up: Top

Design goal
***********

MULE-UCS is a character code translator system.  I set the goal of this
system as follows.

_map character codepoint._
     MULE-UCS have to map character codepoint fast, and give a flexible
     way to change mapping policy.

_utilize character codetables_
     MULE-UCS can handle multiple codepoint tables, and then reorganize
     many character set.

_generate coding system._
     MULE-UCS can generate coding systems from your own translation
     rule.  Of course including a CCL to convert font codepoint.

   MULE-UCS has the following supplementary features.

   * Very biased (`:-P') MULE-INTERNAL and ISO-10646 translator. and
     ISO-10646 coding-system.

   * Convertor tables from text representation to MULE-UCS awarable
     emacs lisp representation.

   MULE-UCS overview.

   MULE-UCS consists of these modules mainly.

  1. Association compiler.

  2. Table organizer.

  3. CCL generator.

_Association compiler._
     On MULE-UCS, codepoint mapping rule is described by association
     list(alist).  Association compiler generate table set from an
     assocation list for encoding and decoding.  Association compiler
     also optimize tables.

_Table organizer._
     Table Organizer can



Tag Table:
Node: Top1257
Node: Copying3243
Node: Overview4182
Node: Obtaining Mule-UCS7807
Node: History9014
Node: Installation9248
Node: Configuration9972
Node: Design of Mule-UCS11021

End Tag Table
