Details of Package X-Symbol

1. Activating X-Symbol Mode
2. Characters and Tokens
3. Input Methods, Info in Echo Area (with screenshots)
4. Super- and Subscripts (with screenshot)
5. Thumbnails for Images (with screenshot)

Activating X-Symbol Mode

For X-Symbol to work in a buffer, there must be a token language which is appropriate for the buffer. If there is no appropriate token language, you are asked for the name of a token language to be used in that buffer. With the default installation, X-Symbol mode is automatically turned on for most buffers with an appropriate token language:

• For buffers using a LaTeX/TeX major mode (tex-mode, latex-mode, plain-tex-mode), we use token language tex (TeX macro). X-Symbol mode is automatically turned on if we visit a file with extension .tex.
• For buffers using an HTML major mode (html-mode, hm--html-mode, html-helper-mode, we use token language sgml (SGML entity). X-Symbol mode is automatically turned on if we visit a file.
• For buffer using a BibTeX major mode (bibtex-mode), we use token language bib (BibTeX macro) and X-Symbol mode is automatically turned on if we visit a file.
• For buffer using a TeXinfo major mode (texinfo-mode), we use token language texi (TeXinfo command) and X-Symbol mode is automatically turned on if we visit a file.

The language is mentioned in the modeline string if X-Symbol mode is turned on: e.g., XS:tex is the modeline string for buffers with token language tex.

Old releases: we used a token language tex for buffers in both LaTeX/TeX and BibTeX major modes. It was very similar to the token language bib, i.e., with surrounding braces for tokens representing text-mode characters.

Technical detail: the X-Symbol manual or the documentation of command x-symbol-mode, and for each token language lang, variable x-symbol-lang-auto-style.

Characters and Tokens

Package X-Symbol assumes that you are not really interested in the token for a character (the info in the echo area for a character includes the name of the token, though). Consequently, all editing operations really work on characters, not on the corresponding tokens for the token language of the current buffer. Except for special input methods (see below), the tokens only come into play when visiting and saving a file:

• If you copy the character ± from a LaTeX buffer to a HTML buffer, you really copy that character and not the three characters of the TeX macro \pm. This is also the case for the additional characters of X-Symbol, and is still true if you copy the character into a simple text or mail buffer. There are commands to copy a region encoded and paste&decode some text.
• Some characters are represented by more than one token. If you visit and save a file containing such tokens, the canonical token representation for the character is saved. E.g., with token language tex, visiting a file with tokens \neq and \ne converts both tokens to character ≠ (`notequal'), saving the buffer stores the character as token \neq in both occurrences.
• Some characters for tokens have a 8bit encoding in the file. If a file contains both the 8bit character and the token, saving the buffer normalizes the document to use either the 8bit character or the token. For details on 8bit characters, see below.

You can customize that you do not want to have any character/token normalization: in this case, you only decode the tokens which are canonical (and not represented by 8bit characters of the current 8bit encoding). This is by default used for LaTeX/TeX style files.

Old releases: the normalization for LaTeX/TeX files was a bit excessive and you could not really prevent this, except when using a token language utex, which has been discarded.

X-Symbol supports characters in the Latin-1, Latin-2, Latin-3, Latin-5 font, and Latin-9. Some characters are defined in more than one of these fonts, but are meant to be the same character, having the same Unicode mapping, and correspondingly, the same token representation. Unfortunately, Emacs does not see it that way and treats them as different.

• X-Symbol unifies these characters again: you can insert just one ä, and the conversion when visiting or saving a file produces the same ä. If possible, it uses the version according to your default encoding.
• You can visit files with an encoding which is different to your default encoding / the buffer file coding recognized by Mule. This is mentioned in the modeline string, e.g., you see XS:tex8-l2 if you visit a file with Latin-2 encoding and you default encoding is not Latin-2. As just mentioned, the ä in this file will be an ä according to your default encoding in the buffer. There is a mechanism to automatically deduce the file encoding, see below; if none can be deduced, your default encoding is assumed.
• By default, all 8bit characters are encoded to tokens when saving the file. This won't be done if a file encoding can be automatically deduced (by the method mentioned below) or if there are already 8bit characters in the file when visiting. The modeline string will contain an 8 after the token language if 8bit characters are to be stored in the file. You can change the default behaviour by using the submenu Buffer/File Options in menu X-Symbol.

As mentioned above, X-Symbol can automatically deduce a non-standard file encoding and the information to store 8bit characters. It searches for some strings in the beginning of the file, including the comment:

• For token language tex with file extension .tex, it searches for one of the following six strings in the current buffer and the buffer-local TeX-master (variable defined in AucTeX).

  \usepackage[latin1]{inputenc}
  \usepackage[latin2]{inputenc}
  \usepackage[latin3]{inputenc}
  \usepackage[latin5]{inputenc}
  \usepackage[latin9]{inputenc}
  %& -translation-file=il1
  %& -translation-file=il2

• For token language sgml with major mode html-mode, it searches for one of the following four strings in the current buffer.

  <meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-2">
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-3">
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-9">
  <meta http-equiv="content-type" content="text/html; charset=iso-8859-15">

Technical detail: the X-Symbol manual and the documentation of variables x-symbol-coding and x-symbol-8bits.

Input Methods, Info in Echo Area

Package X-Symbol offers various input methods for the insertion of X-Symbol characters. They are best explained with screenshots (which are a bit outdated) .

Menu. There are various submenus in menu X-Symbol for the insertion of characters. AucTeX's math mode menu also inserts the character if it is represented by the selected TeX macro.

Grid. The easiest way to insert a character is by the input method Grid. When you select menu item X-Symbol - Other Commands - GRID Of Characters, you get a buffer with all characters supported by X-Symbol. Using the middle mouse button inserts the character under the mouse pointer (highlighted in green).

Some information for the highlighted character is shown in the the echo area (minibuffer). By default, the grid only displays characters valid in the buffer where you have invoked the grid from. It also might use a coloring scheme which gives you some additional information about the characters.

If you press the right mouse button, 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. They are automatically initialized in other cases, though.

Info in the echo area. Further on, you see an example of the info in the echo area (minibuffer) for characters around point. The info includes the encodings in which the character is considered a 8bit character.

Token. If you are new to package X-Symbol, you are likely to insert characters by their token name. Input method Token automatically replaces the token by the corresponding character. Press C-x u or undo to undo the replacement.

You may also select a character by the command found at menu item X-Symbol - Other Commands - READ Token Character using completion in the minibuffer (I also use Emacs packages icomplete and paren).

Context. The idea of the input method Context is to replace a sequence of characters by a character which looks similar to the whole sequence. By default, there is some info in the echo area mentioning this (but not for character sequences which are likely to be normal text).

C-, is the command which forces the replacement (if you have used the standard installation file). Because more characters might "want" to be represented by the same character sequence, another C-, "modifies" the previous character to an alternative character. If you do it often enough, you are back at your first character.

Electric. The input method Context is so convenient that people are actually too lazy to type C-,. By default, input method Electric therefore automatically replaces some contexts in specific situations. Press C-x u or undo if input method Electric was too eager.

You can use C-. to "rotate" a character which has a "direction" (or change uppercase/lowercase). If a prefix argument is given, it lets you 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". The key is also used to "Greekify" the previous character: typing a C-. is shorter than a # C-,.

Key. Unfortunately (and obviously), input method Context does not work for C-s (isearch). Therefore, you may also insert a character by normal key bindings. As you see in the following screenshot, the key bindings are similar to the Ascii sequences which are replaced by 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, press Help or C-h and you get the buffer with completions (like that in the following screenshot):

Quail. If you are used to the input methods of Emacs/Mule, you might appreciate that the above mentioned Ascii sequences are also used to define a multilingual text input method "x-symbol".

As for all insert commands, the prefix command specifies how often to insert the character. If a character is not valid in the current buffer, an error is signaled, but a negative prefix argument might let you insert the character anyway.

Note on screenshots: the key bindings might start with C-= instead multi-key on your system (definitely under XEmacs/Mule).

Super- and Subscripts

Super- and subscripts are supported with special faces via the use of the Emacs package font-lock. The super-/subscript command itself is invisible, except at point where it is revealed and highlighted with pink (by default). Only the innermost super-/subscripts are displayed via special faces.

You can turn off this feature by selecting menu item X-Symbol - Buffer/File Options - Super-/Subscripts. Then, the modeline string would look like XS:sgml/i instead XS:sgml/si.

Thumbnails for Images

Image insertion commands are highlighted and a glyph is put at the end of the command showing a scaled-down version of the image (not if this would slow things down considerably, e.g., for remote files). The following commands are recognized:

• For token language tex, it searches for one of the following six commands.

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

• For token language sgml, it searches for the following command.

  <img [...] src="FILE.{gif,png,jpeg,jpg}" [ATTRIBUTES]>

You can turn off this feature by selecting menu item X-Symbol - Buffer/File Options - Show Images. Then, the modeline string would look like XS:sgml/s instead XS:sgml/si.

Using the middle mouse button invokes the image editor for the image under the mouse pointer. You can specify different editors for files with different extension, you may even edit a more "abstract" image file: by default, you do not directly edit Postscript images, xfig FILE.fig is invoked instead.

If you press the right mouse button, you can select all possible directories in the image search path of the token language if the buffer file name is implicitly relative. (For language sgml, the searchpath only consists of the current directory (but you can define some kind of links); for tex, it is $TEXPICTS or $TEXINPUTS.)

In order not to slow down editing, glyphs are not created (special glyphs are used instead) in the following situations (you can change the default):

• The image file is created after the file has been visited. Reason: we would need to check the file system during typing. Solution: use "Rescan buffer" from the image highlight menu.
• The image file name has a directory part which is neither empty nor found in: figures/ for tex, images/ or pictures/ for sgml. Reason: we cannot check the whole file system for image files. Solution: customize where X-Symbol should search for image files.

Technical detail: the X-Symbol manual or the documentation of function x-symbol-image-parse-buffer.