1. 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 ™. It also provides various input methods to insert these characters. Thumbnails for included images and real super-/subscripts and are also supported.

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

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

1.3 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 7. 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 8.5 How to Send a Bug/Problem Report.