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

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  X-Symbol provides a poor man's Mule.
8.2 Spurious Encodings  Some commands turn off X-Symbol mode.
8.3 The Encoding Does Not Work  The encoding does not work in a rare case.
8.4 Frequently Asked Questions  Frequently asked questions.
8.5 How to Send a Bug/Problem Report  How to contact the maintainer of 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):


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.


8.3 The Encoding Does Not Work

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


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  XEmacs crashes when using input method Token
8.4.2 X-Symbol's Fontification does Not Work  X-Symbol's fontification does not work.
8.4.3 The Buffer Contains Strange Characters  The buffer contains strange characters
8.4.4 I Cannot See any/some Super- or Subscripts  I cannot see any/some super-/subscripts.
8.4.5 I See Super- and Subscripts where I Don't Want Them.  I see subscripts where I don't want them.
8.4.6 The Characters are Too Small or Too Big  The characters are too small or too big.
8.4.7 The Conversion Changes Some Tokens  The conversion changes some tokens.
8.4.8 A Space is Added During the Encoding  A space is added during the encoding.
8.4.9 I Don't Want 8bit Characters in the File  I do not want 8bit characters in the file.
8.4.10 I Cannot Distinguish Character hyphen from `-'  I cannot distinguish hyphen from `-'.
8.4.11 Problems with Spell-checking  I have problems with spell-checking.
8.4.12 How to Use X-Symbol with Gnus or VM  I want to use X-Symbol in Gnus or VM.


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:


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:

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:


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.


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.


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.


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

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:

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.



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