X-Symbol Overview Related Details Manual News »Project »Download

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

2.1 Requirements  Which programs you need for X-Symbol.
2.2 Put the Files into your Home Directory  Basics 1: Put the files into your home dir.
2.3 System-wide Installation: Put the Files into the XEmacs Directory  Alternative: Put the files into the XEmacs dir.
2.4 Make XEmacs Initialize X-Symbol During Startup  Basics 2: Initialize X-Symbol during startup.
2.5 Installing the Image Converter from ImageMagick  Recommended: How to install convert.
2.6 Package Integration  How X-Symbol interacts with other packages.
2.7 Installing Additional Fonts  Optional: What to do when using other fonts.
2.8 Installing Fonts for Exceed (X-server on Windows)  If appropriate: What to do when using Exceed.
2.9 Lisp Coding when Using Other Fonts  If appropriate: Lisp coding for other fonts.
2.10 Installing Info, Postscript and HTML Files  Optional: How to create the manual.
2.11 Checking the Correct Installation of Package X-Symbol  Is package X-Symbol completely installed?

2.1 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, 8.4.1 XEmacs Crashes when using Input Method Token), 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 section 9.2.2 Wishlist: Generated 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 2.6.2 Syntax Highlighting Packages (font-lock and add-ons).

If you want to see the images at the end of image insertion commands, install convert from ImageMagick, see 2.5 Installing the Image Converter from ImageMagick. 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 section 2.10 Installing Info, Postscript and HTML Files.

2.2 Put the Files into your Home Directory

If you use Emacs, please check the web pages of X-Symbol.

In this section, we assume that you want to install the binary distribution (also called the binary tarball) of package X-Symbol in your home directory. To install it somewhere below the XEmacs root (it might be already there), see 2.3 System-wide Installation: Put the Files into the XEmacs Directory. 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.

2.3 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 2.2 Put the Files into your Home Directory. 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:

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.

If you have a local copy of the web pages (see section 2.10 Installing Info, Postscript and HTML Files), set this variable to the corresponding URL.

2.4 Make XEmacs Initialize X-Symbol During Startup

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


Basically, that's it! If your XEmacs runs on a different machine, check 2.7 Installing Additional 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, 2.1 Requirements), set the default coding (see section 3.2.1 Normal File and Default Encoding) 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:

By default, package X-Symbol does a full initialization. This includes an integration with some packages, see also 2.6 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))

2.5 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 section 5.2.2 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.

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

2.6.1 LaTeX Packages  Packages used in LaTeX buffers.
2.6.2 Syntax Highlighting Packages (font-lock and add-ons)  Package font-lock and support modes.
2.6.3 File I/O Packages  Compression, encryption, remote files, etc.
2.6.4 Miscellaneous Packages  Other packages.

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

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 section 3.2.2 File Coding of 8bit Characters) and when converting image files with relative names (see section 5.2.1 Display of Images).

  • 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 section 4.8 Input Method Electric: Automatic Context) with token language tex uses package texmathp.

  • AucTeX's math mode commands also inserts X-Symbol characters (see section `Mathematics' in 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.

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.

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.

Use Version 3.26 or higher. For a workaround for some minor annoyances with the combination RefTeX/X-Symbol/Multifile Document, see section `Problems and Work-arounds' in 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 section 5.4 Ascii Representation of Strings) by setting reftex-translate-to-ascii-function.

Use the newest.

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

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.

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 section 8.4.5 I See Super- and Subscripts where I Don't Want Them..

Is required by this package (see section 3.5 The 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.

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

Is strongly recommended.

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

See also efs and jka-compr.

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.

I recommend to use package jka-compr instead. See section 8.2 Spurious Encodings. See section 8.3 The Encoding Does Not Work. If you use crypt or crypt++ and the character alpha looks like `\233a' after save-buffer, set this variable to slowest. See section 9.3 Open Questions.

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

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.

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

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!

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 section 3.2.7 Character Aliases) and recoding (see section 3.2.2 File Coding of 8bit Characters). Has some safe-encoding mechanism, but the test comes currently too early (see section 9.2.3 Wishlist: Changes in Emacs/XEmacs).

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

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

2.6.4 Miscellaneous Packages

On XEmacs without Mule support, I recommend to set variable words-include-escapes to t. See section 8.1 Problems under XEmacs/no-Mule.

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

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.

Should work apart from the general problem of ispell.

Should work with X-Symbol.

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 9.2.3 Wishlist: Changes in Emacs/XEmacs. See section 8.4.11 Problems with Spell-checking.

Use a future version (hopefully v3.4). Includes special X-Symbol initialization/handling and defines additional token languages. See section 6.6 Languages Defined in Other Emacs Packages.

psgml-html: Do not set html-auto-sgml-entity-conversion to non-nil. See section 2.6.3 File I/O Packages, package iso-sgml.

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.

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 section 4.1 Common Behavior of All Input Methods.

2.7 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 section 9.2.2 Wishlist: Generated 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). You might need to check the permissions of the created files (see section 2.2 Put the Files into your Home Directory).

  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 section 2.9 Lisp Coding when Using Other Fonts.

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

2.9 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 section 3.5 The Role of font-lock).

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

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.

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

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 section 8.4.6 The Characters are Too Small or Too Big).

You might want to change the following variables:

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.

Package X-Symbol does not change the fonts of pre-defined Mule charsets (this can be changed by this variable). Thus, the variables from 2.9 Lisp Coding when Using Other Fonts might have no influence if Emacs already has defined fonts for the corresponding charsets.

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

2.11 Checking the Correct Installation of Package X-Symbol

After having completed the installation, exit and restart Emacs.

This document was generated by Christoph Wedler on December, 8 2003 using texi2html