8. Problems, Troubleshooting

This section is based on a successful installation of package X-Symbol. See section 2.11 Checking the Correct Installation of Package X-Symbol.

8.1 Problems under XEmacs/no-Mule

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 "poor man's Mule", see 3.4 Poor Man's Mule: Running Under XEmacs/no-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):

• If font-lock is not prepared to display these two-character sequences, i.e., if you installation is incomplete (see section 3.5 The Role of font-lock), they look like `\233a' instead alpha.

• Commands which add more than one entry to the buffer-undo-list and involve X-Symbol characters might lead to strange results, e.g. C-t (transpose-chars) with point between character alpha and `b', leads to beta`a'. Simple deletion and insertion works OK, though.

• Selecting or inserting a rectangle with X-Symbol characters on the left or right margin might not work properly.

• Be careful with M-% (query-replace): the first character of from-string can probably match the second of the two "internal" characters of an X-Symbol character.

• If you use C-x ' (expand-abbrev) without M-' (abbrev-prefix-mark) and the last word before point starts directly after a X-Symbol character, C-x ' could behave strange:
  • If words-include-escapes is t, there will be no expansion.

  • If words-include-escapes is 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.

• 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 (C-g). Unfortunately, XEmacs (as opposed to Emacs) does not run the hooks in post-command-hook in these cases. Solution: move point right (C-f).

• If you provide prefix arguments to commands, they are likely to consider just "internal" characters. E.g., C-u 2 C-f before alpha behaves like C-f.

• Column position considers "internal" characters, e.g., C-n might jump to an unexpected position (well, typically just one character left/right from the expected position, if at all).

• Auto-filling also considers "internal" characters, i.e., might break the line too early.

• There are no syntax definitions for the new characters, e.g., M-C-f before floorleft does not move to the closing floorright.

• In some cases, e.g., when using the minibuffer for input via M-% or C-s, the internal representation of X-Symbol characters (see section 7.1 Internal Representation of X-Symbol Characters) are displayed directly (see section 8.4.3 The Buffer Contains Strange Characters)

8.2 Spurious Encodings

In rare cases, some commands (mostly from package 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.

• Doing the next logical version control operation (C-x v v and friends) encode characters to tokens when using package crypt.

  Solution: use package jka-compr instead crypt (this is recommended anyway, see section 2.6.3 File I/O Packages). Or kill the buffer and revisit the file.

• When using AucTeX with its default-mode algorithm, getting rid of the recently checked-in version of a file without reverting the buffer afterwards (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 `\233a'.

  Explanation: when using AucTeX's TeX-default-mode, the final major-mode is different from the initial major-mode deduced using auto-mode-alist. If this is the case, the VC command executes normal-mode which kills all local-variables including turning-off x-symbol-mode.

  Solution: Turn on X-Symbol mode or change auto-mode-alist to directly choose latex-mode:

  (push '("\\[tT]e[xX]\\'" . latex-mode) auto-mode-alist)

• When using AucTeX with its default-mode algorithm, writing a LaTeX 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 AucTeX's TeX-default-mode, we get the problems as described in the previous item.

  Solution: Set change-major-mode-with-file-name to nil or use the solution from the previous item.

8.3 The Encoding Does Not Work

In a rare case, X-Symbol cannot do its encoding, i.e., convert the characters to tokens.

• M-x write-region fails to do the encoding if you use package crypt.

  Explanation: with package crypt, the encoding has to be done by a function in write-file-hooks which is not used by write-region.

  Solution: use package jka-compr instead crypt (this is recommended anyway, see section 2.6.3 File I/O Packages). Or visit the region file and save it again via C-x C-s.

8.4 Frequently Asked Questions

It is assumed that you had successfully installed package X-Symbol, see 2.11 Checking the Correct Installation of Package X-Symbol.

8.4.1 XEmacs Crashes when using 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 2.1 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 x-symbol-xmas-warn-about-core to 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 newest version of XEmacs (please put me in the CC).

8.4.2 X-Symbol's Fontification does Not Work

In this case, super- and subscripts are not properly displayed (see section 8.4.4 I Cannot See any/some Super- or Subscripts) and under XEmacs/no-Mule, the buffer contains s.th. like `\233a' (see section 8.4.3 The Buffer Contains Strange Characters). Possible causes:

• You have turned off font-lock or font-lock is out of sync. Use M-x x-symbol-fontify. See section 3.5 The Role of font-lock.

• The font-lock keywords of the current buffer are not prepared to display X-Symbol characters. See section 3.5 The Role of font-lock.

• You use package fast-lock. Solution: set fast-lock-save-faces to nil (done by default installation).

• You use some version control commands. You have probably noticed that these versions control commands also turn off font-lock in modes where you don't use X-Symbol, i.e., this is not a problem of package X-Symbol. See section 9.2.3 Wishlist: Changes in Emacs/XEmacs. See section 8.2 Spurious Encodings.

8.4.3 The Buffer Contains Strange Characters

If you see s.th. like `\233a', you see the internal representation of X-Symbol characters under XEmacs/no-Mule (see section 7.1 Internal Representation of X-Symbol Characters) directly. Possible causes:

• You have font-lock problems, see 8.4.2 X-Symbol's Fontification does Not Work.

• More complicated editing commands like C-t may produce strange character sequences which do not represent X-Symbol characters, see 8.1 Problems under XEmacs/no-Mule.

• In some cases, e.g., when using the minibuffer for input via M-% or C-s, it would be too much work to fontify these character sequences in order to display proper X-Symbol characters. See section 8.1 Problems under XEmacs/no-Mule.

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 adobe-fontspecific, but in fact uses another encoding. E.g., Mathematica's fonts cause the characters intersection and union to mix up. Possible solutions:

• Delete that font from the font path. Maybe moving it at the end also works.

• 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

  (setq face-ignored-fonts '("\\`-wri-math1"))

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

8.4.4 I Cannot See any/some Super- or Subscripts

If you cannot select `Super-/Subscripts' in the menu, the first of the following points is more likely the cause, the others otherwise.

• You have font-lock problems, see 8.4.2 X-Symbol's Fontification does Not Work.

• There are cases where super- and subscripts are not displayed, see 5.1 Super- and Subscripts.

• The argument in braces are not correctly recognized, since the font-lock syntax-table is not correct. It should include `{' as the only open parenthesis and `}' 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 font-lock package, but would require other changes there, therefore not likely to be fixed. Fortunately, this does not happen often.

8.4.5 I See Super- and Subscripts where I Don't Want Them.

E.g., I see a subscript in arguments of \label. Package X-Symbol only uses super- and subscripts if they are in braces, if the asciicircum/underscore has not been fontified yet or is only fontified with faces which are allowed by x-symbol-tex-font-lock-allowed-faces, see 5.1 Super- and Subscripts.

• You use the default tex-font-lock-keywords: The argument of \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 font-latex, see below.

• You use package font-latex. Solution: set font-lock-maximum-decoration to value t, 2 or higher. Package X-Symbol will still use subscripts in \verb, in the verbatim environment, in the argument of \includegraphics and probably other commands. Some of these problems will probably be solved by future versions of font-latex.

• You use my font-lock keywords (file `x-font-lock.el'): everything should work fine. Please note that this file is not meant to be a replacement of `font-latex.el' useful to all users. Also, highlighting is a matter of taste, i.e., I am not going to change the `x-font-lock.el' to support LaTeX-2.09, TeX's math regions, other likings, etc.

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

8.4.6 The Characters are Too Small or Too Big

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). 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 (see section 5.3 Info in Echo Area) that you actually get the correct letter--they are just of different sizes. See section 2.9 Lisp Coding when Using Other Fonts.

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.

8.4.7 The Conversion Changes Some Tokens

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. See section 3.2.4 Unique Decoding.

• Solution: Do not redefine standard TeX macros or use unique decoding. See section 6.2.3 Problems with TeX Macros.

8.4.8 A Space is Added During the Encoding

A space is added after some characters during the encoding to tokens. With token languages tex and utex (not with language sgml), there must be a space after the token to recognize its end in some cases.

E.g., if your buffer contains `a+b' (where + stands for the character circleplus), this is encoded to `a\oplus b' (note the space after \oplus). Decoding it yields `a+ b'.

I admit, this looks ugly. The space is only added if the symbol character is followed by a letter or by `@'. Thus, decoding `a\oplus\beta' yields `a+b' (without space!).

• Suggestion: Also use a space before \oplus. The alternative would be to delete the space which other people won't like.

For an exact description, See section 6.2.4 The Conversion of TeX Macros for an exact description.

8.4.9 I Don't Want 8bit Characters in the File

By default, these are not encoded if the buffer-local variable x-symbol-8bits is non-nil.

By default, this variable is only set to non-nil, if something like

\usepackage[latin1]{inputenc}

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. See section 3.2.2 File Coding of 8bit Characters. Note: commenting the line is not enough! (I do not run LaTeX to check for the line, I just do plain text search.)

8.4.10 I Cannot Distinguish Character hyphen from `-'

In most fonts, the Latin character hyphen cannot be distinguish from the Ascii character `-'. If you do not want to decode the corresponding token \- or ­, put the following into your `~/.emacs':

(setq x-symbol-tex-user-table '((hyphen)))
(setq x-symbol-sgml-user-table '((hyphen)))

A better alternative would be to make font-lock display these character in a different color.

8.4.11 Problems with Spell-checking

As explained in 2.6.4 Miscellaneous Packages, 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 ispell-word and ispell-region. Possible symptoms:

• A word which contains letters which the program ispell does not know about is either not spell-checked or parts of it are spell-checked as independent words.

  Solution: Use the ispells 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 oe if you use a Latin-1 encoding.

• Spell-checking might stop with the error message `Ispell misalignment'. I can reproduce this only with Emacs, not with XEmacs.

  Question: If you know some settings (like for 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 flyspell.

The real solution would be to fix ispell, at least by providing a useful hook which allows X-Symbol to fix the problem. See section 9.2.3 Wishlist: Changes in Emacs/XEmacs. You are strongly encouraged to send a patch to the maintainer of ispell, you even get a paragraph here in 9.4 Acknowledgments!

8.4.12 How to Use X-Symbol with Gnus or VM

You can also use X-Symbol to read and write your News and Mails. This sections includes coding for your `~/.emacs' if you want to do so. It has been tested for Gnus-5.8.8 and VM-6.96; if you use RMAIL or MH-E, you have to try to find a solution yourself (please send it to me). Support for Gnus might become a standard part of X-Symbol.

(custom-set-variables
 '(x-symbol-auto-style-alist
   '(((mail-mode message-mode gnus-article-mode vm-presentation-mode)
      tex nil nil nil nil t nil))))

This is optional (you might want to use the Custom interface for the same effect) and tells Emacs/X-Symbol to use token language tex and to display super-/subscripts (if font-lock is enabled), X-Symbol is not automatically turned on. See section 3.3 Minor Mode.

(defun x-symbol-x-mail-send-hook ()
  (if x-symbol-mode (x-symbol-mode 0)))
(add-hook 'mail-send-hook 'x-symbol-x-mail-send-hook)
(add-hook 'message-send-hook 'x-symbol-x-mail-send-hook)
(add-hook 'vm-mail-send-hook 'x-symbol-x-mail-send-hook)

This tells tells Emacs to automatically turn off X-Symbol (which includes encoding characters to token) before actually sending the message.

(defun x-symbol-x-gnus-prepare ()
  (when x-symbol-mode
    (setq x-symbol-mode nil)
    (x-symbol-mode-internal nil)))
(add-hook 'gnus-article-prepare-hook 'x-symbol-x-gnus-prepare)

Since Gnus reuses the `*Article*' buffer, where X-Symbol could have been turned on previously, we must make sure that X-Symbol is turned off with the new article.

(defun x-symbol-x-vm-prepare ()
  (and (boundp 'vm-presentation-buffer)
       (buffer-live-p vm-presentation-buffer)
       (save-excursion
	 (set-buffer vm-presentation-buffer)
	 (when x-symbol-mode
	   (setq x-symbol-mode nil)
	   (x-symbol-mode-internal nil)))))
(add-hook 'vm-select-message-hook 'x-symbol-x-gnus-prepare)

The same thing for VM, although the hook is not as nice as Gnus' one; the function therefore might depend a bit too much on VM's interna.

(put 'vm-mode 'x-symbol-mode-disable
     "Use VM Presentation Mode to turn on X-Symbol")
(custom-set-variables '(vm-fill-paragraphs-containing-long-lines 80))

You cannot use X-Symbol in VM Mode, only in VM Presentation Mode (X-Symbol would change your `INBOX'). The first (optional) Emacs Lisp expression gives you a better error message when you try to turn on X-Symbol Mode in VM Mode. The second line makes sure that VM always uses VM Presentation Mode to display the articles.

8.5 How to Send a Bug/Problem Report

Bug fixes, bug/problem reports, improvements, and suggestions are strongly appreciated. So are corrections to this manual (better explanations, correcting my English, ...). Especially useful would be some feedback by people using default fonts with a charset registry-encoding other than iso8859-1 (Western encoding).

Please read this section carefully, even if you generally know how to send a bug report (see section `Bugs' in XEmacs User's Manual). This might look tedious to you, but it actually saves a lot of time (your time, too).

The general recommendation for bug/problem reports is: give the impression that your really have tried to find the necessary information yourself and make your report precise while including all information you have.

For each bug/problem report or question you want to send to the maintainer, please use the following sequence:

1. Make sure that you use the newest version of X-Symbol. You are reading Edition 4.5.2 (XEmacs) of the manual for X-Symbol 4.5.1.

2. Read the manual, especially 2.11 Checking the Correct Installation of Package X-Symbol, 8. Problems, Troubleshooting, and 8.4 Frequently Asked Questions. The four indexes (see section Indexes) might also lead you to an answer to your question.

3. Use M-x x-symbol-package-bug (also to be found in X-Symbol's Command submenu) to write your report describing one bug or problem, i.e., use different mails for 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' `*mail*' buffer to your mail tool.

   If 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 `x-symbol version; summary' as Subject header where version is the version of X-Symbol (it should be 4.5.1) and summary is a brief summary of your installation problem.

   (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.)

4. Start your report with:

   In the manual, I checked the sections section1, section2, ..., but didn't find anything which helped me with the following problem:

   The sections section1, section2, etc are names of the sections (not whole chapters) in the manual where you would expect an answer to your question/problem/bug.

   If you didn't know which sections to inspect, please check the indexes. If they are not helpful, send me words/terms which should be included in the indexes.

   (Rationale: This way, I get an idea where to improve the manual, especially by adding cross references.)

5. If buffer `*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 `X-Symbol' is not mentioned there. Otherwise, include the contents of buffer `*Warnings*' into your bug report.

   Temporary Emacs (< v21.4) note: the warnings might be somewhere hidden in buffer `*Messages*'; please check that buffer.

6. Put the parts of the code from `~/.emacs' and the system-wide files which causes the problem into a fresh file `my-problem.el'. The problem/error should be visible when invoking

   xemacs -no-site-file -q -l my-problem.el

   In the minimal case, `my-problem.el' just contains the following line (see section 2.4 Make XEmacs Initialize X-Symbol During Startup):

   (x-symbol-initialize)

   If the error has disappeared after you have included your complete `~/.xemacs/init.el' and `~/.emacs', the problem is likely caused by some code of your system-wide installation. Include the code, which can be found using command M-x find-library with files `site-start' and `default' (everything is fine if these files do not exist).

   If you use `x-symbol-site.el' (its use is deprecated), copy its contents into `my-problem.el' and delete the corresponding load command.

   Attach the file `my-problem.el' to your report. Please try to minimize the size of `my-problem.el'! A standard technique is recursive halving: Delete the second half of `my-problem.el'. If the problem disappears, delete the first half instead. Do the same with the smaller file again, ....

   (Rationale: Most problems are a consequence of some specific customizations, but I don't have time to debug each user's init file.)

7. If you have set variable custom-file in `my-problem.el', attach the corresponding file to your report.

8. If the error can only be reproduced in combination with another Emacs package, please send me:
   • 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 M-x find-library to check whether you really use the version from the Emacs/XEmacs distribution).

   • If it is a non-standard (and non-obscure) package: the URL of the distribution and/or the source.

   • Otherwise: include its code into `my-problem.el' and delete the corresponding load or require command. Then, reduce the size of `my-problem.el' as described above.

9. If the problem is not reproducible with an arbitrary (`.tex', `.html', ...) file, include the file with its full file name into your bug report. (If you like, you can try to minimize the file if the problem is still reproducible.)

   (Rationale: Most problems are only reproducible with specific files.)

10. 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 C-x C-f file 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 C-h l and include the contents of buffer `*Help*' in your bug report.

    (Rationale: Most problems are only reproducible with point being at a specific position in the file, with specific key sequences, etc.)

11. If you have problem with the display of images, please include the output of the shell commands `convert -h' and `convert -list Format' in your bug report. If the first command fails, you have a problem with the program convert, not X-Symbol.

12. If necessary, include a screen-shot in your bug report.

13. If you could not use M-x x-symbol-package-bug, include the contents of buffer `*Help*' after the following actions:
    • Type C-h v x-symbol-version RET.
    • Type C-h v emacs-version RET.
    • Type C-h v features RET.

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