Initial Commit

[packages] / xemacs-packages / x-symbol / man / x-symbol.texi

\input texinfo
@c Copyright (C) 1998-2003 Free Software Foundation, Inc.
@c
@c Author: Christoph Wedler <wedler@users.sourceforge.net>
@c Maintainer: (Please use `M-x x-symbol-package-bug' to contact the maintainer)
@c Keywords: WYSIWYG, LaTeX, HTML, wp, math, internationalization
@c X-URL: http://x-symbol.sourceforge.net/

@c %**start of header
@setfilename x-symbol.info
@settitle X-Symbol Manual
@setchapternewpage odd

@set edition 4.5.2
@set version 4.5.1
@set update December 2003
@set url http://x-symbol.sourceforge.net
@set maintainer wedler@@users.sourceforge.net
@set listdevel x-symbol-devel@@lists.sourceforge.net

@set imagemagickurl http://www.imagemagick.org/
@set proofgeneralurl http://proofgeneral.inf.ed.ac.uk
@set sgmlentitiesurl http://www.w3.org/TR/REC-html40/sgml/entities.html

@c for cross references to other manuals
@ifset GNU
@set subedition Emacs
@set emacs emacs
@set emacsman GNU Emacs Manual
@end ifset

@ifclear GNU
@set subedition XEmacs
@set emacs xemacs
@set emacsman XEmacs User's Manual
@end ifclear

@set auctex auctex
@set auctexman AUC@TeX{}

@set reftex reftex
@set reftexman Ref@TeX{} User Manual

@set kpathsea kpathsea
@set kpathseaman Kpathsea Manual

@syncodeindex fn vr
@c %**end of header
@dircategory Editors
@direntry
* X-Symbol::      Semi WYSIWYG for LaTeX, HTML and other "token languages"
@end direntry

@ifnottex
This file documents X-Symbol, a package providing semi-@sc{wysiwyg} for
La@TeX{}, HTML and other ``token languages''.  It uses additional fonts
and provide input methods to insert their characters into your document.

This is Edition @value{edition} (@value{subedition}) of the X-Symbol
Manual for X-Symbol @value{version}, @value{update}.

Copyright (c) 1998-2003 Free Software Foundation, Inc.

@c default
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.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
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.
@c end default
@end ifnottex

@finalout
@titlepage
@title X-Symbol Manual
@subtitle Semi-@sc{wysiwyg} for La@TeX{}, HTML and other ``token languages''
@subtitle Edition @value{edition} (@value{subedition}), for X-Symbol @value{version}, @value{update}
@author by Christoph Wedler

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998-2003 Free Software Foundation, Inc.

@c default (slight change)
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 that the
entire resulting derive 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.
@c end default

@end titlepage

@c ===========================================================================

@ifnottex
@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up
@top X-Symbol

When you edit La@TeX{}, HTML, BibTeX or @TeX{}info sources in Emacs,
package X-Symbol provides some kind of @sc{wysiwyg} by using real
characters for tokens like @code{\oplus} or @code{&trade;}.  It also
provides various input methods to insert these characters.  Thumbnails
for included images and real super-/subscripts and are also supported.

The first part of this master menu lists the major nodes in this Info
document, including the indexes.  The rest of the menu lists all the
lower level nodes in the document.

This is Edition @value{edition} (@value{subedition}) of the X-Symbol
Manual for X-Symbol @value{version}, @value{update}.  For recent
changes, see @ref{News}.

Bug fixes, bug reports, improvements, and suggestions are strongly
appreciated.  If you want to contact the maintainer of package X-Symbol,
please read @ref{Bug Reports}.
@end ifnottex

@menu
* Introduction::                Introduction to X-Symbol.
* Installation::                What to do before using package X-Symbol.
* Concepts::                    Token language, conversion, coding, etc.
* Input Methods::               How to insert X-Symbol characters.
* Features::                    Super-/subscripts, images, info, etc.
* Supported Languages::         Details of the predefined token languages.
* X-Symbol Internals::          How package X-Symbol works.
* Problems::                    Annoyances, contacting the maintainer.
* History::                     Changes, wishlist, projects.
* Indexes::                     Menus covering various topics.

@detailmenu
 --- The Detailed Node Listing ---

Introduction

* Copying::                     X-Symbol is GPL'd.
* Summary::                     A brief summary of package X-Symbol.
* About::                       About this manual.

Installation

* Requirements::                Which programs you need for X-Symbol.
* Installing Files::            Basics 1: Put the files into your home dir.
* System-wide Installation::    Alternative:  Put the files into the XEmacs dir.
* Installing Lisp::             Basics 2: Initialize X-Symbol during startup.
* Installing Image Converter::  Recommended: How to install @code{convert}.
* Package Integration::         How X-Symbol interacts with other packages.
* Installing Fonts::            Optional: What to do when using other fonts.
* Installing Fonts Exceed::     If appropriate: What to do when using Exceed.
* Installing Fonts Lisp::       If appropriate: Lisp coding for other fonts.
* Installing Manual::           Optional: How to create the manual.
* Checking Installation::       Is package X-Symbol completely installed?

Package Integration

* LaTeX Packages::              Packages used in La@TeX{} buffers.
* Syntax Hiliting Packages::    Package @code{font-lock} and support modes.
* File IO Packages::            Compression, encryption, remote files, etc.
* Miscellaneous Packages::      Other packages.

Concepts of Package X-Symbol

* Token Language::              What does a X-Symbol character represent.
* Conversion::                  Decoding tokens, encoding characters.
* Minor Mode::                  How to control the behavior of X-Symbol.
* Poor Mans Mule::              Running X-Symbol under XEmacs/no-Mule.
* Role of font-lock::           Why does X-Symbol need @code{font-lock}.
* Char Group::                  Character group and token classes.

Conversion: Decoding and Encoding

* Default Coding::              Normal File and Default Encoding.
* File Coding::                 Specific encoding of a file.
* Controlling 8bit Coding::     Do you want to store 8bit characters?
* Unique Decoding::             Restrict decoding to avoid normalization?
* Conversion Commands::         Interactive encoding and decoding.
* Copy with Conversion::        Copy & paste with conversion.
* Char Aliases::                Different charsets include the same chars.

X-Symbol's Input Methods

* Introducing Input Methods::   Common behavior of all input methods.
* Input Method Token::          Replace token by character.
* Input Method Read Token::     Minibuffer input with completion.
* Input Method Menu::           Select a menu item.
* Input Method Grid::           Choose highlighted character.
* Input Method Keyboard::       Compose a key sequence.
* Input Method Context::        Replace character sequence.
* Input Method Electric::       Automatically replace character sequence.
* Input Method Quail::          A Mule input method "x-symbol".
* Customizing Input Method::    How to customize the input methods.

Features of Package X-Symbol

* Super and Subscripts::        Use special fonts for super-/subscripts.
* Images::                      Images after image insertion commands.
* Info::                        Display information in echo area.
* Ascii Representation::        Derive label from a buffer contents.
* Package Information::         Invoke info system, use WWW browser.

Images at the end of Image Insertion Commands

* Image Display::               When to display images.
* Image Conversion::            Producing a scaled-down image.
* Image Caching::               Speeding up the image processing.
* Special Images::              Signaling specific situations.
* Image Editor::                Editing the original image file.

Supported Token Languages

* Pseudo Language::             Token language ``x-symbol charsym''.
* TeX Macro::                   Token language @code{tex}.
* SGML Entity::                 Token language @code{sgml}.
* BibTeX Macro::                Token language @code{bib}.
* TeXinfo Command::             Token language @code{texi}.
* External Languages::          Languages defined in other Emacs Packages.

Token Language ``@TeX{} macro'' (@code{tex})

* TeX Macro Basics::            Basics of language ``@TeX{} macro''.
* TeX Macro Features::          Super-/subscripts and images in La@TeX{}.
* TeX Macro Problems::          Problems with @TeX{} macros.
* TeX Macro Conversion::        How the conversion of @TeX{} macros works.
* TeX Macro Symbols::           Extra Symbols of Language ``@TeX{} Macro''.

Token Language ``@sc{sgml} entity'' (@code{sgml})

* SGML Entity Basics::          Basics of Language ``@sc{sgml} entity''.
* SGML Entity Features::        Super-/Subscripts and Images in @sc{html}.
* SGML Entity Conversion::      How the conversion of @sc{sgml} entities works.

X-Symbol Internals

* Char Representation::         How X-Symbol represents X-Symbol chars.
* Defining Charsets::           How X-Symbol defines additional chars.
* Defining Input Methods::      How X-Symbol defines the input methods.
* Extending X-Symbol::          How to add fonts and token languages.
* Various Internals::           How X-Symbol handles other aspects.
* Design Alternatives::         Why X-Symbol is not designed differently.
* Language Internals::          How X-Symbol handles languages.
* Misc Internals::              Various.  TODO.

Defining Input Methods

* Input Method Objectives::     Input methods should be intuitive/consistent.
* Intro Char Descriptions::     An example introducing char descriptions.
* Char Descriptions::           The aspects and the contexts of a character.
* Example Char Descriptions::   A complete example defining input methods.
* Customizing Input Methods::   How to customize the input methods.

Extending Package X-Symbol

* Extending with Fonts::        How to add fonts to X-Symbol.
* Input Definitions::           Guidelines for input definitions.
* Font Definition File::        How to define new character in a file.
* Language Extension File::     Extending an existing language.
* Language Definition File::    Defining a new language.

Various Internals

* Tagging Insert Commands::     Don't break input methods Token and Electric.
* Avoiding Flickering::         Moving cursor in invisible commands.

Design Alternatives

* Alt Token Representations::   Why we need the conversion.
* Alt Global Mode::             How to turn on X-Symbol globally.
* Alt Auto Conversion::         When do we convert automatically.

Problems, Troubleshooting

* Nomule Problems::             X-Symbol provides a @emph{poor} man's Mule.
* Spurious Encodings::          Some commands turn off X-Symbol mode.
* No Encoding::                 The encoding does not work in a rare case.
* FAQ::                         Frequently asked questions.
* Bug Reports::                 How to contact the maintainer of X-Symbol.

Frequently Asked Questions

* FAQ XEmacs Core::             XEmacs crashes when using input method Token
* FAQ font-lock::               X-Symbol's fontification does not work.
* FAQ Strange Chars::           The buffer contains strange characters
* FAQ No Subscripts::           I cannot see any/some super-/subscripts.
* FAQ Stupid Subscripts::       I see subscripts where I don't want them.
* FAQ Font Size::               The characters are too small or too big.
* FAQ Conversion::              The conversion changes some tokens.
* FAQ Additional Spaces::       A space is added during the encoding.
* FAQ 8bit Chars::              I do not want 8bit characters in the file.
* FAQ Hyphen::                  I cannot distinguish @code{hyphen} from @samp{-}.
* FAQ Spell Check::             I have problems with spell-checking.
* FAQ News and Mail::           I want to use X-Symbol in Gnus or @sc{vm}.

History and Projects

* News::                        Changes in recent versions.
* Wishlist::                    Projects for X-Symbol.
* Open Questions::              How you can contribute.
* Acknowledgments::             People having contributed.

News: Changes in Recent Versions of X-Symbol

* Changes New::                 To be announced.
* Changes 4.5::                 Released Mar 2003 as beta.
* Changes 4.4::                 Released June 2002 as beta.
* Changes 4.1::                 Released Mar 2002 as beta.
* Changes 3.4::                 Released Mar 2002.
* Changes 3.3::                 Released Jan 1999.
* Changes 3.2::                 Released Dec 1998.
* Changes 3.1::                 Released Oct 1998.
* Changes 3.0::                 Released Sep 1998 as beta.
* Changes Old::                 Overview of old releases.

Wishlist: Projects for X-Symbol

* Wishlist Languages::          Additional token languages.
* Wishlist Fonts::              Automatically generated fonts.
* Wishlist Emacs::              Changes in Emacs/XEmacs.
* Wishlist LaTeX::              Changes in La@TeX{}.
* Wishlist Various::            Other changes.
* Wishlist Rejected::           Rejected Suggestions for X-Symbol.

Indexes

* Key Index::                   Key sequences.
* Program Index::               Programs and Emacs packages.
* Variable Index::              Commands, functions, variables.
* Concept Index::               Various topics.

@end detailmenu
@end menu

@c ===========================================================================

@node  Introduction, Installation, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction
@cindex Overview
@cindex Introduction

When you edit La@TeX{}, HTML, BibTeX or @TeX{}info sources in Emacs,
package X-Symbol provides some kind of @sc{wysiwyg} by using real
characters for tokens like @code{\oplus} or @code{&trade;}.  It also
provides various input methods to insert these characters.  Thumbnails
for included images and real super-/subscripts and are also supported.

@menu
* Copying::                     X-Symbol is GPL'd.
* Summary::                     A brief summary of package X-Symbol.
* About::                       About this manual.
@end menu

@c ====================================================================

@node Copying, Summary, Introduction, Introduction
@comment  node-name,  next,  previous,  up
@section X-Symbol's Copying Conditions: GPL
@cindex Copying
@cindex Copyright
@cindex GPL
@cindex General Public License
@cindex License
@cindex Warranty

(This text is stolen from the @TeX{}info manual, Edition 4.0).

The programs currently being distributed that relate to X-Symbol include
Emacs Lisp files and X11 font files.  These programs are @dfn{free};
this means that everyone is free to use them and free to redistribute
them on a free basis.  The X-Symbol related programs are not in the
public domain; they are copyrighted and there are restrictions on their
distribution, but these restrictions are designed to permit everything
that a good cooperating citizen would want to do.  What is not allowed
is to try to prevent others from further sharing any version of these
programs that they might get from you.

Specifically, we want to make sure that you have the right to give away
copies of the programs that relate to X-Symbol, that you receive source
code or else can get it if you want it, that you can change these
programs or use pieces of them in new free programs, and that you know
you can do these things.

To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute
copies of the X-Symbol related programs, you must give the recipients
all the rights that you have.  You must make sure that they, too,
receive or can get the source code.  And you must tell them their
rights.

Also, for our own protection, we must make certain that everyone finds
out that there is no warranty for the programs that relate to X-Symbol.
If these programs are modified by someone else and passed on, we want
their recipients to know that what they have is not what we distributed,
so that any problems introduced by others will not reflect on our
reputation.

The precise conditions of the licenses for the programs currently being
distributed that relate to X-Symbol are found in the General Public
Licenses that accompany them.

@c ====================================================================

@node Summary, About, Copying, Introduction
@comment  node-name,  next,  previous,  up
@section Brief Summary of X-Symbol
@cindex Summary
@cindex Brief Summary
@cindex X-Symbol in a Nutshell

@itemize @bullet
@item
X-Symbol provides a @strong{minor mode} which make use of characters in
the Latin-1, Latin-2, Latin-3, Latin-5, and Latin-9 font (179 chars +
294 char aliases), the Adobe symbol font (109 chars) and the xsymb1 font
(165 chars, distributed with the package).  Additional fonts could be
used easily.

@item
These characters are used in the buffer to represent @strong{tokens}
(e.g., @TeX{} macros, @sc{sgml} entities, more ``token languages'' could be
added easily) in the file.  The @emph{conversion} is done automatically
when visiting the file, saving the buffer and turning the minor mode
on/off.

@item
Defines 8 @strong{input methods} for these characters: @emph{Menu},
@emph{Grid} (selecting a character with the mouse), @emph{Keyboard},
@emph{Context} (replace/modify similar-looking char sequence),
@emph{Electric} (automatic replace), @emph{Quail} (a Mule input method),
@emph{Token} (replace token by corresponding char), @emph{Read Token}
(completing minibuffer input of token).

@item
Offers some @strong{info} in the echo area for these characters (e.g.,
that the character under point represents the TeX macro @code{\leadsto}
and that the macro is defined in La@TeX{} package @file{latexsym.sty}).

@item
Allows to use a @strong{8bit file encoding} which is different from your
"normal" 8bit file encoding, e.g., you can visit @TeX{} files with
@code{\usepackage[latin5]@{inputenc@}} even if you normally use a Latin-2
font.

@item
Provides a kind of ``@strong{poor man's Mule}'' when running on an
XEmacs without Mule support: it can @emph{display} more than 256
characters via @code{font-lock} and removes most annoyances resulting
from the fact that, without Mule support, many ``X-Symbol characters''
are actually a sequence of two chars.

@item
Provides fonts for single-line innermost @strong{super-} and
@strong{subscripts} to be displayed with per-buffer control. The
invisible part, like @code{<sub>} in HTML, is revealed at point.

@item
Displays thumbnails for @strong{images} at the end of image insertion
commands with per-buffer control (e.g.,
@code{\includegraphics@{@var{file}@}} in La@TeX{}, @code{<img
src=@var{file}>} in HTML).  They show a scaled-down version of the
included image files (using @code{convert} from
@uref{@value{imagemagickurl},ImageMagick}).  A single mouse click
on the image or command invokes the image editor for the corresponding
image file.

@item
It @emph{does not} and @emph{will not} provide commands to hide (more or
less) uninteresting parts of your document or fontify them differently.
This is more the task of the corresponding major mode or
@code{font-lock}, e.g., @code{font-latex}.  (I admit, the support of
super- and subscripts might let you think that this is a good point for
the todo list of package X-Symbol.)  Using @code{outline-minor-mode} or
folding might also be an alternative.
@end itemize

If you prefer a more @sc{wysiwyg}-like document processor, you should
probably use @code{LyX} or @code{GNU TeXmacs}.  Here are some reasons
why you would use Emacs/XEmacs with package X-Symbol instead:

@itemize @bullet
@item
You have complete control over the La@TeX{} source.  X-Symbol supports
more characters.

@item
You can read any La@TeX{} source and you write normal La@TeX{} code,
i.e., package X-Symbol does not use any special format.

@item
It also supports HTML and @TeX{}info documents and BibTeX entries.

@item
You can use your favorite editor, i.e., Emacs or XEmacs.
@end itemize

@c ====================================================================

@node About,  , Summary, Introduction
@comment  node-name,  next,  previous,  up
@section About this Manual
@cindex About
@cindex Web Pages
@cindex Info Pages
@cindex Manual
@cindex Online Help

Apart from this manual, there are two other sources of information about
X-Symbol:

@itemize @bullet
@item
The web pages of X-Symbol provide a summary of X-Symbol, including some
screen shots.  You are strongly encouraged to read them carefully.  They
probably provide enough info for the standard user and can be found at:

@display
  @uref{@value{url}/}
@end display

@item
The online help for commands (functions) and user options (variables) is
quite technical.  It is shown during customization and when using Emacs'
Help menu.
@end itemize

This manual is somewhere in between: it more detailed than the web pages
and less technical than the online help.  For example, when explaining
some functionality, it states the default behavior, gives an impression
of what can be customized, and it even lists all related user options,
but it does not describes the technical format of possible values of
each option.

If you want to learn something about X-Symbol's internals, e.g., if you
want to define your own token language, see @ref{X-Symbol Internals}.

This manual does not explain Emacs in general or some optional programs
used by this package such as @code{convert} (used to produce the image
thumbnails).  It also includes no installation instructions for those
programs and the author of this package will not help you with the
installation of those programs (sorry for that).

You do not have to learn this manual by heart before sending a question
to the maintainer of X-Symbol, but you should give the impression that
your really have tried to find the necessary information yourself and
spend some time making your report precise.  Before sending a problem
report, please read @ref{Bug Reports}.

@c ===========================================================================

@node Installation, Concepts, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Installation
@cindex Installation

The short version of the installation instructions for package X-Symbol
on XEmacs is: uncompress & extract the @emph{binary distribution} in
directory @file{~/.xemacs/xemacs-packages/}, add
@code{(x-symbol-initialize)} to your @file{~/.emacs} and install
ImageMagick for the image support (unless you want to get a warning).

Please check the web page @emph{additionally} to the sections here for
the installation instructions for package X-Symbol on Emacs.

The rest of this chapter contains the long version.  I recommend that
you read this chapter completely after a short test of X-Symbol,
especially if you have customized your Emacs more or less heavily or if
you get some problems.

@menu
* Requirements::                Which programs you need for X-Symbol.
* Installing Files::            Basics 1: Put the files into your home dir.
* System-wide Installation::    Alternative:  Put the files into the XEmacs dir.
* Installing Lisp::             Basics 2: Initialize X-Symbol during startup.
* Installing Image Converter::  Recommended: How to install @code{convert}.
* Package Integration::         How X-Symbol interacts with other packages.
* Installing Fonts::            Optional: What to do when using other fonts.
* Installing Fonts Exceed::     If appropriate: What to do when using Exceed.
* Installing Fonts Lisp::       If appropriate: Lisp coding for other fonts.
* Installing Manual::           Optional: How to create the manual.
* Checking Installation::       Is package X-Symbol completely installed?
@end menu

@c ====================================================================

@node Requirements, Installing Files, Installation, Installation
@comment  node-name,  next,  previous,  up
@section Requirements
@cindex Requirements
@cindex Binary Package
@cindex Source Package
@cindex Old Version
@cindex Window System
@cindex X
@cindex Windows
@cindex MS-Windows
@cindex Character Terminal
@cindex TTY
@pindex Emacs
@pindex XEmacs

This development version of package X-Symbol works with Emacs-21.1 or
higher, and XEmacs 20.4 or higher (XEmacs-21.1.9 is strongly
recommended, @ref{FAQ XEmacs Core}), with or without Mule support.

X-Symbol should work with all window systems Emacs is running under (Mac
is not testet and might not work).  Under X, no restrictions apply.
Under Windows with Emacs, images will not be displayed (they are not yet
supported by Emacs under Windows).  Under Windows with XEmacs, X-Symbol
just supports a limited number of characters (Latin-1, Latin-5, and half
the math symbols) and no super- and subscripts, due to missing
MS-Windows fonts (@pxref{Wishlist Fonts}).  Under a character terminal,
X-Symbol just supports Latin-1 characters only, no super- and subscripts
and no images.

@pindex font-lock
@pindex lazy-shot
@pindex texmathp
@pindex auctex
This package require package @code{font-lock} (distributed with Emacs
and XEmacs), the use of package @code{lazy-shot} is recommended, see
@ref{Syntax Hiliting Packages}.

@pindex convert
If you want to see the images at the end of image insertion commands,
install @code{convert} from
@uref{@value{imagemagickurl},ImageMagick},
see @ref{Installing Image Converter}.  They show a scaled-down version
of the included image files.

@pindex makeinfo
@pindex texi2dvi
@pindex latex2html
If you want to produce the Info files yourself (they are included in the
binary distribution), you need @code{makeinfo}, Version 1.68 or higher.
If you want to produce a PS file from the manual, you need
@code{texi2dvi}.  If you want to produce an HTML version of this manual,
you need @code{texi2html}, Version 1.62 or higher.  @xref{Installing
Manual}.


@c ====================================================================

@node Installing Files, System-wide Installation, Requirements, Installation
@comment  node-name,  next,  previous,  up
@section Put the Files into your Home Directory
@cindex Basic Installation
@cindex Uncompress Tarball
@cindex Extract Tarball
@cindex Tarball
@cindex Binary Distribution

If you use Emacs, please check the @uref{@value{url}/news.html,web pages
of X-Symbol}.

In this section, we assume that you want to install the binary
distribution (also called the binary tarball) of package X-Symbol in
your home directory.  To install it somewhere below the XEmacs root (it
might be already there), see @ref{System-wide Installation}.  If you use
the source distribution, you should know what do to instead.

In directory @file{~/.xemacs/xemacs-packages/}, run
@example
zcat x-symbol-pkg.tar.gz | tar xvf -
@end example

Remember that @code{tar} does not overwrite write-protected files.

X-Symbol's @file{pcf} files and font directory must be world-readable 
since you do not own the X11 font server process.  You are on the safe
side, if you run
@example
chmod -R a+rx ~/.xemacs/xemacs-packages
@end example

If package X-Symbol has been installed system-wide and you install a
newer version in your @file{~/.xemacs/xemacs-packages/}, you get a warning during
XEmacs' startup (autoload error: already loaded).  You can safely ignore
this warning, but there is unfortunately no good way to get rid of it.
Yes, XEmacs' packaging system is excellent, but there is still a place
for improvements@dots{}.

Before XEmacs-21.0: the user package directory was @file{~/.xemacs/}
instead of @file{~/.xemacs/packages/}; also: delete and recompile the
@file{.elc} files.

@c ====================================================================

@node System-wide Installation, Installing Lisp, Installing Files, Installation
@comment  node-name,  next,  previous,  up
@section System-wide Installation: Put the Files into the XEmacs Directory
@cindex System-wide Installation
@cindex Installing System-wide
@cindex @file{default.el}
@cindex @file{site-start.el}

You can skip this section if your have installed X-Symbol in your home
directory according to the previous section.

If you install package X-Symbol system-wide, use @file{default.el} and
@file{@var{xemacs}/site-packages/} whenever @file{~/.emacs} and
@file{~/.xemacs/xemacs-packages/} are mentioned in the previous or
following subsections.  @file{@var{xemacs}/site-packages/} is the
directory of independent packages for XEmacs.

Under XEmacs-21, you can uncompress and extract the tarball by

@example
M-x package-admin-add-binary-package @key{RET} @var{dir}/x-symbol-pkg.tar.gz
@end example

Then, @file{@var{xemacs}/} is the default directory of buffer
@file{*Package Output*} (use @kbd{C-x C-f} in that buffer to see it).
It might be @file{/usr/local/lib/xemacs/xemacs-packages/} (the first
element in variable @code{late-packages}).

Under XEmacs-20, @file{@var{xemacs}/} might be
@file{/usr/local/lib/xemacs-@var{version}/}.  Here, you have to
uncompress and extract the tarball as described in @ref{Installing
Files}.  You also have to load the autoload file explicitly by putting
the following line into file @file{site-start.el}:

@lisp
(load "@var{xemacs}/lisp/x-symbol/auto-autoloads")
@end lisp

I would appreciate if you would set the following variables:

@vtable @code
@item x-symbol-installer-address
Please set this variable to your email address to catch problems which
could be solved locally.  In your private @file{~/.emacs}, you might
want to set this variable to @code{nil}.

@item x-symbol-package-url
If you have a local copy of the web pages (@pxref{Installing Manual}), set
this variable to the corresponding @sc{url}.
@end vtable

@c ====================================================================

@node Installing Lisp, Installing Image Converter, System-wide Installation, Installation
@comment  node-name,  next,  previous,  up
@section Make XEmacs Initialize X-Symbol During Startup
@cindex Installing Lisp
@cindex Lisp Installation
@cindex Elisp Installation
@cindex @file{.emacs}
@findex x-symbol-initialize

Put the following into your @file{~/.emacs} (or @file{~/.xemacs/init.el}):

@lisp
(x-symbol-initialize)
@end lisp

Basically, that's it!  If your XEmacs runs on a different machine, check
@ref{Installing Fonts}.

If you get a warning about X-Symbol not being able to deduce a default
encoding (or about limited support with XEmacs under Windows or a
character terminal, @ref{Requirements}), set the default coding
(@pxref{Default Coding}) by putting the following in front of the line
above:

@lisp
(setq x-symbol-default-coding 'iso-8859-1)
@end lisp

When running Emacs under a character terminal, you might need to use the
following (with or without X-Symbol):

@lisp
(unless window-system (standard-display-european 1))
@end lisp

If your character terminal does not support Latin characters, there is
no reason to use package X-Symbol.  In this case, use the following
instead:

@lisp
(when window-system (x-symbol-initialize))
@end lisp

The initialization can be controlled by the following variable:

@vtable @code
@item x-symbol-initialize
By default, package X-Symbol does a full initialization.  This includes
an integration with some packages, see also @ref{Package Integration}.
@end vtable

If you use a B/W monitor and XEmacs/no-Mule, it might be necessary to
remove the font properties of any face which is used on regions with
X-Symbol characters: @code{isearch}, @code{highlight},
@code{primary-selection}, @code{secondary-selection},
@code{paren-match}, @code{paren-mismatch}, @code{paren-blink-off},
@code{underline}.  I.e., for each @var{face}, use:

@lisp
(remove-specifier (get (get-face '@var{face}) 'font))
@end lisp

@c ====================================================================

@node Installing Image Converter, Package Integration, Installing Lisp, Installation
@comment  node-name,  next,  previous,  up
@section Installing the Image Converter from ImageMagick
@cindex Installing Image Converter
@cindex Installing @code{convert}
@cindex Image Converter Installation
@cindex @code{convert} Installation

@pindex convert
Program @code{convert} from ImageMagick is used to display images at the
end of image insertion commands.  The images show a scaled-down version
of the included image files.

@vindex x-symbol-image-converter
While the installation of @code{convert} is optional, you get a warning
if @code{convert} is not found on your system or if there is no image
format supported by both @code{convert} and Emacs.  Set variable
@code{x-symbol-image-converter} to @code{nil} if you don't want to get
the warning.

@vindex x-symbol-image-convert-program
On Unix, @code{convert} must be in your @code{$PATH}.  On Windows, it is
assumed to be found at @file{C:\ImageMagick\convert}.  If this is not
the case, you have to customize the variable
@code{x-symbol-image-convert-program}.

Check @uref{@value{imagemagickurl}} for the installation
instructions.  Run @samp{convert -h} and @samp{convert -list Format} (in
newer versions of ImageMagick) in your shell to check whether the
installation of ImageMagick was successful.  If you have problems, check
the ImageMagick web page for FAQs and mailing lists.
@comment ImageMagick-5.0..5.37 failed to show formats sometimes

If you do not have a truecolor device (i.e., just 256 colors), package
X-Symbol uses @code{convert} with a colormap by default (@pxref{Image
Conversion}).  You might create and use your own colormap instead.  It
should be tuned to include the colors you use in Emacs anyway, i.e., the
face colors.

@c ====================================================================

@node Package Integration, Installing Fonts, Installing Image Converter, Installation
@comment  node-name,  next,  previous,  up
@section Package Integration
@cindex Package Integration
@cindex Integrating Package
@cindex Other Packages

You might skip this section when trying package X-Symbol the first time.
Nevertheless, I strongly recommend to read this section if you have
customized your Emacs more or less heavily or if you get some problems.

Some features of X-Symbol work by hooking itself into existing functions
of Emacs or related packages via predefined hooks.  A potential problem
arises if your customization or other packages use the same hooks, or if
other packages assume these hooks not to be used, e.g., some packages
assume the buffer contents to contain the same characters as the
corresponding file.

This section lists some special adaptation for other packages
(everything is fine if you do not use these packages).  It also lists
potential problems in combination with other packages.  If you discover
some problems in combination with other packages, please let me know.

@menu
* LaTeX Packages::              Packages used in La@TeX{} buffers.
* Syntax Hiliting Packages::    Package @code{font-lock} and support modes.
* File IO Packages::            Compression, encryption, remote files, etc.
* Miscellaneous Packages::      Other packages.
@end menu


@node LaTeX Packages, Syntax Hiliting Packages, Package Integration, Package Integration
@comment  node-name,  next,  previous,  up
@subsection La@TeX{} Packages
@cindex La@TeX{} Packages
@cindex Integrating La@TeX{} Packages

Objectives: relate positions in buffer to positions in file, do
conversion in master/slave buffers, preserve highlighting, improve input
methods and other things.

@table @code
@item auctex
@pindex auctex
@pindex texmathp
@findex TeX-next-error
@vindex TeX-translate-location-hook
@findex x-symbol-tex-error-location
Use Version 9.9c or higher, which includes @code{texmathp}.  There is
some special X-Symbol adaptation for Auc@TeX{}:

@itemize @minus
@item
@vindex TeX-master
X-Symbol supports Auc@TeX{}'s multifile documents: it respects the
variable @code{TeX-master} when searching for the file encoding
(@pxref{File Coding}) and when converting image files with relative
names (@pxref{Image Display}).

@item
@vindex TeX-region-hook
X-Symbol supports Auc@TeX{}'s region commands: it ensures that
characters in @file{_region_.tex} buffer are converted according to the
parent buffer.  Initialization changes @code{TeX-region-hook}.  Requires
Auc@TeX{}, v9.8a or higher.

@item
X-Symbol's input method Electric (@pxref{Input Method Electric}) with
token language @code{tex} uses package @code{texmathp}.

@item
@vindex LaTeX-math-insert-function
Auc@TeX{}'s math mode commands also inserts X-Symbol characters
(@pxref{Mathematics,,,
@value{auctex},
@value{auctexman}}).
Initialization sets @code{LaTeX-math-insert-function}.  Requires
Auc@TeX{}, v9.8a or higher.

@item
@findex TeX-next-error
@vindex TeX-translate-location-hook
If @TeX{} displays an error message, it also displays the context of the
error position.  Auc@TeX{} uses the context to set point to this
position when @kbd{M-x TeX-next-error} is invoked.  The former context
are characters in the file, the latter characters in the buffer,
X-Symbol provides the translation.  Initialization changes
@code{TeX-translate-location-hook}.
@end itemize

@item bib-cite
@pindex bib-cite
Use Version 3.0 or higher.  Initialization of package X-Symbol changes
the installation of package bib-cite to make X-Symbol's decoding not
overwrite @code{bib-cite}s highlighting of @code{\cite} and friends.

@item preview-latex
@pindex preview-latex
@findex x-symbol-tex-preview-locations
@TeX{}'s error positions are also used by package @code{preview-latex},
which was clever enough to reuse the above mentioned hook of Auc@TeX{}.
Unfortunately, that hook is @dots{} and does not allow a fast translation of
error positions, so @code{preview-latex} allows to provide better
variants of functions in that hook.  X-Symbol's variant is
@code{x-symbol-tex-preview-locations}.

@item reftex
@pindex reftex
@vindex reftex-translate-to-ascii-function
Use Version 3.26 or higher.  For a workaround for some minor annoyances
with the combination Ref@TeX{}/X-Symbol/Multifile Document, see
@ref{Problems and Work-arounds,,,@value{reftex},@value{reftexman}}.  By
default, the initialization of package X-Symbol makes Ref@TeX{}'s label
creation use the nicer Asciification of package X-Symbol (@pxref{Ascii
Representation}) by setting @code{reftex-translate-to-ascii-function}.

@item whizzytex
Use the newest.
@end table


@node Syntax Hiliting Packages, File IO Packages, LaTeX Packages, Package Integration
@comment  node-name,  next,  previous,  up
@subsection Syntax Highlighting Packages (@code{font-lock} and add-ons)
@cindex Syntax Highlighting Packages
@cindex @code{font-lock} Packages
@cindex Integrating @code{font-lock} Packages

Objectives: start highlighting after conversion.  Highlighting is
needed for super- and subscripts and when using XEmacs without Mule
support.

@table @code
@item fast-lock
@pindex fast-lock
@vindex fast-lock-save-faces
I recommend to use package @code{lazy-shot} instead.  By default, the
initialization of package X-Symbol sets @code{fast-lock-save-faces} to
@code{nil} to make package @code{fast-lock} work with X-Symbol.

@item font-latex
@pindex font-latex
@vindex font-lock-maximum-decoration
I suggest to set @code{font-lock-maximum-decoration} to value @code{t},
2 or higher if you do not want to use super- and subscripts in arguments
of @code{\label} and friends.  @xref{FAQ Stupid Subscripts}.

@item font-lock
@pindex font-lock
@vindex font-lock-auto-fontify
Is required by this package (@pxref{Role of font-lock}).  I strongly
recommend @emph{not} to turn on font-lock in @emph{any} mode hook, set
@code{font-lock-auto-fontify} to @code{t} instead (this is the default,
anyway).  See also @code{lazy-shot}.

If you turn on font-lock in a mode-hook, visiting a file would become
slower, since X-Symbol mode is usually turned on @emph{after} the
functions in the mode hook have been run, i.e., the fontification is
getting useless if the tokens are automatically decoded.

@item lazy-lock
@pindex lazy-lock
From XEmacs-20.3 on, the successor is called @code{lazy-shot}.

@item lazy-shot
@pindex lazy-shot
Is strongly recommended.
@end table


@node File IO Packages, Miscellaneous Packages, Syntax Hiliting Packages, Package Integration
@comment  node-name,  next,  previous,  up
@subsection File I/O Packages
@cindex File I/O Packages
@cindex I/O Packages
@cindex Remote File Packages
@cindex Compression Packages
@cindex Encryption Packages
@cindex Integrating I/O Packages

Issue: compression, encryption and so on can be seen as some kind of
conversion.  When doing multiple conversion, the sequence matters.

@table @code
@item ange-ftp
@pindex ange-ftp
See also @code{efs} and @code{jka-compr}.

@item comint
@pindex comint
@vindex comint-input-sender
The default installation makes @code{comint}s in-/output use X-Symbol's
conversion function.  If you set variable @code{comint-input-sender},
set it before initializing package X-Symbol.

@item crypt
@itemx crypt++
@pindex crypt
@pindex crypt++
@findex save-buffer
@vindex x-symbol-auto-conversion-method
I recommend to use package @code{jka-compr} instead.  @xref{Spurious
Encodings}.  @xref{No Encoding}.  If you use @code{crypt} or  @code{crypt++} and the
character @code{alpha} looks like @samp{\233a} after @code{save-buffer},
set this variable to @code{slowest}.  @xref{Open Questions}.

@item efs
@pindex efs
XEmacs' version of @code{ange-ftp}.  See also @code{jka-compr}.

@item iso-cvt
@pindex iso-cvt
There is no need to use it.  Package X-Symbol already provides the
conversion between Latin-1 characters and ``@TeX{} macros''.  Package
X-Symbol does not provide the German and Spanish conversion tables,
though.

@item iso-sgml
@pindex iso-sgml
There is no need to use it.  Package X-Symbol already provides the
conversion between Latin-1 characters and ``@sc{sgml} entities''.
@xref{Miscellaneous Packages}, package @code{psgml-html}.

@item jka-compr
@pindex jka-compr
Can be used with package X-Symbol, preferred to @code{crypt}.  The
following is absolutely necessary (with or without using package
X-Symbol, at least in older Emacsen): load @code{jka-compr} after
@code{efs}/@code{ange-ftp}!

@item latin-unity
@pindex latin-unity
This XEmacs package can be used with package X-Symbol, functionality is already provided by
X-Symbol for Latin-@{1,2,3,5,9@} characters: remapping (@pxref{Char
Aliases}) and recoding (@pxref{File Coding}).  Has some safe-encoding
mechanism, but the test comes currently too early (@pxref{Wishlist
Emacs}).

@c TODO: test mule-ucs.el with Emacs-21.4
@item ucs-tables
@pindex ucs-tables
@findex unify-8859-on-decoding-mode
@findex unify-8859-on-encoding-mode
The Emacs minor modes @code{unify-8859-on-decoding-mode} and
@code{unify-8859-on-encoding-mode} can be used with package X-Symbol.

@item vc
@pindex vc
@findex vc-next-action
If you use package @code{crypt}, @code{vc-next-action} and friends
encode characters to tokens.  @xref{Spurious Encodings}.
@end table


@node Miscellaneous Packages,  , File IO Packages, Package Integration
@comment  node-name,  next,  previous,  up
@subsection Miscellaneous Packages
@cindex Miscellaneous Packages

@table @code
@item abbrev
@pindex abbrev
On XEmacs without Mule support, I recommend to set variable
@code{words-include-escapes} to @code{t}.  @xref{Nomule Problems}.

@item completion
@pindex completion
Should work with X-Symbol (earlier version of X-Symbol had problems with
input method token).

@item desktop
@pindex desktop
XEmacs' version (an old one) does not save its @file{.emacs.desktop}
files with a coding system.  Emacs' version save it with an incorrect
coding system.  Thus, strings which contain X-Symbol's private
characters might get corrupted.  See also package @code{session} below.

@item flyspell
@pindex flyspell
@findex global-flyspell-mode
Should work apart from the general problem of @code{ispell}.

@item func-menu
@pindex func-menu
Should work with X-Symbol.

@item ispell
@pindex ispell
The package @code{ispell} assumes the buffer contents to be the same as
the file contents and does not provide any hook to fix this.  This
should be fixed in @code{ispell}, see @ref{Wishlist Emacs}.  @xref{FAQ
Spell Check}.

@item ProofGeneral
@pindex ProofGeneral
Use a future version (hopefully v3.4).  Includes special X-Symbol
initialization/handling and defines additional token languages.
@xref{External Languages}.

@item psgml-html
@pindex psgml
@pindex psgml-html
@code{psgml-html}: Do not set @code{html-auto-sgml-entity-conversion} to
non-@code{nil}.  @xref{File IO Packages}, package @code{iso-sgml}.

@item session
@pindex session
Use Version 1.5a or higher.  If strings in this file should always be
read correctly, you should put @code{(x-symbol-init-input)} into your
@file{~/.emacs}; otherwise strings containing X-Symbol's private
characters read from the @file{~/.session} file might look funny.  See
also package @code{desktop} above.

@item x-compose
@pindex x-compose
All characters from @code{x-compose} are also supported by package
X-Symbol.  Thus, I recommend to use @kbd{@key{multi-key}} instead
@kbd{C-=} when running under XEmacs without Mule support.
@xref{Introducing Input Methods}.
@end table

@c ===========================================================================

@node Installing Fonts, Installing Fonts Exceed, Package Integration, Installation
@comment  node-name,  next,  previous,  up
@section Installing Additional Fonts
@cindex Installing Fonts
@cindex Fonts
@cindex X11 Fonts

You don't have to install X-Symbol fonts in usual circumstances (with
the binary distribution, Emacs runs on the same machine, you are happy
with the default fonts).

If your Emacs runs on a different machine, please follow the steps 5 and
6 below or read the next section.

If you want to install additional fonts (since the binary distribution
contains only a limited selection of fonts and font sizes), please
follow the following sequence which worked for me (on SunOS
5.4-5.6/Solaris).  If you have to do s.th. (completely) different on
your system, please let me know---I will include your hints.

If you are lost with the following instructions, use the standard fonts
from the binary distribution.  (Sorry, I do not have to time to answer
general Unix font questions.  Or to be more exact, I'm not an expert in
this area@dots{}.  Nevertheless, if you have a clearer explanation for
the installation sequence below, please send me a patch to
@file{man/x-symbol/x-symbol.texi}.)

@enumerate
@item
@pindex xfd
@pindex xfontsel
Find the font which you want to replace by checking fonts with the X11
program @code{xfontsel} or @code{xfd}.  The bad news is that there is no
general way to say which character belongs to which font.  My only goal
was to use standard fonts whenever possible; the rest belong the the
xsymb1 font (which I have designed).  If you want to use a font as an
alternative to another font, it must have the same charset
registry-encoding.

@item
Find the @file{.bdf} files of your preferred fonts in your file system
or by Internet search engines like Google.  The source distribution of
package X-Symbol contains @file{.bdf} files for additional fonts sizes
of all fonts except the xsymb1 font (@pxref{Wishlist Fonts}).

There are two categories of @file{.bdf} files.  The first category
contains files for fonts which are already installed; the files are
needed to create and install the super- and subscript versions.  Copy
these files to @file{~/.xemacs/xemacs-packages/etc/x-symbol/origfonts/}.  The second
category contains files for fonts which are not installed.  Copy these
files to @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/}.

@item
In file @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/Makefile},
change variables @code{ORIGBDFS} for the first category and @code{BDFS}
for the second category accordingly.

@item
@pindex perl
In directory @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/},
execute @code{make mkdirs}, and @code{make pcfs}.  You need GNUs
@code{make} and @code{perl}, Version 5 (or higher).  You might need to
check the permissions of the created files (@pxref{Installing Files}).

@item
If your Emacs runs on a different machine or if you want to use the
fonts outside Emacs, too, add X-Symbol's fonts to your font path by
inserting the following in your @file{~/.xsession} (X11 startup file).

@pindex xset
@example
xset +fp ~/.xemacs/xemacs-packages/etc/x-symbol/pcf/
@end example

For a system-wide installation, you might want to add this directory to
the system-wide font path instead.

If your system doesn't have @code{xset}, you should copy all @file{.pcf}
files (compiled fonts) from @file{~/.xemacs/xemacs-packages/etc/x-symbol/pcf/} into
directory @file{/usr/lib/X11/fonts/75dpi/} (Slackware distribution) and
run @samp{mkfontdir 75dpi} in that directory.

@item
Your are on the safe side if you restart X11 after this.

@item
Set the Emacs Lisp variables which define the fonts.  @xref{Installing Fonts Lisp}.
@end enumerate

@c ====================================================================

@node Installing Fonts Exceed, Installing Fonts Lisp, Installing Fonts, Installation
@comment  node-name,  next,  previous,  up
@section Installing Fonts for Exceed (X-server on Windows)
@cindex Installing Fonts
@cindex Fonts
@pindex Exceed
@cindex Windows
@cindex Windows
@cindex X-Server

If your X-server on Windows is Exceed and if you have configured
Exceed to use the ``native window manager'' for your Unix screens, you
must install the X-Symbol fonts on Windows.  The following works with
Exceed 6.0 & NT 4.0 and Exceed 7.0 & Windows 2000:

@enumerate
@item
In Unix, edit file @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/makesub} to limit 
the shift for superscript to 3 points:
@smallexample
%supoffs = ('08',3, 10,3, 12,3, 14,3, 16,3, 18,3, 24,3);
@end smallexample

@item
Then, execute @code{make mkdirs}, and @code{make gens} in
@file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/}.  If you have problems, please read 
the previous section.

@item
In Exceed's configuration window, click on @key{Font} to open Window
@file{Font Settings}.  In this window, click on @key{Select All}, then
on @key{Compile Fonts...}.

@item
Copy X-Symbol's @file{bdf} files in @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/}
and @file{~/.xemacs/xemacs-packages/etc/x-symbol/genfonts/} to a Windows directory
and select this directory in the Exceed Window @file{Compile Fonts}.
Click on @key{Compile}.

@item
In Window @file{Font Settings}, click on @key{Font Database...}.  In
this window, click on @key{Add...}.  Enter the output directory from the
previous step as the @samp{Font Directory} and @code{xsymb} as the
@samp{File Name (*.fdb)}.  Click on @key{OK}.

@item
You might want to rearrange the sequence of Font DB files to let files
@file{75dpi} appear prior to files @file{100dpi}, because X-Symbol's
fonts are designed for 75dpi.

@item
In Window @file{Font Database}, click on @key{Rebuild Database...} and
then on @key{OK}.
@end enumerate

Note: @emph{Windows NT 4.0 will crash (bluescreen) if you use fonts
compiled by Exceed from the @file{pcf} files or if you missed step 1,
i.e., limiting the superscript shift!}  With Exceed 7.0 & Windows 2000,
there is no crash, but these fonts cannot be displayed.

If you use XEmacs with Exceed as your X-server on Windows, X-Symbol
cannot warn you about undefined fonts, because XEmacs in general cannot
recognizes in that case, whether a font exists.

@c ====================================================================

@node Installing Fonts Lisp, Installing Manual, Installing Fonts Exceed, Installation
@comment  node-name,  next,  previous,  up
@section Lisp Coding when Using Other Fonts
@cindex Font Lisp Setup
@cindex Font Lisp Installation

Package X-Symbol needs to know which fonts to use for the X-Symbol
characters and super- and subscripts.  It also must interact with
package @code{font-lock} to display them (@pxref{Role of font-lock}).

If you have installed additional fonts (@pxref{Installing Fonts}) for
use with package X-Symbol, you might have to change the following
variables:

@vtable @code
@item x-symbol-latin1-fonts
@itemx x-symbol-latin2-fonts
@itemx x-symbol-latin3-fonts
@itemx x-symbol-latin5-fonts
@itemx x-symbol-latin9-fonts
@itemx x-symbol-xsymb0-fonts
@itemx x-symbol-xsymb1-fonts
The value of each variable consists of three elements: one for the
normal text, one for subscripts and one for the superscripts.  Each
element is a list of fonts which are tried in order---the first which
exists on your system is used.

If you change the values of one of these variables, do only specify the
same charset registry@minus{}encoding (e.g., @samp{adobe-fontspecific})
as specified by the fonts in the default value of this variable.

@item x-symbol-font-sizes
Here you can specify the sizes for all fonts in the above mentioned
variables.  The value consists of regular expressions matching font
names and numbers which replace all occurences of @samp{%d} in the
names.
@end vtable

E.g., if you prefer larger fonts, you might want to insert the following
into your @file{~/.emacs}:

@smalllisp
(setq x-symbol-font-sizes
  '(18 ("_su[bp]-" . 14) ("\\`-etl-" . 16)))
(setq x-symbol-xsymb0-fonts
  '(("-adobe-symbol-medium-r-normal-*-*-%d0-*-*-*-*-adobe-fontspecific"
     "-xsymb-xsymb0-medium-r-normal--%d-%d0-75-75-p-85-adobe-fontspecific")
    ("-adobe-symbol_sub-medium-r-normal-*-*-%d0-*-*-*-*-adobe-fontspecific"
     "-xsymb-xsymb0_sub-medium-r-normal--%d-%d0-75-75-p-74-adobe-fontspecific")
    ("-adobe-symbol_sup-medium-r-normal-*-*-%d0-*-*-*-*-adobe-fontspecific"
     "-xsymb-xsymb0_sup-medium-r-normal--%d-%d0-75-75-p-74-adobe-fontspecific")))
@end smalllisp

The first assignment changes the font sizes, the second makes X-Symbol
using the original Adobe symbol font instead of my minor modification
(appearance) of it.  The xsymb1 font will be scaled, which might not
look nice (@pxref{FAQ Font Size}).

You might want to change the following variables:

@vtable @code
@item x-symbol-latin-force-use
Package X-Symbol defines Latin characters even when the corresponding
fonts are missing (this can be changed by this variable).  Characters
for the symbol fonts are only defined if the corresponding fonts are
available.

@item x-symbol-mule-change-default-face
Package X-Symbol does not change the fonts of pre-defined Mule charsets
(this can be changed by this variable).  Thus, the variables from
@ref{Installing Fonts Lisp} might have no influence if Emacs
already has defined fonts for the corresponding charsets.
@end vtable

@c ====================================================================

@node Installing Manual, Checking Installation, Installing Fonts Lisp, Installation
@comment  node-name,  next,  previous,  up
@section Installing Info, Postscript and HTML Files
@cindex Installing Manual
@cindex Info
@cindex Texinfo
@cindex Postscript
@cindex HTML
@cindex Manual
@cindex Documentation

@pindex makeinfo
To create the info files, execute @code{make info} in directory
@file{~/.xemacs/xemacs-packages/man/x-symbol/} of the distribution.  It requires
@code{makeinfo}, Version 1.68 or higher.  This should not be necessary
if you use the binary distribution of package X-Symbol.

If no entry for X-Symbol is automatically added to the info directory
listing, add the following line to @file{~/.xemacs/xemacs-packages/info/dir}:
@smallexample
* X-Symbol::     Semi WYSIWYG for LaTeX, HTML and other "token languages"
@end smallexample


@pindex texi2dvi
Optionally, you might want to create a printed document from the @TeX{}info
file.  Execute @code{make ps} in directory @file{~/.xemacs/xemacs-packages/man/x-symbol/}
of the distribution.  It requires @code{texi2dvi}.

@pindex latex2html
Optionally, you can create an online manual for a web browser by
executing @code{make html} in directory @file{~/.xemacs/xemacs-packages/man/x-symbol/} of
the distribution.  It requires @code{texi2html}.

All formats of the manual are created by executing @code{make all}.

@c ====================================================================

@node Checking Installation,  , Installing Manual, Installation
@comment  node-name,  next,  previous,  up
@section Checking the Correct Installation of Package X-Symbol
@cindex Checking Installation
@cindex Final Installation Checks
@cindex Installation Checks

After having completed the installation, exit and restart Emacs.

@itemize @bullet
@item
Type @kbd{M-x show-message-log} to check whether you got problems so
far, e.g., whether errors occurred when loading a file.  If you do,
identity and correct the offender.

@item
Type @kbd{M-x x-symbol-grid} in buffer @file{*scratch*}.  If you get the
Grid but if you see less characters than you see on the web page of
package X-Symbol, you have decided to use other fonts but failed to
install them correctly.  This is also mentioned in buffer
@file{*Warnings*}.  @xref{Installing Fonts}.

@item
Move your mouse pointer to any X-Symbol character in buffer
@file{*X-Symbol Grid (x-symbol charsym)*}, press the right mouse button
and initialize successively all token languages.

@item
Again, type @kbd{M-x show-message-log} to check whether you got problems
so far, e.g., whether errors occurred when loading a file.  If you do,
identity and correct the offender.

@item
If buffer @file{*Warnings*} does not exist in the buffer menu,
everything is fine.  So is (for me as the author of package X-Symbol),
if @samp{X-Symbol} is not mentioned there.  If there is a warning with
@samp{no valid image converter}, you have forgotten to install
ImageMagick (@pxref{Installing Image Converter}).
@end itemize

@c ===========================================================================

@node Concepts, Input Methods, Installation, Top
@comment  node-name,  next,  previous,  up
@chapter Concepts of Package X-Symbol
@cindex Concepts
@cindex Terminology
@cindex Basics

This chapter describes the concepts of package X-Symbol.  It contains
quite a few forward references to feature which are based on these
concepts, such as @ref{Input Methods}, and @ref{Features}.

@menu
* Token Language::              What does a X-Symbol character represent.
* Conversion::                  Decoding tokens, encoding characters.
* Minor Mode::                  How to control the behavior of X-Symbol.
* Poor Mans Mule::              Running X-Symbol under XEmacs/no-Mule.
* Role of font-lock::           Why does X-Symbol need @code{font-lock}.
* Char Group::                  Character group and token classes.
@end menu

@c ===========================================================================

@node Token Language, Conversion, Concepts, Concepts
@comment  node-name,  next,  previous,  up
@section Token Language
@cindex Token Language
@cindex Language

As mentioned in the overview, ``X-Symbol Characters'' in the buffer are
represented by ``tokens'' in the file.  The correspondence between these
is determined by the @dfn{token language} which is in close relation to
the major mode of the current buffer.  E.g., character @code{alpha}
stands for @code{\alpha} in La@TeX{} buffers.

For details of predefined token languages ``@TeX{} macro'' (@code{tex}),
``@sc{sgml} entity'' (@code{sgml}), ``Bib@TeX{} macro'' (@code{bib}), and
``@TeX{}info command'' (@code{texi}), see @ref{Supported Languages}.

The token language determines the conversion between X-Symbol characters
and tokens (@pxref{Conversion}), the input methods (@pxref{Input
Methods}), and various other features (@pxref{Features}).

The token language is defined by the following buffer-local variable:

@vtable @code
@item x-symbol-language
Token language used in current buffer.  You can set this variable in the
``local variables list'' near the end of the file (@pxref{File
Variables,,,@value{emacs},@value{emacsman}}), e.g.:

@example
%% Local Variables:
%% x-symbol-language: tex
%% End:
@end example
@end vtable

Package X-Symbol uses a reasonable value according to the major mode and
the file name of a buffer if the variable is not already buffer-local.
A valid token language is required to turn on X-Symbol Minor mode, see
@ref{Minor Mode}.

A token language must be @dfn{registered}, if you want to use it.  By
default, the above mentioned token languages are registered.

@c ===========================================================================

@node Conversion, Minor Mode, Token Language, Concepts
@comment  node-name,  next,  previous,  up
@section Conversion: Decoding and Encoding
@cindex Conversion
@cindex Decoding
@cindex Encoding

As mentioned, X-Symbol characters in the buffer are represented by
tokens in the file.  Thus, we need some conversion from tokens to
characters, called @dfn{decoding}, and some conversion from characters
to tokens, called @dfn{encoding}.

We have the additional problem that some characters are not only
represented by tokens, but also via some 8bit character encoding.

Package X-Symbol supports the following 8bit character encodings:
Latin-1 (@code{iso-8859-1}), Latin-2 (@code{iso-8859-2}), Latin-3
(@code{iso-8859-3}), Latin-5 (@code{iso-8859-9}), and Latin-9
(@code{iso-8859-15}).  It currently supports less encodings with XEmacs
on Windows (@pxref{Requirements}).


@menu
* Default Coding::              Normal File and Default Encoding.
* File Coding::                 Specific encoding of a file.
* Controlling 8bit Coding::     Do you want to store 8bit characters?
* Unique Decoding::             Restrict decoding to avoid normalization?
* Conversion Commands::         Interactive encoding and decoding.
* Copy with Conversion::        Copy & paste with conversion.
* Char Aliases::                Different charsets include the same chars.
@end menu


@node Default Coding, File Coding, Conversion, Conversion
@comment  node-name,  next,  previous,  up
@subsection Normal File and Default Encoding
@cindex Default Coding
@cindex Default Encoding
@cindex Default Font
@cindex Coding, Default
@cindex Encoding, Default
@cindex Font, Default

As mentioned, some characters have a 8bit file encoding, and X-Symbol
needs to know which 8bit file encoding you use normally when visiting a
file and saving a buffer.

With Mule support, Emacs/XEmacs can recognize the @dfn{normal file
encoding}, also called a coding system (@pxref{Recognize
Coding,,,@value{emacs},@value{emacsman}}).

Without Mule support, XEmacs can usually only support 8bit characters of
one encoding; this encoding corresponds to the charset/registry of your
default font.  Here, the @dfn{normal file encoding} is the default
encoding:

@vtable @code
@item x-symbol-default-coding
The default encoding.  The value must be a symbol denoting one of the
supported encodings or @code{nil}.  The variable must be set before
X-Symbol has been initialized.  @xref{Installing Lisp}.
@end vtable

The @dfn{default encoding} is not only used to determine the normal file
encoding without Mule, but also for the following:

@itemize @bullet
@item
X-Symbol has its own mechanism to recognize a file encoding which only
works with a specified default encoding.  @xref{File Coding}.

@item
The same character can be included in various Latin charsets and
X-Symbol needs to know which of the instances (which Emacs views as
different characters) to support.  @xref{Char Aliases}.

@item
Without Mule support, the default encoding is also needed to decide
which characters have to be faked by 2 characters internally: exactly
the characters in those charsets which do not correspond to the default
encoding.  @xref{Poor Mans Mule}.
@end itemize

To deduce the default value, X-Symbol inspects the Mule language
environment and the output of the shell command @code{locale}, or to be
more exact:

@example
locale -ck code_set_name charmap
@end example

Without Mule support, you get a warning if the command does not exist on
your system or lists an encoding which is not supported by X-Symbol,
such as some Asian encoding.  Value @code{nil} is the same as
@code{iso-8859-1}.

With Mule support, you get a warning if the command lists a supported
encoding which is different from the encoding deduced from the Mule
language environment.  Value @code{nil} makes sure that X-Symbol file
encoding detection (@pxref{File Coding}) only works if Emacs has
detected the same encoding; it works like @code{iso-8859-1} otherwise.


@node File Coding, Controlling 8bit Coding, Default Coding, Conversion
@comment  node-name,  next,  previous,  up
@subsection File Coding of 8bit Characters
@cindex File Coding
@cindex Coding in File
@cindex Encoding in File
@cindex 8bit File Coding
@cindex Latin File Coding
@cindex Recoding

X-Symbol can use a different encoding for single buffers/files, even if
you use X-Symbol on XEmacs without Mule support.  To do so, set the
following buffer-local variable:

@vtable @code
@item x-symbol-coding
8bit character encoding in the file visited by the current buffer.
Value @code{nil} represents the normal file encoding (@pxref{Default
Coding}).

With Mule support, any value other than @code{nil} is considered invalid
if the normal file encoding is neither the same as this value nor the
same as the default encoding.  I.e., if your default encoding is
@code{nil}, X-Symbol's file encoding detection never takes precedence
over Emacs' one, i.e., the normal file encoding.

You can set this variable in the ``local variables list'' near the end
of the file (@pxref{File Variables,,,@value{emacs},@value{emacsman}}),
e.g.:

@example
<!-- Local Variables: -->
<!-- x-symbol-coding: iso-8859-2 -->
<!-- End: -->
@end example
@end vtable

If the variable is not already buffer-local, a reasonable value is
deduced when turning on X-Symbol (@pxref{Minor Mode}) by searching for
some language dependent headers at the beginning of the file:

@vtable @code
@item x-symbol-auto-coding-search-limit
X-Symbol usually searches for something like
@samp{\usepackage[@dots{}]@{inputenc@}} (@pxref{TeX Macro}) or @samp{<meta @dots{}
charset=@dots{}>} (@pxref{SGML Entity}) in the first 10000 characters.
@end vtable

If you choose not to save a file containing 8bit characters
(@pxref{Controlling 8bit Coding}), the file encoding is still important,
since the file might contain 8bit characters when you visit it.

If the file encoding is different to the normal file encoding, X-Symbol
performs the necessary recoding itself.  @dfn{Recoding} changes a
character with code position @var{pos} in one charset to a character
with the same code position @var{pos} in another charset.  If the normal
file encoding is different to the default encoding, X-Symbol also
resolves character aliases (@pxref{Char Aliases}).

If you have specified an invalid file encoding (including an encoding
different to a non-default normal file encoding), we have the following
cases:

@itemize @bullet
@item
If the normal file encoding is unsupported (any file encoding is invalid
in this case) or if the normal file encoding is supported and the file
does not contain 8bit characters, we always encode all X-Symbol
character (@pxref{Controlling 8bit Coding}).  The modeline includes
@samp{-i} to represent the file encoding (@pxref{Minor Mode}), except if
the default encoding is @code{nil}, the normal file encoding is
unsupported, and the variable @code{x-symbol-coding} is not specified.

@item
If the normal file encoding is supported and the file contains at least
one 8bit character, X-Symbol does not touch 8bit characters and never
produces them, neither via decoding (@pxref{Unique Decoding}) nor via
input methods.  The modeline includes @samp{-err} to represent the file
encoding (@pxref{Minor Mode}).
@end itemize

We end with a little example: if your normal file encoding and default
encoding is Latin-1, and you visit a file with
@samp{\usepackage[latin9]@{inputenc@}} producing some document containing
the Euro sign, you see the Euro character in Emacs when X-Symbol is
enabled, but you see the currency character without X-Symbol.


@node Controlling 8bit Coding, Unique Decoding, File Coding, Conversion
@comment  node-name,  next,  previous,  up
@subsection Store or Encode 8bit Characters
@cindex Storing 8bit Characters
@cindex Controlling 8bit Coding
@c @cindex Buffer 8bit Control
@cindex 8bit Coding Control
@cindex Latin in File

You can specify that 8bit characters (according to the coding in your
file, see @ref{File Coding}), are not encoded to tokens (when saving a
file), by setting the following buffer-local variable:

@vtable @code
@item x-symbol-8bits
Whether to store 8bit characters when saving the current buffer.

You can set this variable in the ``local variables list'' near the end
of the file (@pxref{File Variables,,,@value{emacs},@value{emacsman}}),
e.g.:

@example
%% Local Variables:
%% x-symbol-8bits: t
%% End:
@end example
@end vtable

If the variable is not already buffer-local, a reasonable value is
deduced when turning on X-Symbol (@pxref{Minor Mode}) by setting it the
the value of @code{x-symbol-coding}, or searching in the file for 8bit
characters:

@vtable @code
@item x-symbol-auto-8bit-search-limit
If there is a 8bit character in the file when visiting it, X-Symbol will
also store 8bit characters when saving the buffer.
@end vtable

If the file encoding is invalid (@pxref{File Coding}), we always search
for 8bit characters in the complete document and set
@code{x-symbol-8bits} accordingly.  Then, a non-@code{nil} value also
implies unique decoding (@pxref{Unique Decoding}).

While the variable @code{x-symbol-8bits} usually only influences the
encoding, it also influences the decoding if you choose to decode
uniquely (@pxref{Unique Decoding}).

Setting variable @code{x-symbol-8bits} to @code{nil} does not
necessarily mean that the file will not contain 8bit characters: the
characters might have no token representation in the current token
language (@pxref{TeXinfo Command}), or they are glyphs for ununsed code
points in the Latin-3 charset.  In both cases, it is unlikely that you
have inserted these invalid characters via X-Symbol's input methods
(@pxref{Introducing Input Methods}), you have probably copied them into
the current buffer.


@node Unique Decoding, Conversion Commands, Controlling 8bit Coding, Conversion
@comment  node-name,  next,  previous,  up
@subsection Unique Decoding
@cindex Unique Decoding
@cindex Restricted Decoding
@cindex Unique @TeX{} macro

Token languages might define more than one token representing the same
character.  When decoding and encoding these tokens, they will be
@dfn{normalized} to one form, the @dfn{canonical representation}.  E.g.,
with language @code{tex}, visiting a file with tokens @code{\neq} and
@code{\ne} converts both tokens to character @code{lessequal}, saving
the buffer stores the character as token @code{\neq} in both
occurrences.

It can also happen that a file contains both a 8bit character and a
token which would be converted to exactly that character.  When saving
the file, both characters are either not encoded, or both are encoded to
the same token.

Normally, this is no problem.  But if you redefine standard @TeX{}
macros, it certainly could be the case (@pxref{TeX Macro Problems})!
For this reason, package X-Symbol provides the following buffer-local
variable:

@vtable @code
@item x-symbol-unique
Whether to limit the decoding in such a way that no normalization will
happen.  That means: only decode canonical tokens, and, if
@code{x-symbol-8bits} is non-@code{nil} (@pxref{Controlling 8bit
Coding}), do not decode tokens which would be decoded to 8bit characters
(according to the coding in your file, see @ref{File Coding}).

You can set this variable in the ``local variables list'' near the end
of the file (@pxref{File Variables,,,@value{emacs},@value{emacsman}}),
e.g., together with a setting for @code{x-symbol-8bits}:

@example
%% Local Variables:
%% x-symbol-8bits: t
%% x-symbol-unique: t
%% End:
@end example
@end vtable

If the variable is not already buffer-local, a reasonable value is
deduced when turning on X-Symbol (@pxref{Minor Mode}): it will be set to
@code{t} if X-Symbol mode is not automatically turned on.

If the file encoding is invalid (@pxref{File Coding}) and
@code{x-symbol-8bits} is non-@code{nil} (@pxref{Controlling 8bit
Coding}), X-Symbol always uses unique decoding (@pxref{Unique
Decoding}).


@node Conversion Commands, Copy with Conversion, Unique Decoding, Conversion
@comment  node-name,  next,  previous,  up
@subsection Conversion Commands
@cindex Conversion Commands
@cindex Automatic Conversion
@cindex Interactive Conversion
@cindex Explicit Conversion

First the good news: most of the time, the necessary conversions are
performed automatically when you would expect them to be performed:

@itemize @bullet
@item
Turning X-Symbol minor mode (@pxref{Minor Mode}) on/off also performs
decoding/encoding.

@item
Saving a buffer where X-Symbol is enabled will encode the characters to
tokens in the file (of course, you keep to have the characters in the
buffer).

@item
Inserting a file into a buffer where X-Symbol is enabled will decode the
tokens in the inserted region.
@end itemize

Nevertheless, you might want to perform the conversions explicitly in
some situations by using one of the following commands (also to be found
in the menu):

@table @kbd
@item M-x x-symbol-decode-recode
@findex x-symbol-decode-recode
Recode all characters (if necessary) and decode all tokens to
characters.

@item M-x x-symbol-decode
@findex x-symbol-decode
Decode all tokens to characters, do not recode characters.

@item M-x x-symbol-encode-recode
@findex x-symbol-encode-recode
Encode all characters in buffer to tokens or recode them.

@item M-x x-symbol-encode
@findex x-symbol-encode
Encode all characters in buffer to tokens.  No recoding will be
performed since 8bit characters will always be encoded if the file
coding is different to the default coding, since @code{x-symbol-8bits}
is relative to the file coding, see @ref{Controlling 8bit Coding}.
@end table

All commands work on the region if it is active, or the (narrowed part
of the) buffer if no region is active.

If the file coding is the same as the default coding, the variants with
and without recoding (@pxref{File Coding}) do the same.  The variants
with recodings are the ones used when doing the conversion
automatically.  The variants without recodings are the ones used when
using the special Copy & Paste commands presented in the next
subsection.


@node Copy with Conversion, Char Aliases, Conversion Commands, Conversion
@comment  node-name,  next,  previous,  up
@subsection Copy & Paste with Conversion
@cindex Copy and Conversion
@cindex Copy Encoded
@cindex Paste and Conversion
@cindex Paste Decoded
@cindex Yank Decoded

You probably use X-Symbol, because you want to produce some
non-@sc{ascii} characters in your final document, but you are not really
interested what kind of token you would need to write.  (After all, you do
not use a hex editor to produce documents using some non-@sc{ascii}
encoding in the file, since you are not interested in the byte sequence
of individual characters.)

Consequently, all editing operations really work on characters, not on
the corresponding tokens for the token language of the current buffer.
This includes copying and pasting: if you copy the character
@code{plusminus} from a LaTeX buffer to a HTML buffer, you really copy
that character and not the three characters of the TeX macro @code{\pm}.

If you copy text to a buffer where X-Symbol is not enabled, like a mail
buffer, that is probably not what you want.  Similarly, you would
probably like to see the X-Symbol characters for tokens in a text which
you have copied from such a buffer.  Therefore, X-Symbol provides the
following commands (also to be found in the menu):

@table @kbd
@item M-x x-symbol-copy-region-encoded
@findex x-symbol-copy-region-encoded
@vindex kill-ring
Save the region in the @code{kill-ring} with all X-Symbol characters
encoded like by @kbd{M-x x-symbol-encode}, i.e., without recoding.

@item M-x x-symbol-yank-decoded
@findex x-symbol-yank-decoded
Reinsert the last text in the @code{kill-ring} and decode the inserted
text like @kbd{M-x x-symbol-decode}, i.e., without recoding.
@end table

You could get the same result with the usual copy & paste commands and
the conversion commands from the previous section (@pxref{Conversion
Commands}), but this would clutter the undo information of the current
buffer and would require an additional undo operation for the copy.


@node Char Aliases,  , Copy with Conversion, Conversion
@comment  node-name,  next,  previous,  up
@subsection Character Aliases
@cindex Char Aliases
@cindex Character Aliases
@cindex Aliases of Characters
@cindex Latin Character Aliases
@cindex Remapping Characters

A @dfn{character alias} or @dfn{char alias} is a character which is also
a character in a font with another registry, e.g., @code{adiaeresis} is
defined in all supported Latin fonts.  Emacs distinguish between these
five characters.  In package X-Symbol, one of them, with
@code{x-symbol-default-coding} (@pxref{Default Coding} if possible, is
supported by the input methods, the other ones are char aliases to the
supported one.

The reason is that it would be confusing for the user to choose among
different @code{adiaeresis}es and that there are neither different
@code{adiaeresis}es in Unicode nor in the token representations of
languages @code{tex} and @code{sgml}.

8bit characters in files with a file coding @code{x-symbol-coding} other
than @code{x-symbol-default-coding} are converted to the ``normal''
form.  E.g., if you have a Latin-1 font by default, the
@code{adiaeresis} in a Latin-2 encoded file is a Latin-1
@code{adiaeresis} in the buffer.  When saving the buffer, its is again
the right 8bit character in the Latin-2 encoded file.

Thus, in normal cases, buffers do not have char aliases.  In Emacs with
Mule support, this is only possible if you copy characters from buffers
with characters considered as char aliases by package X-Symbol, e.g.,
from the Mule file @file{european.el}.  In XEmacs without Mule support,
this is only possible if you use commands like @kbd{C-q 2 3 4}.

If you have char aliases in the current buffer, you might want to use
(it is not really necessary, just when searching for characters):

@table @kbd
@item M-x x-symbol-unalias
@findex x-symbol-unalias
Resolve all character aliases in buffer.  If the region is active, only
resolve char aliases in the region.
@end table

A single char alias before point can be resolved by command
@code{x-symbol-modify-key} and @code{x-symbol-rotate-key}, see
@ref{Input Method Context}.

@pindex latin-unity
The XEmacs package @code{latin-unity} provides a command to ``remap''
characters to one character set (if possible).  X-Symbol's unaliasing
can be seen as remap operations to a fixed sequence of character sets.

@c ===========================================================================

@node Minor Mode, Poor Mans Mule, Conversion, Concepts
@comment  node-name,  next,  previous,  up
@section Minor Mode
@cindex Minor Mode
@cindex Mode
@cindex X-Symbol Mode

X-Symbol is a minor mode (@pxref{Minor
Modes,,,@value{emacs},@value{emacsman}}) which enables the features
mentioned in this manual:

@itemize @bullet
@item
X-Symbol mode is required to do the conversions.  Turning the minor mode
on/off also includes decoding/encoding (@pxref{Conversion Commands}).

@item
X-Symbol mode provides the minor mode menu which includes: various
commands, commands to insert characters (@pxref{Input Method Menu}), and
entries to change some global and buffer-local variables mentioned in
this manual.

@item
X-Symbol mode is required for most input methods (@pxref{Input Methods})
and other features (@pxref{Features}).
@end itemize

With the default installation, X-Symbol mode is automatically turned on
when it is appropriate to do so (see below for details).  You can
control it for individually by the following command:

@table @kbd
@item M-x x-symbol-mode
@findex x-symbol-mode
@vindex x-symbol-mode
Toggle X-Symbol mode.  If provided with a prefix argument, turn X-Symbol
mode on if the numeric value of the argument is positive, else turn it
off.  If no token language can be deduced, ask for a token language; if
provided with a non-numeric prefix argument (@kbd{C-u M-x
x-symbol-mode}), always ask.

By default, X-Symbol mode is disabled in special major-modes visiting a
file, e.g., @code{vm-mode} (@pxref{FAQ News and Mail}).  Use a prefix
argument to be asked whether to turn in on anyway.
@end table

Turning X-Symbol mode on requires that you have a valid token language
for the current buffer.  Since turning X-Symbol mode on also decodes
tokens, it is also useful to set the variables which control the
conversion (@pxref{Conversion}).

Since people usually do not want to write some Emacs Lisp functions to
do some customizations, X-Symbol provides the following variables which
induce X-Symbol to set the necessary buffer-local variables when
X-Symbol is turned on:

@vtable @code
@item x-symbol-auto-style-alist
You can use the major mode and/or the name of the buffer or visited
file, and specific functions to set the following variables (if not
already buffer-local):

@itemize @minus
@item
@code{x-symbol-token-language} (@pxref{Token Language}), indicated in
the modeline, e.g. @samp{tex},
@item
@code{x-symbol-mode}, i.e., whether it is appropriate to turn on
X-Symbol mode automatically,
@item
@code{x-symbol-coding} (@pxref{File Coding}), indicated in the modeline
if different from the default coding, e.g. @samp{-l2} for Latin-2,
@item
@code{x-symbol-8bits} (@pxref{Controlling 8bit Coding}), indicated in
the modeline by @samp{8},
@item
@code{x-symbol-unique} (@pxref{Unique Decoding}), indicated in
the modeline by @samp{*},
@item
@code{x-symbol-subscripts} (@pxref{Super and Subscripts}), indicated in
the modeline by @samp{s},
@item
@code{x-symbol-image} (@pxref{Images}), indicated in the modeline by
@samp{i},
@end itemize

@item x-symbol-@var{lang}-modes
Major modes which use token language @var{lang} by default.
@xref{Supported Languages}.  The languages are checked in registration
order (the order shown in the language selection submenus).

@item x-symbol-@var{lang}-auto-style
Default values for the above mentioned variables @code{x-symbol-mode},
@code{x-symbol-coding}, @code{x-symbol-8bits}, @code{x-symbol-unique},
@code{x-symbol-subscripts}, and @code{x-symbol-image} if not already
buffer-local.

@item x-symbol-auto-mode-suffixes
Regular expression matching file suffixes to be ignored when checking
file names for the derivation above, e.g., extension @file{.orig}.

@item x-symbol-modeline-state-list
This variable controls the modeline appearance just mentioned.


The menu might also include individual entries for a token
language (@pxref{TeX Macro Basics}):

@item x-symbol-@var{lang}-extra-menu-items
Extra menu items for each token language @var{lang} (@pxref{TeX Macro
Basics}).
@end vtable

@c ====================================================================

@node Poor Mans Mule, Role of font-lock, Minor Mode, Concepts
@comment  node-name,  next,  previous,  up
@section Poor Man's Mule: Running Under XEmacs/no-Mule
@cindex Poor Man's Mule
@cindex No Mule
@cindex XEmacs without Mule

Using XEmacs/no-Mule normally means that you are restricted to use not
more than 256 different characters in your documents.

Package X-Symbol provides a lot more characters which can also be used
with XEmacs/no-Mule.  Internally, all X-Symbol characters except the
ones of your default font (@pxref{Default Coding}) are represented by
two characters, see @ref{Char Representation}.

This can lead to a lot of problems, which are resolved by the following
methods (some annoyances remain, @pxref{Nomule Problems}) when X-Symbol
mode is turned on (@pxref{Minor Mode}):

@itemize @bullet
@item
After each editing command, i.e., point movement, deletion of text and
insertion of text, package X-Symbol checks whether just one of the two
internal characters of an X-Symbol character has been affected.

@item
Package @code{font-lock} is used to display these two-character
sequences with the correct fonts.  The potential problem lies in the
set-up of the corresponding font-lock keywords, see @ref{Role of
font-lock}.

@ftable @code
@item x-symbol-nomule-fontify-cstrings
Alternatively to enabling @code{font-lock}, you can run this functions
in buffers having the special two-character sequences.  With the default
installation, this function is run in the selection buffers of package
@code{reftex}.
@end ftable
@end itemize

@c ====================================================================

@node Role of font-lock, Char Group, Poor Mans Mule, Concepts
@comment  node-name,  next,  previous,  up
@section The Role of @code{font-lock}
@cindex Role of @code{font-lock}
@cindex @code{font-lock} Use
@cindex Special Fonts

Package X-Symbol uses package @code{font-lock} to display super- and
subscripts (@pxref{Super and Subscripts}) and to display its special
characters under XEmacs/no-Mule (@pxref{Poor Mans Mule}).  Thus, you
should enable @code{font-lock} in buffers where you want to use X-Symbol
(it is by default).  @xref{Syntax Hiliting Packages}.

When X-Symbol mode is turned on, it automatically adds the necessary
font-lock keywords to the buffer-local value of
@code{font-lock-keywords} and all font-lock keywords which are commonly
used with the current token language.

Setting all font-lock keywords is important since @code{font-lock} might
not yet been turned on or since you might want to change
@code{font-lock}s decoration of the current buffer after X-Symbol has
been turned on.

Please note that switching the mode by typing @kbd{M-x latex-mode}
@emph{does not set} the La@TeX{}'s font-lock keywords!  They are set at
the end of @kbd{C-x C-f}.  If you switch the mode, turn on
@code{font-lock} by yourself.

Independently from package X-Symbol, the following command might be
useful in some situations:

@table @kbd
@item M-x x-symbol-fontify
@findex x-symbol-fontify
Refontify buffer.
@end table

@c ====================================================================

@node Char Group,  , Role of font-lock, Concepts
@comment  node-name,  next,  previous,  up
@section Character Group and Token Classes
@cindex Character Group
@cindex Group of Characters
@cindex Similar Characters
@cindex Category of Character
@cindex Syntax of Character
@cindex Token Classes
@cindex Classes of Tokens
@cindex Coloring Scheme

Each X-Symbol character belongs to a @dfn{character group}, e.g.,
@code{natnums} belongs to @code{setsymbol}.  A character group should
consists of similar characters where ``similar'' means similar meaning,
not similar appearance.  Two characters which have nearly the same
appearance, should be in the same group, though.  The group determines:

@itemize @bullet
@item
The Grid and submenu header under which the character can be found
(@pxref{Input Method Grid}, @ref{Input Method Menu}).

@item
The default bindings of characters (@pxref{Input Method Keyboard}) of
some groups.

@item
Whether to show the context info for a character (@pxref{Info}).

@item
The default @sc{ascii} representation of a character (@pxref{Ascii
Representation}).

@item
When using Emacs/XEmacs with Mule support, the syntax of a character
(@pxref{Syntax,,,@value{emacs},@value{emacsman}}).
@end itemize

The character group is independent from any token language, but is
probably somewhat related to some of its @dfn{token classes}.  For each
token language, each character is assigned to a list of token classes,
which can be used for the following:

@itemize @bullet
@item
Information in the echo area (@pxref{Info}), it could inform users to
include a specific La@TeX{} package when they want to use that character
in the document.

@item
Using a @dfn{coloring scheme} when displaying the characters in the echo
area (@pxref{Info}) or the Grid of characters (@pxref{Input Method
Grid}), useful for characters which can just be used in a specific
context, like @TeX{}'s math-mode characters.

@item
Restricting the ``electricity'' of input method Electric (@pxref{Input
Method Electric}), useful to disable this input methods for @TeX{}'s
math-mode characters if we are in text-mode.
@end itemize

The token classes for individual token languages are explained in the
corresponding sections of @ref{Supported Languages}:

@vtable @code
@item x-symbol-@var{lang}-header-groups-alist
The Grid and Menu headers for each token language @var{lang}.

@item x-symbol-@var{lang}-class-alist
Strings for the character info in the echo area for each token language
@var{lang}.

@item x-symbol-@var{lang}-class-face-alist
The coloring scheme for each token language @var{lang}.
@end vtable

@c ===========================================================================

@node Input Methods, Features, Concepts, Top
@comment  node-name,  next,  previous,  up
@chapter X-Symbol's Input Methods
@cindex Input Methods
@cindex Character Insertion

An X-Symbol @dfn{input method} is a way, provided by package X-Symbol,
to insert a X-Symbol character (not in the sense of Mule's ``input
methods'').  For a short overview with screenshots, see the
@uref{@value{url}/details.html,web pages of X-Symbol}.

Input methods Token and Electric change the normal way to insert
characters a bit.  Therefore, they require X-Symbol mode to be turned on
and can be turned off explicitly.  The other input methods are provided
with additional commands and key prefixes, they can also be used in
buffers where X-Symbol mode is turned off.

With Auc@TeX{}, Version 9.8a or higher, its math mode commands also
inserts X-Symbol characters
(@pxref{Mathematics,,,@value{auctex},@value{auctexman}}).

@menu
* Introducing Input Methods::   Common behavior of all input methods.
* Input Method Token::          Replace token by character.
* Input Method Read Token::     Minibuffer input with completion.
* Input Method Menu::           Select a menu item.
* Input Method Grid::           Choose highlighted character.
* Input Method Keyboard::       Compose a key sequence.
* Input Method Context::        Replace character sequence.
* Input Method Electric::       Automatically replace character sequence.
* Input Method Quail::          A Mule input method "x-symbol".
* Customizing Input Method::    How to customize the input methods.
@end menu

@c ===========================================================================

@node Introducing Input Methods, Input Method Token, Input Methods, Input Methods
@comment  node-name,  next,  previous,  up
@section Common Behavior of All Input Methods
@cindex Input Methods, General
@cindex Input Methods, Common
@cindex Input Methods, Standard
@cindex Valid Character
@cindex Allowed Character
@cindex Key Prefix
@cindex Prefix Argument
@cindex Prefix Key
@cindex Defined Character
@cindex Compose Key

Input methods normally just inserts @dfn{valid characters} which are
those characters which have a useful representation in the file:

@vtable @code
@item x-symbol-valid-charsym-function
When X-Symbol is turned off, a character is valid if it is an 8bit
character according to the value of @code{x-symbol-default-coding}.

When X-Symbol is turned on, a character is valid if the characters could
be encoded to a token in language @code{x-symbol-language} (@pxref{Token
Language}).
@end vtable

If a buffer is read-only (@pxref{Misc
Buffer,,,@value{emacs},@value{emacsman}}), most input methods push the
character to insert onto the kill ring instead.  Typing @kbd{C-y} lets
you then insert the character
(@pxref{Yanking,,,@value{emacs},@value{emacsman}}).

The input methods Keyboard, Menu and Grid (the character selection with
@kbd{@key{button2}}) have the same interpretation of the prefix
argument:

@itemize @bullet
@item
With prefix argument @samp{0}, do not insert anything, just barf, if the
character is not valid.

@item
With a positive prefix argument, insert a character that many times.
Barf, if the character is not valid.

@item
With a negative prefix argument, insert a character as many times as
specified by the absolute value of the prefix argument.  A character is
also inserted if it is not valid.

@item
With one or more @kbd{C-u}s with no digits, insert the token of a
language to choose, including ``x-symbol charsym'' (@pxref{Pseudo
Language}).
@end itemize

Many input commands of package X-Symbol uses the same key prefix in its
default binding:

@vtable @code
@item x-symbol-compose-key
@kindex C-=
@kindex @key{multi-key}
By default, @kbd{C-=} is used as the key prefix.  Under XEmacs/no-Mule,
you might want to use @kbd{@key{multi-key}} instead:

@lisp
(unless (featurep 'mule) (setq x-symbol-compose-key '(multi-key)))
@end lisp

@item x-symbol-auto-key-autoload
Set this to @code{nil}, if you do not want that pressing @kbd{C-=}
automatically initializes the input methods.
@end vtable

@c ===========================================================================

@node Input Method Token, Input Method Read Token, Introducing Input Methods, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Token: Replace Token by Character
@cindex Input Method Token
@cindex Token, Input Method
@cindex Replace Token
@cindex Abbrev, Token           @c pre-2.2

If X-Symbol mode is on, input method @dfn{Token} automatically replaces
the token by the corresponding character when inserting the next
character following the token (in some token languages you need the next
character to decide whether the token is completed) if it is valid.

The token will be replaced only if the next character has been inserted
without prefix argument or with prefix argument 0 (@kbd{C-u 0}), the
latter will therefore just induce the replacement.

Please note that the token is really replaced by the characters, it is
not just @code{font-lock} which highlights the token to look like a
character.

You might want to press @kbd{C-/} or @kbd{C-x u} to undo the
replacement.  Input method Token requires X-Symbol mode to be enabled,
it can be disabled (and re-enabled) by setting the following variable:

@vtable @code
@item x-symbol-token-input
A boolean which can also be changed via the X-Symbol menu.
@end vtable

Individual token language might slightly change the way input method
Token works exactly; from the predefined language, it is just @code{tex}
(@pxref{TeX Macro}).

@c ===========================================================================

@node Input Method Read Token, Input Method Menu, Input Method Token, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Read Token: Minibuffer Completion
@cindex Input Method Read Token
@cindex Read Token, Input Method
@cindex Minibuffer Completion, Token

You can insert a character by reading the corresponding token in the
minibuffer.  You are offered completion over the known tokens
(@pxref{Completion,,,@value{emacs},@value{emacsman}}).

@table @kbd
@item M-x x-symbol-read-token-direct
@itemx C-= @key{TAB}
@findex x-symbol-read-token-direct
@kindex C-= @key{TAB}
Insert character by selecting a token in the current token language
(even if X-Symbol mode is turned off) or an ``x-symbol charsym''
(@pxref{Pseudo Language}).

@item M-x x-symbol-read-token
@itemx C-= @key{RET}
@findex x-symbol-read-token
@kindex C-= @key{RET}
Insert character by first selecting the token language and then a token
in that language.
@end table

Input method Read Token also works if X-Symbol mode is not enabled.  It
uses the common interpretation of prefix arguments for X-Symbol insert
commands, see @ref{Introducing Input Methods}.

@c ===========================================================================

@node Input Method Menu, Input Method Grid, Input Method Read Token, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Menu: Select a Menu Item
@cindex Input Method Menu
@cindex Menu, Input Method

If X-Symbol mode is turned on, a @dfn{Menu} @code{X-Symbol} appears in
the menubar (@pxref{Minor Mode}).  It also appears over non-highlighted
parts in the Grid and the Key Completions buffer (@pxref{Input Method
Grid}).  The menu allows to change buffer-local and global variables
(some directly, some via package @code{custom}).  It has a submenu with
the most interesting commands of package X-Symbol.

The menu has submenus with commands to insert X-Symbol characters.  The
submenu headers are the same as the headers in the Grid, see
@ref{Char Group}.  The appearance of the menu can be customized:

@vtable @code
@item x-symbol-local-menu
With a valid token language, the X-Symbol menu only contains insertion
commands for valid characters.  The entries are mentioned and sorted
according to the token.  Otherwise, the X-Symbol menu contains all
characters, the entries are mentioned according to their charsym name.

@item x-symbol-menu-max-items
The submenus do not contain more than 30 insertion commands for X-Symbol
characters.  A submenu is split if necessarily.
@end vtable

Input method Menu also works if X-Symbol mode is not enabled.  It uses
the common interpretation of prefix arguments for X-Symbol insert
commands, see @ref{Introducing Input Methods}.

@c ===========================================================================

@node Input Method Grid, Input Method Keyboard, Input Method Menu, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Grid: Choose Highlighted Character
@cindex Input Method Grid
@cindex Grid, Input Method
@cindex Table of Characters
@cindex Highlighted Character

Probably the easiest way to insert a character is by using a @dfn{Grid}
of characters:

@table @kbd
@item M-x x-symbol-grid
@itemx C-= C-=
@findex x-symbol-grid
@kindex C-= C-=
Pops up a buffer displaying X-Symbol characters in a grid like fashion.
You can select a character with the mouse or @kbd{@key{RET}}, see below.
@end table

In the Grid buffer and the buffer with the possible completions for an
X-Symbol key sequence (@pxref{Input Method Keyboard}), the following
commands are used if the mouse pointer is over an highlighted character.

@table @kbd
@item @key{button2}
@itemx @key{RET}
@itemx @key{SPC}
@c @itemx x-symbol-list-selected
@kindex @key{button2}
@kindex @key{RET}
@kindex @key{SPC}
@c @findex x-symbol-list-selected
Insert highlighted character (or character under point, respectively)
into the buffer of @code{point} if @code{point} is not in the same
buffer as the highlighted character.  Otherwise, insert the character
into the reference buffer, i.e., the buffer where you have invoked the
grid or the key completions from.  (The reference to the buffer is
erased when an X-Symbol character is inserted into any buffer.)

@item @key{button3}
@kindex @key{button3}
Pops up a highlight menu where you can select to insert the token of
various token languages instead the character itself.  In order not to
load and initialize all additional token language you have not yet used,
the menu offers to do so explicitly for supported (registered) token
languages (@pxref{Token Language}).
@end table

Over all non-highlighted parts, the following commands are used:

@table @kbd
@item @key{button2}
@kindex @key{button2}
@c @findex x-symbol-list-selected
Scroll Grid or Key Completions buffer down in upper half of the window
and scroll up in the lower half of the window.

@item @key{button3}
@kindex @key{button3}
Pops up the X-Symbol menu, see @ref{Input Method Menu}).
@end table

When using the keyboard to select a character, the following command
could be useful:

@table @kbd
@item M-x x-symbol-list-info
@itemx ?
@itemx h
@itemx i
@findex x-symbol-list-info
@kindex ?
@kindex h
@kindex i
Display info for character under point in echo area.

@item M-x x-symbol-list-bury
@itemx q
@findex x-symbol-list-bury
@kindex q
Bury list buffer while trying to use the old window configuration.
@end table

You can control the grid by the following variables:

@vtable @code
@item x-symbol-local-grid
With a valid token language, the Grid only contains insertion commands
for valid characters and might use a coloring scheme.  Otherwise, it
contains all characters.

@item x-symbol-temp-grid
Inserting an X-Symbol character does not restore the window
configuration current before the invocation of the Grid.

@item x-symbol-grid-reuse
Use old Grid when invoking command @code{x-symbol-grid}, if this is
reasonably to do.  If @code{x-symbol-grid} is called with a prefix
argument, always create new Grid.

@item x-symbol-grid-ignore-charsyms
The Grid does not contain @code{nobreakspace}.

@item x-symbol-grid-tab-width
The tab width in the Grid buffer should correspond the font in
@code{x-symbol-heading-face} which is also used as the default font in
the Grid buffer.

@item x-symbol-heading-strut-glyph
Use larger interline spacing if a line in the Grid starts with a header.
@end vtable

The headers in the Grid are the same as the submenu headers, see
@ref{Char Group}.  Similar looking characters for one headers are
grouped together.  @xref{Input Method Context}.

Input method Grid also works if X-Symbol mode is not enabled.  It uses
the common interpretation of prefix arguments for X-Symbol insert
commands, see @ref{Introducing Input Methods}.

@c ===========================================================================

@node Input Method Keyboard, Input Method Context, Input Method Grid, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Keyboard: Compose Key Sequence
@cindex Input Method Keyboard
@cindex Keyboard, Input Method

Key sequences starting with @kbd{C-=} (@pxref{Introducing Input
Methods}) are used to insert X-Symbol characters, e.g., @kbd{C-= ~ >}
inserts @code{leadsto}.  The Ascii sequence of the keys after @kbd{C-=}
look similar to the character which you are going to insert.  It is the
same as the sequence which is replaced by input method Context, see
@ref{Input Method Context}.

If many characters are represented by the same Ascii sequence, the
binding is extended by @samp{1}, @samp{2} and so on.  If you do not know
how to continue your key sequence, the following commands might be
useful:

@table @kbd
@item M-x x-symbol-help
@itemx C-= @var{zero-or-more-keys} @key{help}
@itemx C-= @var{zero-or-more-keys} C-h
@findex x-symbol-help
@kindex C-= @key{help}
@kindex C-= C-h
@kindex @key{help}
@kindex C-h
Pops up a buffer displaying possible completions for the key sequence
@kbd{C-= @var{zero-or-more-keys}}.  You do not have to type the key
sequence again, i.e., @kbd{C-= @var{zero-or-more-keys}} is also used for
the next input.

@item C-= @var{zero-or-more-keys} @key{button1}
@itemx C-= @var{zero-or-more-keys} @key{button2}
@itemx C-= @var{zero-or-more-keys} @key{button3}
@kindex @key{button1}
@kindex @key{button2}
@kindex @key{button3}
Use the normal bindings of @kbd{@key{button1}},  @kbd{@key{button2}} or
@kbd{@key{button3}}, respectively (@pxref{Input Method Grid}).  The key sequence
is not used for the next input.

@item C-= @var{zero-or-more-keys} M-@key{prior}
@itemx C-= @var{zero-or-more-keys} M-@key{next}
@itemx C-= @var{zero-or-more-keys} M-@key{home}
@itemx C-= @var{zero-or-more-keys} M-@key{end}
@kindex M-@key{prior}
@kindex M-@key{next}
@kindex M-@key{home}
@kindex M-@key{end}
Execute the commands @code{scroll-other-window-down},
@code{scroll-other-window}, @code{beginning-of-buffer-other-window} or
@code{end-of-buffer-other-window}, respectively.  You do not have to
type the key sequence again, i.e., @kbd{C-= @var{zero-or-more-keys}} is
also used for the next input.
@end table

@vtable @code
@item x-symbol-temp-help
Inserting an X-Symbol character restores the window configuration
current before the invocation of the Grid.

@item x-symbol-map-default-keys-alist
Defines the bindings mentioned above.
@end vtable

Input method Keyboard also works if X-Symbol mode is not enabled.  It
uses the common interpretation of prefix arguments for X-Symbol insert
commands, see @ref{Introducing Input Methods}.

@c ===========================================================================

@node Input Method Context, Input Method Electric, Input Method Keyboard, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Context: Replace Char Sequence
@cindex Context, Input Method
@cindex Input Method Context
@cindex Character Sequence Input
@cindex Ascii Sequence Input
@cindex Modify Chain
@cindex Rotate Chain
@cindex Greek Input

The idea of the input method @dfn{Context} is to replace a sequence of
characters by a character which looks similar to the whole sequence.  If
the sequence consists only of Ascii characters, it is also used for the
key bindings, see @ref{Input Method Keyboard}.

There will be some info in the echo area that the character sequence
before point can be replace via input method Context.  The following
commands are provided:

@table @kbd
@item M-x x-symbol-modify-key
@itemx C-,
@itemx C-= @key{left}
@itemx C-= @key{right}
@findex x-symbol-modify-key
@kindex C-,
@kindex C-= @key{left}
@kindex C-= @key{right}
If character before point is an X-Symbol character, ``modify'' it to an
alternative character (if you do it often enough, you are back at your
first character).  Otherwise replace sequence of characters by a
character which looks similar to the whole sequence.

@item M-x x-symbol-rotate-key
@itemx C-.
@itemx C-= @key{up}
@itemx C-= @key{down}
@findex x-symbol-rotate-key
@kindex C-.
@kindex C-= @key{up}
@kindex C-= @key{down}
If character before point is an X-Symbol character, ``rotate'' its
``direction'' (or change uppercase/lowercase).
@end table

Both commands can also be used to resolve a character alias before
point, see @ref{Char Aliases}.  If the region is active, restrict
replacement to use that region since the input method Context only
considers the longest sequence of characters with a replacement.

Input method Context can be customized by changing the following
variables:

@vtable @code
@item x-symbol-rotate-prefix-alist
If you provide a prefix argument to command @code{x-symbol-rotate-key},
you can specify the direction you want to have: it is according to
numerical keypads, e.g., with prefix argument @samp{7} you specify the
direction ``north-west''.

@item x-symbol-rotate-suffix-char
Command @code{x-symbol-rotate-key} is also used to ``Greekify'' the
previous character: typing @kbd{a C-.} is shorter than @kbd{a # C-,}.

@item x-symbol-context-ignore
Constrains whether a context/charsym can be replaced.  No constraints by
default.

@item x-symbol-context-init-ignore
Contexts starting with a space cannot be replaced.  This variable must
be set before X-Symbol has been initialized.
@end vtable

@c ===========================================================================

@node Input Method Electric, Input Method Quail, Input Method Context, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Electric: Automatic Context
@cindex Input Method Electric
@cindex Electric, Input Method
@cindex Aggressive Context      @c 2.6
@cindex Automatic Context

The idea of input method @dfn{Electric} is to have the input method
Context (@pxref{Input Method Context}) do its replacement automatically.
X-Symbol automatically replaces some character sequences of input method
Context by the X-Symbol character as soon as the last character in the
sequence of the sequence has been pressed.

Input method Electric has nothing to do with the display of
super-/subscripts (@pxref{Super and Subscripts}).

You might want to press @kbd{C-/} or @kbd{C-x u} to undo the
replacement.  Input method Electric requires X-Symbol mode to be
enabled, it can be disabled (and re-enabled) by setting the following
variable:

@vtable @code
@item x-symbol-electric-input
A boolean which can also be changed via the X-Symbol menu.
@end vtable

To make input method Electric useful and not annoying, several
conditions must be met for X-Symbol to do the auto-replacement:

@itemize @bullet
@item
Not all contexts will be replaced automatically.  E.g., while input
method Context allows both pre- and postfixes for accented characters,
@kbd{:} and @kbd{'} only act as prefixes, and @kbd{`} and @kbd{~} only
as postfixes for input method Electric, since these are the combinations
where those characters are quite likely not used literally.

@item
The character must be valid in the current token language, see
@ref{Introducing Input Methods}.

@item
All characters of the context have been typed without any other command
in between, e.g., @kbd{- >} inserts @code{arrowright}, "- @key{left}
@key{right} > simply inserts @samp{->}.

@item
No prefix argument has been used for any character in the context.

@item
The electric context must not be a suffix of a longer valid context for
another character.  E.g., @kbd{' ' o} does not insert
@samp{'@code{oacute}} because @samp{''o} is the context for
@code{ohungarumlaut} (which cannot be inserted by input method
Electric).

@item
It should be ``allowed'' to change the context to the character via
input method Context.

@item
Individual contexts/charsyms can be disabled by setting the following
variables:

@vtable @code
@item x-symbol-electric-ignore
The context should neither be @samp{'s} (this would be annoying when
writing English), nor include a space.  If you want to disable input
method Electric for all accented characters, use

@lisp
(setq x-symbol-electric-ignore
      "[ \t]\\|[A-Za-z][~`]\\|[:'][A-Za-z]")
@end lisp

@item x-symbol-@var{lang}-electric-ignore
Individual contexts/charsyms can be disabled for each token language
@var{lang}.
@end vtable
@end itemize

@c ===========================================================================

@node Input Method Quail, Customizing Input Method, Input Method Electric, Input Methods
@comment  node-name,  next,  previous,  up
@section Input Method Quail: a Mule Input Method
@cindex Input Method Quail
@cindex Mule Input Method

Another way to insert a characters is by using the Emacs/Mule
multilingual text input method ``x-symbol'' (@pxref{Input
Methods,,,@value{emacs},@value{emacsman}})..

Again, the Ascii sequence used there is the same as the sequence which
is replaced by input method Context, see @ref{Input Method Context}.  A
one-letter key sequence is extended by @key{;}.

If input method Quail is selected for a buffer, input method Electric
(@pxref{Input Method Electric}) is disabled in that buffer.

@c TODO: more

@c ===========================================================================

@node Customizing Input Method,  , Input Method Quail, Input Methods
@comment  node-name,  next,  previous,  up
@section Customizing Input Methods
@cindex Customizing Method Internals
@cindex Input Methods Customization

You may safely define key bindings not using the @code{x-symbol-map}
(i.e., starting with @kbd{C-=}).  E.g., for @code{alpha} on @kbd{A-a} ,
use

@lisp
(global-set-key [(alt a)] 'x-symbol-INSERT-alpha)
@end lisp

Please note that the command @code{x-symbol-INSERT-alpha} is not defined
before the main file (@file{x-symbol}) in the package has been loaded
(if you really need it, function @code{autoload} is your friend).

Other possibilities to customize the input methods are by setting the
following variables:

@vtable @code
@item x-symbol-header-groups-alist
Defines the groups whose characters appear after that header in the Grid
and in submenus with that header.  @xref{Char Group}.  Extra variables
exists for the language dependent Grid and Menu.

@item x-symbol-group-input-alist
@itemx x-symbol-user-table
These are variables which are used to compute the input definitions.
While this kind of indirection might seem complicated to you (it is), it
actually ensures consistency across all input methods.  @xref{Defining
Input Methods}.

For example, if you prefer charsym @code{epsilon1} over @code{epsilon}
you might want to use:

@lisp
@group
(setq x-symbol-user-table
      '((epsilon1 t (greek1 "e" nil "epsilon") nil -3000)))
@end group
@end lisp

@item x-symbol-list-mode-hook
Additional functions to execute after setting up the Grid and Key
Completions buffer.

@item x-symbol-after-init-input-hook
You can change the input methods directly by functions in these hooks.
@end vtable

@c ===========================================================================

@node Features, Supported Languages, Input Methods, Top
@comment  node-name,  next,  previous,  up
@chapter Features of Package X-Symbol
@cindex Features of X-Symbol
@cindex Supported Features

Package X-Symbol not only provides input methods for X-Symbol
characters, it also provides more features which support an easy and
comfortable preparation of documents.

@menu
* Super and Subscripts::        Use special fonts for super-/subscripts.
* Images::                      Images after image insertion commands.
* Info::                        Display information in echo area.
* Ascii Representation::        Derive label from a buffer contents.
* Package Information::         Invoke info system, use WWW browser.
@end menu

@c ===========================================================================

@node Super and Subscripts, Images, Features, Features
@comment  node-name,  next,  previous,  up
@section Super- and Subscripts
@cindex Superscripts
@cindex Subscripts
@cindex Invisible, Revealing
@cindex Point, Invisible
@cindex Cursor, Invisible
@cindex Keywords for Subscripts

Package X-Symbol displays the characters inside super-/subscript
commands in a way to make them look like super-/subscripts.  It also
marks the super-/subscript command itself as invisible, so you don't see
it on the screen.  For example, the three characters @samp{a^2} in the
buffer are @emph{displayed} as an @samp{a} and a raised, smaller
@samp{2}---the @samp{^} is still in the buffer.

Therefore, the display of super- and subscripts has nothing to do with
Input Method Electric (@pxref{Input Method Electric}).

Do not confuse the special Latin characters @code{twosuperior},
@code{threesuperior}, @code{ordfeminine} and @code{masculine} with the
characters @samp{2}, @samp{3}, @samp{a} and @samp{o} when displayed as
superscripts.  You might notice that the characters look a bit
different, but to help you seeing the difference, X-Symbol will display
an info in the echo area (@pxref{Info}) for the special Latin
characters when point is before or after the character in question.

X-Symbol only displays the innermost super- and subscripts, since we
would need even more additional fonts otherwise.  It is also restricted
to display single-line super- and subscripts.

The display of super- and subscripts requires @code{font-lock} to be
enabled (@pxref{Role of font-lock}).

Super- and subscripts are by default enabled if the they are defined for
the token language and it would be appropriate to turn on X-Symbol
automatically for the current buffer (@pxref{Minor Mode}).  They can be
disabled (and re-enabled) by setting the following buffer-local
variable:

@vtable @code
@item x-symbol-subscripts
A boolean which can also be changed via the X-Symbol menu.
@end vtable

As mentioned before, X-Symbol marks the super-/subscript command itself
as invisible, except when point is directly before, inside or directly
after this command.  During the time where this this is the case,
X-Symbol makes the super-/subscript command reappear and highlights it
with pink.  This feature can be disabled (and re-enabled) by setting the
following variables:

@vtable @code
@item x-symbol-reveal-invisible
A boolean which can also be changed via the X-Symbol menu.

@item x-symbol-revealed-face
The face used for the super-/subscript command when revealed.

@item x-symbol-idle-delay
Time in seconds of idle time before revealing invisible characters.
@end vtable

Super-/subscript commands are @code{^}/@code{_} (@pxref{TeX Macro}) and
@code{<sup>}/@code{<sub>} (@pxref{SGML Entity}):

@c ===========================================================================

@node Images, Info, Super and Subscripts, Features
@comment  node-name,  next,  previous,  up
@section Images at the end of Image Insertion Commands
@cindex Images
@cindex Glyphs

@pindex convert
Package X-Symbol can display @dfn{images} at the end of image insertion
commands.  They show thumbnails (scaled-down version of the image) for
the included image files (using @code{convert}, @pxref{Installing Image
Converter}).  Using the middle mouse button invokes the image editor for
the image under the mouse pointer.

@menu
* Image Display::               When to display images.
* Image Conversion::            Producing a scaled-down image.
* Image Caching::               Speeding up the image processing.
* Special Images::              Signaling specific situations.
* Image Editor::                Editing the original image file.
@end menu


@node Image Display, Image Conversion, Images, Images
@comment  node-name,  next,  previous,  up
@subsection Display of Images
@cindex Image Display
@cindex Image Control
@cindex Image Commands
@cindex Controlling Images
@cindex Image Keywords
@cindex Keywords for Images

The display of images is by default enabled if the image commands are
defined for the token language and it would be appropriate to turn on
X-Symbol automatically for the current buffer (@pxref{Minor Mode}).  It
can be disabled (and re-enabled) by setting the following buffer-local
variable:

@vtable @code
@item x-symbol-image
A boolean which can also be changed via the X-Symbol menu.
@end vtable

Image commands are @code{\includegraphics} and others (@pxref{TeX
Macro}), and @code{<img>} (@pxref{SGML Entity}):

@vtable @code
@item x-symbol-@var{lang}-image-keywords
The keywords (image commands & arguments) for each token language
@var{lang}.
@end vtable

File names in the image commands must be interpreted correctly.  They
can be:

@itemize @minus
@item
@dfn{absolute}, start with @samp{/} or @samp{~},
@item
@dfn{explicitly relative}, start with @samp{./} or @samp{../},
@item
@dfn{implicitly relative}, assumed otherwise, e.g., @file{image.eps}, or
@item
special, like having some special URL prefix like @file{http:} or @file{ftp:}.
@end itemize

Relative file names can be relative to some @dfn{master directory}
(usually the current directory of the file) or to directories in some
@dfn{search path} (only used with token language @code{tex}):

@vtable @code
@item x-symbol-@var{lang}-master-directory
The master directory for each token language @var{lang}.

@item x-symbol-@var{lang}-image-searchpath
The image search path for each token language @var{lang}.  Defaults to
the current directory.

@item x-symbol-image-searchpath-follow-symlink
Directories in the search path ending with @file{//} (double slash) are
recursive: all subdirectories not starting with a dot are also included
in the search path.  If this variable has value @code{nil} (the
default), subdirectories which are symbolic links are not included.
@end vtable

For details, see the section of the individual token languages
(@pxref{Supported Languages}).


@node Image Conversion, Image Caching, Image Display, Images
@comment  node-name,  next,  previous,  up
@subsection Image Conversion
@cindex Image Conversion
@cindex Converting Images
@cindex Colormap
@cindex Image Cache File

The file mentioned inside the image insertion command is not used
directly to display the image after the command.  The image might be too
big, it might use too many colors or the image format might not be
supported by Emacs.  Therefore, it is converted to an @dfn{image cache
file}, see @ref{Image Caching}.

@vtable @code
@item x-symbol-image-max-width
The image is not wider than 120 points.

@item x-symbol-image-max-height
The image is not higher than 80 points.

@item x-symbol-image-convert-colormap
Colormap used in function @code{x-symbol-image-convert-colormap} below.
A colormap is a normal image whose colors are the only ones used for
producing other images.  The distribution of package X-Symbol includes
two colormaps: @file{etc/colormap138.xpm} and @file{etc/colormap66.xpm}.

@item x-symbol-image-colormap-allocation
Package X-Symbol allocates the colors of the colormap at start-up and
prevents them to be de-allocated.

@item x-symbol-image-converter
@pindex convert
Program @code{convert} from ImageMagick is used to convert the images
(@pxref{Installing Image Converter}).  Set this variable to @code{nil},
if you don't want to convert images.

The following variables controls the invocation of the program
@code{convert} from ImageMagick:

@vtable @code
@item x-symbol-image-convert-program
The name of the program @code{convert}, it is
@samp{C:\\ImageMagick\\convert} when running on Windows and
@samp{convert} otherwise.

@item x-symbol-image-convert-file-alist
Program @code{convert} needs to be told that @file{@var{file}.pstex} is
a Postscript file.
@end vtable

The following functions are possible values in
@code{x-symbol-image-converter}:

@ftable @code
@item x-symbol-image-start-convert-mono
Produces monochrome images.  Used if your device has less than 32
colors.

@item x-symbol-image-start-convert-truecolor
Produce images with original colors.  Used if your device has more than
767 colors.

@item x-symbol-image-start-convert-color
Produce images with maximal four colors (just four because different
images might use a different sets of colors).  Used otherwise without a
colormap.

@item x-symbol-image-start-convert-colormap
Produce image with colors from the colormap.  Used otherwise with a
colormap.

@vtable @code
@item x-symbol-image-convert-mono-regexp
Function @code{x-symbol-image-start-convert-colormap} just produces
monochrome images for temporary image cache files (@pxref{Image
Caching}) since @code{convert} is slower when using a colormap.
@end vtable
@end ftable
@end vtable


@node Image Caching, Special Images, Image Conversion, Images
@comment  node-name,  next,  previous,  up
@subsection Image Caching
@cindex Image Caching
@cindex Caching of Images
@cindex Glyph Caching
@cindex Memory Cache for Images
@cindex File Cache for Images

Editing would be extremely slow, if an image cache file would be
produced every time an image insertion command has been recognized.
Therefore, package X-Symbol uses the following techniques:

@itemize @bullet
@item
It uses an asynchronous process to create the image cache file.  You can
edit your file during the conversion.

@item
It uses a @dfn{file cache}: image cache file can be kept for future
Emacs sessions.

@item
It uses a @dfn{memory cache}: images from the most common file names are
cached in a buffer-local memory cache.  The cached is initialized when
parsing the whole buffer for image keywords.  Rescan the buffer if you
want to display the the images of new image files by using the following
command:

@table @kbd
@item M-x x-symbol-image-parse-buffer
@findex x-symbol-image-parse-buffer
Parse the buffer to recognize image insertion commands.  Usually, this
is done automatically.
@end table
@end itemize

File and memory caching can be controlled by the following variables:

@vtable @code
@item x-symbol-image-update-cache
The image cache is automatically updated if it does not exist yet or if it
is older than the corresponding image file.

@item x-symbol-image-cache-directories
Cache files for images in your home directory are stored in directory
@file{~/.images/}, e.g., image @file{~/d/img.eps}, is cached in
@file{~/.images/d/img.png}.

Images outside your home directory are just temporarily cached, or not
displayed at all if they cannot be stored in the memory cache.

You could also specify that the cache files uses a relative
subdirectory, e.g., that @file{~/d/img.eps} is cached in
@file{~/d/.img/img.eps} or that the image is not displayed at all.

@item x-symbol-image-temp-name
Temporary image files are stored in a temporary directory (@file{/tmp/})
having some unique name.  They are not supported on Emacs.

@item x-symbol-image-use-remote
Package X-Symbol only displays images which can be stored in the memory
cache.  With value @code{t}, it tries to find the image file during
editing (ignoring the search path for speed, though).  Editing lines
with image files not in the memory cache would be slow, since file
accesses are necessary for every command.
@end vtable

The memory cache only stored image file from the current directory or
some standard image directories like @file{figures/} (@pxref{TeX
Macro}), or @file{images/} or @file{pictures/} (@pxref{SGML Entity}).
Otherwise, the image file is considered similar to remote files:

@vtable @code
@item x-symbol-@var{lang}-image-cached-dirs
The directories with images which are stored in the memory cache.  Can
be separately defined for each token language @var{lang}.
@end vtable


@node Special Images, Image Editor, Image Caching, Images
@comment  node-name,  next,  previous,  up
@subsection Special Images for Specific Situations
@cindex Special Images
@cindex Images for Specific Situations
@cindex Glyph for Specific Situations

If package X-Symbol cannot display images representing the included
image files, it uses special images instead:

@itemize @bullet
@item
@dfn{Remote:} An Escher knot is displayed if the file is remote or if
the image cannot be cached in the memory cache, see @ref{Image Caching}.

@item
@dfn{Junk}: A recycle sign is displayed if there is no image converter
(@pxref{Image Conversion}), if it should not use a file cache or if the
file cache cannot be written.

@item
@dfn{Locked:} A terminal with a lock is displayed if the image cache file
cannot be read or written.

@item
@dfn{Design:} An ink pen is displayed if the image file does not exist.

@item
@dfn{Create:} An hour glass is displayed used during the creation of the
image cache file, an old image cache is used instead if it exists.

@item
@dfn{Broken:} A tombstone is displayed if the creation of the image
cache file has failed.
@end itemize

To customize the glyphs for the special images, use:

@vtable @code
@item x-symbol-image-data-directory
Directory of files for the special images.

@item x-symbol-image-special-glyphs
File names of special images and their image format.
@end vtable


@node Image Editor,  , Special Images, Images
@comment  node-name,  next,  previous,  up
@subsection Image Editor
@cindex Image Editor
@cindex Editing Image Files
@cindex Designing Images
@cindex Scale Factor, Images
@cindex Image Highlight Menu

If you move the mouse pointer to an image insertion command or its
image, it is highlighted.

@table @kbd
@item @key{button2}
@kindex @key{button2}
Start image editor for highlighted image.  If the image is searched in
the searchpath (@pxref{Image Caching}), edit first existing image file.
If no image exists, open a new file in the first directory of the
searchpath.

@item @key{button3}
@kindex @key{button3}
Pop up the @dfn{image highlight menu}.  You can rescan the buffer for
image insertion commands (@pxref{Image Display}).

It also displays all directories in the searchpath if the file name is
implicitly relative, or the current directory otherwise.  Selecting a
directory starts the image editor in that directory (relatively to that
directory if the file name has a directory part).

@item M-x x-symbol-image-editor
@findex x-symbol-image-editor
Start image editor.  Asks for the image file.
@end table

You can control which editor to use:

@vtable @code
@item x-symbol-image-editor-alist
@pindex display
@pindex xfig
Normally, program @code{display} is used to edit the highlighted image
file.  But for image names @file{@var{file}.eps}, @file{@var{file}.ps}
or @file{@var{file}.pstex}, program @code{xfig} is invoked with
@file{@var{file}.fig}.  It also uses a scale method, e.g., with
@file{img.80.eps}, we edit @file{img.fig} (which should be exported with
scale=80%).

@item x-symbol-image-scale-method
If a scale method is used for a file name and the file name without
extension ends with a dot and two digits, these three characters are
removed from the file name.

@item x-symbol-image-current-marker
Directories with an existing image for the specified file name are
marked with an @samp{*}.  The first of these represents the file which
is used when pressing @kbd{@key{button2}}.
@end vtable

@c ===========================================================================

@node Info, Ascii Representation, Images, Features
@comment  node-name,  next,  previous,  up
@section Info in Echo Area
@cindex Info in Echo Area
@cindex Echo Area Info
@cindex Character Info
@cindex Context Info
@cindex Minibuffer Info

The echo area (@pxref{Echo Area,,,@value{emacs},@value{emacsman}}) is
used by X-Symbol to give some information about the character around
point, and whether there is a context before point which can be replaced
by input method Context (@pxref{Input Method Context}).

It will be controlled by the following variables (also to be found in
the menu):

@vtable @code
@item x-symbol-character-info
A three-value variable which controls whether to display some info for
the character after or around point.  The info for the character after
point includes the character itself and the following infos:

@itemize @minus
@item
the token of the current language, eventually colored according to some
coloring scheme (@pxref{Char Group}),

@item
infos using the token classes (@pxref{Char Group}), which could inform
users to include a specific La@TeX{} package when they want to use that
character in the document,

@item
the codings in which the characters is considered to be a 8bit character
(@pxref{File Coding}), and

@item
the key bindings (@pxref{Input Method Keyboard}).
@end itemize

@item x-symbol-context-info
If X-Symbol mode is on and some conditions are met, display some info
for the character which would replace the context before point when
pressing @kbd{C-,} (@pxref{Input Method Context}).  It can be controlled
by the following variables:

@vtable @code
@item x-symbol-context-info-ignore
@findex x-symbol-default-context-info-ignore
The default value @code{x-symbol-default-context-info-ignore} makes the
following variables control whether to display the context info.

@item x-symbol-context-info-threshold
The context does not consist of a single character.

@item x-symbol-context-info-ignore-regexp
The context does not solely consist of letters.

@item x-symbol-context-info-ignore-groups
The context is not replaced by an accented character, see @ref{Char
Group}.
@end vtable

@item x-symbol-idle-delay
Time in seconds of idle time before showing the info.
@end vtable

@c ====================================================================

@node Ascii Representation, Package Information, Info, Features
@comment  node-name,  next,  previous,  up
@section Ascii Representation of Strings 
@cindex Ascii Representation
@cindex Representation of Characters
@cindex Label Creation

@pindex reftex
If you want to derive labels from a buffer contents (provided e.g., by
Emacs packages @code{reftex} or @code{bibtex}), you need a Ascii
representation of strings containing X-Symbol characters.  This is
provided by the following function:

@ftable @code
@item x-symbol-translate-to-ascii
Takes a string and returns a string only consisting of Ascii characters.

@vtable @code
@item x-symbol-charsym-ascii-alist
You might want to define the German way to Asciify accented characters
by:
@lisp
@group
(setq x-symbol-charsym-ascii-alist
      '((adiaeresis . "ae") (Adiaeresis . "Ae")
        (odiaeresis . "oe") (Odiaeresis . "Oe")
        (udiaeresis . "ue") (Udiaeresis . "Ue")))
@end group
@end lisp

@item x-symbol-charsym-ascii-groups
By default, ``Ascii''fying accented characters means removing the
accents.  Other characters have built-in Ascii representation, e.g,
@code{sigma1} has the Ascii representation @samp{sigma}.
@end vtable
@end ftable

@c ====================================================================

@node Package Information,  , Ascii Representation, Features
@comment  node-name,  next,  previous,  up
@section X-Symbol Package Information
@cindex Package Information
@cindex WWW Browsing
@cindex URL for X-Symbol

@table @kbd
@item M-x x-symbol-package-info
@findex x-symbol-package-info
Read documentation for package X-Symbol in the info system.

@item M-x x-symbol-package-web
@findex x-symbol-package-web
Ask a WWW browser to load the URL of package X-Symbol.

@item M-x x-symbol-package-bug
@findex x-symbol-package-bug
Use this command to contact the maintainer of package X-Symbol @emph{in
any case}, e.g., for suggestions, bug and problem reports, see @ref{Bug
Reports}.  Use @kbd{C-u 9 M-x x-symbol-package-bug} for patches
(including corrections of this manual, which are strongly appreciated)
and for other messages.
@end table

@vtable @code
@item x-symbol-installer-address
E-mail address of the person who has installed package X-Symbol
system-wide (@pxref{System-wide Installation}).

@item x-symbol-package-url
URL of package X-Symbol, used by @code{x-symbol-package-web}.
@end vtable

@c ====================================================================

@node Supported Languages, X-Symbol Internals, Features, Top
@comment  node-name,  next,  previous,  up
@chapter Supported Token Languages
@cindex Supported Languages
@cindex Default Languages
@cindex Built-in Languages
@cindex Provided Languages
@cindex Languages in Distribution

The chapter describe the predefined token language.  It also presents
the language specific behavior for @ref{Concepts}, @ref{Input Methods},
and @ref{Features}.

@menu
* Pseudo Language::             Token language ``x-symbol charsym''.
* TeX Macro::                   Token language @code{tex}.
* SGML Entity::                 Token language @code{sgml}.
* BibTeX Macro::                Token language @code{bib}.
* TeXinfo Command::             Token language @code{texi}.
* External Languages::          Languages defined in other Emacs Packages.
@end menu

@c ====================================================================

@node Pseudo Language, TeX Macro, Supported Languages, Supported Languages
@comment  node-name,  next,  previous,  up
@section Pseudo Token Language ``x-symbol charsym''
@cindex Pseudo Language
@cindex Charsym
@cindex X-Symbol Charsym

If no (or an invalid) token language is set for a buffer, the info in
the echo area (@pxref{Info}) for a X-Symbol Character in the buffer (if
it exists) uses the name of its @dfn{charsym}.  In this manual, we
actually refer to X-Symbol characters by their charsym name, e.g.,
@code{alpha}.

A charsym is a symbol which is used internally to represent a X-Symbol
character.  Charsyms are used instead characters in all user variables
of package X-Symbol.

The highlight menu of the Grid (@pxref{Input Method Grid}) also offers
to insert a charsym name.  Charsyms can also be used for input method
Read Token, see @ref{Input Method Read Token}.

You cannot use this pseudo language to turn on the X-Symbol minor mode
(@pxref{Minor Mode}), you cannot decode charsyms to their characters, and
you cannot encode characters to charsyms.

@c ===========================================================================

@node TeX Macro, SGML Entity, Pseudo Language, Supported Languages
@comment  node-name,  next,  previous,  up
@section Token Language ``@TeX{} macro'' (@code{tex})
@cindex Token Language @code{tex}
@cindex Language @code{tex}
@cindex @TeX{} macro
@cindex @code{tex}
@cindex La@TeX{}

For buffers using the major mode @code{latex-mode}, @code{tex-mode} or
@code{plain-tex-mode}, we use token language @dfn{@TeX{} macro}
(@code{tex}).  This language provides the display of super-/subscripts
and images.  If the buffer visits a file with extension @file{.tex},
X-Symbol mode is automatically turned on.

@menu
* TeX Macro Basics::            Basics of language ``@TeX{} macro''.
* TeX Macro Features::          Super-/subscripts and images in La@TeX{}.
* TeX Macro Problems::          Problems with @TeX{} macros.
* TeX Macro Conversion::        How the conversion of @TeX{} macros works.
* TeX Macro Symbols::           Extra Symbols of Language ``@TeX{} Macro''.
@end menu


@node TeX Macro Basics, TeX Macro Features, TeX Macro, TeX Macro
@comment  node-name,  next,  previous,  up
@subsection Basics of Language ``@TeX{} macro''
@cindex TeX Macro Basics
@cindex Basics TeX Macro
@cindex Choosing TeX Macro
@cindex TeX Macro Use
@cindex TeX Macro Modes

The standard behavior can be controlled by the following variables:

@vtable @code
@item x-symbol-tex-modes
@itemx x-symbol-tex-auto-style
The variables known from @ref{Minor Mode}.  If the buffer visits a file
with extension @file{.tex}, super-/subscripts and images are displayed,
otherwise unique decoding (@pxref{Unique Decoding}) will be used.

@item x-symbol-tex-auto-coding-alist
Used there to automatically deduce the specific encoding of the file
(@pxref{File Coding}) if the file visited by the buffer has the
extension @file{.tex}.  It searches for one of the following two strings
in the current buffer, including the comment:

@example
\usepackage[@var{encoding}]@{inputenc@}
%& -translation-file=i@var{enc}
@end example

where @var{encoding} should be one of @samp{latin1}, @samp{latin2},
@samp{latin3}, @samp{latin5}, or @samp{latin9}, and @var{enc} should be
one of @samp{l1} or @samp{l2}.  8bit characters are not encoded if the
file if the search was successful (@pxref{Controlling 8bit Coding}).

@item x-symbol-tex-coding-master
@vindex TeX-master
If one of the above strings cannot be found in the current buffer, and
the current buffer has a buffer-local string value of @code{TeX-master},
also search in the file denoted by that value for the strings.
(Buffer-local variables will not be inherited.)
@end vtable

The input methods and the character info in the echo area are controlled
by:

@vtable @code
@item x-symbol-tex-header-groups-alist
We use the standard Grid and Menu headers.

@item x-symbol-tex-extra-menu-items
There is an extra menu item to remove the braces around text-mode
letters and other text-mode symbols.
@c TODO: detailed list of additional commands

@item x-symbol-tex-electric-ignore
@itemx x-symbol-tex-electric-ignore-regexp
@pindex texmathp
Input method Electric (@pxref{Input Method Electric}) is disabled if the
character is not of the correct @TeX{} mode, i.e., it only produces a
math-mode character in a math area and a text-mode character in a text
area (this test requires package @code{texmathp}, see @ref{LaTeX Packages}).
Postfix tilde is not electric, because @samp{~} produces a space in
@TeX{}.

@item x-symbol-tex-token-suppress-space
Input method Token (@pxref{Input Method Token}) only converts a token
ending with a control word like @code{\i}, if the character following
the token is no letter.  If that token is a text-mode token and a
@key{SPC} has been entered without a prefix argument, the @key{SPC} will
only perform the replacement, it will not insert a space, i.e., it will
act like @kbd{C-u 0 @key{SPC}}.

@item x-symbol-tex-class-alist
@itemx x-symbol-tex-class-face-alist
Various token classes (@pxref{Char Group}) are defined.  They are used
to give some info (@pxref{Info}) about the characters spacing behavior,
which La@TeX{} packages are necessary to use the character (@pxref{TeX
Macro Symbols}), and about the conversion (@pxref{TeX Macro
Conversion}).  X-Symbol uses blue for text-mode only and purple for
math-mode only characters in the Grid (@pxref{Input Method Grid} and the
character info.
@end vtable


@node TeX Macro Features, TeX Macro Problems, TeX Macro Basics, TeX Macro
@comment  node-name,  next,  previous,  up
@subsection Super-/Subscripts and Images in La@TeX{}
@cindex TeX Macro Features
@cindex Features TeX Macro
@cindex TeX Macro Superscripts
@cindex TeX Macro Subscripts
@cindex TeX Macro Images

The display of super- and subscripts (@pxref{Super and Subscripts}) is
controlled by:

@vtable @code
@itemx x-symbol-tex-font-lock-limit-regexp
The superscript command @code{^} and the subscript command @code{_} is
recognized.  The argument can be provided with and without braces.  The
argument should not span more than one line and should not contain a
super-/subscript command.

@item x-symbol-tex-font-lock-allowed-faces
The characters @samp{^} and @samp{_} are not always commands (@pxref{TeX
Macro Problems}), e.g., in the argument of @code{\ref}.  X-Symbol uses
the usual syntax highlighting keywords to decide whether to recognize
these characters as super-/subscript commands: they are commands if they
are not highlighted or highlighted with the usual math-mode faces.

This might lead to problems: @ref{FAQ No Subscripts}, @ref{FAQ Stupid
Subscripts}.  Using @code{texmathp} (@pxref{LaTeX Packages}) has even
more problems:

@itemize @minus
@item
The syntax highlighting (which is used for super-/subscripts) would be
much too slow.

@item
With own La@TeX{} environments, you would need to customize
@code{texmathp}.

@item
It is actually wrong: whether @samp{^} and @samp{_} are
super-/subscripts commands does not depend on whether we are in @TeX{}'s
math mode, it depends on its catcodes (which are changed by commands
like @code{\ref}).
@end itemize
@end vtable

The display of images (@pxref{Images}) is controlled by:

@vtable @code
@item x-symbol-tex-image-keywords
The following commands are recognized.  Extension @var{ext} stands for
@file{eps} (which is the default extension for both versions of
@code{\includegraphics} if the extension is omitted there), @file{ps},
@file{gif}, @file{png}, @file{jpeg}, @file{jpg}, or @file{pdf}.  Options
@var{options} can be omitted with their surrounding brackets or
preceding comma, respectively.

@example
\input@{@var{file}.pstex_t@}
\includegraphics[@var{options}][@var{options}]@{@var{file}.@var{ext}@}
\includegraphics*[@var{options}][@var{options}]@{@var{file}.@var{ext}@}
\epsfig@{file=@var{file}.@var{ext},@var{options}@}
\psfig@{file=@var{file}.@var{ext},@var{options}@}
\epsfbox[@var{options}]@{@var{file}.@var{ext}@}
\epsffile[@var{options}]@{@var{file}.@var{ext}@}
@end example

@item x-symbol-tex-master-directory
@vindex TeX-master
Relative file names (@pxref{Image Display}, explicitly or implicitly)
are relative to the directory part of variable @code{TeX-master} if it
is buffer-local and a string.  Otherwise, they are relative to the
directory of the current file.

@item x-symbol-tex-image-searchpath
@vindex TEXPICTS
@vindex TEXINPUTS
Files with implicitly relative names are meant to be searched in a
search path.  It defaults to the list of directories specified by the
environment variable @code{TEXPICTS} or @code{TEXINPUTS} (@pxref{TeX
environment variables,,,@value{kpathsea},@value{kpathseaman}}),
extended by @file{./} if necessary.

Each directory in this list is used to expand the file name.  The first
expansion naming a readable file is used.  Relative directories in this
list are expanded in the master directory mentioned above.

This mimics the standard behavior of @TeX{}, omitting the ``built-in''
directories of the search path (@pxref{Path
sources,,,@value{kpathsea},@value{kpathseaman}}).

@item x-symbol-tex-image-cached-dirs
The file name in the image command should not have a directory part or
the directory part should be @file{figures/} if the image should be
cached in the memory cache.
@end vtable


@node TeX Macro Problems, TeX Macro Conversion, TeX Macro Features, TeX Macro
@comment  node-name,  next,  previous,  up
@subsection Problems with @TeX{} Macros
@cindex TeX Macro Problems
@cindex Problems TeX Macro

Like with other token languages, the conversion between characters and
@TeX{} macros induce the problem that we have two conflicting
requirements: we would like X-Symbol not to change the file when
visiting and saving a file, and we would like X-Symbol to use characters
for all corresponding macros.  @xref{Unique Decoding}.

The additional problem with @TeX{} macros is that there is no fixed and
simple definition of @TeX{} macros, and many users have their personal
@TeX{} style, while many users are probably not aware that the style
also influences @TeX{}'s typesetting:

@itemize @bullet
@item
The tokens in @TeX{} are not ended by a dedicated character (like
@sc{sgml} entities are ended by @samp{;}).  Instead, we need the next
char to decide whether a macro ends, which would be no problem if @TeX{}
would have a character which has no meaning except separating tokens
(like space in most programming languages).  Unfortunately, this is not
the case: after an @dfn{control word} (an all-letter macro), a space has
no meaning, but it does produce a space in the output after characters
and other macros, except in math mode.

During decoding, a text-mode control word has to be replaced either with
its trailing spaces or not be replaced at all.  Since the number of
spaces can vary and X-Symbol does not remember the original @TeX{}
sequence of a character, X-Symbol would change the file if it would use
characters for all sequences.

@item
During encoding, a space after a character in the buffer must produce a
space in the document output, since users normally do not care whether
the character is represented by a control word or not.  Let us assume
that we (Bavarians) want to produce the output @samp{Ma@ss{}@ Bier}.
@ifnottex
In the info file, you will probably not see any 8bit characters (the
sharp @samp{s} is shown as @samp{@ss{}}).
@end ifnottex

@itemize @minus 
@item
Many people would use @samp{Ma\ss\@ Bier}.  This is (almost ever) fine
in text mode, but a @samp{\@ } in math mode is not ignored (whereas the
spaces after characters are).  If we have text- and math-mode control
word, we have a problem, since math-mode detection cannot work properly
without @TeX{} processing.

@item
Many people would use @samp{Ma\ss@{@}@ Bier}.  This has less problems and
is therefore used by X-Symbol.  The @samp{@{@}} at the end of the control
word is not used if the character is not followed by a space, e.g., to
produce @samp{Stra@ss{}e}, we use @samp{Stra\ss@ e}.  Consequently,
@samp{Ma\ss\@ Bier} in the file would be decoded to @samp{Ma@ss{}\@ Bier},
which would be encoded to the original sequence in the file.

@item
Some people would always use @samp{@{@}} after a text-mode control word,
even it is not followed by a space, like @samp{Stra\ss@{@}e}.  This is
wrong, since it breaks ligatures and kerns.  For example, compare the
output of @samp{\L@ V} with @samp{\L@{@}V} using @samp{T1} font encoding.

@item
Up to Version 4.1, X-Symbol surrounded a text-mode control word with
braces, like @samp{Stra@{\ss@}e}.  This was probably even worse than
always adding @samp{@{@}} at the end of the control word.  It was used,
because it is required by Bib@TeX{} (@pxref{BibTeX Macro}).
Unfortunately, Bib@TeX{} sends this bad sequence directly to La@TeX{},
but this has nothing to do with X-Symbol.
@end itemize

@item
The accented characters are not represented by one tokens in @TeX{}.
Most people use @samp{\"a} to produce an @samp{@"a}, while some use
@samp{\"@{a@}}.  X-Symbol uses the former, it does not even decode the
latter automatically.  Up to Version 4.1, X-Symbol used @samp{@{\"a@}},
having the same problems as using @samp{Stra@{\ss@}e}.

@item
Around a dozen characters can be produced by more than one @TeX{} macro,
like @code{\neq} and @code{\ne}.  Here, X-Symbol decodes both forms,
because it is probably a bad idea to redefine standard @TeX{} macros.
This will not be done with in style files (@pxref{Unique Decoding}).

@item
In @TeX{}, you can change the lexer on the fly, i.e., in a strict sense,
any conversion is unsafe without @TeX{} processing.  Since the most
likely change is to change the catcode of the character @samp{@@} to a
letter (used in La@TeX{}'s style files), this character is considered a
letter by X-Symbol.  This means that although both @samp{\ss@ @@} and
@samp{\ss@@} usually produce the same output, only the first is decoded
to @samp{@ss{}@@}.

@item
In @TeX{}, the definitions of macros can also change on the fly i.e., in
a strict sense, any conversion is unsafe without @TeX{} processing.
X-Symbol assumes that you do not do something like that except as done
by the standard La@TeX{} @code{\verb} command, and the @code{verbatim}
and @code{tabbing} environments.
@end itemize


@node TeX Macro Conversion, TeX Macro Symbols, TeX Macro Problems, TeX Macro
@comment  node-name,  next,  previous,  up
@subsection The Conversion of @TeX{} Macros
@cindex TeX Macro Conversion
@cindex Conversion of TeX Macros

The @TeX{} macros for Latin characters are according to the La@TeX{}
package @file{inputenc.sty}, v0.97+.  Package X-Symbol uses U00B5 for
@code{\mathmicro}, not for @code{\mu}, though!  @xref{Wishlist LaTeX}.

It is assumed that you do not redefine standard @TeX{} macros like
@code{\ne} (@pxref{TeX Macro Conversion}), if you do so, you should
better use unique decoding (@pxref{Unique Decoding}).

The encoding of characters to @TeX{} macros works as follows:

@itemize @bullet
@item
If the character is preceded by an odd number of backslashes, insert a
space before the character.

@item
Accented characters are encoded without braces, e.g., we encode @samp{@,{c}}
to @samp{\c@ c}.  Accents are encoded with braces, e.g., we use
@samp{\c@{@ @}} and @samp{\u@{@}}.
@end itemize

Additionally, the encoding of characters to @TeX{} macros which are
@dfn{control words} (all-letter macros), or whose @TeX{} representation
ends with a control word (like @samp{\'\i}) works as follows:

@itemize @bullet
@item
If the character is followed by a letter, replace the character by the
macro and insert a space.

@item
If the macro is a text-mode macro and followed by one or more blanks,
replace the character and insert @samp{@{@}}.

@item
Otherwise, just replace the character.
@end itemize

The decoding of @TeX{} macros which are control words to characters
works as follows:

@itemize @bullet
@item
If the macro is a text-mode macro and followed by @samp{@{@}} which is
followed by a blank, replace the macro and delete the braces.

@item
If the macro is a text-mode macro and followed by one are more blanks,
we have the following rule:

@itemize @minus
@item
If we have exactly one blank, the blank is a space, and it is not
followed by a @samp{%} (comment character), replace the macro by the
corresponding character and delete the space.  (With unique decoding,
the character following the space must be a letter.)

@item
Otherwise, do @emph{not decode} the macro!
@end itemize

@item
Otherwise, just replace the macro.
@end itemize

To clarify, @dfn{letter} means @samp{A}-@samp{Z}, @samp{a}-@samp{z}, or
@samp{@@}, @dfn{blank} means a space, newline or the end of the buffer
(therefore, the last character in the buffer is always followed by a
blank).

There are three control words which are both text-mode and math mode
macros: @code{\ldots}, @code{\vdots}, and (by accident) @code{\angle}.
They are all treated like math-mode characters, but their minibuffer
info (@pxref{Info}) includes @samp{gobbles space} (spaces in the buffer
after the character have no impact on the document),

Additionally, the following commands and environments are processed
during decoding (but we are just looking for strings, i.e., they are
also processed in comments):

@vtable @code
@item x-symbol-tex-verb-delimiter-regexp
If the command @code{\verb} is found, its argument is not decoded if it
is delimited by one of the following characters: @samp{-}, @samp{!},
@samp{#}, @samp{$}, @samp{&}, @samp{*}, @samp{+}, @samp{/}, @samp{=},
@samp{?}, @samp{^}, @samp{|}, or @samp{!}.

@item x-symbol-tex-env-verbatim-regexp
The contents of the @code{verbatim} environment is not decoded.  To
produce accented characters inside this environment, use the La@TeX{}
package @file{inputenc.sty}.

@c Inside @code{\hyphenation}@{@dots{}@}, you can only use Latin characters.

@c David Kastrup: Wrong.  inputenc.sty converts things like @"a into \"a
@c anyway (take a look into your table of contents file, xxx.toc, for
@c example).  Both @"a and \"a will not work in hyphenation patterns when you
@c are using a font encoding without such a character (like the default OT1
@c encoding), both @"a and \"a will work if something like
@c \usepackage[T1]{fontenc} is active.  This holds for LaTeX; plain TeX is
@c not as sophisticated as to replace \"a with a single character when in
@c T1 encodings.

@item x-symbol-tex-env-tabbing-regexp
Inside a @code{tabbing} environment, the macro sequences starting with
@samp{\`}, @samp{\'}, @samp{\=} and @samp{\-} are not decoded.  It is
probably better (with or without X-Symbol) to use the La@TeX{} package
@file{inputenc.sty} or to the @code{Tabbing} environment, to be found in
the @sc{ctan} archives.
@end vtable

During encoding, these commands and environments are not respected,
since it does not make any sense to have X-Symbol's private characters
in the @TeX{} file.

@ifnottex
Final note: in the info file, you will probably not see any 8bit
characters.
@end ifnottex

You might want change the conversion between characters and tokens in
language @code{tex} by changing:

@vtable @code
@item x-symbol-tex-user-table
You can define you own tokens for X-Symbol characters.  E.g., if you
like to have the command @code{\sqrt} represented by a character
(shadowing the entry for @code{\surd}), add the following to your
@file{~/.emacs}:

@lisp
(setq x-symbol-tex-user-table '((radical (math special) "\\sqrt")))
@end lisp
@end vtable


@node TeX Macro Symbols,  , TeX Macro Conversion, TeX Macro
@comment  node-name,  next,  previous,  up
@subsection Extra Symbols of Language ``@TeX{} Macro''
@cindex Extra Symbols for @TeX{}
@cindex Defining @code{tex}
@cindex Initializing @code{tex}
@cindex @TeX{} Macro Installation
@cindex Installing @code{tex}
@pindex @file{latexsym.sty}
@pindex @file{amssymb.sty}
@pindex @file{stmaryrd.sty}
@pindex @file{fontenc.sty}
@pindex @file{inputenc.sty}

This section describes what you should put into your private style file
or your document if you want to use extra symbols, i.e., characters
whose info in the echo area (@pxref{Info}) contains s.th. like
@samp{@var{package}.sty} or @samp{user}.  If you do not use the
corresponding characters, you do not have to do anything, of course.

The @TeX{} macros @code{\Box}, @code{\Diamond}, @code{\leadsto},
@code{\Join}, @code{\lhd}, @code{\mho}, @code{\rhd}, @code{\sqsupset},
@code{\sqsubset}, @code{\unlhd}, @code{\unrhd}, are defined in La@TeX{}
package @file{latexsym.sty}:

@example
\usepackage@{latexsym@}
@end example

Note that these macros are also defined @file{amssymb.sty}.  Since the
first four macros are defined differently (better) in
@file{latexsym.sty}, it does make sense to load both La@TeX{} packages
(e.g., @file{amssymb.sty} simply defines @code{\Diamond} to be the same
as @code{\lozenge}).

The @TeX{} macros @code{\boldsymbol}, @code{\circledast},
@code{\circledcirc}, @code{\circleddash}, @code{\digamma},
@code{\gtrapprox}, @code{\gtrsim}, @code{\lessapprox}, @code{\lesssim},
@code{\triangleq}, @code{\varkappa} are defined in AMS La@TeX{} package
@file{amssymb.sty}:

@example
\usepackage@{amssymb@}
@end example

The @TeX{} macros @code{\bigsqcap}, @code{\llbracket},
@code{\rrbracket}, @code{\llparenthesis}, @code{\rrparenthesis} are
defined in the La@TeX{} package @file{stmaryrd.sty}:

@example
\usepackage@{stmaryrd@}
@end example

The @TeX{} macros @code{\guilsinglleft}, @code{\guilsinglright},
@code{\dj}, @code{\NG}, @code{\ng}, @code{\DH}, @code{\DJ}, @code{\dh},
@code{\dj}, @code{\TH}, @code{\th}, @code{\guillemotleft},
@code{\guillemotright} and the ogonek characters are only defined if
you use T1 font encoding:

@example
\usepackage[T1]@{fontenc@}
@end example

The @TeX{} macro @code{\mathmicro} for U00B5 can be defined by
(@pxref{Wishlist LaTeX}):

@example
\let\mathmicro\mu
@end example

You should define the following in your La@TeX{} file (if you use the
corresponding characters), the first can only be used with T1 font encoding.

@example
\DeclareTextSymbol@{\textbackslash@}@{T1@}@{92@}
\newcommand@{\nsubset@}@{\not\subset@}
\newcommand@{\textflorin@}@{\textit@{f@}@}
\newcommand@{\setB@}@{@{\mathord@{\mathbb B@}@}@}
\newcommand@{\setC@}@{@{\mathord@{\mathbb C@}@}@}
\newcommand@{\setN@}@{@{\mathord@{\mathbb N@}@}@}
\newcommand@{\setQ@}@{@{\mathord@{\mathbb Q@}@}@}
\newcommand@{\setR@}@{@{\mathord@{\mathbb R@}@}@}
\newcommand@{\setZ@}@{@{\mathord@{\mathbb Z@}@}@}
\newcommand@{\coloncolon@}@{\mathrel@{::@}@}
@c \newcommand@{\lsemantics@}@{\mathopen@{\lbrack\mkern-3mu\lbrack@}@}
@c \newcommand@{\rsemantics@}@{\mathclose@{\rbrack\mkern-3mu\rbrack@}@}
@c \newcommand@{\lcata@}@{\mathopen@{(\mkern-3mu\mid@}@}
@c \newcommand@{\rcata@}@{\mathclose@{\mid\mkern-3mu)@}@}
@end example

The @TeX{} macros @code{\textordfeminine}, @code{\textordmasculine},
@code{\textdegree}, @code{\textonequarter}, @code{\textonehalf},
@code{\textthreequarters}, @code{\mathonesuperior},
@code{\mathtwosuperior}, @code{\maththreesuperior},
@code{\textcopyright} are only defined when using La@TeX{} package
@file{inputenc.sty}:

@example
\usepackage[latin1]@{inputenc@}
@end example

The @TeX{} macros @code{\textcent}, @code{\textcurrency},
@code{\textyen}, @code{\textbrokenbar}, @code{\textmalteseH},
@code{\textmalteseh} are defined as not available in La@TeX{} package
@file{inputenc.sty}.  @xref{Wishlist LaTeX}.  If you use this package
and want to define these commands, use @code{\renewcommand} (or
@code{\def}) after, e.g.:

@example
\usepackage[latin1]@{inputenc@}
\usepackage@{wasysym@}  %% defines \cent, \currency, \brokenvert
\usepackage@{amssymb@}  %% defines \yen
\renewcommand@{\textcent@}@{\cent@}
\renewcommand@{\textcurrency@}@{\currency@}
\renewcommand@{\textyen@}@{\yen@}
\renewcommand@{\textbrokenbar@}@{brokenvert@}
@end example

@c ===========================================================================

@node SGML Entity, BibTeX Macro, TeX Macro, Supported Languages
@comment  node-name,  next,  previous,  up
@section Token Language ``@sc{sgml} entity'' (@code{sgml})
@cindex HTML
@cindex SGML entity
@cindex Token Language @code{sgml}
@cindex Language @code{sgml}
@pindex Netscape

For buffers using the major mode @code{html-mode}, @code{hm--html-mode},
@code{html-helper-mode}, @code{sgml-mode} or @code{xml-mode}, we use
token language @dfn{@sc{sgml} entity} (@code{sgml}).  This language
provides the display of super-/subscripts and images.  If the buffer
visits a file and uses a @sc{html} mode, X-Symbol mode is automatically
turned on.

@menu
* SGML Entity Basics::          Basics of Language ``@sc{sgml} entity''.
* SGML Entity Features::        Super-/Subscripts and Images in @sc{html}.
* SGML Entity Conversion::      How the conversion of @sc{sgml} entities works.
@end menu


@node SGML Entity Basics, SGML Entity Features, SGML Entity, SGML Entity
@comment  node-name,  next,  previous,  up
@subsection Basics of Language ``@sc{sgml} entity''
@cindex SGML Entity Basics
@cindex Basics SGML Entity
@cindex Choosing SGML Entity
@cindex SGML Entity Use
@cindex SGML Entity Modes

The standard behavior can be controlled by the following variables:

@vtable @code
@item x-symbol-sgml-modes
@itemx x-symbol-sgml-auto-style
The variables known from @ref{Minor Mode}.  If the buffer uses a
@sc{html} mode, super-/subscripts and images are displayed, otherwise
unique decoding (@pxref{Unique Decoding}) will be used.

@item x-symbol-sgml-auto-coding-alist
Used there to automatically deduce the specific encoding of the file
(@pxref{File Coding}).  It searches for the following string in the
current buffer, including the comment:

@example
<meta http-equiv="content-type"
      content="text/html; charset=@var{encoding}">
@end example

where @var{encoding} should be one of @samp{iso-8859-1},
@samp{iso-8859-2}, @samp{iso-8859-3}, @samp{iso-8859-9}, or
@samp{iso-8859-15}.  8bit characters are not encoded if the file if the
search was successful (@pxref{Controlling 8bit Coding}).
@end vtable

The input methods and the character info in the echo area are controlled
by:

@vtable @code
@item x-symbol-sgml-header-groups-alist
Defines the headers and their characters for the language specific Grid
and Menu.

@item x-symbol-sgml-extra-menu-items
There are no special entries in the X-Symbol menu.

@item x-symbol-sgml-electric-ignore
There is no additional constraint to the ones mentioned in @ref{Input
Method Electric}.

@item x-symbol-sgml-class-alist
@itemx x-symbol-sgml-class-face-alist
Token classes (@pxref{Char Group}) are only used to define a coloring
scheme.  X-Symbol uses dark orange or dark red for non-Latin-1
characters in the Grid (@pxref{Input Method Grid} and the character info
(@pxref{Info}), dark red for characters without defined entity names in
@sc{html} (@pxref{SGML Entity Conversion}).
@end vtable


@node SGML Entity Features, SGML Entity Conversion, SGML Entity Basics, SGML Entity
@comment  node-name,  next,  previous,  up
@subsection Super-/Subscripts and Images in @sc{html}
@cindex SGML Entity Features
@cindex Features SGML Entity
@cindex SGML Entity Superscripts
@cindex SGML Entity Subscripts
@cindex SGML Entity Images

The display of super- and subscripts (@pxref{Super and Subscripts}) is
controlled by:

@vtable @code
@item x-symbol-sgml-font-lock-regexp
@itemx x-symbol-sgml-font-lock-limit-regexp
@itemx x-symbol-sgml-font-lock-alist
@itemx x-symbol-sgml-font-lock-contents-regexp
The superscript command @code{<sup>}@dots{}@code{</sup>} and the subscript
command @code{<sub>}@dots{}@code{</sub>} is recognized.  The contents should
contain at least one character which is not a space or a
@code{nobreakspace}.
@end vtable

The display of images (@pxref{Images}) is controlled by:

@vtable @code
@item x-symbol-sgml-image-keywords
The following commands are recognized.  Extension @var{ext} stands for
@file{gif}, @file{png}, @file{jpeg} or @file{jpg}.

@example
<img @var{@dots{}} src="@var{file}.@var{ext}" @var{@dots{}}>
@end example

@item x-symbol-sgml-master-directory
@itemx x-symbol-sgml-image-searchpath
Relative file names (@pxref{Image Display}) are relative to the
directory of the current file.

@item x-symbol-sgml-image-file-truename-alist
The file name prefix @file{file:} is ignored.  For any other file name
which starts with letters and then a colon, e.g., with @file{http:} or
@file{C:\} (which is no @sc{url} anyway), the image insertion command
will be skipped.  By changing this variable, you could specify that the
prefix @file{http://www.fmi.uni-passau.de/~wedler/} corresponds to
@file{~/public_html/}.

@item x-symbol-sgml-image-cached-dirs
The file name in the image command should not have a directory part or
the directory part should be @file{images/} or @file{pictures/} if the
image should be cached in the memory cache.
@end vtable


@node SGML Entity Conversion,  , SGML Entity Features, SGML Entity
@comment  node-name,  next,  previous,  up
@subsection The Conversion of @sc{sgml} Entities
@cindex SGML Entity Conversion
@cindex Conversion of SGML Entities

Most character entities of HTML-4.0 are supported, except the following:
uppercase Greek which look like uppercase Latin, ``markup-significant
and internationalization'' characters, and some quotes.  See
@uref{@value{sgmlentitiesurl}}.

By default, we encode to entity references like @code{&amp;}, and decode
from both entity references and character references like @code{&#38;}.
For Latin-N characters without defined entity names in @sc{html} (e.g.
@code{scedilla}), we can only use character references.

Do not expect Netscape before v6 to display non-Latin-1 characters
correctly (this might work by specifying the charset UTF-8 and using
character references).

You might want change the conversion between characters and tokens in
language @code{sgml} by changing:

@vtable @code
@item x-symbol-sgml-token-list
@findex x-symbol-sgml-token-list-name
@findex x-symbol-sgml-token-list-code
@findex x-symbol-sgml-token-list-netscape
A symbol, which defines whether to use entity references, character
references, or entity references for Latin-1 characters and character
references for others.

@item x-symbol-sgml-user-table
It is probably not a good idea to change the defined tokens (except via
the variable above), but you might want to add some definitions:

@example
(setq x-symbol-sgml-user-table '((circ () 999 "&bcomp;")))
@end example
@end vtable

@c ====================================================================

@node BibTeX Macro, TeXinfo Command, SGML Entity, Supported Languages
@comment  node-name,  next,  previous,  up
@section Token Language ``Bib@TeX{} macro'' (@code{bib})
@cindex Token Language @code{bib}
@cindex Language @code{bib}
@cindex Bib@TeX{} macro
@cindex @code{bib}
@cindex Bib@TeX{}

For buffers using the major mode @code{bibtex-mode}, we use token
language @dfn{Bib@TeX{} macro} (@code{bib}).  This language does not
provide the display of super-/subscripts and images.  If the buffer
visits a file, X-Symbol mode is automatically turned on.  It is
controlled by:

@vtable @code
@item x-symbol-bib-modes
@itemx x-symbol-bib-auto-style
The variables known from @ref{Minor Mode}.  There is no automatic
deduction of the file encoding, 8bit characters are usually encoded, and
there is usually no unique decoding.  @xref{Conversion}.
@end vtable

@pindex bibtex
The major difference between this language and the token language
@code{tex} is that the tokens for text-mode characters are most likely
enclosed by braces.  This has some problems (@pxref{TeX Macro
Problems}), but is required by the program @code{bibtex}.

The input methods and most features except super-/subscripts and images
work like in token language @code{tex} (@pxref{TeX Macro}):

@vtable @code
@item x-symbol-bib-header-groups-alist
@itemx x-symbol-bib-electric-ignore
@itemx x-symbol-bib-class-alist
@itemx x-symbol-bib-class-face-alist
Like in @ref{TeX Macro Features}.

@item x-symbol-bib-extra-menu-items
There are no special entries in the X-Symbol menu.
@end vtable

You might want change the conversion between characters and tokens in
language @code{bib} by changing:

@vtable @code
@item x-symbol-bib-user-table
@itemx x-symbol-tex-user-table
Use the former for @code{bib}-only changes, the latter also influences
the conversion with token language @code{tex}.
@end vtable

@c ====================================================================

@node TeXinfo Command, External Languages, BibTeX Macro, Supported Languages
@comment  node-name,  next,  previous,  up
@section Token Language ``@TeX{}info command'' (@code{texi})
@cindex Token Language @code{texi}
@cindex Language @code{texi}
@cindex @TeX{}info command
@cindex @code{texi}
@pindex texinfo
@pindex GNU texinfo

For buffers using the major mode @code{texinfo-mode}, we use token
language @dfn{@TeX{}info command} (@code{texi}).  This language does not
provide the display of super-/subscripts and images.  If the buffer
visits a file, X-Symbol mode is automatically turned on.  It is
controlled by:

@vtable @code
@item x-symbol-texi-modes
@itemx x-symbol-texi-auto-style
The variables known from @ref{Minor Mode}.  There is no automatic
deduction of the file encoding, 8bit characters are usually encoded, and
there is usually no unique decoding.  @xref{Conversion}.
@end vtable

With @code{x-symbol-8bits} having value @code{nil} (the default), it
might still happen that the saved file contains 8bit characters, since
token language @code{texi} does not define tokens for all characters in
the Latin charsets supported by X-Symbol.  @xref{Controlling 8bit
Coding}.

With @code{x-symbol-unique} having value @code{nil} (the default), we
have unique decoding anyway, since token language @code{texi} does only
define one token per character, i.e., the value is not important if
@code{x-symbol-8bits} is @code{nil}.  @xref{Unique Decoding}.

The input methods and the character info in the echo area are controlled
by:

@vtable @code
@item x-symbol-texi-header-groups-alist
Defines the headers and their characters for the language specific Grid
and Menu.

@item x-symbol-texi-extra-menu-items
There are no special entries in the X-Symbol menu.

@item x-symbol-texi-electric-ignore
There is no additional constraint to the ones mentioned in @ref{Input
Method Electric}.

@item x-symbol-texi-class-alist
@itemx x-symbol-texi-class-face-alist
Only a few token classes (@pxref{Char Group}) are defined, the most
interesting induces the character info (@pxref{Info}) to display
@samp{not as code} for @code{@@minus@{@}} (@code{@@minus@{@}} should not
used inside @code{@@code} and @code{@@example}).  No coloring scheme is
defined.
@end vtable

@pindex makeinfo
At least with @code{makeinfo-4.0}, you do not get accented characters in
the info file for the corresponding @TeX{}info commands in the
@file{.texi} file, the @sc{html} output might contain illegal
``@sc{sgml} entities'' like @code{&140;}.

@pindex texi2html
At least with @code{texi2html-1.62}, you see accented characters in the
@sc{html} output for the corresponding @TeX{}info commands in the
@file{.texi} file, but the output might also contain illegal ``@sc{sgml}
entities'' like @code{&140;}.

You might want change the conversion between characters and tokens in
language @code{texi} by changing:

@vtable @code
@itemx x-symbol-texi-user-table
Extra entries for the conversion.
@end vtable

@c ====================================================================

@node External Languages,  , TeXinfo Command, Supported Languages
@comment  node-name,  next,  previous,  up
@section Languages Defined in Other Emacs Packages
@cindex Foreign Languages
@cindex External Languages
@cindex Other Languages

It is no problem for other Emacs packages to define their own token
language (@pxref{Extending X-Symbol}).

I know of the following package---please check its manual for details.

@itemize @bullet
@item
@pindex ProofGeneral
@cindex Isabelle Symbol
Package @uref{@value{proofgeneralurl},ProofGeneral} defines token
language ``Isabelle symbol''.
@end itemize

@c ===========================================================================

@node X-Symbol Internals, Problems, Supported Languages, Top
@comment  node-name,  next,  previous,  up
@chapter X-Symbol Internals
@cindex Internals, X-Symbol
@cindex X-Symbol Internals

This section is outdated, it currently describes Version 3.4.2 of X-Symbol.

Package X-Symbol is distributed in two ways.  End-users should use the
@emph{binary package} which contains pre-compiled files.  X-Symbol
developers should use the @emph{source package} which contains some
additional files.

@menu
* Char Representation::         How X-Symbol represents X-Symbol chars.
* Defining Charsets::           How X-Symbol defines additional chars.
* Defining Input Methods::      How X-Symbol defines the input methods.
* Extending X-Symbol::          How to add fonts and token languages.
* Various Internals::           How X-Symbol handles other aspects.
* Design Alternatives::         Why X-Symbol is not designed differently.
* Language Internals::          How X-Symbol handles languages.
* Misc Internals::              Various.  TODO.
@end menu

@c ====================================================================

@node Char Representation, Defining Charsets, X-Symbol Internals, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Internal Representation of X-Symbol Characters
@cindex Charsym
@cindex Leading Character
@cindex Octet
@cindex Cstring
@cindex Mule Character

As mentioned in @ref{Pseudo Language}, most functions do not operate
on X-Symbol characters directly, they use ``x-symbol charsyms''.  These
charsyms have a symbol property @code{x-symbol-cstring} which points to
a string, called @dfn{cstring}, containing the X-Symbol character.

@itemize @bullet
@item
Under Emacs and XEmacs/Mule, the string only contains the character
which is a normal Mule character created by @code{make-char}.

@item
@pindex font-lock
Under XEmacs/no-Mule, the string only contains the 8bit character if the
X-Symbol character is a 8bit character according to
@code{x-symbol-default-coding} (@pxref{Default Coding}).  Otherwise, the
string contains of a @dfn{leading character} (with range @samp{\200} to
@samp{\237}) and an @dfn{octet}.  Package @code{font-lock} is used to
display them correctly as X-Symbol characters (@pxref{FAQ Strange
Chars}).  E.g., with @samp{\251} is @code{copyright}, we get

@lisp
(get 'Idotaccent 'x-symbol-cstring)
     @result{} "\235\251"
@end lisp
@end itemize

If the character is also a 8bit character in some encoding (@pxref{File
Coding}), the charsym also has the symbol property
@code{x-symbol-file-cstrings} for the representation in the file and
property @code{x-symbol-buffer-cstrings} to recognize character aliases
(@pxref{Char Aliases}).  E.g., under XEmacs/no-Mule, with @samp{\335} is
@code{Yacute}, @samp{\251} is @code{copyright}, we get

@lisp
(get 'Idotaccent 'x-symbol-file-cstrings)
     @result{} (iso-8859-9 "\335" iso-8859-3 "\251")
(get 'Idotaccent 'x-symbol-buffer-cstrings)
     @result{} (iso-8859-9 "\234\335" iso-8859-3 "\235\251")
@end lisp

The values are plists (@pxref{Property Lists,,,lispref,XEmacs Lisp
Reference Manual}) mapping the file coding to the strings in the file or 
the buffer, respectively.

After token languages have been initialized, the charsym also has the
symbol properties @code{x-symbol-tokens} (@pxref{Token Language}) and
@code{x-symbol-classes} (@pxref{Char Group}):

@lisp
(get 'Idotaccent 'x-symbol-tokens)
     @result{} (sgml "&#304;" tex "@{\\.I@}")
(get 'Idotaccent 'x-symbol-classes)
     @result{} (sgml (non-l1) tex (text aletter))
@end lisp

@c ====================================================================

@node Defining Charsets, Defining Input Methods, Char Representation, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Defining X-Symbol Charsets
@cindex Cset
@cindex Charset
@cindex Final Byte

An X-Symbol charset, called @dfn{cset} in the code and the docstrings,
handles one font used by package X-Symbol.  Each cset must use the
same char registry@minus{}encoding as the corresponding variables for
the fonts (@pxref{Installing Fonts Lisp}).

You have to tell X-Symbol, how to define Mule charsets with Emacs or
XEmacs/Mule and which leading character to use with XEmacs/no-Mule.  As
an example, we use the definition of the Adobe symbol font.

@lisp
@group
(defvar x-symbol-xsymb0-cset
  '((("adobe-fontspecific") ?\233 -3600)
    (xsymb0-left  "X-Symbol characters 0, left"  94 ?:) .
    (xsymb0-right "X-Symbol characters 0, right" 94 ?\;)))
@end group
@end lisp

Mule charsets (@pxref{Charsets,,,lispref,XEmacs Lisp Reference Manual})
may be used for 94 or 96 characters (this example: 94, only charset with
dimension 1 can be defined with X-Symbol).  Thus, if your font provides
more characters, you are likely to use both the left and the right half
of the font to define two Mule charsets.  For both of them, you have to
define a unique, free final character/byte of the standard ISO 2022
escape sequence designating the charset (this example: @samp{:} and
@samp{;}).  The remaining free (reserved by Emacs for users) are
@samp{>} and @samp{?}, the latter is already used in XEmacs.

For XEmacs/no-Mule, you have to define the leading character (this
example: @samp{\233}).

@vtable @code
@item x-symbol-latin1-cset
@itemx x-symbol-latin2-cset
@itemx x-symbol-latin3-cset
@itemx x-symbol-latin5-cset
Cset definitions only using the upper halves of the fonts where the
corresponding Mule charsets are known and which define characters which
are considered 8bit characters in the corresponding encoding, see
@ref{File Coding}.

@item x-symbol-xsymb0-cset
@itemx x-symbol-xsymb1-cset
Cset definitions using both halves of the fonts where no corresponding
Mule charset are yet known.
@end vtable

@c ====================================================================

@node Defining Input Methods, Extending X-Symbol, Defining Charsets, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Defining Input Methods
@cindex Input Method Internals
@cindex Internals, Input Method
@cindex Defining Input Methods

This is probably the hardest section in this manual@dots{}.

@menu
* Input Method Objectives::     Input methods should be intuitive/consistent.
* Intro Char Descriptions::     An example introducing char descriptions.
* Char Descriptions::           The aspects and the contexts of a character.
* Example Char Descriptions::   A complete example defining input methods.
* Customizing Input Methods::   How to customize the input methods.
@end menu


@node Input Method Objectives, Intro Char Descriptions, Defining Input Methods, Defining Input Methods
@comment  node-name,  next,  previous,  up
@subsection Defining Input Methods: Objectives
@cindex Input Method Objectives
@cindex Objectives, Input Methods
@cindex Consistent Input Methods

Input methods should be intuitive.  This requires consistency:

@itemize @bullet
@item
Characters should be found under the same header in the Grid and in the
Menu.

@item
If one character can be modified or rotated to another character
(@pxref{Input Method Context}), both should stand near to each other in
the Grid.  E.g., since @code{arrowsouthwest} rotates to
@code{arrowdown}, they stand next to each other.

@item
The key binding should be similar to the context of input method
Context.  If two characters are defined to have the same context, they
should have the same key prefix and the suffix should be a number which
increases with the ``modify-to'' behavior.  E.g., @code{reflexsubset}
with key binding @kbd{C-= < _ 2} modifies to @code{reflexsqsubset} with
key binding @kbd{C-= < _ 3}.

@item
Consistent definition of ``modify-to'' and ``rotate-to'': if A can be
modified to B and rotated to C and C can be modified to D, B can be
rotated to D in most cases.

@item
It should be possible to load character definitions later on, e.g., when
new token languages get initialized.

@itemize @minus
@item
Existing key bindings should not be overwritten.  If some of them have to
change, it should be done in a uniform way (solution: key suffix
@samp{1}).

@item
Also, modifying or rotating a new character to/from old ones should be
possible without changing the input definitions of the old characters.
@end itemize
@end itemize

Observation: It is impossible, especially with the possibility to load
character definitions later on, to define the input methods directly,
i.e., by something like @code{define-key}.  The solution is an indirect
definitions with ``character descriptions''.


@node Intro Char Descriptions, Char Descriptions, Input Method Objectives, Defining Input Methods
@comment  node-name,  next,  previous,  up
@subsection X-Symbol Character Descriptions: Example
@cindex Character Descriptions, Intro
@cindex Character Descriptions, Example

As an example for ``character descriptions'', look at the definition of
@code{longarrowright} in @code{x-symbol-xsymb1-table} (@samp{95} is the
encoding in the font and not of interest here).  Some terms are defined
in the next section:

@lisp
@group
(longarrowright 95
 (arrow) (size big . arrowright) nil ("->" t "-->") (emdash))
@end group
@end lisp

With this definition, package X-Symbol automatically defines:

@itemize @bullet
@item
Key bindings @kbd{C-= - - >} and @kbd{C-= - > 2}, the latter has suffix
2, because @kbd{C-= - >} is also ``wanted'' by @code{arrowright} which
now has the key binding @kbd{C-= - > 1} (the ``score'' of
@code{longarrowright} is higher, due to @samp{size big}).  @xref{Input
Method Keyboard}.

@item
@code{arrowright} modifies to @code{longarrowright}, which modifies to
@code{arrowright}.  @xref{Input Method Context}.

@item
@code{longarrowleft} rotates to @code{longarrowright}, which rotates to
@code{longarrowboth} (which rotates to @code{longarrowleft}).  (The
``rotate aspects'' are inherited from @code{arrowright}.)  @xref{Input
Method Context}.

@item
The following contexts can be modified to @code{longarrowright}:
@samp{-->} or @code{minus1} / @code{endash} / @code{macron} /
@code{emdash} / @code{hyphen} and @samp{->} (since all define context
@samp{-}) and @code{emdash} and @samp{>} (since @code{emdash} defines
context @samp{--}).  @samp{->} is used for @code{arrowright}, which has
a lower score, see above.  @xref{Input Method Context}.

@item
Input method Electric will change context @samp{-->} (is tagged with
@code{t} in the definition) to @code{longarrowright}, also @code{emdash}
and @samp{>} (only theoretically, since input method Electric will
produce @code{emdash} only in @TeX{}'s text mode, and
@code{longarrowright} only in @TeX{}'s math mode).  @xref{Input Method
Electric}.

@item
The character will appear in the Grid under the header @samp{Arrow}.
You will probably recognize that the placement is based on the modify-to
and rotate-to behavior above.  @xref{Input Method Grid}.

@item
The character will appear in the Menu under one of the headers
@samp{Arrow @var{n}}".  The submenus are sorted alphabetically.
@xref{Input Method Menu}.
@end itemize

Consider that this character would be missing in package X-Symbol and
you want to define your own character (in your own font).  With the
current scheme, the one line above is enough!  Have fun defining all the
consequences directly instead@dots{}.


@node Char Descriptions, Example Char Descriptions, Intro Char Descriptions, Defining Input Methods
@comment  node-name,  next,  previous,  up
@subsection Defining Input Methods by Character Descriptions
@cindex Character Descriptions
@cindex Aspects of Characters
@cindex Parent Character
@cindex Component of Characters
@cindex Modify Scores
@cindex Rotate Scores
@cindex Modify Aspects
@cindex Rotate Aspects
@cindex Score of a Character
@cindex Modify Chain
@cindex Exclusive Modify Chain
@cindex Rotate Chain
@cindex Horizontal Chain
@cindex Key Chain

Characters are defined with @dfn{character descriptions} which consist
of different @dfn{aspects} and @dfn{contexts}, which can also be
inherited from a @dfn{parent} character.  All characters which are
connected with parents, form a @dfn{component}.  Aspects and contexts
are used to determine the modify-to and rotate-to chain for characters,
the contexts for input method Context and Electric, the key bindings,
and the position in the Menu and the Grid.

If you want to check the component, scores, etc of a specific character,
look at the symbol property (e.g., with @kbd{M-x hyper-apropos-get-doc})
of the corresponding charsym, e.g., @code{arrowright}.  See also the
docstrings of @code{x-symbol-init-cset} and @code{x-symbol-init-input}.

Remember, all characters which are connected with parents, form a
component.  @dfn{Contexts} are the contexts of input method Context
(@pxref{Input Method Context}).  If a table entry of a charsym does not
define its own contexts, they are the same as the contexts of the
charsym in an earlier position in the modify chain (see below), or the
contexts of the first charsym with defined contexts in the modify chain.
The @dfn{modify context} of a charsym is the first context.

@vtable @code
@item x-symbol-rotate-aspects-alist
Characters in the same component whose aspects only differ by their
@code{direction} (@code{east},@dots{}), a key in this alist, are
circularly connected by ``rotate-to''.  The sequence in the @dfn{rotate
chain} is determined by @dfn{rotate scores} depending on the values in
the @dfn{rotate aspects}.  Charsyms with the same ``rotate-aspects'' are
not connected (charsyms with the smallest modify scores are preferred).

@lisp
(get 'longarrowright 'x-symbol-rotate-aspects)
     @result{} (-1500 direction east)
@end lisp

@item x-symbol-modify-aspects-alist
Characters in the same components whose aspects only differ by their
@code{size} (@code{big},@dots{}), @code{shape} (@code{round},
@code{square}@dots{}) and/or @code{shift} (@code{up},
@code{down},@dots{}), keys in this alist, are circularly connected by
``modify-to'', if all their modify contexts are used exclusively, i.e.,
no other modify chain uses any of them.  The sequence in the @dfn{modify
chain} is determined by @dfn{modify scores} depending on the values in
the @dfn{modify aspects}, the charsym score defined in the definition
tables and the score of the whole cset (@pxref{Defining Charsets}).

@lisp
(get 'longarrowright 'x-symbol-score)
     @result{} -3500
(get 'longarrowright 'x-symbol-modify-aspects)
     @result{} (1500 shift nil shape nil size big)
@end lisp

Otherwise, the ``modify chain'' is divided into modify subchains, which
are those charsyms sharing the same modify context.  All modify
subchains using the same modify context, build a @dfn{horizontal chain}
whose charsyms are circularly connected by ``modify-to''.

We build a @dfn{key chain} for all contexts (not just modify contexts),
consisting of all charsyms (sorted according to modify scores) having
the context.  Input method Context modifies the context to the first
charsym in the key chain.

@item x-symbol-key-suffix-string
If there is only one charsym in the key chain, @kbd{C-=} plus the
context inserts the charsym.  Otherwise, we determine a suffix for each
charsym in the key chain by its index and this string.  @kbd{C-=} plus
the context plus the suffix inserts the charsym.
@end vtable


@node Example Char Descriptions, Customizing Input Methods, Char Descriptions, Defining Input Methods
@comment  node-name,  next,  previous,  up
@subsection Defining Input Methods: Example
@cindex Character Descriptions, Example

@smallexample
An example:  Modify  Modify  Rotate  Rotate  Modify   Other
             Score   Aspect  Score   Aspect  Context  Contexts
--------------------------------------------------------------
charsym 1w    150     nil     100     west    `a'      `c'
charsym 2w    200     nil     100     west    `b'       -
charsym 3w    350     big     100     west   (`b')     (-)
charsym 1e    100     nil     200     east   (`a')    (`b')
charsym 2e    250     big     200     east    `a'      `b'
charsym 3e    300     big     200     east    `a'       -
charsym 1n    100     nil     300     north   `d'      `c'
charsym 2n    200     big     300     north   `c'       -
@end smallexample

Assuming that all charsyms form one component, we have:

@smallexample
Rotate chains:     (1w,2w)-1e-1n @r{and} 3w-(2e,3e)-2n.
Modify chains:     1w-2w-3w @r{and} 1e-2w-3w and 1n-2n.
Horizontal chains: 1e-1w-2e-3e       @r{(for modify context @samp{a})}
                   2w-3w             @r{(for modify context @samp{b})}
Key chains:        1e-1w-2e-3e       @r{(for context @samp{a})}
                   1e-2w-2e-3w       @r{(for context @samp{b})}
                   1n-1w-2n          @r{(for context @samp{c})}
                   1n                @r{(for context @samp{d})}
@end smallexample

That makes the following bindings:

@smallexample
Rotate-to: 1w->1e, 2w->1e, 1e->1n, 1n->1w
           3w->2e, 2e->2n, 3e->2n, 2n->3w
Modify-to: 1e->1w, 1w->2e, 2e->3e, 3e->1e     @r{(horizontal chain)}
           2w->3w, 3w->2w                     @r{(horizontal chain)}
           1n->2n, 2n->1n  @r{(modify chain with exclusive modify contexts)}
CONTEXTS:  `a'->1e, `b'->1e, `c'->1n, `d'->1n
KEY:       `a1'=1e, `a2'=1w, `a3'=2e, `a4'=3e, `b1'=1e, ..., `d'=1n
@end smallexample


@node Customizing Input Methods,  , Example Char Descriptions, Defining Input Methods
@comment  node-name,  next,  previous,  up
@subsection Customizing Input Methods
@cindex Customizing Input Methods
@cindex Input Methods Customization

When defining contexts for characters, you should try to use default
contexts to make them and key bindings as consistent as possible.  E.g.,
package X-Symbol only defines explicit contexts for 186 of the 437
characters.

@vtable @code
@item x-symbol-group-input-alist
Defines default scores and bindings for characters of a group
(@pxref{Char Group}).  E.g., the definition (in
@code{x-symbol-latin1-table})

@lisp
(aacute 225 (acute "a" Aacute))
@end lisp

defines @code{aacute} without any explicit contexts, but having the
group @code{acute} and the subgroup @samp{a}.  The default input for the 
group is defined by the following element in this variable:

@lisp
(acute 0 "%s'" t "'%s")
@end lisp

That means: 0 is added to the normal ``modify-score'' of the character.
@samp{%s'} and @samp{'%s} with @samp{%s} substituted by the subgroup,
i.e., @samp{a'} and @samp{'a}, are the contexts for @code{aacute}.  The
context @samp{'a} is also used for input method Electric since it is
prefixed by @code{t}.

@item x-symbol-key-min-length
It is quite unlikely that a one-character context is not the prefix of
another context, at least when loading additional font definitions.  In
order not to have to change key bindings @kbd{C-= @var{key}} to @kbd{C-=
@var{key} 1}, it is required that the length of the key binding without
@kbd{C-=} is at least 2.
@end vtable

@c ====================================================================

@node Extending X-Symbol, Various Internals, Defining Input Methods, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Extending Package X-Symbol
@cindex Extending X-Symbol

In this section, you are told what to consider and what to do when
extending package X-Symbol with new characters and new token languages.
If you only want to define a token language using existing characters,
you only have to read the last section.

@menu
* Extending with Fonts::        How to add fonts to X-Symbol.
* Input Definitions::           Guidelines for input definitions.
* Font Definition File::        How to define new character in a file.
* Language Extension File::     Extending an existing language.
* Language Definition File::    Defining a new language.
@end menu


@node Extending with Fonts, Input Definitions, Extending X-Symbol, Extending X-Symbol
@comment  node-name,  next,  previous,  up
@subsection Extending X-Symbol with New Fonts
@cindex Extending with Fonts
@cindex Adding Fonts
@cindex Font Extension
@cindex Guidelines, Font Extension

If you add a new token language to package X-Symbol which should
represent tokens by characters which are not yet defined by package
X-Symbol, you have to add a new font to package X-Symbol, first.

When adding new fonts to package X-Symbol, consider that X-Symbol has to
run under Emacs, XEmacs/Mule and XEmacs/no-Mule.

Running under Emacs and XEmacs/Mule requires that you cannot use all
encodings in a font for characters: you should probably only use
encodings 33 to 126 and 160 to 255.  You should also use a unique pair
of charset properties @samp{CHARSET_REGISTRY} and
@samp{CHARSET_ENCODING}.

Running under XEmacs/no-Mule can leads to problems when major modes do
not check whether the previous character is an escape character (in our
case, a leading character, @pxref{Char Representation}) when looking at a
character.  Thus, you should probably not use encodings which represent
characters in your default font with a special syntax.

@itemize @bullet
@item
In general, escape sequences use the digits of the current font.  Thus,
you should probably define the encodings 48 to 57 as digits @samp{0} to
@samp{9}.

@item
In La@TeX{} buffers, characters in @samp{$%\@{@}} have a special
syntax.  Thus, you should probably not use encodings 36, 37,
92, 123 and 125 for characters which could also be useful with token
languages @code{tex} and @code{utex}.

@item
In HTML buffers, characters in @samp{&<>} have a special syntax.  Thus,
you should probably not use encodings 38, 60 and 62 for
characters which could also be useful with token language @code{sgml}.
@end itemize

You have to tell package X-Symbol which fonts to use for the normal
text, subscripts and superscripts.  @xref{Installing Fonts Lisp}.

You have to tell X-Symbol, how to define Mule charsets with Emacs and
XEmacs/Mule and which leading character to use with XEmacs/no-Mule.
@xref{Defining Charsets}.


@node Input Definitions, Font Definition File, Extending with Fonts, Extending X-Symbol
@comment  node-name,  next,  previous,  up
@subsection Guidelines for Input Definitions
@cindex Input Definitions, Guidelines
@cindex Guidelines, Input Definitions

Read section @ref{Defining Input Methods}.  Look at the tables in
@file{x-symbol.el}.  Here are some guidelines of how to define the input
methods for new characters:

@enumerate
@item
Define reasonable character groups for new characters, see @ref{Char
Group}.  E.g., if you add the IPA font for phonetic characters, you
are likely to define at least one additional charset group.  If you do
not know whether to use one or two groups for a set of characters, use
two.

@item
Define under which Grid/Menu header the character of the new character
group should appear.  You may also want to add additional headers for
these characters.  @xref{Char Group}.

@item
If reasonable, define default contexts for characters of a group, see
@ref{Customizing Input Methods}.

@item
For the other characters, define contexts by Ascii sequences which look
similar to the character.

@item
Form a component for a set of characters which are strongly related to
each other.  In most cases, characters of a component are in the same
group but not vice versa.  E.g., the simple arrows already defined by
package X-Symbol form one component.  You form a component of characters
by specifying parents in their definition, see @ref{Char Descriptions}.

@item
Use aspects to describe the new characters.  Add new aspects to
@code{x-symbol-modify-aspects-alist} and
@code{x-symbol-rotate-aspects-alist} if necessary (@pxref{Char
Descriptions}).

@item
Finish the definition of your font file (@pxref{Font Definition File}),
load it with @kbd{M-x load-file}, and initialize the input methods,
e.g., by invoking the grid (@kbd{M-x x-symbol-grid}).

@item
If there are no errors, you are likely to get warnings about equal
modify scores.  In this case, the sequence of characters in the
modify-to chain is random, so are the numerical suffixes of key bindings.

@enumerate a
@item
Define a base score for the whole X-Symbol charset (``cset score'')
which should be a positive number in order not to change the key bindings 
of previously defined X-Symbol characters.

@item
Define reasonable scores for newly defined aspects and character groups.

@item
Finally, fine-tune your definitions by charsym scores in the tables.
This should be necessary only for a few characters.
@end enumerate
@end enumerate


@node Font Definition File, Language Extension File, Input Definitions, Extending X-Symbol
@comment  node-name,  next,  previous,  up
@subsection Emacs Lisp File Defining a New Font
@cindex Font Definition File

Now put all things together in a separate font definition file.  You
should not put it in a language definition file.

Here is a tiny example using only the lower half of the font:

@lisp
(provide 'x-symbol-myfont)
@group
(defvar x-symbol-myfont-fonts
  '(("-xsymb-myfont-medium-r-normal--14-140-75-75-p-85-xsymb-myfont")
    ("-xsymb-myfont_sub-medium-r-normal--12-120-75-75-p-74-xsymb-myfont")
    ("-xsymb-myfont_sup-medium-r-normal--12-120-75-75-p-74-xsymb-myfont")))
@end group
@group
(defvar x-symbol-myfont-cset
  '((("xsymb-myfont") ?\200 1000)
    (myfont-left "My font characters, left"  94 63) . nil))
@end group
@end lisp

@lisp
@group
(defvar x-symbol-myfont-table
  '((longarrownortheast 33 (arrow) (size big . arrownortheast))
    (koerper 34 (setsymbol "K"))
    (circleS 35 (symbol "S") nil nil "SO")))
@end group
@group
(x-symbol-init-cset x-symbol-myfont-cset x-symbol-myfont-fonts
                      x-symbol-myfont-table)
@end group
@end lisp

Due to an XEmacs bug with char syntax @code{inherit}, you should also
add the following line to files @file{x-symbol-xmas20.el} and
@file{x-symbol-xmas21.el}:

@lisp
  (modify-syntax-entry ?\200 "\\" (standard-syntax-table))
@end lisp


@node Language Extension File, Language Definition File, Font Definition File, Extending X-Symbol
@comment  node-name,  next,  previous,  up
@subsection Emacs Lisp File Extending a Token Language
@cindex Language Definition File

If you want to use the new font to extend an existing token language,
define a new token language which inherits most variables from the
``parent language''.  E.g., token language @code{utex} inherits most
variables from @code{tex}, see @file{x-symbol-utex.el}.

A language must define variables for all language aspects, see
@ref{Language Internals}.  Our example defines a language @code{mytex}
using the additional characters from @ref{Font Definition File}.

First, you have to register the language in a startup file:

@lisp
(defvar x-symbol-mytex-name "My TeX macro")
(defvar x-symbol-mytex-modes nil)
(x-symbol-register-language 'mytex 'x-symbol-mytex x-symbol-mytex-modes)
@end lisp

The language definition file should look like (leaving out most parts
which are similar to the ones in @file{x-symbol-utex.el}):

@lisp
(provide 'x-symbol-mytex)
(require 'x-symbol-tex)
(defvar x-symbol-mytex-required-fonts '(x-symbol-myfont))
(put 'mytex 'x-symbol-font-lock-keywords 'x-symbol-tex-font-lock-keywords)
@end lisp

@lisp
(defvar x-symbol-mytex-user-table nil)
@group
(defvar x-symbol-mytex-myfont-table
  '((longarrownortheast (math arrow user) "\\longnortheastarrow")
    (koerper (math letter user) "\\setK")
    (circleS (math ordinary amssymb) "\\circledS")))
@end group
@group
(defvar x-symbol-mytex-table
  (append x-symbol-mytex-user-table
          '(nil)
          x-symbol-mytex-myfont-table
          x-symbol-tex-table))
@end group
@end lisp

It is important that you do not define a variable for the language
access @code{x-symbol-font-lock-keywords}, but rather use the variable
of the parent language directly, see @ref{Language Internals}.

During the testing phase, you should probably leave out the
@samp{'(nil)} which prevents warnings about redefinitions for the
following elements.


@node Language Definition File,  , Language Extension File, Extending X-Symbol
@comment  node-name,  next,  previous,  up
@subsection Emacs Lisp File Defining a New Token Language
@cindex Language Definition File

You might also want to define a new token language not based on another
language.

As an example, consider a token language ``My Unicode'' (@code{myuc})
for buffers with major mode @code{myuc-mode}.  Thus, we register the
language by:

@lisp
(defvar x-symbol-myuc-name "My Unicode")
(defvar x-symbol-myuc-modes '(myuc-mode))
(x-symbol-register-language 'myuc 'x-symbol-myuc x-symbol-myuc-modes)
@end lisp

Each token if language @code{myuc} consists of @samp{#} plus the
hexadecimal representation of the Unicode with hexadecimal values where
the case of digits is not important and the preferred case is upcase.  A 
single @samp{#} is represented by the token @code{##}.  In order to be
more flexible, we want to define the tokens by their decimal value in
the table.  There are no subscript and no images.  The code below
(@file{x-symbol-myuc.el}) is included in the source distribution of
package X-Symbol.

@lisp
(provide 'x-symbol-myuc)
(defvar x-symbol-myuc-required-fonts nil)
(defvar x-symbol-myuc-modeline-name "myuc")
@group
(defvar x-symbol-myuc-class-alist
  '((VALID "My Unicode" (x-symbol-info-face))
    (INVALID "no My Unicode" (red x-symbol-info-face))))
@end group
(defvar x-symbol-myuc-font-lock-keywords nil)
(defvar x-symbol-myuc-image-keywords nil)
@dots{}
@end lisp

@lisp
(defvar x-symbol-myuc-case-insensitive 'upcase)
(defvar x-symbol-myuc-token-shape '(?# "#[0-9A-Fa-f]+\\'" . "[0-9A-Fa-f]"))
(defvar x-symbol-myuc-exec-specs '(nil (nil . "#[0-9A-Fa-f]+")))
(defvar x-symbol-myuc-input-token-ignore nil)
@end lisp

@lisp
@group
(defun x-symbol-myuc-default-token-list (tokens)
  (list (format "#%X" (car tokens))))
@end group
(defvar x-symbol-myuc-token-list 'x-symbol-myuc-default-token-list)
(defvar x-symbol-myuc-user-table nil)
@group
(defvar x-symbol-myuc-xsymb0-table
  '((alpha () 945) (beta () 946)))
@end group
@group
(defvar x-symbol-myuc-table
  (append x-symbol-myuc-user-table x-symbol-myuc-xsymb0-table))
@end group
@dots{}
@end lisp

@c ====================================================================

@node Various Internals, Design Alternatives, Extending X-Symbol, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Various Internals

@menu
* Tagging Insert Commands::     Don't break input methods Token and Electric.
* Avoiding Flickering::         Moving cursor in invisible commands.
@end menu


@node Tagging Insert Commands, Avoiding Flickering, Various Internals, Various Internals
@comment  node-name,  next,  previous,  up
@subsection Tagging Insert Commands for Token and Electric
@cindex Insert Commands, Tagging
@cindex Tagging Insert Commands
@cindex Recognizing Insert Commands

Input methods Token (@pxref{Input Method Token}) and Electric
(@pxref{Input Method Electric}) stop their auto replacement if you use a 
command which is not an insert command.

@ftable @code
@item self-insert-command
@itemx newline
@itemx newline-and-indent
@itemx reindent-then-newline-and-indent
@itemx tex-insert-quote
@itemx TeX-insert-quote
@itemx TeX-insert-punctuation
@itemx TeX-insert-dollar
@itemx sgml-close-angle
@itemx sgml-slash
These commands and commands aliased to these are recognized as input
commands by having a non-@code{nil} value of its symbol property
@code{x-symbol-input}.
@end ftable


@node Avoiding Flickering,  , Tagging Insert Commands, Various Internals
@comment  node-name,  next,  previous,  up
@subsection Avoiding Hide/Show-Invisible Flickering
@cindex Avoiding Flickering
@cindex Flickering, Invisible
@cindex Invisible Flickering

Starting a command makes a previously revealed super- or subscript
command (@pxref{Super and Subscripts}) invisible again.  Repeatedly
invoking commands which moves the point just by a small amount can lead
to some flickering.

@ftable @code
@item forward-char
@itemx forward-char-command
@itemx backward-char
@itemx backward-char-command
If the point position after the execution of these commands is still
``at'' the super- or subscript command, the command won't be made
invisible at the first place.  Each of these four commands have a
function (@code{1+} and @code{1-}) as the value of its symbol property
@code{x-symbol-point-function} which returns the position ``after'' when
called with the position ``before''.
@end ftable

@c ====================================================================

@node Design Alternatives, Language Internals, Various Internals, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Design Alternatives

This section describes potential design alternatives and why they were
not used.

@menu
* Alt Token Representations::   Why we need the conversion.
* Alt Global Mode::             How to turn on X-Symbol globally.
* Alt Auto Conversion::         When do we convert automatically.
@end menu


@node Alt Token Representations, Alt Global Mode, Design Alternatives, Design Alternatives
@comment  node-name,  next,  previous,  up
@subsection Alternative Token Representations
@cindex Alternative Token Representations
@cindex Token Representation, Alternatives

Package X-Symbol represents tokens in the file by characters in the
buffer.  This requires an automatic conversion when visiting a file or
saving a buffer, see @ref{Conversion}.

Another possibility would be to use the tokens directly in the buffer
and just display them differently.  You would need no conversion and you
could copy the text easily to a message buffer.  This could be done by a
special face and an additional font-lock keyword for every token.  The
disadvantages make this approach unfeasible:

@itemize @bullet
@item
The editing commands would work on the tokens which are invisible for
the user.

@item
Extremely resource and startup-time consuming.  If as many characters
should be supported as done by package X-Symbol, including superscripts
and subscripts, more than 2000 faces with display tables would have to
be defined even without considering char aliases!

@item
Time consuming.  More than 2000 entries in you font-lock keywords would
slow down the fontification considerably, which would be too much even
when using @code{lazy-shot}!
@end itemize

Another possibility would be to adapt @TeX{} to the representations of
the corresponding characters in Emacs' buffer.  Again, you would need no
conversion.  The disadvantages make this approach too restrictive:

@itemize @bullet
@item
You cannot adopt @sc{sgml} to this approach.

@item
You cannot read normal La@TeX{} files directly, you do not write normal
La@TeX{} files.

@item
You would have different @TeX{} versions: one for X-Symbol with Emacs
and XEmacs/Mule, one with XEmacs/no-Mule.

@item
If you are not an extremely good @TeX{} hacker, it would be impossible
to adopt this approach to support more than 256 characters.
@end itemize

A third alternative would be very similar to the method used in this
package.  There would be just a slight difference when running under
XEmacs/no-Mule: the internal representation of a character is always
just one character, but we would also provide font properties for
characters not of your default font.  The disadvantages make this
approach too unsafe:

@itemize @bullet
@item
Problems with current search/replace commands.

@item
Problems with the current version of @code{font-lock} (it should @emph{never}
overwrite the font property for this character, even if the character
matches some @var{match} in @code{font-lock-keywords} and
@var{overwrite} is non-@code{nil}).  This gets even more difficult with
superscripts/subscripts.

@item
Unless you can provide a syntax table for faces (you cannot), characters
in different faces with the same encoding are in the same syntax class,
which is irritating: e.g., @code{\leftrightarrow} and @code{\approx}
would be delimiters.
@end itemize


@node Alt Global Mode, Alt Auto Conversion, Alt Token Representations, Design Alternatives
@comment  node-name,  next,  previous,  up
@subsection Alternative Ways to Turn on X-Symbol Globally
@cindex Alternative Global Mode
@cindex Global Mode, Alternatives
@cindex Turn on Globally, Alternatives

This package hooks itself into @code{hack-local-variables-hook} which
makes the installation very simple.

Another possibility would be to use the major-mode hooks which is the
normal way how to turn on a minor mode.  The disadvantages are:

@itemize @bullet
@item
The installation is more complicated.

@item
Local variables in files are not yet processed (this was the main reason
not to do it this way).
@end itemize

Another possibility would be to hook X-Symbol into
@code{find-file-hooks}, as it is done in old versions of package
X-Symbol.  It would be as easy as the current approach but we would have
to be careful with sequence of functions in @code{find-file-hooks},
especially with the function hooked in by @code{font-lock}.


@node Alt Auto Conversion,  , Alt Global Mode, Design Alternatives
@comment  node-name,  next,  previous,  up
@subsection Alternative Auto Conversion Methods
@cindex Alternative Auto Conversion
@cindex Auto Conversion, Alternatives

@vindex hack-local-variables-hook
@vindex after-insert-file-functions
@vindex write-region-annotate-functions
Without package @code{crypt}, this package automatically decodes tokens
when turning on the minor mode (in @code{hack-local-variables-hook},
@pxref{Alt Global Mode}) or in @code{after-insert-file-functions}.  This
package automatically encodes characters in
@code{write-region-annotate-functions}.  The disadvantage is that the
possibility to change buffers in @code{write-region-annotate-functions}
is not official (@pxref{Wishlist Emacs}), i.e., not mentioned in the
docstring (only mentioned for corresponding encode-functions of package
@code{format} which use a similar loop in the C code).

@vindex write-file-hooks
With package @code{crypt}, this package automatically decodes tokens
when turning on the minor mode.  This package automatically encodes
characters in @code{write-file-hooks}.  The disadvantage is that the
encoding is slower (use @code{jka-compr} instead @code{crypt}) and the
problem with @code{vc-next-action} (@pxref{Spurious Encodings}).

@vindex write-file-data-hooks
Without package @code{crypt}, Version 2.6 of this package automatically
encoded characters in @code{write-file-data-hooks}.  The advantage was
that changing buffers there is official, the disadvantage is that it is
also more complicated.

@pindex format
A totally different method would be to use package @code{format}.
Unfortunately, this is not really possible, since a @var{regexp} in
@code{format-alist} is much too weak, i.e., X-Symbol's decoding does not
change any file headers which would represent the file format.  In
XEmacs, this package also fails to work properly with @code{jka-compr}
and @code{crypt}.

@c ====================================================================

@node Language Internals, Misc Internals, Design Alternatives, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Language Internals
@cindex Language Internals
@cindex Token Language Internals
@cindex Internals, Languages
@cindex Registered Languages
@cindex Loaded Language
@cindex Initialized Language
@cindex Language Access
@cindex Accessing Language Depending Variables

In order to use a token language or accessing one of the language
dependent values, the following conditions must be met:

@itemize @bullet
@item
The language must be @dfn{registered}.  This makes it possible to select
the language in the menus.  It also prevents to load a potentially
dangerous file when a file specifies a buffer-local value of
@code{x-symbol-language}.

@ftable @code
@item x-symbol-register-language
Registering a language includes stating the name of the feature (i.e., a
file) which provides the language.  The name of the language must have
been already defined.
@end ftable

@item
The file providing the language must have been @dfn{loaded}.  This will
be done automatically when the language is initialized.  Customizing
X-Symbol will also load the language files.

@item
The language must be @dfn{initialized}.  This will be done automatically
if the language is used.  This loads the language file and fails if the
language has not been registered.  If some minor language information is
needed, e.g., in the highlight menu of the Grid (@pxref{Input Method
Grid}), you should initialize the language explicitly, e.g., by the
following command:

@table @kbd
@item M-x x-symbol-init-language-interactive
@findex x-symbol-init-language-interactive
Initialized a token language if it is not already initialized.
@end table
@end itemize

Language dependent values are accessed by language accesses:

@table @code
@item x-symbol-language-value
@findex x-symbol-language-value
Returns the language depending value.  Also initializes language if
necessary.  E.g., we get the name of a language by the language access
@code{x-symbol-name}.  With a simplified expansion, we get

@lisp
(x-symbol-language-value 'x-symbol-name 'tex)
     @expansion{} (symbol-value (get 'tex 'x-symbol-name))
     @result{} (symbol-value 'x-symbol-tex-name)
     @result{} "TeX macro"
@end lisp

@item x-symbol-language-access-alist
@vindex x-symbol-language-access-alist
List of all language accesses.  A token language @emph{must} define all
variables accessed by language accesses.  A @dfn{language access} is a
property of the language symbol, its value is the symbol naming a
variable whose value is used.

If the language is a derived language, e.g., like language @code{utex},
the language access @code{x-symbol-font-lock-keywords}, should point
directly to the variable of the parent language (here @code{tex}), see
file @file{x-symbol-utex.el}.
@end table


@c Hi, X-Symbol's interna have changed considerably with v4.3.1-alpha.  For
@c token languages to work with new versions of X-Symbol, it is important
@c to define some new language accesses (you
@c can also delete some if you do not want X-Symbol backward compatiblity)

@c The reason for the change is:

@c  * more general ways to define the "grammar" of tokens, also useful for
@c    ProofGeneral's languages, see below.
@c  * faster conversion (I also dropped the support of executables)


@c As an example, let's look at x-symbol-texi.el:

@c The following vars must now be defined (value nil...)

@c    (defvar x-symbol-texi-generated-data nil)

@c Now the interesting part:

@c (defvar x-symbol-texi-token-grammar
@c   '(x-symbol-make-grammar
@c     :encode-spec (?@)
@c     :decode-regexp
@c     "@\\(?:[A-Za-z]+{[A-Za-z]?}\\|[{}]\\|[~^\"'`][A-Za-z]\\|,{[A-Za-z]}\\)"
@c     :decode-spec (?@))
@c   "Token grammar for language `texi'.")

@c In short, not too difficult if the token grammar is regular (even
@c simpler for SGML entities).  The good news: powerful enough for
@c irregular token grammar which couldn't be defined with previous versions
@c of X-Symbol.

@c The conversion now works as follows:

@c  1. decode (token->char): search for regexp, then decode match except if
@c     context is "bad".
@c  2. encode (char->token): search for non-ascii/8bit, then encode match.
@c     Surround by spaces if context is "bad".

@c The "token grammar" is simply a definition of the regexp and the bad
@c contexts, which can be different for different "shapes" of the token.
@c A special BEFORE context is the escape character: this character may
@c appear exactly even times before the token; it will be used for
@c all shapes.

@c Lets assume a language "Isabelle Symbol" plus symbols for identifiers
@c and operators (see below for lisp coding):

@c   shape nil:  \<NAME>
@c   shape id:   [A-Za-z_][A-Za-z_0-9]+
@c   shape op:   [<>!+-*/|&]+

@c To make the conversion fast, the shape must be given at definition time,
@c i.e., the init must get tokens in the form (TOKEN . SHAPE).
@c Either per hand or computed via function in language access
@c x-symbol-token-list...

@c The decode-regexp must match all tokens and:

@c  a. should be specific enough to make the conversion fast
@c  b. must be general enough to match strings which should not be
@c     considered to contain a token even if a substring is a token (to
@c     avoid excessive context checking)

@c In our example, the regexp would be something like

@c   "\\\\<[A-Za-z]+>\\|[A-Za-z_][A-Za-z_0-9]+\\|[<>!+-*/|&]+"

@c No bad context has to be defined for decoding since the regexp is
@c general enough.

@c For encoding, we have to define the following bad contexts (no context
@c can be defined for shape nil):

@c   shape id:  BEFORE: [A-Za-z_0-9], AFTER: [A-Za-z_0-9]
@c   shape op:  BEFORE: [<>!+-*/|&],  AFTER: [<>!+-*/|&]

@c BEFORE is a regexp used via `string-match' with the character before the
@c character to encode; if it matches, we put a space before the token for
@c the character.  AFTER is a regexp used with `looking-at' with point
@c after the character.  We would put a space after the token.

@c There is probably no escape char defined for Isabelle Symbols (i.e.,
@c "\\" is no token).

@c The input-token-grammar is very similar to the decode-grammar: the
@c regexp should end with \\' such that only matches ending at point will
@c get replaced, and we should define a bad context (which will be
@c tried to match against `last-command-char').

@c This makes the grammar below.

@c Hope this helps,
@c - Christoph


@c (defvar x-symbol-xisa-token-grammar
@c   '(x-symbol-make-grammar
@c     :encode-spec '(((id . "[A-Za-z_0-9]") (op . "[<>!+-*/|&]")) .
@c                ((id . "[A-Za-z_0-9]") (op . "[<>!+-*/|&]")))
@c     :decode-spec nil
@c     :decode-regexp "\\\\<[A-Za-z]+>\\|[A-Za-z_][A-Za-z_0-9]+\\|[<>!+-*/|&]+"
@c     :token-list #'x-symbol-xisa-default-token-list))

@c (defvar x-symbol-xisa-input-token-grammar
@c   '(("\\(?:\\\\<[A-Za-z]+>\\|[A-Za-z_][A-Za-z_0-9]+\\|[<>!+-*/|&]+\\)\\'")
@c     ((id . "[A-Za-z_0-9]") (op . "[<>!+-*/|&]"))
@c     (id . "[A-Za-z_0-9]") (op . "[<>!+-*/|&]")))

@c (defun x-symbol-xisa-default-token-list (tokens)
@c   (mapcar (lambda (x)
@c          (cons x (cond ((string-match "\\`[A-Za-z_][A-Za-z_0-9]+\\'" x) 'id)
@c                        ((string-match "\\`[<>!+-*/|&]+\\'" x) 'op))))
@c        tokens))

@c (defun x-symbol-xisa-table
@c   '((product () "\\<Prod>")
@c     (longarrowright () "-->")
@c     (alpha () "alpha")))


@c ====================================================================

@node Misc Internals,  , Language Internals, X-Symbol Internals
@comment  node-name,  next,  previous,  up
@section Miscellaneous Internals

TODO.  This is currently just a collection of unrelated stuff.

@c was in "Char Group
Characters might also define a @dfn{subgroup} which is a string defining
some order on characters in the same group (@pxref{Char Group}) and is
also used for default contexts/bindings (@pxref{Customizing Input
Methods}).

@vtable @code
@item x-symbol-group-syntax-alist
Lists all valid character groups.  Under Emacs and XEmacs/Mule, this
list also determines the syntax of characters.
@end vtable

The character group could probably also be used to define character
categories if they are implemented in XEmacs.

@c ===========================================================================

@node Problems, History, X-Symbol Internals, Top
@comment  node-name,  next,  previous,  up
@chapter Problems, Troubleshooting
@cindex Problems
@cindex Troubleshooting
@cindex Annoyances
@cindex Bugs

This section is based on a successful installation of package X-Symbol.
@xref{Checking Installation}.

@menu
* Nomule Problems::             X-Symbol provides a @emph{poor} man's Mule.
* Spurious Encodings::          Some commands turn off X-Symbol mode.
* No Encoding::                 The encoding does not work in a rare case.
* FAQ::                         Frequently asked questions.
* Bug Reports::                 How to contact the maintainer of X-Symbol.
@end menu

@c ===========================================================================

@node Nomule Problems, Spurious Encodings, Problems, Problems
@comment  node-name,  next,  previous,  up
@section Problems under XEmacs/no-Mule
@cindex Nomule Problems
@cindex @code{transpose-chars} Problems
@cindex Replace Problems
@cindex Rectangle Problems
@cindex Abbrev Problems
@cindex Invisible Point
@cindex Parenthesis Problems
@cindex Fill Problems

If you use package X-Symbol under XEmacs/no-Mule, there are some
annoyances which result from the fact that additional ``X-Symbol
characters'' are represented by two characters internally.  Package
X-Symbol just provides a kind of ``@emph{poor} man's Mule'', see
@ref{Poor Mans Mule}.  This means: I have provided workarounds for the
most annoying ones, but some remain (and will remain: I am not going to
provide workarounds for these):

@itemize @bullet
@item
If @code{font-lock} is not prepared to display these two-character
sequences, i.e., if you installation is incomplete (@pxref{Role of
font-lock}), they look like @samp{\233a} instead @code{alpha}.

@item
Commands which add more than one entry to the @code{buffer-undo-list}
and involve X-Symbol characters might lead to strange results,
e.g. @kbd{C-t} (@code{transpose-chars}) with point between character
@code{alpha} and @samp{b}, leads to @code{beta}@samp{a}.  Simple
deletion and insertion works OK, though.

@item
Selecting or inserting a rectangle with X-Symbol characters on the left
or right margin might not work properly.

@item
Be careful with @kbd{M-%} (@code{query-replace}): the first character of
@var{from-string} can probably match the second of the two ``internal''
characters of an X-Symbol character.

@item
If you use @kbd{C-x '} (@code{expand-abbrev}) without @kbd{M-'}
(@code{abbrev-prefix-mark}) and the last word before point starts
directly after a X-Symbol character, @kbd{C-x '} could behave strange:

@itemize @minus
@item
If @code{words-include-escapes} is @code{t}, there will be no expansion.

@item
If @code{words-include-escapes} is @code{nil}, the second ``internal''
character could be the first character of the last word before point
which is going to be replaced by the abbrev mechanism.
@end itemize

@item
If the character under point is a X-Symbol character, you will not see
the cursor if you exit a command with an error or with quit (@kbd{C-g}).
Unfortunately, XEmacs (as opposed to Emacs) does not run the hooks in
@code{post-command-hook} in these cases.  Solution: move point right
(@kbd{C-f}).

@item
If you provide prefix arguments to commands, they are likely to consider
just ``internal'' characters.  E.g., @kbd{C-u 2 C-f} before @code{alpha}
behaves like @kbd{C-f}.

@item
Column position considers ``internal'' characters, e.g., @kbd{C-n} might
jump to an unexpected position (well, typically just one character
left/right from the expected position, if at all).

@item
Auto-filling also considers ``internal'' characters, i.e., might break
the line too early.

@item
There are no syntax definitions for the new characters, e.g.,
@kbd{M-C-f} before @code{floorleft} does not move to the closing
@code{floorright}.

@item
In some cases, e.g., when using the minibuffer for input via @kbd{M-%}
or @kbd{C-s}, the internal representation of X-Symbol characters
(@pxref{Char Representation}) are displayed directly (@pxref{FAQ Strange
Chars})
@end itemize

@c ====================================================================

@node Spurious Encodings, No Encoding, Nomule Problems, Problems
@comment  node-name,  next,  previous,  up
@section Spurious Encodings
@cindex Spurious Encodings
@cindex Version Control Problems
@cindex @code{write-file} Problems
@cindex @code{vc} Problems
@cindex Revert Buffer Problems

@pindex vc
In rare cases, some commands (mostly from package @code{vc}) encode
characters to tokens or even turn off X-Symbol mode.  Package X-Symbol
will not provide a workaround for these problems, because the situations
in which they appear are too rare, the workarounds are easy, and the
problems are not really caused by package X-Symbol.

@itemize @bullet
@item
@pindex crypt
Doing the next logical version control operation (@kbd{C-x v v} and
friends) encode characters to tokens when using package @code{crypt}.

Solution: use package @code{jka-compr} instead @code{crypt} (this is
recommended anyway, @pxref{File IO Packages}).  Or kill the buffer and
revisit the file.

@item
@pindex auctex
When using Auc@TeX{} with its default-mode algorithm, getting rid of the
recently checked-in version of a file without reverting the buffer
afterwards (@kbd{C-u C-x v c}) turns off X-Symbol mode without encoding
the characters, e.g. under XEmacs/no-Mule, you see some strange
characters like @samp{\233a}.

Explanation: when using Auc@TeX{}'s @code{TeX-default-mode}, the final
@code{major-mode} is different from the initial @code{major-mode}
deduced using @code{auto-mode-alist}.  If this is the case, the VC
command executes @code{normal-mode} which kills all local-variables
including turning-off @code{x-symbol-mode}.

Solution: Turn on X-Symbol mode or change @code{auto-mode-alist} to
directly choose @code{latex-mode}:

@lisp
(push '("\\[tT]e[xX]\\'" . latex-mode) auto-mode-alist)
@end lisp

@item
@findex write-file
@vindex change-major-mode-with-file-name
When using Auc@TeX{} with its default-mode algorithm, writing a La@TeX{}
buffer into a file with another file name turns off X-Symbol mode.

Explanation: Emacs sets the major mode with the file name.  When using
Auc@TeX{}'s @code{TeX-default-mode}, we get the problems as described in
the previous item.

Solution: Set @code{change-major-mode-with-file-name} to @code{nil} or
use the solution from the previous item.
@end itemize

@c ====================================================================

@node No Encoding, FAQ, Spurious Encodings, Problems
@comment  node-name,  next,  previous,  up
@section The Encoding Does Not Work
@cindex No Encoding
@cindex @code{write-region} Problems

In a rare case, X-Symbol cannot do its encoding, i.e., convert the
characters to tokens.

@itemize @bullet
@item
@findex write-region
@pindex crypt
@vindex write-file-hooks
@kbd{M-x write-region} fails to do the encoding if you use package
@code{crypt}.

Explanation: with package @code{crypt}, the encoding has to be done by a
function in @code{write-file-hooks} which is not used by
@code{write-region}.

Solution: use package @code{jka-compr} instead @code{crypt} (this is
recommended anyway, @pxref{File IO Packages}).  Or visit the region file
and save it again via @kbd{C-x C-s}.
@end itemize


@c ===========================================================================

@node FAQ, Bug Reports, No Encoding, Problems
@comment  node-name,  next,  previous,  up
@section Frequently Asked Questions
@cindex Frequently Asked Questions
@cindex FAQ X-Symbol

It is assumed that you had successfully installed package X-Symbol, see
@ref{Checking Installation}.

@menu
* FAQ XEmacs Core::             XEmacs crashes when using input method Token
* FAQ font-lock::               X-Symbol's fontification does not work.
* FAQ Strange Chars::           The buffer contains strange characters
* FAQ No Subscripts::           I cannot see any/some super-/subscripts.
* FAQ Stupid Subscripts::       I see subscripts where I don't want them.
* FAQ Font Size::               The characters are too small or too big.
* FAQ Conversion::              The conversion changes some tokens.
* FAQ Additional Spaces::       A space is added during the encoding.
* FAQ 8bit Chars::              I do not want 8bit characters in the file.
* FAQ Hyphen::                  I cannot distinguish @code{hyphen} from @samp{-}.
* FAQ Spell Check::             I have problems with spell-checking.
* FAQ News and Mail::           I want to use X-Symbol in Gnus or @sc{vm}.
@end menu


@node FAQ XEmacs Core, FAQ font-lock, FAQ, FAQ
@comment  node-name,  next,  previous,  up
@subsection XEmacs Crashes when using Input Method Token
@cindex XEmacs Core
@cindex Core XEmacs
@cindex Crash XEmacs
@cindex Input Method Token

It has been reported that XEmacs-21.0 to XEmacs-21.1.8 might produce
cores when you use input method Token.  That's why I strongly recommend
to use XEmacs-21.1.9 or higher with package X-Symbol, see
@ref{Requirements}.

You get a warning during X-Symbol's initialization when using these
XEmacs versions.  If you don't want to upgrade, but also don't want to
see the warning, you might want to set variable
@code{x-symbol-xmas-warn-about-core} to @code{nil}.

A core in XEmacs always indicates a bug in XEmacs itself, not in a Lisp
package like X-Symbol.  Thus, send a bug report to the XEmacs team if
you get cores with the @emph{newest} version of XEmacs (please put me in
the CC).


@node FAQ font-lock, FAQ Strange Chars, FAQ XEmacs Core, FAQ
@comment  node-name,  next,  previous,  up
@subsection X-Symbol's Fontification does Not Work
@pindex font-lock
@cindex No fontification
@cindex @code{font-lock} Problems

In this case, super- and subscripts are not properly displayed
(@pxref{FAQ No Subscripts}) and under XEmacs/no-Mule, the buffer
contains s.th. like @samp{\233a} (@pxref{FAQ Strange Chars}).
Possible causes:

@itemize @bullet
@findex x-symbol-fontify
@item
You have turned off @code{font-lock} or @code{font-lock} is out of sync.
Use @kbd{M-x x-symbol-fontify}.  @xref{Role of font-lock}.

@item
The font-lock keywords of the current buffer are not prepared to display
X-Symbol characters.  @xref{Role of font-lock}.

@item
@vindex fast-lock-save-faces
You use package @code{fast-lock}.  Solution: set
@code{fast-lock-save-faces} to @code{nil} (done by default
installation).

@item
You use some version control commands.  You have probably noticed that
these versions control commands also turn off @code{font-lock} in modes
where you don't use X-Symbol, i.e., this is not a problem of package
X-Symbol.  @xref{Wishlist Emacs}.  @xref{Spurious Encodings}.
@end itemize


@node FAQ Strange Chars, FAQ No Subscripts, FAQ font-lock, FAQ
@comment  node-name,  next,  previous,  up
@subsection The Buffer Contains Strange Characters
@cindex Strange Characters
@cindex Funny Characters
@cindex Character Problems
@cindex Escape Character Problems
@pindex Mathematica

If you see s.th. like @samp{\233a}, you see the internal representation
of X-Symbol characters under XEmacs/no-Mule (@pxref{Char
Representation}) directly.  Possible causes:

@itemize @bullet
@item
You have @code{font-lock} problems, see @ref{FAQ font-lock}.

@item
More complicated editing commands like @kbd{C-t} may produce strange
character sequences which do not represent X-Symbol characters, see
@ref{Nomule Problems}.

@item
In some cases, e.g., when using the minibuffer for input via @kbd{M-%}
or @kbd{C-s}, it would be too much work to fontify these character
sequences in order to display proper X-Symbol characters.  @xref{Nomule
Problems}.
@end itemize

If Emacs shows some strange glyphs for some characters in your buffers
but not the Grid, there is a font in you font path which pretends to
have charset registry-encoding @code{adobe-fontspecific}, but in fact
uses another encoding.  E.g., Mathematica's fonts cause the characters
intersection and union to mix up.  Possible solutions:

@itemize @bullet
@item
Delete that font from the font path.  Maybe moving it at the end also
works.

@item
In Emacs-21, you have the chance to disable the use of some fonts (if
you know something similar for XEmacs, please let me know).  For
example, to disable the fonts from Mathematica, use

@lisp
(setq face-ignored-fonts '("\\`-wri-math1"))
@end lisp

@item
If the characters show up correctly initially, but mix up after some
font changing command, don't use that command.  E.g., the font selection
in XEmacs via the Options menu seems to loose some information about the
original font.  OK, this is not really a satisfying solution, but the
whole issue isn't my fault, either.
@end itemize


@node FAQ No Subscripts, FAQ Stupid Subscripts, FAQ Strange Chars, FAQ
@comment  node-name,  next,  previous,  up
@subsection I Cannot See any/some Super- or Subscripts
@cindex No Subscripts
@cindex Subscript Problems
@cindex Superscript Problems

If you cannot select @samp{Super-/Subscripts} in the menu, the first of
the following points is more likely the cause, the others otherwise.

@itemize @bullet
@item
You have @code{font-lock} problems, see @ref{FAQ font-lock}.

@item
There are cases where super- and subscripts are not displayed, see
@ref{Super and Subscripts}.

@item
The argument in braces are not correctly recognized, since the
@code{font-lock} syntax-table is not correct.  It should include
@samp{@{} as the only open parenthesis and @samp{@}} as the only close
parenthesis character.  Note that this is quite difficult to archive
under Emacs and XEmacs/Mule.  This is a minor bug in the corresponding
@code{font-lock} package, but would require other changes there,
therefore not likely to be fixed.  Fortunately, this does not happen
often.
@end itemize


@node FAQ Stupid Subscripts, FAQ Font Size, FAQ No Subscripts, FAQ
@comment  node-name,  next,  previous,  up
@subsection I See Super- and Subscripts where I Don't Want Them.
@pindex font-lock
@pindex font-latex
@cindex Stupid Subscripts
@cindex Annoying Subscripts
@cindex Label Subscripts
@cindex Subscript Problems
@cindex Superscript Problems

E.g., I see a subscript in arguments of @code{\label}.  Package X-Symbol
only uses super- and subscripts if they are in braces, if the
@code{asciicircum}/@code{underscore} has not been fontified yet or is
only fontified with faces which are allowed by
@code{x-symbol-tex-font-lock-allowed-faces}, see @ref{Super and
Subscripts}.

@itemize @bullet
@item
You use the default @code{tex-font-lock-keywords}: The argument of
@code{\include} and friends are not fontified by these, i.e., the use of super-
and subscripts are not prohibited.  Solution: add your own keyword for
these commands or use package @code{font-latex}, see below.

@item
You use package @code{font-latex}.  Solution: set
@code{font-lock-maximum-decoration} to value @code{t}, 2 or higher.
Package X-Symbol will still use subscripts in @code{\verb}, in the
@code{verbatim} environment, in the argument of @code{\includegraphics}
and probably other commands.  Some of these problems will probably be
solved by future versions of @code{font-latex}.

@item
You use my font-lock keywords (file @file{x-font-lock.el}): everything
should work fine.  Please note that this file is not meant to be a
replacement of @file{font-latex.el} useful to all users.  Also,
highlighting is a matter of taste, i.e., I am not going to change the
@file{x-font-lock.el} to support La@TeX{}-2.09, @TeX{}'s math regions,
other likings, etc.

@item
You use your own font-lock keywords for @TeX{}.  In this case, you be able
to adapt the solutions from the previous points to your situation.
@end itemize


@node FAQ Font Size, FAQ Conversion, FAQ Stupid Subscripts, FAQ
@comment  node-name,  next,  previous,  up
@subsection The Characters are Too Small or Too Big
@cindex Font Size
@cindex Big Characters
@cindex Small Characters

Why aren't there more different font sizes?  Because nobody (including
the author) was in the mood to design them (actually only the xsymb1
font needs to be designed).  @emph{Please do only ask the author whether they
are in work if you are serious to do it yourself otherwise!}

Why do I get a lower-case letter when I should get a capital letter (or
vice versa)?  Please convince yourself (@pxref{Info}) that you actually
get the correct letter---they are just of different sizes.
@xref{Installing Fonts Lisp}.

I was told that the xsymb1 font scales reasonably well to a larger font
size---if you don't think so, design a new font and send me the result.


@node FAQ Conversion, FAQ Additional Spaces, FAQ Font Size, FAQ
@comment  node-name,  next,  previous,  up
@subsection The Conversion Changes Some Tokens
@cindex Token Changes
@cindex Conversion Problems
@cindex Encoding Problems

In most token languages, a character might be represented by different
tokens.  If this character is encoded (when saving the buffer), the
canonical representation is saved.  @xref{Unique Decoding}.

@itemize @bullet
@item
Solution: Do not redefine standard @TeX{} macros or use unique
decoding.  @xref{TeX Macro Problems}.
@end itemize


@node FAQ Additional Spaces, FAQ 8bit Chars, FAQ Conversion, FAQ
@comment  node-name,  next,  previous,  up
@subsection A Space is Added During the Encoding
@cindex Additional Spaces
@cindex Token Problems
@cindex Encoding Problems
@cindex Space Problems

A space is added after some characters during the encoding to tokens.
With token languages @code{tex} and @code{utex} (not with language
@code{sgml}), there must be a space after the token to recognize its end
in some cases.

E.g., if your buffer contains @samp{a+b} (where + stands for the
character @code{circleplus}), this is encoded to @samp{a\oplus b} (note
the space after @code{\oplus}).  Decoding it yields @samp{a+ b}.

I admit, this looks ugly.  The space is only added if the symbol
character is followed by a letter or by @samp{@@}.  Thus, decoding
@samp{a\oplus\beta} yields @samp{a+b} (without space!).

@itemize @bullet
@item
Suggestion: Also use a space before @code{\oplus}.  The alternative
would be to delete the space which other people won't like.
@end itemize

For an exact description, @xref{TeX Macro Conversion} for an exact description.


@node FAQ 8bit Chars, FAQ Hyphen, FAQ Additional Spaces, FAQ
@comment  node-name,  next,  previous,  up
@subsection I Don't Want 8bit Characters in the File
@cindex 8bit Character Problems
@cindex No 8bit Characters

By default, these are not encoded if the buffer-local variable
@code{x-symbol-8bits} is non-@code{nil}.

By default, this variable is only set to non-@code{nil}, if something like

@example
\usepackage[latin1]@{inputenc@}
@end example

is found at the beginning of the file.  That line does not make sense if
you do not have 8bit characters in the file, i.e., delete it.
@xref{File Coding}.  Note: commenting the line is not enough!  (I do not
run La@TeX{} to check for the line, I just do plain text search.)


@node FAQ Hyphen, FAQ Spell Check, FAQ 8bit Chars, FAQ
@comment  node-name,  next,  previous,  up
@subsection I Cannot Distinguish Character @code{hyphen} from @samp{-}
@cindex Hyphen Versus Minus
@cindex Minus Versus Hyphen

In most fonts, the Latin character @code{hyphen} cannot be distinguish
from the Ascii character @samp{-}.  If you do not want to decode the
corresponding token @code{\-} or @code{&shy;}, put the following into
your @file{~/.emacs}:

@lisp
(setq x-symbol-tex-user-table '((hyphen)))
(setq x-symbol-sgml-user-table '((hyphen)))
@end lisp

A better alternative would be to make @code{font-lock} display these
character in a different color.


@node FAQ Spell Check, FAQ News and Mail, FAQ Hyphen, FAQ
@comment  node-name,  next,  previous,  up
@subsection Problems with Spell-checking
@cindex Spell Checking
@pindex ispell
@findex ispell-word
@findex ispell-region

As explained in @ref{Miscellaneous Packages}, @code{ispell} assumes the
buffer contents to be the same as the file contents and does not provide
any hook to fix this.  This might break @code{ispell-word} and
@code{ispell-region}.  Possible symptoms:

@itemize @bullet
@item
A word which contains letters which the program @code{ispell} does not
know about is either not spell-checked or parts of it are spell-checked
as independent words.

Solution: Use the @code{ispell}s 8bit dictionaries even if you do not
store 8bit characters in the file.  This should fix the problem for
almost every word, except, e.g., words containing the Latin-9 character
@code{oe} if you use a Latin-1 encoding.

@item
Spell-checking might stop with the error message @samp{Ispell
misalignment}.  I can reproduce this only with Emacs, not with XEmacs.

Question: If you know some settings (like for
@code{process-coding-system-alist}) which solves this problem, please
let me know!

Solution: turn X-Symbol off before spell-checking your buffer.  This is
of course no option if you use @code{flyspell}.
@end itemize

The real solution would be to fix @code{ispell}, at least by providing a
useful hook which allows X-Symbol to fix the problem.  @xref{Wishlist
Emacs}.  You are strongly encouraged to send a patch to the maintainer
of @code{ispell}, you even get a paragraph here in
@ref{Acknowledgments}!


@node FAQ News and Mail,  , FAQ Spell Check, FAQ
@comment  node-name,  next,  previous,  up
@subsection How to Use X-Symbol with Gnus or @sc{vm}
@cindex News Reader
@cindex Mail Reader
@pindex Gnus
@pindex VM
@pindex Message

You can also use X-Symbol to read and write your News and Mails.  This
sections includes coding for your @file{~/.emacs} if you want to do so.
It has been tested for Gnus-5.8.8 and @sc{vm}-6.96; if you use
@sc{rmail} or @sc{mh-e}, you have to try to find a solution yourself
(please send it to me).  Support for Gnus might become a standard
part of X-Symbol.

@lisp
(custom-set-variables
 '(x-symbol-auto-style-alist
   '(((mail-mode message-mode gnus-article-mode vm-presentation-mode)
      tex nil nil nil nil t nil))))
@end lisp

This is optional (you might want to use the Custom interface for the
same effect) and tells Emacs/X-Symbol to use token language @code{tex}
and to display super-/subscripts (if @code{font-lock} is enabled),
X-Symbol is not automatically turned on.  @xref{Minor Mode}.

@findex mail
@findex message-mail
@findex vm-mail
@vindex mail-send-hook
@vindex message-send-hook
@vindex vm-mail-send-hook
@lisp
(defun x-symbol-x-mail-send-hook ()
  (if x-symbol-mode (x-symbol-mode 0)))
(add-hook 'mail-send-hook 'x-symbol-x-mail-send-hook)
(add-hook 'message-send-hook 'x-symbol-x-mail-send-hook)
(add-hook 'vm-mail-send-hook 'x-symbol-x-mail-send-hook)
@end lisp

This tells tells Emacs to automatically turn off X-Symbol (which
includes encoding characters to token) before actually sending the
message.

@findex gnus
@vindex gnus-article-prepare-hook
@lisp
(defun x-symbol-x-gnus-prepare ()
  (when x-symbol-mode
    (setq x-symbol-mode nil)
    (x-symbol-mode-internal nil)))
(add-hook 'gnus-article-prepare-hook 'x-symbol-x-gnus-prepare)
@end lisp

Since Gnus reuses the @file{*Article*} buffer, where X-Symbol could
have been turned on previously, we must make sure that X-Symbol is
turned off with the new article.

@findex vm
@vindex vm-select-message-hook
@lisp
(defun x-symbol-x-vm-prepare ()
  (and (boundp 'vm-presentation-buffer)
       (buffer-live-p vm-presentation-buffer)
       (save-excursion
         (set-buffer vm-presentation-buffer)
         (when x-symbol-mode
           (setq x-symbol-mode nil)
           (x-symbol-mode-internal nil)))))
(add-hook 'vm-select-message-hook 'x-symbol-x-gnus-prepare)
@end lisp

The same thing for @sc{vm}, although the hook is not as nice as
Gnus' one; the function therefore might depend a bit too much on
@sc{vm}'s interna.

@findex vm-mode
@findex vm-presentation-mode
@lisp
(put 'vm-mode 'x-symbol-mode-disable
     "Use VM Presentation Mode to turn on X-Symbol")
(custom-set-variables '(vm-fill-paragraphs-containing-long-lines 80))
@end lisp

You cannot use X-Symbol in @sc{vm} Mode, only in @sc{vm} Presentation Mode
(X-Symbol would change your @file{INBOX}).  The first (optional) Emacs
Lisp expression gives you a better error message when you try to turn on
X-Symbol Mode in @sc{vm} Mode.  The second line makes sure that @sc{vm}
always uses @sc{vm} Presentation Mode to display the articles.

@c ===========================================================================

@node Bug Reports,  , FAQ, Problems
@comment  node-name,  next,  previous,  up
@section How to Send a Bug/Problem Report
@cindex Bug Reports
@cindex Problem Reports
@cindex Contacting the Maintainer
@cindex Maintainer Address
@cindex Email to the Maintainer
@cindex Reports of Bugs

Bug fixes, bug/problem reports, improvements, and suggestions are
strongly appreciated.  So are corrections to this manual (better
explanations, correcting my English, @dots{}).  Especially useful would be
some feedback by people using default fonts with a charset
registry-encoding other than @code{iso8859-1} (Western encoding).

Please read this section carefully, even if you generally know how to
send a bug report (@pxref{Bugs,,,@value{emacs},@value{emacsman}}).
This might look tedious to you, but it actually saves a lot of time
(your time, too).

The @strong{general recommendation} for bug/problem reports is: give the
impression that your really have tried to find the necessary information
yourself and make your report precise while including all information
you have.

For each bug/problem report or question you want to send to the
maintainer, please use the following sequence:

@enumerate
@item
Make sure that you use the @strong{newest version} of X-Symbol.  You are
reading Edition @value{edition} (@value{subedition}) of the manual for
X-Symbol @value{version}.

@item
Read the manual, especially @ref{Checking Installation}, @ref{Problems},
and @ref{FAQ}.  The four indexes (@pxref{Indexes}) might also lead you
to an answer to your question.

@item
Use @kbd{M-x x-symbol-package-bug} (also to be found in X-Symbol's
Command submenu) to write your report describing @emph{one} bug or
problem, i.e., use @strong{different mails} for @strong{unrelated
problems}.  Please do not ``reuse'' a mail thread with the maintainer,
i.e., if you start a section with ``Here is another problem'', you do
something wrong.

If Emacs is not your mail tool, copy the Subject header line and the
message body from Emacs' @file{*mail*} buffer to your mail tool.

If @kbd{M-x x-symbol-package-bug} fails to work, you have a problem with
your installation and your report should be about this problem.  In this
case, use @samp{x-symbol @var{version}; @var{summary}} as Subject header
where @var{version} is the version of X-Symbol (it should be
@value{version}) and @var{summary} is a brief summary of your
installation problem.

(@emph{Rationale}: This command automatically extracts some essential
information without any work by you.  Don't waste your time pondering whether
you should really use this command to write your report.)
@c The additional advantage is that I can see who doesn't have any problems
@c wasting my time.

@item
Start your report with:

@quotation
In the manual, I checked the sections @var{section1}, @var{section2},
@dots{}, but didn't find anything which helped me with the following
problem:
@end quotation

The sections @var{section1}, @var{section2}, etc are names of the
sections (not whole chapters) in the manual where you would expect an
answer to your question/problem/bug.

If you didn't know which sections to inspect, please check the indexes.
If they are not helpful, send me words/terms which should be included in
the indexes.

(@emph{Rationale}: This way, I get an idea where to improve the manual,
especially by adding cross references.)
@c It also ensures that you really have tried to find the relevant
@c information yourself.

@item
If buffer @file{*Warnings*} does not exist in the buffer menu,
everything is fine so far.  So is (for me as the author of package
X-Symbol), if @samp{X-Symbol} is not mentioned there.  Otherwise,
include the contents of buffer @file{*Warnings*} into your bug report.

@c TODO: without warnings.el from Emacs-21.4
Temporary Emacs (< v21.4) note: the warnings might be somewhere hidden
in buffer @file{*Messages*}; please check that buffer.

@item
Put the parts of the code from @file{~/.emacs} and the system-wide files
which causes the problem into a fresh file @file{@var{my-problem}.el}.
The problem/error should be visible when invoking

@example
xemacs -no-site-file -q -l @var{my-problem}.el
@end example

In the minimal case, @file{@var{my-problem.el}} just contains the
following line (@pxref{Installing Lisp}):

@lisp
(x-symbol-initialize)
@end lisp

If the error has disappeared after you have included your complete
@file{~/.xemacs/init.el} and @file{~/.emacs}, the problem is likely
caused by some code of your system-wide installation.  Include the code,
which can be found using command @kbd{M-x find-library} with files
@file{site-start} and @file{default} (everything is fine if these files
do not exist).

If you use @file{x-symbol-site.el} (its use is deprecated), copy its
contents into @file{@var{my-problem.el}} and delete the corresponding
@code{load} command.

Attach the file @file{@var{my-problem}.el} to your report.
@strong{Please try to minimize the size of @file{@var{my-problem}.el}}!
A standard technique is recursive halving: Delete the second half of
@file{@var{my-problem.el}}.  If the problem disappears, delete the first
half instead.  Do the same with the smaller file again, @dots{}.

(@emph{Rationale}: Most problems are a consequence of some specific
customizations, but I don't have time to debug each user's init file.)

@item
If you have set variable @code{custom-file} in
@file{@var{my-problem}.el}, attach the corresponding file to your report.

@item
If the error can only be reproduced in combination with another Emacs
package, please send me:

@itemize @minus
@item
If it is included in the standard Emacs/XEmacs distribution / if is an
XEmacs package: the version you use if it is not that from the
Emacs/XEmacs distribution (use @kbd{M-x find-library} to check whether
you really use the version from the Emacs/XEmacs distribution).

@item
If it is a non-standard (and non-obscure) package: the URL of the
distribution and/or the source.

@item
Otherwise: include its code into @file{@var{my-problem}.el} and delete
the corresponding @code{load} or @code{require} command.  Then, reduce
the size of @file{@var{my-problem}.el} as described above.
@end itemize

@item
If the problem is not reproducible with an @emph{arbitrary}
(@file{.tex}, @file{.html}, @dots{}) file, include the file with its full file
name into your bug report.  (If you like, you can try to minimize the
file if the problem is still reproducible.)

(@emph{Rationale}: Most problems are only reproducible with specific
files.)

@ignore
@item
I would appreciate, if you would set variable @code{debug-on-error} to
@code{t} before you trigger the error and send me the contents of buffer
@file{*Backtrace*}.  At best, using the uncompiled versions of the
functions involved, i.e., by jumping to its definition and evaluation it:

@example
M-x find-function @key{RET} @var{function} @key{RET} C-M-f C-x C-e
@end example
@end ignore

@item
Finally, include the exact key sequence which causes the problem into
your bug report.  You should also tell me the name of the buffer in
which the problem occurred and how you have created that buffer (e.g.,
by @kbd{C-x C-f @var{file} @key{RET}}).

At best, you start your Emacs, and then try to reproduce the problem as
fast as possible (i.e., with a minimum number of key/mouse strokes).

As soon as the problem appears, press @kbd{C-h l} and include the
contents of buffer @file{*Help*} in your bug report.

(@emph{Rationale}: Most problems are only reproducible with point being
at a specific position in the file, with specific key sequences, etc.)

@item
If you have problem with the display of images, please include the
output of the shell commands @samp{convert -h} and @samp{convert -list
Format} in your bug report.  If the first command fails, you have a
problem with the program @code{convert}, not X-Symbol.

@item
If necessary, include a screen-shot in your bug report.

@item
If you could not use @kbd{M-x x-symbol-package-bug}, include the
contents of buffer @file{*Help*} after the following actions:

@itemize @minus
@item
Type @kbd{C-h v x-symbol-version @key{RET}}.
@item
Type @kbd{C-h v emacs-version @key{RET}}.
@item
Type @kbd{C-h v features @key{RET}}.
@end itemize

@end enumerate

If you have solved your problem during this sequence, but you think your
situation is worth to be mention in this manual (e.g., in @ref{Package
Integration}), I would appreciate if you would send me a some new text
for this manual or a normal bug report together with your solution.

@c ===========================================================================

@node History, Indexes, Problems, Top
@comment  node-name,  next,  previous,  up
@chapter History and Projects

@menu
* News::                        Changes in recent versions.
* Wishlist::                    Projects for X-Symbol.
* Open Questions::              How you can contribute.
* Acknowledgments::             People having contributed.
@end menu

@c ===========================================================================

@node News, Wishlist, History, History
@comment  node-name,  next,  previous,  up
@section News: Changes in Recent Versions of X-Symbol
@cindex New Features
@cindex Changes
@cindex History

This is the complete history of X-Symbol.  It just lists the major
changes before Version 3.0.

@menu
* Changes New::                 To be announced.
* Changes 4.5::                 Released Mar 2003 as beta.
* Changes 4.4::                 Released June 2002 as beta.
* Changes 4.1::                 Released Mar 2002 as beta.
* Changes 3.4::                 Released Mar 2002.
* Changes 3.3::                 Released Jan 1999.
* Changes 3.2::                 Released Dec 1998.
* Changes 3.1::                 Released Oct 1998.
* Changes 3.0::                 Released Sep 1998 as beta.
* Changes Old::                 Overview of old releases.
@end menu



@node Changes New, Changes 4.5, News, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol @value{version}

Version @value{version} has not yet been announced.

@itemize @bullet
@item
Various bug fixes and minor changes.
@end itemize


@node Changes 4.5, Changes 4.4, Changes New, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 4.5

Version 4.5 has been released on March 2003 as beta.

@itemize @bullet
@item
X-Symbol finally respects the Mule coding system of each individual buffer.

@item
Bug fix: would mess up encoding of math-mode characters with token
language @code{bib}.  Other conversion fixes for languages @code{bib}
and @code{texi}.

@item
Bug fix (workaround for bug in XEmacs): auto-save files would have
length 0.

@item
Bug fix (Emacs): package now works with package
@code{crypt}/@code{crypt++}.

@item
Token language @code{sgml}: always encode characters to entity
references by default (where defined by the HTML standard).  Include
@code{hm--html-mode}, @code{html-helper-mode}, remove @code{sgml-mode}
as typical major modes which use X-Symbol.

@item
Token language @code{tex}: support some symbols of package
@file{stmaryrd.sty}.

@item
Change the auto-style, formerly auto-mode, mechanism.

@item
Image support when running on Emacs.

@item
New input method Quail, a usual Mule input method.

@item
Corrected Latin-5 definitions.  Support Latin-5 (``Turkish'') on XEmacs
running under Windows.

@item
X-Symbol works with Emacs/XEmacs running under a character terminal.

@item
Improments for external languages.  Super-/subscript matching of token
languages has changed.

@item
X-Symbol can use package @code{format} and does not require special
fonts for super-/subscripts with Emacs-21.4+.  Still open whether this
will be used@dots{}.

@item
Dropped support for XEmacs-20.3.

@item
Various bug fixes and minor changes.
@end itemize


@node Changes 4.4, Changes 4.1, Changes 4.5, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 4.2 to 4.4

Version 4.4 has been released on June 2002 as beta.

@itemize @bullet
@item
Token language TeX has changed: no excessive use of braces anymore, no
excessive normalization, and aware of environments @code{@{tabbing@}} and
@code{@{verbatim@}}, and macro @code{\verb}.  Reading and saving
``old-encoded'' files works without changes in the file (the buffer
looks different), there is also a command to remove the unwanted braces
around accented letters.

@item
New token language ``Bib@TeX{} Macro'' (@code{bib}, similar to old
@code{tex}), used for Bib@TeX{} files.

@item
Nuked executables, the Lisp conversion for all languages is now 2-5
times faster.

@item
Latin-9 support.  Latin-9 font included in distribution.

@item
Works with XEmacs-21.4+ on Windows.  Of course, it just supports a
limited number of characters and no super- and subscripts there due to
missing fonts.

@item
More likely to save 8bit characters in the file by default: also look
for 8bit characters in the file when visiting the file, also inspect
master file (@code{TeX-master}) with token language @code{tex}.

@item
New buffer-local variable @code{x-symbol-unique}: when non-@code{nil},
decodes much less tokens to avoid near to all normalizations, used for
@TeX{}'s style files (but X-Symbol is not automatically turned on).
Dropped token language @code{utex}.

@item
Menu changes, new commands: submenu ``Conversion'', menu items ``Copy
Encoded'', ``Paste Decoded'' and others.

@item
Special coding for @code{preview-latex}.  Using X-Symbol now only gives
a 10% overhead of @code{preview}s parsing time.

@item
X-Symbol now works with Whizzy@TeX{}.

@item
The interface for defining a token language has changed, it is also much
more general, useful for ProofGeneral.

@item
Changed final bytes of ISO 2022 escape sequence for X-Symbol charsets
since Emacs reserves the characters @samp{0-9} for itself.  Does XEmacs
has any policy here (it also uses @samp{?})?

@item
Dropped workaround for minor bug in XEmacs-20.X.

@item
Various bug fixes and minor changes.
@end itemize


@node Changes 4.1, Changes 3.4, Changes 4.4, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 4.1

Version 4.1 has been released on Mar 2002 as beta.

@itemize @bullet
@item
X-Symbol works with Emacs-21.1 or higher.  Porting is not complete, yet.

@item
New token language ``@TeX{}info command'' (@code{texi}).

@item
Slightly different definition of ``valid character''.

@item
Remove the ``local if set'' and ``default: @dots{}'' submenu stuff.
@end itemize


@node Changes 3.4, Changes 3.3, Changes 4.1, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 3.4

Version 3.4 has been released on Mar 2002.

@itemize @bullet
@item
Moved to SourceForge.net.  Added files for nicer HTML output of manual.

@item
Would sometimes perform strange conversions when
@code{global-flyspell-mode} is enabled.

@item
Bug fixes: command @kbd{M-x write-region} would always save the whole
buffer if X-Symbol is enabled for that buffer, writing a remote file via
ange-ftp would not work (was OK with efs).

@item
Automatically deduce default coding via @code{locale -ck LC_CTYPE}.

@item
Issue warning when running on XEmacs-21.0 to XEmacs-21.1.8.  Update
manual: XEmacs user package directory is @file{~/.xemacs/packages}.

@item
Directories ending with @file{//} in image search paths are recursive.

@item
New characters used for token languages ``@TeX{} macro'' and ``Isabelle
symbol''.

@item
Make sure to convert just the first part of a multi-part image.

@item
Source distribution includes files for building an RPM package, all
files also compile without Mule support.

@item
Minor changes.  Manual changes.
@end itemize


@node Changes 3.3, Changes 3.2, Changes 3.4, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 3.3

Version 3.3 has been released on Jan 1999.

@itemize @bullet
@item
Package X-Symbol is really a proper XEmacs package: no need to create
fonts and to set the font path.  With XEmacs/no-Mule, I still recommend
to create the executables (type @kbd{M-x x-symbol-exec-create}).

@item
New functions used for interaction with Emacs package @code{comint}.
This is necessary for new token language ``Isabelle symbol'', to be
distributed with Emacs package ProofGeneral.

@item
New characters used for token languages ``@TeX{} macro'' and ``Isabelle
symbol''.

@item
Minor changes.  Manual changes.
@end itemize


@node Changes 3.2, Changes 3.1, Changes 3.3, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 3.2

Version 3.2 has been released on Dec 1998.

@itemize @bullet
@item
Package X-Symbol is a proper XEmacs package.  The installation process
is much easier (using the binary package).  It has changed, though!
The use of file @file{x-symbol-site.el} is deprecated.

@item
Reverting the buffer and using @code{vc} commands do not encode
characters when not using @code{crypt}.  (This did not work always.)

@item
Workaround for bug (segfault) in XEmacs-21/Mule betas.

@item
Command @code{x-symbol-package-bug} is less restrictive.  Please use
this command to contact the maintainer.

@item
Bug fixes.  Minor changes.  Manual changes.
@end itemize


@node Changes 3.1, Changes 3.0, Changes 3.2, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 3.1

Version 3.1 has been released on Oct 1998.

@itemize @bullet
@item
@TeX{} macro @code{\mu} is represented by a character in the Adobe Symbol
font, not in a Latin-@{1,3,5@} font anymore.

@item
Support for most @sc{sgml} entities in HTML-4.0 specification.

@item
Additional characters for @code{\therefore}/@code{&there4;},
@code{&oline;} and @code{&euro;}.

@item
Package X-Symbol has been customized.

@item
The documentation has been completed (as @TeX{}info file).

@item
Handle special URL prefixes @file{file:}, @file{http:} for images.

@item
Bug fixes, configuration changes.
@end itemize


@node Changes 3.0, Changes Old, Changes 3.1, News
@comment  node-name,  next,  previous,  up
@subsection Changes in X-Symbol 3.0

Version 3.0 has been released on Sep 1998 as beta.

@itemize @bullet
@item
Package X-Symbol now works on XEmacs with and without Mule support.
Dropped support for XEmacs 19.13 to 19.16/20.2.

@item
Full support of token language @code{sgml} (executables, subscripts, images).

@item
X-Symbol is a proper minor mode.

@item
Easier (automatic) 8bit character control (e.g., for @code{\times}
@code{\pm},@dots{}).  By default, the encoding when saving only writes
8bit characters, if @samp{\usepackage[latin@var{n}]@{inputenc@}} with
@var{n}=1,2,3,5 was found in the first 10000 characters of the file
(including commentary).

@item
Package X-Symbol can be easily extended with new token languages and
fonts due to its modular design.  It consistently handles situations
where an entry for an additional character defines the same preferred
key binding (and context) as for a previously defined character

@item
Key bindings have completely changed.  They are now consistent with the
contexts of input method Context (which have changed a bit).

@item
The keys @kbd{@@} and @kbd{!} are not used anymore as Modify- and
Rotate-Key.  The Rotate key (instead of the Modify-Key) is used to
``Greek''ify the previous Ascii char.

@item
Input method Aggressive Context is now called input method Electric and
is much more restrictive (using package @code{texmathp} with language
``@TeX{} macro'').

@item
Easier installation despite many additional features.

@item
Supports more characters.

@item
Nicer grid, info in echo area.

@item
Better cooperation with packages: @code{vc} (check-out does not convert
characters), @code{reftex} (no strange characters @samp{\237}, help with
label creation), @code{auctex}, @code{ispell}, @code{font-latex} (no
annoyances with @code{\exists}).

@item
Safer use of executables.

@item
The code has completely changed.  You have to redo your installation.
@end itemize


@node Changes Old,  , Changes 3.0, News
@comment  node-name,  next,  previous,  up
@subsection Changes in Old Releases.

This sections gives just an overview of the major changes in the releases.

Version 2.6 has been released on Oct 1998.

@itemize @bullet
@item
Fixed serious bug when used under tty.
@end itemize

Version 2.5 has been released on Mar 1998.

@itemize @bullet
@item
Image support.
@end itemize

Version 2.4 has been released on  Mar 1997.

@itemize @bullet
@item
Token language @code{sgml}.  (X-Symbol can handle more then token
language @code{tex}.)

@item
Input method Aggressive Context (precursor of input method Electric),
input method Context has been much improved.

@item
Fixed performance bug when saving a file with package @code{crypt}.

@item
Control of Conversion and 8bit character has changed.
@end itemize

Version 2.3 has been released on Sep 1996.

@itemize @bullet
@item
Distributed with own font for more math characters.

@item
Info for the character around point in echo area.
@end itemize

Version 2.2 has been released on June 1996.

@itemize @bullet
@item
Input method Grid.  Help when using input method Keyboard.

@item
Control of Conversion and 8bit character has changed.
@end itemize

Version 2.1 has been released on April 1996.

@itemize @bullet
@item
Fixed serious performance bug when loading files with
font-lock/lazy-lock.  Use executables for conversion of large buffers.

@item
The package @code{iso-cvt} is not integrated anymore.  Now this package
can also convert to/from Latin-1 characters, it is much faster.

@item
Menu support, including input method Menu.

@item
@code{isearch} works with X-Symbol characters.

@item
First multi-file version.
@end itemize

Version 1.4 has been released on Feb 1996.

@itemize @bullet
@item
Provide some kind of ``poor man's Mule'' to remove most Nomule-Problems.
@end itemize

Version 1.3 has been released on Jan 1996.

@itemize @bullet
@item
Input method Abbrev (precursor of input method Token).

@item
Super-/subscript support.
@end itemize

Version 1.2 has been released on Jan 1996.  It was the first release.

@itemize @bullet
@item
Conversion between characters and @TeX{} tokens.  Do so automatically
when visiting a file and saving the buffer.

@item
Input method Keyboard.
@end itemize

@c ====================================================================

@node Wishlist, Open Questions, News, History
@comment  node-name,  next,  previous,  up
@section Wishlist: Projects for X-Symbol
@cindex Wishlist
@cindex Project
@cindex Future Features
@cindex Contributions
@cindex Your Contribution

You are encouraged to try to provide a solution to one of the problems
of this section.  In fact, it is quite unlikely that I do it myself
without any contributions from you, see also @ref{Open Questions}.

Providing a solution to these problems is the second way of making your
name appear in @ref{Acknowledgments}.

@menu
* Wishlist Languages::          Additional token languages.
* Wishlist Fonts::              Automatically generated fonts.
* Wishlist Emacs::              Changes in Emacs/XEmacs.
* Wishlist LaTeX::              Changes in La@TeX{}.
* Wishlist Various::            Other changes.
* Wishlist Rejected::           Rejected Suggestions for X-Symbol.
@end menu



@node Wishlist Languages, Wishlist Fonts, Wishlist, Wishlist
@comment  node-name,  next,  previous,  up
@subsection Wishlist: Additional Token Languages
@cindex More Token Languages
@cindex Language Additions
@cindex Ams@TeX{}
@cindex IPA Fonts

Making a contribution here would require just a basic knowledge of Emacs
and X-Symbol.  In fact, I would do the non-trivial part of the Emacs Lisp
part (@pxref{Extending X-Symbol}) for general-interest token languages
(e.g., Ams@TeX{}).

It is likely that this would require additional fonts: available fonts
(e.g., IPA font), hand-crafted, or generated (@pxref{Wishlist
Fonts}).


@node Wishlist Fonts, Wishlist Emacs, Wishlist Languages, Wishlist
@comment  node-name,  next,  previous,  up
@subsection Wishlist: Generated Fonts
@cindex Generated Fonts
@cindex Fonts from Other Sources
@cindex Fonts for Windows
@cindex MS-Windows Fonts
@cindex Windows Fonts

@pindex bdftofon
A specific direction of font generation would be from @file{.bdf} or
@file{.pcf} font files to Windows fonts to get rid of the limited
support for XEmacs on Windows (@pxref{Requirements}).  If you have
successfully converted X-Symbol's fonts from the Unix format to the
Windows format (via @code{bdftofon} or whatever) or if you have free and
real Latin-N fonts for Windows, please @emph{let me know}!  I would also
appreciate if you would actively try to get those missing Windows fonts.

The general direction is to automatically generate the @file{.bdf} or
@file{.fon} fonts from other sources.  This would have various
advantages:

@itemize @bullet
@item
We could easily create different sizes for our symbol font.

@item
It would be quite simple to create a font for Ams@TeX{} macros, etc.,
which would be displayed as X-Symbol characters by package X-Symbol.

@item
We could easily create different sizes for our symbol font.

@item
We would have fonts for both X11 and Windows.
@end itemize

New fonts for X-Symbol are being worked on.  You can find material to
generate them at the @uref{@value{url}/news.html,web pages of X-Symbol}.
Quite a few problems needs to be fixed though, so it is considered as
experimental.  You are welcome to try, fix and report on the
@uref{mailto:@value{listdevel},X-Symbol development mailing list}.

General open design issues (i.e., they could be re-thought for the
currently used handcrafted fonts, too) are:

@itemize @bullet
@item
Different @TeX{} macros (same appearance, different @TeX{} class =
different spacing) use the same MetaFont character, e.g., @code{\dagger}
and @code{\dag}.  Therefore, we need different X11 characters for them.

@item
Some Ascii characters have a special meaning in @TeX{}.  The
corresponding MetaFont character is therefore produced by a TeX macro,
e.g., @samp{@{} by @code{\@{}.
@c @}@}
We need a X11 character which looks similar to the character but not
exactly like it.
@end itemize

We could ask the question whether we should really distinguish the
characters by appearance@dots{}we have the minibuffer info for the X-Symbol
character anyway@dots{}.  Here are the options:

@itemize @minus
@item
distinguished by size/underlining/miscellaneous (currently used),
@item
distinguished by different spacing (my current favorite),
@item
not distinguished
@end itemize


@node Wishlist Emacs, Wishlist LaTeX, Wishlist Fonts, Wishlist
@comment  node-name,  next,  previous,  up
@subsection Wishlist: Changes in Emacs/XEmacs
@cindex Emacs Changes
@cindex XEmacs Changes
@cindex Changes in Emacs
@cindex Changes in XEmacs

Changes in Emacs and/or XEmacs would improve package X-Symbol, too:

@itemize @bullet
@item
In Emacs: a package system similar to XEmacs' one.  The installation
would be easier.

@item
@pindex ispell
The package @code{ispell} assumes the buffer contents to be the same as
the file contents and does not provide any hook to fix this.  This
should be fixed in @code{ispell} (it will be better in Emacs-21.4),
see @ref{Miscellaneous Packages}.

@item
@pindex vc
Some versions control commands turn off @code{font-lock}.  This should
be changed.

@item
Provide a face property @code{raise}: we wouldn't need extra fonts for
super- and subscripts.  Emacs: it's already a display property, make it
a face property, too (or make @code{font-lock} set properties other than
faces).  XEmacs: no such property, yet.

@item
You are sometimes unnecessarily asked (because X-Symbol will encode the
corresponding characters anyway) for a safe coding system.  In Emacs
(will be fixed in Emacs-21.4) for non-default Latin characters.  In
XEmacs, for all non-default characters if you use package
@code{latin-unity} (@pxref{File IO Packages}).

@item
@findex isearch
In Emacs, will be fixed in 21.4.  Using @code{isearch} and the input
method Grid would not work.

@item
@vindex after-insert-file-functions
In XEmacs, fixed in 21.X.  In @code{after-insert-file-functions}, there
should be a possibility to get to know the start position of the region
which is inserted.  If @code{insert-file-contents} is called with
argument @code{replace} being non-@code{nil}, it is not always point.

@item
@vindex write-region-annotate-functions
In Emacs and XEmacs, will be fixed in Emacs-21.4.  Make possibility to
change buffers in @code{write-region-annotate-functions} official, see
@ref{Alt Auto Conversion}, have a way to get the original buffer.

@item
Since @code{font-lock} uses duplicable text properties in some cases, I
need a function like @code{insert-buffer-substring-without-extents}.
(Currently, I remove the extents afterwards, which looks slow for me.)

@item
@vindex post-command-hook
In XEmacs.  Run hooks in @code{post-command-hook} even if command exits
with an error or quit (as it is in Emacs) or having some
@code{post-error-or-quit-hook}.  @xref{Nomule Problems}.

@item
In XEmacs.  There are some bugs in package @code{custom}/@code{widget}
(still in XEmacs-21.4) which are visible during the customization of
X-Symbol.

@end itemize


@node Wishlist LaTeX, Wishlist Various, Wishlist Emacs, Wishlist
@comment  node-name,  next,  previous,  up
@subsection Wishlist: Changes in La@TeX{}
@cindex La@TeX{} Changes
@cindex Changes in La@TeX{}
@cindex @file{inputenc.sty} Changes
@pindex @file{inputenc.sty}

Changes in La@TeX{}, especially @file{inputenc.sty}, would improve package
X-Symbol, too:

@itemize @bullet
@item
To make the definition of the character U00B5 consistent with Unicode,
@file{inputenc.sty} should define the character to stand not for the
token @code{\mu} (U03BC is the right character), but for an extra token,
e.g., something like @code{\textmicro}.  X-Symbol uses @code{\mathmicro}
here in order to avoid changing @code{\mu} to the character U00B5 if you
have chosen to store 8bit characters.
@c X-Symbol should not define it as \textmicro because then there would
@c be a major difference between `x-symbol-8bits' nil and non-nil.

@item
Use same encoding for both text and math, i.e. use @code{periodcentered}
for both @code{\textperiodcentered} (the default) and @code{\cdot}.  At
least provide text-and-math versions for characters where no alternative
is more obvious than the other.  If that is not possible, always choose
text mode except for @code{\lnot}, @code{\pm}, @code{\times} and
@code{\division}: use
@code{\textonesuperior} for U00B9, \texttwosuperior for U00B2, and
@code{\textthreesuperior} for U00B3.

@item
The @TeX{} macros @code{\textcent}, @code{\textcurrency},
@code{\textbrokenbar}, @code{\textyen} are defined as not available with
OT1 and T1 font encoding.  This should be changed.
@end itemize


@node Wishlist Various, Wishlist Rejected, Wishlist LaTeX, Wishlist
@comment  node-name,  next,  previous,  up
@subsection Various Projects for X-Symbol

The following suggestions seem to be useful, though not essential:

@itemize @bullet
@item
@cindex Print Buffer
@cindex Buffer Printing
@pindex ps-print
It would be nice if we could print the buffer contents.  Currently, you
see strange characters instead X-Symbol's own characters.

Printing non-standard fonts is only possible via the Emacs package
@code{ps-print}.  A newer version of @code{ps-print} might be probably
already capable of doing it.  Thus, you are encouraged to help the
XEmacs team updating this package.
@end itemize


@node Wishlist Rejected,  , Wishlist Various, Wishlist
@comment  node-name,  next,  previous,  up
@subsection Rejected Suggestions for X-Symbol
@cindex Rejected Suggestions

The following suggestions seem to be not useful enough to be worth the
additional effort and increased package size.  I might be convinced
otherwise by patches (i.e., code, not text), though:

@itemize @bullet
@item
@cindex Input Method Token
It would be nice if X-Symbol would replace the token with the last
character of the token if this is possible (@pxref{Input Method Token}),
not just with the next character.  Well, during typing, this is not
really annoying and after a while, you will use input method Token only
for very short tokens.
@end itemize

@c ===========================================================================

@node Open Questions, Acknowledgments, Wishlist, History
@comment  node-name,  next,  previous,  up
@section Open Questions
@cindex Open Questions
@cindex Various Questions
@cindex Questions I Have

This section lists some minor open questions.

@itemize @bullet
@item
@findex x-symbol-initialize
@cindex Auto Initialization
Loading file @file{x-symbol.el} will initialize package X-Symbol (via
function @code{x-symbol-initialize}), since all functions will need the
initialization.  In my opinion, this is no problem, since all
customization options are defined an other files which do not require
file @file{x-symbol.el}.  Thus, customizing package X-Symbol will not
initialize package X-Symbol.

The alternative would be to call function @code{x-symbol-initialize} in
every function which can be autoloaded.  This seems quite tedious to
me.  Also, I do not see a reason not to call @code{x-symbol-initialize}
top-level in file @file{x-symbol.el}.  If I am wrong here, please let me 
know (with an explanation).  Batch-compilation might be an issue@dots{}

@item
@pindex crypt
@vindex x-symbol-auto-conversion-method
When is necessary to set @code{x-symbol-auto-conversion-method} to
@code{slowest}?  Of course, it is only necessary when using
@code{crypt}.  Is the other necessary condition to use the computer pool
of the University of Edinburgh?
@end itemize

@c ===========================================================================

@node Acknowledgments,  , Open Questions, History
@comment  node-name,  next,  previous,  up
@section Acknowledgments
@cindex Acknowledgments
@cindex Contributions
@cindex Marlet, Renaud
@cindex Bradfield, Julien
@pindex math-mode
@cindex Adobe
@pindex frame-icon
@cindex Thanks

Stefan Monnier did many of the changes necessary for porting X-Symbol to
Emacs-21.  Fortunately, he not only changed X-Symbol to use a quite
different API on Emacs for things like charsets and menus, he also made
the necessary changes in Emacs itself.  Before that, Sang-Min Lee
started porting X-Symbol to Emacs-20.4, which was important for moving
the status of the Emacs port of X-Symbol from ``todo'' to ``in work''.

David Kastrup demonstrated that the old way of encoding characters to
@TeX{} macros generally inhibited ligatures and kerns, i.e., it was
worse than expected.  He also discussed the details of how to do the
encoding and decoding right.  Christophe Raffalli suggested to use a
decode method which can be used for a larger class of token languages.
He also proved that it is faster.

Solofo Ramangalahy is working on scripts to generate X-Symbol fonts from
other sources.  This has various advantages and is discussed in more detail at
@ref{Wishlist Fonts}.  His work is now available at the
X-Symbol download area.

Package @code{math-mode} by Renaud Marlet and the extension of it by
Julian Bradfield gave the basic idea for the following features:
supporting @TeX{}'s math macros, input methods token, context/electric,
super-/subscript support.  The shell script @code{makesub} is a merge
and change of the scripts @code{makesupers} and @code{makesub} by
Julian.

The font @samp{xsymb0}, which is distributed with this package, is a
minor modification (appearance) of the Adobe symbol font, thanks to its
non-restrictive copyright.  You may use the Adobe font instead.  The
special images are from package @code{frame-icon}.

The idea for Help during an X-Symbol key sequence is from package
@code{x-compose}.  The general idea for showing some info in the echo
area is from package @code{eldoc}.  The trick which stops
@code{expand-abbrev} is from package @code{mail-abbrevs}.  The idea for
@code{x-symbol-image-cache-directories} is from package
@code{fast-lock}.  The code for image command parsing is influenced by
some code in package @code{font-lock}.  The code around
@code{x-symbol-image-delete-extents} is based on some code in package
@code{bib-cite}.

@i{Thanks for patches/reports/suggestions to}: Adrian Aichner, Vladimir Alexiev, David
Aspinall, Masayuki Ataka, Neal Becker, Matthias Berberich, Stefano
Bianchi, Janusz S. Bien, Uwe Brauer, Alastair Burt, John Collins,
Laurent Descamps, Frederic Devernay, Carsten Dominik, Steve Dunham,
Michael Ebner, Stephen Eglen, Paul Furnanz, Jeffrey Grandy, Clemens
Gr@"opl, Kenichi Handa, Meik Hellmund, Ryurick M. Hristev, Adriaan
Joubert, Marcin Kasperski, David Kastrup, Richard Ketchersid, Felix
E. Klee, Gerwin Klein, Thomas Kleymann, Ekkehard Koehler, Fred Labrosse,
Jan-Ake Larsson, Bernhard Lehner, Stefan Monnier, Harald Muehlboeck,
Karsten Muehlmann, Jakub Narebski, Peter M@o{}ller Neergaard, Raymond
Nijssen, David von Oheimb, Alex Ott, Sudeep Kumar Palat, Arshak
Petrosyan, Jim Radford, Christophe Raffalli, Solofo Ramangalahy, Alex
Russell, Marciano Siniscalchi, Richard M. Stallman, Axel Thimm, Eli
Tziperman, Jan Vroonhof, Markus Wenzel, Sabine Wetzel, Pierre-Henri
Wuillemin, Roland Zumkeller, Marco Zunino, Gerard Zwaan.

@i{Thanks for general information to:} Per Abrahamsen, Steve L. Baur,
Kenichi Handa, David Kastrup, Gerd Moellmann, Stefan Monnier, Primoz
Peterlin, Martin Ramsch, Peter Schmitt, Toby Speight, Jan Vroonhof, Eli
Zaretskii.

I made use of information from the following URLs:

@display
  @url{http://www.fmi.uni-passau.de/~ramsch/iso8859-1.html}
  @url{http://czyborra.com/charsets/iso8859.html}
  @url{http://www.bbsinc.com/iso8859.html}
  @url{http://www.bbsinc.com/iso8879.html}
  @url{http://ppewww.ph.gla.ac.uk/~flavell/charset/internat.html}
  @url{http://ppewww.ph.gla.ac.uk/~flavell/iso8859/iso8859-pointers.html}
  @url{http://sizif.mf.uni-lj.si/linux/cee/iso8859-2.html}
@end display

I do not intend to update this list in the future---this is just an
"Acknowledgment" section.


@node Indexes,  , History, Top
@comment  node-name,  next,  previous,  up@unnumbered Indexes
@unnumbered Indexes

You should consult the following indexes if you are interested in a
specific feature or aspect of package X-Symbol.  You should also consult
them before sending a report to the maintainer (@pxref{Bug Reports}),

@menu
* Key Index::                   Key sequences.
* Program Index::               Programs and Emacs packages.
* Variable Index::              Commands, functions, variables.
* Concept Index::               Various topics.
@end menu

The links lead you to the manual sections describing X-Symbol's commands
and variables.  @xref{About}.

@comment workaround for bug with the length of the lists
@iftex
@vskip 6ex plus 1ex minus 4ex
@end iftex

@node Key Index, Program Index, Indexes, Indexes
@comment  node-name,  next,  previous,  up
@unnumberedsec Key Index
@printindex ky

@comment workaround for bug with the length of the lists
@iftex
@page
@end iftex

@node Program Index, Variable Index, Key Index, Indexes
@comment  node-name,  next,  previous,  up
@unnumberedsec Program and Package Index
@printindex pg

@comment workaround for bug with the length of the lists
@iftex
@page
@end iftex

@node Variable Index, Concept Index, Program Index, Indexes
@comment  node-name,  next,  previous,  up
@unnumberedsec Command, Function and Variable Index
@printindex vr

@comment workaround for bug with the length of the lists
@iftex
@page
@end iftex
@node Concept Index,  , Variable Index, Indexes
@comment  node-name,  next,  previous,  up
@unnumberedsec Concept Index
@printindex cp

@contents
@bye
@c Local IspellPersDict: .ispell_xsymb