diff options
Diffstat (limited to 'elpa/auctex-13.1.3/preview-latex.info')
| -rw-r--r-- | elpa/auctex-13.1.3/preview-latex.info | 2582 |
1 files changed, 2582 insertions, 0 deletions
diff --git a/elpa/auctex-13.1.3/preview-latex.info b/elpa/auctex-13.1.3/preview-latex.info new file mode 100644 index 0000000..b6aae47 --- /dev/null +++ b/elpa/auctex-13.1.3/preview-latex.info @@ -0,0 +1,2582 @@ +This is preview-latex.info, produced by makeinfo version 6.8 from +preview-latex.texi. + +This manual is for preview-latex, a LaTeX preview mode for AUCTeX +(version 13.1.3 from 2022-04-16). + + Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2017-2019, 2021 +Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts and no + Back-Cover Texts. A copy of the license is included in the section + entitled "GNU Free Documentation License." +INFO-DIR-SECTION Emacs +START-INFO-DIR-ENTRY +* preview-latex: (preview-latex). Preview LaTeX fragments in Emacs +END-INFO-DIR-ENTRY + +INFO-DIR-SECTION TeX +START-INFO-DIR-ENTRY +* preview-latex: (preview-latex). Preview LaTeX fragments in Emacs +END-INFO-DIR-ENTRY + + +File: preview-latex.info, Node: Top, Prev: (dir), Up: (dir) + +preview-latex +************* + +This manual may be copied under the conditions spelled out in *note +Copying this Manual::. + + preview-latex is a package embedding preview fragments into Emacs +source buffers under the AUCTeX editing environment for LaTeX. It uses +'preview.sty' for the extraction of certain environments (most notably +displayed formulas). Other applications of this style file are possible +and exist. + + The name of the package is really 'preview-latex', all in lowercase +letters, with a hyphen. If you typeset it, you can use a sans-serif +font to visually offset it. + +* Menu: + +* Copying:: Copying +* Introduction:: Getting started. +* Installation:: Make Install. +* Keys and lisp:: Key bindings and user-level lisp functions. +* Simple customization:: To make it fit in. +* Known problems:: When things go wrong. +* For advanced users:: Internals and more customizations. +* ToDo:: Future development. +* Frequently Asked Questions:: All about preview-latex +* Copying this Manual:: GNU Free Documentation License +* Index:: A menu of many topics. + + +File: preview-latex.info, Node: Copying, Next: Introduction, Prev: Top, Up: Top + +Copying +******* + +For the conditions for copying parts of preview-latex, see the General +Public Licenses referred to in the copyright notices of the files, the +General Public Licenses accompanying them and the explanatory section in +*note (auctex)Copying::. + + This manual specifically is covered by the GNU Free Documentation +License (*note Copying this Manual::). + + +File: preview-latex.info, Node: Introduction, Next: Installation, Prev: Copying, Up: Top + +1 Introduction +************** + +Does your neck hurt from turning between previewer windows and the +source too often? This AUCTeX component will render your displayed +LaTeX equations right into the editing window where they belong. + + The purpose of preview-latex is to embed LaTeX environments such as +display math or figures into the source buffers and switch conveniently +between source and image representation. + +* Menu: + +* What use is it?:: +* Activating preview-latex:: +* Getting started:: +* Basic modes of operation:: +* More documentation:: +* Availability:: +* Contacts:: + + +File: preview-latex.info, Node: What use is it?, Next: Activating preview-latex, Prev: Introduction, Up: Introduction + +1.1 What use is it? +=================== + +WYSIWYG (what you see is what you get) sometimes is considered all the +rage, sometimes frowned upon. Do we really want it? Wrong question. +The right question is _what_ we want from it. Except when finetuning +the layout, we don't want to use printer fonts for on-screen text +editing. The low resolution and contrast of a computer screen render +all but the coarsest printer fonts (those for low-quality newsprint) +unappealing, and the margins and pagination of the print are not wanted +on the screen, either. On the other hand, more complex visual +compositions like math formulas and tables can't easily be taken in when +seen only in the source. preview-latex strikes a balance: it only uses +graphic renditions of the output for certain, configurable constructs, +does this only when told, and then right in the source code. Switching +back and forth between the source and preview is easy and natural and +can be done for each image independently. Behind the scenes of +preview-latex, a sophisticated framework of other programs like +'dvipng', Dvips and Ghostscript are employed together with a special +LaTeX style file for extracting the material of interest in the +background and providing fast interactive response. + + +File: preview-latex.info, Node: Activating preview-latex, Next: Getting started, Prev: What use is it?, Up: Introduction + +1.2 Activating preview-latex +============================ + +After installation, the package may need to be activated (and remember +to activate AUCTeX too). If preview-latex is installed via the Emacs +package manager (ELPA), activation should be automatic upon +installation. + + The usual activation (if it is not done automatically) would be + + (load "preview-latex.el" nil t t) + + If you still don't get a "Preview" menu in LaTeX mode in spite of +AUCTeX showing its "Command", your installation is broken. One possible +cause are duplicate Lisp files that might be detectable with 'M-x +list-load-path-shadows <RET>'. + + +File: preview-latex.info, Node: Getting started, Next: Basic modes of operation, Prev: Activating preview-latex, Up: Introduction + +1.3 Getting started +=================== + +Once activated, preview-latex and its documentation will be accessible +via its menus (note that preview-latex requires AUCTeX to be loaded). +When you have loaded a LaTeX document (a sample document 'circ.tex' is +included in the distribution, but most documents including math and/or +figures should do), you can use its menu or 'C-c C-p C-d' (for +'Preview/Document'). Previews will now be generated for various objects +in your document. You can use the time to take a short look at the +other menu entries and key bindings in the 'Preview' menu. You'll see +the previewed objects change into a roadworks sign when preview-latex +has determined just what it is going to preview. Note that you can +freely navigate the buffer while this is going on. When the process is +finished you will see the objects typeset in your buffer. + + It is a bad idea, however, to edit the buffer before the roadworks +signs appear, since that is the moment when the correlation between the +original text and the buffer locations gets established. If the buffer +changes before that point of time, the previews will not be placed where +they belong. If you do want to change some obvious error you just +spotted, we recommend you stop the background process by pressing 'C-c +C-k'. + + To see/edit the LaTeX code for a specific object, put the point (the +cursor) on it and press 'C-c C-p C-p' (for 'Preview/at point'). It will +also do to click with the middle mouse button on the preview. Now you +can edit the code, and generate a new preview by again pressing 'C-c C-p +C-p' (or by clicking with the middle mouse button on the icon before the +edited text). + + If you are using the 'desktop' package, previews will remain from one +session to the next as long as you don't kill your buffer. + + +File: preview-latex.info, Node: Basic modes of operation, Next: More documentation, Prev: Getting started, Up: Introduction + +1.4 Basic modes of operation +============================ + +preview-latex has a number of methods for generating its graphics. Its +default operation is equivalent to using the 'LaTeX' command from +AUCTeX. If this happens to be a call of PDFLaTeX generating PDF output +(you need at least AUCTeX 11.51 for this), then Ghostscript will be +called directly on the resulting PDF file. If a DVI file gets produced, +first Dvips and then Ghostscript get called by default. + + The image type to be generated by Ghostscript can be configured with + + M-x customize-option <RET> preview-image-type <RET> + +The default is 'png' (the most efficient image type). A special setting +is 'dvipng' in case you have the 'dvipng' program installed. In this +case, 'dvipng' will be used for converting DVI files and Ghostscript +(with a 'PNG' device) for converting PDF files. 'dvipng' is much faster +than the combination of Dvips and Ghostscript. You can get downloads, +access to its CVS archive and further information from its project site +(https://savannah.nongnu.org/projects/dvipng). + + +File: preview-latex.info, Node: More documentation, Next: Availability, Prev: Basic modes of operation, Up: Introduction + +1.5 More documentation +====================== + +After the installation, documentation in the form of this info manual +will be available. You can access it with the standalone info reader +with + + info preview-latex + +or by pressing 'C-h i d m preview-latex <RET>' in Emacs. Once +preview-latex is activated, you can instead use 'C-c C-p <TAB>' (or the +menu entry 'Preview/Read documentation'). + + Depending on your installation, a printable manual may also be +available in the form of 'preview-latex.pdf'. + + Detailed documentation for the LaTeX style used for extracting the +preview images is placed in 'preview.pdf' in a suitable directory during +installation; on typical TeX Live-based systems, + + texdoc preview + +will display it. + + +File: preview-latex.info, Node: Availability, Next: Contacts, Prev: More documentation, Up: Introduction + +1.6 Availability +================ + +The preview-latex project is now part of AUCTeX and accessible as part +of the AUCTeX project page (https://savannah.gnu.org/projects/auctex). +You can get its files from the AUCTeX download area +(https://ftp.gnu.org/pub/gnu/auctex/). As of AUCTeX 11.81, +preview-latex should already be integrated into AUCTeX, so no separate +download will be necessary. + + Anonymous Git is available at <git://git.savannah.gnu.org/auctex.git> +or <https://git.savannah.gnu.org/git/auctex.git>. You can also browse +the repository (https://git.savannah.gnu.org/cgit/auctex.git) via web +interface. + + +File: preview-latex.info, Node: Contacts, Prev: Availability, Up: Introduction + +1.7 Contacts +============ + +Bug reports should be sent by using 'M-x preview-report-bug <RET>', as +this will fill in a lot of information interesting to us. If the +installation fails (but this should be a rare event), report bugs to +<bug-auctex@gnu.org>. + + There is a general discussion list for AUCTeX which also covers +preview-latex, look at <https://lists.gnu.org/mailman/listinfo/auctex>. +For more information on the mailing list, send a message with just the +word "help" as subject or body to <auctex-request@gnu.org>. For the +developers, there is the <auctex-devel@gnu.org> list; it would probably +make sense to direct feature requests and questions about internal +details there. There is a low-volume read-only announcement list +available to which you can subscribe by sending a mail with "subscribe" +in the subject to <info-auctex-request@gnu.org>. + + Offers to support further development will be appreciated. If you +want to show your appreciation with a donation to the main developer, +you can do so via PayPal to <dak@gnu.org>, and of course you can arrange +for service contracts or for added functionality. Take a look at the +'TODO' list for suggestions in that area. + + +File: preview-latex.info, Node: Installation, Next: Keys and lisp, Prev: Introduction, Up: Top + +2 Installation +************** + +Installation is now being covered in *note (auctex)Installation::. + + +File: preview-latex.info, Node: Keys and lisp, Next: Simple customization, Prev: Installation, Up: Top + +3 Key bindings and user-level lisp functions +******************************************** + +preview-latex adds key bindings starting with 'C-c C-p' to the supported +modes of AUCTeX (*Note (auctex)Key Index::). It will also add its own +'Preview' menu in the menu bar, as well as an icon in the toolbar. + + The following only describes the interactive use: view the +documentation strings with 'C-h f' if you need the Lisp information. + +'C-c C-p C-p' +'preview-at-point' +Preview/Generate previews (or toggle) at point + If the cursor is positioned on or inside of a preview area, this + toggles its visibility, regenerating the preview if necessary. If + not, it will run the surroundings through preview. The + surroundings include all areas up to the next valid preview, unless + invalid previews occur before, in which case the area will include + the last such preview in either direction. And overriding any + other action, if a region is active ('transient-mark-mode'), it is + run through 'preview-region'. + +'<mouse-2>' + The middle mouse button has a similar action bound to it as + 'preview-at-point', only that it knows which preview to apply it to + according to the position of the click. You can click either + anywhere on a previewed image, or when the preview is opened and + showing the source text, you can click on the icon preceding the + source text. In other areas, the usual mouse key action + (typically: paste) is not affected. + +'<mouse-3>' + The right mouse key pops up a context menu with several options: + toggling the preview, regenerating it, removing it (leaving the + unpreviewed text), copying the text inside of the preview, and + copying it in a form suitable for copying as an image into a mail + or news article. This is a one-image variant of the following + command: + +'C-c C-p C-w' +'preview-copy-region-as-mml' +Copy a region as MML + This command is also available as a variant in the context menu on + the right mouse button (where the region is the preview that has + been clicked on). It copies the current region into the kill + buffer in a form suitable for copying as a text including images + into a mail or news article using mml-mode (*note Composing: + (emacs-mime)Composing.). + + If you regenerate or otherwise kill the preview in its source + buffer before the mail or news gets posted, this will fail. Also + you should generate images you want to send with + 'preview-transparent-border' set to 'nil', or the images will have + an ugly border. preview-latex detects this condition and asks + whether to regenerate the region with borders switched off. As + this is an asynchronous operation running in the background, you'll + need to call this command explicitly again to get the newly + generated images into the kill ring. + + Preview your articles with 'mml-preview' (on 'C-c C-m P') to make + sure they look fine. + +'C-c C-p C-e' +'preview-environment' +Preview/Generate previews for environment + Run preview on LaTeX environment. The environments in + 'preview-inner-environments' are treated as inner levels so that + for instance, the 'split' environment in + '\begin{equation}\begin{split}...\end{split}\end{equation}' is + properly displayed. If called with a numeric argument, the + corresponding number of outward nested environments is treated as + inner levels. + +'C-c C-p C-s' +'preview-section' +Preview/Generate previews for section + Run preview on this LaTeX section. + +'C-c C-p C-r' +'preview-region' +Preview/Generate previews for region + Run preview on current region. + +'C-c C-p C-b' +'preview-buffer' +Preview/Generate previews for buffer + Run preview on the current buffer. + +'C-c C-p C-d' +'preview-document' +Preview/Generate previews for document + Run preview on the current document. + +'C-c C-p C-c C-p' +'preview-clearout-at-point' +Preview/Remove previews at point + Clear out (remove) the previews that are immediately adjacent to + point. + +'C-c C-p C-c C-s' +'preview-clearout-section' +Preview/Remove previews from section + Clear out all previews in current section. + +'C-c C-p C-c C-r' +'preview-clearout' +Preview/Remove previews from region + Clear out all previews in the current region. + +'C-c C-p C-c C-b' +'preview-clearout-buffer' +Preview/Remove previews from buffer + Clear out all previews in current buffer. This makes the current + buffer lose all previews. + +'C-c C-p C-c C-d' +'preview-clearout-document' +Preview/Remove previews from document + Clear out all previews in current document. The document consists + of all buffers that have the same master file as the current + buffer. This makes the current document lose all previews. + +'C-c C-p C-f' +'preview-cache-preamble' +Preview/Turn preamble cache on + Dump a pregenerated format file. For the rest of the session, this + file is used when running on the same master file. Use this if you + know your LaTeX takes a long time to start up, the speedup will be + most noticeable when generating single or few previews. If you + change your preamble, do this again. preview-latex will try to + detect the necessity of that automatically when editing changes to + the preamble are done from within Emacs, but it will not notice if + the preamble effectively changes because some included file or + style file is tampered with. + + Note that support for preamble cache is limited for LaTeX variants. + c.f. <https://github.com/davidcarlisle/dpctex/issues/15> + * XeLaTeX cannot use preamble cache at all. The reason is + intrinsic in XeLaTeX, so preview-latex can't help. + * LuaLaTeX works with preamble cache only when the preamble is + simple enough, i.e., when it doesn't load opentype fonts and + it doesn't use lua codes in preamble. + +'C-c C-p C-c C-f' +'preview-cache-preamble-off' +Preview/Turn preamble cache off + Clear the pregenerated format file and stop using preambles for the + current document. If the caching gives you problems, use this. + +'C-c C-p C-i' +'preview-goto-info-page' +Preview/Read Documentation + Read this info manual. + +'M-x preview-report-bug <RET>' +'preview-report-bug' +Preview/Report Bug + This is the preferred way of reporting bugs as it will fill in what + version of preview-latex you are using as well as versions of + relevant other software, and also some of the more important + settings. Please use this method of reporting, if at all possible + and before reporting a bug, have a look at *note Known problems::. + +'C-c C-k' +LaTeX/TeX Output/Kill Job + Kills the preview-generating process. This is really an AUCTeX + keybinding, but it is included here as a hint. If you are + generating a preview and then make a change to the buffer, + preview-latex may be confused and place the previews wrong. + + +File: preview-latex.info, Node: Simple customization, Next: Known problems, Prev: Keys and lisp, Up: Top + +4 Simple customization +********************** + +Customization options can be found by typing 'M-x customize-group <RET> +preview <RET>'. Remember to set the option when you have changed it. +The list of suggestions can be made very long (and is covered in detail +in *note For advanced users::), but some are: + + * Change the color of the preview background + + If you use a non-white background in Emacs, you might have color + artifacts at the edges of your previews. Playing around with the + option 'preview-transparent-color' in the 'Preview Appearance' + group might improve things. With some settings, the cursor may + cover the whole background of a preview, however. + + This option is specific to the display engine in use. + + * Showing '\label's + + When using preview-latex, the '\label's are hidden by the previews. + It is possible to make them visible in the output by using the + LaTeX package 'showkeys' alternatively 'showlabels'. However, the + boxes of these labels will be outside the region preview-latex + considers as the preview image. To enable a similar mechanism + internal to preview-latex, enable the 'showlabels' option in the + variable 'preview-default-option-list' in the 'Preview Latex' + group. + + It must be noted, however, that a much better idea may be to use + the RefTeX package for managing references. *Note RefTeX in a + Nutshell: (reftex)RefTeX in a Nutshell. + + * Open previews automatically + + The current default is to open previews automatically when you + enter them with cursor left/right motions. Auto-opened previews + will close again once the cursor leaves them again (this is also + done when doing incremental search, or query-replace operations), + unless you changed anything in it. In that case, you will have to + regenerate the preview (via e.g., 'C-c C-p C-p'). Other options + for 'preview-auto-reveal' are available via 'customize'. + + * Automatically cache preambles + + Currently preview-latex asks you whether you want to cache the + document preamble (everything before '\begin{document}') before it + generates previews for a buffer the first time. Caching the + preamble will significantly speed up regeneration of previews. The + larger your preamble is, the more this will be apparent. Once a + preamble is cached, preview-latex will try to keep track of when it + is changed, and dump a fresh format in that case. If you + experience problems with this, or if you want it to happen without + asking you the first time, you can customize the variable + 'preview-auto-cache-preamble'. + + * Attempt to keep counters accurate when editing + + Since preview-latex frequently runs only small regions through + LaTeX, values like equation counters are not consistent from run to + run. If this bothers you, customize the variable + 'preview-preserve-counters' to 't' (this is consulted by + 'preview-required-option-list'). LaTeX will then output a load of + counter information during compilation, and this information will + be used on subsequent updates to keep counters set to useful + values. The additional information takes additional time to + analyze, but this is relevant mostly only when you are regenerating + all previews at once, and maybe you will be less tempted to do so + when counters appear more or less correct. + + * Preview your favourite LaTeX constructs + + If you have a certain macro or environment that you want to + preview, first check if it can be chosen by cutomizing + 'preview-default-option-list' in the 'Preview Latex' group. + + If it is not available there, you can add it to + 'preview-default-preamble' also in the 'Preview Latex' group, by + adding a '\PreviewMacro' or '\PreviewEnvironment' entry (*note + Provided commands::) _after_ the '\RequirePackage' line. For + example, if you want to preview the 'center' environment, press the + <Show> button and the last <INS> button, then add + + \PreviewEnvironment{center} + in the space that just opened. Note that since 'center' is a + generic formatting construct of LaTeX, a general configuration like + that is not quite prudent. You better to do this on a per-document + base so that it is easy to disable this behavior when you find this + particular entry gives you trouble. + + One possibility is to save such settings in the corresponding + file-local variable instead of your global configuration (*note + Local Variables in Files: (emacs)File Variables.). A perhaps more + convenient place for such options would be in a configuration file + in the same directory with your project (*note Package options::). + + The usual file for preview-latex preconfiguration is + 'prauctex.cfg'. If you also want to keep the systemwide defaults, + you should add a line + + \InputIfFileExists{preview/prauctex.cfg}{}{} + to your own version of 'prauctex.cfg' (this is assuming that global + files relating to the 'preview' package are installed in a + subdirectory 'preview', the default behavior). + + * Don't preview inline math + + If you have performance problems because your document is full of + inline math ('$...$'), or if your usage of '$' conflicts with + preview-latex's, you can turn off inline math previews. In the + 'Preview Latex' group, remove 'textmath' from + 'preview-default-option-list' by customizing this variable. + + +File: preview-latex.info, Node: Known problems, Next: For advanced users, Prev: Simple customization, Up: Top + +5 Known problems +**************** + +A number of issues are known concerning the interoperation with various +other software. Some of the known problems can be solved by moving to +newer versions of the problematic software or by simple patches. + +* Menu: + +* Font problems with Dvips:: +* Too small bounding boxes:: +* x-symbol interoperation:: +* Middle-clicks paste instead of toggling:: +* No images are displayed with gs 9.27 and earlier:: + + If you find something not mentioned here, please send a bug report +using 'M-x preview-report-bug <RET>', which will fill in a lot of +information interesting to us and send it to the <bug-auctex@gnu.org> +list. Please use the bug reporting commands if at all possible. + + +File: preview-latex.info, Node: Font problems with Dvips, Next: Too small bounding boxes, Up: Known problems + +5.1 Font problems with Dvips +============================ + +Some fonts have been reported to produce wrong characters with +preview-latex. preview-latex calls Dvips by default with the option +'-Pwww' in order to get scalable fonts for nice results. If you are +using antialiasing, however, the results might be sufficiently nice with +bitmapped fonts, anyway. You might try '-Ppdf' for another stab at +scalable fonts, or other printer definitions. Use + + 'M-x customize-option <RET> preview-fast-dvips-command <RET>' +and + 'M-x customize-option <RET> preview-dvips-command <RET>' +in order to customize this. + + One particular problem is that several printer setup files (typically +in a file called '/usr/share/texmf/dvips/config/config.pdf' if you are +using the '-Ppdf' switch) contain the 'G' option for 'character +shifting'. This option will result in 'fi' being rendered as '£' +(British Pounds sign) in several fonts, unless your version of Dvips has +a long-standing bug in its implementation fixed (only very recent +versions of Dvips have). + + +File: preview-latex.info, Node: Too small bounding boxes, Next: x-symbol interoperation, Prev: Font problems with Dvips, Up: Known problems + +5.2 Too small bounding boxes +============================ + +The bounding box of a preview is determined by the LaTeX package using +the pure TeX bounding boxes. If there is material extending outside of +the TeX box, that material will be missing from the preview image. This +happens for the label-showing boxes from the 'showkeys' package. This +particular problem can be circumvented by using the 'showlabels' option +of the preview package. + + In general, you should try to fix the problem in the TeX code, like +avoiding drawing outside of the picture with PSTricks. + + One possible remedy is to set 'preview-fast-conversion' to 'Off' +(*note The Emacs interface::). The conversion will take more time, but +will then use the bounding boxes from EPS files generated by Dvips. + + Dvips generally does not miss things, but it does not understand +PostScript constructs like '\resizebox' or '\rotate' commands, so will +generate rather wrong boxes for those. Dvips can be helped with the +'psfixbb' package option to preview (*note The LaTeX style file::), +which will tag the corners of the included TeX box. This will mostly be +convenient for _pure_ PostScript stuff like that created by PSTricks, +which Dvips would otherwise reserve no space for. + + +File: preview-latex.info, Node: x-symbol interoperation, Next: Middle-clicks paste instead of toggling, Prev: Too small bounding boxes, Up: Known problems + +5.3 x-symbol interoperation +=========================== + +Thanks to the work of Christoph Wedler, starting with version +'4.0h/beta' of x-symbol, the line parsing of AUCTeX and preview-latex is +fully supported. Earlier versions exhibit problems. However, versions +before '4.2.2' will cause a drastic slowdown of preview-latex's parsing +pass, so we don't recommend to use versions earlier than that. + + If you wonder what x-symbol is, it is a package that transforms +various tokens and subscripts to a more readable form while editing and +offers a few input methods handy especially for dealing with math. Take +a look at <http://x-symbol.sourceforge.net/>. + + x-symbol versions up to '4.5.1-beta' at least require an 8bit-clean +TeX implementation (meaning that its terminal output should not use +'^^'-started escape sequences) for cooperation with preview-latex. +Later versions may get along without it, like preview-latex does now. + + If you experience problems with 'circ.tex' in connection with both +x-symbol and Latin-1 characters, you may need to change your language +environment or, as a last resort, customize the variable +'LaTeX-command-style' by replacing the command 'latex' with 'latex +-translate-file=cp8bit'. + + +File: preview-latex.info, Node: Middle-clicks paste instead of toggling, Next: No images are displayed with gs 9.27 and earlier, Prev: x-symbol interoperation, Up: Known problems + +5.4 Middle-clicks paste instead of toggling +=========================================== + +This is probably the fault of your favorite package. 'isearch.el' is +known to be affected while searches are in progress, but the code is +such a complicated mess that no patch is in sight. Better just end the +search with '<RET>' before toggling and resume with 'C-s C-s' or similar +afterwards. Since previews over the current match will auto-open, +anyway, this should not be much of a problem in practice. + + +File: preview-latex.info, Node: No images are displayed with gs 9.27 and earlier, Prev: Middle-clicks paste instead of toggling, Up: Known problems + +5.5 No images are displayed with gs 9.27 and earlier +==================================================== + +preview-latex tries to adjust the foreground and background colors of +generated images to those of Emacs. Unfortunately, incompatible changes +introduced in Ghostscript 9.27 breaks the traditional method partially, +and preview-latex can display no images under certain circumstances. + + A new method implemented alternatively works only with Ghostscript > +9.27. If you are using Ghostscript 9.27 or earlier, customize the +option 'preview-pdf-adjust-color-method'. + + -- User Option: preview-pdf-adjust-color-method + Method to adjust colors of images generated from PDF. It is not + consulted when the LaTeX command produces DVI files. + + When the option is 't' (default), preview-latex adjusts the FG and + BG colors of the generated images by the new method. This method + requires that Ghostscript has working 'DELAYBIND' feature, thus is + invalid with gs 9.27 (and possibly < 9.27). + + When it is 'compatible', preview-latex uses traditional method. + This option is provided for backward compatibility with older gs. + See the below explanation for detail. + + When 'nil', no adjustment is done and "black on white" image is + generated regardless of Emacs color. This is provided for fallback + for gs 9.27 users with customized foreground color. See the below + explanation for detail. + + When the LaTeX command produces PDF rather than DVI and Emacs has + non-trivial foreground color, the traditional method ('compatible') + makes gs >= 9.27 to stop with error. Here, "non-trivial foreground + color" includes customized themes. + + If you use such non-trivial foreground color and the version of + Ghostscript equals to 9.27, you have two options: + 1. Choose the value 'compatible' and customize + 'preview-reference-face' to have default (black) foreground + color. This makes the generated image almost non-readable on + dark background, so the next option would be your only choice + in that case. + 2. Choose the value 'nil', which forces plain "black on white" + appearance for the generated image. You can at least read + what are written in the image although they may not match with + your Emacs color well. + + The default value used to be 'compatible' for short period before + Ghostscript 9.50 was released but now is 't'. + + +File: preview-latex.info, Node: For advanced users, Next: ToDo, Prev: Known problems, Up: Top + +6 For advanced users +******************** + +This package consists of two parts: a LaTeX style that splits the output +into appropriate parts with one preview object on each page, and an +Emacs-lisp part integrating the thing into Emacs (aided by AUCTeX). + +* Menu: + +* The LaTeX style file:: +* The Emacs interface:: +* The preview images:: +* Misplaced previews:: + + +File: preview-latex.info, Node: The LaTeX style file, Next: The Emacs interface, Prev: For advanced users, Up: For advanced users + +6.1 The LaTeX style file +======================== + +The main purpose of this package is the extraction of certain +environments (most notably displayed formulas) from LaTeX sources as +graphics. This works with DVI files postprocessed by either Dvips and +Ghostscript or dvipng, but it also works when you are using PDFTeX for +generating PDF files (usually also postprocessed by Ghostscript). + + Current uses of the package include the preview-latex package for +WYSIWYG functionality in the AUCTeX editing environment, generation of +previews in LyX, as part of the operation of the pst-pdf package, the +tbook XML system and some other tools. + + Producing EPS files with Dvips and its derivatives using the '-E' +option is not a good alternative: People make do by fiddling around with +'\thispagestyle{empty}' and hoping for the best (namely, that the +specified contents will indeed fit on single pages), and then trying to +guess the baseline of the resulting code and stuff, but this is at best +dissatisfactory. The preview package provides an easy way to ensure +that exactly one page per request gets shipped, with a well-defined +baseline and no page decorations. While you still can use the preview +package with the 'classic' + + dvips -E -i + +invocation, there are better ways available that don't rely on Dvips not +getting confused by PostScript specials. + + For most applications, you'll want to make use of the 'tightpage' +option. This will embed the page dimensions into the PostScript or PDF +code, obliterating the need to use the '-E -i' options to Dvips. You +can then produce all image files with a single run of Ghostscript from a +single PDF or PostScript (as opposed to EPS) file. + + Various options exist that will pass TeX dimensions and other +information about the respective shipped out material (including +descender size) into the log file, where external applications might +make use of it. + + The possibility for generating a whole set of graphics with a single +run of Ghostscript (whether from LaTeX or PDFLaTeX) increases both speed +and robustness of applications. It is also feasible to use dvipng on a +DVI file with the options + + -picky -noghostscript + +to omit generating any image file that requires Ghostscript, then let a +script generate all missing files using Dvips/Ghostscript. This will +usually speed up the process significantly. + +* Menu: + +* Package options:: +* Provided commands:: + + +File: preview-latex.info, Node: Package options, Next: Provided commands, Prev: The LaTeX style file, Up: The LaTeX style file + +6.1.1 Package options +--------------------- + +The package is included with the customary + + \usepackage[OPTIONS]{preview} + +You should usually load this package as the last one, since it redefines +several things that other packages may also provide. + + The following options are available: + +'active' + is the most essential option. If this option is not specified, the + 'preview' package will be inactive and the document will be typeset + as if the 'preview' package were not loaded, except that all + declarations and environments defined by the package are still + legal but have no effect. This allows defining previewing + characteristics in your document, and only activating them by + calling LaTeX as + + latex '\PassOptionsToPackage{active}{preview} \input{FILENAME}' + +'noconfig' + Usually the file 'prdefault.cfg' gets loaded whenever the 'preview' + package gets activated. 'prdefault.cfg' is supposed to contain + definitions that can cater for otherwise bad results, for example, + if a certain document class would otherwise lead to trouble. It + also can be used to override any settings made in this package, + since it is loaded at the very end of it. In addition, there may + be configuration files specific for certain 'preview' options like + 'auctex' which have more immediate needs. The 'noconfig' option + suppresses loading of those option files, too. +'psfixbb' + Dvips determines the bounding boxes from the material in the DVI + file it understands. Lots of PostScript specials are not part of + that. Since the TeX boxes do not make it into the DVI file, but + merely characters, rules and specials do, Dvips might include far + too small areas. The option 'psfixbb' will include '/dev/null' as + a graphic file in the ultimate upper left and lower right corner of + the previewed box. This will make Dvips generate an appropriate + bounding box. +'dvips' + If this option is specified as a class option or to other packages, + several packages pass things like page size information to Dvips, + or cause crop marks or draft messages written on pages. This + seriously hampers the usability of previews. If this option is + specified, the changes will be undone if possible. +'pdftex' + If this option is set, PDFTeX is assumed as the output driver. + This mainly affects the 'tightpage' option. +'xetex' + If this option is set, XeTeX is assumed as the output driver. This + mainly affects the 'tightpage' option. +'displaymath' + will make all displayed math environments subject to preview + processing. This will typically be the most desired option. +'floats' + will make all float objects subject to preview processing. If you + want to be more selective about what floats to pass through to a + preview, you should instead use the '\PreviewSnarfEnvironment' + command on the floats you want to have previewed. +'textmath' + will make all text math subject to previews. Since math mode is + used throughly inside of LaTeX even for other purposes, this works + by redefining '\(', '\)' and '$' and the 'math' environment + (apparently some people use that). Only occurences of these text + math delimiters in later loaded packages and in the main document + will thus be affected. +'graphics' + will subject all '\includegraphics' commands to a preview. +'sections' + will subject all section headers to a preview. +'delayed' + will delay all activations and redefinitions the 'preview' package + makes until '\''begin{document}'. The purpose of this is to cater + for documents which should be subjected to the 'preview' package + without having been prepared for it. You can process such + documents with + + latex '\RequirePackage[active,delayed,OPTIONS]{preview} + \input{FILENAME}' + + This relaxes the requirement to be loading the 'preview' package as + last package. +DRIVER + loads a special driver file 'prDRIVER.def'. The remaining options + are implemented through the use of driver files. +'auctex' + This driver will produce fake error messages at the start and end + of every preview environment that enable the Emacs package + preview-latex in connection with AUCTeX to pinpoint the exact + source location where the previews have originated. Unfortunately, + there is no other reliable means of passing the current TeX input + position _in_ a line to external programs. In order to make the + parsing more robust, this option also switches off quite a few + diagnostics that could be misinterpreted. + + You should not specify this option manually, since it will only be + needed by automated runs that want to parse the pseudo error + messages. Those runs will then use '\PassOptionsToPackage' in + order to effect the desired behaviour. In addition, 'prauctex.cfg' + will get loaded unless inhibited by the 'noconfig' option. This + caters for the most frequently encountered problematic commands. +'showlabels' + During the editing process, some people like to see the label names + in their equations, figures and the like. Now if you are using + Emacs for editing, and in particular preview-latex, I'd strongly + recommend that you check out the RefTeX package which pretty much + obliterates the need for this kind of functionality. If you still + want it, standard LaTeX provides it with the 'showkeys' package, + and there is also the less encompassing 'showlabels' package. + Unfortunately, since those go to some pain not to change the page + layout and spacing, they also don't change 'preview''s idea of the + TeX dimensions of the involved boxes. So if you are using + 'preview' for determing bounding boxes, those packages are mostly + useless. The option 'showlabels' offers a substitute for them. +'tightpage' + It is not uncommon to want to use the results of 'preview' as + graphic images for some other application. One possibility is to + generate a flurry of EPS files with + + dvips -E -i -Pwww -o OUTPUTFILE.000 INPUTFILE + + However, in case those are to be processed further into graphic + image files by Ghostscript, this process is inefficient since all + of those files need to be processed one by one. In addition, it is + necessary to extract the bounding box comments from the EPS files + and convert them into page dimension parameters for Ghostscript in + order to avoid full-page graphics. This is not even possible if + you wanted to use Ghostscript in a _single_ run for generating the + files from a single PostScript file, since Dvips will in that case + leave no bounding box information anywhere. + + The solution is to use the 'tightpage' option. That way a single + command line like + + gs -sDEVICE=png16m -dTextAlphaBits=4 -r300 + -dGraphicsAlphaBits=4 -dSAFER -q -dNOPAUSE + -sOutputFile=OUTPUTFILE%d.png INPUTFILE.ps + + will be able to produce tight graphics from a single PostScript + file generated with Dvips _without_ use of the options '-E -i', in + a single run. + + The 'tightpage' option actually also works when using the 'pdftex' + option and generating PDF files with PDFTeX. The resulting PDF + file has separate page dimensions for every page and can directly + be converted with one run of Ghostscript into image files. + + If neither 'dvips' or 'pdftex' have been specified, the + corresponding option will get autodetected and invoked. + + If you need this in a batch environment where you don't want to use + 'preview''s automatic extraction facilities, no problem: just don't + use any of the extraction options, and wrap everything to be + previewed into 'preview' environments. This is how LyX does its + math previews. + + If the pages under the 'tightpage' option are just too tight, you + can adjust by setting the length '\PreviewBorder' to a different + value by using '\setlength'. The default value is '0.50001bp', + which is half of a usual PostScript point, rounded up. If you go + below this value, the resulting page size may drop below '1bp', and + Ghostscript does not seem to like that. If you need finer control, + you can adjust the bounding box dimensions individually by changing + the macro '\PreviewBbAdjust' with the help of '\renewcommand'. Its + default value is + + \newcommand \PreviewBbAdjust + {-\PreviewBorder -\PreviewBorder + \PreviewBorder \PreviewBorder} + + This adjusts the left, lower, right and upper borders by the given + amount. The macro must contain 4 TeX dimensions after another, and + you may not omit the units if you specify them explicitly instead + of by register. PostScript points have the unit 'bp'. +'lyx' + This option is for the sake of LyX developers. It will output a + few diagnostics relevant for the sake of LyX' preview functionality + (at the time of writing, mostly implemented for math insets, in + versions of LyX starting with 1.3.0). +'counters' + This writes out diagnostics at the start and the end of previews. + Only the counters changed since the last output get written, and if + no counters changed, nothing gets written at all. The list + consists of counter name and value, both enclosed in '{}' braces, + followed by a space. The last such pair is followed by a colon + (':') if it is at the start of the preview snippet, and by a period + ('.') if it is at the end. The order of different diagnostics like + this being issued depends on the order of the specification of the + options when calling the package. + + Systems like preview-latex use this for keeping counters accurate + when single previews are regenerated. +'footnotes' + This makes footnotes render as previews, and only as their footnote + symbol. A convenient editing feature inside of Emacs. + + The following options are just for debugging purposes of the package +and similar to the corresponding TeX commands they allude to: + +'tracingall' + causes lots of diagnostic output to appear in the log file during + the preview collecting phases of TeX's operation. In contrast to + the similarly named TeX command, it will not switch to + '\errorstopmode', nor will it change the setting of + '\tracingonline'. +'showbox' + This option will show the contents of the boxes shipped out to the + DVI files. It also sets '\showboxbreadth' and '\showboxdepth' to + their maximum values at the end of loading this package, but you + may reset them if you don't like that. + + +File: preview-latex.info, Node: Provided commands, Prev: Package options, Up: The LaTeX style file + +6.1.2 Provided commands +----------------------- + +'\begin{preview}...\end{preview}' + The 'preview' environment causes its contents to be set as a single + preview image. Insertions like figures and footnotes (except those + included in minipages) will typically lead to error messages or be + lost. In case the 'preview' package has not been activated, the + contents of this environment will be typeset normally. + +'\begin{nopreview}...\end{nopreview}' + The 'nopreview' environment will cause its contents not to undergo + any special treatment by the 'preview' package. When 'preview' is + active, the contents will be discarded like all main text that does + not trigger the 'preview' hooks. When 'preview' is not active, the + contents will be typeset just like the main text. + + Note that both of these environments typeset things as usual when + preview is not active. If you need something typeset + conditionally, use the '\ifPreview' conditional for it. + +'\PreviewMacro' + If you want to make a macro like '\includegraphics' (actually, this + is what is done by the 'graphics' option to 'preview') produce a + preview image, you put a declaration like + + \PreviewMacro[*[[!]{\includegraphics} + + or, more readable, + + \PreviewMacro[{*[][]{}}]{\includegraphics} + + into your preamble. The optional argument to '\PreviewMacro' + specifies the arguments '\includegraphics' accepts, since this is + necessary information for properly ending the preview box. Note + that if you are using the more readable form, you have to enclose + the argument in a '[{' and '}]' pair. The inner braces are + necessary to stop any included '[]' pairs from prematurely ending + the optional argument, and to make a single '{}' denoting an + optional argument not get stripped away by TeX's argument parsing. + + The letters simply mean + + '*' + indicates an optional '*' modifier, as in '\includegraphics*'. + '[' + indicates an optional argument in brackets. This syntax is + somewhat baroque, but brief. + '[]' + also indicates an optional argument in brackets. Be sure to + have encluded the entire optional argument specification in an + additional pair of braces as described above. + '!' + indicates a mandatory argument. + '{}' + indicates the same. Again, be sure to have that additional + level of braces around the whole argument specification. + '?'DELIMITER{TRUE CASE}{FALSE CASE} + is a conditional. The next character is checked against being + equal to DELIMITER. If it is, the specification TRUE CASE is + used for the further parsing, otherwise FALSE CASE will be + employed. In neither case is something consumed from the + input, so {TRUE CASE} will still have to deal with the + upcoming delimiter. + '@'{LITERAL SEQUENCE} + will insert the given sequence literally into the executed + call of the command. + '-' + will just drop the next token. It will probably be most often + used in the true branch of a '?' specification. + '#'{ARGUMENT}{REPLACEMENT} + is a transformation rule that calls a macro with the given + argument and replacement text on the rest of the argument + list. The replacement is used in the executed call of the + command. This can be used for parsing arbitrary constructs. + For example, the '[]' option could manually be implemented + with the option string '?[{#{[#1]}{[{#1}]}}{}'. PStricks + users might enjoy this sort of flexibility. + ':'{ARGUMENT}{REPLACEMENT} + is again a transformation rule. As opposed to '#', however, + the result of the transformation is parsed again. You'll + rarely need this. + + There is a second optional argument in brackets that can be used to + declare any default action to be taken instead. This is mostly for + the sake of macros that influence numbering: you would want to keep + their effects in that respect. The default action should use '#1' + for referring to the original (not the patched) command with the + parsed options appended. Not specifying a second optional argument + here is equivalent to specifying '[#1]'. + +'\PreviewMacro*' + A similar invocation '\PreviewMacro*' simply throws the macro and + all of its arguments declared in the manner above away. This is + mostly useful for having things like '\footnote' not do their magic + on their arguments. More often than not, you don't want to declare + any arguments to scan to '\PreviewMacro*' since you would want the + remaining arguments to be treated as usual text and typeset in that + manner instead of being thrown away. An exception might be, say, + sort keys for '\cite'. + + A second optional argument in brackets can be used to declare any + default action to be taken instead. This is for the sake of macros + that influence numbering: you would want to keep their effects in + that respect. The default action might use '#1' for referring to + the original (not the patched) command with the parsed options + appended. Not specifying a second optional argument here is + equivalent to specifying '[]' since the command usually gets thrown + away. + + As an example for using this argument, you might want to specify + + \PreviewMacro*[{[]}][#1{}]{\footnote} + + This will replace a footnote by an empty footnote, but taking any + optional parameter into account, since an optional paramter changes + the numbering scheme. That way the real argument for the footnote + remains for processing by preview-latex. + +'\PreviewEnvironment' + The macro '\PreviewEnvironment' works just as '\PreviewMacro' does, + only for environments. +'\PreviewEnvironment*' + And the same goes for '\PreviewEnvironment*' as compared to + '\PreviewMacro*'. + +'\PreviewSnarfEnvironment' + This macro does not typeset the original environment inside of a + preview box, but instead typesets just the contents of the original + environment inside of the preview box, leaving nothing for the + original environment. This has to be used for figures, for + example, since they would + + 1. produce insertion material that cannot be extracted to the + preview properly, + 2. complain with an error message about not being in outer par + mode. + +'\PreviewOpen' +'\PreviewClose' + Those Macros form a matched preview pair. This is for macros that + behave similar as '\begin' and '\end' of an environment. It is + essential for the operation of '\PreviewOpen' that the macro + treated with it will open an additional group even when the preview + falls inside of another preview or inside of a 'nopreview' + environment. Similarly, the macro treated with '\PreviewClose' + will close an environment even when inactive. + +'\ifPreview' + In case you need to know whether 'preview' is active, you can use + the conditional '\ifPreview' together with '\else' and '\fi'. + + +File: preview-latex.info, Node: The Emacs interface, Next: The preview images, Prev: The LaTeX style file, Up: For advanced users + +6.2 The Emacs interface +======================= + +You can use 'M-x customize-group <RET> preview-latex <RET>' in order to +customize these variables, or use the menus for it. We explain the +various available options together with explaining how they work +together in making preview-latex work as intended. + +'preview-LaTeX-command' + When you generate previews on a buffer or a region, the command in + 'preview-LaTeX-command' gets run (that variable should only be + changed with Customize since its structure is somewhat peculiar, + though expressive). As usual with AUCTeX, you can continue working + while this is going on. It is not a good idea to change the file + until after preview-latex has established where to place the + previews which it can only do after the LaTeX run completes. This + run produces a host of pseudo-error messages that get parsed by + preview-latex at the end of the LaTeX run and give it the necessary + information about where in the source file the LaTeX code for the + various previews is located exactly. The parsing takes a moment + and will render Emacs busy. + +'preview-LaTeX-command-replacements' + This variable specifies transformations to be used before calling + the configured command. One possibility is to have '\pdfoutput=0 ' + appended to every command starting with 'pdf'. This particular + setting is available as the shortcut + 'preview-LaTeX-disable-pdfoutput'. Since preview-latex can work + with PDF files by now, there is little incentive for using this + option, anymore (for projects not requiring PDF output, the added + speed of 'dvipng' might make this somewhat attractive). + +'preview-required-option-list' + 'preview-LaTeX-command' uses 'preview-required-option-list' in + order to pass options such as 'auctex', 'active' and 'dvips' to the + 'preview' package. This means that the user need (and should) not + supply these in the document itself in case he wants to be able to + still compile his document without it turning into an incoherent + mass of little pictures. These options even get passed in when the + user loads 'preview' explicitly in his document. + + The default includes an option 'counters' that is controlled by the + boolean variable + +'preview-preserve-counters' + This option will cause the 'preview' package to emit information + that will assist in keeping things like equation counters and + section numbers reasonably correct even when you are regenerating + only single previews. + +'preview-default-option-list' +'preview-default-preamble' + If the document does not call in the package 'preview' itself (via + '\usepackage') in the preamble, the preview package is loaded using + default options from 'preview-default-option-list' and additional + commands specified in 'preview-default-preamble'. + +'preview-fast-conversion' + This is relevant only for DVI mode. It defaults to 'On' and + results in the whole document being processed as one large + PostScript file from which the single images are extracted with the + help of parsing the PostScript for use of so-called DSC comments. + The bounding boxes are extracted with the help of TeX instead of + getting them from Dvips. If you are experiencing bounding box + problems, try setting this option to 'Off'. + +'preview-prefer-TeX-bb' + If this option is 'On', it tells preview-latex never to try to + extract bounding boxes from the bounding box comments of EPS files, + but rather rely on the boxes it gets from TeX. If you activated + 'preview-fast-conversion', this is done, anyhow, since there are no + EPS files from which to read this information. The option defaults + to 'Off', simply because about the only conceivable reason to + switch off 'preview-fast-conversion' would be that you have some + bounding box problem and want to get Dvips' angle on that matter. + +'preview-scale-function' +'preview-reference-face' +'preview-document-pt-list' +'preview-default-document-pt' + 'preview-scale-function' determines by what factor images should be + scaled when appearing on the screen. If you specify a numerical + value here, the physical size on the screen will be that of the + original paper output scaled by the specified factor, at least if + Emacs' information about screen size and resolution are correct. + The default is to let 'preview-scale-from-face' determine the scale + function. This function determines the scale factor by making the + size of the default font in the document match that of the + on-screen fonts. + + The size of the screen fonts is deduced from the font + 'preview-reference-face' (usually the default face used for + display), the size of the default font for the document is + determined by calling 'preview-document-pt'. This function + consults the members of 'preview-document-pt-list' in turn until it + gets the desired information. The default consults first + 'preview-parsed-font-size', then calls 'preview-auctex-font-size' + which asks AUCTeX about any size specification like '12pt' to the + documentclass that it might have detected when parsing the + document, and finally reverts to just assuming + 'preview-default-document-pt' as the size used in the document + (defaulting to 10pt). + + If you find that the size of previews and the other Emacs display + clashes, something goes wrong. 'preview-parsed-font-size' is + determined at '\begin{document}' time; if the default font size + changes after that, it will not get reported. If you have an + outdated version of 'preview.sty' in your path, the size might not + be reported at all. If in this case AUCTeX is unable to find a + size specification, and if you are using a document class with a + different default value (like 'KomaScript'), the default fallback + assumption will probably be wrong and preview-latex will scale up + things too large. So better specify those size options even when + you know that LaTeX does not need them: preview-latex might benefit + from them. Another possibility for error is that you have not + enabled AUCTeX's document parsing options. The fallback method of + asking AUCTeX about the size might be disabled in future versions + of preview-latex since in general it is more reliable to get this + information from the LaTeX run itself. + +'preview-fast-dvips-command' +'preview-dvips-command' + The regular command for turning a DVI file into a single PostScript + file is 'preview-fast-dvips-command', while 'preview-dvips-command' + is used for cranking out a DVI file where every preview is in a + separate EPS file. Which of the two commands gets used depends on + the setting of 'preview-fast-conversion'. The printer specified + here is '-Pwww' by default, which will usually get you scalable + fonts where available. If you are experiencing problems, you might + want to try playing around with Dvips options (*Note + (dvips)Command-line options::). + + The conversion of the previews into PostScript or EPS files gets + started after the LaTeX run completes when Emacs recognizes the + first image while parsing the error messages. When Emacs has + finished parsing the error messages, it activates all detected + previews. This entails throwing away any previous previews + covering the same areas, and then replacing the text in its visual + appearance by a placeholder looking like a roadworks sign. + +'preview-nonready-icon-specs' + This is the roadworks sign displayed while previews are being + prepared. You may want to customize the font sizes at which + preview-latex switches over between different icon sizes, and the + ascent ratio which determines how high above the base line the icon + gets placed. + +'preview-error-icon-specs' +'preview-icon-specs' + Those are icons placed before the source code of an opened preview + and, respectively, the image specs to be used for PostScript + errors, and a normal open preview in text representation. + +'preview-inner-environments' + This is a list of environments that are regarded as inner levels of + an outer environment when doing 'preview-environment'. One example + when this is needed is in + '\begin{equation}\begin{split}...\end{split}\end{equation}', and + accordingly 'split' is one entry in 'preview-inner-environments'. + + +File: preview-latex.info, Node: The preview images, Next: Misplaced previews, Prev: The Emacs interface, Up: For advanced users + +6.3 The preview images +====================== + +'preview-image-type' +'preview-image-creators' +'preview-gs-image-type-alist' + What happens when LaTeX is finished depends on the configuration of + 'preview-image-type'. What to do for each of the various settings + is specified in the variable 'preview-image-creators'. The options + to pass into Ghostscript and what Emacs image type to use is + specified in 'preview-gs-image-type-alist'. + + 'preview-image-type' defaults to 'png'. For this to work, your + version of Ghostscript needs to support the 'png16m' device. If + you are experiencing problems here, you might want to reconfigure + 'preview-gs-image-type-alist' or 'preview-image-type'. + Reconfiguring 'preview-image-creators' is only necessary for adding + additional image types. + + Most devices make preview-latex start up a single Ghostscript + process for the entire preview run (as opposed to one per image) + and feed it either sections of a PDF file (if PDFLaTeX was used), + or (after running Dvips) sections of a single PostScript file or + separate EPS files in sequence for conversion into PNG format which + can be displayed much faster by Emacs. Actually, not in sequence + but backwards since you are most likely editing at the end of the + document. And as an added convenience, any preview that happens to + be on-screen is given higher priority so that preview-latex will + first cater for the images that are displayed. There are various + options customizable concerning aspects of that operation, see the + customization group 'Preview Gs' for this. + + Another noteworthy setting of 'preview-image-type' is 'dvipng': in + this case, the 'dvipng' program will get run on DVI output (see + below for PDF). This is in general much faster than Dvips and + Ghostscript. In that case, the option + +'preview-dvipng-command' + will get run for doing the conversion, and it is expected that + +'preview-dvipng-image-type' + images get produced ('dvipng' might be configured for other image + types as well). You will notice that 'preview-gs-image-type-alist' + contains an entry for 'dvipng': this actually has nothing to with + 'dvipng' itself but specifies the image type and Ghostscript device + option to use when 'dvipng' can't be used. This will obviously be + the case for PDF output by PDFLaTeX, but it will also happen if the + DVI file contains PostScript specials in which case the affected + images will get run through Dvips and Ghostscript once 'dvipng' + finishes. + + Note for pLaTeX and upLaTeX users: It is known that 'dvipng' is not + compatible with pLaTeX and upLaTeX. If 'preview-image-type' is set + to 'dvipng' and (u)pLaTeX is used, 'dvipng' just fails and + preview-latex falls back on Dvips and Ghostscript. + +'preview-gs-options' + Most interesting to the user perhaps is the setting of this + variable. It contains the default antialiasing settings + '-dTextAlphaBits=4' and '-dGraphicsAlphaBits=4'. Decreasing those + values to 2 or 1 might increase Ghostscript's performance if you + find it lacking. + + Running and feeding Ghostscript from preview-latex happens +asynchronously again: you can resume editing while the images arrive. +While those pretty pictures filling in the blanks on screen tend to make +one marvel instead of work, rendering the non-displayed images +afterwards will not take away your attention and will eventually +guarantee that jumping around in the document will encounter only +prerendered images. + + +File: preview-latex.info, Node: Misplaced previews, Prev: The preview images, Up: For advanced users + +6.4 Misplaced previews +====================== + +If you are reading this section, the first thing is to check that your +problem is not caused by x-symbol in connection with an installation not +supporting 8-bit characters (*note x-symbol interoperation::). If not, +here's the beef: + + As explained previously, Emacs uses pseudo-error messages generated +by the 'preview' package in order to pinpoint the exact source location +where a preview originated. This works in running text, but fails when +preview material happens to lie in macro arguments, like the contents of +'\emph'. Those macros first read in their entire argument, munge it +through, perhaps transform it somehow, process it and perhaps then +typeset something. When they finally typeset something, where is the +location where the stuff originated? TeX, having read in the entire +argument before, does not know and actually there would be no sane way +of defining it. + + For previews contained inside such a macro argument, the default +behaviour of preview-latex is to use a position immediately after the +closing brace of the argument. All the previews get placed there, all +at a zero-width position, which means that Emacs displays it in an order +that preview-latex cannot influence (currently in Emacs it is even +possible that the order changes between runs). And since the placement +of those previews is goofed up, you will not be able to regenerate them +by clicking on them. The default behaviour is thus somewhat +undesirable. + + The solution (like with other preview problems) is to tell the LaTeX +'preview' package how to tackle this problem (*note The LaTeX style +file::). Simply, you don't need '\emph' do anything at all during +previews! You only want the text math previewed, so the solution is to +use '\PreviewMacro*\emph' in the preamble of your document which will +make LaTeX ignore '\emph' completely as long as it is not part of a +larger preview (in which case it gets typeset as usual). Its argument +thus becomes ordinary text and gets treated like ordinary text. + + Note that it would be a bad idea to declare +'\PreviewMacro*[{{}}]\emph' since then both '\emph' as well as its +argument would be ignored instead of previewed. For user-level macros, +this is almost never wanted, but there may be internal macros where you +might want to ignore internal arguments. + + The same mechanism can be used for a number of other text-formatting +commands like '\textrm', '\textit' and the like. While they all use the +same internal macro '\text@command', it will not do to redefine just +that, since they call it only after having read their argument in, and +then it already is too late. So you need to disable every of those +commands by hand in your document preamble. + + Actually, we wrote all of the above just to scare you. At least all +of the above mentioned macros and a few more are already catered for by +a configuration file 'prauctex.cfg' that gets loaded by default unless +the 'preview' package gets loaded with the 'noconfig' option. You can +make your own copy of this file in a local directory and edit it in case +of need. You can also add loading of a file of your liking to +'preview-default-preamble', or alternatively do the manual disabling of +your favorite macro in 'preview-default-preamble', which is customizable +in the 'Preview Latex' group. + + +File: preview-latex.info, Node: ToDo, Next: Frequently Asked Questions, Prev: For advanced users, Up: Top + +Appendix A ToDo +*************** + + * Support other formats than just LaTeX + + plain TeX users and ConTeXt users should not have to feel left out. + While ConTeXt is not supported yet by released versions of AUCTeX, + at least supporting plain would help people, and be a start for + ConTeXt as well. There are plain-based formats like MusiXTeX that + could benefit a lot from preview-latex. The main part of the + difficulties here is to adapt 'preview.dtx' to produce stuff not + requiring LaTeX. + + * Support nested snippets + + Currently you can't have both a footnote (which gets displayed as + just its footnote number) and math inside of a footnote rendered as + an image: such nesting might be achieved by rerunning preview-latex + on the footnote contents when one opens the footnote for editing. + + * Support other text properties than just images + + Macros like '\textit' can be rendered as images, but the resulting + humungous blob is not suitable for editing, in particular since the + line filling from LaTeX does not coincide with that of Emacs. It + would be much more useful if text properties just switched the + relevant font to italics rather than replacing the whole text with + an image. It would also make editing quite easier. Then there are + things like footnotes that are currently just replaced by their + footnote number. While editing is not a concern here (the number + is not in the original text, anyway), it would save a lot of + conversion time if no images were generated, but Emacs just + displayed a properly fontified version of the footnote number. + Also, this might make preview-latex useful even on text terminals. + + * Find a way to facilitate Source Specials + + Probably in connection with adding appropriate support to 'dvipng', + it would be nice if clicking on an image from a larger piece of + source code would place the cursor at the respective source code + location. + + * Make 'preview.dtx' look reasonable in AUCTeX + + It is a bit embarrassing that 'preview.dtx' is written in a manner + that will not give either good syntax highlighting or good + indentation when employing AUCTeX. + + * Web page work + + Currently, preview-latex's web page is not structured at all. + Better navigation would be desirable, as well as separate News and + Errata eye catchers. + + * Manual improvements + + - Pepper the manual with screen shots and graphics + + This will be of interest for the HTML and TeX renditions of + the texinfo manual. Since Texinfo now supports images as + well, this could well be nice to have. + + - Fix duplicates + + Various stuff appears several times. + + * Implement rendering pipelines for Emacs + + The current preview-latex interface is fundamentally flawed, not + only because of a broken implementation. A general batchable and + daemonizable rendering infrastructure that can work on all kinds of + preview images for embedding into buffers is warranted. The + current implementation has a rather adhoc flavor and is not easily + extended. It will not work outside of AUCTeX, either. + + * Integrate into RefTeX + + When referencing to equations and the like, the preview-images of + the source rather than plain text should be displayed. If the + preview in question covers labels, those should appear in the + bubble help and/or a context menu. Apropos: + + * Implement LaTeX error indicators + + Previews on erroneous LaTeX passages might gain a red border or + similar. + + * Pop up relevant online documentation for frequent errors + + A lot of errors are of the "badly configured" variety. Perhaps the + relevant info pages should be delivered in addition to the error + message. + + * Implement a table editing mode where every table cell gets output + as a separate preview. Alternatively, output the complete table + metrics in a way that lets people click on individual cells for + editing purposes. + + * Benchmark and kill Emacs inefficiencies + + Both the LaTeX run under Emacs control as well as actual image + insertion in Emacs could be faster. CVS Emacs has improved in that + respect, but it still is slower than desirable. + + * Improve image support under Emacs + + The general image and color handling in Emacs is inefficient and + partly defective. This is still the case in CVS. One option would + be to replace the whole color and image handling with GDK routines + when this library is available, since it has been optimized for it. + + +File: preview-latex.info, Node: Frequently Asked Questions, Next: Copying this Manual, Prev: ToDo, Up: Top + +Appendix B Frequently Asked Questions +************************************* + +* Menu: + +* Introduction to FAQ:: +* Requirements:: +* Installation Trouble:: +* Customization:: +* Troubleshooting:: +* Other formats:: + + +File: preview-latex.info, Node: Introduction to FAQ, Next: Requirements, Prev: Frequently Asked Questions, Up: Frequently Asked Questions + +B.1 Introduction +================ + +B.1.1 How can I contribute to the FAQ? +-------------------------------------- + +Send an email with the subject: + Preview FAQ + to <auctex-devel@gnu.org>. + + +File: preview-latex.info, Node: Requirements, Next: Installation Trouble, Prev: Introduction to FAQ, Up: Frequently Asked Questions + +B.2 Requirements +================ + +B.2.1 Which version of Emacs is needed? +--------------------------------------- + +preview-latex nominally requires GNU Emacs with a version of at least +25.1. + +B.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. + +B.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. + +B.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, both native Emacs and Cygwin Emacs should work. +However, it is known that MiKTeX (https://miktex.org/) sometimes doesn't +work with preview-latex. In that case, use TeX Live +(https://tug.org/texlive/) instead. + + +File: preview-latex.info, Node: Installation Trouble, Next: Customization, Prev: Requirements, Up: Frequently Asked Questions + +B.3 Installation Trouble +======================== + +B.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 TeX Live. 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. + + +File: preview-latex.info, Node: Customization, Next: Troubleshooting, Prev: Installation Trouble, Up: Frequently Asked Questions + +B.4 Customization +================= + +B.4.1 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. + +B.4.2 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. + +B.4.3 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). + +B.4.4 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. + + +File: preview-latex.info, Node: Troubleshooting, Next: Other formats, Prev: Customization, Up: Frequently Asked Questions + +B.5 Troubleshooting +=================== + +B.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. + +B.5.2 Why do my DVI and PDF output files vanish? +------------------------------------------------ + +In order to produce the preview images preview-latex runs LaTeX on the +master or region file. The resulting DVI or PDF file can happen to have +the same name as the output file of a regular LaTeX run. So the regular +output file gets overwritten and is subsequently deleted by +preview-latex. + +B.5.3 My output file suddenly only contains preview images?! +------------------------------------------------------------ + +As mentioned in the previews FAQ entry, preview-latex might use the file +name of the original output file for the creation of preview images. If +the original output file is being displayed with a viewer when this +happens, you might see strange effects depending on the viewer, e.g. a +message about the file being corrupted or the display of all the preview +images instead of your typeset document. (Also *note Customization::.) + + +File: preview-latex.info, Node: Other formats, Prev: Troubleshooting, Up: Frequently Asked Questions + +B.6 preview-latex when not using LaTeX +====================================== + +B.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'. + +B.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. + +B.6.3 Does preview-latex work with ConTeXt? +------------------------------------------- + +In short, no. The 'preview' package is LaTeX-dependent. Adding support +for other formats requires volunteers. + +B.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} + + +File: preview-latex.info, Node: Copying this Manual, Next: Index, Prev: Frequently Asked Questions, Up: Top + +Appendix C Copying this Manual +****************************** + +The copyright notice for this manual is: + + This manual is for preview-latex, a LaTeX preview mode for AUCTeX +(version 13.1.3 from 2022-04-16). + + Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2017-2019, 2021 +Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts and no + Back-Cover Texts. A copy of the license is included in the section + entitled "GNU Free Documentation License." + + The full license text can be read here: + +* Menu: + +* GNU Free Documentation License:: License for copying this manual. + + +File: preview-latex.info, Node: GNU Free Documentation License, Up: Copying this Manual + +C.1 GNU Free Documentation License +================================== + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software + Foundation, Inc. <https://fsf.org/> + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + <https://www.gnu.org/licenses/>. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: preview-latex.info, Node: Index, Prev: Copying this Manual, Up: Top + +Index +***** + + +* Menu: + +* \PreviewEnvironment: Provided commands. (line 123) +* \PreviewMacro: Provided commands. (line 25) +* Activation: Activating preview-latex. + (line 6) +* C-c C-k: Keys and lisp. (line 168) +* C-c C-m P: Keys and lisp. (line 62) +* C-c C-p C-b: Keys and lisp. (line 89) +* C-c C-p C-c C-b: Keys and lisp. (line 115) +* C-c C-p C-c C-d: Keys and lisp. (line 121) +* C-c C-p C-c C-p: Keys and lisp. (line 99) +* C-c C-p C-c C-r: Keys and lisp. (line 110) +* C-c C-p C-c C-s: Keys and lisp. (line 105) +* C-c C-p C-d: Keys and lisp. (line 94) +* C-c C-p C-e: Keys and lisp. (line 74) +* C-c C-p C-f: Keys and lisp. (line 128) +* C-c C-p C-i: Keys and lisp. (line 155) +* C-c C-p C-p: Keys and lisp. (line 23) +* C-c C-p C-r: Keys and lisp. (line 84) +* C-c C-p C-s: Keys and lisp. (line 79) +* C-c C-p C-w: Keys and lisp. (line 45) +* C-u C-c C-p C-f: Keys and lisp. (line 149) +* Caching a preamble: Simple customization. + (line 57) +* Contacts: Contacts. (line 6) +* Copying: Copying. (line 6) +* Copyright: Copying. (line 6) +* Distribution: Copying. (line 6) +* Download: Availability. (line 6) +* FDL, GNU Free Documentation License: GNU Free Documentation License. + (line 6) +* Free: Copying. (line 6) +* Free software: Copying. (line 6) +* General Public License: Copying. (line 6) +* GIT access: Availability. (line 6) +* GPL: Copying. (line 6) +* Inline math: Simple customization. + (line 108) +* Kill preview-generating process: Keys and lisp. (line 168) +* License: Copying. (line 6) +* M-x preview-report-bug <RET>: Keys and lisp. (line 160) +* Mailing list: Contacts. (line 6) +* Menu entries: Keys and lisp. (line 6) +* Philosophy of preview-latex: What use is it?. (line 6) +* preview-at-point: Keys and lisp. (line 23) +* preview-auctex-font-size: The Emacs interface. (line 99) +* preview-auto-cache-preamble: Simple customization. + (line 57) +* preview-buffer: Keys and lisp. (line 89) +* preview-cache-preamble: Keys and lisp. (line 128) +* preview-cache-preamble-off: Keys and lisp. (line 149) +* preview-clearout: Keys and lisp. (line 110) +* preview-clearout-at-point: Keys and lisp. (line 99) +* preview-clearout-buffer: Keys and lisp. (line 115) +* preview-clearout-document: Keys and lisp. (line 105) +* preview-clearout-document <1>: Keys and lisp. (line 121) +* preview-copy-region-as-mml: Keys and lisp. (line 45) +* preview-default-document-pt: The Emacs interface. (line 82) +* preview-default-option-list: Simple customization. + (line 30) +* preview-default-option-list <1>: Simple customization. + (line 75) +* preview-default-option-list <2>: Simple customization. + (line 108) +* preview-default-option-list <3>: The Emacs interface. (line 53) +* preview-default-preamble: Simple customization. + (line 75) +* preview-default-preamble <1>: The Emacs interface. (line 54) +* preview-default-preamble <2>: Misplaced previews. (line 60) +* preview-default-preamble <3>: Misplaced previews. (line 61) +* preview-document: Keys and lisp. (line 94) +* preview-document-pt: The Emacs interface. (line 96) +* preview-document-pt-list: The Emacs interface. (line 81) +* preview-dvipng-command: The preview images. (line 40) +* preview-dvipng-image-type: The preview images. (line 43) +* preview-dvips-command: The Emacs interface. (line 124) +* preview-environment: Keys and lisp. (line 74) +* preview-error-icon-specs: The Emacs interface. (line 150) +* preview-fast-conversion: The Emacs interface. (line 60) +* preview-fast-dvips-command: The Emacs interface. (line 123) +* preview-goto-info-page: Keys and lisp. (line 155) +* preview-gs-image-type-alist: The preview images. (line 8) +* preview-gs-options: The preview images. (line 59) +* preview-icon-specs: The Emacs interface. (line 151) +* preview-image-creators: The preview images. (line 7) +* preview-image-type: Basic modes of operation. + (line 16) +* preview-image-type <1>: The preview images. (line 6) +* preview-inner-environments: The Emacs interface. (line 156) +* preview-LaTeX-command: The Emacs interface. (line 11) +* preview-LaTeX-command-replacements: The Emacs interface. (line 25) +* preview-nonready-icon-specs: The Emacs interface. (line 143) +* preview-parsed-font-size: The Emacs interface. (line 99) +* preview-pdf-adjust-color-method: No images are displayed with gs 9.27 and earlier. + (line 15) +* preview-prefer-TeX-bb: The Emacs interface. (line 69) +* preview-preserve-counters: Simple customization. + (line 61) +* preview-preserve-counters <1>: The Emacs interface. (line 47) +* preview-reference-face: The Emacs interface. (line 80) +* preview-region: Keys and lisp. (line 84) +* preview-report-bug: Keys and lisp. (line 160) +* preview-required-option-list: Simple customization. + (line 61) +* preview-required-option-list <1>: The Emacs interface. (line 35) +* preview-scale-function: The Emacs interface. (line 79) +* preview-section: Keys and lisp. (line 79) +* preview-transparent-border: Keys and lisp. (line 55) +* Readme: Introduction. (line 6) +* Report a bug: Keys and lisp. (line 160) +* Right: Copying. (line 6) +* Showing \labels: Simple customization. + (line 21) +* Using dvipng: Basic modes of operation. + (line 18) +* Warranty: Copying. (line 6) + + + +Tag Table: +Node: Top959 +Node: Copying2231 +Node: Introduction2685 +Node: What use is it?3359 +Node: Activating preview-latex4748 +Node: Getting started5499 +Node: Basic modes of operation7446 +Node: More documentation8651 +Node: Availability9520 +Node: Contacts10247 +Node: Installation11520 +Node: Keys and lisp11721 +Node: Simple customization18796 +Node: Known problems24458 +Node: Font problems with Dvips25284 +Node: Too small bounding boxes26454 +Node: x-symbol interoperation27850 +Node: Middle-clicks paste instead of toggling29238 +Node: No images are displayed with gs 9.27 and earlier29923 +Node: For advanced users32565 +Node: The LaTeX style file33024 +Node: Package options35586 +Node: Provided commands46490 +Node: The Emacs interface53835 +Node: The preview images62537 +Node: Misplaced previews66294 +Node: ToDo69750 +Node: Frequently Asked Questions74527 +Node: Introduction to FAQ74850 +Node: Requirements75189 +Node: Installation Trouble77157 +Node: Customization79421 +Node: Troubleshooting82497 +Node: Other formats85007 +Node: Copying this Manual86322 +Node: GNU Free Documentation License87268 +Node: Index112391 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: |