# auctex / FAQ

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 Frequently Asked Questions about AUCTeX *************************************** 1. Something is not working correctly. What should I do? Well, you might have guessed it, the first place to look is in the available documentation packaged with AUCTeX. This could be the release notes (in the RELEASE' file) or the news section of the manual in case you are experiencing problems after an upgrade, the INSTALL' file in case you are having problems with the installation, the section about bugs in the manual in case you encountered a bug or the relevant sections in the manual for other related problems. If this did not help, you can send a bug report to the AUCTeX bug reporting list by using the command M-x TeX-submit-bug-report RET'. But before you do this, you can try to get more information about the problem at hand which might also help you locate the cause of the error yourself. First, you can try to generate a so-called backtrace which shows functions involved in a program error. In order to do this, start Emacs with the command line emacs --debug-init' and/or put the line (setq debug-on-error t) as the first line into your init file. XEmacs users might want to add (setq stack-trace-on-error t)' as well. After Emacs has started, you can load a file which triggers the error and a new window should pop up showing the backtrace. If you get such a backtrace, please include it in the bug report. Second, you can try to figure out if something in your personal or site configuration triggers the error by starting Emacs without such customizations. You can do this by invoking Emacs with the command line emacs -q -no-site-file'. Once Emacs is running, copy the line (load "auctex.el" nil t t) into the *scratch*' buffer and type M-x eval-buffer RET'. This makes sure that AUCTeX will be used for the file types it supports. After you have done so, you can load the file triggering the error. If everything is working now, you know that you have to search either in the site configuration file or your personal init file for statements related to the problem. 2. What versions of Emacs and XEmacs are supported? AUCTeX was tested with Emacs 21 and XEmacs 21.4.15. Older versions may work but are unsupported. Older versions of XEmacs might possibly made to work by updating the xemacs-base' package through the XEmacs package system. If you are looking for a recommendation, it would appear that the smoothest working platform on all operating systems at the current point of time would be Emacs 22.1. At the time of this writing, however, it has not been released and is still under development. The quality of the development version is quite solid, so we recommend giving it a try. With a developer version, of course, you have to be prepared to update in case you managed to get your snapshot at a bad time. The second best choice would be the latest released Emacs 21.4. However, Unicode support is less good, there is no version for the popular GTK toolkit, and the native versions for Windows and MacOS don't offer toolbar and preview-latex support. Our success with XEmacs has been less than convincing. Under the Windows operating system, nominally the only option for a released, stable Emacs variant supporting toolbars and preview-latex would be XEmacs 21.4. However, code for core functionality like formatting and syntax highlighting tends to be different and often older than even Emacs 21.4, and Unicode support as delivered is problematic at best, missing on Windows. Both AUCTeX and XEmacs developers don't hear much from active users of the combination. Partly for that reason, problems tend to go unnoticed for long amounts of time and are often found, if at all, after releases. No experiences or recommendations can be given for beta or developer versions of XEmacs. 3. Why doesn't the completion, style file, or multi-file stuff work? It must be enabled first, insert this in your init file: (setq-default TeX-master nil) (setq TeX-parse-self t) (setq TeX-auto-save t) Read also the chapters about parsing and multifile documents in the manual. 4. Why doesn't TeX-save-document' work? TeX-check-path' has to contain "./" somewhere. 5. Why is the information in foo.tex' forgotten when I save foo.bib'? For various reasons, AUCTeX ignores the extension when it stores information about a file, so you should use unique base names for your files. E.g. rename foo.bib' to foob.bib'. 6. Why doesn't AUCTeX signal when processing a document is done? If the message in the minibuffer stays "Type C-c C-l' to display results of compilation.", you probably have a misconfiguration in your init file (.emacs', init.el' or similar). To track this down either search in the *Messages*' buffer for an error message or put (setq debug-on-error t)' as the first line into your init file, restart Emacs and open a LaTeX file. Emacs will complain loudly by opening a debugging buffer as soon as an error occurs. The information in the debugging buffer can help you find the cause of the error in your init file. 7. What does AUC stand for? AUCTeX came into being at Aalborg University in Denmark. Back then the Danish name of the university was Aalborg Universitetscenter; AUC for short. Frequently Asked Questions about preview-latex ********************************************** 1 Introduction ************** 1.1 How can I contribute to the FAQ? ==================================== Send an email with the subject: Preview FAQ to . 2 Requirements ************** 2.1 Which version of (X)Emacs is needed? ======================================== See also the table at the end of the section. preview-latex nominally requires GNU Emacs with a version of at least 21.1. However, Emacs 22 (currently under development) offers superior performance and wider platform support, and is even now the recommended platform to use. While recent versions of XEmacs 21.4 are supported, doing this in a satisfactory manner has proven to be difficult due to technical shortcomings and differing API's which are hard to come by. If preview-latex is an important part of your editing workflow, you are likely to get better results and support by switching to Emacs. Of course, you can improve support for your favorite editor by giving feedback in case you encounter bugs. 2.2 Which versions of Ghostscript and AUCTeX are needed? ======================================================== We recommend to use GNU or AFPL Ghostscript with a version of at least 7.07. preview-latex has been distributed as part of AUCTeX since version 11.80. If your version of AUCTeX is older than that, or if it does not contain a working copy of preview-latex, complain to wherever you got it from. 2.3 I have trouble with the display format... ============================================= We recommend keeping the variable preview-image-type' set to dvipng' (if you have it installed) or png'. This is the default and can be set via the Preview/Customize menu. All other formats are known to have inconveniences, either in file size or quality. There are some Emacs versions around not supporting PNG; the proper way to deal with that is to complain to your Emacs provider. Short of that, checking out PNM or JPEG formats might be a good way to find out whether the lack of PNG format support might be the only problem with your Emacs. 2.4 For which OS does preview work? =================================== It is known to work under the X Window System for Linux and for several flavors of Unix: we have reports for HP and Solaris. There are several development versions of Emacs around for native MacOS Carbon, and preview-latex is working with them, too. With Windows, Cygwin and native ports of XEmacs should work. preview-latex will not work with any native version 21 of Emacs under Windows: you need to get a hold of Emacs 22 which is at the time of this writing not released but available as a developer snapshot. The entry "X11/Unix" currently means Linux, Solaris or HP/UX, as well as the X-specific version for Mac/OSX. OS Emacs version XEmacs version X11/Unix 21.1 21.4.9 Win9x cygwin 21.3.50? 21.4.8 Win9x native 22.1 21.4.8 MacOSX native 22.1 - 3 Installation Trouble ********************** 3.1 I just get LaTeX found no preview images'. =============================================== The reason for this is that LaTeX found no preview images in the document in question. One reason might be that there are no previews to be seen. If you have not used preview-latex before, you might not know its manner of operation. One sure-fire way to test if you just have a document where no previews are to be found is to use the provided example document circ.tex' (you will have to copy it to some directory where you have write permissions). If the symptom persists, you have a problem, and the problem is most likely a LaTeX problem. Here are possible reasons: Filename database not updated Various TeX distributions have their own ways of knowing where the files are without actually searching directories. The normal preview-latex installation should detect common tools for that purpose and use them. If this goes wrong, or if the files get installed into a place where they are not looked for, the LaTeX run will fail. An incomplete manual installation This should not happen if you followed installation instructions. Unfortunately, people know better all the time. If only preview.sty' gets installed without a set of supplementary files also in the latex' subdirectory, preview-latex runs will not generate any errors, but they will not produce any previews, either. An outdated preview' installation The preview.sty' package is useful for more than just preview-latex. For example, it is part of TeXlive. So you have to make sure that preview-latex does not get to work with outdated style and configuration files: some newer features will not work with older TeX style files, and really old files will make preview-latex fail completely. There usual is a local texmf' tree, or even a user-specific tree that are searched before the default tree. Make sure that the first version of those files that gets found is the correct one. 3.2 I have problems with the XEmacs installation ================================================ Please note that the XEmacs installation is different, since XEmacs has a package system that gets used here. Please make sure that you read and follow the installation instructions for XEmacs. 4 Customization *************** 4.1 Why don't I get balloon help like in the screen shots? ========================================================== Some users have reported problems with their XEmacs version, so balloon help is no longer switched on by default. Use the Preview/Customize menu or  customize-variable' in order to customize preview-use-balloon-help' to On'. This only concerns XEmacs: tooltips under GNU Emacs are enabled by default and unproblematic. 4.2 How to include additional environments like enumerate' =========================================================== By default, preview-latex is intended mainly for displaying mathematical formulas, so environments like enumerate' or tabular' (except where contained in a float) are not included. You can include them however manually by adding the lines: \usepackage[displaymath,textmath,sections,graphics,floats]{preview} \PreviewEnvironment{enumerate} in your document header, that is before \begin{document} In general, preview' should be loaded as the last thing before the start of document. Be aware that \PreviewEnvironment{...} does not accept a comma separated list! Also note that by putting more and more \PreviewEnvironment{...} in your document, it will look more and more like a DVI file preview when running preview-latex. Since each preview is treated as one large monolithic block by Emacs, one should really restrict previews to those elements where the improvement in visual representation more than makes up for the decreased editability. 4.3 What if I don't want to change the document? ================================================ The easiest way is to generate a configuration file in the current directory. You can basically either create prdefault.cfg' which is used for any use of the preview' package, or you can use prauctex.cfg' which only applies to the use from with Emacs. Let us assume you use the latter. In that case you should write something like \InputIfFileExists{preview/prauctex.cfg}{}{} \PreviewEnvironment{enumerate} in it. The first line inputs the system-wide default configuration (the file name should match that, but not your own prauctex.cfg'), then you add your own stuff. 4.4 Suddenly I get gazillions of ridiculous pages?!? ==================================================== When preview-latex works on extracting its stuff, it typesets each single preview on a page of its own. This only happens when actual previews get generated. Now if you want to configure preview-latex in your document, you need to add your own \usepackage' call to preview' so that it will be able to interpret its various definition commands. It is an error to add the active' option to this invocation: you don't want the package to be active unless preview-latex itself enables the previewing operation (which it will). 4.5 Does preview-latex work with presentation classes? ====================================================== preview-latex should work with most presentation classes. However, since those classes often have macros or pseudo environments encompassing a complete slide, you will need to use the customization facilities of preview.sty' to tell it how to resolve this, whether you want no previews, previews of whole slides or previews of inner material. 5 Troubleshooting ***************** 5.1 Preview causes all sort of strange error messages ===================================================== When running preview-latex and taking a look at either log file or terminal output, lots of messages like ! Preview: Snippet 3 started. <-><-> l.52 \item Sie lassen sich als Funktion $y = f(x)$ darstellen. ! Preview: Snippet 3 ended.(491520+163840x2494310). <-><-> l.52 \item Sie lassen sich als Funktion $y = f(x)$ darstellen. appear (previous versions generated messages looking even more like errors). Those are not real errors (as will be noted in the log file). Or rather, while they *are* really TeX error messages, they are intentional. This currently is the only reliable way to pass the information from the LaTeX run of preview-latex to its Emacs part about where the previews originated in the source text. Since they are actual errors, you will also get AUCTeX to state Preview-LaTeX exited as expected with code 1 at Wed Sep 4 17:03:30 after the LaTeX run in the run buffer. This merely indicates that errors were present, and errors will always be present when preview-latex is operating. There might be also real errors, so in case of doubt, look for them explicitly in either run buffer or the resulting .log' file. 6 preview-latex when not using LaTeX ************************************ 6.1 Does preview-latex work with PDFLaTeX? =========================================== Yes, as long as you use AUCTeX's own PDFLaTeX mode and have not messed with TeX-command-list'. 6.2 Does preview-latex work with elatex'? ========================================== No problem here. If you configure your AUCTeX to use elatex', or simply have latex' point to elatex', this will work fine. Modern TeX distributions use eTeX for LaTeX, anyway. 6.3 Does preview-latex work with ConTeXt? ========================================= In short, no. The preview' package is LaTeX-dependent. Adding support for other formats requires volunteers. 6.4 Does preview-latex work with plain TeX? =========================================== Again, no. Restructuring the preview' package for plain' operation would be required. Volunteers welcome. In some cases you might get around by making a wrapper pseudo-Master file looking like the following: \documentclass{article} \usepackage{plain} \begin{document} \begin{plain} \input myplainfile \end{plain} \end{document}