This file documents X-Symbol, a package providing semi-WYSIWYG for LaTeX, HTML and other ``token languages''.  It uses additional fonts and provide input methods to insert their characters into your document.

This is Edition 4.5.1 (XEmacs) of the X-Symbol Manual for X-Symbol 4.5.1, May 2003.

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

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

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

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

X-Symbol
********

When you edit LaTeX, HTML, BibTeX or TeXinfo sources in Emacs, package X-Symbol provides some kind of WYSIWYG by using real characters for tokens like \oplus or &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 4.5.1 (XEmacs) of the X-Symbol Manual for X-Symbol 4.5.1, May 2003.  For recent changes, see News.

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

Introduction
************

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

X-Symbol's Copying Conditions: GPL
==================================

(This text is stolen from the TeXinfo 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 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.

Brief Summary of X-Symbol
=========================

  * X-Symbol provides a 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.

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

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

  * Offers some info in the echo area for these characters (e.g., that the character under point represents the TeX macro \leadsto and that the macro is defined in LaTeX package latexsym.sty).

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

  * Provides a kind of ``poor man's Mule'' when running on an XEmacs without Mule support: it can display more than 256 characters via 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.

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

  * Displays thumbnails for images at the end of image insertion commands with per-buffer control (e.g., \includegraphics{FILE} in LaTeX, <img src=FILE> in HTML).  They show a scaled-down version of the included image files (using convert from ImageMagick (http://www.imagemagick.org/)).  A single mouse click on the image or command invokes the image editor for the corresponding image file.

  * It does not and 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 font-lock, e.g., 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 outline-minor-mode or folding might also be an alternative.

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

  * You have complete control over the LaTeX source.  X-Symbol supports more characters.

  * You can read any LaTeX source and you write normal LaTeX code, i.e., package X-Symbol does not use any special format.

  * It also supports HTML and TeXinfo documents and BibTeX entries.

  * You can use your favorite editor, i.e., Emacs or XEmacs.

About this Manual
=================

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

  * 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:

            http://x-symbol.sourceforge.net/

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

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 X-Symbol Internals.

This manual does not explain Emacs in general or some optional programs used by this package such as 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 Bug Reports.

Installation
************

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

Please check the web page 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.

Requirements
============

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, 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 (see Wishlist Fonts).  Under a character terminal, X-Symbol just supports Latin-1 characters only, no super- and subscripts and no images.

This package require package font-lock (distributed with Emacs and XEmacs), the use of package lazy-shot is recommended, see Syntax Hiliting Packages.

If you want to see the images at the end of image insertion commands, install convert from ImageMagick (http://www.imagemagick.org/), see Installing Image Converter.  They show a scaled-down version of the included image files.

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

Put the Files into your Home Directory
======================================

If you use Emacs, please check the web pages of X-Symbol (http://x-symbol.sourceforge.net/news.html).

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 System-wide Installation.  If you use the source distribution, you should know what do to instead.

In directory ~/.xemacs/xemacs-packages/, run

     zcat x-symbol-pkg.tar.gz | tar xvf -

Remember that tar does not overwrite write-protected files.

X-Symbol's 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

     chmod -R a+rx ~/.xemacs/xemacs-packages

If package X-Symbol has been installed system-wide and you install a newer version in your ~/.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....

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

System-wide Installation: Put the Files into the XEmacs Directory
=================================================================

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 default.el and XEMACS/site-packages/ whenever ~/.emacs and ~/.xemacs/xemacs-packages/ are mentioned in the previous or following subsections.  XEMACS/site-packages/ is the directory of independent packages for XEmacs.

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

     M-x package-admin-add-binary-package RET DIR/x-symbol-pkg.tar.gz

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

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

     (load "XEMACS/lisp/x-symbol/auto-autoloads")

I would appreciate if you would set the following variables:

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

x-symbol-package-url
     If you have a local copy of the web pages (see Installing Manual), set this variable to the corresponding URL.

Make XEmacs Initialize X-Symbol During Startup
==============================================

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

     (x-symbol-initialize)

Basically, that's it!  If your XEmacs runs on a different machine, check 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, Requirements), set the default coding (see Default Coding) by putting the following in front of the line above:

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

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

     (unless window-system (standard-display-european 1))

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:

     (when window-system (x-symbol-initialize))

The initialization can be controlled by the following variable:

x-symbol-initialize
     By default, package X-Symbol does a full initialization.  This includes an integration with some packages, see also Package Integration.

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: isearch, highlight, primary-selection, secondary-selection, paren-match, paren-mismatch, paren-blink-off, underline.  I.e., for each FACE, use:

     (remove-specifier (get (get-face 'FACE) 'font))

Installing the Image Converter from ImageMagick
===============================================

Program 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.

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

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

Check http://www.imagemagick.org/ for the installation instructions.  Run convert -h and 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.

If you do not have a truecolor device (i.e., just 256 colors), package X-Symbol uses convert with a colormap by default (see 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.

Package Integration
===================

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.

LaTeX Packages
--------------

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

auctex
     Use Version 9.9c or higher, which includes texmathp.  There is some special X-Symbol adaptation for AucTeX:

       - X-Symbol supports AucTeX's multifile documents: it respects the variable TeX-master when searching for the file encoding (see File Coding) and when converting image files with relative names (see Image Display).

       - X-Symbol supports AucTeX's region commands: it ensures that characters in _region_.tex buffer are converted according to the parent buffer.  Initialization changes TeX-region-hook.  Requires AucTeX, v9.8a or higher.

       - X-Symbol's input method Electric (see Input Method Electric) with token language tex uses package texmathp.

       - AucTeX's math mode commands also inserts X-Symbol characters (see Mathematics (AUCTeX)). Initialization sets LaTeX-math-insert-function.  Requires AucTeX, v9.8a or higher.

       - If TeX displays an error message, it also displays the context of the error position.  AucTeX uses the context to set point to this position when 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 TeX-translate-location-hook.

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 bib-cites highlighting of \cite and friends.

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

reftex
     Use Version 3.26 or higher.  For a workaround for some minor annoyances with the combination RefTeX/X-Symbol/Multifile Document, see Problems and Work-arounds (RefTeX User Manual).  By default, the initialization of package X-Symbol makes RefTeX's label creation use the nicer Asciification of package X-Symbol (see Ascii Representation) by setting reftex-translate-to-ascii-function.

whizzytex
     Use the newest.

Syntax Highlighting Packages (font-lock and add-ons)
----------------------------------------------------

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

fast-lock
     I recommend to use package lazy-shot instead.  By default, the initialization of package X-Symbol sets fast-lock-save-faces to nil to make package fast-lock work with X-Symbol.

font-latex
     I suggest to set font-lock-maximum-decoration to value t, 2 or higher if you do not want to use super- and subscripts in arguments of \label and friends.  See FAQ Stupid Subscripts.

font-lock
     Is required by this package (see Role of font-lock).  I strongly recommend not to turn on font-lock in any mode hook, set font-lock-auto-fontify to t instead (this is the default, anyway).  See also 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 after the functions in the mode hook have been run, i.e., the fontification is getting useless if the tokens are automatically decoded.

lazy-lock
     From XEmacs-20.3 on, the successor is called lazy-shot.

lazy-shot
     Is strongly recommended.

File I/O Packages
-----------------

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

ange-ftp
     See also efs and jka-compr.

comint
     The default installation makes comints in-/output use X-Symbol's conversion function.  If you set variable comint-input-sender, set it before initializing package X-Symbol.

crypt
crypt++
     I recommend to use package jka-compr instead.  See Spurious Encodings.  See No Encoding.  If you use crypt or  crypt++ and the character alpha looks like \233a after save-buffer, set this variable to slowest.  See Open Questions.

efs
     XEmacs' version of ange-ftp.  See also jka-compr.

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.

iso-sgml
     There is no need to use it.  Package X-Symbol already provides the conversion between Latin-1 characters and ``SGML entities''. See Miscellaneous Packages, package psgml-html.

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

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 (see Char Aliases) and recoding (see File Coding).  Has some safe-encoding mechanism, but the test comes currently too early (see Wishlist Emacs).

ucs-tables
     The Emacs minor modes unify-8859-on-decoding-mode and unify-8859-on-encoding-mode can be used with package X-Symbol.

vc
     If you use package crypt, vc-next-action and friends encode characters to tokens.  See Spurious Encodings.

Miscellaneous Packages
----------------------

abbrev
     On XEmacs without Mule support, I recommend to set variable words-include-escapes to t.  See Nomule Problems.

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

desktop
     XEmacs' version (an old one) does not save its .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 session below.

flyspell
     Should work apart from the general problem of ispell.

func-menu
     Should work with X-Symbol.

ispell
     The package 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 ispell, see Wishlist Emacs.  See FAQ Spell Check.

     Use a future version (hopefully v3.4).  Includes special X-Symbol initialization/handling and defines additional token languages. See External Languages.

psgml-html
     psgml-html: Do not set html-auto-sgml-entity-conversion to non-nil.  See File IO Packages, package iso-sgml.

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

x-compose
     All characters from x-compose are also supported by package X-Symbol.  Thus, I recommend to use multi-key instead C-= when running under XEmacs without Mule support. See Introducing Input Methods.

Installing Additional 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....  Nevertheless, if you have a clearer explanation for the installation sequence below, please send me a patch to man/x-symbol/x-symbol.texi.)

 1. Find the font which you want to replace by checking fonts with the X11 program xfontsel or 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.

 2. Find the .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 .bdf files for additional fonts sizes of all fonts except the xsymb1 font (see Wishlist Fonts).

     There are two categories of .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 ~/.xemacs/xemacs-packages/etc/x-symbol/origfonts/.  The second category contains files for fonts which are not installed.  Copy these files to ~/.xemacs/xemacs-packages/etc/x-symbol/fonts/.

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

 4. In directory ~/.xemacs/xemacs-packages/etc/x-symbol/fonts/, execute make mkdirs, and make pcfs.  You need GNUs make and perl, Version 5 (or higher).

 5. 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 ~/.xsession (X11 startup file).

          xset +fp ~/.xemacs/xemacs-packages/etc/x-symbol/pcf/

     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 xset, you should copy all .pcf files (compiled fonts) from ~/.xemacs/xemacs-packages/etc/x-symbol/pcf/ into directory /usr/lib/X11/fonts/75dpi/ (Slackware distribution) and run mkfontdir 75dpi in that directory.

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

 7. Set the Emacs Lisp variables which define the fonts.  See Installing Fonts Lisp.

Installing Fonts for Exceed (X-server on Windows)
=================================================

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:

 1. In Unix, edit file ~/.xemacs/xemacs-packages/etc/x-symbol/fonts/makesub to limit the shift for superscript to 3 points:

          %supoffs = ('08',3, 10,3, 12,3, 14,3, 16,3, 18,3, 24,3);

 2. Then, execute make mkdirs, and make gens in ~/.xemacs/xemacs-packages/etc/x-symbol/fonts/.  If you have problems, please read the previous section.

 3. In Exceed's configuration window, click on Font to open Window Font Settings.  In this window, click on Select All, then on Compile Fonts....

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

 5. In Window Font Settings, click on Font Database....  In this window, click on Add....  Enter the output directory from the previous step as the Font Directory and xsymb as the File Name (*.fdb).  Click on OK.

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

 7. In Window Font Database, click on Rebuild Database... and then on OK.

Note: Windows NT 4.0 will crash (bluescreen) if you use fonts compiled by Exceed from the 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.

Lisp Coding when Using Other Fonts
==================================

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 font-lock to display them (see Role of font-lock).

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

x-symbol-latin1-fonts
x-symbol-latin2-fonts
x-symbol-latin3-fonts
x-symbol-latin5-fonts
x-symbol-latin9-fonts
x-symbol-xsymb0-fonts
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-encoding (e.g., adobe-fontspecific) as specified by the fonts in the default value of this variable.

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 %d in the names.

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

     (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")))

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 (see FAQ Font Size).

You might want to change the following variables:

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.

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 Installing Fonts Lisp might have no influence if Emacs already has defined fonts for the corresponding charsets.

Installing Info, Postscript and HTML Files
==========================================

To create the info files, execute make info in directory ~/.xemacs/xemacs-packages/man/x-symbol/ of the distribution.  It requires 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 ~/.xemacs/xemacs-packages/info/dir:

     * X-Symbol::	 Semi WYSIWYG for LaTeX, HTML and other "token languages"

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

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

All formats of the manual are created by executing make all.

Checking the Correct Installation of Package X-Symbol
=====================================================

After having completed the installation, exit and restart Emacs.

  * Type 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.

  * Type M-x x-symbol-grid in buffer *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 *Warnings*.  See Installing Fonts.

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

  * Again, type 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.

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

Concepts of Package X-Symbol
****************************

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 Input Methods, and Features.

Token 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 token language which is in close relation to the major mode of the current buffer.  E.g., character alpha stands for \alpha in LaTeX buffers.

For details of predefined token languages ``TeX macro'' (tex), ``SGML entity'' (sgml), ``BibTeX macro'' (bib), and ``TeXinfo command'' (texi), see Supported Languages.

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

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

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 (see File Variables (XEmacs User's Manual)), e.g.:

          %% Local Variables:
          %% x-symbol-language: tex
          %% End:

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 Minor Mode.

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

Conversion: Decoding and 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 decoding, and some conversion from characters to tokens, called 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 (iso-8859-1), Latin-2 (iso-8859-2), Latin-3 (iso-8859-3), Latin-5 (iso-8859-9), and Latin-9 (iso-8859-15).  It currently supports less encodings with XEmacs on Windows (see Requirements).

Normal File and Default Encoding
--------------------------------

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 normal file
encoding, also called a coding system (see Recognize Coding (XEmacs User's Manual)).

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 normal file encoding is the default encoding:

x-symbol-default-coding
     The default encoding.  The value must be a symbol denoting one of the supported encodings or nil.  The variable must be set before X-Symbol has been initialized.  See Installing Lisp.

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

  * X-Symbol has its own mechanism to recognize a file encoding which only works with a specified default encoding.  See File Coding.

  * 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.  See Char Aliases.

  * 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.  See Poor Mans Mule.

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

     locale -ck code_set_name charmap

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 nil is the same as 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 nil makes sure that X-Symbol file encoding detection (see File Coding) only works if Emacs has detected the same encoding; it works like iso-8859-1 otherwise.

File Coding of 8bit Characters
------------------------------

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:

x-symbol-coding
     8bit character encoding in the file visited by the current buffer. Value nil represents the normal file encoding (see Default Coding).

     With Mule support, any value other than 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 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 (see File Variables (XEmacs User's Manual)), e.g.:

          <!-- Local Variables: -->
          <!-- x-symbol-coding: iso-8859-2 -->
          <!-- End: -->

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

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

If you choose not to save a file containing 8bit characters (see 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.  Recoding changes a character with code position POS in one charset to a character with the same code position POS in another charset.  If the normal file encoding is different to the default encoding, X-Symbol also resolves character aliases (see 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:

  * 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 (see Controlling 8bit Coding).  The modeline includes -i to represent the file encoding (see Minor Mode), except if the default encoding is nil, the normal file encoding is unsupported, and the variable x-symbol-coding is not specified.

  * 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 (see Unique Decoding) nor via input methods.  The modeline includes -err to represent the file encoding (see Minor Mode).

We end with a little example: if your normal file encoding and default encoding is Latin-1, and you visit a file with \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.

Store or Encode 8bit Characters
-------------------------------

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

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 (see File Variables (XEmacs User's Manual)), e.g.:

          %% Local Variables:
          %% x-symbol-8bits: t
          %% End:

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

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.

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

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

Setting variable x-symbol-8bits to 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 (see 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 (see Introducing Input Methods), you have probably copied them into the current buffer.

Unique Decoding
---------------

Token languages might define more than one token representing the same character.  When decoding and encoding these tokens, they will be normalized to one form, the canonical representation.  E.g., with language tex, visiting a file with tokens \neq and \ne converts both tokens to character lessequal, saving the buffer stores the character as token \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 (see TeX Macro Problems)! For this reason, package X-Symbol provides the following buffer-local variable:

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 x-symbol-8bits is non-nil (see Controlling 8bit Coding), do not decode tokens which would be decoded to 8bit characters (according to the coding in your file, see File Coding).

     You can set this variable in the ``local variables list'' near the end of the file (see File Variables (XEmacs User's Manual)), e.g., together with a setting for x-symbol-8bits:

          %% Local Variables:
          %% x-symbol-8bits: t
          %% x-symbol-unique: t
          %% End:

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

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

Conversion Commands
-------------------

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

  * Turning X-Symbol minor mode (see Minor Mode) on/off also performs decoding/encoding.

  * 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).

  * Inserting a file into a buffer where X-Symbol is enabled will decode the tokens in the inserted region.

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):

M-x x-symbol-decode-recode
     Recode all characters (if necessary) and decode all tokens to characters.

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

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

M-x 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 x-symbol-8bits is relative to the file coding, see Controlling 8bit Coding.

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 (see 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.

Copy & Paste with Conversion
----------------------------

You probably use X-Symbol, because you want to produce some non-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-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 plusminus from a LaTeX buffer to a HTML buffer, you really copy that character and not the three characters of the TeX macro \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):

M-x x-symbol-copy-region-encoded
     Save the region in the kill-ring with all X-Symbol characters encoded like by M-x x-symbol-encode, i.e., without recoding.

M-x x-symbol-yank-decoded
     Reinsert the last text in the kill-ring and decode the inserted text like M-x x-symbol-decode, i.e., without recoding.

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

Character Aliases
-----------------

A character alias or char alias is a character which is also a character in a font with another registry, e.g., adiaeresis is defined in all supported Latin fonts.  Emacs distinguish between these five characters.  In package X-Symbol, one of them, with x-symbol-default-coding (see 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 adiaeresises and that there are neither different adiaeresises in Unicode nor in the token representations of languages tex and sgml.

8bit characters in files with a file coding x-symbol-coding other than x-symbol-default-coding are converted to the ``normal'' form.  E.g., if you have a Latin-1 font by default, the adiaeresis in a Latin-2 encoded file is a Latin-1 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 european.el.  In XEmacs without Mule support, this is only possible if you use commands like 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):

M-x x-symbol-unalias
     Resolve all character aliases in buffer.  If the region is active, only resolve char aliases in the region.

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

The XEmacs package 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.

Minor Mode
==========

X-Symbol is a minor mode (see Minor Modes (XEmacs User's Manual)) which enables the features mentioned in this manual:

  * X-Symbol mode is required to do the conversions.  Turning the minor mode on/off also includes decoding/encoding (see Conversion Commands).

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

  * X-Symbol mode is required for most input methods (see Input Methods) and other features (see Features).

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:

M-x 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 (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., vm-mode (see FAQ News and Mail).  Use a prefix argument to be asked whether to turn in on anyway.

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 (see 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:

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):

       - x-symbol-token-language (see Token Language), indicated in the modeline, e.g. tex,

       - x-symbol-mode, i.e., whether it is appropriate to turn on X-Symbol mode automatically,

       - x-symbol-coding (see File Coding), indicated in the modeline if different from the default coding, e.g. -l2 for Latin-2,

       - x-symbol-8bits (see Controlling 8bit Coding), indicated in the modeline by 8,

       - x-symbol-unique (see Unique Decoding), indicated in the modeline by *,

       - x-symbol-subscripts (see Super and Subscripts), indicated in the modeline by s,

       - x-symbol-image (see Images), indicated in the modeline by i,

x-symbol-LANG-modes
     Major modes which use token language LANG by default. See Supported Languages.  The languages are checked in registration order (the order shown in the language selection submenus).

x-symbol-LANG-auto-style
     Default values for the above mentioned variables x-symbol-mode, x-symbol-coding, x-symbol-8bits, x-symbol-unique, x-symbol-subscripts, and x-symbol-image if not already buffer-local.

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

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

     The menu might also include individual entries for a token language (see TeX Macro Basics):

x-symbol-LANG-extra-menu-items
     Extra menu items for each token language LANG (see TeX Macro Basics).

Poor Man's Mule: Running Under XEmacs/no-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 (see Default Coding) are represented by two characters, see Char Representation.

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

  * 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.

  * Package 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 Role of font-lock.

     x-symbol-nomule-fontify-cstrings
          Alternatively to enabling 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 reftex.

The Role of font-lock
=====================

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

When X-Symbol mode is turned on, it automatically adds the necessary font-lock keywords to the buffer-local value of 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 font-lock might not yet been turned on or since you might want to change font-locks decoration of the current buffer after X-Symbol has been turned on.

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

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

M-x x-symbol-fontify
     Refontify buffer.

Character Group and Token Classes
=================================

Each X-Symbol character belongs to a character group, e.g., natnums belongs to 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:

  * The Grid and submenu header under which the character can be found (see Input Method Grid, Input Method Menu).

  * The default bindings of characters (see Input Method Keyboard) of some groups.

  * Whether to show the context info for a character (see Info).

  * The default ASCII representation of a character (see Ascii Representation).

  * When using Emacs/XEmacs with Mule support, the syntax of a character (see Syntax (XEmacs User's Manual)).

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

  * Information in the echo area (see Info), it could inform users to include a specific LaTeX package when they want to use that character in the document.

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

  * Restricting the ``electricity'' of input method Electric (see Input Method Electric), useful to disable this input methods for TeX's math-mode characters if we are in text-mode.

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

x-symbol-LANG-header-groups-alist
     The Grid and Menu headers for each token language LANG.

x-symbol-LANG-class-alist
     Strings for the character info in the echo area for each token language LANG.

x-symbol-LANG-class-face-alist
     The coloring scheme for each token language LANG.

X-Symbol's Input Methods
************************

An X-Symbol 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 web pages of X-Symbol (http://x-symbol.sourceforge.net/details.html).

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 AucTeX, Version 9.8a or higher, its math mode commands also inserts X-Symbol characters (see Mathematics (AUCTeX)).

Common Behavior of All Input Methods
====================================

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

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 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 x-symbol-language (see Token Language).

If a buffer is read-only (see Misc Buffer (XEmacs User's Manual)), most input methods push the character to insert onto the kill ring instead.  Typing C-y lets you then insert the character (see Yanking (XEmacs User's Manual)).

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

  * With prefix argument 0, do not insert anything, just barf, if the character is not valid.

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

  * 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.

  * With one or more C-us with no digits, insert the token of a language to choose, including ``x-symbol charsym'' (see Pseudo Language).

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

x-symbol-compose-key
     By default, C-= is used as the key prefix.  Under XEmacs/no-Mule, you might want to use multi-key instead:

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

x-symbol-auto-key-autoload
     Set this to nil, if you do not want that pressing C-= automatically initializes the input methods.

Input Method Token: Replace Token by Character
==============================================

If X-Symbol mode is on, input method 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 (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 font-lock which highlights the token to look like a character.

You might want to press C-/ or 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:

x-symbol-token-input
     A boolean which can also be changed via the X-Symbol menu.

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

Input Method Read Token: Minibuffer Completion
==============================================

You can insert a character by reading the corresponding token in the minibuffer.  You are offered completion over the known tokens (see Completion (XEmacs User's Manual)).

M-x x-symbol-read-token-direct
C-= 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'' (see Pseudo Language).

M-x x-symbol-read-token
C-= RET
     Insert character by first selecting the token language and then a token in that language.

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 Introducing Input Methods.

Input Method Menu: Select a Menu Item
=====================================

If X-Symbol mode is turned on, a Menu X-Symbol appears in the menubar (see Minor Mode).  It also appears over non-highlighted parts in the Grid and the Key Completions buffer (see Input Method Grid).  The menu allows to change buffer-local and global variables (some directly, some via package 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 Char Group.  The appearance of the menu can be customized:

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.

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.

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 Introducing Input Methods.

Input Method Grid: Choose Highlighted Character
===============================================

Probably the easiest way to insert a character is by using a Grid of characters:

M-x x-symbol-grid
C-= C-=
     Pops up a buffer displaying X-Symbol characters in a grid like fashion. You can select a character with the mouse or RET, see below.

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

button2
RET
SPC
     Insert highlighted character (or character under point, respectively) into the buffer of point if 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.)

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 (see Token Language).

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

button2
     Scroll Grid or Key Completions buffer down in upper half of the window and scroll up in the lower half of the window.

button3
     Pops up the X-Symbol menu, see Input Method Menu).

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

M-x x-symbol-list-info
?
h
i
     Display info for character under point in echo area.

M-x x-symbol-list-bury
q
     Bury list buffer while trying to use the old window configuration.

You can control the grid by the following variables:

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.

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

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

x-symbol-grid-ignore-charsyms
     The Grid does not contain nobreakspace.

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

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

The headers in the Grid are the same as the submenu headers, see Char Group.  Similar looking characters for one headers are grouped together.  See 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 Introducing Input Methods.

Input Method Keyboard: Compose Key Sequence
===========================================

Key sequences starting with C-= (see Introducing Input Methods) are used to insert X-Symbol characters, e.g., C-= ~ > inserts leadsto.  The Ascii sequence of the keys after 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 Input Method Context.

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

M-x x-symbol-help
C-= ZERO-OR-MORE-KEYS help
C-= ZERO-OR-MORE-KEYS C-h
     Pops up a buffer displaying possible completions for the key sequence C-= ZERO-OR-MORE-KEYS.  You do not have to type the key sequence again, i.e., C-= ZERO-OR-MORE-KEYS is also used for the next input.

C-= ZERO-OR-MORE-KEYS button1
C-= ZERO-OR-MORE-KEYS button2
C-= ZERO-OR-MORE-KEYS button3
     Use the normal bindings of button1,  button2 or button3, respectively (see Input Method Grid).  The key sequence is not used for the next input.

C-= ZERO-OR-MORE-KEYS M-prior
C-= ZERO-OR-MORE-KEYS M-next
C-= ZERO-OR-MORE-KEYS M-home
C-= ZERO-OR-MORE-KEYS M-end
     Execute the commands scroll-other-window-down, scroll-other-window, beginning-of-buffer-other-window or end-of-buffer-other-window, respectively.  You do not have to type the key sequence again, i.e., C-= ZERO-OR-MORE-KEYS is also used for the next input.

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

x-symbol-map-default-keys-alist
     Defines the bindings mentioned above.

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 Introducing Input Methods.

Input Method Context: Replace Char Sequence
===========================================

The idea of the input method 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 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:

M-x x-symbol-modify-key
C-,
C-= left
C-= 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.

M-x x-symbol-rotate-key
C-.
C-= up
C-= down
     If character before point is an X-Symbol character, ``rotate'' its ``direction'' (or change uppercase/lowercase).

Both commands can also be used to resolve a character alias before point, see 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:

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

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

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

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

Input Method Electric: Automatic Context
========================================

The idea of input method Electric is to have the input method Context (see 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 (see Super and Subscripts).

You might want to press C-/ or 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:

x-symbol-electric-input
     A boolean which can also be changed via the X-Symbol menu.

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

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

  * The character must be valid in the current token language, see Introducing Input Methods.

  * All characters of the context have been typed without any other command in between, e.g., - > inserts arrowright, "- left right > simply inserts ->.

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

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

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

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

     x-symbol-electric-ignore
          The context should neither be '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

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

     x-symbol-LANG-electric-ignore
          Individual contexts/charsyms can be disabled for each token language LANG.

Input Method Quail: a Mule Input Method
=======================================

Another way to insert a characters is by using the Emacs/Mule multilingual text input method ``x-symbol'' (see Input Methods (XEmacs User's Manual))..

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

If input method Quail is selected for a buffer, input method Electric (see Input Method Electric) is disabled in that buffer.

Customizing Input Methods
=========================

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

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

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

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

x-symbol-header-groups-alist
     Defines the groups whose characters appear after that header in the Grid and in submenus with that header.  See Char Group.  Extra variables exists for the language dependent Grid and Menu.

x-symbol-group-input-alist
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.  See Defining Input Methods.

     For example, if you prefer charsym epsilon1 over epsilon you might want to use:

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

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

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

Features of Package X-Symbol
****************************

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.

Super- and 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 a^2 in the buffer are displayed as an a and a raised, smaller 2---the ^ is still in the buffer.

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

Do not confuse the special Latin characters twosuperior, threesuperior, ordfeminine and masculine with the characters 2, 3, a and 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 (see 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 font-lock to be enabled (see 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 (see Minor Mode).  They can be disabled (and re-enabled) by setting the following buffer-local variable:

x-symbol-subscripts
     A boolean which can also be changed via the X-Symbol menu.

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:

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

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

x-symbol-idle-delay
     Time in seconds of idle time before revealing invisible characters.

Super-/subscript commands are ^/_ (see TeX Macro) and <sup>/<sub> (see SGML Entity):

Images at the end of Image Insertion Commands
=============================================

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

Display of 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 (see Minor Mode).  It can be disabled (and re-enabled) by setting the following buffer-local variable:

x-symbol-image
     A boolean which can also be changed via the X-Symbol menu.

Image commands are \includegraphics and others (see TeX Macro), and <img> (see SGML Entity):

x-symbol-LANG-image-keywords
     The keywords (image commands & arguments) for each token language LANG.

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

  - absolute, start with / or ~,

  - explicitly relative, start with ./ or ../,

  - implicitly relative, assumed otherwise, e.g., image.eps, or

  - special, like having some special URL prefix like http: or ftp:.

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

x-symbol-LANG-master-directory
     The master directory for each token language LANG.

x-symbol-LANG-image-searchpath
     The image search path for each token language LANG.  Defaults to the current directory.

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

For details, see the section of the individual token languages (see Supported Languages).

Image Conversion
----------------

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 image cache file, see Image Caching.

x-symbol-image-max-width
     The image is not wider than 120 points.

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

x-symbol-image-convert-colormap
     Colormap used in function 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: etc/colormap138.xpm and etc/colormap66.xpm.

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

x-symbol-image-converter
     Program convert from ImageMagick is used to convert the images (see Installing Image Converter).  Set this variable to nil, if you don't want to convert images.

     The following variables controls the invocation of the program convert from ImageMagick:

     x-symbol-image-convert-program
          The name of the program convert, it is C:\\ImageMagick\\convert when running on Windows and convert otherwise.

     x-symbol-image-convert-file-alist
          Program convert needs to be told that FILE.pstex is a Postscript file.

     The following functions are possible values in x-symbol-image-converter:

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

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

     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.

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

          x-symbol-image-convert-mono-regexp
               Function x-symbol-image-start-convert-colormap just produces monochrome images for temporary image cache files (see Image Caching) since convert is slower when using a colormap.

Image Caching
-------------

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:

  * It uses an asynchronous process to create the image cache file.  You can edit your file during the conversion.

  * It uses a file cache: image cache file can be kept for future Emacs sessions.

  * It uses a 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:

     M-x x-symbol-image-parse-buffer
          Parse the buffer to recognize image insertion commands.  Usually, this is done automatically.

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

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.

x-symbol-image-cache-directories
     Cache files for images in your home directory are stored in directory ~/.images/, e.g., image ~/d/img.eps, is cached in ~/.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 ~/d/img.eps is cached in ~/d/.img/img.eps or that the image is not displayed at all.

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

x-symbol-image-use-remote
     Package X-Symbol only displays images which can be stored in the memory cache.  With value 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.

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

x-symbol-LANG-image-cached-dirs
     The directories with images which are stored in the memory cache.  Can be separately defined for each token language LANG.

Special Images for Specific Situations
--------------------------------------

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

  * Remote: An Escher knot is displayed if the file is remote or if the image cannot be cached in the memory cache, see Image Caching.

  * Junk: A recycle sign is displayed if there is no image converter (see Image Conversion), if it should not use a file cache or if the file cache cannot be written.

  * Locked: A terminal with a lock is displayed if the image cache file cannot be read or written.

  * Design: An ink pen is displayed if the image file does not exist.

  * 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.

  * Broken: A tombstone is displayed if the creation of the image cache file has failed.

To customize the glyphs for the special images, use:

x-symbol-image-data-directory
     Directory of files for the special images.

x-symbol-image-special-glyphs
     File names of special images and their image format.

Image Editor
------------

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

button2
     Start image editor for highlighted image.  If the image is searched in the searchpath (see Image Caching), edit first existing image file. If no image exists, open a new file in the first directory of the searchpath.

button3
     Pop up the image highlight menu.  You can rescan the buffer for image insertion commands (see 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).

M-x x-symbol-image-editor
     Start image editor.  Asks for the image file.

You can control which editor to use:

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

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.

x-symbol-image-current-marker
     Directories with an existing image for the specified file name are marked with an *.  The first of these represents the file which is used when pressing button2.

Info in Echo Area
=================

The echo area (see Echo Area (XEmacs User's Manual)) 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 (see Input Method Context).

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

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:

       - the token of the current language, eventually colored according to some coloring scheme (see Char Group),

       - infos using the token classes (see Char Group), which could inform users to include a specific LaTeX package when they want to use that character in the document,

       - the codings in which the characters is considered to be a 8bit character (see File Coding), and

       - the key bindings (see Input Method Keyboard).

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 C-, (see Input Method Context).  It can be controlled by the following variables:

     x-symbol-context-info-ignore
          The default value x-symbol-default-context-info-ignore makes the following variables control whether to display the context info.

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

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

     x-symbol-context-info-ignore-groups
          The context is not replaced by an accented character, see Char Group.

x-symbol-idle-delay
     Time in seconds of idle time before showing the info.

Ascii Representation of Strings
===============================

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

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

     x-symbol-charsym-ascii-alist
          You might want to define the German way to Asciify accented characters by:

               (setq x-symbol-charsym-ascii-alist
                     '((adiaeresis . "ae") (Adiaeresis . "Ae")
                       (odiaeresis . "oe") (Odiaeresis . "Oe")
                       (udiaeresis . "ue") (Udiaeresis . "Ue")))

     x-symbol-charsym-ascii-groups
          By default, ``Ascii''fying accented characters means removing the accents.  Other characters have built-in Ascii representation, e.g, sigma1 has the Ascii representation sigma.

X-Symbol Package Information
============================

M-x x-symbol-package-info
     Read documentation for package X-Symbol in the info system.

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

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

x-symbol-installer-address
     E-mail address of the person who has installed package X-Symbol system-wide (see System-wide Installation).

x-symbol-package-url
     URL of package X-Symbol, used by x-symbol-package-web.

Supported Token Languages
*************************

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

Pseudo Token Language ``x-symbol charsym''
==========================================

If no (or an invalid) token language is set for a buffer, the info in the echo area (see Info) for a X-Symbol Character in the buffer (if it exists) uses the name of its charsym.  In this manual, we actually refer to X-Symbol characters by their charsym name, e.g., 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 (see Input Method Grid) also offers to insert a charsym name.  Charsyms can also be used for input method Read Token, see Input Method Read Token.

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

Token Language ``TeX macro'' (tex)
==================================

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

Basics of Language ``TeX macro''
--------------------------------

The standard behavior can be controlled by the following variables:

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

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

          \usepackage[ENCODING]{inputenc}
          %& -translation-file=iENC

     where ENCODING should be one of latin1, latin2, latin3, latin5, or latin9, and ENC should be one of l1 or l2.  8bit characters are not encoded if the file if the search was successful (see Controlling 8bit Coding).

x-symbol-tex-coding-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 TeX-master, also search in the file denoted by that value for the strings. (Buffer-local variables will not be inherited.)

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

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

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.

x-symbol-tex-electric-ignore
x-symbol-tex-electric-ignore-regexp
     Input method Electric (see 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 texmathp, see LaTeX Packages). Postfix tilde is not electric, because ~ produces a space in TeX.

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

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

Super-/Subscripts and Images in LaTeX
-------------------------------------

The display of super- and subscripts (see Super and Subscripts) is controlled by:

x-symbol-tex-font-lock-limit-regexp
     The superscript command ^ and the subscript command _ 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.

x-symbol-tex-font-lock-allowed-faces
     The characters ^ and _ are not always commands (see TeX Macro Problems), e.g., in the argument of \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: FAQ No Subscripts, FAQ Stupid Subscripts.  Using texmathp (see LaTeX Packages) has even more problems:

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

       - With own LaTeX environments, you would need to customize texmathp.

       - It is actually wrong: whether ^ and _ 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 \ref).

The display of images (see Images) is controlled by:

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

          \input{FILE.pstex_t}
          \includegraphics[OPTIONS][OPTIONS]{FILE.EXT}
          \includegraphics*[OPTIONS][OPTIONS]{FILE.EXT}
          \epsfig{file=FILE.EXT,OPTIONS}
          \psfig{file=FILE.EXT,OPTIONS}
          \epsfbox[OPTIONS]{FILE.EXT}
          \epsffile[OPTIONS]{FILE.EXT}

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

x-symbol-tex-image-searchpath
     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 TEXPICTS or TEXINPUTS (see TeX environment variables (Kpathsea Manual)), extended by ./ 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 (see Path sources (Kpathsea Manual)).

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 figures/ if the image should be cached in the memory cache.

Problems with TeX Macros
------------------------

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.  See 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:

  * The tokens in TeX are not ended by a dedicated character (like SGML entities are ended by ;).  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 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.

  * 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 Maß Bier. In the info file, you will probably not see any 8bit characters (the sharp s is shown as ß).

       - Many people would use Ma\ss\ Bier.  This is (almost ever) fine in text mode, but a \  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.

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

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

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

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

  * Around a dozen characters can be produced by more than one TeX macro, like \neq and \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 (see Unique Decoding).

  * 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 @ to a letter (used in LaTeX's style files), this character is considered a letter by X-Symbol.  This means that although both \ss @ and \ss@ usually produce the same output, only the first is decoded to ß@.

  * 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 LaTeX \verb command, and the verbatim and tabbing environments.

The Conversion of TeX Macros
----------------------------

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

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

The encoding of characters to TeX macros works as follows:

  * If the character is preceded by an odd number of backslashes, insert a space before the character.

  * Accented characters are encoded without braces, e.g., we encode ç to \c c.  Accents are encoded with braces, e.g., we use \c{ } and \u{}.

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

  * If the character is followed by a letter, replace the character by the macro and insert a space.

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

  * Otherwise, just replace the character.

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

  * If the macro is a text-mode macro and followed by {} which is followed by a blank, replace the macro and delete the braces.

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

       - If we have exactly one blank, the blank is a space, and it is not followed by a % (comment character), replace the macro by the corresponding character and delete the space.  (The character following the space must be a letter with unique decoding, see Unique Decoding.)

       - Otherwise, do not decode the macro!

  * Otherwise, just replace the macro.

To clarify, letter means A-Z, a-z, or @, 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: \ldots, \vdots, and (by accident) \angle. They are all treated like math-mode characters, but their minibuffer info (see Info) includes 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):

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

x-symbol-tex-env-verbatim-regexp
     The contents of the verbatim environment is not decoded.  To produce accented characters inside this environment, use the LaTeX package inputenc.sty.

x-symbol-tex-env-tabbing-regexp
     Inside a tabbing environment, the macro sequences starting with \`, \', \= and \- are not decoded.  It is probably better (with or without X-Symbol) to use the LaTeX package inputenc.sty or to the Tabbing environment, to be found in the CTAN archives.

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.

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

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

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

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

Extra Symbols of Language ``TeX Macro''
---------------------------------------

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 (see Info) contains s.th. like PACKAGE.sty or user.  If you do not use the corresponding characters, you do not have to do anything, of course.

The TeX macros \Box, \Diamond, \leadsto, \Join, \lhd, \mho, \rhd, \sqsupset, \sqsubset, \unlhd, \unrhd, are defined in LaTeX package latexsym.sty:

     \usepackage{latexsym}

Note that these macros are also defined amssymb.sty.  Since the first four macros are defined differently (better) in latexsym.sty, it does make sense to load both LaTeX packages.

The TeX macros \boldsymbol, \circledast, \circledcirc, \circleddash, \digamma, \gtrapprox, \gtrsim, \lessapprox, \lesssim, \triangleq, \varkappa are defined in AMS LaTeX package amssymb.sty:

     \usepackage{amssymb}

The TeX macros \bigsqcap, \llbracket, \rrbracket, \llparenthesis, \rrparenthesis are defined in the LaTeX package stmaryrd.sty:

     \usepackage{stmaryrd}

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

     \usepackage[T1]{fontenc}

The TeX macro \mathmicro for U00B5 can be defined by (see Wishlist LaTeX):

     \let\mathmicro\mu

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

     \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{::}}

The TeX macros \textordfeminine, \textordmasculine, \textdegree, \textonequarter, \textonehalf, \textthreequarters, \mathonesuperior, \mathtwosuperior, \maththreesuperior, \textcopyright are only defined when using LaTeX package inputenc.sty:

     \usepackage[latin1]{inputenc}

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

     \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}

Token Language ``SGML entity'' (sgml)
=====================================

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

Basics of Language ``SGML entity''
----------------------------------

The standard behavior can be controlled by the following variables:

x-symbol-sgml-modes
x-symbol-sgml-auto-style
     The variables known from Minor Mode.  If the buffer uses a HTML mode, super-/subscripts and images are displayed, otherwise unique decoding (see Unique Decoding) will be used.

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

          <meta http-equiv="content-type"
                content="text/html; charset=ENCODING">

     where ENCODING should be one of iso-8859-1, iso-8859-2, iso-8859-3, iso-8859-9, or iso-8859-15.  8bit characters are not encoded if the file if the search was successful (see Controlling 8bit Coding).

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

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

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

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

x-symbol-sgml-class-alist
x-symbol-sgml-class-face-alist
     Token classes (see 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 (see Input Method Grid and the character info (see Info), dark red for characters without defined entity names in HTML (see SGML Entity Conversion).

Super-/Subscripts and Images in HTML
------------------------------------

The display of super- and subscripts (see Super and Subscripts) is controlled by:

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

The display of images (see Images) is controlled by:

x-symbol-sgml-image-keywords
     The following commands are recognized.  Extension EXT stands for gif, png, jpeg or jpg.

          <img ... src="FILE.EXT" ...>

x-symbol-sgml-master-directory
x-symbol-sgml-image-searchpath
     Relative file names (see Image Display) are relative to the directory of the current file.

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

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 images/ or pictures/ if the image should be cached in the memory cache.

The 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 http://www.w3.org/TR/REC-html40/sgml/entities.html.

By default, we encode to entity references like &amp;, and decode from both entity references and character references like &#38;. For Latin-N characters without defined entity names in HTML (e.g. 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 sgml by changing:

x-symbol-sgml-token-list
     A symbol, which defines whether to use entity references, character references, or entity references for Latin-1 characters and character references for others.

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:

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

Token Language ``BibTeX macro'' (bib)
=====================================

For buffers using the major mode bibtex-mode, we use token language BibTeX macro (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:

x-symbol-bib-modes
x-symbol-bib-auto-style
     The variables known from Minor Mode.  There is no automatic deduction of the file encoding, 8bit characters are usually encoded, and there is usually no unique decoding.  See Conversion.

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

The input methods and most features except super-/subscripts and images work like in token language tex (see TeX Macro):

x-symbol-bib-header-groups-alist
x-symbol-bib-electric-ignore
x-symbol-bib-class-alist
x-symbol-bib-class-face-alist
     Like in TeX Macro Features.

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

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

x-symbol-bib-user-table
x-symbol-tex-user-table
     Use the former for bib-only changes, the latter also influences the conversion with token language tex.

Token Language ``TeXinfo command'' (texi)
=========================================

For buffers using the major mode texinfo-mode, we use token language TeXinfo command (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:

x-symbol-texi-modes
x-symbol-texi-auto-style
     The variables known from Minor Mode.  There is no automatic deduction of the file encoding, 8bit characters are usually encoded, and there is usually no unique decoding.  See Conversion.

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

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

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

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

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

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

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

At least with makeinfo-4.0, you do not get accented characters in the info file for the corresponding TeXinfo commands in the .texi file, the HTML output might contain illegal ``SGML entities'' like &140;.

At least with texi2html-1.62, you see accented characters in the HTML output for the corresponding TeXinfo commands in the .texi file, but the output might also contain illegal ``SGML entities'' like &140;.

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

x-symbol-texi-user-table
     Extra entries for the conversion.

Languages Defined in Other Emacs Packages
=========================================

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

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

  * Package ProofGeneral (http://proofgeneral.inf.ed.ac.uk/) defines token language ``Isabelle symbol''.

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 binary package which contains pre-compiled files.  X-Symbol developers should use the source package which contains some additional files.

Internal Representation of X-Symbol Characters
==============================================

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

  * Under Emacs and XEmacs/Mule, the string only contains the character which is a normal Mule character created by make-char.

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

          (get 'Idotaccent 'x-symbol-cstring)
               => "\235\251"

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

     (get 'Idotaccent 'x-symbol-file-cstrings)
          => (iso-8859-9 "\335" iso-8859-3 "\251")
     (get 'Idotaccent 'x-symbol-buffer-cstrings)
          => (iso-8859-9 "\234\335" iso-8859-3 "\235\251")

The values are plists (see Property Lists (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 x-symbol-tokens (see Token Language) and x-symbol-classes (see Char Group):

     (get 'Idotaccent 'x-symbol-tokens)
          => (sgml "&#304;" tex "{\\.I}")
     (get 'Idotaccent 'x-symbol-classes)
          => (sgml (non-l1) tex (text aletter))

Defining X-Symbol Charsets
==========================

An X-Symbol charset, called cset in the code and the docstrings, handles one font used by package X-Symbol.  Each cset must use the same char registry-encoding as the corresponding variables for the fonts (see 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.

     (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 ?\;)))

Mule charsets (see Charsets (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: : and ;).  The remaining free (reserved by Emacs for users) are > and ?, the latter is already used in XEmacs.

For XEmacs/no-Mule, you have to define the leading character (this example: \233).

x-symbol-latin1-cset
x-symbol-latin2-cset
x-symbol-latin3-cset
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 File Coding.

x-symbol-xsymb0-cset
x-symbol-xsymb1-cset
     Cset definitions using both halves of the fonts where no corresponding Mule charset are yet known.

Defining Input Methods
======================

This is probably the hardest section in this manual....

Defining Input Methods: Objectives
----------------------------------

Input methods should be intuitive.  This requires consistency:

  * Characters should be found under the same header in the Grid and in the Menu.

  * If one character can be modified or rotated to another character (see Input Method Context), both should stand near to each other in the Grid.  E.g., since arrowsouthwest rotates to arrowdown, they stand next to each other.

  * 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., reflexsubset with key binding C-= < _ 2 modifies to reflexsqsubset with key binding C-= < _ 3.

  * 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.

  * It should be possible to load character definitions later on, e.g., when new token languages get initialized.

       - 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 1).

       - Also, modifying or rotating a new character to/from old ones should be possible without changing the input definitions of the old characters.

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 define-key.  The solution is an indirect definitions with ``character descriptions''.

X-Symbol Character Descriptions: Example
----------------------------------------

As an example for ``character descriptions'', look at the definition of longarrowright in x-symbol-xsymb1-table (95 is the encoding in the font and not of interest here).  Some terms are defined in the next section:

     (longarrowright 95
      (arrow) (size big . arrowright) nil ("->" t "-->") (emdash))

With this definition, package X-Symbol automatically defines:

  * Key bindings C-= - - > and C-= - > 2, the latter has suffix 2, because C-= - > is also ``wanted'' by arrowright which now has the key binding C-= - > 1 (the ``score'' of longarrowright is higher, due to size big).  See Input Method Keyboard.

  * arrowright modifies to longarrowright, which modifies to arrowright.  See Input Method Context.

  * longarrowleft rotates to longarrowright, which rotates to longarrowboth (which rotates to longarrowleft).  (The ``rotate aspects'' are inherited from arrowright.)  See Input Method Context.

  * The following contexts can be modified to longarrowright: --> or minus1 / endash / macron / emdash / hyphen and -> (since all define context -) and emdash and > (since emdash defines context --).  -> is used for arrowright, which has a lower score, see above.  See Input Method Context.

  * Input method Electric will change context --> (is tagged with t in the definition) to longarrowright, also emdash and > (only theoretically, since input method Electric will produce emdash only in TeX's text mode, and longarrowright only in TeX's math mode).  See Input Method Electric.

  * The character will appear in the Grid under the header Arrow. You will probably recognize that the placement is based on the modify-to and rotate-to behavior above.  See Input Method Grid.

  * The character will appear in the Menu under one of the headers Arrow N".  The submenus are sorted alphabetically. See Input Method Menu.

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....

Defining Input Methods by Character Descriptions
------------------------------------------------

Characters are defined with character descriptions which consist of different aspects and contexts, which can also be inherited from a parent character.  All characters which are connected with parents, form a 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 M-x hyper-apropos-get-doc) of the corresponding charsym, e.g., arrowright.  See also the docstrings of x-symbol-init-cset and x-symbol-init-input.

Remember, all characters which are connected with parents, form a component.  Contexts are the contexts of input method Context (see 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 modify context of a charsym is the first context.

x-symbol-rotate-aspects-alist
     Characters in the same component whose aspects only differ by their direction (east,...), a key in this alist, are circularly connected by ``rotate-to''.  The sequence in the rotate chain is determined by rotate scores depending on the values in the rotate aspects.  Charsyms with the same ``rotate-aspects'' are not connected (charsyms with the smallest modify scores are preferred).

          (get 'longarrowright 'x-symbol-rotate-aspects)
               => (-1500 direction east)

x-symbol-modify-aspects-alist
     Characters in the same components whose aspects only differ by their size (big,...), shape (round, square...) and/or shift (up, down,...), 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 modify chain is determined by modify scores depending on the values in the modify aspects, the charsym score defined in the definition tables and the score of the whole cset (see Defining Charsets).

          (get 'longarrowright 'x-symbol-score)
               => -3500
          (get 'longarrowright 'x-symbol-modify-aspects)
               => (1500 shift nil shape nil size big)

     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 horizontal chain whose charsyms are circularly connected by ``modify-to''.

     We build a 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.

x-symbol-key-suffix-string
     If there is only one charsym in the key chain, 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.  C-= plus the context plus the suffix inserts the charsym.

Defining Input Methods: Example
-------------------------------

     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'       -

Assuming that all charsyms form one component, we have:

     Rotate chains:     (1w,2w)-1e-1n and 3w-(2e,3e)-2n.
     Modify chains:     1w-2w-3w and 1e-2w-3w and 1n-2n.
     Horizontal chains: 1e-1w-2e-3e       (for modify context a)
                        2w-3w             (for modify context b)
     Key chains:        1e-1w-2e-3e       (for context a)
                        1e-2w-2e-3w       (for context b)
                        1n-1w-2n          (for context c)
                        1n                (for context d)

That makes the following bindings:

     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     (horizontal chain)
                2w->3w, 3w->2w                     (horizontal chain)
                1n->2n, 2n->1n  (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

Customizing Input Methods
-------------------------

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.

x-symbol-group-input-alist
     Defines default scores and bindings for characters of a group (see Char Group).  E.g., the definition (in x-symbol-latin1-table)

          (aacute 225 (acute "a" Aacute))

     defines aacute without any explicit contexts, but having the group acute and the subgroup a.  The default input for the group is defined by the following element in this variable:

          (acute 0 "%s'" t "'%s")

     That means: 0 is added to the normal ``modify-score'' of the character. %s' and '%s with %s substituted by the subgroup, i.e., a' and 'a, are the contexts for aacute.  The context 'a is also used for input method Electric since it is prefixed by t.

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 C-= KEY to C-= KEY 1, it is required that the length of the key binding without C-= is at least 2.

Extending Package 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.

Extending X-Symbol with New Fonts
---------------------------------

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 CHARSET_REGISTRY and 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, see 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.

  * In general, escape sequences use the digits of the current font.  Thus, you should probably define the encodings 48 to 57 as digits 0 to 9.

  * In LaTeX buffers, characters in $%\{} 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 tex and utex.

  * In HTML buffers, characters in &<> 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 sgml.

You have to tell package X-Symbol which fonts to use for the normal text, subscripts and superscripts.  See 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. See Defining Charsets.

Guidelines for Input Definitions
--------------------------------

Read section Defining Input Methods.  Look at the tables in x-symbol.el.  Here are some guidelines of how to define the input methods for new characters:

 1. Define reasonable character groups for new characters, see 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.

 2. 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.  See Char Group.

 3. If reasonable, define default contexts for characters of a group, see Customizing Input Methods.

 4. For the other characters, define contexts by Ascii sequences which look similar to the character.

 5. 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 Char Descriptions.

 6. Use aspects to describe the new characters.  Add new aspects to x-symbol-modify-aspects-alist and x-symbol-rotate-aspects-alist if necessary (see Char Descriptions).

 7. Finish the definition of your font file (see Font Definition File), load it with M-x load-file, and initialize the input methods, e.g., by invoking the grid (M-x x-symbol-grid).

 8. 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.

      a. 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.

      b. Define reasonable scores for newly defined aspects and character groups.

      c. Finally, fine-tune your definitions by charsym scores in the tables. This should be necessary only for a few characters.

Emacs Lisp File Defining a New Font
-----------------------------------

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:

     (provide 'x-symbol-myfont)

     (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")))

     (defvar x-symbol-myfont-cset
       '((("xsymb-myfont") ?\200 1000)
         (myfont-left "My font characters, left"  94 63) . nil))

     (defvar x-symbol-myfont-table
       '((longarrownortheast 33 (arrow) (size big . arrownortheast))
         (koerper 34 (setsymbol "K"))
         (circleS 35 (symbol "S") nil nil "SO")))

     (x-symbol-init-cset x-symbol-myfont-cset x-symbol-myfont-fonts
     		      x-symbol-myfont-table)

Due to an XEmacs bug with char syntax inherit, you should also add the following line to files x-symbol-xmas20.el and x-symbol-xmas21.el:

       (modify-syntax-entry ?\200 "\\" (standard-syntax-table))

Emacs Lisp File Extending a Token Language
------------------------------------------

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 utex inherits most variables from tex, see x-symbol-utex.el.

A language must define variables for all language aspects, see Language Internals.  Our example defines a language mytex using the additional characters from Font Definition File.

First, you have to register the language in a startup file:

     (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)

The language definition file should look like (leaving out most parts which are similar to the ones in x-symbol-utex.el):

     (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)

     (defvar x-symbol-mytex-user-table nil)

     (defvar x-symbol-mytex-myfont-table
       '((longarrownortheast (math arrow user) "\\longnortheastarrow")
         (koerper (math letter user) "\\setK")
         (circleS (math ordinary amssymb) "\\circledS")))

     (defvar x-symbol-mytex-table
       (append x-symbol-mytex-user-table
               '(nil)
               x-symbol-mytex-myfont-table
               x-symbol-tex-table))

It is important that you do not define a variable for the language access x-symbol-font-lock-keywords, but rather use the variable of the parent language directly, see Language Internals.

During the testing phase, you should probably leave out the '(nil) which prevents warnings about redefinitions for the following elements.

Emacs Lisp File Defining a New Token Language
---------------------------------------------

You might also want to define a new token language not based on another language.

As an example, consider a token language ``My Unicode'' (myuc) for buffers with major mode myuc-mode.  Thus, we register the language by:

     (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)

Each token if language myuc consists of # 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 # is represented by the token ##.  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 (x-symbol-myuc.el) is included in the source distribution of package X-Symbol.

     (provide 'x-symbol-myuc)
     (defvar x-symbol-myuc-required-fonts nil)
     (defvar x-symbol-myuc-modeline-name "myuc")

     (defvar x-symbol-myuc-class-alist
       '((VALID "My Unicode" (x-symbol-info-face))
         (INVALID "no My Unicode" (red x-symbol-info-face))))

     (defvar x-symbol-myuc-font-lock-keywords nil)
     (defvar x-symbol-myuc-image-keywords nil)
     ...

     (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)

     (defun x-symbol-myuc-default-token-list (tokens)
       (list (format "#%X" (car tokens))))

     (defvar x-symbol-myuc-token-list 'x-symbol-myuc-default-token-list)
     (defvar x-symbol-myuc-user-table nil)

     (defvar x-symbol-myuc-xsymb0-table
       '((alpha () 945) (beta () 946)))

     (defvar x-symbol-myuc-table
       (append x-symbol-myuc-user-table x-symbol-myuc-xsymb0-table))

     ...

Various Internals
=================

Tagging Insert Commands for Token and Electric
----------------------------------------------

Input methods Token (see Input Method Token) and Electric (see Input Method Electric) stop their auto replacement if you use a command which is not an insert command.

self-insert-command
newline
newline-and-indent
reindent-then-newline-and-indent
tex-insert-quote
TeX-insert-quote
TeX-insert-punctuation
TeX-insert-dollar
sgml-close-angle
sgml-slash
     These commands and commands aliased to these are recognized as input commands by having a non-nil value of its symbol property x-symbol-input.

Avoiding Hide/Show-Invisible Flickering
---------------------------------------

Starting a command makes a previously revealed super- or subscript command (see Super and Subscripts) invisible again.  Repeatedly invoking commands which moves the point just by a small amount can lead to some flickering.

forward-char
forward-char-command
backward-char
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 (1+ and 1-) as the value of its symbol property x-symbol-point-function which returns the position ``after'' when called with the position ``before''.

Design Alternatives
===================

This section describes potential design alternatives and why they were not used.

Alternative Token Representations
---------------------------------

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 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:

  * The editing commands would work on the tokens which are invisible for the user.

  * 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!

  * 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 lazy-shot!

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:

  * You cannot adopt SGML to this approach.

  * You cannot read normal LaTeX files directly, you do not write normal LaTeX files.

  * You would have different TeX versions: one for X-Symbol with Emacs and XEmacs/Mule, one with XEmacs/no-Mule.

  * If you are not an extremely good TeX hacker, it would be impossible to adopt this approach to support more than 256 characters.

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:

  * Problems with current search/replace commands.

  * Problems with the current version of font-lock (it should never overwrite the font property for this character, even if the character matches some MATCH in font-lock-keywords and OVERWRITE is non-nil).  This gets even more difficult with superscripts/subscripts.

  * 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., \leftrightarrow and \approx would be delimiters.

Alternative Ways to Turn on X-Symbol Globally
---------------------------------------------

This package hooks itself into 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:

  * The installation is more complicated.

  * Local variables in files are not yet processed (this was the main reason not to do it this way).

Another possibility would be to hook X-Symbol into 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 find-file-hooks, especially with the function hooked in by font-lock.

Alternative Auto Conversion Methods
-----------------------------------

Without package crypt, this package automatically decodes tokens when turning on the minor mode (in hack-local-variables-hook, see Alt Global Mode) or in after-insert-file-functions.  This package automatically encodes characters in write-region-annotate-functions.  The disadvantage is that the possibility to change buffers in write-region-annotate-functions is not official (see Wishlist Emacs), i.e., not mentioned in the docstring (only mentioned for corresponding encode-functions of package format which use a similar loop in the C code).

With package crypt, this package automatically decodes tokens when turning on the minor mode.  This package automatically encodes characters in write-file-hooks.  The disadvantage is that the encoding is slower (use jka-compr instead crypt) and the problem with vc-next-action (see Spurious Encodings).

Without package crypt, Version 2.6 of this package automatically encoded characters in write-file-data-hooks.  The advantage was that changing buffers there is official, the disadvantage is that it is also more complicated.

A totally different method would be to use package format. Unfortunately, this is not really possible, since a REGEXP in 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 jka-compr and crypt.

Language Internals
==================

In order to use a token language or accessing one of the language dependent values, the following conditions must be met:

  * The language must be 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 x-symbol-language.

     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.

  * The file providing the language must have been loaded.  This will be done automatically when the language is initialized.  Customizing X-Symbol will also load the language files.

  * The language must be 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 (see Input Method Grid), you should initialize the language explicitly, e.g., by the following command:

     M-x x-symbol-init-language-interactive
          Initialized a token language if it is not already initialized.

Language dependent values are accessed by language accesses:

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 x-symbol-name.  With a simplified expansion, we get

          (x-symbol-language-value 'x-symbol-name 'tex)
               ==> (symbol-value (get 'tex 'x-symbol-name))
               => (symbol-value 'x-symbol-tex-name)
               => "TeX macro"

x-symbol-language-access-alist
     List of all language accesses.  A token language must define all variables accessed by language accesses.  A 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 utex, the language access x-symbol-font-lock-keywords, should point directly to the variable of the parent language (here tex), see file x-symbol-utex.el.

Miscellaneous Internals
=======================

TODO.  This is currently just a collection of unrelated stuff.

Characters might also define a subgroup which is a string defining some order on characters in the same group (see Char Group) and is also used for default contexts/bindings (see Customizing Input Methods).

x-symbol-group-syntax-alist
     Lists all valid character groups.  Under Emacs and XEmacs/Mule, this list also determines the syntax of characters.

The character group could probably also be used to define character categories if they are implemented in XEmacs.

Problems, Troubleshooting
*************************

This section is based on a successful installation of package X-Symbol. See Checking Installation.

Problems under XEmacs/no-Mule
=============================

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 ``poor man's Mule'', see 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):

  * If font-lock is not prepared to display these two-character sequences, i.e., if you installation is incomplete (see Role of font-lock), they look like \233a instead alpha.

  * Commands which add more than one entry to the buffer-undo-list and involve X-Symbol characters might lead to strange results, e.g. C-t (transpose-chars) with point between character alpha and b, leads to betaa.  Simple deletion and insertion works OK, though.

  * Selecting or inserting a rectangle with X-Symbol characters on the left or right margin might not work properly.

  * Be careful with M-% (query-replace): the first character of FROM-STRING can probably match the second of the two ``internal'' characters of an X-Symbol character.

  * If you use C-x ' (expand-abbrev) without M-' (abbrev-prefix-mark) and the last word before point starts directly after a X-Symbol character, C-x ' could behave strange:

       - If words-include-escapes is t, there will be no expansion.

       - If words-include-escapes is 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.

  * 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 (C-g). Unfortunately, XEmacs (as opposed to Emacs) does not run the hooks in post-command-hook in these cases.  Solution: move point right (C-f).

  * If you provide prefix arguments to commands, they are likely to consider just ``internal'' characters.  E.g., C-u 2 C-f before alpha behaves like C-f.

  * Column position considers ``internal'' characters, e.g., C-n might jump to an unexpected position (well, typically just one character left/right from the expected position, if at all).

  * Auto-filling also considers ``internal'' characters, i.e., might break the line too early.

  * There are no syntax definitions for the new characters, e.g., M-C-f before floorleft does not move to the closing floorright.

  * In some cases, e.g., when using the minibuffer for input via M-% or C-s, the internal representation of X-Symbol characters (see Char Representation) are displayed directly (see FAQ Strange Chars)

Spurious Encodings
==================

In rare cases, some commands (mostly from package 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.

  * Doing the next logical version control operation (C-x v v and friends) encode characters to tokens when using package crypt.

     Solution: use package jka-compr instead crypt (this is recommended anyway, see File IO Packages).  Or kill the buffer and revisit the file.

  * When using AucTeX with its default-mode algorithm, getting rid of the recently checked-in version of a file without reverting the buffer afterwards (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 \233a.

     Explanation: when using AucTeX's TeX-default-mode, the final major-mode is different from the initial major-mode deduced using auto-mode-alist.  If this is the case, the VC command executes normal-mode which kills all local-variables including turning-off x-symbol-mode.

     Solution: Turn on X-Symbol mode or change auto-mode-alist to directly choose latex-mode:

          (push '("\\[tT]e[xX]\\'" . latex-mode) auto-mode-alist)

  * When using AucTeX with its default-mode algorithm, writing a LaTeX 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 AucTeX's TeX-default-mode, we get the problems as described in the previous item.

     Solution: Set change-major-mode-with-file-name to nil or use the solution from the previous item.

The Encoding Does Not Work
==========================

In a rare case, X-Symbol cannot do its encoding, i.e., convert the characters to tokens.

  * M-x write-region fails to do the encoding if you use package crypt.

     Explanation: with package crypt, the encoding has to be done by a function in write-file-hooks which is not used by write-region.

     Solution: use package jka-compr instead crypt (this is recommended anyway, see File IO Packages).  Or visit the region file and save it again via C-x C-s.

Frequently Asked Questions
==========================

It is assumed that you had successfully installed package X-Symbol, see Checking Installation.

XEmacs Crashes when using 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 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 x-symbol-xmas-warn-about-core to 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 newest version of XEmacs (please put me in the CC).

X-Symbol's Fontification does Not Work
--------------------------------------

In this case, super- and subscripts are not properly displayed (see FAQ No Subscripts) and under XEmacs/no-Mule, the buffer contains s.th. like \233a (see FAQ Strange Chars). Possible causes:

  * You have turned off font-lock or font-lock is out of sync. Use M-x x-symbol-fontify.  See Role of font-lock.

  * The font-lock keywords of the current buffer are not prepared to display X-Symbol characters.  See Role of font-lock.

  * You use package fast-lock.  Solution: set fast-lock-save-faces to nil (done by default installation).

  * You use some version control commands.  You have probably noticed that these versions control commands also turn off font-lock in modes where you don't use X-Symbol, i.e., this is not a problem of package X-Symbol.  See Wishlist Emacs.  See Spurious Encodings.

The Buffer Contains Strange Characters
--------------------------------------

If you see s.th. like \233a, you see the internal representation of X-Symbol characters under XEmacs/no-Mule (see Char Representation) directly.  Possible causes:

  * You have font-lock problems, see FAQ font-lock.

  * More complicated editing commands like C-t may produce strange character sequences which do not represent X-Symbol characters, see Nomule Problems.

  * In some cases, e.g., when using the minibuffer for input via M-% or C-s, it would be too much work to fontify these character sequences in order to display proper X-Symbol characters.  See Nomule Problems.

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 adobe-fontspecific, but in fact uses another encoding.  E.g., Mathematica's fonts cause the characters intersection and union to mix up.  Possible solutions:

  * Delete that font from the font path.  Maybe moving it at the end also works.

  * 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

          (setq face-ignored-fonts '("\\`-wri-math1"))

  * 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.

I Cannot See any/some Super- or Subscripts
------------------------------------------

If you cannot select Super-/Subscripts in the menu, the first of the following points is more likely the cause, the others otherwise.

  * You have font-lock problems, see FAQ font-lock.

  * There are cases where super- and subscripts are not displayed, see Super and Subscripts.

  * The argument in braces are not correctly recognized, since the font-lock syntax-table is not correct.  It should include { as the only open parenthesis and } 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 font-lock package, but would require other changes there, therefore not likely to be fixed.  Fortunately, this does not happen often.

I See Super- and Subscripts where I Don't Want Them.
----------------------------------------------------

E.g., I see a subscript in arguments of \label.  Package X-Symbol only uses super- and subscripts if they are in braces, if the asciicircum/underscore has not been fontified yet or is only fontified with faces which are allowed by x-symbol-tex-font-lock-allowed-faces, see Super and Subscripts.

  * You use the default tex-font-lock-keywords: The argument of \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 font-latex, see below.

  * You use package font-latex.  Solution: set font-lock-maximum-decoration to value t, 2 or higher. Package X-Symbol will still use subscripts in \verb, in the verbatim environment, in the argument of \includegraphics and probably other commands.  Some of these problems will probably be solved by future versions of font-latex.

  * You use my font-lock keywords (file x-font-lock.el): everything should work fine.  Please note that this file is not meant to be a replacement of font-latex.el useful to all users.  Also, highlighting is a matter of taste, i.e., I am not going to change the x-font-lock.el to support LaTeX-2.09, TeX's math regions, other likings, etc.

  * 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.

The Characters are Too Small or Too Big
---------------------------------------

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).  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 (see Info) that you actually get the correct letter---they are just of different sizes. See 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.

The Conversion Changes Some Tokens
----------------------------------

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.  See Unique Decoding.

  * Solution: Do not redefine standard TeX macros or use unique decoding.

A Space is Added During the Encoding
------------------------------------

A space is added after some characters during the encoding to tokens. With token languages tex and utex (not with language sgml), there must be a space after the token to recognize its end in some cases.

E.g., if your buffer contains a+b (where + stands for the character circleplus), this is encoded to a\oplus b (note the space after \oplus).  Decoding it yields a+ b.

I admit, this looks ugly.  The space is only added if the symbol character is followed by a letter or by @.  Thus, decoding a\oplus\beta yields a+b (without space!).

  * Suggestion: Also use a space before \oplus.  The alternative would be to delete the space which other people won't like.

For an exact description, see TeX Macro Conversion for an exact description.

I Don't Want 8bit Characters in the File
----------------------------------------

By default, these are not encoded if the buffer-local variable x-symbol-8bits is non-nil.

By default, this variable is only set to non-nil, if something like

     \usepackage[latin1]{inputenc}

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. See File Coding.  Note: commenting the line is not enough!  (I do not run LaTeX to check for the line, I just do plain text search.)

I Cannot Distinguish Character hyphen from -
--------------------------------------------

In most fonts, the Latin character hyphen cannot be distinguish from the Ascii character -.  If you do not want to decode the corresponding token \- or &shy;, put the following into your ~/.emacs:

     (setq x-symbol-tex-user-table '((hyphen)))
     (setq x-symbol-sgml-user-table '((hyphen)))

A better alternative would be to make font-lock display these character in a different color.

Problems with Spell-checking
----------------------------

As explained in Miscellaneous Packages, 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 ispell-word and ispell-region.  Possible symptoms:

  * A word which contains letters which the program ispell does not know about is either not spell-checked or parts of it are spell-checked as independent words.

     Solution: Use the ispells 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 oe if you use a Latin-1 encoding.

  * Spell-checking might stop with the error message Ispell misalignment.  I can reproduce this only with Emacs, not with XEmacs.

     Question: If you know some settings (like for 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 flyspell.

The real solution would be to fix ispell, at least by providing a useful hook which allows X-Symbol to fix the problem.  See Wishlist Emacs.  You are strongly encouraged to send a patch to the maintainer of ispell, you even get a paragraph here in Acknowledgments!

How to Use X-Symbol with Gnus or VM
-----------------------------------

You can also use X-Symbol to read and write your News and Mails.  This sections includes coding for your ~/.emacs if you want to do so. It has been tested for Gnus-5.8.8 and VM-6.96; if you use RMAIL or 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.

     (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))))

This is optional (you might want to use the Custom interface for the same effect) and tells Emacs/X-Symbol to use token language tex and to display super-/subscripts (if font-lock is enabled), X-Symbol is not automatically turned on.  See Minor Mode.

     (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)

This tells tells Emacs to automatically turn off X-Symbol (which includes encoding characters to token) before actually sending the message.

     (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)

Since Gnus reuses the *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.

     (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)

The same thing for VM, although the hook is not as nice as Gnus' one; the function therefore might depend a bit too much on VM's interna.

     (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))

You cannot use X-Symbol in VM Mode, only in VM Presentation Mode (X-Symbol would change your INBOX).  The first (optional) Emacs Lisp expression gives you a better error message when you try to turn on X-Symbol Mode in VM Mode.  The second line makes sure that VM always uses VM Presentation Mode to display the articles.

How to Send a Bug/Problem Report
================================

Bug fixes, bug/problem reports, improvements, and suggestions are strongly appreciated.  So are corrections to this manual (better explanations, correcting my English, ...).  Especially useful would be some feedback by people using default fonts with a charset registry-encoding other than iso8859-1 (Western encoding).

Please read this section carefully, even if you generally know how to send a bug report (see Bugs (XEmacs User's Manual)). This might look tedious to you, but it actually saves a lot of time (your time, too).

The 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:

 1. Make sure that you use the newest version of X-Symbol.  You are reading Edition 4.5.1 (XEmacs) of the manual for X-Symbol 4.5.1.

 2. Read the manual, especially Checking Installation, Problems, and FAQ.  The four indexes (see Indexes) might also lead you to an answer to your question.

 3. Use M-x x-symbol-package-bug (also to be found in X-Symbol's Command submenu) to write your report describing one bug or problem, i.e., use different mails for 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' *mail* buffer to your mail tool.

     If 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 x-symbol VERSION; SUMMARY as Subject header where VERSION is the version of X-Symbol (it should be 4.5.1) and SUMMARY is a brief summary of your installation problem.

     (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.)

 4. Start your report with:

          In the manual, I checked the sections SECTION1, SECTION2, ..., but didn't find anything which helped me with the following problem:

     The sections SECTION1, 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.

     (Rationale: This way, I get an idea where to improve the manual, especially by adding cross references.)

 5. If buffer *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 X-Symbol is not mentioned there.  Otherwise, include the contents of buffer *Warnings* into your bug report.

     Temporary Emacs (< v21.4) note: the warnings might be somewhere hidden in buffer *Messages*; please check that buffer.

 6. Put the parts of the code from ~/.emacs and the system-wide files which causes the problem into a fresh file MY-PROBLEM.el. The problem/error should be visible when invoking

          xemacs -no-site-file -q -l MY-PROBLEM.el

     In the minimal case, MY-PROBLEM.EL just contains the following line (see Installing Lisp):

          (x-symbol-initialize)

     If the error has disappeared after you have included your complete ~/.xemacs/init.el and ~/.emacs, the problem is likely caused by some code of your system-wide installation.  Include the code, which can be found using command M-x find-library with files site-start and default (everything is fine if these files do not exist).

     If you use x-symbol-site.el (its use is deprecated), copy its contents into MY-PROBLEM.EL and delete the corresponding load command.

     Attach the file MY-PROBLEM.el to your report. Please try to minimize the size of MY-PROBLEM.el! A standard technique is recursive halving: Delete the second half of MY-PROBLEM.EL.  If the problem disappears, delete the first half instead.  Do the same with the smaller file again, ....

     (Rationale: Most problems are a consequence of some specific customizations, but I don't have time to debug each user's init file.)

 7. If you have set variable custom-file in MY-PROBLEM.el, attach the corresponding file to your report.

 8. If the error can only be reproduced in combination with another Emacs package, please send me:

       - 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 M-x find-library to check whether you really use the version from the Emacs/XEmacs distribution).

       - If it is a non-standard (and non-obscure) package: the URL of the distribution and/or the source.

       - Otherwise: include its code into MY-PROBLEM.el and delete the corresponding load or require command.  Then, reduce the size of MY-PROBLEM.el as described above.

 9. If the problem is not reproducible with an arbitrary (.tex, .html, ...) 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.)

     (Rationale: Most problems are only reproducible with specific files.)

 10. 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 C-x C-f FILE 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 C-h l and include the contents of buffer *Help* in your bug report.

     (Rationale: Most problems are only reproducible with point being at a specific position in the file, with specific key sequences, etc.)

 11. If you have problem with the display of images, please include the output of the shell commands convert -h and convert -list Format in your bug report.  If the first command fails, you have a problem with the program convert, not X-Symbol.

 12. If necessary, include a screen-shot in your bug report.

 13. If you could not use M-x x-symbol-package-bug, include the contents of buffer *Help* after the following actions:

       - Type C-h v x-symbol-version RET.

       - Type C-h v emacs-version RET.

       - Type C-h v features RET.

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 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.

History and Projects
********************

News: Changes in Recent Versions of X-Symbol
============================================

This is the complete history of X-Symbol.  It just lists the major changes before Version 3.0.

Changes in X-Symbol 4.5.1
-------------------------

Version 4.5.1 has not yet been announced.

  * Various bug fixes and minor changes.

Changes in X-Symbol 4.5
-----------------------

Version 4.5 has been released on March 2003 as beta.

  * X-Symbol finally respects the Mule coding system of each individual buffer.

  * Bug fix: would mess up encoding of math-mode characters with token language bib.  Other conversion fixes for languages bib and texi.

  * Bug fix (workaround for bug in XEmacs): auto-save files would have length 0.

  * Bug fix (Emacs): package now works with package crypt/crypt++.

  * Token language sgml: always encode characters to entity references by default (where defined by the HTML standard).  Include hm--html-mode, html-helper-mode, remove sgml-mode as typical major modes which use X-Symbol.

  * Token language tex: support some symbols of package stmaryrd.sty.

  * Change the auto-style, formerly auto-mode, mechanism.

  * Image support when running on Emacs.

  * New input method Quail, a usual Mule input method.

  * Corrected Latin-5 definitions.  Support Latin-5 (``Turkish'') on XEmacs running under Windows.

  * X-Symbol works with Emacs/XEmacs running under a character terminal.

  * Improments for external languages.  Super-/subscript matching of token languages has changed.

  * X-Symbol can use package format and does not require special fonts for super-/subscripts with Emacs-21.4+.  Still open whether this will be used....

  * Dropped support for XEmacs-20.3.

  * Various bug fixes and minor changes.

Changes in X-Symbol 4.2 to 4.4
------------------------------

Version 4.4 has been released on June 2002 as beta.

  * Token language TeX has changed: no excessive use of braces anymore, no excessive normalization, and aware of environments {tabbing} and {verbatim}, and macro \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.

  * New token language ``BibTeX Macro'' (bib, similar to old tex), used for BibTeX files.

  * Nuked executables, the Lisp conversion for all languages is now 2-5 times faster.

  * Latin-9 support.  Latin-9 font included in distribution.

  * 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.

  * 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 (TeX-master) with token language tex.

  * New buffer-local variable x-symbol-unique: when non-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 utex.

  * Menu changes, new commands: submenu ``Conversion'', menu items ``Copy Encoded'', ``Paste Decoded'' and others.

  * Special coding for preview-latex.  Using X-Symbol now only gives a 10% overhead of previews parsing time.

  * X-Symbol now works with WhizzyTeX.

  * The interface for defining a token language has changed, it is also much more general, useful for ProofGeneral.

  * Changed final bytes of ISO 2022 escape sequence for X-Symbol charsets since Emacs reserves the characters 0-9 for itself.  Does XEmacs has any policy here (it also uses ?)?

  * Dropped workaround for minor bug in XEmacs-20.X.

  * Various bug fixes and minor changes.

Changes in X-Symbol 4.1
-----------------------

Version 4.1 has been released on Mar 2002 as beta.

  * X-Symbol works with Emacs-21.1 or higher.  Porting is not complete, yet.

  * New token language ``TeXinfo command'' (texi).

  * Slightly different definition of ``valid character''.

  * Remove the ``local if set'' and ``default: ...'' submenu stuff.

Changes in X-Symbol 3.4
-----------------------

Version 3.4 has been released on Mar 2002.

  * Moved to SourceForge.net.  Added files for nicer HTML output of manual.

  * Would sometimes perform strange conversions when global-flyspell-mode is enabled.

  * Bug fixes: command 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).

  * Automatically deduce default coding via locale -ck LC_CTYPE.

  * Issue warning when running on XEmacs-21.0 to XEmacs-21.1.8.  Update manual: XEmacs user package directory is ~/.xemacs/packages.

  * Directories ending with // in image search paths are recursive.

  * New characters used for token languages ``TeX macro'' and ``Isabelle symbol''.

  * Make sure to convert just the first part of a multi-part image.

  * Source distribution includes files for building an RPM package, all files also compile without Mule support.

  * Minor changes.  Manual changes.

Changes in X-Symbol 3.3
-----------------------

Version 3.3 has been released on Jan 1999.

  * 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 M-x x-symbol-exec-create).

  * New functions used for interaction with Emacs package comint. This is necessary for new token language ``Isabelle symbol'', to be distributed with Emacs package ProofGeneral (http://proofgeneral.inf.ed.ac.uk/).

  * New characters used for token languages ``TeX macro'' and ``Isabelle symbol''.

  * Minor changes.  Manual changes.

Changes in X-Symbol 3.2
-----------------------

Version 3.2 has been released on Dec 1998.

  * 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 x-symbol-site.el is deprecated.

  * Reverting the buffer and using vc commands do not encode characters when not using crypt.  (This did not work always.)

  * Workaround for bug (segfault) in XEmacs-21/Mule betas.

  * Command x-symbol-package-bug is less restrictive.  Please use this command to contact the maintainer.

  * Bug fixes.  Minor changes.  Manual changes.

Changes in X-Symbol 3.1
-----------------------

Version 3.1 has been released on Oct 1998.

  * TeX macro \mu is represented by a character in the Adobe Symbol font, not in a Latin-{1,3,5} font anymore.

  * Support for most SGML entities in HTML-4.0 specification.

  * Additional characters for \therefore/&there4;, &oline; and &euro;.

  * Package X-Symbol has been customized.

  * The documentation has been completed (as TeXinfo file).

  * Handle special URL prefixes file:, http: for images.

  * Bug fixes, configuration changes.

Changes in X-Symbol 3.0
-----------------------

Version 3.0 has been released on Sep 1998 as beta.

  * Package X-Symbol now works on XEmacs with and without Mule support. Dropped support for XEmacs 19.13 to 19.16/20.2.

  * Full support of token language sgml (executables, subscripts, images).

  * X-Symbol is a proper minor mode.

  * Easier (automatic) 8bit character control (e.g., for \times \pm,...).  By default, the encoding when saving only writes 8bit characters, if \usepackage[latinN]{inputenc} with N=1,2,3,5 was found in the first 10000 characters of the file (including commentary).

  * 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

  * Key bindings have completely changed.  They are now consistent with the contexts of input method Context (which have changed a bit).

  * The keys @ and ! 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.

  * Input method Aggressive Context is now called input method Electric and is much more restrictive (using package texmathp with language ``TeX macro'').

  * Easier installation despite many additional features.

  * Supports more characters.

  * Nicer grid, info in echo area.

  * Better cooperation with packages: vc (check-out does not convert characters), reftex (no strange characters \237, help with label creation), auctex, ispell, font-latex (no annoyances with \exists).

  * Safer use of executables.

  * The code has completely changed.  You have to redo your installation.

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.

  * Fixed serious bug when used under tty.

Version 2.5 has been released on Mar 1998.

  * Image support.

Version 2.4 has been released on  Mar 1997.

  * Token language sgml.  (X-Symbol can handle more then token language tex.)

  * Input method Aggressive Context (precursor of input method Electric), input method Context has been much improved.

  * Fixed performance bug when saving a file with package crypt.

  * Control of Conversion and 8bit character has changed.

Version 2.3 has been released on Sep 1996.

  * Distributed with own font for more math characters.

  * Info for the character around point in echo area.

Version 2.2 has been released on June 1996.

  * Input method Grid.  Help when using input method Keyboard.

  * Control of Conversion and 8bit character has changed.

Version 2.1 has been released on April 1996.

  * Fixed serious performance bug when loading files with font-lock/lazy-lock.  Use executables for conversion of large buffers.

  * The package iso-cvt is not integrated anymore.  Now this package can also convert to/from Latin-1 characters, it is much faster.

  * Menu support, including input method Menu.

  * isearch works with X-Symbol characters.

  * First multi-file version.

Version 1.4 has been released on Feb 1996.

  * Provide some kind of ``poor man's Mule'' to remove most Nomule-Problems.

Version 1.3 has been released on Jan 1996.

  * Input method Abbrev (precursor of input method Token).

  * Super-/subscript support.

Version 1.2 has been released on Jan 1996.  It was the first release.

  * Conversion between characters and TeX tokens.  Do so automatically when visiting a file and saving the buffer.

  * Input method Keyboard.

Wishlist: Projects for X-Symbol
===============================

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 Open Questions.

Providing a solution to these problems is the second way of making your name appear in Acknowledgments.

Wishlist: Additional Token Languages
------------------------------------

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 (see Extending X-Symbol) for general-interest token languages (e.g., AmsTeX).

It is likely that this would require additional fonts: available fonts (e.g., IPA font), hand-crafted, or generated (see Wishlist Fonts).

Wishlist: Generated Fonts
-------------------------

A specific direction of font generation would be from .bdf or .pcf font files to Windows fonts to get rid of the limited support for XEmacs on Windows (see Requirements).  If you have successfully converted X-Symbol's fonts from the Unix format to the Windows format (via bdftofon or whatever) or if you have free and real Latin-N fonts for Windows, please 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 .bdf or .fon fonts from other sources.  This would have various advantages:

  * We could easily create different sizes for our symbol font.

  * It would be quite simple to create a font for AmsTeX macros, etc., which would be displayed as X-Symbol characters by package X-Symbol.

  * We could easily create different sizes for our symbol font.

  * We would have fonts for both X11 and Windows.

New fonts for X-Symbol are being worked on.  You can find material to generate them at the web pages of X-Symbol (http://x-symbol.sourceforge.net/news.html). 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 X-Symbol development mailing list (x-symbol-devel@lists.sourceforge.net).

General open design issues (i.e., they could be re-thought for the currently used handcrafted fonts, too) are:

  * Different TeX macros (same appearance, different TeX class = different spacing) use the same MetaFont character, e.g., \dagger and \dag.  Therefore, we need different X11 characters for them.

  * Some Ascii characters have a special meaning in TeX.  The corresponding MetaFont character is therefore produced by a TeX macro, e.g., { by \{. We need a X11 character which looks similar to the character but not exactly like it.

We could ask the question whether we should really distinguish the characters by appearance...we have the minibuffer info for the X-Symbol character anyway....  Here are the options:

  - distinguished by size/underlining/miscellaneous (currently used),

  - distinguished by different spacing (my current favorite),

  - not distinguished

Wishlist: Changes in Emacs/XEmacs
---------------------------------

Changes in Emacs and/or XEmacs would improve package X-Symbol, too:

  * In Emacs: a package system similar to XEmacs' one.  The installation would be easier.

  * The package 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 ispell (it will be better in Emacs-21.4), see Miscellaneous Packages.

  * Some versions control commands turn off font-lock.  This should be changed.

  * Provide a face property 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 font-lock set properties other than faces).  XEmacs: no such property, yet.

  * 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 latin-unity (see File IO Packages).

  * In Emacs, will be fixed in 21.4.  Using isearch and the input method Grid would not work.

  * In XEmacs, fixed in 21.X.  In after-insert-file-functions, there should be a possibility to get to know the start position of the region which is inserted.  If insert-file-contents is called with argument replace being non-nil, it is not always point.

  * In Emacs and XEmacs, will be fixed in Emacs-21.4.  Make possibility to change buffers in write-region-annotate-functions official, see Alt Auto Conversion, have a way to get the original buffer.

  * Since font-lock uses duplicable text properties in some cases, I need a function like insert-buffer-substring-without-extents. (Currently, I remove the extents afterwards, which looks slow for me.)

  * In XEmacs.  Run hooks in post-command-hook even if command exits with an error or quit (as it is in Emacs) or having some post-error-or-quit-hook.  See Nomule Problems.

  * In XEmacs.  There are some bugs in package custom/widget (still in XEmacs-21.4) which are visible during the customization of X-Symbol.

Wishlist: Changes in LaTeX
--------------------------

Changes in LaTeX, especially inputenc.sty, would improve package X-Symbol, too:

  * To make the definition of the character U00B5 consistent with Unicode, inputenc.sty should define the character to stand not for the token \mu (U03BC is the right character), but for an extra token, e.g., something like \textmicro.  X-Symbol uses \mathmicro here in order to avoid changing \mu to the character U00B5 if you have chosen to store 8bit characters.

  * Use same encoding for both text and math, i.e. use periodcentered for both \textperiodcentered (the default) and \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 \lnot, \pm, \times and \division: use \textonesuperior for U00B9, \texttwosuperior for U00B2, and \textthreesuperior for U00B3.

  * The TeX macros \textcent, \textcurrency, \textbrokenbar, \textyen are defined as not available with OT1 and T1 font encoding.  This should be changed.

Various Projects for X-Symbol
-----------------------------

The following suggestions seem to be useful, though not essential:

  * 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 ps-print.  A newer version of ps-print might be probably already capable of doing it.  Thus, you are encouraged to help the XEmacs team updating this package.

Rejected Suggestions for X-Symbol
---------------------------------

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:

  * It would be nice if X-Symbol would replace the token with the last character of the token if this is possible (see 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.

Open Questions
==============

This section lists some minor open questions.

  * Loading file x-symbol.el will initialize package X-Symbol (via function 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 x-symbol.el.  Thus, customizing package X-Symbol will not initialize package X-Symbol.

     The alternative would be to call function 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 x-symbol-initialize top-level in file x-symbol.el.  If I am wrong here, please let me know (with an explanation).  Batch-compilation might be an issue...

  * When is necessary to set x-symbol-auto-conversion-method to slowest?  Of course, it is only necessary when using crypt.  Is the other necessary condition to use the computer pool of the University of Edinburgh?

Acknowledgments
===============

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 Wishlist Fonts.  His work is now available at the X-Symbol download area.

Package 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 makesub is a merge and change of the scripts makesupers and makesub by Julian.

The font 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 frame-icon.

The idea for Help during an X-Symbol key sequence is from package x-compose.  The general idea for showing some info in the echo area is from package eldoc.  The trick which stops expand-abbrev is from package mail-abbrevs.  The idea for x-symbol-image-cache-directories is from package fast-lock.  The code for image command parsing is influenced by some code in package font-lock.  The code around x-symbol-image-delete-extents is based on some code in package bib-cite.

Thanks for patches/reports/suggestions to: 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öpl, 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ø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.

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:

       http://www.w3.org/TR/REC-html40/sgml/entities.html
       http://www.fmi.uni-passau.de/~ramsch/iso8859-1.html
       http://czyborra.com/charsets/iso8859.html
       http://www.bbsinc.com/iso8859.html
       http://www.bbsinc.com/iso8879.html
       http://ppewww.ph.gla.ac.uk/~flavell/charset/internat.html
       http://ppewww.ph.gla.ac.uk/~flavell/iso8859/iso8859-pointers.html
       http://sizif.mf.uni-lj.si/linux/cee/iso8859-2.html

I do not intend to update this list in the future---this is just an "Acknowledgment" section.

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 (see Bug Reports),

The links lead you to the manual sections describing X-Symbol's commands and variables.  See About.