11.6 Troubleshooting

Gnus works so well straight out of the box—I can’t imagine any problems, really.

Ahem.

1. Make sure your computer is switched on.
2. Make sure that you really load the current Gnus version. If you have been running GNUS, you need to exit Emacs and start it up again before Gnus will work.
3. Try doing an M-x gnus-version. If you get something that looks like ‘Ma Gnus v0.12’ you have the right files loaded. Otherwise you have some old ‘.el’ files lying around. Delete these.
4. Read the help group (G h in the group buffer) for a FAQ and a how-to.
5. Gnus works on many recursive structures, and in some extreme (and very rare) cases Gnus may recurse down “too deeply” and Emacs will beep at you. If this happens to you, set max-lisp-eval-depth to 500 or something like that.

If all else fails, report the problem as a bug.

If you find a bug in Gnus, you can report it with the M-x gnus-bug command. M-x set-variable RET debug-on-error RET t RET, and send me the backtrace. I will fix bugs, but I can only fix them if you send me a precise description as to how to reproduce the bug.

You really can never be too detailed in a bug report. Always use the M-x gnus-bug command when you make bug reports, even if it creates a 10Kb mail each time you use it, and even if you have sent me your environment 500 times before. I don’t care. I want the full info each time.

It is also important to remember that I have no memory whatsoever. If you send a bug report, and I send you a reply, and then you just send back “No, it’s not! Moron!”, I will have no idea what you are insulting me about. Always over-explain everything. It’s much easier for all of us—if I don’t have all the information I need, I will just mail you and ask for more info, and everything takes more time.

If the problem you’re seeing is very visual, and you can’t quite explain it, copy the Emacs window to a file (with xwd, for instance), put it somewhere it can be reached, and include the URL of the picture in the bug report.

If you would like to contribute a patch to fix bugs or make improvements, please produce the patch using ‘diff -u’.

If you want to debug your problem further before reporting, possibly in order to solve the problem yourself and send a patch, you can use edebug. Debugging Lisp code is documented in the Elisp manual (see (elisp)Debugging section ‘Debugging Lisp Programs’ in The GNU Emacs Lisp Reference Manual). To get you started with edebug, consider if you discover some weird behavior when pressing c, the first step is to do C-h k c and click on the hyperlink (Emacs only) in the documentation buffer that leads you to the function definition, then press M-x edebug-defun RET with point inside that function, return to Gnus and press c to invoke the code. You will be placed in the lisp buffer and can single step using SPC and evaluate expressions using M-: or inspect variables using C-h v, abort execution with q, and resume execution with c or g.

Sometimes, a problem do not directly generate an elisp error but manifests itself by causing Gnus to be very slow. In these cases, you can use M-x toggle-debug-on-quit and press C-g when things are slow, and then try to analyze the backtrace (repeating the procedure helps isolating the real problem areas).

A fancier approach is to use the elisp profiler, ELP. The profiler is (or should be) fully documented elsewhere, but to get you started there are a few steps that need to be followed. First, instrument the part of Gnus you are interested in for profiling, e.g., M-x elp-instrument-package RET gnus or M-x elp-instrument-package RET message. Then perform the operation that is slow and press M-x elp-results. You will then see which operations that takes time, and can debug them further. If the entire operation takes much longer than the time spent in the slowest function in the profiler output, you probably profiled the wrong part of Gnus. To reset profiling statistics, use M-x elp-reset-all. M-x elp-restore-all is supposed to remove profiling, but given the complexities and dynamic code generation in Gnus, it might not always work perfectly.

If you just need help, you are better off asking on ‘gnu.emacs.gnus’. I’m not very helpful. You can also ask on the ding mailing list. Write to ding-request@gnus.org to subscribe.

This document was generated on January 25, 2015 using texi2html 1.82.