\input texinfo @c Copyright (C) 1998-2003 Free Software Foundation, Inc. @c @c Author: Christoph Wedler @c Maintainer: (Please use `M-x x-symbol-package-bug' to contact the maintainer) @c Keywords: WYSIWYG, LaTeX, HTML, wp, math, internationalization @c X-URL: http://x-symbol.sourceforge.net/ @c %**start of header @setfilename x-symbol.info @settitle X-Symbol Manual @setchapternewpage odd @set edition 4.5.1 @set version 4.5.1 @set update May 2003 @set url http://x-symbol.sourceforge.net @set maintainer wedler@@users.sourceforge.net @set listdevel x-symbol-devel@@lists.sourceforge.net @c for cross references to other manuals @ifset GNU @set subedition Emacs @set emacs emacs @set emacsman GNU Emacs Manual @end ifset @ifclear GNU @set subedition XEmacs @set emacs xemacs @set emacsman XEmacs User's Manual @end ifclear @set auctex auctex @set auctexman AUC@TeX{} @set reftex reftex @set reftexman Ref@TeX{} User Manual @set kpathsea kpathsea @set kpathseaman Kpathsea Manual @syncodeindex fn vr @c %**end of header @dircategory Editors @direntry * X-Symbol:: Semi WYSIWYG for LaTeX, HTML and other "token languages" @end direntry @ifinfo This file documents X-Symbol, a package providing semi-@sc{wysiwyg} for La@TeX{}, HTML and other ``token languages''. It uses additional fonts and provide input methods to insert their characters into your document. This is Edition @value{edition} (@value{subedition}) of the X-Symbol Manual for X-Symbol @value{version}, @value{update}. Copyright (c) 1998-2003 Free Software Foundation, Inc. @c default 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. @ignore Permission is granted to process this file through TeX and print the results, provided the printed document carries a copying permission notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual). @end ignore 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. @c end default @end ifinfo @finalout @titlepage @title X-Symbol Manual @subtitle Semi-@sc{wysiwyg} for La@TeX{}, HTML and other ``token languages'' @subtitle Edition @value{edition} (@value{subedition}), for X-Symbol @value{version}, @value{update} @author by Christoph Wedler @page @vskip 0pt plus 1filll Copyright @copyright{} 1998-2003 Free Software Foundation, Inc. @c default (slight change) 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 that the entire resulting derive 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. @c end default @end titlepage @c =========================================================================== @ifinfo @node Top, Introduction, (dir), (dir) @comment node-name, next, previous, up @top X-Symbol When you edit La@TeX{}, HTML, BibTeX or @TeX{}info sources in Emacs, package X-Symbol provides some kind of @sc{wysiwyg} by using real characters for tokens like @code{\oplus} or @code{™}. 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 @value{edition} (@value{subedition}) of the X-Symbol Manual for X-Symbol @value{version}, @value{update}. For recent changes, see @ref{News}. Bug fixes, bug reports, improvements, and suggestions are strongly appreciated. If you want to contact the maintainer of package X-Symbol, please read @ref{Bug Reports}. @end ifinfo @menu * Introduction:: Introduction to X-Symbol. * Installation:: What to do before using package X-Symbol. * Concepts:: Token language, conversion, coding, etc. * Input Methods:: How to insert X-Symbol characters. * Features:: Super-/subscripts, images, info, etc. * Supported Languages:: Details of the predefined token languages. * X-Symbol Internals:: How package X-Symbol works. * Problems:: Annoyances, contacting the maintainer. * History:: Changes, wishlist, projects. * Indexes:: Menus covering various topics. @detailmenu --- The Detailed Node Listing --- Introduction * Copying:: X-Symbol is GPL'd. * Summary:: A brief summary of package X-Symbol. * About:: About this manual. Installation * Requirements:: Which programs you need for X-Symbol. * Installing Files:: Basics 1: Put the files into your home dir. * System-wide Installation:: Alternative: Put the files into the XEmacs dir. * Installing Lisp:: Basics 2: Initialize X-Symbol during startup. * Installing Image Converter:: Recommended: How to install @code{convert}. * Package Integration:: How X-Symbol interacts with other packages. * Installing Fonts:: Optional: What to do when using other fonts. * Installing Fonts Exceed:: If appropriate: What to do when using Exceed. * Installing Fonts Lisp:: If appropriate: Lisp coding for other fonts. * Installing Manual:: Optional: How to create the manual. * Checking Installation:: Is package X-Symbol completely installed? Package Integration * LaTeX Packages:: Packages used in La@TeX{} buffers. * Syntax Hiliting Packages:: Package @code{font-lock} and support modes. * File IO Packages:: Compression, encryption, remote files, etc. * Miscellaneous Packages:: Other packages. Concepts of Package X-Symbol * Token Language:: What does a X-Symbol character represent. * Conversion:: Decoding tokens, encoding characters. * Minor Mode:: How to control the behavior of X-Symbol. * Poor Mans Mule:: Running X-Symbol under XEmacs/no-Mule. * Role of font-lock:: Why does X-Symbol need @code{font-lock}. * Char Group:: Character group and token classes. Conversion: Decoding and Encoding * Default Coding:: Normal File and Default Encoding. * File Coding:: Specific encoding of a file. * Controlling 8bit Coding:: Do you want to store 8bit characters? * Unique Decoding:: Restrict decoding to avoid normalization? * Conversion Commands:: Interactive encoding and decoding. * Copy with Conversion:: Copy & paste with conversion. * Char Aliases:: Different charsets include the same chars. X-Symbol's Input Methods * Introducing Input Methods:: Common behavior of all input methods. * Input Method Token:: Replace token by character. * Input Method Read Token:: Minibuffer input with completion. * Input Method Menu:: Select a menu item. * Input Method Grid:: Choose highlighted character. * Input Method Keyboard:: Compose a key sequence. * Input Method Context:: Replace character sequence. * Input Method Electric:: Automatically replace character sequence. * Input Method Quail:: A Mule input method "x-symbol". * Customizing Input Method:: How to customize the input methods. Features of Package X-Symbol * Super and Subscripts:: Use special fonts for super-/subscripts. * Images:: Images after image insertion commands. * Info:: Display information in echo area. * Ascii Representation:: Derive label from a buffer contents. * Package Information:: Invoke info system, use WWW browser. Images at the end of Image Insertion Commands * Image Display:: When to display images. * Image Conversion:: Producing a scaled-down image. * Image Caching:: Speeding up the image processing. * Special Images:: Signaling specific situations. * Image Editor:: Editing the original image file. Supported Token Languages * Pseudo Language:: Token language ``x-symbol charsym''. * TeX Macro:: Token language @code{tex}. * SGML Entity:: Token language @code{sgml}. * BibTeX Macro:: Token language @code{bib}. * TeXinfo Command:: Token language @code{texi}. * External Languages:: Languages defined in other Emacs Packages. Token Language ``@TeX{} macro'' (@code{tex}) * TeX Macro Basics:: Basics of language ``@TeX{} macro''. * TeX Macro Features:: Super-/subscripts and images in La@TeX{}. * TeX Macro Problems:: Problems with @TeX{} macros. * TeX Macro Conversion:: How the conversion of @TeX{} macros works. * TeX Macro Symbols:: Extra Symbols of Language ``@TeX{} Macro''. Token Language ``@sc{sgml} entity'' (@code{sgml}) * SGML Entity Basics:: Basics of Language ``@sc{sgml} entity''. * SGML Entity Features:: Super-/Subscripts and Images in @sc{html}. * SGML Entity Conversion:: How the conversion of @sc{sgml} entities works. X-Symbol Internals * Char Representation:: How X-Symbol represents X-Symbol chars. * Defining Charsets:: How X-Symbol defines additional chars. * Defining Input Methods:: How X-Symbol defines the input methods. * Extending X-Symbol:: How to add fonts and token languages. * Various Internals:: How X-Symbol handles other aspects. * Design Alternatives:: Why X-Symbol is not designed differently. * Language Internals:: How X-Symbol handles languages. * Misc Internals:: Various. TODO. Defining Input Methods * Input Method Objectives:: Input methods should be intuitive/consistent. * Intro Char Descriptions:: An example introducing char descriptions. * Char Descriptions:: The aspects and the contexts of a character. * Example Char Descriptions:: A complete example defining input methods. * Customizing Input Methods:: How to customize the input methods. Extending Package X-Symbol * Extending with Fonts:: How to add fonts to X-Symbol. * Input Definitions:: Guidelines for input definitions. * Font Definition File:: How to define new character in a file. * Language Extension File:: Extending an existing language. * Language Definition File:: Defining a new language. Various Internals * Tagging Insert Commands:: Don't break input methods Token and Electric. * Avoiding Flickering:: Moving cursor in invisible commands. Design Alternatives * Alt Token Representations:: Why we need the conversion. * Alt Global Mode:: How to turn on X-Symbol globally. * Alt Auto Conversion:: When do we convert automatically. Problems, Troubleshooting * Nomule Problems:: X-Symbol provides a @emph{poor} man's Mule. * Spurious Encodings:: Some commands turn off X-Symbol mode. * No Encoding:: The encoding does not work in a rare case. * FAQ:: Frequently asked questions. * Bug Reports:: How to contact the maintainer of X-Symbol. Frequently Asked Questions * FAQ XEmacs Core:: XEmacs crashes when using input method Token * FAQ font-lock:: X-Symbol's fontification does not work. * FAQ Strange Chars:: The buffer contains strange characters * FAQ No Subscripts:: I cannot see any/some super-/subscripts. * FAQ Stupid Subscripts:: I see subscripts where I don't want them. * FAQ Font Size:: The characters are too small or too big. * FAQ Conversion:: The conversion changes some tokens. * FAQ Additional Spaces:: A space is added during the encoding. * FAQ 8bit Chars:: I do not want 8bit characters in the file. * FAQ Hyphen:: I cannot distinguish @code{hyphen} from @samp{-}. * FAQ Spell Check:: I have problems with spell-checking. * FAQ News and Mail:: I want to use X-Symbol in Gnus or @sc{vm}. History and Projects * News:: Changes in recent versions. * Wishlist:: Projects for X-Symbol. * Open Questions:: How you can contribute. * Acknowledgments:: People having contributed. News: Changes in Recent Versions of X-Symbol * Changes New:: To be announced. * Changes 4.5:: Released Mar 2003 as beta. * Changes 4.4:: Released June 2002 as beta. * Changes 4.1:: Released Mar 2002 as beta. * Changes 3.4:: Released Mar 2002. * Changes 3.3:: Released Jan 1999. * Changes 3.2:: Released Dec 1998. * Changes 3.1:: Released Oct 1998. * Changes 3.0:: Released Sep 1998 as beta. * Changes Old:: Overview of old releases. Wishlist: Projects for X-Symbol * Wishlist Languages:: Additional token languages. * Wishlist Fonts:: Automatically generated fonts. * Wishlist Emacs:: Changes in Emacs/XEmacs. * Wishlist LaTeX:: Changes in La@TeX{}. * Wishlist Various:: Other changes. * Wishlist Rejected:: Rejected Suggestions for X-Symbol. Indexes * Key Index:: Key sequences. * Program Index:: Programs and Emacs packages. * Variable Index:: Commands, functions, variables. * Concept Index:: Various topics. @end detailmenu @end menu @c =========================================================================== @node Introduction, Installation, Top, Top @comment node-name, next, previous, up @chapter Introduction @cindex Overview @cindex Introduction When you edit La@TeX{}, HTML, BibTeX or @TeX{}info sources in Emacs, package X-Symbol provides some kind of @sc{wysiwyg} by using real characters for tokens like @code{\oplus} or @code{™}. It also provides various input methods to insert these characters. Thumbnails for included images and real super-/subscripts and are also supported. @menu * Copying:: X-Symbol is GPL'd. * Summary:: A brief summary of package X-Symbol. * About:: About this manual. @end menu @c ==================================================================== @node Copying, Summary, Introduction, Introduction @comment node-name, next, previous, up @section X-Symbol's Copying Conditions: GPL @cindex Copying @cindex Copyright @cindex GPL @cindex General Public License @cindex License @cindex Warranty (This text is stolen from the @TeX{}info 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 @dfn{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. @c ==================================================================== @node Summary, About, Copying, Introduction @comment node-name, next, previous, up @section Brief Summary of X-Symbol @cindex Summary @cindex Brief Summary @cindex X-Symbol in a Nutshell @itemize @bullet @item X-Symbol provides a @strong{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. @item These characters are used in the buffer to represent @strong{tokens} (e.g., @TeX{} macros, @sc{sgml} entities, more ``token languages'' could be added easily) in the file. The @emph{conversion} is done automatically when visiting the file, saving the buffer and turning the minor mode on/off. @item Defines 8 @strong{input methods} for these characters: @emph{Menu}, @emph{Grid} (selecting a character with the mouse), @emph{Keyboard}, @emph{Context} (replace/modify similar-looking char sequence), @emph{Electric} (automatic replace), @emph{Quail} (a Mule input method), @emph{Token} (replace token by corresponding char), @emph{Read Token} (completing minibuffer input of token). @item Offers some @strong{info} in the echo area for these characters (e.g., that the character under point represents the TeX macro @code{\leadsto} and that the macro is defined in La@TeX{} package @file{latexsym.sty}). @item Allows to use a @strong{8bit file encoding} which is different from your "normal" 8bit file encoding, e.g., you can visit @TeX{} files with @code{\usepackage[latin5]@{inputenc@}} even if you normally use a Latin-2 font. @item Provides a kind of ``@strong{poor man's Mule}'' when running on an XEmacs without Mule support: it can @emph{display} more than 256 characters via @code{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. @item Provides fonts for single-line innermost @strong{super-} and @strong{subscripts} to be displayed with per-buffer control. The invisible part, like @code{} in HTML, is revealed at point. @item Displays thumbnails for @strong{images} at the end of image insertion commands with per-buffer control (e.g., @code{\includegraphics@{@var{file}@}} in La@TeX{}, @code{} in HTML). They show a scaled-down version of the included image files (using @code{convert} from @uref{http://www.imagemagick.org/,ImageMagick}). A single mouse click on the image or command invokes the image editor for the corresponding image file. @item It @emph{does not} and @emph{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 @code{font-lock}, e.g., @code{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 @code{outline-minor-mode} or folding might also be an alternative. @end itemize If you prefer a more @sc{wysiwyg}-like document processor, you should probably use @code{LyX} or @code{GNU TeXmacs}. Here are some reasons why you would use Emacs/XEmacs with package X-Symbol instead: @itemize @bullet @item You have complete control over the La@TeX{} source. X-Symbol supports more characters. @item You can read any La@TeX{} source and you write normal La@TeX{} code, i.e., package X-Symbol does not use any special format. @item It also supports HTML and @TeX{}info documents and BibTeX entries. @item You can use your favorite editor, i.e., Emacs or XEmacs. @end itemize @c ==================================================================== @node About, , Summary, Introduction @comment node-name, next, previous, up @section About this Manual @cindex About @cindex Web Pages @cindex Info Pages @cindex Manual @cindex Online Help Apart from this manual, there are two other sources of information about X-Symbol: @itemize @bullet @item 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: @display @uref{@value{url}/} @end display @item The online help for commands (functions) and user options (variables) is quite technical. It is shown during customization and when using Emacs' Help menu. @end itemize 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 @ref{X-Symbol Internals}. This manual does not explain Emacs in general or some optional programs used by this package such as @code{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 @ref{Bug Reports}. @c =========================================================================== @node Installation, Concepts, Introduction, Top @comment node-name, next, previous, up @chapter Installation @cindex Installation The short version of the installation instructions for package X-Symbol on XEmacs is: uncompress & extract the @emph{binary distribution} in directory @file{~/.xemacs/xemacs-packages/}, add @code{(x-symbol-initialize)} to your @file{~/.emacs} and install ImageMagick for the image support (unless you want to get a warning). Please check the web page @emph{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. @menu * Requirements:: Which programs you need for X-Symbol. * Installing Files:: Basics 1: Put the files into your home dir. * System-wide Installation:: Alternative: Put the files into the XEmacs dir. * Installing Lisp:: Basics 2: Initialize X-Symbol during startup. * Installing Image Converter:: Recommended: How to install @code{convert}. * Package Integration:: How X-Symbol interacts with other packages. * Installing Fonts:: Optional: What to do when using other fonts. * Installing Fonts Exceed:: If appropriate: What to do when using Exceed. * Installing Fonts Lisp:: If appropriate: Lisp coding for other fonts. * Installing Manual:: Optional: How to create the manual. * Checking Installation:: Is package X-Symbol completely installed? @end menu @c ==================================================================== @node Requirements, Installing Files, Installation, Installation @comment node-name, next, previous, up @section Requirements @cindex Requirements @cindex Binary Package @cindex Source Package @cindex Old Version @cindex Window System @cindex X @cindex Windows @cindex MS-Windows @cindex Character Terminal @cindex TTY @pindex Emacs @pindex XEmacs 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, @ref{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 (@pxref{Wishlist Fonts}). Under a character terminal, X-Symbol just supports Latin-1 characters only, no super- and subscripts and no images. @pindex font-lock @pindex lazy-shot @pindex texmathp @pindex auctex This package require package @code{font-lock} (distributed with Emacs and XEmacs), the use of package @code{lazy-shot} is recommended, see @ref{Syntax Hiliting Packages}. @pindex convert If you want to see the images at the end of image insertion commands, install @code{convert} from @uref{http://www.imagemagick.org/,ImageMagick}, see @ref{Installing Image Converter}. They show a scaled-down version of the included image files. @pindex makeinfo @pindex texi2dvi @pindex latex2html If you want to produce the Info files yourself (they are included in the binary distribution), you need @code{makeinfo}, Version 1.68 or higher. If you want to produce a PS file from the manual, you need @code{texi2dvi}. If you want to produce an HTML version of this manual, you need @code{texi2html}, Version 1.62 or higher. @xref{Installing Manual}. @c ==================================================================== @node Installing Files, System-wide Installation, Requirements, Installation @comment node-name, next, previous, up @section Put the Files into your Home Directory @cindex Basic Installation @cindex Uncompress Tarball @cindex Extract Tarball @cindex Tarball @cindex Binary Distribution If you use Emacs, please check the @uref{@value{url}/news.html,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 @ref{System-wide Installation}. If you use the source distribution, you should know what do to instead. In directory @file{~/.xemacs/xemacs-packages/}, run @example zcat x-symbol-pkg.tar.gz | tar xvf - @end example Remember that @code{tar} does not overwrite write-protected files. X-Symbol's @file{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 @example chmod -R a+rx ~/.xemacs/xemacs-packages @end example If package X-Symbol has been installed system-wide and you install a newer version in your @file{~/.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@dots{}. Before XEmacs-21.0: the user package directory was @file{~/.xemacs/} instead of @file{~/.xemacs/packages/}; also: delete and recompile the @file{.elc} files. @c ==================================================================== @node System-wide Installation, Installing Lisp, Installing Files, Installation @comment node-name, next, previous, up @section System-wide Installation: Put the Files into the XEmacs Directory @cindex System-wide Installation @cindex Installing System-wide @cindex @file{default.el} @cindex @file{site-start.el} 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 @file{default.el} and @file{@var{xemacs}/site-packages/} whenever @file{~/.emacs} and @file{~/.xemacs/xemacs-packages/} are mentioned in the previous or following subsections. @file{@var{xemacs}/site-packages/} is the directory of independent packages for XEmacs. Under XEmacs-21, you can uncompress and extract the tarball by @example M-x package-admin-add-binary-package @key{RET} @var{dir}/x-symbol-pkg.tar.gz @end example Then, @file{@var{xemacs}/} is the default directory of buffer @file{*Package Output*} (use @kbd{C-x C-f} in that buffer to see it). It might be @file{/usr/local/lib/xemacs/xemacs-packages/} (the first element in variable @code{late-packages}). Under XEmacs-20, @file{@var{xemacs}/} might be @file{/usr/local/lib/xemacs-@var{version}/}. Here, you have to uncompress and extract the tarball as described in @ref{Installing Files}. You also have to load the autoload file explicitly by putting the following line into file @file{site-start.el}: @lisp (load "@var{xemacs}/lisp/x-symbol/auto-autoloads") @end lisp I would appreciate if you would set the following variables: @vtable @code @item x-symbol-installer-address Please set this variable to your email address to catch problems which could be solved locally. In your private @file{~/.emacs}, you might want to set this variable to @code{nil}. @item x-symbol-package-url If you have a local copy of the web pages (@pxref{Installing Manual}), set this variable to the corresponding @sc{url}. @end vtable @c ==================================================================== @node Installing Lisp, Installing Image Converter, System-wide Installation, Installation @comment node-name, next, previous, up @section Make XEmacs Initialize X-Symbol During Startup @cindex Installing Lisp @cindex Lisp Installation @cindex Elisp Installation @cindex @file{.emacs} @findex x-symbol-initialize Put the following into your @file{~/.emacs} (or @file{~/.xemacs/init.el}): @lisp (x-symbol-initialize) @end lisp Basically, that's it! If your XEmacs runs on a different machine, check @ref{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, @ref{Requirements}), set the default coding (@pxref{Default Coding}) by putting the following in front of the line above: @lisp (setq x-symbol-default-coding 'iso-8859-1) @end lisp When running Emacs under a character terminal, you might need to use the following (with or without X-Symbol): @lisp (unless window-system (standard-display-european 1)) @end lisp 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: @lisp (when window-system (x-symbol-initialize)) @end lisp The initialization can be controlled by the following variable: @vtable @code @item x-symbol-initialize By default, package X-Symbol does a full initialization. This includes an integration with some packages, see also @ref{Package Integration}. @end vtable 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: @code{isearch}, @code{highlight}, @code{primary-selection}, @code{secondary-selection}, @code{paren-match}, @code{paren-mismatch}, @code{paren-blink-off}, @code{underline}. I.e., for each @var{face}, use: @lisp (remove-specifier (get (get-face '@var{face}) 'font)) @end lisp @c ==================================================================== @node Installing Image Converter, Package Integration, Installing Lisp, Installation @comment node-name, next, previous, up @section Installing the Image Converter from ImageMagick @cindex Installing Image Converter @cindex Installing @code{convert} @cindex Image Converter Installation @cindex @code{convert} Installation @pindex convert Program @code{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. @vindex x-symbol-image-converter While the installation of @code{convert} is optional, you get a warning if @code{convert} is not found on your system or if there is no image format supported by both @code{convert} and Emacs. Set variable @code{x-symbol-image-converter} to @code{nil} if you don't want to get the warning. @vindex x-symbol-image-convert-program On Unix, @code{convert} must be in your @code{$PATH}. On Windows, it is assumed to be found at @file{C:\ImageMagick\convert}. If this is not the case, you have to customize the variable @code{x-symbol-image-convert-program}. Check @uref{http://www.imagemagick.org/} for the installation instructions. Run @samp{convert -h} and @samp{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. @comment ImageMagick-5.0..5.37 failed to show formats sometimes If you do not have a truecolor device (i.e., just 256 colors), package X-Symbol uses @code{convert} with a colormap by default (@pxref{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. @c ==================================================================== @node Package Integration, Installing Fonts, Installing Image Converter, Installation @comment node-name, next, previous, up @section Package Integration @cindex Package Integration @cindex Integrating Package @cindex Other Packages 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. @menu * LaTeX Packages:: Packages used in La@TeX{} buffers. * Syntax Hiliting Packages:: Package @code{font-lock} and support modes. * File IO Packages:: Compression, encryption, remote files, etc. * Miscellaneous Packages:: Other packages. @end menu @node LaTeX Packages, Syntax Hiliting Packages, Package Integration, Package Integration @comment node-name, next, previous, up @subsection La@TeX{} Packages @cindex La@TeX{} Packages @cindex Integrating La@TeX{} Packages Objectives: relate positions in buffer to positions in file, do conversion in master/slave buffers, preserve highlighting, improve input methods and other things. @table @code @item auctex @pindex auctex @pindex texmathp @findex TeX-next-error @vindex TeX-translate-location-hook @findex x-symbol-tex-error-location Use Version 9.9c or higher, which includes @code{texmathp}. There is some special X-Symbol adaptation for Auc@TeX{}: @itemize @minus @item @vindex TeX-master X-Symbol supports Auc@TeX{}'s multifile documents: it respects the variable @code{TeX-master} when searching for the file encoding (@pxref{File Coding}) and when converting image files with relative names (@pxref{Image Display}). @item @vindex TeX-region-hook X-Symbol supports Auc@TeX{}'s region commands: it ensures that characters in @file{_region_.tex} buffer are converted according to the parent buffer. Initialization changes @code{TeX-region-hook}. Requires Auc@TeX{}, v9.8a or higher. @item X-Symbol's input method Electric (@pxref{Input Method Electric}) with token language @code{tex} uses package @code{texmathp}. @item @vindex LaTeX-math-insert-function Auc@TeX{}'s math mode commands also inserts X-Symbol characters (@pxref{Mathematics,,, @value{auctex}, @value{auctexman}}). Initialization sets @code{LaTeX-math-insert-function}. Requires Auc@TeX{}, v9.8a or higher. @item @findex TeX-next-error @vindex TeX-translate-location-hook If @TeX{} displays an error message, it also displays the context of the error position. Auc@TeX{} uses the context to set point to this position when @kbd{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 @code{TeX-translate-location-hook}. @end itemize @item bib-cite @pindex 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 @code{bib-cite}s highlighting of @code{\cite} and friends. @item preview-latex @pindex preview-latex @findex x-symbol-tex-preview-locations @TeX{}'s error positions are also used by package @code{preview-latex}, which was clever enough to reuse the above mentioned hook of Auc@TeX{}. Unfortunately, that hook is @dots{} and does not allow a fast translation of error positions, so @code{preview-latex} allows to provide better variants of functions in that hook. X-Symbol's variant is @code{x-symbol-tex-preview-locations}. @item reftex @pindex reftex @vindex reftex-translate-to-ascii-function Use Version 3.26 or higher. For a workaround for some minor annoyances with the combination Ref@TeX{}/X-Symbol/Multifile Document, see @ref{Problems and Work-arounds,,,@value{reftex},@value{reftexman}}. By default, the initialization of package X-Symbol makes Ref@TeX{}'s label creation use the nicer Asciification of package X-Symbol (@pxref{Ascii Representation}) by setting @code{reftex-translate-to-ascii-function}. @item whizzytex Use the newest. @end table @node Syntax Hiliting Packages, File IO Packages, LaTeX Packages, Package Integration @comment node-name, next, previous, up @subsection Syntax Highlighting Packages (@code{font-lock} and add-ons) @cindex Syntax Highlighting Packages @cindex @code{font-lock} Packages @cindex Integrating @code{font-lock} Packages Objectives: start highlighting after conversion. Highlighting is needed for super- and subscripts and when using XEmacs without Mule support. @table @code @item fast-lock @pindex fast-lock @vindex fast-lock-save-faces I recommend to use package @code{lazy-shot} instead. By default, the initialization of package X-Symbol sets @code{fast-lock-save-faces} to @code{nil} to make package @code{fast-lock} work with X-Symbol. @item font-latex @pindex font-latex @vindex font-lock-maximum-decoration I suggest to set @code{font-lock-maximum-decoration} to value @code{t}, 2 or higher if you do not want to use super- and subscripts in arguments of @code{\label} and friends. @xref{FAQ Stupid Subscripts}. @item font-lock @pindex font-lock @vindex font-lock-auto-fontify Is required by this package (@pxref{Role of font-lock}). I strongly recommend @emph{not} to turn on font-lock in @emph{any} mode hook, set @code{font-lock-auto-fontify} to @code{t} instead (this is the default, anyway). See also @code{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 @emph{after} the functions in the mode hook have been run, i.e., the fontification is getting useless if the tokens are automatically decoded. @item lazy-lock @pindex lazy-lock From XEmacs-20.3 on, the successor is called @code{lazy-shot}. @item lazy-shot @pindex lazy-shot Is strongly recommended. @end table @node File IO Packages, Miscellaneous Packages, Syntax Hiliting Packages, Package Integration @comment node-name, next, previous, up @subsection File I/O Packages @cindex File I/O Packages @cindex I/O Packages @cindex Remote File Packages @cindex Compression Packages @cindex Encryption Packages @cindex Integrating I/O Packages Issue: compression, encryption and so on can be seen as some kind of conversion. When doing multiple conversion, the sequence matters. @table @code @item ange-ftp @pindex ange-ftp See also @code{efs} and @code{jka-compr}. @item comint @pindex comint @vindex comint-input-sender The default installation makes @code{comint}s in-/output use X-Symbol's conversion function. If you set variable @code{comint-input-sender}, set it before initializing package X-Symbol. @item crypt @itemx crypt++ @pindex crypt @pindex crypt++ @findex save-buffer @vindex x-symbol-auto-conversion-method I recommend to use package @code{jka-compr} instead. @xref{Spurious Encodings}. @xref{No Encoding}. If you use @code{crypt} or @code{crypt++} and the character @code{alpha} looks like @samp{\233a} after @code{save-buffer}, set this variable to @code{slowest}. @xref{Open Questions}. @item efs @pindex efs XEmacs' version of @code{ange-ftp}. See also @code{jka-compr}. @item iso-cvt @pindex 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. @item iso-sgml @pindex iso-sgml There is no need to use it. Package X-Symbol already provides the conversion between Latin-1 characters and ``@sc{sgml} entities''. @xref{Miscellaneous Packages}, package @code{psgml-html}. @item jka-compr @pindex jka-compr Can be used with package X-Symbol, preferred to @code{crypt}. The following is absolutely necessary (with or without using package X-Symbol, at least in older Emacsen): load @code{jka-compr} after @code{efs}/@code{ange-ftp}! @item latin-unity @pindex 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 (@pxref{Char Aliases}) and recoding (@pxref{File Coding}). Has some safe-encoding mechanism, but the test comes currently too early (@pxref{Wishlist Emacs}). @c TODO: test mule-ucs.el with Emacs-21.4 @item ucs-tables @pindex ucs-tables @findex unify-8859-on-decoding-mode @findex unify-8859-on-encoding-mode The Emacs minor modes @code{unify-8859-on-decoding-mode} and @code{unify-8859-on-encoding-mode} can be used with package X-Symbol. @item vc @pindex vc @findex vc-next-action If you use package @code{crypt}, @code{vc-next-action} and friends encode characters to tokens. @xref{Spurious Encodings}. @end table @node Miscellaneous Packages, , File IO Packages, Package Integration @comment node-name, next, previous, up @subsection Miscellaneous Packages @cindex Miscellaneous Packages @table @code @item abbrev @pindex abbrev On XEmacs without Mule support, I recommend to set variable @code{words-include-escapes} to @code{t}. @xref{Nomule Problems}. @item completion @pindex completion Should work with X-Symbol (earlier version of X-Symbol had problems with input method token). @item desktop @pindex desktop XEmacs' version (an old one) does not save its @file{.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 @code{session} below. @item flyspell @pindex flyspell @findex global-flyspell-mode Should work apart from the general problem of @code{ispell}. @item func-menu @pindex func-menu Should work with X-Symbol. @item ispell @pindex ispell The package @code{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 @code{ispell}, see @ref{Wishlist Emacs}. @xref{FAQ Spell Check}. @pindex ProofGeneral Use a future version (hopefully v3.4). Includes special X-Symbol initialization/handling and defines additional token languages. @xref{External Languages}. @item psgml-html @pindex psgml @pindex psgml-html @code{psgml-html}: Do not set @code{html-auto-sgml-entity-conversion} to non-@code{nil}. @xref{File IO Packages}, package @code{iso-sgml}. @item session @pindex session Use Version 1.5a or higher. If strings in this file should always be read correctly, you should put @code{(x-symbol-init-input)} into your @file{~/.emacs}; otherwise strings containing X-Symbol's private characters read from the @file{~/.session} file might look funny. See also package @code{desktop} above. @item x-compose @pindex x-compose All characters from @code{x-compose} are also supported by package X-Symbol. Thus, I recommend to use @kbd{@key{multi-key}} instead @kbd{C-=} when running under XEmacs without Mule support. @xref{Introducing Input Methods}. @end table @c =========================================================================== @node Installing Fonts, Installing Fonts Exceed, Package Integration, Installation @comment node-name, next, previous, up @section Installing Additional Fonts @cindex Installing Fonts @cindex Fonts @cindex X11 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@dots{}. Nevertheless, if you have a clearer explanation for the installation sequence below, please send me a patch to @file{man/x-symbol/x-symbol.texi}.) @enumerate @item @pindex xfd @pindex xfontsel Find the font which you want to replace by checking fonts with the X11 program @code{xfontsel} or @code{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. @item Find the @file{.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 @file{.bdf} files for additional fonts sizes of all fonts except the xsymb1 font (@pxref{Wishlist Fonts}). There are two categories of @file{.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 @file{~/.xemacs/xemacs-packages/etc/x-symbol/origfonts/}. The second category contains files for fonts which are not installed. Copy these files to @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/}. @item In file @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/Makefile}, change variables @code{ORIGBDFS} for the first category and @code{BDFS} for the second category accordingly. @item @pindex perl In directory @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/}, execute @code{make mkdirs}, and @code{make pcfs}. You need GNUs @code{make} and @code{perl}, Version 5 (or higher). @item 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 @file{~/.xsession} (X11 startup file). @pindex xset @example xset +fp ~/.xemacs/xemacs-packages/etc/x-symbol/pcf/ @end example 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 @code{xset}, you should copy all @file{.pcf} files (compiled fonts) from @file{~/.xemacs/xemacs-packages/etc/x-symbol/pcf/} into directory @file{/usr/lib/X11/fonts/75dpi/} (Slackware distribution) and run @samp{mkfontdir 75dpi} in that directory. @item Your are on the safe side if you restart X11 after this. @item Set the Emacs Lisp variables which define the fonts. @xref{Installing Fonts Lisp}. @end enumerate @c ==================================================================== @node Installing Fonts Exceed, Installing Fonts Lisp, Installing Fonts, Installation @comment node-name, next, previous, up @section Installing Fonts for Exceed (X-server on Windows) @cindex Installing Fonts @cindex Fonts @pindex Exceed @cindex Windows @cindex Windows @cindex X-Server 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: @enumerate @item In Unix, edit file @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/makesub} to limit the shift for superscript to 3 points: @smallexample %supoffs = ('08',3, 10,3, 12,3, 14,3, 16,3, 18,3, 24,3); @end smallexample @item Then, execute @code{make mkdirs}, and @code{make gens} in @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/}. If you have problems, please read the previous section. @item In Exceed's configuration window, click on @key{Font} to open Window @file{Font Settings}. In this window, click on @key{Select All}, then on @key{Compile Fonts...}. @item Copy X-Symbol's @file{bdf} files in @file{~/.xemacs/xemacs-packages/etc/x-symbol/fonts/} and @file{~/.xemacs/xemacs-packages/etc/x-symbol/genfonts/} to a Windows directory and select this directory in the Exceed Window @file{Compile Fonts}. Click on @key{Compile}. @item In Window @file{Font Settings}, click on @key{Font Database...}. In this window, click on @key{Add...}. Enter the output directory from the previous step as the @samp{Font Directory} and @code{xsymb} as the @samp{File Name (*.fdb)}. Click on @key{OK}. @item You might want to rearrange the sequence of Font DB files to let files @file{75dpi} appear prior to files @file{100dpi}, because X-Symbol's fonts are designed for 75dpi. @item In Window @file{Font Database}, click on @key{Rebuild Database...} and then on @key{OK}. @end enumerate Note: @emph{Windows NT 4.0 will crash (bluescreen) if you use fonts compiled by Exceed from the @file{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. @c ==================================================================== @node Installing Fonts Lisp, Installing Manual, Installing Fonts Exceed, Installation @comment node-name, next, previous, up @section Lisp Coding when Using Other Fonts @cindex Font Lisp Setup @cindex Font Lisp Installation 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 @code{font-lock} to display them (@pxref{Role of font-lock}). If you have installed additional fonts (@pxref{Installing Fonts}) for use with package X-Symbol, you might have to change the following variables: @vtable @code @item x-symbol-latin1-fonts @itemx x-symbol-latin2-fonts @itemx x-symbol-latin3-fonts @itemx x-symbol-latin5-fonts @itemx x-symbol-latin9-fonts @itemx x-symbol-xsymb0-fonts @itemx 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@minus{}encoding (e.g., @samp{adobe-fontspecific}) as specified by the fonts in the default value of this variable. @item 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 @samp{%d} in the names. @end vtable E.g., if you prefer larger fonts, you might want to insert the following into your @file{~/.emacs}: @smalllisp (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"))) @end smalllisp 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 (@pxref{FAQ Font Size}). You might want to change the following variables: @vtable @code @item 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. @item 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 @ref{Installing Fonts Lisp} might have no influence if Emacs already has defined fonts for the corresponding charsets. @end vtable @c ==================================================================== @node Installing Manual, Checking Installation, Installing Fonts Lisp, Installation @comment node-name, next, previous, up @section Installing Info, Postscript and HTML Files @cindex Installing Manual @cindex Info @cindex Texinfo @cindex Postscript @cindex HTML @cindex Manual @cindex Documentation @pindex makeinfo To create the info files, execute @code{make info} in directory @file{~/.xemacs/xemacs-packages/man/x-symbol/} of the distribution. It requires @code{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 @file{~/.xemacs/xemacs-packages/info/dir}: @smallexample * X-Symbol:: Semi WYSIWYG for LaTeX, HTML and other "token languages" @end smallexample @pindex texi2dvi Optionally, you might want to create a printed document from the @TeX{}info file. Execute @code{make ps} in directory @file{~/.xemacs/xemacs-packages/man/x-symbol/} of the distribution. It requires @code{texi2dvi}. @pindex latex2html Optionally, you can create an online manual for a web browser by executing @code{make html} in directory @file{~/.xemacs/xemacs-packages/man/x-symbol/} of the distribution. It requires @code{texi2html}. All formats of the manual are created by executing @code{make all}. @c ==================================================================== @node Checking Installation, , Installing Manual, Installation @comment node-name, next, previous, up @section Checking the Correct Installation of Package X-Symbol @cindex Checking Installation @cindex Final Installation Checks @cindex Installation Checks After having completed the installation, exit and restart Emacs. @itemize @bullet @item Type @kbd{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. @item Type @kbd{M-x x-symbol-grid} in buffer @file{*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 @file{*Warnings*}. @xref{Installing Fonts}. @item Move your mouse pointer to any X-Symbol character in buffer @file{*X-Symbol Grid (x-symbol charsym)*}, press the right mouse button and initialize successively all token languages. @item Again, type @kbd{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. @item If buffer @file{*Warnings*} does not exist in the buffer menu, everything is fine. So is (for me as the author of package X-Symbol), if @samp{X-Symbol} is not mentioned there. If there is a warning with @samp{no valid image converter}, you have forgotten to install ImageMagick (@pxref{Installing Image Converter}). @end itemize @c =========================================================================== @node Concepts, Input Methods, Installation, Top @comment node-name, next, previous, up @chapter Concepts of Package X-Symbol @cindex Concepts @cindex Terminology @cindex Basics 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 @ref{Input Methods}, and @ref{Features}. @menu * Token Language:: What does a X-Symbol character represent. * Conversion:: Decoding tokens, encoding characters. * Minor Mode:: How to control the behavior of X-Symbol. * Poor Mans Mule:: Running X-Symbol under XEmacs/no-Mule. * Role of font-lock:: Why does X-Symbol need @code{font-lock}. * Char Group:: Character group and token classes. @end menu @c =========================================================================== @node Token Language, Conversion, Concepts, Concepts @comment node-name, next, previous, up @section Token Language @cindex Token Language @cindex 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 @dfn{token language} which is in close relation to the major mode of the current buffer. E.g., character @code{alpha} stands for @code{\alpha} in La@TeX{} buffers. For details of predefined token languages ``@TeX{} macro'' (@code{tex}), ``@sc{sgml} entity'' (@code{sgml}), ``Bib@TeX{} macro'' (@code{bib}), and ``@TeX{}info command'' (@code{texi}), see @ref{Supported Languages}. The token language determines the conversion between X-Symbol characters and tokens (@pxref{Conversion}), the input methods (@pxref{Input Methods}), and various other features (@pxref{Features}). The token language is defined by the following buffer-local variable: @vtable @code @item 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 (@pxref{File Variables,,,@value{emacs},@value{emacsman}}), e.g.: @example %% Local Variables: %% x-symbol-language: tex %% End: @end example @end vtable 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 @ref{Minor Mode}. A token language must be @dfn{registered}, if you want to use it. By default, the above mentioned token languages are registered. @c =========================================================================== @node Conversion, Minor Mode, Token Language, Concepts @comment node-name, next, previous, up @section Conversion: Decoding and Encoding @cindex Conversion @cindex Decoding @cindex 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 @dfn{decoding}, and some conversion from characters to tokens, called @dfn{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 (@code{iso-8859-1}), Latin-2 (@code{iso-8859-2}), Latin-3 (@code{iso-8859-3}), Latin-5 (@code{iso-8859-9}), and Latin-9 (@code{iso-8859-15}). It currently supports less encodings with XEmacs on Windows (@pxref{Requirements}). @menu * Default Coding:: Normal File and Default Encoding. * File Coding:: Specific encoding of a file. * Controlling 8bit Coding:: Do you want to store 8bit characters? * Unique Decoding:: Restrict decoding to avoid normalization? * Conversion Commands:: Interactive encoding and decoding. * Copy with Conversion:: Copy & paste with conversion. * Char Aliases:: Different charsets include the same chars. @end menu @node Default Coding, File Coding, Conversion, Conversion @comment node-name, next, previous, up @subsection Normal File and Default Encoding @cindex Default Coding @cindex Default Encoding @cindex Default Font @cindex Coding, Default @cindex Encoding, Default @cindex Font, Default 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 @dfn{normal file encoding}, also called a coding system (@pxref{Recognize Coding,,,@value{emacs},@value{emacsman}}). 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 @dfn{normal file encoding} is the default encoding: @vtable @code @item x-symbol-default-coding The default encoding. The value must be a symbol denoting one of the supported encodings or @code{nil}. The variable must be set before X-Symbol has been initialized. @xref{Installing Lisp}. @end vtable The @dfn{default encoding} is not only used to determine the normal file encoding without Mule, but also for the following: @itemize @bullet @item X-Symbol has its own mechanism to recognize a file encoding which only works with a specified default encoding. @xref{File Coding}. @item 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. @xref{Char Aliases}. @item 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. @xref{Poor Mans Mule}. @end itemize To deduce the default value, X-Symbol inspects the Mule language environment and the output of the shell command @code{locale}, or to be more exact: @example locale -ck code_set_name charmap @end example 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 @code{nil} is the same as @code{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 @code{nil} makes sure that X-Symbol file encoding detection (@pxref{File Coding}) only works if Emacs has detected the same encoding; it works like @code{iso-8859-1} otherwise. @node File Coding, Controlling 8bit Coding, Default Coding, Conversion @comment node-name, next, previous, up @subsection File Coding of 8bit Characters @cindex File Coding @cindex Coding in File @cindex Encoding in File @cindex 8bit File Coding @cindex Latin File Coding @cindex Recoding 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: @vtable @code @item x-symbol-coding 8bit character encoding in the file visited by the current buffer. Value @code{nil} represents the normal file encoding (@pxref{Default Coding}). With Mule support, any value other than @code{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 @code{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 (@pxref{File Variables,,,@value{emacs},@value{emacsman}}), e.g.: @example @end example @end vtable If the variable is not already buffer-local, a reasonable value is deduced when turning on X-Symbol (@pxref{Minor Mode}) by searching for some language dependent headers at the beginning of the file: @vtable @code @item x-symbol-auto-coding-search-limit X-Symbol usually searches for something like @samp{\usepackage[@dots{}]@{inputenc@}} (@pxref{TeX Macro}) or @samp{} (@pxref{SGML Entity}) in the first 10000 characters. @end vtable If you choose not to save a file containing 8bit characters (@pxref{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. @dfn{Recoding} changes a character with code position @var{pos} in one charset to a character with the same code position @var{pos} in another charset. If the normal file encoding is different to the default encoding, X-Symbol also resolves character aliases (@pxref{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: @itemize @bullet @item 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 (@pxref{Controlling 8bit Coding}). The modeline includes @samp{-i} to represent the file encoding (@pxref{Minor Mode}), except if the default encoding is @code{nil}, the normal file encoding is unsupported, and the variable @code{x-symbol-coding} is not specified. @item 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 (@pxref{Unique Decoding}) nor via input methods. The modeline includes @samp{-err} to represent the file encoding (@pxref{Minor Mode}). @end itemize We end with a little example: if your normal file encoding and default encoding is Latin-1, and you visit a file with @samp{\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. @node Controlling 8bit Coding, Unique Decoding, File Coding, Conversion @comment node-name, next, previous, up @subsection Store or Encode 8bit Characters @cindex Storing 8bit Characters @cindex Controlling 8bit Coding @c @cindex Buffer 8bit Control @cindex 8bit Coding Control @cindex Latin in File You can specify that 8bit characters (according to the coding in your file, see @ref{File Coding}), are not encoded to tokens (when saving a file), by setting the following buffer-local variable: @vtable @code @item 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 (@pxref{File Variables,,,@value{emacs},@value{emacsman}}), e.g.: @example %% Local Variables: %% x-symbol-8bits: t %% End: @end example @end vtable If the variable is not already buffer-local, a reasonable value is deduced when turning on X-Symbol (@pxref{Minor Mode}) by setting it the the value of @code{x-symbol-coding}, or searching in the file for 8bit characters: @vtable @code @item 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. @end vtable If the file encoding is invalid (@pxref{File Coding}), we always search for 8bit characters in the complete document and set @code{x-symbol-8bits} accordingly. Then, a non-@code{nil} value also implies unique decoding (@pxref{Unique Decoding}). While the variable @code{x-symbol-8bits} usually only influences the encoding, it also influences the decoding if you choose to decode uniquely (@pxref{Unique Decoding}). Setting variable @code{x-symbol-8bits} to @code{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 (@pxref{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 (@pxref{Introducing Input Methods}), you have probably copied them into the current buffer. @node Unique Decoding, Conversion Commands, Controlling 8bit Coding, Conversion @comment node-name, next, previous, up @subsection Unique Decoding @cindex Unique Decoding @cindex Restricted Decoding @cindex Unique @TeX{} macro Token languages might define more than one token representing the same character. When decoding and encoding these tokens, they will be @dfn{normalized} to one form, the @dfn{canonical representation}. E.g., with language @code{tex}, visiting a file with tokens @code{\neq} and @code{\ne} converts both tokens to character @code{lessequal}, saving the buffer stores the character as token @code{\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 (@pxref{TeX Macro Problems})! For this reason, package X-Symbol provides the following buffer-local variable: @vtable @code @item 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 @code{x-symbol-8bits} is non-@code{nil} (@pxref{Controlling 8bit Coding}), do not decode tokens which would be decoded to 8bit characters (according to the coding in your file, see @ref{File Coding}). You can set this variable in the ``local variables list'' near the end of the file (@pxref{File Variables,,,@value{emacs},@value{emacsman}}), e.g., together with a setting for @code{x-symbol-8bits}: @example %% Local Variables: %% x-symbol-8bits: t %% x-symbol-unique: t %% End: @end example @end vtable If the variable is not already buffer-local, a reasonable value is deduced when turning on X-Symbol (@pxref{Minor Mode}): it will be set to @code{t} if X-Symbol mode is not automatically turned on. If the file encoding is invalid (@pxref{File Coding}) and @code{x-symbol-8bits} is non-@code{nil} (@pxref{Controlling 8bit Coding}), X-Symbol always uses unique decoding (@pxref{Unique Decoding}). @node Conversion Commands, Copy with Conversion, Unique Decoding, Conversion @comment node-name, next, previous, up @subsection Conversion Commands @cindex Conversion Commands @cindex Automatic Conversion @cindex Interactive Conversion @cindex Explicit Conversion First the good news: most of the time, the necessary conversions are performed automatically when you would expect them to be performed: @itemize @bullet @item Turning X-Symbol minor mode (@pxref{Minor Mode}) on/off also performs decoding/encoding. @item 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). @item Inserting a file into a buffer where X-Symbol is enabled will decode the tokens in the inserted region. @end itemize 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): @table @kbd @item M-x x-symbol-decode-recode @findex x-symbol-decode-recode Recode all characters (if necessary) and decode all tokens to characters. @item M-x x-symbol-decode @findex x-symbol-decode Decode all tokens to characters, do not recode characters. @item M-x x-symbol-encode-recode @findex x-symbol-encode-recode Encode all characters in buffer to tokens or recode them. @item M-x x-symbol-encode @findex 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 @code{x-symbol-8bits} is relative to the file coding, see @ref{Controlling 8bit Coding}. @end table 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 (@pxref{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. @node Copy with Conversion, Char Aliases, Conversion Commands, Conversion @comment node-name, next, previous, up @subsection Copy & Paste with Conversion @cindex Copy and Conversion @cindex Copy Encoded @cindex Paste and Conversion @cindex Paste Decoded @cindex Yank Decoded You probably use X-Symbol, because you want to produce some non-@sc{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-@sc{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 @code{plusminus} from a LaTeX buffer to a HTML buffer, you really copy that character and not the three characters of the TeX macro @code{\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): @table @kbd @item M-x x-symbol-copy-region-encoded @findex x-symbol-copy-region-encoded @vindex kill-ring Save the region in the @code{kill-ring} with all X-Symbol characters encoded like by @kbd{M-x x-symbol-encode}, i.e., without recoding. @item M-x x-symbol-yank-decoded @findex x-symbol-yank-decoded Reinsert the last text in the @code{kill-ring} and decode the inserted text like @kbd{M-x x-symbol-decode}, i.e., without recoding. @end table You could get the same result with the usual copy & paste commands and the conversion commands from the previous section (@pxref{Conversion Commands}), but this would clutter the undo information of the current buffer and would require an additional undo operation for the copy. @node Char Aliases, , Copy with Conversion, Conversion @comment node-name, next, previous, up @subsection Character Aliases @cindex Char Aliases @cindex Character Aliases @cindex Aliases of Characters @cindex Latin Character Aliases @cindex Remapping Characters A @dfn{character alias} or @dfn{char alias} is a character which is also a character in a font with another registry, e.g., @code{adiaeresis} is defined in all supported Latin fonts. Emacs distinguish between these five characters. In package X-Symbol, one of them, with @code{x-symbol-default-coding} (@pxref{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 @code{adiaeresis}es and that there are neither different @code{adiaeresis}es in Unicode nor in the token representations of languages @code{tex} and @code{sgml}. 8bit characters in files with a file coding @code{x-symbol-coding} other than @code{x-symbol-default-coding} are converted to the ``normal'' form. E.g., if you have a Latin-1 font by default, the @code{adiaeresis} in a Latin-2 encoded file is a Latin-1 @code{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 @file{european.el}. In XEmacs without Mule support, this is only possible if you use commands like @kbd{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): @table @kbd @item M-x x-symbol-unalias @findex x-symbol-unalias Resolve all character aliases in buffer. If the region is active, only resolve char aliases in the region. @end table A single char alias before point can be resolved by command @code{x-symbol-modify-key} and @code{x-symbol-rotate-key}, see @ref{Input Method Context}. @pindex latin-unity The XEmacs package @code{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. @c =========================================================================== @node Minor Mode, Poor Mans Mule, Conversion, Concepts @comment node-name, next, previous, up @section Minor Mode @cindex Minor Mode @cindex Mode @cindex X-Symbol Mode X-Symbol is a minor mode (@pxref{Minor Modes,,,@value{emacs},@value{emacsman}}) which enables the features mentioned in this manual: @itemize @bullet @item X-Symbol mode is required to do the conversions. Turning the minor mode on/off also includes decoding/encoding (@pxref{Conversion Commands}). @item X-Symbol mode provides the minor mode menu which includes: various commands, commands to insert characters (@pxref{Input Method Menu}), and entries to change some global and buffer-local variables mentioned in this manual. @item X-Symbol mode is required for most input methods (@pxref{Input Methods}) and other features (@pxref{Features}). @end itemize 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: @table @kbd @item M-x x-symbol-mode @findex x-symbol-mode @vindex 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 (@kbd{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., @code{vm-mode} (@pxref{FAQ News and Mail}). Use a prefix argument to be asked whether to turn in on anyway. @end table 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 (@pxref{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: @vtable @code @item 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): @itemize @minus @item @code{x-symbol-token-language} (@pxref{Token Language}), indicated in the modeline, e.g. @samp{tex}, @item @code{x-symbol-mode}, i.e., whether it is appropriate to turn on X-Symbol mode automatically, @item @code{x-symbol-coding} (@pxref{File Coding}), indicated in the modeline if different from the default coding, e.g. @samp{-l2} for Latin-2, @item @code{x-symbol-8bits} (@pxref{Controlling 8bit Coding}), indicated in the modeline by @samp{8}, @item @code{x-symbol-unique} (@pxref{Unique Decoding}), indicated in the modeline by @samp{*}, @item @code{x-symbol-subscripts} (@pxref{Super and Subscripts}), indicated in the modeline by @samp{s}, @item @code{x-symbol-image} (@pxref{Images}), indicated in the modeline by @samp{i}, @end itemize @item x-symbol-@var{lang}-modes Major modes which use token language @var{lang} by default. @xref{Supported Languages}. The languages are checked in registration order (the order shown in the language selection submenus). @item x-symbol-@var{lang}-auto-style Default values for the above mentioned variables @code{x-symbol-mode}, @code{x-symbol-coding}, @code{x-symbol-8bits}, @code{x-symbol-unique}, @code{x-symbol-subscripts}, and @code{x-symbol-image} if not already buffer-local. @item x-symbol-auto-mode-suffixes Regular expression matching file suffixes to be ignored when checking file names for the derivation above, e.g., extension @file{.orig}. @item x-symbol-modeline-state-list This variable controls the modeline appearance just mentioned. The menu might also include individual entries for a token language (@pxref{TeX Macro Basics}): @item x-symbol-@var{lang}-extra-menu-items Extra menu items for each token language @var{lang} (@pxref{TeX Macro Basics}). @end vtable @c ==================================================================== @node Poor Mans Mule, Role of font-lock, Minor Mode, Concepts @comment node-name, next, previous, up @section Poor Man's Mule: Running Under XEmacs/no-Mule @cindex Poor Man's Mule @cindex No Mule @cindex XEmacs without 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 (@pxref{Default Coding}) are represented by two characters, see @ref{Char Representation}. This can lead to a lot of problems, which are resolved by the following methods (some annoyances remain, @pxref{Nomule Problems}) when X-Symbol mode is turned on (@pxref{Minor Mode}): @itemize @bullet @item 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. @item Package @code{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 @ref{Role of font-lock}. @ftable @code @item x-symbol-nomule-fontify-cstrings Alternatively to enabling @code{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 @code{reftex}. @end ftable @end itemize @c ==================================================================== @node Role of font-lock, Char Group, Poor Mans Mule, Concepts @comment node-name, next, previous, up @section The Role of @code{font-lock} @cindex Role of @code{font-lock} @cindex @code{font-lock} Use @cindex Special Fonts Package X-Symbol uses package @code{font-lock} to display super- and subscripts (@pxref{Super and Subscripts}) and to display its special characters under XEmacs/no-Mule (@pxref{Poor Mans Mule}). Thus, you should enable @code{font-lock} in buffers where you want to use X-Symbol (it is by default). @xref{Syntax Hiliting Packages}. When X-Symbol mode is turned on, it automatically adds the necessary font-lock keywords to the buffer-local value of @code{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 @code{font-lock} might not yet been turned on or since you might want to change @code{font-lock}s decoration of the current buffer after X-Symbol has been turned on. Please note that switching the mode by typing @kbd{M-x latex-mode} @emph{does not set} the La@TeX{}'s font-lock keywords! They are set at the end of @kbd{C-x C-f}. If you switch the mode, turn on @code{font-lock} by yourself. Independently from package X-Symbol, the following command might be useful in some situations: @table @kbd @item M-x x-symbol-fontify @findex x-symbol-fontify Refontify buffer. @end table @c ==================================================================== @node Char Group, , Role of font-lock, Concepts @comment node-name, next, previous, up @section Character Group and Token Classes @cindex Character Group @cindex Group of Characters @cindex Similar Characters @cindex Category of Character @cindex Syntax of Character @cindex Token Classes @cindex Classes of Tokens @cindex Coloring Scheme Each X-Symbol character belongs to a @dfn{character group}, e.g., @code{natnums} belongs to @code{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: @itemize @bullet @item The Grid and submenu header under which the character can be found (@pxref{Input Method Grid}, @ref{Input Method Menu}). @item The default bindings of characters (@pxref{Input Method Keyboard}) of some groups. @item Whether to show the context info for a character (@pxref{Info}). @item The default @sc{ascii} representation of a character (@pxref{Ascii Representation}). @item When using Emacs/XEmacs with Mule support, the syntax of a character (@pxref{Syntax,,,@value{emacs},@value{emacsman}}). @end itemize The character group is independent from any token language, but is probably somewhat related to some of its @dfn{token classes}. For each token language, each character is assigned to a list of token classes, which can be used for the following: @itemize @bullet @item Information in the echo area (@pxref{Info}), it could inform users to include a specific La@TeX{} package when they want to use that character in the document. @item Using a @dfn{coloring scheme} when displaying the characters in the echo area (@pxref{Info}) or the Grid of characters (@pxref{Input Method Grid}), useful for characters which can just be used in a specific context, like @TeX{}'s math-mode characters. @item Restricting the ``electricity'' of input method Electric (@pxref{Input Method Electric}), useful to disable this input methods for @TeX{}'s math-mode characters if we are in text-mode. @end itemize The token classes for individual token languages are explained in the corresponding sections of @ref{Supported Languages}: @vtable @code @item x-symbol-@var{lang}-header-groups-alist The Grid and Menu headers for each token language @var{lang}. @item x-symbol-@var{lang}-class-alist Strings for the character info in the echo area for each token language @var{lang}. @item x-symbol-@var{lang}-class-face-alist The coloring scheme for each token language @var{lang}. @end vtable @c =========================================================================== @node Input Methods, Features, Concepts, Top @comment node-name, next, previous, up @chapter X-Symbol's Input Methods @cindex Input Methods @cindex Character Insertion An X-Symbol @dfn{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 @uref{@value{url}/details.html,web pages of X-Symbol}. 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 Auc@TeX{}, Version 9.8a or higher, its math mode commands also inserts X-Symbol characters (@pxref{Mathematics,,,@value{auctex},@value{auctexman}}). @menu * Introducing Input Methods:: Common behavior of all input methods. * Input Method Token:: Replace token by character. * Input Method Read Token:: Minibuffer input with completion. * Input Method Menu:: Select a menu item. * Input Method Grid:: Choose highlighted character. * Input Method Keyboard:: Compose a key sequence. * Input Method Context:: Replace character sequence. * Input Method Electric:: Automatically replace character sequence. * Input Method Quail:: A Mule input method "x-symbol". * Customizing Input Method:: How to customize the input methods. @end menu @c =========================================================================== @node Introducing Input Methods, Input Method Token, Input Methods, Input Methods @comment node-name, next, previous, up @section Common Behavior of All Input Methods @cindex Input Methods, General @cindex Input Methods, Common @cindex Input Methods, Standard @cindex Valid Character @cindex Allowed Character @cindex Key Prefix @cindex Prefix Argument @cindex Prefix Key @cindex Defined Character @cindex Compose Key Input methods normally just inserts @dfn{valid characters} which are those characters which have a useful representation in the file: @vtable @code @item 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 @code{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 @code{x-symbol-language} (@pxref{Token Language}). @end vtable If a buffer is read-only (@pxref{Misc Buffer,,,@value{emacs},@value{emacsman}}), most input methods push the character to insert onto the kill ring instead. Typing @kbd{C-y} lets you then insert the character (@pxref{Yanking,,,@value{emacs},@value{emacsman}}). The input methods Keyboard, Menu and Grid (the character selection with @kbd{@key{button2}}) have the same interpretation of the prefix argument: @itemize @bullet @item With prefix argument @samp{0}, do not insert anything, just barf, if the character is not valid. @item With a positive prefix argument, insert a character that many times. Barf, if the character is not valid. @item 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. @item With one or more @kbd{C-u}s with no digits, insert the token of a language to choose, including ``x-symbol charsym'' (@pxref{Pseudo Language}). @end itemize Many input commands of package X-Symbol uses the same key prefix in its default binding: @vtable @code @item x-symbol-compose-key @kindex C-= @kindex @key{multi-key} By default, @kbd{C-=} is used as the key prefix. Under XEmacs/no-Mule, you might want to use @kbd{@key{multi-key}} instead: @lisp (unless (featurep 'mule) (setq x-symbol-compose-key '(multi-key))) @end lisp @item x-symbol-auto-key-autoload Set this to @code{nil}, if you do not want that pressing @kbd{C-=} automatically initializes the input methods. @end vtable @c =========================================================================== @node Input Method Token, Input Method Read Token, Introducing Input Methods, Input Methods @comment node-name, next, previous, up @section Input Method Token: Replace Token by Character @cindex Input Method Token @cindex Token, Input Method @cindex Replace Token @cindex Abbrev, Token @c pre-2.2 If X-Symbol mode is on, input method @dfn{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 (@kbd{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 @code{font-lock} which highlights the token to look like a character. You might want to press @kbd{C-/} or @kbd{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: @vtable @code @item x-symbol-token-input A boolean which can also be changed via the X-Symbol menu. @end vtable Individual token language might slightly change the way input method Token works exactly; from the predefined language, it is just @code{tex} (@pxref{TeX Macro}). @c =========================================================================== @node Input Method Read Token, Input Method Menu, Input Method Token, Input Methods @comment node-name, next, previous, up @section Input Method Read Token: Minibuffer Completion @cindex Input Method Read Token @cindex Read Token, Input Method @cindex Minibuffer Completion, Token You can insert a character by reading the corresponding token in the minibuffer. You are offered completion over the known tokens (@pxref{Completion,,,@value{emacs},@value{emacsman}}). @table @kbd @item M-x x-symbol-read-token-direct @itemx C-= @key{TAB} @findex x-symbol-read-token-direct @kindex C-= @key{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'' (@pxref{Pseudo Language}). @item M-x x-symbol-read-token @itemx C-= @key{RET} @findex x-symbol-read-token @kindex C-= @key{RET} Insert character by first selecting the token language and then a token in that language. @end table 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 @ref{Introducing Input Methods}. @c =========================================================================== @node Input Method Menu, Input Method Grid, Input Method Read Token, Input Methods @comment node-name, next, previous, up @section Input Method Menu: Select a Menu Item @cindex Input Method Menu @cindex Menu, Input Method If X-Symbol mode is turned on, a @dfn{Menu} @code{X-Symbol} appears in the menubar (@pxref{Minor Mode}). It also appears over non-highlighted parts in the Grid and the Key Completions buffer (@pxref{Input Method Grid}). The menu allows to change buffer-local and global variables (some directly, some via package @code{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 @ref{Char Group}. The appearance of the menu can be customized: @vtable @code @item 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. @item 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. @end vtable 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 @ref{Introducing Input Methods}. @c =========================================================================== @node Input Method Grid, Input Method Keyboard, Input Method Menu, Input Methods @comment node-name, next, previous, up @section Input Method Grid: Choose Highlighted Character @cindex Input Method Grid @cindex Grid, Input Method @cindex Table of Characters @cindex Highlighted Character Probably the easiest way to insert a character is by using a @dfn{Grid} of characters: @table @kbd @item M-x x-symbol-grid @itemx C-= C-= @findex x-symbol-grid @kindex C-= C-= Pops up a buffer displaying X-Symbol characters in a grid like fashion. You can select a character with the mouse or @kbd{@key{RET}}, see below. @end table In the Grid buffer and the buffer with the possible completions for an X-Symbol key sequence (@pxref{Input Method Keyboard}), the following commands are used if the mouse pointer is over an highlighted character. @table @kbd @item @key{button2} @itemx @key{RET} @itemx @key{SPC} @c @itemx x-symbol-list-selected @kindex @key{button2} @kindex @key{RET} @kindex @key{SPC} @c @findex x-symbol-list-selected Insert highlighted character (or character under point, respectively) into the buffer of @code{point} if @code{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.) @item @key{button3} @kindex @key{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 (@pxref{Token Language}). @end table Over all non-highlighted parts, the following commands are used: @table @kbd @item @key{button2} @kindex @key{button2} @c @findex x-symbol-list-selected Scroll Grid or Key Completions buffer down in upper half of the window and scroll up in the lower half of the window. @item @key{button3} @kindex @key{button3} Pops up the X-Symbol menu, see @ref{Input Method Menu}). @end table When using the keyboard to select a character, the following command could be useful: @table @kbd @item M-x x-symbol-list-info @itemx ? @itemx h @itemx i @findex x-symbol-list-info @kindex ? @kindex h @kindex i Display info for character under point in echo area. @item M-x x-symbol-list-bury @itemx q @findex x-symbol-list-bury @kindex q Bury list buffer while trying to use the old window configuration. @end table You can control the grid by the following variables: @vtable @code @item 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. @item x-symbol-temp-grid Inserting an X-Symbol character does not restore the window configuration current before the invocation of the Grid. @item x-symbol-grid-reuse Use old Grid when invoking command @code{x-symbol-grid}, if this is reasonably to do. If @code{x-symbol-grid} is called with a prefix argument, always create new Grid. @item x-symbol-grid-ignore-charsyms The Grid does not contain @code{nobreakspace}. @item x-symbol-grid-tab-width The tab width in the Grid buffer should correspond the font in @code{x-symbol-heading-face} which is also used as the default font in the Grid buffer. @item x-symbol-heading-strut-glyph Use larger interline spacing if a line in the Grid starts with a header. @end vtable The headers in the Grid are the same as the submenu headers, see @ref{Char Group}. Similar looking characters for one headers are grouped together. @xref{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 @ref{Introducing Input Methods}. @c =========================================================================== @node Input Method Keyboard, Input Method Context, Input Method Grid, Input Methods @comment node-name, next, previous, up @section Input Method Keyboard: Compose Key Sequence @cindex Input Method Keyboard @cindex Keyboard, Input Method Key sequences starting with @kbd{C-=} (@pxref{Introducing Input Methods}) are used to insert X-Symbol characters, e.g., @kbd{C-= ~ >} inserts @code{leadsto}. The Ascii sequence of the keys after @kbd{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 @ref{Input Method Context}. If many characters are represented by the same Ascii sequence, the binding is extended by @samp{1}, @samp{2} and so on. If you do not know how to continue your key sequence, the following commands might be useful: @table @kbd @item M-x x-symbol-help @itemx C-= @var{zero-or-more-keys} @key{help} @itemx C-= @var{zero-or-more-keys} C-h @findex x-symbol-help @kindex C-= @key{help} @kindex C-= C-h @kindex @key{help} @kindex C-h Pops up a buffer displaying possible completions for the key sequence @kbd{C-= @var{zero-or-more-keys}}. You do not have to type the key sequence again, i.e., @kbd{C-= @var{zero-or-more-keys}} is also used for the next input. @item C-= @var{zero-or-more-keys} @key{button1} @itemx C-= @var{zero-or-more-keys} @key{button2} @itemx C-= @var{zero-or-more-keys} @key{button3} @kindex @key{button1} @kindex @key{button2} @kindex @key{button3} Use the normal bindings of @kbd{@key{button1}}, @kbd{@key{button2}} or @kbd{@key{button3}}, respectively (@pxref{Input Method Grid}). The key sequence is not used for the next input. @item C-= @var{zero-or-more-keys} M-@key{prior} @itemx C-= @var{zero-or-more-keys} M-@key{next} @itemx C-= @var{zero-or-more-keys} M-@key{home} @itemx C-= @var{zero-or-more-keys} M-@key{end} @kindex M-@key{prior} @kindex M-@key{next} @kindex M-@key{home} @kindex M-@key{end} Execute the commands @code{scroll-other-window-down}, @code{scroll-other-window}, @code{beginning-of-buffer-other-window} or @code{end-of-buffer-other-window}, respectively. You do not have to type the key sequence again, i.e., @kbd{C-= @var{zero-or-more-keys}} is also used for the next input. @end table @vtable @code @item x-symbol-temp-help Inserting an X-Symbol character restores the window configuration current before the invocation of the Grid. @item x-symbol-map-default-keys-alist Defines the bindings mentioned above. @end vtable 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 @ref{Introducing Input Methods}. @c =========================================================================== @node Input Method Context, Input Method Electric, Input Method Keyboard, Input Methods @comment node-name, next, previous, up @section Input Method Context: Replace Char Sequence @cindex Context, Input Method @cindex Input Method Context @cindex Character Sequence Input @cindex Ascii Sequence Input @cindex Modify Chain @cindex Rotate Chain @cindex Greek Input The idea of the input method @dfn{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 @ref{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: @table @kbd @item M-x x-symbol-modify-key @itemx C-, @itemx C-= @key{left} @itemx C-= @key{right} @findex x-symbol-modify-key @kindex C-, @kindex C-= @key{left} @kindex C-= @key{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. @item M-x x-symbol-rotate-key @itemx C-. @itemx C-= @key{up} @itemx C-= @key{down} @findex x-symbol-rotate-key @kindex C-. @kindex C-= @key{up} @kindex C-= @key{down} If character before point is an X-Symbol character, ``rotate'' its ``direction'' (or change uppercase/lowercase). @end table Both commands can also be used to resolve a character alias before point, see @ref{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: @vtable @code @item x-symbol-rotate-prefix-alist If you provide a prefix argument to command @code{x-symbol-rotate-key}, you can specify the direction you want to have: it is according to numerical keypads, e.g., with prefix argument @samp{7} you specify the direction ``north-west''. @item x-symbol-rotate-suffix-char Command @code{x-symbol-rotate-key} is also used to ``Greekify'' the previous character: typing @kbd{a C-.} is shorter than @kbd{a # C-,}. @item x-symbol-context-ignore Constrains whether a context/charsym can be replaced. No constraints by default. @item x-symbol-context-init-ignore Contexts starting with a space cannot be replaced. This variable must be set before X-Symbol has been initialized. @end vtable @c =========================================================================== @node Input Method Electric, Input Method Quail, Input Method Context, Input Methods @comment node-name, next, previous, up @section Input Method Electric: Automatic Context @cindex Input Method Electric @cindex Electric, Input Method @cindex Aggressive Context @c 2.6 @cindex Automatic Context The idea of input method @dfn{Electric} is to have the input method Context (@pxref{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 (@pxref{Super and Subscripts}). You might want to press @kbd{C-/} or @kbd{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: @vtable @code @item x-symbol-electric-input A boolean which can also be changed via the X-Symbol menu. @end vtable To make input method Electric useful and not annoying, several conditions must be met for X-Symbol to do the auto-replacement: @itemize @bullet @item Not all contexts will be replaced automatically. E.g., while input method Context allows both pre- and postfixes for accented characters, @kbd{:} and @kbd{'} only act as prefixes, and @kbd{`} and @kbd{~} only as postfixes for input method Electric, since these are the combinations where those characters are quite likely not used literally. @item The character must be valid in the current token language, see @ref{Introducing Input Methods}. @item All characters of the context have been typed without any other command in between, e.g., @kbd{- >} inserts @code{arrowright}, "- @key{left} @key{right} > simply inserts @samp{->}. @item No prefix argument has been used for any character in the context. @item The electric context must not be a suffix of a longer valid context for another character. E.g., @kbd{' ' o} does not insert @samp{'@code{oacute}} because @samp{''o} is the context for @code{ohungarumlaut} (which cannot be inserted by input method Electric). @item It should be ``allowed'' to change the context to the character via input method Context. @item Individual contexts/charsyms can be disabled by setting the following variables: @vtable @code @item x-symbol-electric-ignore The context should neither be @samp{'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 @lisp (setq x-symbol-electric-ignore "[ \t]\\|[A-Za-z][~`]\\|[:'][A-Za-z]") @end lisp @item x-symbol-@var{lang}-electric-ignore Individual contexts/charsyms can be disabled for each token language @var{lang}. @end vtable @end itemize @c =========================================================================== @node Input Method Quail, Customizing Input Method, Input Method Electric, Input Methods @comment node-name, next, previous, up @section Input Method Quail: a Mule Input Method @cindex Input Method Quail @cindex Mule Input Method Another way to insert a characters is by using the Emacs/Mule multilingual text input method ``x-symbol'' (@pxref{Input Methods,,,@value{emacs},@value{emacsman}}).. Again, the Ascii sequence used there is the same as the sequence which is replaced by input method Context, see @ref{Input Method Context}. A one-letter key sequence is extended by @key{;}. If input method Quail is selected for a buffer, input method Electric (@pxref{Input Method Electric}) is disabled in that buffer. @c TODO: more @c =========================================================================== @node Customizing Input Method, , Input Method Quail, Input Methods @comment node-name, next, previous, up @section Customizing Input Methods @cindex Customizing Method Internals @cindex Input Methods Customization You may safely define key bindings not using the @code{x-symbol-map} (i.e., starting with @kbd{C-=}). E.g., for @code{alpha} on @kbd{A-a} , use @lisp (global-set-key [(alt a)] 'x-symbol-INSERT-alpha) @end lisp Please note that the command @code{x-symbol-INSERT-alpha} is not defined before the main file (@file{x-symbol}) in the package has been loaded (if you really need it, function @code{autoload} is your friend). Other possibilities to customize the input methods are by setting the following variables: @vtable @code @item x-symbol-header-groups-alist Defines the groups whose characters appear after that header in the Grid and in submenus with that header. @xref{Char Group}. Extra variables exists for the language dependent Grid and Menu. @item x-symbol-group-input-alist @itemx 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. @xref{Defining Input Methods}. For example, if you prefer charsym @code{epsilon1} over @code{epsilon} you might want to use: @lisp @group (setq x-symbol-user-table '((epsilon1 t (greek1 "e" nil "epsilon") nil -3000))) @end group @end lisp @item x-symbol-list-mode-hook Additional functions to execute after setting up the Grid and Key Completions buffer. @item x-symbol-after-init-input-hook You can change the input methods directly by functions in these hooks. @end vtable @c =========================================================================== @node Features, Supported Languages, Input Methods, Top @comment node-name, next, previous, up @chapter Features of Package X-Symbol @cindex Features of X-Symbol @cindex Supported Features 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. @menu * Super and Subscripts:: Use special fonts for super-/subscripts. * Images:: Images after image insertion commands. * Info:: Display information in echo area. * Ascii Representation:: Derive label from a buffer contents. * Package Information:: Invoke info system, use WWW browser. @end menu @c =========================================================================== @node Super and Subscripts, Images, Features, Features @comment node-name, next, previous, up @section Super- and Subscripts @cindex Superscripts @cindex Subscripts @cindex Invisible, Revealing @cindex Point, Invisible @cindex Cursor, Invisible @cindex Keywords for 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 @samp{a^2} in the buffer are @emph{displayed} as an @samp{a} and a raised, smaller @samp{2}---the @samp{^} is still in the buffer. Therefore, the display of super- and subscripts has nothing to do with Input Method Electric (@pxref{Input Method Electric}). Do not confuse the special Latin characters @code{twosuperior}, @code{threesuperior}, @code{ordfeminine} and @code{masculine} with the characters @samp{2}, @samp{3}, @samp{a} and @samp{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 (@pxref{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 @code{font-lock} to be enabled (@pxref{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 (@pxref{Minor Mode}). They can be disabled (and re-enabled) by setting the following buffer-local variable: @vtable @code @item x-symbol-subscripts A boolean which can also be changed via the X-Symbol menu. @end vtable 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: @vtable @code @item x-symbol-reveal-invisible A boolean which can also be changed via the X-Symbol menu. @item x-symbol-revealed-face The face used for the super-/subscript command when revealed. @item x-symbol-idle-delay Time in seconds of idle time before revealing invisible characters. @end vtable Super-/subscript commands are @code{^}/@code{_} (@pxref{TeX Macro}) and @code{}/@code{} (@pxref{SGML Entity}): @c =========================================================================== @node Images, Info, Super and Subscripts, Features @comment node-name, next, previous, up @section Images at the end of Image Insertion Commands @cindex Images @cindex Glyphs @pindex convert Package X-Symbol can display @dfn{images} at the end of image insertion commands. They show thumbnails (scaled-down version of the image) for the included image files (using @code{convert}, @pxref{Installing Image Converter}). Using the middle mouse button invokes the image editor for the image under the mouse pointer. @menu * Image Display:: When to display images. * Image Conversion:: Producing a scaled-down image. * Image Caching:: Speeding up the image processing. * Special Images:: Signaling specific situations. * Image Editor:: Editing the original image file. @end menu @node Image Display, Image Conversion, Images, Images @comment node-name, next, previous, up @subsection Display of Images @cindex Image Display @cindex Image Control @cindex Image Commands @cindex Controlling Images @cindex Image Keywords @cindex Keywords for 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 (@pxref{Minor Mode}). It can be disabled (and re-enabled) by setting the following buffer-local variable: @vtable @code @item x-symbol-image A boolean which can also be changed via the X-Symbol menu. @end vtable Image commands are @code{\includegraphics} and others (@pxref{TeX Macro}), and @code{} (@pxref{SGML Entity}): @vtable @code @item x-symbol-@var{lang}-image-keywords The keywords (image commands & arguments) for each token language @var{lang}. @end vtable File names in the image commands must be interpreted correctly. They can be: @itemize @minus @item @dfn{absolute}, start with @samp{/} or @samp{~}, @item @dfn{explicitly relative}, start with @samp{./} or @samp{../}, @item @dfn{implicitly relative}, assumed otherwise, e.g., @file{image.eps}, or @item special, like having some special URL prefix like @file{http:} or @file{ftp:}. @end itemize Relative file names can be relative to some @dfn{master directory} (usually the current directory of the file) or to directories in some @dfn{search path} (only used with token language @code{tex}): @vtable @code @item x-symbol-@var{lang}-master-directory The master directory for each token language @var{lang}. @item x-symbol-@var{lang}-image-searchpath The image search path for each token language @var{lang}. Defaults to the current directory. @item x-symbol-image-searchpath-follow-symlink Directories in the search path ending with @file{//} (double slash) are recursive: all subdirectories not starting with a dot are also included in the search path. If this variable has value @code{nil} (the default), subdirectories which are symbolic links are not included. @end vtable For details, see the section of the individual token languages (@pxref{Supported Languages}). @node Image Conversion, Image Caching, Image Display, Images @comment node-name, next, previous, up @subsection Image Conversion @cindex Image Conversion @cindex Converting Images @cindex Colormap @cindex Image Cache File 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 @dfn{image cache file}, see @ref{Image Caching}. @vtable @code @item x-symbol-image-max-width The image is not wider than 120 points. @item x-symbol-image-max-height The image is not higher than 80 points. @item x-symbol-image-convert-colormap Colormap used in function @code{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: @file{etc/colormap138.xpm} and @file{etc/colormap66.xpm}. @item x-symbol-image-colormap-allocation Package X-Symbol allocates the colors of the colormap at start-up and prevents them to be de-allocated. @item x-symbol-image-converter @pindex convert Program @code{convert} from ImageMagick is used to convert the images (@pxref{Installing Image Converter}). Set this variable to @code{nil}, if you don't want to convert images. The following variables controls the invocation of the program @code{convert} from ImageMagick: @vtable @code @item x-symbol-image-convert-program The name of the program @code{convert}, it is @samp{C:\\ImageMagick\\convert} when running on Windows and @samp{convert} otherwise. @item x-symbol-image-convert-file-alist Program @code{convert} needs to be told that @file{@var{file}.pstex} is a Postscript file. @end vtable The following functions are possible values in @code{x-symbol-image-converter}: @ftable @code @item x-symbol-image-start-convert-mono Produces monochrome images. Used if your device has less than 32 colors. @item x-symbol-image-start-convert-truecolor Produce images with original colors. Used if your device has more than 767 colors. @item 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. @item x-symbol-image-start-convert-colormap Produce image with colors from the colormap. Used otherwise with a colormap. @vtable @code @item x-symbol-image-convert-mono-regexp Function @code{x-symbol-image-start-convert-colormap} just produces monochrome images for temporary image cache files (@pxref{Image Caching}) since @code{convert} is slower when using a colormap. @end vtable @end ftable @end vtable @node Image Caching, Special Images, Image Conversion, Images @comment node-name, next, previous, up @subsection Image Caching @cindex Image Caching @cindex Caching of Images @cindex Glyph Caching @cindex Memory Cache for Images @cindex File Cache for Images 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: @itemize @bullet @item It uses an asynchronous process to create the image cache file. You can edit your file during the conversion. @item It uses a @dfn{file cache}: image cache file can be kept for future Emacs sessions. @item It uses a @dfn{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: @table @kbd @item M-x x-symbol-image-parse-buffer @findex x-symbol-image-parse-buffer Parse the buffer to recognize image insertion commands. Usually, this is done automatically. @end table @end itemize File and memory caching can be controlled by the following variables: @vtable @code @item 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. @item x-symbol-image-cache-directories Cache files for images in your home directory are stored in directory @file{~/.images/}, e.g., image @file{~/d/img.eps}, is cached in @file{~/.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 @file{~/d/img.eps} is cached in @file{~/d/.img/img.eps} or that the image is not displayed at all. @item x-symbol-image-temp-name Temporary image files are stored in a temporary directory (@file{/tmp/}) having some unique name. They are not supported on Emacs. @item x-symbol-image-use-remote Package X-Symbol only displays images which can be stored in the memory cache. With value @code{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. @end vtable The memory cache only stored image file from the current directory or some standard image directories like @file{figures/} (@pxref{TeX Macro}), or @file{images/} or @file{pictures/} (@pxref{SGML Entity}). Otherwise, the image file is considered similar to remote files: @vtable @code @item x-symbol-@var{lang}-image-cached-dirs The directories with images which are stored in the memory cache. Can be separately defined for each token language @var{lang}. @end vtable @node Special Images, Image Editor, Image Caching, Images @comment node-name, next, previous, up @subsection Special Images for Specific Situations @cindex Special Images @cindex Images for Specific Situations @cindex Glyph for Specific Situations If package X-Symbol cannot display images representing the included image files, it uses special images instead: @itemize @bullet @item @dfn{Remote:} An Escher knot is displayed if the file is remote or if the image cannot be cached in the memory cache, see @ref{Image Caching}. @item @dfn{Junk}: A recycle sign is displayed if there is no image converter (@pxref{Image Conversion}), if it should not use a file cache or if the file cache cannot be written. @item @dfn{Locked:} A terminal with a lock is displayed if the image cache file cannot be read or written. @item @dfn{Design:} An ink pen is displayed if the image file does not exist. @item @dfn{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. @item @dfn{Broken:} A tombstone is displayed if the creation of the image cache file has failed. @end itemize To customize the glyphs for the special images, use: @vtable @code @item x-symbol-image-data-directory Directory of files for the special images. @item x-symbol-image-special-glyphs File names of special images and their image format. @end vtable @node Image Editor, , Special Images, Images @comment node-name, next, previous, up @subsection Image Editor @cindex Image Editor @cindex Editing Image Files @cindex Designing Images @cindex Scale Factor, Images @cindex Image Highlight Menu If you move the mouse pointer to an image insertion command or its image, it is highlighted. @table @kbd @item @key{button2} @kindex @key{button2} Start image editor for highlighted image. If the image is searched in the searchpath (@pxref{Image Caching}), edit first existing image file. If no image exists, open a new file in the first directory of the searchpath. @item @key{button3} @kindex @key{button3} Pop up the @dfn{image highlight menu}. You can rescan the buffer for image insertion commands (@pxref{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). @item M-x x-symbol-image-editor @findex x-symbol-image-editor Start image editor. Asks for the image file. @end table You can control which editor to use: @vtable @code @item x-symbol-image-editor-alist @pindex display @pindex xfig Normally, program @code{display} is used to edit the highlighted image file. But for image names @file{@var{file}.eps}, @file{@var{file}.ps} or @file{@var{file}.pstex}, program @code{xfig} is invoked with @file{@var{file}.fig}. It also uses a scale method, e.g., with @file{img.80.eps}, we edit @file{img.fig} (which should be exported with scale=80%). @item 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. @item x-symbol-image-current-marker Directories with an existing image for the specified file name are marked with an @samp{*}. The first of these represents the file which is used when pressing @kbd{@key{button2}}. @end vtable @c =========================================================================== @node Info, Ascii Representation, Images, Features @comment node-name, next, previous, up @section Info in Echo Area @cindex Info in Echo Area @cindex Echo Area Info @cindex Character Info @cindex Context Info @cindex Minibuffer Info The echo area (@pxref{Echo Area,,,@value{emacs},@value{emacsman}}) 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 (@pxref{Input Method Context}). It will be controlled by the following variables (also to be found in the menu): @vtable @code @item 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: @itemize @minus @item the token of the current language, eventually colored according to some coloring scheme (@pxref{Char Group}), @item infos using the token classes (@pxref{Char Group}), which could inform users to include a specific La@TeX{} package when they want to use that character in the document, @item the codings in which the characters is considered to be a 8bit character (@pxref{File Coding}), and @item the key bindings (@pxref{Input Method Keyboard}). @end itemize @item 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 @kbd{C-,} (@pxref{Input Method Context}). It can be controlled by the following variables: @vtable @code @item x-symbol-context-info-ignore @findex x-symbol-default-context-info-ignore The default value @code{x-symbol-default-context-info-ignore} makes the following variables control whether to display the context info. @item x-symbol-context-info-threshold The context does not consist of a single character. @item x-symbol-context-info-ignore-regexp The context does not solely consist of letters. @item x-symbol-context-info-ignore-groups The context is not replaced by an accented character, see @ref{Char Group}. @end vtable @item x-symbol-idle-delay Time in seconds of idle time before showing the info. @end vtable @c ==================================================================== @node Ascii Representation, Package Information, Info, Features @comment node-name, next, previous, up @section Ascii Representation of Strings @cindex Ascii Representation @cindex Representation of Characters @cindex Label Creation @pindex reftex If you want to derive labels from a buffer contents (provided e.g., by Emacs packages @code{reftex} or @code{bibtex}), you need a Ascii representation of strings containing X-Symbol characters. This is provided by the following function: @ftable @code @item x-symbol-translate-to-ascii Takes a string and returns a string only consisting of Ascii characters. @vtable @code @item x-symbol-charsym-ascii-alist You might want to define the German way to Asciify accented characters by: @lisp @group (setq x-symbol-charsym-ascii-alist '((adiaeresis . "ae") (Adiaeresis . "Ae") (odiaeresis . "oe") (Odiaeresis . "Oe") (udiaeresis . "ue") (Udiaeresis . "Ue"))) @end group @end lisp @item x-symbol-charsym-ascii-groups By default, ``Ascii''fying accented characters means removing the accents. Other characters have built-in Ascii representation, e.g, @code{sigma1} has the Ascii representation @samp{sigma}. @end vtable @end ftable @c ==================================================================== @node Package Information, , Ascii Representation, Features @comment node-name, next, previous, up @section X-Symbol Package Information @cindex Package Information @cindex WWW Browsing @cindex URL for X-Symbol @table @kbd @item M-x x-symbol-package-info @findex x-symbol-package-info Read documentation for package X-Symbol in the info system. @item M-x x-symbol-package-web @findex x-symbol-package-web Ask a WWW browser to load the URL of package X-Symbol. @item M-x x-symbol-package-bug @findex x-symbol-package-bug Use this command to contact the maintainer of package X-Symbol @emph{in any case}, e.g., for suggestions, bug and problem reports, see @ref{Bug Reports}. Use @kbd{C-u 9 M-x x-symbol-package-bug} for patches (including corrections of this manual, which are strongly appreciated) and for other messages. @end table @vtable @code @item x-symbol-installer-address E-mail address of the person who has installed package X-Symbol system-wide (@pxref{System-wide Installation}). @item x-symbol-package-url URL of package X-Symbol, used by @code{x-symbol-package-web}. @end vtable @c ==================================================================== @node Supported Languages, X-Symbol Internals, Features, Top @comment node-name, next, previous, up @chapter Supported Token Languages @cindex Supported Languages @cindex Default Languages @cindex Built-in Languages @cindex Provided Languages @cindex Languages in Distribution The chapter describe the predefined token language. It also presents the language specific behavior for @ref{Concepts}, @ref{Input Methods}, and @ref{Features}. @menu * Pseudo Language:: Token language ``x-symbol charsym''. * TeX Macro:: Token language @code{tex}. * SGML Entity:: Token language @code{sgml}. * BibTeX Macro:: Token language @code{bib}. * TeXinfo Command:: Token language @code{texi}. * External Languages:: Languages defined in other Emacs Packages. @end menu @c ==================================================================== @node Pseudo Language, TeX Macro, Supported Languages, Supported Languages @comment node-name, next, previous, up @section Pseudo Token Language ``x-symbol charsym'' @cindex Pseudo Language @cindex Charsym @cindex X-Symbol Charsym If no (or an invalid) token language is set for a buffer, the info in the echo area (@pxref{Info}) for a X-Symbol Character in the buffer (if it exists) uses the name of its @dfn{charsym}. In this manual, we actually refer to X-Symbol characters by their charsym name, e.g., @code{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 (@pxref{Input Method Grid}) also offers to insert a charsym name. Charsyms can also be used for input method Read Token, see @ref{Input Method Read Token}. You cannot use this pseudo language to turn on the X-Symbol minor mode (@pxref{Minor Mode}), you cannot decode charsyms to their characters, and you cannot encode characters to charsyms. @c =========================================================================== @node TeX Macro, SGML Entity, Pseudo Language, Supported Languages @comment node-name, next, previous, up @section Token Language ``@TeX{} macro'' (@code{tex}) @cindex Token Language @code{tex} @cindex Language @code{tex} @cindex @TeX{} macro @cindex @code{tex} @cindex La@TeX{} For buffers using the major mode @code{latex-mode}, @code{tex-mode} or @code{plain-tex-mode}, we use token language @dfn{@TeX{} macro} (@code{tex}). This language provides the display of super-/subscripts and images. If the buffer visits a file with extension @file{.tex}, X-Symbol mode is automatically turned on. @menu * TeX Macro Basics:: Basics of language ``@TeX{} macro''. * TeX Macro Features:: Super-/subscripts and images in La@TeX{}. * TeX Macro Problems:: Problems with @TeX{} macros. * TeX Macro Conversion:: How the conversion of @TeX{} macros works. * TeX Macro Symbols:: Extra Symbols of Language ``@TeX{} Macro''. @end menu @node TeX Macro Basics, TeX Macro Features, TeX Macro, TeX Macro @comment node-name, next, previous, up @subsection Basics of Language ``@TeX{} macro'' @cindex TeX Macro Basics @cindex Basics TeX Macro @cindex Choosing TeX Macro @cindex TeX Macro Use @cindex TeX Macro Modes The standard behavior can be controlled by the following variables: @vtable @code @item x-symbol-tex-modes @itemx x-symbol-tex-auto-style The variables known from @ref{Minor Mode}. If the buffer visits a file with extension @file{.tex}, super-/subscripts and images are displayed, otherwise unique decoding (@pxref{Unique Decoding}) will be used. @item x-symbol-tex-auto-coding-alist Used there to automatically deduce the specific encoding of the file (@pxref{File Coding}) if the file visited by the buffer has the extension @file{.tex}. It searches for one of the following two strings in the current buffer, including the comment: @example \usepackage[@var{encoding}]@{inputenc@} %& -translation-file=i@var{enc} @end example where @var{encoding} should be one of @samp{latin1}, @samp{latin2}, @samp{latin3}, @samp{latin5}, or @samp{latin9}, and @var{enc} should be one of @samp{l1} or @samp{l2}. 8bit characters are not encoded if the file if the search was successful (@pxref{Controlling 8bit Coding}). @item x-symbol-tex-coding-master @vindex TeX-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 @code{TeX-master}, also search in the file denoted by that value for the strings. (Buffer-local variables will not be inherited.) @end vtable The input methods and the character info in the echo area are controlled by: @vtable @code @item x-symbol-tex-header-groups-alist We use the standard Grid and Menu headers. @item 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. @c TODO: detailed list of additional commands @item x-symbol-tex-electric-ignore @itemx x-symbol-tex-electric-ignore-regexp @pindex texmathp Input method Electric (@pxref{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 @code{texmathp}, see @ref{LaTeX Packages}). Postfix tilde is not electric, because @samp{~} produces a space in @TeX{}. @item x-symbol-tex-token-suppress-space Input method Token (@pxref{Input Method Token}) only converts a token ending with a control word like @code{\i}, if the character following the token is no letter. If that token is a text-mode token and a @key{SPC} has been entered without a prefix argument, the @key{SPC} will only perform the replacement, it will not insert a space, i.e., it will act like @kbd{C-u 0 @key{SPC}}. @item x-symbol-tex-class-alist @itemx x-symbol-tex-class-face-alist Various token classes (@pxref{Char Group}) are defined. They are used to give some info (@pxref{Info}) about the characters spacing behavior, which La@TeX{} packages are necessary to use the character (@pxref{TeX Macro Symbols}), and about the conversion (@pxref{TeX Macro Conversion}). X-Symbol uses blue for text-mode only and purple for math-mode only characters in the Grid (@pxref{Input Method Grid} and the character info. @end vtable @node TeX Macro Features, TeX Macro Problems, TeX Macro Basics, TeX Macro @comment node-name, next, previous, up @subsection Super-/Subscripts and Images in La@TeX{} @cindex TeX Macro Features @cindex Features TeX Macro @cindex TeX Macro Superscripts @cindex TeX Macro Subscripts @cindex TeX Macro Images The display of super- and subscripts (@pxref{Super and Subscripts}) is controlled by: @vtable @code @itemx x-symbol-tex-font-lock-limit-regexp The superscript command @code{^} and the subscript command @code{_} 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. @item x-symbol-tex-font-lock-allowed-faces The characters @samp{^} and @samp{_} are not always commands (@pxref{TeX Macro Problems}), e.g., in the argument of @code{\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: @ref{FAQ No Subscripts}, @ref{FAQ Stupid Subscripts}. Using @code{texmathp} (@pxref{LaTeX Packages}) has even more problems: @itemize @minus @item The syntax highlighting (which is used for super-/subscripts) would be much too slow. @item With own La@TeX{} environments, you would need to customize @code{texmathp}. @item It is actually wrong: whether @samp{^} and @samp{_} 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 @code{\ref}). @end itemize @end vtable The display of images (@pxref{Images}) is controlled by: @vtable @code @item x-symbol-tex-image-keywords The following commands are recognized. Extension @var{ext} stands for @file{eps} (which is the default extension for both versions of @code{\includegraphics} if the extension is omitted there), @file{ps}, @file{gif}, @file{png}, @file{jpeg}, @file{jpg}, or @file{pdf}. Options @var{options} can be omitted with their surrounding brackets or preceding comma, respectively. @example \input@{@var{file}.pstex_t@} \includegraphics[@var{options}][@var{options}]@{@var{file}.@var{ext}@} \includegraphics*[@var{options}][@var{options}]@{@var{file}.@var{ext}@} \epsfig@{file=@var{file}.@var{ext},@var{options}@} \psfig@{file=@var{file}.@var{ext},@var{options}@} \epsfbox[@var{options}]@{@var{file}.@var{ext}@} \epsffile[@var{options}]@{@var{file}.@var{ext}@} @end example @item x-symbol-tex-master-directory @vindex TeX-master Relative file names (@pxref{Image Display}, explicitly or implicitly) are relative to the directory part of variable @code{TeX-master} if it is buffer-local and a string. Otherwise, they are relative to the directory of the current file. @item x-symbol-tex-image-searchpath @vindex TEXPICTS @vindex TEXINPUTS 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 @code{TEXPICTS} or @code{TEXINPUTS} (@pxref{TeX environment variables,,,@value{kpathsea},@value{kpathseaman}}), extended by @file{./} 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 (@pxref{Path sources,,,@value{kpathsea},@value{kpathseaman}}). @item 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 @file{figures/} if the image should be cached in the memory cache. @end vtable @node TeX Macro Problems, TeX Macro Conversion, TeX Macro Features, TeX Macro @comment node-name, next, previous, up @subsection Problems with @TeX{} Macros @cindex TeX Macro Problems @cindex Problems TeX Macro 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. @xref{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: @itemize @bullet @item The tokens in @TeX{} are not ended by a dedicated character (like @sc{sgml} entities are ended by @samp{;}). 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 @dfn{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. @item 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 @samp{Ma@ss{}@ Bier}. @ifinfo In the info file, you will probably not see any 8bit characters (the sharp @samp{s} is shown as @samp{@ss{}}). @end ifinfo @itemize @minus @item Many people would use @samp{Ma\ss\@ Bier}. This is (almost ever) fine in text mode, but a @samp{\@ } 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. @item Many people would use @samp{Ma\ss@{@}@ Bier}. This has less problems and is therefore used by X-Symbol. The @samp{@{@}} at the end of the control word is not used if the character is not followed by a space, e.g., to produce @samp{Stra@ss{}e}, we use @samp{Stra\ss@ e}. Consequently, @samp{Ma\ss\@ Bier} in the file would be decoded to @samp{Ma@ss{}\@ Bier}, which would be encoded to the original sequence in the file. @item Some people would always use @samp{@{@}} after a text-mode control word, even it is not followed by a space, like @samp{Stra\ss@{@}e}. This is wrong, since it breaks ligatures and kerns. For example, compare the output of @samp{\L@ V} with @samp{\L@{@}V} using @samp{T1} font encoding. @item Up to Version 4.1, X-Symbol surrounded a text-mode control word with braces, like @samp{Stra@{\ss@}e}. This was probably even worse than always adding @samp{@{@}} at the end of the control word. It was used, because it is required by Bib@TeX{} (@pxref{BibTeX Macro}). Unfortunately, Bib@TeX{} sends this bad sequence directly to La@TeX{}, but this has nothing to do with X-Symbol. @end itemize @item The accented characters are not represented by one tokens in @TeX{}. Most people use @samp{\"a} to produce an @samp{@"a}, while some use @samp{\"@{a@}}. X-Symbol uses the former, it does not even decode the latter automatically. Up to Version 4.1, X-Symbol used @samp{@{\"a@}}, having the same problems as using @samp{Stra@{\ss@}e}. @item Around a dozen characters can be produced by more than one @TeX{} macro, like @code{\neq} and @code{\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 (@pxref{Unique Decoding}). @item 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 @samp{@@} to a letter (used in La@TeX{}'s style files), this character is considered a letter by X-Symbol. This means that although both @samp{\ss@ @@} and @samp{\ss@@} usually produce the same output, only the first is decoded to @samp{@ss{}@@}. @item 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 La@TeX{} @code{\verb} command, and the @code{verbatim} and @code{tabbing} environments. @end itemize @node TeX Macro Conversion, TeX Macro Symbols, TeX Macro Problems, TeX Macro @comment node-name, next, previous, up @subsection The Conversion of @TeX{} Macros @cindex TeX Macro Conversion @cindex Conversion of TeX Macros The @TeX{} macros for Latin characters are according to the La@TeX{} package @file{inputenc.sty}, v0.97+. Package X-Symbol uses U00B5 for @code{\mathmicro}, not for @code{\mu}, though! @xref{Wishlist LaTeX}. It is assumed that you do not redefine standard @TeX{} macros like @code{\ne} (@pxref{TeX Macro Conversion}), if you do so, you should better use unique decoding (@pxref{Unique Decoding}). The encoding of characters to @TeX{} macros works as follows: @itemize @bullet @item If the character is preceded by an odd number of backslashes, insert a space before the character. @item Accented characters are encoded without braces, e.g., we encode @samp{@,{c}} to @samp{\c@ c}. Accents are encoded with braces, e.g., we use @samp{\c@{@ @}} and @samp{\u@{@}}. @end itemize Additionally, the encoding of characters to @TeX{} macros which are @dfn{control words} (all-letter macros), or whose @TeX{} representation ends with a control word (like @samp{\'\i}) works as follows: @itemize @bullet @item If the character is followed by a letter, replace the character by the macro and insert a space. @item If the macro is a text-mode macro and followed by one or more blanks, replace the character and insert @samp{@{@}}. @item Otherwise, just replace the character. @end itemize The decoding of @TeX{} macros which are control words to characters works as follows: @itemize @bullet @item If the macro is a text-mode macro and followed by @samp{@{@}} which is followed by a blank, replace the macro and delete the braces. @item If the macro is a text-mode macro and followed by one are more blanks, we have the following rule: @itemize @minus @item If we have exactly one blank, the blank is a space, and it is not followed by a @samp{%} (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 @ref{Unique Decoding}.) @item Otherwise, do @emph{not decode} the macro! @end itemize @item Otherwise, just replace the macro. @end itemize To clarify, @dfn{letter} means @samp{A}-@samp{Z}, @samp{a}-@samp{z}, or @samp{@@}, @dfn{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: @code{\ldots}, @code{\vdots}, and (by accident) @code{\angle}. They are all treated like math-mode characters, but their minibuffer info (@pxref{Info}) includes @samp{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): @vtable @code @item x-symbol-tex-verb-delimiter-regexp If the command @code{\verb} is found, its argument is not decoded if it is delimited by one of the following characters: @samp{-}, @samp{!}, @samp{#}, @samp{$}, @samp{&}, @samp{*}, @samp{+}, @samp{/}, @samp{=}, @samp{?}, @samp{^}, @samp{|}, or @samp{!}. @item x-symbol-tex-env-verbatim-regexp The contents of the @code{verbatim} environment is not decoded. To produce accented characters inside this environment, use the La@TeX{} package @file{inputenc.sty}. @c Inside @code{\hyphenation}@{@dots{}@}, you can only use Latin characters. @c David Kastrup: Wrong. inputenc.sty converts things like @"a into \"a @c anyway (take a look into your table of contents file, xxx.toc, for @c example). Both @"a and \"a will not work in hyphenation patterns when you @c are using a font encoding without such a character (like the default OT1 @c encoding), both @"a and \"a will work if something like @c \usepackage[T1]{fontenc} is active. This holds for LaTeX; plain TeX is @c not as sophisticated as to replace \"a with a single character when in @c T1 encodings. @item x-symbol-tex-env-tabbing-regexp Inside a @code{tabbing} environment, the macro sequences starting with @samp{\`}, @samp{\'}, @samp{\=} and @samp{\-} are not decoded. It is probably better (with or without X-Symbol) to use the La@TeX{} package @file{inputenc.sty} or to the @code{Tabbing} environment, to be found in the @sc{ctan} archives. @end vtable 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. @ifinfo Final note: in the info file, you will probably not see any 8bit characters. @end ifinfo You might want change the conversion between characters and tokens in language @code{tex} by changing: @vtable @code @item x-symbol-tex-user-table You can define you own tokens for X-Symbol characters. E.g., if you like to have the command @code{\sqrt} represented by a character (shadowing the entry for @code{\surd}), add the following to your @file{~/.emacs}: @lisp (setq x-symbol-tex-user-table '((radical (math special) "\\sqrt"))) @end lisp @end vtable @node TeX Macro Symbols, , TeX Macro Conversion, TeX Macro @comment node-name, next, previous, up @subsection Extra Symbols of Language ``@TeX{} Macro'' @cindex Extra Symbols for @TeX{} @cindex Defining @code{tex} @cindex Initializing @code{tex} @cindex @TeX{} Macro Installation @cindex Installing @code{tex} @pindex @file{latexsym.sty} @pindex @file{amssymb.sty} @pindex @file{stmaryrd.sty} @pindex @file{fontenc.sty} @pindex @file{inputenc.sty} 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 (@pxref{Info}) contains s.th. like @samp{@var{package}.sty} or @samp{user}. If you do not use the corresponding characters, you do not have to do anything, of course. The @TeX{} macros @code{\Box}, @code{\Diamond}, @code{\leadsto}, @code{\Join}, @code{\lhd}, @code{\mho}, @code{\rhd}, @code{\sqsupset}, @code{\sqsubset}, @code{\unlhd}, @code{\unrhd}, are defined in La@TeX{} package @file{latexsym.sty}: @example \usepackage@{latexsym@} @end example Note that these macros are also defined @file{amssymb.sty}. Since the first four macros are defined differently (better) in @file{latexsym.sty}, it does make sense to load both La@TeX{} packages. The @TeX{} macros @code{\boldsymbol}, @code{\circledast}, @code{\circledcirc}, @code{\circleddash}, @code{\digamma}, @code{\gtrapprox}, @code{\gtrsim}, @code{\lessapprox}, @code{\lesssim}, @code{\triangleq}, @code{\varkappa} are defined in AMS La@TeX{} package @file{amssymb.sty}: @example \usepackage@{amssymb@} @end example The @TeX{} macros @code{\bigsqcap}, @code{\llbracket}, @code{\rrbracket}, @code{\llparenthesis}, @code{\rrparenthesis} are defined in the La@TeX{} package @file{stmaryrd.sty}: @example \usepackage@{stmaryrd@} @end example The @TeX{} macros @code{\guilsinglleft}, @code{\guilsinglright}, @code{\dj}, @code{\NG}, @code{\ng}, @code{\DH}, @code{\DJ}, @code{\dh}, @code{\dj}, @code{\TH}, @code{\th}, @code{\guillemotleft}, @code{\guillemotright} and the ogonek characters are only defined if you use T1 font encoding: @example \usepackage[T1]@{fontenc@} @end example The @TeX{} macro @code{\mathmicro} for U00B5 can be defined by (@pxref{Wishlist LaTeX}): @example \let\mathmicro\mu @end example You should define the following in your La@TeX{} file (if you use the corresponding characters), the first can only be used with T1 font encoding. @example \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@{::@}@} @c \newcommand@{\lsemantics@}@{\mathopen@{\lbrack\mkern-3mu\lbrack@}@} @c \newcommand@{\rsemantics@}@{\mathclose@{\rbrack\mkern-3mu\rbrack@}@} @c \newcommand@{\lcata@}@{\mathopen@{(\mkern-3mu\mid@}@} @c \newcommand@{\rcata@}@{\mathclose@{\mid\mkern-3mu)@}@} @end example The @TeX{} macros @code{\textordfeminine}, @code{\textordmasculine}, @code{\textdegree}, @code{\textonequarter}, @code{\textonehalf}, @code{\textthreequarters}, @code{\mathonesuperior}, @code{\mathtwosuperior}, @code{\maththreesuperior}, @code{\textcopyright} are only defined when using La@TeX{} package @file{inputenc.sty}: @example \usepackage[latin1]@{inputenc@} @end example The @TeX{} macros @code{\textcent}, @code{\textcurrency}, @code{\textyen}, @code{\textbrokenbar}, @code{\textmalteseH}, @code{\textmalteseh} are defined as not available in La@TeX{} package @file{inputenc.sty}. @xref{Wishlist LaTeX}. If you use this package and want to define these commands, use @code{\renewcommand} (or @code{\def}) after, e.g.: @example \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@} @end example @c =========================================================================== @node SGML Entity, BibTeX Macro, TeX Macro, Supported Languages @comment node-name, next, previous, up @section Token Language ``@sc{sgml} entity'' (@code{sgml}) @cindex HTML @cindex SGML entity @cindex Token Language @code{sgml} @cindex Language @code{sgml} @pindex Netscape For buffers using the major mode @code{html-mode}, @code{hm--html-mode}, @code{html-helper-mode}, @code{sgml-mode} or @code{xml-mode}, we use token language @dfn{@sc{sgml} entity} (@code{sgml}). This language provides the display of super-/subscripts and images. If the buffer visits a file and uses a @sc{html} mode, X-Symbol mode is automatically turned on. @menu * SGML Entity Basics:: Basics of Language ``@sc{sgml} entity''. * SGML Entity Features:: Super-/Subscripts and Images in @sc{html}. * SGML Entity Conversion:: How the conversion of @sc{sgml} entities works. @end menu @node SGML Entity Basics, SGML Entity Features, SGML Entity, SGML Entity @comment node-name, next, previous, up @subsection Basics of Language ``@sc{sgml} entity'' @cindex SGML Entity Basics @cindex Basics SGML Entity @cindex Choosing SGML Entity @cindex SGML Entity Use @cindex SGML Entity Modes The standard behavior can be controlled by the following variables: @vtable @code @item x-symbol-sgml-modes @itemx x-symbol-sgml-auto-style The variables known from @ref{Minor Mode}. If the buffer uses a @sc{html} mode, super-/subscripts and images are displayed, otherwise unique decoding (@pxref{Unique Decoding}) will be used. @item x-symbol-sgml-auto-coding-alist Used there to automatically deduce the specific encoding of the file (@pxref{File Coding}). It searches for the following string in the current buffer, including the comment: @example @end example where @var{encoding} should be one of @samp{iso-8859-1}, @samp{iso-8859-2}, @samp{iso-8859-3}, @samp{iso-8859-9}, or @samp{iso-8859-15}. 8bit characters are not encoded if the file if the search was successful (@pxref{Controlling 8bit Coding}). @end vtable The input methods and the character info in the echo area are controlled by: @vtable @code @item x-symbol-sgml-header-groups-alist Defines the headers and their characters for the language specific Grid and Menu. @item x-symbol-sgml-extra-menu-items There are no special entries in the X-Symbol menu. @item x-symbol-sgml-electric-ignore There is no additional constraint to the ones mentioned in @ref{Input Method Electric}. @item x-symbol-sgml-class-alist @itemx x-symbol-sgml-class-face-alist Token classes (@pxref{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 (@pxref{Input Method Grid} and the character info (@pxref{Info}), dark red for characters without defined entity names in @sc{html} (@pxref{SGML Entity Conversion}). @end vtable @node SGML Entity Features, SGML Entity Conversion, SGML Entity Basics, SGML Entity @comment node-name, next, previous, up @subsection Super-/Subscripts and Images in @sc{html} @cindex SGML Entity Features @cindex Features SGML Entity @cindex SGML Entity Superscripts @cindex SGML Entity Subscripts @cindex SGML Entity Images The display of super- and subscripts (@pxref{Super and Subscripts}) is controlled by: @vtable @code @item x-symbol-sgml-font-lock-regexp @itemx x-symbol-sgml-font-lock-limit-regexp @itemx x-symbol-sgml-font-lock-alist @itemx x-symbol-sgml-font-lock-contents-regexp The superscript command @code{}@dots{}@code{} and the subscript command @code{}@dots{}@code{} is recognized. The contents should contain at least one character which is not a space or a @code{nobreakspace}. @end vtable The display of images (@pxref{Images}) is controlled by: @vtable @code @item x-symbol-sgml-image-keywords The following commands are recognized. Extension @var{ext} stands for @file{gif}, @file{png}, @file{jpeg} or @file{jpg}. @example @end example @item x-symbol-sgml-master-directory @itemx x-symbol-sgml-image-searchpath Relative file names (@pxref{Image Display}) are relative to the directory of the current file. @item x-symbol-sgml-image-file-truename-alist The file name prefix @file{file:} is ignored. For any other file name which starts with letters and then a colon, e.g., with @file{http:} or @file{C:\} (which is no @sc{url} anyway), the image insertion command will be skipped. By changing this variable, you could specify that the prefix @file{http://www.fmi.uni-passau.de/~wedler/} corresponds to @file{~/public_html/}. @item 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 @file{images/} or @file{pictures/} if the image should be cached in the memory cache. @end vtable @node SGML Entity Conversion, , SGML Entity Features, SGML Entity @comment node-name, next, previous, up @subsection The Conversion of @sc{sgml} Entities @cindex SGML Entity Conversion @cindex 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 @uref{http://www.w3.org/TR/REC-html40/sgml/entities.html}. By default, we encode to entity references like @code{&}, and decode from both entity references and character references like @code{&}. For Latin-N characters without defined entity names in @sc{html} (e.g. @code{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 @code{sgml} by changing: @vtable @code @item x-symbol-sgml-token-list @findex x-symbol-sgml-token-list-name @findex x-symbol-sgml-token-list-code @findex x-symbol-sgml-token-list-netscape A symbol, which defines whether to use entity references, character references, or entity references for Latin-1 characters and character references for others. @item 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: @example (setq x-symbol-sgml-user-table '((circ () 999 "&bcomp;"))) @end example @end vtable @c ==================================================================== @node BibTeX Macro, TeXinfo Command, SGML Entity, Supported Languages @comment node-name, next, previous, up @section Token Language ``Bib@TeX{} macro'' (@code{bib}) @cindex Token Language @code{bib} @cindex Language @code{bib} @cindex Bib@TeX{} macro @cindex @code{bib} @cindex Bib@TeX{} For buffers using the major mode @code{bibtex-mode}, we use token language @dfn{Bib@TeX{} macro} (@code{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: @vtable @code @item x-symbol-bib-modes @itemx x-symbol-bib-auto-style The variables known from @ref{Minor Mode}. There is no automatic deduction of the file encoding, 8bit characters are usually encoded, and there is usually no unique decoding. @xref{Conversion}. @end vtable @pindex bibtex The major difference between this language and the token language @code{tex} is that the tokens for text-mode characters are most likely enclosed by braces. This has some problems (@pxref{TeX Macro Problems}), but is required by the program @code{bibtex}. The input methods and most features except super-/subscripts and images work like in token language @code{tex} (@pxref{TeX Macro}): @vtable @code @item x-symbol-bib-header-groups-alist @itemx x-symbol-bib-electric-ignore @itemx x-symbol-bib-class-alist @itemx x-symbol-bib-class-face-alist Like in @ref{TeX Macro Features}. @item x-symbol-bib-extra-menu-items There are no special entries in the X-Symbol menu. @end vtable You might want change the conversion between characters and tokens in language @code{bib} by changing: @vtable @code @item x-symbol-bib-user-table @itemx x-symbol-tex-user-table Use the former for @code{bib}-only changes, the latter also influences the conversion with token language @code{tex}. @end vtable @c ==================================================================== @node TeXinfo Command, External Languages, BibTeX Macro, Supported Languages @comment node-name, next, previous, up @section Token Language ``@TeX{}info command'' (@code{texi}) @cindex Token Language @code{texi} @cindex Language @code{texi} @cindex @TeX{}info command @cindex @code{texi} @pindex texinfo @pindex GNU texinfo For buffers using the major mode @code{texinfo-mode}, we use token language @dfn{@TeX{}info command} (@code{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: @vtable @code @item x-symbol-texi-modes @itemx x-symbol-texi-auto-style The variables known from @ref{Minor Mode}. There is no automatic deduction of the file encoding, 8bit characters are usually encoded, and there is usually no unique decoding. @xref{Conversion}. @end vtable With @code{x-symbol-8bits} having value @code{nil} (the default), it might still happen that the saved file contains 8bit characters, since token language @code{texi} does not define tokens for all characters in the Latin charsets supported by X-Symbol. @xref{Controlling 8bit Coding}. With @code{x-symbol-unique} having value @code{nil} (the default), we have unique decoding anyway, since token language @code{texi} does only define one token per character, i.e., the value is not important if @code{x-symbol-8bits} is @code{nil}. @xref{Unique Decoding}. The input methods and the character info in the echo area are controlled by: @vtable @code @item x-symbol-texi-header-groups-alist Defines the headers and their characters for the language specific Grid and Menu. @item x-symbol-texi-extra-menu-items There are no special entries in the X-Symbol menu. @item x-symbol-texi-electric-ignore There is no additional constraint to the ones mentioned in @ref{Input Method Electric}. @item x-symbol-texi-class-alist @itemx x-symbol-texi-class-face-alist Only a few token classes (@pxref{Char Group}) are defined, the most interesting induces the character info (@pxref{Info}) to display @samp{not as code} for @code{@@minus@{@}} (@code{@@minus@{@}} should not used inside @code{@@code} and @code{@@example}). No coloring scheme is defined. @end vtable @pindex makeinfo At least with @code{makeinfo-4.0}, you do not get accented characters in the info file for the corresponding @TeX{}info commands in the @file{.texi} file, the @sc{html} output might contain illegal ``@sc{sgml} entities'' like @code{&140;}. @pindex texi2html At least with @code{texi2html-1.62}, you see accented characters in the @sc{html} output for the corresponding @TeX{}info commands in the @file{.texi} file, but the output might also contain illegal ``@sc{sgml} entities'' like @code{&140;}. You might want change the conversion between characters and tokens in language @code{texi} by changing: @vtable @code @itemx x-symbol-texi-user-table Extra entries for the conversion. @end vtable @c ==================================================================== @node External Languages, , TeXinfo Command, Supported Languages @comment node-name, next, previous, up @section Languages Defined in Other Emacs Packages @cindex Foreign Languages @cindex External Languages @cindex Other Languages It is no problem for other Emacs packages to define their own token language (@pxref{Extending X-Symbol}). I know of the following package---please check its manual for details. @itemize @bullet @item @pindex ProofGeneral @cindex Isabelle Symbol Package @uref{http://www.proofgeneral.org/,ProofGeneral} defines token language ``Isabelle symbol''. @end itemize @c =========================================================================== @node X-Symbol Internals, Problems, Supported Languages, Top @comment node-name, next, previous, up @chapter X-Symbol Internals @cindex Internals, X-Symbol @cindex 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 @emph{binary package} which contains pre-compiled files. X-Symbol developers should use the @emph{source package} which contains some additional files. @menu * Char Representation:: How X-Symbol represents X-Symbol chars. * Defining Charsets:: How X-Symbol defines additional chars. * Defining Input Methods:: How X-Symbol defines the input methods. * Extending X-Symbol:: How to add fonts and token languages. * Various Internals:: How X-Symbol handles other aspects. * Design Alternatives:: Why X-Symbol is not designed differently. * Language Internals:: How X-Symbol handles languages. * Misc Internals:: Various. TODO. @end menu @c ==================================================================== @node Char Representation, Defining Charsets, X-Symbol Internals, X-Symbol Internals @comment node-name, next, previous, up @section Internal Representation of X-Symbol Characters @cindex Charsym @cindex Leading Character @cindex Octet @cindex Cstring @cindex Mule Character As mentioned in @ref{Pseudo Language}, most functions do not operate on X-Symbol characters directly, they use ``x-symbol charsyms''. These charsyms have a symbol property @code{x-symbol-cstring} which points to a string, called @dfn{cstring}, containing the X-Symbol character. @itemize @bullet @item Under Emacs and XEmacs/Mule, the string only contains the character which is a normal Mule character created by @code{make-char}. @item @pindex font-lock Under XEmacs/no-Mule, the string only contains the 8bit character if the X-Symbol character is a 8bit character according to @code{x-symbol-default-coding} (@pxref{Default Coding}). Otherwise, the string contains of a @dfn{leading character} (with range @samp{\200} to @samp{\237}) and an @dfn{octet}. Package @code{font-lock} is used to display them correctly as X-Symbol characters (@pxref{FAQ Strange Chars}). E.g., with @samp{\251} is @code{copyright}, we get @lisp (get 'Idotaccent 'x-symbol-cstring) @result{} "\235\251" @end lisp @end itemize If the character is also a 8bit character in some encoding (@pxref{File Coding}), the charsym also has the symbol property @code{x-symbol-file-cstrings} for the representation in the file and property @code{x-symbol-buffer-cstrings} to recognize character aliases (@pxref{Char Aliases}). E.g., under XEmacs/no-Mule, with @samp{\335} is @code{Yacute}, @samp{\251} is @code{copyright}, we get @lisp (get 'Idotaccent 'x-symbol-file-cstrings) @result{} (iso-8859-9 "\335" iso-8859-3 "\251") (get 'Idotaccent 'x-symbol-buffer-cstrings) @result{} (iso-8859-9 "\234\335" iso-8859-3 "\235\251") @end lisp The values are plists (@pxref{Property Lists,,,lispref,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 @code{x-symbol-tokens} (@pxref{Token Language}) and @code{x-symbol-classes} (@pxref{Char Group}): @lisp (get 'Idotaccent 'x-symbol-tokens) @result{} (sgml "İ" tex "@{\\.I@}") (get 'Idotaccent 'x-symbol-classes) @result{} (sgml (non-l1) tex (text aletter)) @end lisp @c ==================================================================== @node Defining Charsets, Defining Input Methods, Char Representation, X-Symbol Internals @comment node-name, next, previous, up @section Defining X-Symbol Charsets @cindex Cset @cindex Charset @cindex Final Byte An X-Symbol charset, called @dfn{cset} in the code and the docstrings, handles one font used by package X-Symbol. Each cset must use the same char registry@minus{}encoding as the corresponding variables for the fonts (@pxref{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. @lisp @group (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 ?\;))) @end group @end lisp Mule charsets (@pxref{Charsets,,,lispref,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: @samp{:} and @samp{;}). The remaining free (reserved by Emacs for users) are @samp{>} and @samp{?}, the latter is already used in XEmacs. For XEmacs/no-Mule, you have to define the leading character (this example: @samp{\233}). @vtable @code @item x-symbol-latin1-cset @itemx x-symbol-latin2-cset @itemx x-symbol-latin3-cset @itemx 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 @ref{File Coding}. @item x-symbol-xsymb0-cset @itemx x-symbol-xsymb1-cset Cset definitions using both halves of the fonts where no corresponding Mule charset are yet known. @end vtable @c ==================================================================== @node Defining Input Methods, Extending X-Symbol, Defining Charsets, X-Symbol Internals @comment node-name, next, previous, up @section Defining Input Methods @cindex Input Method Internals @cindex Internals, Input Method @cindex Defining Input Methods This is probably the hardest section in this manual@dots{}. @menu * Input Method Objectives:: Input methods should be intuitive/consistent. * Intro Char Descriptions:: An example introducing char descriptions. * Char Descriptions:: The aspects and the contexts of a character. * Example Char Descriptions:: A complete example defining input methods. * Customizing Input Methods:: How to customize the input methods. @end menu @node Input Method Objectives, Intro Char Descriptions, Defining Input Methods, Defining Input Methods @comment node-name, next, previous, up @subsection Defining Input Methods: Objectives @cindex Input Method Objectives @cindex Objectives, Input Methods @cindex Consistent Input Methods Input methods should be intuitive. This requires consistency: @itemize @bullet @item Characters should be found under the same header in the Grid and in the Menu. @item If one character can be modified or rotated to another character (@pxref{Input Method Context}), both should stand near to each other in the Grid. E.g., since @code{arrowsouthwest} rotates to @code{arrowdown}, they stand next to each other. @item 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., @code{reflexsubset} with key binding @kbd{C-= < _ 2} modifies to @code{reflexsqsubset} with key binding @kbd{C-= < _ 3}. @item 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. @item It should be possible to load character definitions later on, e.g., when new token languages get initialized. @itemize @minus @item 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 @samp{1}). @item Also, modifying or rotating a new character to/from old ones should be possible without changing the input definitions of the old characters. @end itemize @end itemize 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 @code{define-key}. The solution is an indirect definitions with ``character descriptions''. @node Intro Char Descriptions, Char Descriptions, Input Method Objectives, Defining Input Methods @comment node-name, next, previous, up @subsection X-Symbol Character Descriptions: Example @cindex Character Descriptions, Intro @cindex Character Descriptions, Example As an example for ``character descriptions'', look at the definition of @code{longarrowright} in @code{x-symbol-xsymb1-table} (@samp{95} is the encoding in the font and not of interest here). Some terms are defined in the next section: @lisp @group (longarrowright 95 (arrow) (size big . arrowright) nil ("->" t "-->") (emdash)) @end group @end lisp With this definition, package X-Symbol automatically defines: @itemize @bullet @item Key bindings @kbd{C-= - - >} and @kbd{C-= - > 2}, the latter has suffix 2, because @kbd{C-= - >} is also ``wanted'' by @code{arrowright} which now has the key binding @kbd{C-= - > 1} (the ``score'' of @code{longarrowright} is higher, due to @samp{size big}). @xref{Input Method Keyboard}. @item @code{arrowright} modifies to @code{longarrowright}, which modifies to @code{arrowright}. @xref{Input Method Context}. @item @code{longarrowleft} rotates to @code{longarrowright}, which rotates to @code{longarrowboth} (which rotates to @code{longarrowleft}). (The ``rotate aspects'' are inherited from @code{arrowright}.) @xref{Input Method Context}. @item The following contexts can be modified to @code{longarrowright}: @samp{-->} or @code{minus1} / @code{endash} / @code{macron} / @code{emdash} / @code{hyphen} and @samp{->} (since all define context @samp{-}) and @code{emdash} and @samp{>} (since @code{emdash} defines context @samp{--}). @samp{->} is used for @code{arrowright}, which has a lower score, see above. @xref{Input Method Context}. @item Input method Electric will change context @samp{-->} (is tagged with @code{t} in the definition) to @code{longarrowright}, also @code{emdash} and @samp{>} (only theoretically, since input method Electric will produce @code{emdash} only in @TeX{}'s text mode, and @code{longarrowright} only in @TeX{}'s math mode). @xref{Input Method Electric}. @item The character will appear in the Grid under the header @samp{Arrow}. You will probably recognize that the placement is based on the modify-to and rotate-to behavior above. @xref{Input Method Grid}. @item The character will appear in the Menu under one of the headers @samp{Arrow @var{n}}". The submenus are sorted alphabetically. @xref{Input Method Menu}. @end itemize 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@dots{}. @node Char Descriptions, Example Char Descriptions, Intro Char Descriptions, Defining Input Methods @comment node-name, next, previous, up @subsection Defining Input Methods by Character Descriptions @cindex Character Descriptions @cindex Aspects of Characters @cindex Parent Character @cindex Component of Characters @cindex Modify Scores @cindex Rotate Scores @cindex Modify Aspects @cindex Rotate Aspects @cindex Score of a Character @cindex Modify Chain @cindex Exclusive Modify Chain @cindex Rotate Chain @cindex Horizontal Chain @cindex Key Chain Characters are defined with @dfn{character descriptions} which consist of different @dfn{aspects} and @dfn{contexts}, which can also be inherited from a @dfn{parent} character. All characters which are connected with parents, form a @dfn{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 @kbd{M-x hyper-apropos-get-doc}) of the corresponding charsym, e.g., @code{arrowright}. See also the docstrings of @code{x-symbol-init-cset} and @code{x-symbol-init-input}. Remember, all characters which are connected with parents, form a component. @dfn{Contexts} are the contexts of input method Context (@pxref{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 @dfn{modify context} of a charsym is the first context. @vtable @code @item x-symbol-rotate-aspects-alist Characters in the same component whose aspects only differ by their @code{direction} (@code{east},@dots{}), a key in this alist, are circularly connected by ``rotate-to''. The sequence in the @dfn{rotate chain} is determined by @dfn{rotate scores} depending on the values in the @dfn{rotate aspects}. Charsyms with the same ``rotate-aspects'' are not connected (charsyms with the smallest modify scores are preferred). @lisp (get 'longarrowright 'x-symbol-rotate-aspects) @result{} (-1500 direction east) @end lisp @item x-symbol-modify-aspects-alist Characters in the same components whose aspects only differ by their @code{size} (@code{big},@dots{}), @code{shape} (@code{round}, @code{square}@dots{}) and/or @code{shift} (@code{up}, @code{down},@dots{}), 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 @dfn{modify chain} is determined by @dfn{modify scores} depending on the values in the @dfn{modify aspects}, the charsym score defined in the definition tables and the score of the whole cset (@pxref{Defining Charsets}). @lisp (get 'longarrowright 'x-symbol-score) @result{} -3500 (get 'longarrowright 'x-symbol-modify-aspects) @result{} (1500 shift nil shape nil size big) @end lisp 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 @dfn{horizontal chain} whose charsyms are circularly connected by ``modify-to''. We build a @dfn{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. @item x-symbol-key-suffix-string If there is only one charsym in the key chain, @kbd{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. @kbd{C-=} plus the context plus the suffix inserts the charsym. @end vtable @node Example Char Descriptions, Customizing Input Methods, Char Descriptions, Defining Input Methods @comment node-name, next, previous, up @subsection Defining Input Methods: Example @cindex Character Descriptions, Example @smallexample 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' - @end smallexample Assuming that all charsyms form one component, we have: @smallexample Rotate chains: (1w,2w)-1e-1n @r{and} 3w-(2e,3e)-2n. Modify chains: 1w-2w-3w @r{and} 1e-2w-3w and 1n-2n. Horizontal chains: 1e-1w-2e-3e @r{(for modify context @samp{a})} 2w-3w @r{(for modify context @samp{b})} Key chains: 1e-1w-2e-3e @r{(for context @samp{a})} 1e-2w-2e-3w @r{(for context @samp{b})} 1n-1w-2n @r{(for context @samp{c})} 1n @r{(for context @samp{d})} @end smallexample That makes the following bindings: @smallexample 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 @r{(horizontal chain)} 2w->3w, 3w->2w @r{(horizontal chain)} 1n->2n, 2n->1n @r{(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 @end smallexample @node Customizing Input Methods, , Example Char Descriptions, Defining Input Methods @comment node-name, next, previous, up @subsection Customizing Input Methods @cindex Customizing Input Methods @cindex Input Methods Customization 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. @vtable @code @item x-symbol-group-input-alist Defines default scores and bindings for characters of a group (@pxref{Char Group}). E.g., the definition (in @code{x-symbol-latin1-table}) @lisp (aacute 225 (acute "a" Aacute)) @end lisp defines @code{aacute} without any explicit contexts, but having the group @code{acute} and the subgroup @samp{a}. The default input for the group is defined by the following element in this variable: @lisp (acute 0 "%s'" t "'%s") @end lisp That means: 0 is added to the normal ``modify-score'' of the character. @samp{%s'} and @samp{'%s} with @samp{%s} substituted by the subgroup, i.e., @samp{a'} and @samp{'a}, are the contexts for @code{aacute}. The context @samp{'a} is also used for input method Electric since it is prefixed by @code{t}. @item 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 @kbd{C-= @var{key}} to @kbd{C-= @var{key} 1}, it is required that the length of the key binding without @kbd{C-=} is at least 2. @end vtable @c ==================================================================== @node Extending X-Symbol, Various Internals, Defining Input Methods, X-Symbol Internals @comment node-name, next, previous, up @section Extending Package X-Symbol @cindex Extending 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. @menu * Extending with Fonts:: How to add fonts to X-Symbol. * Input Definitions:: Guidelines for input definitions. * Font Definition File:: How to define new character in a file. * Language Extension File:: Extending an existing language. * Language Definition File:: Defining a new language. @end menu @node Extending with Fonts, Input Definitions, Extending X-Symbol, Extending X-Symbol @comment node-name, next, previous, up @subsection Extending X-Symbol with New Fonts @cindex Extending with Fonts @cindex Adding Fonts @cindex Font Extension @cindex Guidelines, Font Extension 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 @samp{CHARSET_REGISTRY} and @samp{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, @pxref{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. @itemize @bullet @item In general, escape sequences use the digits of the current font. Thus, you should probably define the encodings 48 to 57 as digits @samp{0} to @samp{9}. @item In La@TeX{} buffers, characters in @samp{$%\@{@}} 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 @code{tex} and @code{utex}. @item In HTML buffers, characters in @samp{&<>} 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 @code{sgml}. @end itemize You have to tell package X-Symbol which fonts to use for the normal text, subscripts and superscripts. @xref{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. @xref{Defining Charsets}. @node Input Definitions, Font Definition File, Extending with Fonts, Extending X-Symbol @comment node-name, next, previous, up @subsection Guidelines for Input Definitions @cindex Input Definitions, Guidelines @cindex Guidelines, Input Definitions Read section @ref{Defining Input Methods}. Look at the tables in @file{x-symbol.el}. Here are some guidelines of how to define the input methods for new characters: @enumerate @item Define reasonable character groups for new characters, see @ref{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. @item 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. @xref{Char Group}. @item If reasonable, define default contexts for characters of a group, see @ref{Customizing Input Methods}. @item For the other characters, define contexts by Ascii sequences which look similar to the character. @item 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 @ref{Char Descriptions}. @item Use aspects to describe the new characters. Add new aspects to @code{x-symbol-modify-aspects-alist} and @code{x-symbol-rotate-aspects-alist} if necessary (@pxref{Char Descriptions}). @item Finish the definition of your font file (@pxref{Font Definition File}), load it with @kbd{M-x load-file}, and initialize the input methods, e.g., by invoking the grid (@kbd{M-x x-symbol-grid}). @item 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. @enumerate a @item 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. @item Define reasonable scores for newly defined aspects and character groups. @item Finally, fine-tune your definitions by charsym scores in the tables. This should be necessary only for a few characters. @end enumerate @end enumerate @node Font Definition File, Language Extension File, Input Definitions, Extending X-Symbol @comment node-name, next, previous, up @subsection Emacs Lisp File Defining a New Font @cindex Font Definition File 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: @lisp (provide 'x-symbol-myfont) @group (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"))) @end group @group (defvar x-symbol-myfont-cset '((("xsymb-myfont") ?\200 1000) (myfont-left "My font characters, left" 94 63) . nil)) @end group @end lisp @lisp @group (defvar x-symbol-myfont-table '((longarrownortheast 33 (arrow) (size big . arrownortheast)) (koerper 34 (setsymbol "K")) (circleS 35 (symbol "S") nil nil "SO"))) @end group @group (x-symbol-init-cset x-symbol-myfont-cset x-symbol-myfont-fonts x-symbol-myfont-table) @end group @end lisp Due to an XEmacs bug with char syntax @code{inherit}, you should also add the following line to files @file{x-symbol-xmas20.el} and @file{x-symbol-xmas21.el}: @lisp (modify-syntax-entry ?\200 "\\" (standard-syntax-table)) @end lisp @node Language Extension File, Language Definition File, Font Definition File, Extending X-Symbol @comment node-name, next, previous, up @subsection Emacs Lisp File Extending a Token Language @cindex Language Definition File 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 @code{utex} inherits most variables from @code{tex}, see @file{x-symbol-utex.el}. A language must define variables for all language aspects, see @ref{Language Internals}. Our example defines a language @code{mytex} using the additional characters from @ref{Font Definition File}. First, you have to register the language in a startup file: @lisp (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) @end lisp The language definition file should look like (leaving out most parts which are similar to the ones in @file{x-symbol-utex.el}): @lisp (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) @end lisp @lisp (defvar x-symbol-mytex-user-table nil) @group (defvar x-symbol-mytex-myfont-table '((longarrownortheast (math arrow user) "\\longnortheastarrow") (koerper (math letter user) "\\setK") (circleS (math ordinary amssymb) "\\circledS"))) @end group @group (defvar x-symbol-mytex-table (append x-symbol-mytex-user-table '(nil) x-symbol-mytex-myfont-table x-symbol-tex-table)) @end group @end lisp It is important that you do not define a variable for the language access @code{x-symbol-font-lock-keywords}, but rather use the variable of the parent language directly, see @ref{Language Internals}. During the testing phase, you should probably leave out the @samp{'(nil)} which prevents warnings about redefinitions for the following elements. @node Language Definition File, , Language Extension File, Extending X-Symbol @comment node-name, next, previous, up @subsection Emacs Lisp File Defining a New Token Language @cindex Language Definition File You might also want to define a new token language not based on another language. As an example, consider a token language ``My Unicode'' (@code{myuc}) for buffers with major mode @code{myuc-mode}. Thus, we register the language by: @lisp (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) @end lisp Each token if language @code{myuc} consists of @samp{#} 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 @samp{#} is represented by the token @code{##}. 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 (@file{x-symbol-myuc.el}) is included in the source distribution of package X-Symbol. @lisp (provide 'x-symbol-myuc) (defvar x-symbol-myuc-required-fonts nil) (defvar x-symbol-myuc-modeline-name "myuc") @group (defvar x-symbol-myuc-class-alist '((VALID "My Unicode" (x-symbol-info-face)) (INVALID "no My Unicode" (red x-symbol-info-face)))) @end group (defvar x-symbol-myuc-font-lock-keywords nil) (defvar x-symbol-myuc-image-keywords nil) @dots{} @end lisp @lisp (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) @end lisp @lisp @group (defun x-symbol-myuc-default-token-list (tokens) (list (format "#%X" (car tokens)))) @end group (defvar x-symbol-myuc-token-list 'x-symbol-myuc-default-token-list) (defvar x-symbol-myuc-user-table nil) @group (defvar x-symbol-myuc-xsymb0-table '((alpha () 945) (beta () 946))) @end group @group (defvar x-symbol-myuc-table (append x-symbol-myuc-user-table x-symbol-myuc-xsymb0-table)) @end group @dots{} @end lisp @c ==================================================================== @node Various Internals, Design Alternatives, Extending X-Symbol, X-Symbol Internals @comment node-name, next, previous, up @section Various Internals @menu * Tagging Insert Commands:: Don't break input methods Token and Electric. * Avoiding Flickering:: Moving cursor in invisible commands. @end menu @node Tagging Insert Commands, Avoiding Flickering, Various Internals, Various Internals @comment node-name, next, previous, up @subsection Tagging Insert Commands for Token and Electric @cindex Insert Commands, Tagging @cindex Tagging Insert Commands @cindex Recognizing Insert Commands Input methods Token (@pxref{Input Method Token}) and Electric (@pxref{Input Method Electric}) stop their auto replacement if you use a command which is not an insert command. @ftable @code @item self-insert-command @itemx newline @itemx newline-and-indent @itemx reindent-then-newline-and-indent @itemx tex-insert-quote @itemx TeX-insert-quote @itemx TeX-insert-punctuation @itemx TeX-insert-dollar @itemx sgml-close-angle @itemx sgml-slash These commands and commands aliased to these are recognized as input commands by having a non-@code{nil} value of its symbol property @code{x-symbol-input}. @end ftable @node Avoiding Flickering, , Tagging Insert Commands, Various Internals @comment node-name, next, previous, up @subsection Avoiding Hide/Show-Invisible Flickering @cindex Avoiding Flickering @cindex Flickering, Invisible @cindex Invisible Flickering Starting a command makes a previously revealed super- or subscript command (@pxref{Super and Subscripts}) invisible again. Repeatedly invoking commands which moves the point just by a small amount can lead to some flickering. @ftable @code @item forward-char @itemx forward-char-command @itemx backward-char @itemx 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 (@code{1+} and @code{1-}) as the value of its symbol property @code{x-symbol-point-function} which returns the position ``after'' when called with the position ``before''. @end ftable @c ==================================================================== @node Design Alternatives, Language Internals, Various Internals, X-Symbol Internals @comment node-name, next, previous, up @section Design Alternatives This section describes potential design alternatives and why they were not used. @menu * Alt Token Representations:: Why we need the conversion. * Alt Global Mode:: How to turn on X-Symbol globally. * Alt Auto Conversion:: When do we convert automatically. @end menu @node Alt Token Representations, Alt Global Mode, Design Alternatives, Design Alternatives @comment node-name, next, previous, up @subsection Alternative Token Representations @cindex Alternative Token Representations @cindex Token Representation, Alternatives 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 @ref{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: @itemize @bullet @item The editing commands would work on the tokens which are invisible for the user. @item 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! @item 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 @code{lazy-shot}! @end itemize 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: @itemize @bullet @item You cannot adopt @sc{sgml} to this approach. @item You cannot read normal La@TeX{} files directly, you do not write normal La@TeX{} files. @item You would have different @TeX{} versions: one for X-Symbol with Emacs and XEmacs/Mule, one with XEmacs/no-Mule. @item If you are not an extremely good @TeX{} hacker, it would be impossible to adopt this approach to support more than 256 characters. @end itemize 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: @itemize @bullet @item Problems with current search/replace commands. @item Problems with the current version of @code{font-lock} (it should @emph{never} overwrite the font property for this character, even if the character matches some @var{match} in @code{font-lock-keywords} and @var{overwrite} is non-@code{nil}). This gets even more difficult with superscripts/subscripts. @item 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., @code{\leftrightarrow} and @code{\approx} would be delimiters. @end itemize @node Alt Global Mode, Alt Auto Conversion, Alt Token Representations, Design Alternatives @comment node-name, next, previous, up @subsection Alternative Ways to Turn on X-Symbol Globally @cindex Alternative Global Mode @cindex Global Mode, Alternatives @cindex Turn on Globally, Alternatives This package hooks itself into @code{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: @itemize @bullet @item The installation is more complicated. @item Local variables in files are not yet processed (this was the main reason not to do it this way). @end itemize Another possibility would be to hook X-Symbol into @code{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 @code{find-file-hooks}, especially with the function hooked in by @code{font-lock}. @node Alt Auto Conversion, , Alt Global Mode, Design Alternatives @comment node-name, next, previous, up @subsection Alternative Auto Conversion Methods @cindex Alternative Auto Conversion @cindex Auto Conversion, Alternatives @vindex hack-local-variables-hook @vindex after-insert-file-functions @vindex write-region-annotate-functions Without package @code{crypt}, this package automatically decodes tokens when turning on the minor mode (in @code{hack-local-variables-hook}, @pxref{Alt Global Mode}) or in @code{after-insert-file-functions}. This package automatically encodes characters in @code{write-region-annotate-functions}. The disadvantage is that the possibility to change buffers in @code{write-region-annotate-functions} is not official (@pxref{Wishlist Emacs}), i.e., not mentioned in the docstring (only mentioned for corresponding encode-functions of package @code{format} which use a similar loop in the C code). @vindex write-file-hooks With package @code{crypt}, this package automatically decodes tokens when turning on the minor mode. This package automatically encodes characters in @code{write-file-hooks}. The disadvantage is that the encoding is slower (use @code{jka-compr} instead @code{crypt}) and the problem with @code{vc-next-action} (@pxref{Spurious Encodings}). @vindex write-file-data-hooks Without package @code{crypt}, Version 2.6 of this package automatically encoded characters in @code{write-file-data-hooks}. The advantage was that changing buffers there is official, the disadvantage is that it is also more complicated. @pindex format A totally different method would be to use package @code{format}. Unfortunately, this is not really possible, since a @var{regexp} in @code{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 @code{jka-compr} and @code{crypt}. @c ==================================================================== @node Language Internals, Misc Internals, Design Alternatives, X-Symbol Internals @comment node-name, next, previous, up @section Language Internals @cindex Language Internals @cindex Token Language Internals @cindex Internals, Languages @cindex Registered Languages @cindex Loaded Language @cindex Initialized Language @cindex Language Access @cindex Accessing Language Depending Variables In order to use a token language or accessing one of the language dependent values, the following conditions must be met: @itemize @bullet @item The language must be @dfn{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 @code{x-symbol-language}. @ftable @code @item 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. @end ftable @item The file providing the language must have been @dfn{loaded}. This will be done automatically when the language is initialized. Customizing X-Symbol will also load the language files. @item The language must be @dfn{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 (@pxref{Input Method Grid}), you should initialize the language explicitly, e.g., by the following command: @table @kbd @item M-x x-symbol-init-language-interactive @findex x-symbol-init-language-interactive Initialized a token language if it is not already initialized. @end table @end itemize Language dependent values are accessed by language accesses: @table @code @item x-symbol-language-value @findex 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 @code{x-symbol-name}. With a simplified expansion, we get @lisp (x-symbol-language-value 'x-symbol-name 'tex) @expansion{} (symbol-value (get 'tex 'x-symbol-name)) @result{} (symbol-value 'x-symbol-tex-name) @result{} "TeX macro" @end lisp @item x-symbol-language-access-alist @vindex x-symbol-language-access-alist List of all language accesses. A token language @emph{must} define all variables accessed by language accesses. A @dfn{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 @code{utex}, the language access @code{x-symbol-font-lock-keywords}, should point directly to the variable of the parent language (here @code{tex}), see file @file{x-symbol-utex.el}. @end table @c Hi, X-Symbol's interna have changed considerably with v4.3.1-alpha. For @c token languages to work with new versions of X-Symbol, it is important @c to define some new language accesses (you @c can also delete some if you do not want X-Symbol backward compatiblity) @c The reason for the change is: @c * more general ways to define the "grammar" of tokens, also useful for @c ProofGeneral's languages, see below. @c * faster conversion (I also dropped the support of executables) @c As an example, let's look at x-symbol-texi.el): @c The following vars must now be defined (value nil...) @c (defvar x-symbol-texi-generated-data nil) @c Now the interesting part: @c (defvar x-symbol-texi-token-grammar @c '(x-symbol-make-grammar @c :encode-spec '(?@) @c :decode-regexp @c "@\\(?:[A-Za-z]+{[A-Za-z]?}\\|[{}]\\|[~^\"'`][A-Za-z]\\|,{[A-Za-z]}\\)" @c :decode-spec '(?@)) @c "Token grammar for language `texi'.") @c (defvar x-symbol-texi-input-token-grammar @c '("@\\(?:[A-Za-z]+{[A-Za-z]?}\\|[{}]\\|[~^\"'`][A-Za-z]\\|,{[A-Za-z]}\\)\\'" @c ?@) @c "Grammar of input method Token for language `texi'.") @c In short, not too difficult if the token grammar is regular (even @c simpler for SGML entities). The good news: powerful enough for @c irregular token grammar which couldn't be defined with previous versions @c of X-Symbol. @c The conversion now works as follows: @c 1. decode (token->char): search for regexp, then decode match except if @c context is "bad". @c 2. encode (char->token): search for non-ascii/8bit, then encode match. @c Surround by spaces if context is "bad". @c The "token grammar" is simply a definition of the regexp and the bad @c contexts, which can be different for different "shapes" of the token. @c A special BEFORE context is the escape character: this character may @c appear exactly even times before the token; it will be used for @c all shapes. @c Lets assume a language "Isabelle Symbol" plus symbols for identifiers @c and operators (see below for lisp coding): @c shape nil: \ @c shape id: [A-Za-z_][A-Za-z_0-9]+ @c shape op: [<>!+-*/|&]+ @c To make the conversion fast, the shape must be given at definition time, @c i.e., the init must get tokens in the form (TOKEN . SHAPE). @c Either per hand or computed via function in language access @c x-symbol-token-list... @c The decode-regexp must match all tokens and: @c a. should be specific enough to make the conversion fast @c b. must be general enough to match strings which should not be @c considered to contain a token even if a substring is a token (to @c avoid excessive context checking) @c In our example, the regexp would be something like @c "\\\\<[A-Za-z]+>\\|[A-Za-z_][A-Za-z_0-9]+\\|[<>!+-*/|&]+" @c No bad context has to be defined for decoding since the regexp is @c general enough. @c For encoding, we have to define the following bad contexts (no context @c can be defined for shape nil): @c shape id: BEFORE: [A-Za-z_0-9], AFTER: [A-Za-z_0-9] @c shape op: BEFORE: [<>!+-*/|&], AFTER: [<>!+-*/|&] @c BEFORE is a regexp used via `string-match' with the character before the @c character to encode; if it matches, we put a space before the token for @c the character. AFTER is a regexp used with `looking-at' with point @c after the character. We would put a space after the token. @c There is probably no escape char defined for Isabelle Symbols (i.e., @c "\\" is no token). @c The input-token-grammar is very similar to the decode-grammar: the @c regexp should end with \\' such that only matches ending at point will @c get replaced, and we should define a bad context (which will be @c tried to match against `last-command-char'). @c This makes the grammar below. @c Hope this helps, @c - Christoph @c (defvar x-symbol-xisa-token-grammar @c '(x-symbol-make-grammar @c :encode-spec '(((id . "[A-Za-z_0-9]") (op . "[<>!+-*/|&]")) . @c ((id . "[A-Za-z_0-9]") (op . "[<>!+-*/|&]"))) @c :decode-spec nil @c :decode-regexp "\\\\<[A-Za-z]+>\\|[A-Za-z_][A-Za-z_0-9]+\\|[<>!+-*/|&]+" @c :token-list #'x-symbol-xisa-default-token-list)) @c (defvar x-symbol-xisa-input-token-grammar @c '(("\\(?:\\\\<[A-Za-z]+>\\|[A-Za-z_][A-Za-z_0-9]+\\|[<>!+-*/|&]+\\)\\'") @c ((id . "[A-Za-z_0-9]") (op . "[<>!+-*/|&]")) @c (id . "[A-Za-z_0-9]") (op . "[<>!+-*/|&]"))) @c (defun x-symbol-xisa-default-token-list (tokens) @c (mapcar (lambda (x) @c (cons x (cond ((string-match "\\`[A-Za-z_][A-Za-z_0-9]+\\'" x) 'id) @c ((string-match "\\`[<>!+-*/|&]+\\'" x) 'op)))) @c tokens)) @c (defun x-symbol-xisa-table @c '((product () "\\") @c (longarrowright () "-->") @c (alpha () "alpha"))) @c ==================================================================== @node Misc Internals, , Language Internals, X-Symbol Internals @comment node-name, next, previous, up @section Miscellaneous Internals TODO. This is currently just a collection of unrelated stuff. @c was in "Char Group Characters might also define a @dfn{subgroup} which is a string defining some order on characters in the same group (@pxref{Char Group}) and is also used for default contexts/bindings (@pxref{Customizing Input Methods}). @vtable @code @item x-symbol-group-syntax-alist Lists all valid character groups. Under Emacs and XEmacs/Mule, this list also determines the syntax of characters. @end vtable The character group could probably also be used to define character categories if they are implemented in XEmacs. @c =========================================================================== @node Problems, History, X-Symbol Internals, Top @comment node-name, next, previous, up @chapter Problems, Troubleshooting @cindex Problems @cindex Troubleshooting @cindex Annoyances @cindex Bugs This section is based on a successful installation of package X-Symbol. @xref{Checking Installation}. @menu * Nomule Problems:: X-Symbol provides a @emph{poor} man's Mule. * Spurious Encodings:: Some commands turn off X-Symbol mode. * No Encoding:: The encoding does not work in a rare case. * FAQ:: Frequently asked questions. * Bug Reports:: How to contact the maintainer of X-Symbol. @end menu @c =========================================================================== @node Nomule Problems, Spurious Encodings, Problems, Problems @comment node-name, next, previous, up @section Problems under XEmacs/no-Mule @cindex Nomule Problems @cindex @code{transpose-chars} Problems @cindex Replace Problems @cindex Rectangle Problems @cindex Abbrev Problems @cindex Invisible Point @cindex Parenthesis Problems @cindex Fill Problems 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 ``@emph{poor} man's Mule'', see @ref{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): @itemize @bullet @item If @code{font-lock} is not prepared to display these two-character sequences, i.e., if you installation is incomplete (@pxref{Role of font-lock}), they look like @samp{\233a} instead @code{alpha}. @item Commands which add more than one entry to the @code{buffer-undo-list} and involve X-Symbol characters might lead to strange results, e.g. @kbd{C-t} (@code{transpose-chars}) with point between character @code{alpha} and @samp{b}, leads to @code{beta}@samp{a}. Simple deletion and insertion works OK, though. @item Selecting or inserting a rectangle with X-Symbol characters on the left or right margin might not work properly. @item Be careful with @kbd{M-%} (@code{query-replace}): the first character of @var{from-string} can probably match the second of the two ``internal'' characters of an X-Symbol character. @item If you use @kbd{C-x '} (@code{expand-abbrev}) without @kbd{M-'} (@code{abbrev-prefix-mark}) and the last word before point starts directly after a X-Symbol character, @kbd{C-x '} could behave strange: @itemize @minus @item If @code{words-include-escapes} is @code{t}, there will be no expansion. @item If @code{words-include-escapes} is @code{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. @end itemize @item 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 (@kbd{C-g}). Unfortunately, XEmacs (as opposed to Emacs) does not run the hooks in @code{post-command-hook} in these cases. Solution: move point right (@kbd{C-f}). @item If you provide prefix arguments to commands, they are likely to consider just ``internal'' characters. E.g., @kbd{C-u 2 C-f} before @code{alpha} behaves like @kbd{C-f}. @item Column position considers ``internal'' characters, e.g., @kbd{C-n} might jump to an unexpected position (well, typically just one character left/right from the expected position, if at all). @item Auto-filling also considers ``internal'' characters, i.e., might break the line too early. @item There are no syntax definitions for the new characters, e.g., @kbd{M-C-f} before @code{floorleft} does not move to the closing @code{floorright}. @item In some cases, e.g., when using the minibuffer for input via @kbd{M-%} or @kbd{C-s}, the internal representation of X-Symbol characters (@pxref{Char Representation}) are displayed directly (@pxref{FAQ Strange Chars}) @end itemize @c ==================================================================== @node Spurious Encodings, No Encoding, Nomule Problems, Problems @comment node-name, next, previous, up @section Spurious Encodings @cindex Spurious Encodings @cindex Version Control Problems @cindex @code{write-file} Problems @cindex @code{vc} Problems @cindex Revert Buffer Problems @pindex vc In rare cases, some commands (mostly from package @code{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. @itemize @bullet @item @pindex crypt Doing the next logical version control operation (@kbd{C-x v v} and friends) encode characters to tokens when using package @code{crypt}. Solution: use package @code{jka-compr} instead @code{crypt} (this is recommended anyway, @pxref{File IO Packages}). Or kill the buffer and revisit the file. @item @pindex auctex When using Auc@TeX{} with its default-mode algorithm, getting rid of the recently checked-in version of a file without reverting the buffer afterwards (@kbd{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 @samp{\233a}. Explanation: when using Auc@TeX{}'s @code{TeX-default-mode}, the final @code{major-mode} is different from the initial @code{major-mode} deduced using @code{auto-mode-alist}. If this is the case, the VC command executes @code{normal-mode} which kills all local-variables including turning-off @code{x-symbol-mode}. Solution: Turn on X-Symbol mode or change @code{auto-mode-alist} to directly choose @code{latex-mode}: @lisp (push '("\\[tT]e[xX]\\'" . latex-mode) auto-mode-alist) @end lisp @item @findex write-file @vindex change-major-mode-with-file-name When using Auc@TeX{} with its default-mode algorithm, writing a La@TeX{} 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 Auc@TeX{}'s @code{TeX-default-mode}, we get the problems as described in the previous item. Solution: Set @code{change-major-mode-with-file-name} to @code{nil} or use the solution from the previous item. @end itemize @c ==================================================================== @node No Encoding, FAQ, Spurious Encodings, Problems @comment node-name, next, previous, up @section The Encoding Does Not Work @cindex No Encoding @cindex @code{write-region} Problems In a rare case, X-Symbol cannot do its encoding, i.e., convert the characters to tokens. @itemize @bullet @item @findex write-region @pindex crypt @vindex write-file-hooks @kbd{M-x write-region} fails to do the encoding if you use package @code{crypt}. Explanation: with package @code{crypt}, the encoding has to be done by a function in @code{write-file-hooks} which is not used by @code{write-region}. Solution: use package @code{jka-compr} instead @code{crypt} (this is recommended anyway, @pxref{File IO Packages}). Or visit the region file and save it again via @kbd{C-x C-s}. @end itemize @c =========================================================================== @node FAQ, Bug Reports, No Encoding, Problems @comment node-name, next, previous, up @section Frequently Asked Questions @cindex Frequently Asked Questions @cindex FAQ X-Symbol It is assumed that you had successfully installed package X-Symbol, see @ref{Checking Installation}. @menu * FAQ XEmacs Core:: XEmacs crashes when using input method Token * FAQ font-lock:: X-Symbol's fontification does not work. * FAQ Strange Chars:: The buffer contains strange characters * FAQ No Subscripts:: I cannot see any/some super-/subscripts. * FAQ Stupid Subscripts:: I see subscripts where I don't want them. * FAQ Font Size:: The characters are too small or too big. * FAQ Conversion:: The conversion changes some tokens. * FAQ Additional Spaces:: A space is added during the encoding. * FAQ 8bit Chars:: I do not want 8bit characters in the file. * FAQ Hyphen:: I cannot distinguish @code{hyphen} from @samp{-}. * FAQ Spell Check:: I have problems with spell-checking. * FAQ News and Mail:: I want to use X-Symbol in Gnus or @sc{vm}. @end menu @node FAQ XEmacs Core, FAQ font-lock, FAQ, FAQ @comment node-name, next, previous, up @subsection XEmacs Crashes when using Input Method Token @cindex XEmacs Core @cindex Core XEmacs @cindex Crash XEmacs @cindex 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 @ref{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 @code{x-symbol-xmas-warn-about-core} to @code{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 @emph{newest} version of XEmacs (please put me in the CC). @node FAQ font-lock, FAQ Strange Chars, FAQ XEmacs Core, FAQ @comment node-name, next, previous, up @subsection X-Symbol's Fontification does Not Work @pindex font-lock @cindex No fontification @cindex @code{font-lock} Problems In this case, super- and subscripts are not properly displayed (@pxref{FAQ No Subscripts}) and under XEmacs/no-Mule, the buffer contains s.th. like @samp{\233a} (@pxref{FAQ Strange Chars}). Possible causes: @itemize @bullet @findex x-symbol-fontify @item You have turned off @code{font-lock} or @code{font-lock} is out of sync. Use @kbd{M-x x-symbol-fontify}. @xref{Role of font-lock}. @item The font-lock keywords of the current buffer are not prepared to display X-Symbol characters. @xref{Role of font-lock}. @item @vindex fast-lock-save-faces You use package @code{fast-lock}. Solution: set @code{fast-lock-save-faces} to @code{nil} (done by default installation). @item You use some version control commands. You have probably noticed that these versions control commands also turn off @code{font-lock} in modes where you don't use X-Symbol, i.e., this is not a problem of package X-Symbol. @xref{Wishlist Emacs}. @xref{Spurious Encodings}. @end itemize @node FAQ Strange Chars, FAQ No Subscripts, FAQ font-lock, FAQ @comment node-name, next, previous, up @subsection The Buffer Contains Strange Characters @cindex Strange Characters @cindex Funny Characters @cindex Character Problems @cindex Escape Character Problems @pindex Mathematica If you see s.th. like @samp{\233a}, you see the internal representation of X-Symbol characters under XEmacs/no-Mule (@pxref{Char Representation}) directly. Possible causes: @itemize @bullet @item You have @code{font-lock} problems, see @ref{FAQ font-lock}. @item More complicated editing commands like @kbd{C-t} may produce strange character sequences which do not represent X-Symbol characters, see @ref{Nomule Problems}. @item In some cases, e.g., when using the minibuffer for input via @kbd{M-%} or @kbd{C-s}, it would be too much work to fontify these character sequences in order to display proper X-Symbol characters. @xref{Nomule Problems}. @end itemize 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 @code{adobe-fontspecific}, but in fact uses another encoding. E.g., Mathematica's fonts cause the characters intersection and union to mix up. Possible solutions: @itemize @bullet @item Delete that font from the font path. Maybe moving it at the end also works. @item 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 @lisp (setq face-ignored-fonts '("\\`-wri-math1")) @end lisp @item 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. @end itemize @node FAQ No Subscripts, FAQ Stupid Subscripts, FAQ Strange Chars, FAQ @comment node-name, next, previous, up @subsection I Cannot See any/some Super- or Subscripts @cindex No Subscripts @cindex Subscript Problems @cindex Superscript Problems If you cannot select @samp{Super-/Subscripts} in the menu, the first of the following points is more likely the cause, the others otherwise. @itemize @bullet @item You have @code{font-lock} problems, see @ref{FAQ font-lock}. @item There are cases where super- and subscripts are not displayed, see @ref{Super and Subscripts}. @item The argument in braces are not correctly recognized, since the @code{font-lock} syntax-table is not correct. It should include @samp{@{} as the only open parenthesis and @samp{@}} 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 @code{font-lock} package, but would require other changes there, therefore not likely to be fixed. Fortunately, this does not happen often. @end itemize @node FAQ Stupid Subscripts, FAQ Font Size, FAQ No Subscripts, FAQ @comment node-name, next, previous, up @subsection I See Super- and Subscripts where I Don't Want Them. @pindex font-lock @pindex font-latex @cindex Stupid Subscripts @cindex Annoying Subscripts @cindex Label Subscripts @cindex Subscript Problems @cindex Superscript Problems E.g., I see a subscript in arguments of @code{\label}. Package X-Symbol only uses super- and subscripts if they are in braces, if the @code{asciicircum}/@code{underscore} has not been fontified yet or is only fontified with faces which are allowed by @code{x-symbol-tex-font-lock-allowed-faces}, see @ref{Super and Subscripts}. @itemize @bullet @item You use the default @code{tex-font-lock-keywords}: The argument of @code{\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 @code{font-latex}, see below. @item You use package @code{font-latex}. Solution: set @code{font-lock-maximum-decoration} to value @code{t}, 2 or higher. Package X-Symbol will still use subscripts in @code{\verb}, in the @code{verbatim} environment, in the argument of @code{\includegraphics} and probably other commands. Some of these problems will probably be solved by future versions of @code{font-latex}. @item You use my font-lock keywords (file @file{x-font-lock.el}): everything should work fine. Please note that this file is not meant to be a replacement of @file{font-latex.el} useful to all users. Also, highlighting is a matter of taste, i.e., I am not going to change the @file{x-font-lock.el} to support La@TeX{}-2.09, @TeX{}'s math regions, other likings, etc. @item 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. @end itemize @node FAQ Font Size, FAQ Conversion, FAQ Stupid Subscripts, FAQ @comment node-name, next, previous, up @subsection The Characters are Too Small or Too Big @cindex Font Size @cindex Big Characters @cindex Small Characters 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). @emph{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 (@pxref{Info}) that you actually get the correct letter---they are just of different sizes. @xref{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. @node FAQ Conversion, FAQ Additional Spaces, FAQ Font Size, FAQ @comment node-name, next, previous, up @subsection The Conversion Changes Some Tokens @cindex Token Changes @cindex Conversion Problems @cindex Encoding Problems 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. @xref{Unique Decoding}. @itemize @bullet @item Solution: Do not redefine standard @TeX{} macros or use unique decoding. @end itemize @node FAQ Additional Spaces, FAQ 8bit Chars, FAQ Conversion, FAQ @comment node-name, next, previous, up @subsection A Space is Added During the Encoding @cindex Additional Spaces @cindex Token Problems @cindex Encoding Problems @cindex Space Problems A space is added after some characters during the encoding to tokens. With token languages @code{tex} and @code{utex} (not with language @code{sgml}), there must be a space after the token to recognize its end in some cases. E.g., if your buffer contains @samp{a+b} (where + stands for the character @code{circleplus}), this is encoded to @samp{a\oplus b} (note the space after @code{\oplus}). Decoding it yields @samp{a+ b}. I admit, this looks ugly. The space is only added if the symbol character is followed by a letter or by @samp{@@}. Thus, decoding @samp{a\oplus\beta} yields @samp{a+b} (without space!). @itemize @bullet @item Suggestion: Also use a space before @code{\oplus}. The alternative would be to delete the space which other people won't like. @end itemize For an exact description, @xref{TeX Macro Conversion} for an exact description. @node FAQ 8bit Chars, FAQ Hyphen, FAQ Additional Spaces, FAQ @comment node-name, next, previous, up @subsection I Don't Want 8bit Characters in the File @cindex 8bit Character Problems @cindex No 8bit Characters By default, these are not encoded if the buffer-local variable @code{x-symbol-8bits} is non-@code{nil}. By default, this variable is only set to non-@code{nil}, if something like @example \usepackage[latin1]@{inputenc@} @end example 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. @xref{File Coding}. Note: commenting the line is not enough! (I do not run La@TeX{} to check for the line, I just do plain text search.) @node FAQ Hyphen, FAQ Spell Check, FAQ 8bit Chars, FAQ @comment node-name, next, previous, up @subsection I Cannot Distinguish Character @code{hyphen} from @samp{-} @cindex Hyphen Versus Minus @cindex Minus Versus Hyphen In most fonts, the Latin character @code{hyphen} cannot be distinguish from the Ascii character @samp{-}. If you do not want to decode the corresponding token @code{\-} or @code{­}, put the following into your @file{~/.emacs}: @lisp (setq x-symbol-tex-user-table '((hyphen))) (setq x-symbol-sgml-user-table '((hyphen))) @end lisp A better alternative would be to make @code{font-lock} display these character in a different color. @node FAQ Spell Check, FAQ News and Mail, FAQ Hyphen, FAQ @comment node-name, next, previous, up @subsection Problems with Spell-checking @cindex Spell Checking @pindex ispell @findex ispell-word @findex ispell-region As explained in @ref{Miscellaneous Packages}, @code{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 @code{ispell-word} and @code{ispell-region}. Possible symptoms: @itemize @bullet @item A word which contains letters which the program @code{ispell} does not know about is either not spell-checked or parts of it are spell-checked as independent words. Solution: Use the @code{ispell}s 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 @code{oe} if you use a Latin-1 encoding. @item Spell-checking might stop with the error message @samp{Ispell misalignment}. I can reproduce this only with Emacs, not with XEmacs. Question: If you know some settings (like for @code{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 @code{flyspell}. @end itemize The real solution would be to fix @code{ispell}, at least by providing a useful hook which allows X-Symbol to fix the problem. @xref{Wishlist Emacs}. You are strongly encouraged to send a patch to the maintainer of @code{ispell}, you even get a paragraph here in @ref{Acknowledgments}! @node FAQ News and Mail, , FAQ Spell Check, FAQ @comment node-name, next, previous, up @subsection How to Use X-Symbol with Gnus or @sc{vm} @cindex News Reader @cindex Mail Reader @pindex Gnus @pindex VM @pindex Message You can also use X-Symbol to read and write your News and Mails. This sections includes coding for your @file{~/.emacs} if you want to do so. It has been tested for Gnus-5.8.8 and @sc{vm}-6.96; if you use @sc{rmail} or @sc{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. @lisp (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)))) @end lisp This is optional (you might want to use the Custom interface for the same effect) and tells Emacs/X-Symbol to use token language @code{tex} and to display super-/subscripts (if @code{font-lock} is enabled), X-Symbol is not automatically turned on. @xref{Minor Mode}. @findex mail @findex message-mail @findex vm-mail @vindex mail-send-hook @vindex message-send-hook @vindex vm-mail-send-hook @lisp (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) @end lisp This tells tells Emacs to automatically turn off X-Symbol (which includes encoding characters to token) before actually sending the message. @findex gnus @vindex gnus-article-prepare-hook @lisp (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) @end lisp Since Gnus reuses the @file{*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. @findex vm @vindex vm-select-message-hook @lisp (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) @end lisp The same thing for @sc{vm}, although the hook is not as nice as Gnus' one; the function therefore might depend a bit too much on @sc{vm}'s interna. @findex vm-mode @findex vm-presentation-mode @lisp (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)) @end lisp You cannot use X-Symbol in @sc{vm} Mode, only in @sc{vm} Presentation Mode (X-Symbol would change your @file{INBOX}). The first (optional) Emacs Lisp expression gives you a better error message when you try to turn on X-Symbol Mode in @sc{vm} Mode. The second line makes sure that @sc{vm} always uses @sc{vm} Presentation Mode to display the articles. @c =========================================================================== @node Bug Reports, , FAQ, Problems @comment node-name, next, previous, up @section How to Send a Bug/Problem Report @cindex Bug Reports @cindex Problem Reports @cindex Contacting the Maintainer @cindex Maintainer Address @cindex Email to the Maintainer @cindex Reports of Bugs Bug fixes, bug/problem reports, improvements, and suggestions are strongly appreciated. So are corrections to this manual (better explanations, correcting my English, @dots{}). Especially useful would be some feedback by people using default fonts with a charset registry-encoding other than @code{iso8859-1} (Western encoding). Please read this section carefully, even if you generally know how to send a bug report (@pxref{Bugs,,,@value{emacs},@value{emacsman}}). This might look tedious to you, but it actually saves a lot of time (your time, too). The @strong{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: @enumerate @item Make sure that you use the @strong{newest version} of X-Symbol. You are reading Edition @value{edition} (@value{subedition}) of the manual for X-Symbol @value{version}. @item Read the manual, especially @ref{Checking Installation}, @ref{Problems}, and @ref{FAQ}. The four indexes (@pxref{Indexes}) might also lead you to an answer to your question. @item Use @kbd{M-x x-symbol-package-bug} (also to be found in X-Symbol's Command submenu) to write your report describing @emph{one} bug or problem, i.e., use @strong{different mails} for @strong{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' @file{*mail*} buffer to your mail tool. If @kbd{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 @samp{x-symbol @var{version}; @var{summary}} as Subject header where @var{version} is the version of X-Symbol (it should be @value{version}) and @var{summary} is a brief summary of your installation problem. (@emph{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.) @c The additional advantage is that I can see who doesn't have any problems @c wasting my time. @item Start your report with: @quotation In the manual, I checked the sections @var{section1}, @var{section2}, @dots{}, but didn't find anything which helped me with the following problem: @end quotation The sections @var{section1}, @var{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. (@emph{Rationale}: This way, I get an idea where to improve the manual, especially by adding cross references.) @c It also ensures that you really have tried to find the relevant @c information yourself. @item If buffer @file{*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 @samp{X-Symbol} is not mentioned there. Otherwise, include the contents of buffer @file{*Warnings*} into your bug report. @c TODO: without warnings.el from Emacs-21.4 Temporary Emacs (< v21.4) note: the warnings might be somewhere hidden in buffer @file{*Messages*}; please check that buffer. @item Put the parts of the code from @file{~/.emacs} and the system-wide files which causes the problem into a fresh file @file{@var{my-problem}.el}. The problem/error should be visible when invoking @example xemacs -no-site-file -q -l @var{my-problem}.el @end example In the minimal case, @file{@var{my-problem.el}} just contains the following line (@pxref{Installing Lisp}): @lisp (x-symbol-initialize) @end lisp If the error has disappeared after you have included your complete @file{~/.xemacs/init.el} and @file{~/.emacs}, the problem is likely caused by some code of your system-wide installation. Include the code, which can be found using command @kbd{M-x find-library} with files @file{site-start} and @file{default} (everything is fine if these files do not exist). If you use @file{x-symbol-site.el} (its use is deprecated), copy its contents into @file{@var{my-problem.el}} and delete the corresponding @code{load} command. Attach the file @file{@var{my-problem}.el} to your report. @strong{Please try to minimize the size of @file{@var{my-problem}.el}}! A standard technique is recursive halving: Delete the second half of @file{@var{my-problem.el}}. If the problem disappears, delete the first half instead. Do the same with the smaller file again, @dots{}. (@emph{Rationale}: Most problems are a consequence of some specific customizations, but I don't have time to debug each user's init file.) @item If you have set variable @code{custom-file} in @file{@var{my-problem}.el}, attach the corresponding file to your report. @item If the error can only be reproduced in combination with another Emacs package, please send me: @itemize @minus @item 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 @kbd{M-x find-library} to check whether you really use the version from the Emacs/XEmacs distribution). @item If it is a non-standard (and non-obscure) package: the URL of the distribution and/or the source. @item Otherwise: include its code into @file{@var{my-problem}.el} and delete the corresponding @code{load} or @code{require} command. Then, reduce the size of @file{@var{my-problem}.el} as described above. @end itemize @item If the problem is not reproducible with an @emph{arbitrary} (@file{.tex}, @file{.html}, @dots{}) 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.) (@emph{Rationale}: Most problems are only reproducible with specific files.) @ignore @item I would appreciate, if you would set variable @code{debug-on-error} to @code{t} before you trigger the error and send me the contents of buffer @file{*Backtrace*}. At best, using the uncompiled versions of the functions involved, i.e., by jumping to its definition and evaluation it: @example M-x find-function @key{RET} @var{function} @key{RET} C-M-f C-x C-e @end example @end ignore @item 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 @kbd{C-x C-f @var{file} @key{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 @kbd{C-h l} and include the contents of buffer @file{*Help*} in your bug report. (@emph{Rationale}: Most problems are only reproducible with point being at a specific position in the file, with specific key sequences, etc.) @item If you have problem with the display of images, please include the output of the shell commands @samp{convert -h} and @samp{convert -list Format} in your bug report. If the first command fails, you have a problem with the program @code{convert}, not X-Symbol. @item If necessary, include a screen-shot in your bug report. @item If you could not use @kbd{M-x x-symbol-package-bug}, include the contents of buffer @file{*Help*} after the following actions: @itemize @minus @item Type @kbd{C-h v x-symbol-version @key{RET}}. @item Type @kbd{C-h v emacs-version @key{RET}}. @item Type @kbd{C-h v features @key{RET}}. @end itemize @end enumerate 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 @ref{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. @c =========================================================================== @node History, Indexes, Problems, Top @comment node-name, next, previous, up @chapter History and Projects @menu * News:: Changes in recent versions. * Wishlist:: Projects for X-Symbol. * Open Questions:: How you can contribute. * Acknowledgments:: People having contributed. @end menu @c =========================================================================== @node News, Wishlist, History, History @comment node-name, next, previous, up @section News: Changes in Recent Versions of X-Symbol @cindex New Features @cindex Changes @cindex History This is the complete history of X-Symbol. It just lists the major changes before Version 3.0. @menu * Changes New:: To be announced. * Changes 4.5:: Released Mar 2003 as beta. * Changes 4.4:: Released June 2002 as beta. * Changes 4.1:: Released Mar 2002 as beta. * Changes 3.4:: Released Mar 2002. * Changes 3.3:: Released Jan 1999. * Changes 3.2:: Released Dec 1998. * Changes 3.1:: Released Oct 1998. * Changes 3.0:: Released Sep 1998 as beta. * Changes Old:: Overview of old releases. @end menu @node Changes New, Changes 4.5, News, News @comment node-name, next, previous, up @subsection Changes in X-Symbol @value{version} Version @value{version} has not yet been announced. @itemize @bullet @item Various bug fixes and minor changes. @end itemize @node Changes 4.5, Changes 4.4, Changes New, News @comment node-name, next, previous, up @subsection Changes in X-Symbol 4.5 Version 4.5 has been released on March 2003 as beta. @itemize @bullet @item X-Symbol finally respects the Mule coding system of each individual buffer. @item Bug fix: would mess up encoding of math-mode characters with token language @code{bib}. Other conversion fixes for languages @code{bib} and @code{texi}. @item Bug fix (workaround for bug in XEmacs): auto-save files would have length 0. @item Bug fix (Emacs): package now works with package @code{crypt}/@code{crypt++}. @item Token language @code{sgml}: always encode characters to entity references by default (where defined by the HTML standard). Include @code{hm--html-mode}, @code{html-helper-mode}, remove @code{sgml-mode} as typical major modes which use X-Symbol. @item Token language @code{tex}: support some symbols of package @file{stmaryrd.sty}. @item Change the auto-style, formerly auto-mode, mechanism. @item Image support when running on Emacs. @item New input method Quail, a usual Mule input method. @item Corrected Latin-5 definitions. Support Latin-5 (``Turkish'') on XEmacs running under Windows. @item X-Symbol works with Emacs/XEmacs running under a character terminal. @item Improments for external languages. Super-/subscript matching of token languages has changed. @item X-Symbol can use package @code{format} and does not require special fonts for super-/subscripts with Emacs-21.4+. Still open whether this will be used@dots{}. @item Dropped support for XEmacs-20.3. @item Various bug fixes and minor changes. @end itemize @node Changes 4.4, Changes 4.1, Changes 4.5, News @comment node-name, next, previous, up @subsection Changes in X-Symbol 4.2 to 4.4 Version 4.4 has been released on June 2002 as beta. @itemize @bullet @item Token language TeX has changed: no excessive use of braces anymore, no excessive normalization, and aware of environments @code{@{tabbing@}} and @code{@{verbatim@}}, and macro @code{\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. @item New token language ``Bib@TeX{} Macro'' (@code{bib}, similar to old @code{tex}), used for Bib@TeX{} files. @item Nuked executables, the Lisp conversion for all languages is now 2-5 times faster. @item Latin-9 support. Latin-9 font included in distribution. @item 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. @item 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 (@code{TeX-master}) with token language @code{tex}. @item New buffer-local variable @code{x-symbol-unique}: when non-@code{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 @code{utex}. @item Menu changes, new commands: submenu ``Conversion'', menu items ``Copy Encoded'', ``Paste Decoded'' and others. @item Special coding for @code{preview-latex}. Using X-Symbol now only gives a 10% overhead of @code{preview}s parsing time. @item X-Symbol now works with Whizzy@TeX{}. @item The interface for defining a token language has changed, it is also much more general, useful for ProofGeneral. @item Changed final bytes of ISO 2022 escape sequence for X-Symbol charsets since Emacs reserves the characters @samp{0-9} for itself. Does XEmacs has any policy here (it also uses @samp{?})? @item Dropped workaround for minor bug in XEmacs-20.X. @item Various bug fixes and minor changes. @end itemize @node Changes 4.1, Changes 3.4, Changes 4.4, News @comment node-name, next, previous, up @subsection Changes in X-Symbol 4.1 Version 4.1 has been released on Mar 2002 as beta. @itemize @bullet @item X-Symbol works with Emacs-21.1 or higher. Porting is not complete, yet. @item New token language ``@TeX{}info command'' (@code{texi}). @item Slightly different definition of ``valid character''. @item Remove the ``local if set'' and ``default: @dots{}'' submenu stuff. @end itemize @node Changes 3.4, Changes 3.3, Changes 4.1, News @comment node-name, next, previous, up @subsection Changes in X-Symbol 3.4 Version 3.4 has been released on Mar 2002. @itemize @bullet @item Moved to SourceForge.net. Added files for nicer HTML output of manual. @item Would sometimes perform strange conversions when @code{global-flyspell-mode} is enabled. @item Bug fixes: command @kbd{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). @item Automatically deduce default coding via @code{locale -ck LC_CTYPE}. @item Issue warning when running on XEmacs-21.0 to XEmacs-21.1.8. Update manual: XEmacs user package directory is @file{~/.xemacs/packages}. @item Directories ending with @file{//} in image search paths are recursive. @item New characters used for token languages ``@TeX{} macro'' and ``Isabelle symbol''. @item Make sure to convert just the first part of a multi-part image. @item Source distribution includes files for building an RPM package, all files also compile without Mule support. @item Minor changes. Manual changes. @end itemize @node Changes 3.3, Changes 3.2, Changes 3.4, News @comment node-name, next, previous, up @subsection Changes in X-Symbol 3.3 Version 3.3 has been released on Jan 1999. @itemize @bullet @item 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 @kbd{M-x x-symbol-exec-create}). @item New functions used for interaction with Emacs package @code{comint}. This is necessary for new token language ``Isabelle symbol'', to be distributed with Emacs package @uref{http://www.proofgeneral.org/,ProofGeneral}. @item New characters used for token languages ``@TeX{} macro'' and ``Isabelle symbol''. @item Minor changes. Manual changes. @end itemize @node Changes 3.2, Changes 3.1, Changes 3.3, News @comment node-name, next, previous, up @subsection Changes in X-Symbol 3.2 Version 3.2 has been released on Dec 1998. @itemize @bullet @item 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 @file{x-symbol-site.el} is deprecated. @item Reverting the buffer and using @code{vc} commands do not encode characters when not using @code{crypt}. (This did not work always.) @item Workaround for bug (segfault) in XEmacs-21/Mule betas. @item Command @code{x-symbol-package-bug} is less restrictive. Please use this command to contact the maintainer. @item Bug fixes. Minor changes. Manual changes. @end itemize @node Changes 3.1, Changes 3.0, Changes 3.2, News @comment node-name, next, previous, up @subsection Changes in X-Symbol 3.1 Version 3.1 has been released on Oct 1998. @itemize @bullet @item @TeX{} macro @code{\mu} is represented by a character in the Adobe Symbol font, not in a Latin-@{1,3,5@} font anymore. @item Support for most @sc{sgml} entities in HTML-4.0 specification. @item Additional characters for @code{\therefore}/@code{∴}, @code{‾} and @code{€}. @item Package X-Symbol has been customized. @item The documentation has been completed (as @TeX{}info file). @item Handle special URL prefixes @file{file:}, @file{http:} for images. @item Bug fixes, configuration changes. @end itemize @node Changes 3.0, Changes Old, Changes 3.1, News @comment node-name, next, previous, up @subsection Changes in X-Symbol 3.0 Version 3.0 has been released on Sep 1998 as beta. @itemize @bullet @item Package X-Symbol now works on XEmacs with and without Mule support. Dropped support for XEmacs 19.13 to 19.16/20.2. @item Full support of token language @code{sgml} (executables, subscripts, images). @item X-Symbol is a proper minor mode. @item Easier (automatic) 8bit character control (e.g., for @code{\times} @code{\pm},@dots{}). By default, the encoding when saving only writes 8bit characters, if @samp{\usepackage[latin@var{n}]@{inputenc@}} with @var{n}=1,2,3,5 was found in the first 10000 characters of the file (including commentary). @item 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 @item Key bindings have completely changed. They are now consistent with the contexts of input method Context (which have changed a bit). @item The keys @kbd{@@} and @kbd{!} 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. @item Input method Aggressive Context is now called input method Electric and is much more restrictive (using package @code{texmathp} with language ``@TeX{} macro''). @item Easier installation despite many additional features. @item Supports more characters. @item Nicer grid, info in echo area. @item Better cooperation with packages: @code{vc} (check-out does not convert characters), @code{reftex} (no strange characters @samp{\237}, help with label creation), @code{auctex}, @code{ispell}, @code{font-latex} (no annoyances with @code{\exists}). @item Safer use of executables. @item The code has completely changed. You have to redo your installation. @end itemize @node Changes Old, , Changes 3.0, News @comment node-name, next, previous, up @subsection 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. @itemize @bullet @item Fixed serious bug when used under tty. @end itemize Version 2.5 has been released on Mar 1998. @itemize @bullet @item Image support. @end itemize Version 2.4 has been released on Mar 1997. @itemize @bullet @item Token language @code{sgml}. (X-Symbol can handle more then token language @code{tex}.) @item Input method Aggressive Context (precursor of input method Electric), input method Context has been much improved. @item Fixed performance bug when saving a file with package @code{crypt}. @item Control of Conversion and 8bit character has changed. @end itemize Version 2.3 has been released on Sep 1996. @itemize @bullet @item Distributed with own font for more math characters. @item Info for the character around point in echo area. @end itemize Version 2.2 has been released on June 1996. @itemize @bullet @item Input method Grid. Help when using input method Keyboard. @item Control of Conversion and 8bit character has changed. @end itemize Version 2.1 has been released on April 1996. @itemize @bullet @item Fixed serious performance bug when loading files with font-lock/lazy-lock. Use executables for conversion of large buffers. @item The package @code{iso-cvt} is not integrated anymore. Now this package can also convert to/from Latin-1 characters, it is much faster. @item Menu support, including input method Menu. @item @code{isearch} works with X-Symbol characters. @item First multi-file version. @end itemize Version 1.4 has been released on Feb 1996. @itemize @bullet @item Provide some kind of ``poor man's Mule'' to remove most Nomule-Problems. @end itemize Version 1.3 has been released on Jan 1996. @itemize @bullet @item Input method Abbrev (precursor of input method Token). @item Super-/subscript support. @end itemize Version 1.2 has been released on Jan 1996. It was the first release. @itemize @bullet @item Conversion between characters and @TeX{} tokens. Do so automatically when visiting a file and saving the buffer. @item Input method Keyboard. @end itemize @c ==================================================================== @node Wishlist, Open Questions, News, History @comment node-name, next, previous, up @section Wishlist: Projects for X-Symbol @cindex Wishlist @cindex Project @cindex Future Features @cindex Contributions @cindex Your Contribution 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 @ref{Open Questions}. Providing a solution to these problems is the second way of making your name appear in @ref{Acknowledgments}. @menu * Wishlist Languages:: Additional token languages. * Wishlist Fonts:: Automatically generated fonts. * Wishlist Emacs:: Changes in Emacs/XEmacs. * Wishlist LaTeX:: Changes in La@TeX{}. * Wishlist Various:: Other changes. * Wishlist Rejected:: Rejected Suggestions for X-Symbol. @end menu @node Wishlist Languages, Wishlist Fonts, Wishlist, Wishlist @comment node-name, next, previous, up @subsection Wishlist: Additional Token Languages @cindex More Token Languages @cindex Language Additions @cindex Ams@TeX{} @cindex IPA Fonts 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 (@pxref{Extending X-Symbol}) for general-interest token languages (e.g., Ams@TeX{}). It is likely that this would require additional fonts: available fonts (e.g., IPA font), hand-crafted, or generated (@pxref{Wishlist Fonts}). @node Wishlist Fonts, Wishlist Emacs, Wishlist Languages, Wishlist @comment node-name, next, previous, up @subsection Wishlist: Generated Fonts @cindex Generated Fonts @cindex Fonts from Other Sources @cindex Fonts for Windows @cindex MS-Windows Fonts @cindex Windows Fonts @pindex bdftofon A specific direction of font generation would be from @file{.bdf} or @file{.pcf} font files to Windows fonts to get rid of the limited support for XEmacs on Windows (@pxref{Requirements}). If you have successfully converted X-Symbol's fonts from the Unix format to the Windows format (via @code{bdftofon} or whatever) or if you have free and real Latin-N fonts for Windows, please @emph{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 @file{.bdf} or @file{.fon} fonts from other sources. This would have various advantages: @itemize @bullet @item We could easily create different sizes for our symbol font. @item It would be quite simple to create a font for Ams@TeX{} macros, etc., which would be displayed as X-Symbol characters by package X-Symbol. @item We could easily create different sizes for our symbol font. @item We would have fonts for both X11 and Windows. @end itemize New fonts for X-Symbol are being worked on. You can find material to generate them at the @uref{@value{url}/news.html,web pages of X-Symbol}. 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 @uref{@value{listdevel},X-Symbol development mailing list}. General open design issues (i.e., they could be re-thought for the currently used handcrafted fonts, too) are: @itemize @bullet @item Different @TeX{} macros (same appearance, different @TeX{} class = different spacing) use the same MetaFont character, e.g., @code{\dagger} and @code{\dag}. Therefore, we need different X11 characters for them. @item Some Ascii characters have a special meaning in @TeX{}. The corresponding MetaFont character is therefore produced by a TeX macro, e.g., @samp{@{} by @code{\@{}. @c @}@} We need a X11 character which looks similar to the character but not exactly like it. @end itemize We could ask the question whether we should really distinguish the characters by appearance@dots{}we have the minibuffer info for the X-Symbol character anyway@dots{}. Here are the options: @itemize @minus @item distinguished by size/underlining/miscellaneous (currently used), @item distinguished by different spacing (my current favorite), @item not distinguished @end itemize @node Wishlist Emacs, Wishlist LaTeX, Wishlist Fonts, Wishlist @comment node-name, next, previous, up @subsection Wishlist: Changes in Emacs/XEmacs @cindex Emacs Changes @cindex XEmacs Changes @cindex Changes in Emacs @cindex Changes in XEmacs Changes in Emacs and/or XEmacs would improve package X-Symbol, too: @itemize @bullet @item In Emacs: a package system similar to XEmacs' one. The installation would be easier. @item @pindex ispell The package @code{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 @code{ispell} (it will be better in Emacs-21.4), see @ref{Miscellaneous Packages}. @item @pindex vc Some versions control commands turn off @code{font-lock}. This should be changed. @item Provide a face property @code{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 @code{font-lock} set properties other than faces). XEmacs: no such property, yet. @item 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 @code{latin-unity} (@pxref{File IO Packages}). @item @findex isearch In Emacs, will be fixed in 21.4. Using @code{isearch} and the input method Grid would not work. @item @vindex after-insert-file-functions In XEmacs, fixed in 21.X. In @code{after-insert-file-functions}, there should be a possibility to get to know the start position of the region which is inserted. If @code{insert-file-contents} is called with argument @code{replace} being non-@code{nil}, it is not always point. @item @vindex write-region-annotate-functions In Emacs and XEmacs, will be fixed in Emacs-21.4. Make possibility to change buffers in @code{write-region-annotate-functions} official, see @ref{Alt Auto Conversion}, have a way to get the original buffer. @item Since @code{font-lock} uses duplicable text properties in some cases, I need a function like @code{insert-buffer-substring-without-extents}. (Currently, I remove the extents afterwards, which looks slow for me.) @item @vindex post-command-hook In XEmacs. Run hooks in @code{post-command-hook} even if command exits with an error or quit (as it is in Emacs) or having some @code{post-error-or-quit-hook}. @xref{Nomule Problems}. @item In XEmacs. There are some bugs in package @code{custom}/@code{widget} (still in XEmacs-21.4) which are visible during the customization of X-Symbol. @end itemize @node Wishlist LaTeX, Wishlist Various, Wishlist Emacs, Wishlist @comment node-name, next, previous, up @subsection Wishlist: Changes in La@TeX{} @cindex La@TeX{} Changes @cindex Changes in La@TeX{} @cindex @file{inputenc.sty} Changes @pindex @file{inputenc.sty} Changes in La@TeX{}, especially @file{inputenc.sty}, would improve package X-Symbol, too: @itemize @bullet @item To make the definition of the character U00B5 consistent with Unicode, @file{inputenc.sty} should define the character to stand not for the token @code{\mu} (U03BC is the right character), but for an extra token, e.g., something like @code{\textmicro}. X-Symbol uses @code{\mathmicro} here in order to avoid changing @code{\mu} to the character U00B5 if you have chosen to store 8bit characters. @c X-Symbol should not define it as \textmicro because then there would @c be a major difference between `x-symbol-8bits' nil and non-nil. @item Use same encoding for both text and math, i.e. use @code{periodcentered} for both @code{\textperiodcentered} (the default) and @code{\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 @code{\lnot}, @code{\pm}, @code{\times} and @code{\division}: use @code{\textonesuperior} for U00B9, \texttwosuperior for U00B2, and @code{\textthreesuperior} for U00B3. @item The @TeX{} macros @code{\textcent}, @code{\textcurrency}, @code{\textbrokenbar}, @code{\textyen} are defined as not available with OT1 and T1 font encoding. This should be changed. @end itemize @node Wishlist Various, Wishlist Rejected, Wishlist LaTeX, Wishlist @comment node-name, next, previous, up @subsection Various Projects for X-Symbol The following suggestions seem to be useful, though not essential: @itemize @bullet @item @cindex Print Buffer @cindex Buffer Printing @pindex ps-print 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 @code{ps-print}. A newer version of @code{ps-print} might be probably already capable of doing it. Thus, you are encouraged to help the XEmacs team updating this package. @end itemize @node Wishlist Rejected, , Wishlist Various, Wishlist @comment node-name, next, previous, up @subsection Rejected Suggestions for X-Symbol @cindex Rejected Suggestions 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: @itemize @bullet @item @cindex Input Method Token It would be nice if X-Symbol would replace the token with the last character of the token if this is possible (@pxref{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. @end itemize @c =========================================================================== @node Open Questions, Acknowledgments, Wishlist, History @comment node-name, next, previous, up @section Open Questions @cindex Open Questions @cindex Various Questions @cindex Questions I Have This section lists some minor open questions. @itemize @bullet @item @findex x-symbol-initialize @cindex Auto Initialization Loading file @file{x-symbol.el} will initialize package X-Symbol (via function @code{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 @file{x-symbol.el}. Thus, customizing package X-Symbol will not initialize package X-Symbol. The alternative would be to call function @code{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 @code{x-symbol-initialize} top-level in file @file{x-symbol.el}. If I am wrong here, please let me know (with an explanation). Batch-compilation might be an issue@dots{} @item @pindex crypt @vindex x-symbol-auto-conversion-method When is necessary to set @code{x-symbol-auto-conversion-method} to @code{slowest}? Of course, it is only necessary when using @code{crypt}. Is the other necessary condition to use the computer pool of the University of Edinburgh? @end itemize @c =========================================================================== @node Acknowledgments, , Open Questions, History @comment node-name, next, previous, up @section Acknowledgments @cindex Acknowledgments @cindex Contributions @cindex Marlet, Renaud @cindex Bradfield, Julien @pindex math-mode @cindex Adobe @pindex frame-icon @cindex Thanks 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 @ref{Wishlist Fonts}. His work is now available at the X-Symbol download area. Package @code{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 @code{makesub} is a merge and change of the scripts @code{makesupers} and @code{makesub} by Julian. The font @samp{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 @code{frame-icon}. The idea for Help during an X-Symbol key sequence is from package @code{x-compose}. The general idea for showing some info in the echo area is from package @code{eldoc}. The trick which stops @code{expand-abbrev} is from package @code{mail-abbrevs}. The idea for @code{x-symbol-image-cache-directories} is from package @code{fast-lock}. The code for image command parsing is influenced by some code in package @code{font-lock}. The code around @code{x-symbol-image-delete-extents} is based on some code in package @code{bib-cite}. @i{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@"opl, 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@o{}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. @i{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: @display @url{http://www.w3.org/TR/REC-html40/sgml/entities.html} @url{http://www.fmi.uni-passau.de/~ramsch/iso8859-1.html} @url{http://czyborra.com/charsets/iso8859.html} @url{http://www.bbsinc.com/iso8859.html} @url{http://www.bbsinc.com/iso8879.html} @url{http://ppewww.ph.gla.ac.uk/~flavell/charset/internat.html} @url{http://ppewww.ph.gla.ac.uk/~flavell/iso8859/iso8859-pointers.html} @url{http://sizif.mf.uni-lj.si/linux/cee/iso8859-2.html} @end display I do not intend to update this list in the future---this is just an "Acknowledgment" section. @node Indexes, , History, Top @comment node-name, next, previous, up@unnumbered Indexes @unnumbered 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 (@pxref{Bug Reports}), @menu * Key Index:: Key sequences. * Program Index:: Programs and Emacs packages. * Variable Index:: Commands, functions, variables. * Concept Index:: Various topics. @end menu The links lead you to the manual sections describing X-Symbol's commands and variables. @xref{About}. @comment workaround for bug with the length of the lists @iftex @vskip 6ex plus 1ex minus 4ex @end iftex @node Key Index, Program Index, Indexes, Indexes @comment node-name, next, previous, up @unnumberedsec Key Index @printindex ky @comment workaround for bug with the length of the lists @iftex @page @end iftex @node Program Index, Variable Index, Key Index, Indexes @comment node-name, next, previous, up @unnumberedsec Program and Package Index @printindex pg @comment workaround for bug with the length of the lists @iftex @page @end iftex @node Variable Index, Concept Index, Program Index, Indexes @comment node-name, next, previous, up @unnumberedsec Command, Function and Variable Index @printindex vr @comment workaround for bug with the length of the lists @iftex @page @end iftex @node Concept Index, , Variable Index, Indexes @comment node-name, next, previous, up @unnumberedsec Concept Index @printindex cp @contents @bye @c Local IspellPersDict: .ispell_xsymb