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

5.1 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 section 4.8 Input Method Electric: Automatic Context).

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 section 5.3 Info in Echo Area) 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 section 3.5 The 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 section 3.3 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.

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 section 6.2 Token Language "TeX macro" (tex)) and <sup>/<sub> (see section 6.3 Token Language "SGML entity" (sgml)):

5.2 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 section 2.5 Installing the Image Converter from ImageMagick). Using the middle mouse button invokes the image editor for the image under the mouse pointer.

5.2.1 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 section 3.3 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.

x-symbol-lang-image-keywords

The keywords (image commands & arguments) for each token language lang.

• 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:'.

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 section 6. Supported Token Languages).

5.2.2 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 5.2.3 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 section 2.5 Installing the Image Converter from ImageMagick). 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 section 5.2.3 Image Caching) since convert is slower when using a colormap.

5.2.3 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 section 6.2 Token Language "TeX macro" (tex)), or `images/' or `pictures/' (see section 6.3 Token Language "SGML entity" (sgml)). 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.

5.2.4 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 5.2.3 Image Caching.

• Junk: A recycle sign is displayed if there is no image converter (see section 5.2.2 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.

5.2.5 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 section 5.2.3 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 section 5.2.1 Display of Images).

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.

5.3 Info in Echo Area

The echo area (see section `Echo Area' in 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 section 4.7 Input Method Context: Replace Char Sequence).

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 section 3.6 Character Group and Token Classes),

infos using the token classes (see section 3.6 Character Group and Token Classes), 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 section 3.2.2 File Coding of 8bit Characters), and

the key bindings (see section 4.6 Input Method Keyboard: Compose Key Sequence).

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 section 4.7 Input Method Context: Replace Char Sequence). 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 3.6 Character Group and Token Classes.

x-symbol-idle-delay

Time in seconds of idle time before showing the info.

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

5.5 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 8.5 How to Send a Bug/Problem Report. 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 section 2.3 System-wide Installation: Put the Files into the XEmacs Directory).

x-symbol-package-url

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