diff options
| -rw-r--r-- | x-symbol/man/x-symbol.texi.2 | 7476 |
1 files changed, 7476 insertions, 0 deletions
diff --git a/x-symbol/man/x-symbol.texi.2 b/x-symbol/man/x-symbol.texi.2 new file mode 100644 index 00000000..f23dcbfb --- /dev/null +++ b/x-symbol/man/x-symbol.texi.2 @@ -0,0 +1,7476 @@ +\input texinfo +@c Copyright (C) 1998-2003 Free Software Foundation, Inc. +@c +@c Author: Christoph Wedler <wedler@users.sourceforge.net> +@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 +@set version 4.5 +@set update January 2003 +@set http http://x-symbol.sourceforge.net +@set maintainer wedler@@users.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 AUCTeX + +@set reftex reftex +@set reftexman RefTeX 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} 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. Please read section @ref{Bug Reports} if you want to +contact the maintainer of package X-Symbol. +@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:: Encoding of your default charset. +* 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. + +History and Projects + +* News:: Changes in recent versions. +* Emacs Version:: Beta Version which Works with Emacs +* 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.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{<sub>} 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{<img +src=@var{file}>} 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{http}/} +@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. + +Section @ref{X-Symbol Internals} is for the curious reader and for +people who want to define their own token language. + +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 +@pindex X +@pindex Windows/NT + +Package X-Symbol only works with Emacs-21.1 or higher (X-Symbol's +development version, only, @ref{Emacs Version}), and XEmacs 20.3 or +higher (XEmacs-21.1.9 is strongly recommended, @ref{FAQ XEmacs Core}), +with or without Mule support. + +Package X-Symbol works under X and tty (probably of limited use under +tty). It also works under Windows/NT with the following restrictions: +On XEmacs-21.4+, it just supports a @emph{limited number of characters} +(Latin-1 and half the math symbols), and @emph{no super- and subscripts} +due to missing MS-Windows fonts. @xref{Wishlist Fonts}. + +@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{http}/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 you get a warning about X-Symbol not being +able to deduce a default encoding (or about limited support with XEmacs +on MS-Windows), check @ref{Default Coding}. If your XEmacs runs on a +different machine, check @ref{Installing Fonts}. + +If your tty console does not support Latin characters, there is no +reason to use package X-Symbol. In this case, use the following +instead: + +@lisp +(if (eq (console-type) 'x) (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 MS-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 +@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} 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 +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}). + +@c also ucs-tables.el? should be no problem@dots{} + +@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}, @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 Elisp 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/NT) +@cindex Installing Fonts +@cindex Fonts +@pindex Exceed +@pindex Windows/NT + +If your X-server on Windows/NT 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/NT. 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/NT 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. + +@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 +Section @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 (@ref{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 MS-Windows (@pxref{Requirements}). + + +@menu +* Default Coding:: Encoding of your default charset. +* 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 Default Coding +@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 +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 +<!-- Local Variables: --> +<!-- x-symbol-coding: iso-8859-2 --> +<!-- 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 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{<meta @dots{} +charset=@dots{}>} (@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 (@xref{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, @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, @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, @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. The menu might also include individual entries for a token +language (@pxref{TeX Macro Basics}): + +@vtable @code +@item x-symbol-@var{lang}-extra-menu-items +Extra menu items for each token language @var{lang}. +@end vtable + +@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 numeric prefix argument, turn +X-Symbol mode on if the argument is positive, else turn it off. +@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}. + +@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. +@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 chapter @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{http}/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, @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} +(influences input method , +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{<sup>}/@code{<sub>} (@pxref{SGML Entity}): + +@vtable @code +@item x-symbol-@var{lang}-font-lock-keywords +The super-/subscript @code{font-lock} keywords for each token language +@var{lang}. +@end vtable + +@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 a scaled-down version of 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{<img>} (@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 MS-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. + +@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}, @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, @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 +<meta http-equiv="content-type" + content="text/html; charset=@var{encoding}"> +@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{<sup>}@dots{}@code{</sup>} and the subscript +command @code{<sub>}@dots{}@code{</sub>} 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 +<img @var{@dots{}} src="@var{file}.@var{ext}" @var{@dots{}}> +@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 La@TeX{} buffers, characters in @samp{$%\@{@}} have a special +syntax. Thus, you should 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 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 Elisp 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 Elisp 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 Elisp 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. + +@item +Needs pre/post-conversion in lisp when using executables for the conversion. +@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: \<NAME> +@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 () "\\<Prod>") +@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. +@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. @pxref{Wishlist Emacs} and @ref{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 + +@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 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}! + +@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). + +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} 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 @strong{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 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. The additional +advantage is that I can see who doesn't have any problems 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 (not +numbers!) 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. It also ensures that you really +have tried to find the relevant 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*}. + +@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, try to minimize the file such that +the problem can be still reproducible, and include the file with its +full file name into your bug report. + +(@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. +* Emacs Version:: Beta Version which Works with Emacs +* Wishlist:: Projects for X-Symbol. +* Open Questions:: How you can contribute. +* Acknowledgments:: People having contributed. +@end menu + +@c =========================================================================== + +@node News, Emacs Version, 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.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.4, 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 +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 +Token language @code{sgml}: always encode characters to entity +references by default (not possible with most Latin-N characters, where +we still use character entities). Include @code{hm--html-mode}, +@code{html-helper-mode}, remove @code{sgml-mode} as typical major modes. + +@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/NT. + +@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 +Various bug fixes and minor changes. +@end itemize + +@node Changes 4.4, Changes 4.1, Changes New, News +@comment node-name, next, previous, up +@subsection Changes in X-Symbol 4.2, 4.3, 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 MS-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 Emacs Version, Wishlist, News, History +@comment node-name, next, previous, up +@section Beta Version which Works with Emacs +@cindex Emacs Version +@cindex Beta Version +@cindex Development Version +@cindex Helpers for Emacs Version +@cindex Looking for Helpers +@cindex Gnu Emacs Version +@cindex Your Contribution + +You are reading the manual for the development (beta) version of +X-Symbol which works with Emacs-21.1. This version is also superior in +other aspects to the stable version 3.4.2. + +For details and updates, please check the +@uref{@value{http}/news.html, web pages of X-Symbol}. + +@c ==================================================================== + +@node Wishlist, Open Questions, Emacs Version, 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 Elisp +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 MS-Windows +@cindex MS-Windows Fonts + +@pindex bdftofon +One direction of font generation would be from @file{.bdf} or +@file{.pcf} font files to MS-Windows fonts to get rid of the limited +support for XEmacs on MS-Windows (@pxref{Requirements}). If you have +successfully converted X-Symbol's fonts from the Unix format to the +MS-Windows format (via @code{bdftofon} or whatever) or if you have free +and real Latin-N fonts for MS-Windows, please @emph{let me know}! I +would also appreciate if you would actively try to get those missing +MS-Windows fonts. + +Solofo Ramangalahy suggests to automatically generate the @file{.bdf} +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 @file{.bdf} font for Ams@TeX{} +macros, calligraphical letters etc, which would be displayed as X-Symbol +characters by package X-Symbol. + +@item +We could easily create different sizes for our symbol font. +@end itemize + +Solofo has worked on Postscript fonts. Although the results are good +for big sizes, this cannot replace bdf fonts for ``small'' sizes like +14. Besides, the X font server is not very good for postscript fonts +(compared with ATM where you have anti-aliasing for example). Now that +XEmacs run under windows, it may be that the result is better under +MS-Windows than under Unix. This has not been tested. + +An other possibility is to use true type fonts as true type font servers +can achieve better results with good hinted fonts. This has not been +done yet. + +There are also some problems which are not optimally solved in the current +xsymb font either: + +@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{\@{}. 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 + +Solofo Ramangalahy originally though of generating the @file{.bdf} fonts +out of @TeX{} fonts (@file{.mf}, @file{.pk}) by @code{mftobdf} of +See@TeX{}, which can be found at @file{@var{ctan}/dviware/seetex/} among +others distributions having this tool. He dropped this idea for the +following reason: + +@quotation +The created fonts need some correction by hand, since it's difficult to +make good fonts at small size. MF fonts were created to be printed at +high resolutions (in the MetaFont book, cheapo is 200 pixel per inch, +resolution of screens are around 100 pixel per inch). The parameters +@samp{blacker}, @samp{fillin} and @samp{o_correction} are not sufficient +for tuning the computer modern fonts at low resolutions (they will not +do the job of hints of a postscript font). +@end quotation + +@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}, @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 +@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 +Partly fixed in Emacs-21.3. 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} +(XEmacs-21.0-b59) 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. + +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, 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, Marciano Siniscalchi, Richard M. Stallman, +Alex Russell, 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 |