Info file: latex-mode.info, -*-Text-*- produced by latexinfo-format-buffer from file: ltxinfo.ltx  File: latex-mode.info Node: Top, Prev: Variable Index, Up: (dir), Next: Licensing Information This file documents version 1.0 of the LaTeX editing support package for GNU Emacs, version 18 or later. Copyright (C) 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. * Menu: * Licensing information:: Conditions for use * Author and version:: Who wrote this * LaTeX support:: Editing features for LaTeX documents * SliTeX support:: Editing features for SliTeX documents * Letter support:: Editing features for writing letters * Bug reporting:: How to report bugs, comments, etc. * Conclusion:: What more I can say * Bibliography:: Literature references * Concept Index:: General topic index * Control Sequence Index:: TeX and LaTeX control sequences * Function Index:: Lisp functions * Key Index:: Key bindings * Person Index:: Individuals cited in this text * Variable Index:: Lisp variables  File: latex-mode.info Node: Licensing information, Prev: Top, Up: Top, Next: Author and version Licensing Information ********************* The program currently being distributed that relates to LaTeX is contained in the file `latex.el' in the function `LaTeX-mode' and numerous other support functions. This program is "free"; this means that everyone is free to use it and free to redistribute it on a free basis. Specifically, we want to make sure that you have the right to give away copies of the programs that relate to `LaTeX-mode', that you receive source code or else can get it if you want it, that you can change these programs or use pieces of them in new free programs, and that you know you can do these things. To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights. For example, if you distribute copies of the file `latex.el', you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. Also, for our own protection, we must make certain that everyone finds out that there is no warranty for the programs that relate to `latex.el'. If these programs are modified by someone else and passed on, we want their recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation. The precise conditions of the licenses for the programs currently being distributed that relate to `latex.el' are found in the General Public Licenses that accompany them. The programs that are part of GNU Emacs are covered by the GNU Emacs copying terms (*Note License: (emacs)License.), and other programs are covered by licenses that are contained in their source files.  File: latex-mode.info Node: Author and version, Prev: Licensing information, Up: Top, Next: LaTeX support The GNU Emacs Lisp file `latex.el', and its predecessor, TOPS-20 Emacs TECO file `latex.emacs', was developed by Nelson H. F. Beebe Center for Scientific Computing Department of Mathematics University of Utah Salt Lake City, UT 84112 USA Tel: +1 801 581 5254 FAX: +1 801 581 4148 E-mail: beebe@math.utah.edu from 1984 to 1991, and contributed to the Free Software Foundation. This documentation corresponds to version 1.0 of `latex.el'. This should match the code version that is stored in the Emacs variable `LaTeX-mode-version'.  File: latex-mode.info Node: LaTeX support, Prev: Author and version, Up: Top, Next: SliTeX support LaTeX support ************* * Menu: * Preliminaries:: * Creating a new LaTeX file:: * LaTeX macros:: * LaTeX environments:: * Common commands:: * Math mode:: * Dots, commas, and quotation marks:: * Font changes:: * Comments:: * Mismatched delimiters:: * Mismatched environments:: * Word abbreviations:: * Bibliographies:: * Indexing:: * Cross-references:: * French typography:: * Miscellaneous functions:: * Miscellaneous variables:: * Customizing lists::  File: latex-mode.info Node: Preliminaries, Prev: LaTeX support, Up: LaTeX support, Next: Creating a new LaTeX file Preliminaries ============= The material that you are now reading is contained in the distribution as two files, `ltxmode.ltx' for the TUGboat article, and `ltxinfo.ltx' for LaTeXinfo. The first job is to arrange for `LaTeX-mode' to be selected automatically when required. Because the `latex.el' file of Lisp code is not yet a standard part of the GNU Emacs distribution, its association with particular file extensions is unknown to Emacs. To remedy that, the Lisp code in Table 1 should be inserted into the `.emacs' file in your login directory; that file is processed each time Emacs starts up. The `load' command there tells where `latex.el' is found; it may need adjustment for your system. ---------------------------------------------------------------------- ;============================================= ; Add mode for .ltx files if not there already ; for most people: (load-library "latex.el") ; for my private version: ; Force tex-mode.el to be loaded so latex.el ; can override it. (load-library "tex-mode") (load "~/emacs/latex" t t nil) (if (not (assoc "\\.ltx$" auto-mode-alist)) (setq auto-mode-alist (cons (cons "\\.ltx$" 'LaTeX-mode) auto-mode-alist))) (if (not (assoc "\\.stx$" auto-mode-alist)) (setq auto-mode-alist (cons (cons "\\.stx$" 'LaTeX-mode) auto-mode-alist))) (if (not (assoc "\\.sty$" auto-mode-alist)) (setq auto-mode-alist (cons (cons "\\.sty$" 'LaTeX-mode) auto-mode-alist))) ;============================================= ; Private letter support (load "~/emacs/letter" t t nil) ---------------------------------------------------------------------- Table 1 : `.emacs' file additions. The peculiar `if' commands attach `LaTeX-mode' to the `auto-mode-alist' variable, which is a list of pairs of file extensions and their mode names; the attachment is omitted if the file extensions are already in the list. Once this startup code has been executed, Emacs will automatically select `LaTeX-mode' when you visit files with extensions `.ltx' (LaTeX document), `.stx' (SLiTeX document), or `.sty' (LaTeX style). Others can be easily added according to taste. File extension `.tex' is already attached to GNU Emacs `tex-mode' which comes with the system, so different extensions are needed for different editing modes. If you don't have these associations of file extensions with editing modes in effect, you can always select the mode manually with the command `M-x LaTeX-mode'. Experienced Emacs users may wonder why the `autoload' facility is not used instead of the explicit `load' command in the startup file; the reason lies in a conflict with the standard `tex-mode'. I expect that conflict will be removed when `latex.el' becomes part of the standard GNU Emacs distribution. A modification of `tex-mode.el' that eliminates all LaTeX-specific code has been prepared locally, and that new version removes the incompatibility with `latex.el', allowing `autoload' to be used. In GNU Emacs Lisp, named functions, and variables defined outside functions, are known globally. There is no provision for file scoping or mode scoping to limit name visibility. Consequently, to avoid collision with the thousands of names from other libraries, each library usually includes a distinctive phrase in its global names. Naturally enough, `LaTeX' and `SLiTeX' are the phrases chosen in `latex.el'. They are almost always used as prefixes in variable names, and usually also in function names, although a few functions have embedded phrases for better readability (e.g. `show-LaTeX-labels'). Tables 2 through 4 show the documentation summary for `LaTeX-mode', which you can always reproduce online with the function `describe-mode' which is normally bound to the key `C-h m'. Only major mode functions have such long documentation. Table 5 shows a more typical case, the documentation of the function `LaTeX-index'. You could produce it online with the function `describe-function' on `C-h d'. Tables 6 and 7 show the key bindings in `LaTeX-mode'; the listings can be produced by the function `describe-bindings' which is normally attached to `C-h b'. The name and documentation of the function attached to any key can be obtained by invoking the function `describe-key' attached to `C-h k'. You can change existing key bindings, or add new ones, with the functions `local-set-key' and `global-set-key', and otherwise modify the behavior of `LaTeX-mode'. *Note Customizing lists:: for details. ---------------------------------------------------------------------- LaTeX Mode: Major editing mode for LaTeX and SLiTeX, with tex-mode underneath. To create a new LaTeX document, use make-LaTeX-document (on C-c d), or make-SLiTeX-document (on C-c s). With an argument, they will provide some additional helpful comments. The functions will prompt for document style and options. Type ? to see the standard ones; you can enter them with name completion. You can also enter your own, since it is possible to have private styles and options unknown to make-LaTeX-document or make-SLiTeX-document. The most frequent LaTeX construct is the \begin{}...\end{} grouping; you can generate it by LaTeX-begin-end-block (on C-c b). With an argument, a helpful comment may be printed. Type ? to see the standard environments, or enter your own. If you type a \begin{...} manually, you can later generate a matching \end{...} with the function LaTeX-end (on C-c n). Other common constructs are the insertion of labels, citations, cross-references, index entries, verbatim strings, and additional items in a list. The functions C-c . LaTeX-add-word-to-index C-c C-b LaTeX-bibitem C-c c LaTeX-cite C-c k LaTeX-counter C-c f LaTeX-footnote C-c x LaTeX-index C-c i LaTeX-item C-c l LaTeX-label C-c m LaTeX-macro C-c p LaTeX-pageref-with-completion C-c C-p LaTeX-protect C-c r LaTeX-ref-with-completion C-c v LaTeX-verb C-c d make-LaTeX-document C-c s make-SLiTeX-document provide for these. ---------------------------------------------------------------------- Table 2 : Online summary of LaTeX mode. ---------------------------------------------------------------------- LaTeX-tab (on C-c TAB) will indent a line to the current \begin{}...\end{} nesting level. Most major LaTeX macros can be entered by LaTeX-macro (on C-c m). This will supply the correct set of following braces, brackets, and parentheses, and with an argument, will insert a short comment about the expected command arguments. For SLiTeX, the function renumber-slides can be used to put a numbered comment on each slide environment for handy reference in the \onlynotes{...} and \onlyslides{...} commands. You can move over \begin{} ... \end{} groups with LaTeX-to-begin (on C-c a) and LaTeX-to-end (on C-c e). Insertion of paired angle brackets, braces, square brackets, and parentheses is provided by C-c < LaTeX-angles C-c { LaTeX-braces C-c [ LaTeX-brackets C-c ( LaTeX-parentheses With an argument, the last three insert backslash prefixes for literal braces, math mode, and displaymath mode. Unbalanced character pairs are found by C-c > LaTeX-check-angle-balance C-c } LaTeX-check-brace-balance C-c ] LaTeX-check-bracket-balance C-c $ LaTeX-check-dollar-balance C-c ) LaTeX-check-parenthesis-balance You can test for undefined labels with check-LaTeX-labels, display the labels and their line numbers with show-LaTeX-labels, and fetch labels from an .aux file with update-LaTeX-labels. ---------------------------------------------------------------------- Table 3 : More about LaTeX mode. ---------------------------------------------------------------------- Environment nesting errors can be caught by check-LaTeX-nesting. Use indent-LaTeX-begin-end-groups to get environments nested for improved visibility. Use LaTeX-comment (on C-c %) to comment out the current paragraph (no arg) or region (arg); undo with M-X undo (C-_). LaTeX- uncomment (on C-c u) is the inverse function. One or more words can be set in any standard LaTeX font using the commands C-c C-c b LaTeX-font-bf C-c C-c e LaTeX-font-em C-c C-c i LaTeX-font-it C-c C-c r LaTeX-font-rm C-c C-c u LaTeX-font-sc C-c C-c f LaTeX-font-sf C-c C-c s LaTeX-font-sl C-c C-c t LaTeX-font-tt Please report bugs, comments, and enhancements by e-mail to beebe@math.utah.edu (Internet) LaTeX-gripe (on C-c g) makes this easier. ---------------------------------------------------------------------- Table 4 : Even more about LaTeX mode. ---------------------------------------------------------------------- LaTeX-index: Insert \index{ ... } at point (on C-c x). If a prefix argument is given, the string is prompted for, and inserted both as text and as an index entry, e.g. gnats and gnus\index{gnats and gnus}. All horizontal space preceding \index is removed to prevent an intervening page break causing an off-by-one page number error. If LaTeX-index-start-with-newline is non-nil, insert a percent to start a comment, then put \index at the start of a following new line. If LaTeX-index-end-with-newline is non-nil, follow the entry with a new line. ---------------------------------------------------------------------- Table 5 : Online help for `LaTeX-index'. ---------------------------------------------------------------------- Local Bindings: key binding --- ------- _ LaTeX-subscript ^ LaTeX-superscript . LaTeX-dot , LaTeX-comma $ LaTeX-dollar ESC Prefix Command LFD newline-and-indent C-c Prefix Command " LaTeX-quote C-c , LaTeX-set-indentation C-c C-c Prefix Command C-c = LaTeX-equation C-c } LaTeX-check-brace-balance C-c { LaTeX-braces C-c x LaTeX-index C-c v LaTeX-verb C-c u LaTeX-uncomment C-c s make-SLiTeX-document C-c r LaTeX-ref-with-completion C-c p LaTeX-pageref-with-completion C-c n LaTeX-end C-c m LaTeX-macro C-c l LaTeX-label C-c k LaTeX-counter C-c i LaTeX-item C-c g LaTeX-gripe C-c f LaTeX-footnote C-c e LaTeX-to-end C-c d make-LaTeX-document C-c c LaTeX-cite C-c b LaTeX-begin-end-block C-c a LaTeX-to-begin C-c 0 renumber-slides C-c ] LaTeX-check-bracket-balance C-c [ LaTeX-brackets C-c . LaTeX-add-word-to-index ---------------------------------------------------------------------- Table 6 : Local bindings in LaTeX mode. ---------------------------------------------------------------------- C-c ) LaTeX-check-parenthesis-balance C-c ( LaTeX-parentheses C-c % LaTeX-comment C-c $ LaTeX-check-dollar-balance C-c > LaTeX-check-angle-balance C-c < LaTeX-angles C-c C-p LaTeX-protect C-c C-n LaTeX-news C-c TAB LaTeX-tab C-c C-b LaTeX-bibitem ESC ) forward-list ESC ( backward-up-list C-c C-c t LaTeX-font-tt C-c C-c s LaTeX-font-sl C-c C-c f LaTeX-font-sf C-c C-c u LaTeX-font-sc C-c C-c r LaTeX-font-rm C-c C-c i LaTeX-font-it C-c C-c e LaTeX-font-em C-c C-c b LaTeX-font-bf C-c C-c } LaTeX-check-brace-balance C-c C-c ] LaTeX-check-bracket-balance C-c C-c ) LaTeX-check-parenthesis-balance C-c C-c $ LaTeX-check-dollar-balance C-c C-c = LaTeX-displaymath ---------------------------------------------------------------------- Table 7 : More local bindings. }  File: latex-mode.info Node: Creating a new LaTeX file, Prev: Preliminaries, Up: LaTeX support, Next: LaTeX macros Creating a new LaTeX file ========================= When you visit a new LaTeX file, Emacs starts up with an empty buffer. The mode line at the bottom of the screen will look something like ---Emacs: foo.ltx (LaTeX Abbrev Fill)----All--- The first thing you want to do is get a standard template of a LaTeX file inserted; you do this by typing `C-c d' (`make-LaTeX-document'). This function will first prompt you with Document style: to which you can respond either with a complete style file name, or with the first few characters of a standard style, followed by a space to request Emacs to complete the name, and a `RETurn' to accept the completion. If you are unsure of what to supply, just type a query (?); Emacs will respond with something like Possible completions are: aaai amsart amsbook amstex aps article book deproc letter ltugproc refman report siam slides tugboat ucthesis uoftoronto usafmemo uuthesis xxxslides Completion can also be requested on partial names: the input `a?' in the above command will respond with Possible completions are: aaai amsart amsbook amstex aps article Suppose you type `article' or `ar`'', followed by a `RETurn'. Then Emacs will respond with Document option (RET when done): to which you can then supply an option name followed by a `RETurn'. As before, a query will show you what is available: Possible completions are: 11pt 12pt a4 a4wide acm acronym agugrl agujgr alltt amsbsy amscd amsfonts amssymb amssymbols amstext apalike archmemo array bezier biihead boxedmini changebar chapterbib cite clsc clscmemo concrete cropmark ctagsplt cyrillic dblspace doublespace draft drafthead drop dvidoc eqsecnum espo fleqn format fullpage geophysics german gnuindex ifthen intlim ist21 leqno listing longtab ltugboat makeidx math merge mfr mitthesis moretext natsci nl nonamelm nopageno nosumlim openbib pandora preprint proc psmavg psmbkm psmncs psmpal psmtim remark resume revtex righttag sc21 sc21-wg1 sfwmac showidx showlabels slem spacecites supertab suthesis tablisting tapeseal texindex texnames tgrind theorem thp threepart titlepage trademark troffman troffms twocolumn twoside underline uofutah vdm verbatim You can keep on selecting options until you finally just type a bare `RETurn', at which point `make-LaTeX-document' completes, and you have a buffer that looks like this: % -*-latex-*- % Document name: /u/beebe/foo.ltx % Creator: Nelson Beebe [beebe@math.utah.edu] % Creation Date: Sun Jul 28 08:44:46 1991 \documentstyle[11pt,makeidx]{article} \newcommand{\X}[1]{{#1}\index{{#1}}} \begin{document} \end{document} The cursor, represented by `', is left positioned on the line following the `\begin{document}', ready for text entry. The initial comment with the tag `-*-latex-*-' is a special one. It requests an automatic mode selection when the file is freshly visited in Emacs, overriding any mode that might otherwise be selected based on the file name extension. `latex-mode' is made equivalent to `LaTeX-mode' in `latex.el' so that the comment tag can be written in lower-case letters, as is conventional. The `% Creator:' comment information is obtained from Emacs' operating system interface, which in turn fetches the user's personal name and login name from system authorization files. On networked systems, the hostname is included as well, creating a valid electronic mail address. Had you given `make-LaTeX-document' an argument, it would have been somewhat more verbose: % -*-latex-*- % Document name: /u/beebe/tex/tugboat/foo.ltx % Creator: Nelson Beebe [beebe@math.utah.edu] % Creation Date: Sun Jul 28 08:46:33 1991 %---------------------------------------------- % EVERYTHING TO THE RIGHT OF A % IS A REMARK % TO YOU AND IS IGNORED BY LaTeX. % % WARNING! DO NOT TYPE ANY OF THE FOLLOWING 10 % CHARACTERS AS NORMAL TEXT CHARACTERS: % & $ # % _ { } ^ ~ \ % % The following seven are printed by typing a % backslash in front of them: % $ & # % _ { and }. %---------------------------------------------- \documentstyle[11pt,makeidx]{article} \newcommand{\X}[1]{{#1}\index{{#1}}} \begin{document} \end{document} The extra commentary is a useful reminder for beginning LaTeX users. Several other commands in `LaTeX-mode' use the presence of an argument to supply additional helpful commentary. The `\X' command is one I have found helpful for preparing indexes; typing `\X{gnats and gnus}' will put that phrase in both the document and the index. Further discussion is given later; *Note Indexing::. The lists of standard styles and options are embedded in the `latex.el' code. They cannot be determined automatically from the file system for several reasons: * Some options (e.g. `11pt') do not have a corresponding style file. * Some style files do not represent a valid option (e.g. `art10.sty'). * Some style files found in the normal `TEXINPUTS' search path belong to other systems, such as AmSTeX. * It is impossible to distinguish from the `.sty' file extension whether the file represents a major document style, or merely an option that modifies a major style. It is regrettable that these difficulties exist, because they confuse users, as well as programmers of code like `LaTeX-mode'. It is often difficult to tell from its contents whether a particular file is a major style, or just a document option. It would have been wiser in the initial LaTeX design to have chosen distinctive file extensions, and for each style and option to be associated with a unique file. The present collection of twenty available styles and over one hundred options is daunting for a novice, particularly since many options can only be used with certain styles. Eventually I may find a satisfactory way to deal with this, and offer a better presentation of choices in the completion lists. The style and option lists can be easily extended. *Note Customizing lists:: for details.  File: latex-mode.info Node: LaTeX macros, Prev: Creating a new LaTeX file, Up: LaTeX support, Next: LaTeX environments LaTeX macros ============ Every one of the 589 LaTeX macros in the index to the *LaTeX User's Guide and Reference Manual* [Lamport:latex] is known to the function `LaTeX-macro' (on `C-c m'), and as before, Emacs command completion is available with the query (?) and space (`') characters. Thus, you can type * `C-c m longr' `RETurn' to get `\longrightarrow'; * `C-c m em' `RETurn' to get `{\em \/}' with the cursor positioned ready for you to enter some text; * `C-u' `C-c m newcom' `RETurn' to get `\newcommand{}[]{} % {\cmd}[n]{def} define new command with n arguments' * `C-c m e?' to find the names of macros that begin with `e': Possible completions are: ell em emptyset encl end epsilon equiv eta evensidemargin exists exp extracolsep When the cursor is left after an open brace in a generated command, the closing brace is by default placed at the start of the next line so that you have a clean line to type on. This reduces visually-distracting screen updates, but means that you will need to delete the end-of-line character when you finish typing the argument. If you don't like this behavior, you can set the Emacs variable `LaTeX-newline-after-opening-delimiter' to a `nil' value, usually in your `.emacs' startup file: (setq LaTeX-mode-hook '(lambda () (setq LaTeX-newline-after-opening-delimiter nil) ) ) The variable `LaTeX-newline-after-closing-delimiter' is used similarly for brace pairs inserted on their own, or after certain macros. A *mode hook*is Lisp code to be executed whenever the corresponding mode function is executed. The hook is called just before the mode function returns, so it can override anything that the function did. The peculiar `lambda ()' is the Lisp way of declaring a nameless function. The single quote prefixing it means that `LaTeX-mode-hook' will be assigned the function itself, and not the value returned by the function. In GNU Emacs, you can execute Lisp code in a file through `M-x load-file' and `M-x load-library' commands. Inline code must be executed in a buffer which is in `emacs-lisp-mode'. The minibuffer always has that mode, and can be temporarily accessed with the `eval-expression' function bound to `ESCape ESCape'. If you just want to set an Emacs variable, you can also use the command `M-x set-variable'; it supports completion on the variable name, and prompts for the value. The availability of all of the LaTeX macros with `LaTeX-macro' reduces the likelihood of spelling mistakes, and the command completion usually means that only a few leading characters need to be typed. The complete macro name is entered in the buffer: `\abovedisplayshortskip' is much more readable than a cryptic `\adss' that LaTeX users without such editing support might be inclined to define as a private macro to save typing effort. If you have frequently-used private macros, there is a convenient way to make them known to `LaTeX-mode'. *Note Customizing lists::for details.  File: latex-mode.info Node: LaTeX environments, Prev: LaTeX macros, Up: LaTeX support, Next: Common commands LaTeX environments ================== An important concept in LaTeX is the notion of *environments*, which are marked by surrounding `\begin{...}' and `\end{...}' commands. The braced tag must be repeated, and if the tag name is long, spelling errors are more likely. The function `LaTeX-begin-end-block' on `C-c b' generates the command pair, indented according to the current nesting level, and leaves the cursor on the line between them. The indentation is controlled by the value of the Emacs variable `LaTeX-begin-end-indentation'; the default is two spaces. If the variable `LaTeX-space-after-begin-end' is non-`nil', a space will be inserted between the keyword and the following opening brace. The default value is `nil'. This formatting style is discouraged, because it cannot be applied uniformly; it must be suppressed for the `verbatim' environment. The code in `latex.el' knows about this vagary, and always omits the space for that environment. The keystrokes `C-c b quote' `RETurn' `C-c b ite`'' `RETurn' `C-c b verb`'' `RETurn' produce \begin{quote} \begin{itemize} \item \begin{verbatim} \end {verbatim} \item \item \item \end{itemize} \end{quote} with the cursor inside the `verbatim' environment. Notice that the normal indentation is automatically suppressed for that environment; the command knows that leading spaces in front of `\end{verbatim}' would otherwise generate an unwanted blank line in the typeset output. If you have private environments, you can still use `C-c b'; you just have to type the complete environment name. If you use some private ones frequently in different documents, it is possible to extend the list of environments known to `LaTeX-mode'. *Note Customizing lists::for details. In those environments that have `\item' commands, four are generated by default; that number can be changed by modifying the value of the Emacs variable `LaTeX-item-count'. Their indentation is defined by the variable `LaTeX-item-indentation'; the default is two spaces. Additional indentation of text under a `\item' command is set by the variable `LaTeX-item-info-indent'; the default is six spaces. You can generate additional `\item' commands as needed with the function `LaTeX-item' on `C-c i'. With an argument, it supplies the alternate form `\item[]' instead. If you forgot about the `C-c b' command, and manually typed a `\begin{conjecture}', you can get the matching `\end{conjecture}' generated automatically by typing `C-c n' (`LaTeX-end'). That is also sometimes helpful when you have forgotten what environment you are in: you can generate the `\end{...}', and then kill it. You can type `C-c a' (`LaTeX-to-begin') to move backward to the enclosing `\begin'; with an argument, you can move backward over a specified number of `\begin{...}'s. If the argument is negative, you move forward over `\end{...}'s instead. Usually, you would use `C-c e' (`LaTeX-to-end') instead to move forward over `\end{...}'s; that command handles numeric arguments too, and reverses direction for negative arguments. These two movement commands are analogous to the standard Emacs commands for moving backward and forward in sentences, normally bound to `M-a' and `M-e'. They also require that the `\begin' and `\end' macros be preceded on their lines only by optional whitespace, and immediately followed by open braces. This helps to enforce the discipline of keeping the `\begin{...}' ...`\end{...}' grouping properly nested and readable, and also avoids having to deal with more complex input parsing.  File: latex-mode.info Node: Common commands, Prev: LaTeX environments, Up: LaTeX support, Next: Math mode Common commands =============== Some LaTeX macros are used so often that it is desirable to have them bound directly to keys, instead of having to type their first few characters with `LaTeX-macro' as described earlier. You can find a list of these convenience functions in the fourth paragraph of Table 2. For example, typing `C-c l' (that's the letter `l') generates ~\label{} at the cursor position, leaving the cursor after the open brace.  File: latex-mode.info Node: Math mode, Prev: Common commands, Up: LaTeX support, Next: Dots and commas and quotation marks Math mode ========= TeX's math mode uses paired dollar signs to delimit the math text. Single dollar signs mark inline math, and doubled ones mark display math. If you forget to type a closing dollar sign, or type the wrong number of dollar signs, TeX will complain bitterly. The start and finish of these math regions are indistinguishable, making it hard for simple programs (and sometimes, readers) to distinguish the `inside' from the `outside'. Consequently, LaTeX additionally supports two bracketing forms: \samp{\back (} ...`\)' for `$ ... $', and `\[' ...`\]' for `$$ ... $$', as well as more readable forms \begin{math} ... \end{math} \begin{displaymath} ... \end{displaymath} for the single and double dollar sign pairs, respectively. All of these have unique opening and closing sequences. `LaTeX-mode' supports all of these forms. The variants selected are determined by the variables `LaTeX-math-option' and `LaTeX-displaymath-option'. Values of 0, 1, and 2 select the dollar, backslashed delimiter, and `\begin{...}' ...`\end{...}' environment forms respectively; all other values are equivalent to 0. The default values select the single dollar and `displaymath' forms. Normally, when you type a dollar sign, you get an inline math environment. If the dollar sign happens to be at the beginning of a line, it expands instead into a display math environment. On the other hand, if the preceding character was a backslash, you just get a plain dollar sign. Spacing around the inserted text is controlled by two more variables. If `LaTeX-newline-after-opening-delimiter' is non-`nil' (the default), the opening delimiter is followed by a newline, with the cursor positioned immediately after the delimiter for the inline case, and on a new line for the display form. If `LaTeX-newline-after-closing-delimiter' is non-`nil' (the default), the closing delimiter is followed by a newline. This pleasantness is our first example of having an alternate function bound to a normal printing character. Instead of running the usual `self-insert-command' attached to printing characters, `$' is bound to `LaTeX-dollar' which has been programmed to deal with the three different meanings of the dollar sign. Few editors outside the Emacs family could do this; the critical feature is that *any character* can run *any function*. What if you really just wanted a single plain dollar sign, with no preceding backslash? Well, that is easy. In Emacs, any character can be *quoted*, which causes it to be inserted directly into the buffer; the `quoted-insert' function is normally bound to `C-q', but that too can be changed. Thus, `C-q $' will get you a literal dollar sign, if that is what you really want. The function `LaTeX-equation' on `C-c =' generates \begin{equation} \end{equation} with the cursor between them. `LaTeX-displaymath' on `C-c C-c =' inserts \begin{displaymath} \end{displaymath} All math mode environments (`array', `eqnarray*', `eqnarray', `math', and `theorem') can be also generated by `LaTeX-begin-end-block' on `C-c b', and additional ones can be easily added; *Note Customizing lists::. `LaTeX-subscript' on `_' (underscore) and `LaTeX-superscript' on `^' (caret) generate braced subscript and superscript sequences, leaving the cursor between the braces [vonBechtolsheim:TQ7-195].  File: latex-mode.info Node: Dots and commas and quotation marks, Prev: Math mode, Up: LaTeX support, Next: Font changes Dots, commas, and quotation marks ================================= The dot or period (full stop, to some of you) is an overloaded character. Normally, it just means end of sentence. Sometimes, it ends an abbreviation in the middle of a sentence. It can also be a decimal point, as in 3.14159. Still other times, it appears in ellipses, as in centered dots (`\cdots'), diagonal dots (`\ddots'), ellipses (`\ldots'), and vertical dots (`\vdots'). In typography, these uses are distinguished by small changes in spacing after the dots. That is why TeX provides control sequences for the ellipses, and the LaTeX book [Lamport:latex, p. 14] recommends that you type a `\' sequence after a period that does not end a sentence. TeX assumes that a period following an upper-case letter does not end a sentence (it might be someone's initial) [Knuth:texbook, pp. 74, 311], and follows it with a smaller amount of space. The *LaTeX User's Guide and Reference Manual* recommends insertion of `\@' before a sentence-ending dot that follows an upper-case letter in order to get additional space after the dot. `LaTeX-mode' handles these intricacies by binding dot to the function `LaTeX-dot'. That function examines what is immediately before the dot in the buffer, and takes one of several actions: * If the dot ends an ellipsis, the three dots are replaced by `\ldots{}'. * If the dot is preceded by an italic correction at group end, `\/}', the italic correction is removed. * If the dot ends an abbreviation, like *e.g.* or *i.e.*, it inserts a `\' command or a comma, depending on whether the variable `LaTeX-comma-after-dotted-abbreviation' is `nil' or non-`nil'. Traditionally, such abbreviations are followed by a comma, but modern tendency is to omit the comma [Shertzer:grammar, p. 84], although Knuth disagrees [Knuth:texbook, p. 74]. * If the previous characters are abbreviations like *Fig.*, *cf.*, *vs.*, and *resp.* [Knuth:texbook, p. 74] [Lamport:latex, p. 18] that should be tied to the following word with a single unbreakable space, the function inserts a tilde to mark the tie. * If the dot follows two or more upper-case letters, the dot is prefixed by `\@'. To prevent confusion with words at end of sentence, abbreviations are not recognized if they are immediately preceded by a letter in the editing buffer. The abbreviations known to `LaTeX-dot' are defined by the variable `LaTeX-standard-dotted-abbreviations'. More can be added by a suitable definition of the variable `LaTeX-extra-dotted-abbreviations', such as this example: (setq LaTeX-extra-dotted-abbreviations '( ("ad. lib.") ("cwt.") ("q.e.d.") ) ) *Note Customizing lists::for more details. The abbreviations for which ties are supplied are similarly defined by the variables `LaTeX-standard-tied-abbreviations' and `LaTeX-extra-tied-abbreviations'. `LaTeX-dot' cannot tell whether a dot following an upper-case letter is a sentence-ending one or not, so it only inserts `\@' before a dot if there are *two or more* preceding upper-case letters. It is up to the user to remember to insert `\@' in the exceptional case of a single final upper-case letter. What about a dot after a macro that expands to a word ending in an upper-case letter, like TeX itself? No `\@' is necessary there, because TeX treats that dot as a normal end of sentence. These actions cover most of the common cases, but of course, for abbreviations, cannot be omniscient. Dictionaries that I consulted listed over a thousand abbreviations in use in English. Fewer than a dozen of the commonest ones are included in `LaTeX-standard-dotted-abbreviations', but customization of `LaTeX-extra-dotted-abbreviations' provides a way to add new ones. Emacs' `quoted-insert' function saves the day when you want to suppress all of this wizardry; just type `C-q .' to get a literal dot inserted. `LaTeX-comma' bound to comma removes any immediately preceding italic correction, and then inserts a comma. Italic corrections are somewhat of a nuisance, since you are supposed to have them after italicized text, *except* a period or a comma, which are so low that it doesn't matter if the character to their immediate left leans over them. Those two exceptions make it hard to write a TeX macro to determine whether the correction is needed or not. I'd rather let Emacs remember for me, so I programmed it to do so. Good typography uses different opening and closing quotation marks; in TeX, you get "quoted text" by typing `"quoted text"'. Because many people are accustomed to using the double quotation mark character, `"', found on computer keyboards and typewriters, the function `LaTeX-quote' is bound to that character. It generates the correct paired opening grave accents, `"', or closing apostrophes, `"', as appropriate: the input `"quoted text"' expands to `"quoted text"' in the edit buffer. With an argument, the function inserts a bare double quotation mark; you can get the same effect from `quoted-insert' by typing `C-q "'.  File: latex-mode.info Node: Font changes, Prev: Dots and commas and quotation marks, Up: LaTeX support, Next: Comments Font changes ============ The `LaTeX-macro' function on `C-c m' lets you easily generate font changes to any of LaTeX's eight standard styles, including supplying the italic correction in the three leaning font styles (`\em', `\it', and `\sl'). But what if you are revising a document, and decide to add a font change? Well, you could use `C-c m' to do it, but then you'd have to move the closing brace, and any preceding italic correction. `LaTeX-mode' provides a better solution: customized functions *wrap* a font change around the current word, or if a numeric argument is given, around that many words starting from the current one. These functions are listed in Table 7. They are almost the only functions that require a second prefix character; `C-c C-c e' (`LaTeX-font-em') is easy to type, and retains mnemonic significance. These functions handle the italic correction properly; leaning fonts get it unless the character following the last word is a period or a comma.  File: latex-mode.info Node: Comments, Prev: Font changes, Up: LaTeX support, Next: Mismatched delimiters Comments ======== TeX provides an inline comment mechanism with the percent sign. It discards text from that character to the end of the line, plus *all leading space on the next line up to, but not including, its end-of-line character*. Sometimes, however, you want to temporarily suppress typesetting of a part of a document without actually removing it from the file. One way is to insert leading percents on each line of the region to be suppressed, but that is tedious to do manually. A second way is to use LaTeX's `ifthen' style option which added loops and conditionals, but appeared after the *LaTeX User's Guide and Reference Manual* was written, and so is not widely known. A third way is to define a LaTeX macro like \newcommand{\comment}[1]{} However, that won't work if the argument contains paragraph breaks. You could drop down to low-level TeX and write \long\def\comment#1{} but LaTeX users are not supposed to do that, except in style files. Also, both of these macros risk overflowing TeX's input buffer, since the complete argument might be rather long, even if it is subsequently discarded. I often wish that LaTeX had provided a standard `comment' environment to do this; it could be implemented much like `verbatim', except that it must support properly nested `comment' environments. Rainer Schopf has implemented a version of a `comment' environment in a new `verbatim' implementation for LaTeX [Schoepf:TB11-2-284-296], although nested comments are not yet supported. The solution provided by `LaTeX-mode' is the function `LaTeX-comment' on `C-c %' which implements the first choice above. By default, it comments out the current paragraph, or with an argument, the current region. The comment prefix inserted at the beginning of each line is defined by the variable `LaTeX-comment-prefix'; its default value is `%%:'. A unique prefix is desirable to distinguish such lines from ordinary comments. You should avoid using any regular-expression matching characters in it. You can remove the comments inserted by `LaTeX-comment' with the function `LaTeX-uncomment' on `C-c u'. It should normally be used with an argument to act on a region, instead of a paragraph. The reason for this is that paragraphs are recognized according to the regular expression in the Emacs variable `paragraph-separate'; the default setting is such that a line containing only a comment ends a paragraph. Consequently, `LaTeX-uncomment' will do nothing because its `paragraph' is always empty. Invoking it with an argument to process a marked region solves the problem.  File: latex-mode.info Node: Mismatched delimiters, Prev: Comments, Up: LaTeX support, Next: Mismatched environments Mismatched delimiters ===================== TeX gets very unhappy when it finds mismatched braces, and in complex documents, it can sometimes be difficult to find them. The job is not made easier on low-resolution screen displays where braces and parentheses are virtually indistinguishable. Finding such mismatches is a job for a computer, not a human, and `LaTeX-mode' offers you help. Braces are not the only things you might want assistance with. Checking for mismatched parentheses, square brackets, and angle brackets is also supported. These normally insert themselves when you type them, but `LaTeX-mode' has commands that insert pairs: typing `C-c {' gets you a pair of open and close braces, and similarly for `C-c [', match `C-c (', and `C-c <'. These are the default bindings of the functions `LaTeX-braces', `LaTeX-brackets', `LaTeX-parentheses', and `LaTeX-angles'. If you get in the habit of using these instead of typing the delimiter pair yourself, you will rarely have mismatch problems. Emacs itself has native delimiter matching support: as you type a close delimiter, the cursor flashes briefly to the matching open delimiter. But what if you didn't follow my advice, typed a lot of braces yourself, and then when TeX complained about unbalanced braces, you couldn't find the errors? Well, the function `LaTeX-check-brace-balance' bound to `C-c }' will scan the buffer from the current point to the end, checking for unbalanced braces, and brace pairs separated by unusually long strings, but ignoring backslashed braces. It complains if it finds a paragraph break between braces, unless you give it an argument. If mismatches are detected, you are so informed, and the positions of the mismatches are remembered on Emacs' stack of marks, so you can easily get to them. Similar functions `LaTeX-check-angle-balance', `LaTeX-check-bracket-balance', and `LaTeX-check-parenthesis-balance' are provided on `C-c >', `C-c ]',} and `C-c )', for checking those delimiter balances. Note the key binding symmetry: `C-c open-delimiter' inserts the pair, and `C-c close-delimiter' checks the balance. The characters `<' and `>' are likely to be used in math mode, and not require balancing. However, you might also have used them for other purposes. In such a case, you can just add matching delimiters inside comments in your math mode uses, and then `C-c >' will work satisfactorily. There is also `LaTeX-check-dollar-balance' on `C-c $'. It looks for dollar pairs separated by long strings, ignoring backslashed dollars. It also complains about paragraph breaks between dollar pairs, unless it is given an argument. There is no way for a computer program that is much less complex than TeX to tell the inside of math mode from the outside, so you can confuse this function by starting it inside math mode. The Emacs variables `LaTeX-angle-interval', `LaTeX-brace-interval', `LaTeX-bracket-interval', `LaTeX-dollar-interval', and `LaTeX-parenthesis-interval' set the limiting between-delimiter string length before a warning is raised; their default values are each set to 500 characters.  File: latex-mode.info Node: Mismatched environments, Prev: Mismatched delimiters, Up: LaTeX support, Next: Word abbreviations Mismatched environments ======================= If you have a complex document where `\begin{...}' ...`\end{...}' groups have been typed manually, you can also end up with mismatched environments that are hard to find. The command `M-x check-LaTeX-nesting' scans the buffer to ensure the correctness of `\begin{...}' ...`\end{...}' nesting. If, for example, your buffer contains a nesting error like this \begin{verse} ... \begin{quote} ... \end{verse} ... \end{quote} the command will terminate with the cursor in front of the `\end{verse}' with the error message This \end{verse} is matched by preceding \begin{quote} at mark. The Emacs function `exchange-point-and-mark' on `C-x C-x' will move the cursor to the mismatching `\begin{quote}'. After fixing the error, you can rerun the nesting check by typing `C-x ESCape' (`repeat-complex-command') until it finally reports [done] -- all \begin{}-end{}s balance. The command `M-x indent-LaTeX-begin-end-groups' indents `\begin{...}' ...`\end{...}' groups according to their nesting level, which helps to make the input file more readable. You don't need these commands very often, so they do not have default key bindings.  File: latex-mode.info Node: Word abbreviations, Prev: Mismatched environments, Up: LaTeX support, Next: Bibliographies Word abbreviations ================== Emacs provides a convenient word abbreviation facility that permits the automatic expansion of a string of letters when the following space or punctuation is typed. `LaTeX-mode' provides this by default with a set of abbreviations in a table that can be customized for personal use. You can find the complete set of abbreviations by examining the value of the variable `LaTeX-mode-abbrev-table', or by invoking the function `list-abbrevs'. You can make changes most easily with `M-x edit-abbrevs'. The commonest abbreviations recognized in `LaTeX-mode' are for macro names that are awkward to type: the input `latex ' expands to `\LaTeX{} ', `tex ' to `\TeX{} ', and so on. Note particularly that the expansion here is to `\TeX{}', and *not* `\TeX\'! There are good reasons for this: * If you terminate macro names with `\' instead of with `{}', you have to remember to do that only where a space would really be permitted; in particular, you don't want the `\' before punctuation. You can use `{}' consistently in both cases. * If the `\' appears at the end of a line, and trailing spacesare subsequently stripped, you now have a new macro equivalent to `\^^M', which might have a different meaning. Although both `plain.tex' and `lplain.tex' make the two macros equivalent, that might not always be the case. You should never count on end-of-line blanks being preserved; some e-mail systems, and some editors, may delete them. Text filling and justification as commonly used in Emacs can also remove them. * In composite words, like `\TeX{}book', the braces keep the parts together for text fill operations, word counting, spell checking and so forth, while the form `\TeX book' will not. The form `{\TeX}' has the almost same advantages over `\TeX\' as `\TeX{}' does, but has one drawback: if you need to `\protect' it, then you must do so inside the braces. Use of a final empty brace pair therefore seems the best choice. By Emacs convention, word abbreviation mode is never turned on automatically; you must explicitly toggle it on a case-by-case basis by executing the command `M-x abbrev-mode'. If you always want it selected in `LaTeX-mode', add it to your `.emacs' file in a mode hook: (setq LaTeX-mode-hook '(lambda () (abbrev-mode 1) ) ) If you have other things to set in that mode hook, they should go on the lines immediately before or after the `(abbrev-mode 1)' line, since there can be only one mode hook for each editing mode.