| commit | author | age | ||
| 5cb5f7 | 1 | This is the README file for the AUCTeX distribution. |
| C | 2 | |
| 3 | Copyright (C) 2008, 2017 Free Software Foundation, Inc. | |
| 4 | ||
| 5 | Copying and distribution of this file, with or without | |
| 6 | modification, are permitted in any medium without royalty provided | |
| 7 | the copyright notice and this notice are preserved. | |
| 8 | ||
| 9 | Introduction to AUCTeX | |
| 10 | ********************** | |
| 11 | ||
| 12 | This file gives a brief overview of what AUCTeX is. It is *not* an | |
| 13 | attempt to document AUCTeX. Real documentation for AUCTeX is available | |
| 14 | in the manual, which should be available as an info file after | |
| 15 | installation. | |
| 16 | ||
| 17 | AUCTeX is a comprehensive customizable integrated environment for | |
| 18 | writing input files for TeX, LaTeX, ConTeXt, Texinfo, and docTeX using | |
| 19 | Emacs. | |
| 20 | ||
| 21 | It supports you in the insertion of macros, environments, and sectioning | |
| 22 | commands by providing completion alternatives and prompting for | |
| 23 | parameters. It automatically indents your text as you type it and lets | |
| 24 | you format a whole file at once. The outlining and folding facilities | |
| 25 | provide you with a focused and clean view of your text. | |
| 26 | ||
| 27 | AUCTeX lets you process your source files by running TeX and related | |
| 28 | tools (such as output filters, post processors for generating indices | |
| 29 | and bibliographies, and viewers) from inside Emacs. AUCTeX lets you | |
| 30 | browse through the errors TeX reported, while it moves the cursor | |
| 31 | directly to the reported error, and displays some documentation for that | |
| 32 | particular error. This will even work when the document is spread over | |
| 33 | several files. | |
| 34 | ||
| 35 | One component of AUCTeX that LaTeX users will find attractive is | |
| 36 | preview-latex, a combination of folding and in-source previewing that | |
| 37 | provides true "What You See Is What You Get" experience in your | |
| 38 | sourcebuffer, while letting you retain full control. For more | |
| 39 | information, see further below. | |
| 40 | ||
| 41 | More detailed information about the features and usage of AUCTeX can be | |
| 42 | found in the AUCTeX manual. You can access it from within Emacs by | |
| 43 | typing 'C-h i d m auctex <RET>'. If you prefer the standalone info | |
| 44 | reader, issue the command 'info auctex' in a terminal. | |
| 45 | ||
| 46 | AUCTeX is written entirely in Emacs Lisp, and hence you can easily add | |
| 47 | new features for your own needs. It is a GNU project and distributed | |
| 48 | under the 'GNU General Public License Version 3'. | |
| 49 | ||
| 50 | The most recent version is always available at | |
| 51 | <http://ftp.gnu.org/pub/gnu/auctex/>. | |
| 52 | ||
| 53 | WWW users may want to check out the AUCTeX page at | |
| 54 | <http://www.gnu.org/software/auctex/>. | |
| 55 | ||
| 56 | For comprehensive information about how to install AUCTeX read the file | |
| 57 | 'INSTALL' or 'INSTALL.windows', respectively. | |
| 58 | ||
| 59 | If you are considering upgrading AUCTeX, the recent changes are | |
| 60 | described in the 'CHANGES' file. | |
| 61 | ||
| 62 | If you want to discuss AUCTeX with other users or its developers, there | |
| 63 | are several mailing lists you can use. | |
| 64 | ||
| 65 | Send a mail with the subject "subscribe" to <auctex-request@gnu.org> in | |
| 66 | order to join the general discussion list for AUCTeX. Articles should | |
| 67 | be sent to <auctex@gnu.org>. In a similar way, you can subscribe to the | |
| 68 | <info-auctex@gnu.org> list for just getting important announcements | |
| 69 | about AUCTeX. The list <bug-auctex@gnu.org> is for bug reports which | |
| 70 | you should usually file with the 'M-x TeX-submit-bug-report <RET>' | |
| 71 | command. If you want to address the developers of AUCTeX themselves | |
| 72 | with technical issues, they can be found on the discussion list | |
| 73 | <auctex-devel@gnu.org>. | |
| 74 | preview-latex in a nutshell | |
| 75 | *************************** | |
| 76 | ||
| 77 | Does your neck hurt from turning between previewer windows and the | |
| 78 | source too often? This AUCTeX component will render your displayed | |
| 79 | LaTeX equations right into the editing window where they belong. | |
| 80 | ||
| 81 | The purpose of preview-latex is to embed LaTeX environments such as | |
| 82 | display math or figures into the source buffers and switch conveniently | |
| 83 | between source and image representation. | |
| 84 | ||
| 85 | 1 What use is it? | |
| 86 | ***************** | |
| 87 | ||
| 88 | WYSIWYG (what you see is what you get) sometimes is considered all the | |
| 89 | rage, sometimes frowned upon. Do we really want it? Wrong question. | |
| 90 | The right question is _what_ we want from it. Except when finetuning | |
| 91 | the layout, we don't want to use printer fonts for on-screen text | |
| 92 | editing. The low resolution and contrast of a computer screen render | |
| 93 | all but the coarsest printer fonts (those for low-quality newsprint) | |
| 94 | unappealing, and the margins and pagination of the print are not wanted | |
| 95 | on the screen, either. On the other hand, more complex visual | |
| 96 | compositions like math formulas and tables can't easily be taken in when | |
| 97 | seen only in the source. preview-latex strikes a balance: it only uses | |
| 98 | graphic renditions of the output for certain, configurable constructs, | |
| 99 | does this only when told, and then right in the source code. Switching | |
| 100 | back and forth between the source and preview is easy and natural and | |
| 101 | can be done for each image independently. Behind the scenes of | |
| 102 | preview-latex, a sophisticated framework of other programs like | |
| 103 | 'dvipng', Dvips and Ghostscript are employed together with a special | |
| 104 | LaTeX style file for extracting the material of interest in the | |
| 105 | background and providing fast interactive response. | |
| 106 | ||
| 107 | 2 Activating preview-latex | |
| 108 | ************************** | |
| 109 | ||
| 110 | After installation, the package may need to be activated (and remember | |
| 111 | to activate AUCTeX too). If preview-latex is installed via the Emacs | |
| 112 | package manager (ELPA), activation should be automatic upon | |
| 113 | installation. | |
| 114 | ||
| 115 | The usual activation (if it is not done automatically) would be | |
| 116 | ||
| 117 | (load "preview-latex.el" nil t t) | |
| 118 | ||
| 119 | If you still don't get a "Preview" menu in LaTeX mode in spite of AUCTeX | |
| 120 | showing its "Command", your installation is broken. One possible cause | |
| 121 | are duplicate Lisp files that might be detectable with '<M-x> | |
| 122 | list-load-path-shadows <RET>'. | |
| 123 | ||
| 124 | 3 Getting started | |
| 125 | ***************** | |
| 126 | ||
| 127 | Once activated, preview-latex and its documentation will be accessible | |
| 128 | via its menus (note that preview-latex requires AUCTeX to be loaded). | |
| 129 | When you have loaded a LaTeX document (a sample document 'circ.tex' is | |
| 130 | included in the distribution, but most documents including math and/or | |
| 131 | figures should do), you can use its menu or 'C-c C-p C-d' (for | |
| 132 | 'Preview/Document'). Previews will now be generated for various objects | |
| 133 | in your document. You can use the time to take a short look at the | |
| 134 | other menu entries and key bindings in the 'Preview' menu. You'll see | |
| 135 | the previewed objects change into a roadworks sign when preview-latex | |
| 136 | has determined just what it is going to preview. Note that you can | |
| 137 | freely navigate the buffer while this is going on. When the process is | |
| 138 | finished you will see the objects typeset in your buffer. | |
| 139 | ||
| 140 | It is a bad idea, however, to edit the buffer before the roadworks signs | |
| 141 | appear, since that is the moment when the correlation between the | |
| 142 | original text and the buffer locations gets established. If the buffer | |
| 143 | changes before that point of time, the previews will not be placed where | |
| 144 | they belong. If you do want to change some obvious error you just | |
| 145 | spotted, we recommend you stop the background process by pressing 'C-c | |
| 146 | C-k'. | |
| 147 | ||
| 148 | To see/edit the LaTeX code for a specific object, put the point (the | |
| 149 | cursor) on it and press 'C-c C-p C-p' (for 'Preview/at point'). It will | |
| 150 | also do to click with the middle mouse button on the preview. Now you | |
| 151 | can edit the code, and generate a new preview by again pressing 'C-c C-p | |
| 152 | C-p' (or by clicking with the middle mouse button on the icon before the | |
| 153 | edited text). | |
| 154 | ||
| 155 | If you are using the 'desktop' package, previews will remain from one | |
| 156 | session to the next as long as you don't kill your buffer. | |
| 157 | ||
| 158 | 4 Basic modes of operation | |
| 159 | ************************** | |
| 160 | ||
| 161 | preview-latex has a number of methods for generating its graphics. Its | |
| 162 | default operation is equivalent to using the 'LaTeX' command from | |
| 163 | AUCTeX. If this happens to be a call of PDFLaTeX generating PDF output | |
| 164 | (you need at least AUCTeX 11.51 for this), then Ghostscript will be | |
| 165 | called directly on the resulting PDF file. If a DVI file gets produced, | |
| 166 | first Dvips and then Ghostscript get called by default. | |
| 167 | ||
| 168 | The image type to be generated by Ghostscript can be configured with | |
| 169 | ||
| 170 | M-x customize-variable RET preview-image-type RET | |
| 171 | ||
| 172 | The default is 'png' (the most efficient image type). A special setting | |
| 173 | is 'dvipng' in case you have the 'dvipng' program installed. In this | |
| 174 | case, 'dvipng' will be used for converting DVI files and Ghostscript | |
| 175 | (with a 'PNG' device) for converting PDF files. 'dvipng' is much faster | |
| 176 | than the combination of Dvips and Ghostscript. You can get downloads, | |
| 177 | access to its CVS archive and further information from its project site | |
| 178 | (http://savannah.nongnu.org/projects/dvipng). | |
| 179 | ||
| 180 | 5 More documentation | |
| 181 | ******************** | |
| 182 | ||
| 183 | After the installation, documentation in the form of an info manual will | |
| 184 | be available. You can access it with the standalone info reader with | |
| 185 | ||
| 186 | info preview-latex | |
| 187 | ||
| 188 | or by pressing 'C-h i d m preview-latex <RET>' in Emacs. Once | |
| 189 | preview-latex is activated, you can instead use 'C-c C-p <TAB>' (or the | |
| 190 | menu entry 'Preview/Read documentation'). | |
| 191 | ||
| 192 | Depending on your installation, a printable manual may also be available | |
| 193 | in the form of 'preview-latex.dvi' or 'preview-latex.ps'. | |
| 194 | ||
| 195 | Detailed documentation for the LaTeX style used for extracting the | |
| 196 | preview images is placed in 'preview.dvi' in a suitable directory during | |
| 197 | installation; on typical teTeX-based systems, | |
| 198 | ||
| 199 | texdoc preview | |
| 200 | ||
| 201 | will display it. | |
| 202 | ||
| 203 | 6 Availability | |
| 204 | ************** | |
| 205 | ||
| 206 | The preview-latex project is now part of AUCTeX and accessible as part | |
| 207 | of the AUCTeX project page (http://savannah.gnu.org/projects/auctex). | |
| 208 | You can get its files from the AUCTeX download area | |
| 209 | (ftp://ftp.gnu.org/pub/gnu/auctex). As of AUCTeX 11.81, preview-latex | |
| 210 | should already be integrated into AUCTeX, so no separate download will | |
| 211 | be necessary. | |
| 212 | ||
| 213 | You will also find '.rpm' files there for Fedora and possibly SuSE. | |
| 214 | Anonymous Git is available as well. | |
| 215 | ||
| 216 | 7 Contacts | |
| 217 | ********** | |
| 218 | ||
| 219 | Bug reports should be sent by using 'M-x preview-report-bug <RET>', as | |
| 220 | this will fill in a lot of information interesting to us. If the | |
| 221 | installation fails (but this should be a rare event), report bugs to | |
| 222 | <bug-auctex@gnu.org>. | |
| 223 | ||
| 224 | There is a general discussion list for AUCTeX which also covers | |
| 225 | preview-latex, look at <http://lists.gnu.org/mailman/listinfo/auctex>. | |
| 226 | For more information on the mailing list, send a message with just the | |
| 227 | word "help" as subject or body to <auctex-request@gnu.org>. For the | |
| 228 | developers, there is the <auctex-devel@gnu.org> list; it would probably | |
| 229 | make sense to direct feature requests and questions about internal | |
| 230 | details there. There is a low-volume read-only announcement list | |
| 231 | available to which you can subscribe by sending a mail with "subscribe" | |
| 232 | in the subject to <info-auctex-request@gnu.org>. | |
| 233 | ||
| 234 | Offers to support further development will be appreciated. If you want | |
| 235 | to show your appreciation with a donation to the main developer, you can | |
| 236 | do so via PayPal to <dak@gnu.org>, and of course you can arrange for | |
| 237 | service contracts or for added functionality. Take a look at the 'TODO' | |
| 238 | list for suggestions in that area. | |
