# emacsmirror/auctex

### Subversion checkout URL

You can clone with HTTPS or Subversion.

Fetching contributors…

Cannot retrieve contributors at this time

8158 lines (6537 sloc) 370.971 kb

respectively. A prefix argument to these keys specifies how many errors to move forward or backward. You can visit an error also by clicking on its message. Press to quit the overview. -- User Option: TeX-error-overview-open-after-TeX-run When this boolean variable is non-nil, the error overview will be automatically opened after running TeX if there are errors or warnings to show. The error overview is opened in a new window of the current frame by default, but you can change this behavior by customizing the option 'TeX-error-overview-setup'. -- User Option: TeX-error-overview-setup Controls the frame setup of the error overview. The possible value is: 'separate-frame'; with a nil value the current frame is used instead. The parameters of the separate frame can be set with the 'TeX-error-overview-frame-parameters' option. If the display does not support multi frame, the current frame will be used regardless of the value of this variable. File: auctex.info, Node: Checking, Next: Control, Prev: Debugging, Up: Processing 4.4 Checking for problems ========================= Running TeX or LaTeX will only find regular errors in the document, not examples of bad style. Furthermore, description of the errors may often be confusing. The utilities 'lacheck' and 'chktex' can be used to find style errors, such as forgetting to escape the space after an abbreviation or using '...' instead of '\ldots' and other similar problems. You start 'lacheck' with 'C-c C-c Check ' and 'chktex' with 'C-c C-c ChkTeX '. The result will be a list of errors in the '*compilation*' buffer. You can go through the errors with 'C-x ' ('next-error', *note (emacs)Compilation::), which will move point to the location of the next error. Each of the two utilities will find some errors the other doesn't, but 'chktex' is more configurable, allowing you to create your own errors. You may need to install the programs before using them. You can get 'lacheck' from '' and 'chktex' from ''. File: auctex.info, Node: Control, Next: Cleaning, Prev: Checking, Up: Processing 4.5 Controlling the output ========================== A number of commands are available for controlling the output of an application running under AUCTeX -- Command: TeX-kill-job ('C-c C-k') Kill currently running external application. This may be either of TeX, LaTeX, previewer, BibTeX, etc. -- Command: TeX-recenter-output-buffer ('C-c C-l') Recenter the output buffer so that the bottom line is visible. -- Command: TeX-home-buffer ('C-c ^') Go to the 'master' file in the document associated with the current buffer, or if already there, to the file where the current process was started. File: auctex.info, Node: Cleaning, Next: Documentation, Prev: Control, Up: Processing 4.6 Cleaning intermediate and output files ========================================== -- Command: TeX-clean Remove generated intermediate files. In case a prefix argument is given, remove output files as well. Canonical access to the function is provided by the 'Clean' and 'Clean All' entries in 'TeX-command-list', invokable with 'C-c C-c' or the Command menu. The patterns governing which files to remove can be adapted separately for each AUCTeX mode by means of the variables 'plain-TeX-clean-intermediate-suffixes', 'plain-TeX-clean-output-suffixes', 'LaTeX-clean-intermediate-suffixes', 'LaTeX-clean-output-suffixes', 'docTeX-clean-intermediate-suffixes', 'docTeX-clean-output-suffixes', 'Texinfo-clean-intermediate-suffixes', 'Texinfo-clean-output-suffixes', 'ConTeXt-clean-intermediate-suffixes' and 'ConTeXt-clean-output-suffixes'. -- User Option: TeX-clean-confirm Control if deletion of intermediate and output files has to be confirmed before it is actually done. If non-nil, ask before deleting files. File: auctex.info, Node: Documentation, Prev: Cleaning, Up: Processing 4.7 Documentation about macros and packages =========================================== -- Command: TeX-doc ('C-c ?') Get documentation about macros, packages or TeX & Co. in general. The function will prompt for the name of a command or manual, providing a list of available keywords for completion. If point is on a command or word with available documentation, this will be suggested as default. In case no documentation could be found, a prompt for querying the 'texdoc' program is shown, should the latter be available. The command can be invoked by the key binding mentioned above as well as the 'Find Documentation...' entry in the mode menu. File: auctex.info, Node: Customization, Next: Appendices, Prev: Processing, Up: Top 5 Customization and Extension ***************************** * Menu: * Modes and Hooks:: Modes and Hooks * Multifile:: Multifile Documents * Parsing Files:: Automatic Parsing of TeX Files * Internationalization:: Language Support * Automatic:: Automatic Customization * Style Files:: Writing Your Own Style Support File: auctex.info, Node: Modes and Hooks, Next: Multifile, Up: Customization 5.1 Modes and Hooks =================== AUCTeX supports a wide variety of derivatives and extensions of TeX. Besides plain TeX those are LaTeX, AMS-TeX, ConTeXt, Texinfo and docTeX. For each of them there is a separate major mode in AUCTeX and each major mode runs 'text-mode-hook', 'TeX-mode-hook' as well as a hook special to the mode in this order. The following table provides an overview of the respective mode functions and hooks. Type Mode function Hook ------------------------------------------------------- Plain TeX 'plain-TeX-mode' 'plain-TeX-mode-hook' LaTeX 'LaTeX-mode' 'LaTeX-mode-hook' AMS-TeX 'ams-tex-mode' 'AmS-TeX-mode-hook' ConTeXt 'ConTeXt-mode' 'ConTeXt-mode-hook' Texinfo 'Texinfo-mode' 'Texinfo-mode-hook' DocTeX 'docTeX-mode' 'docTeX-mode-hook' If you need to make a customization via a hook which is only relevant for one of the modes listed above, put it into the respective mode hook, if it is relevant for any AUCTeX mode, add it to 'TeX-mode-hook' and if it is relevant for all text modes, append it to 'text-mode-hook'. File: auctex.info, Node: Multifile, Next: Parsing Files, Prev: Modes and Hooks, Up: Customization 5.2 Multifile Documents ======================= You may wish to spread a document over many files (as you are likely to do if there are multiple authors, or if you have not yet discovered the power of the outline commands (*note Outline::)). This can be done by having a "master" file in which you include the various files with the TeX macro '\input' or the LaTeX macro '\include'. These files may also include other files themselves. However, to format the document you must run the commands on the top level master file. When you, for example, ask AUCTeX to run a command on the master file, it has no way of knowing the name of the master file. By default, it will assume that the current file is the master file. If you insert the following in your '.emacs' file AUCTeX will use a more advanced algorithm. (setq-default TeX-master nil) ; Query for master file. If AUCTeX finds the line indicating the end of the header in a master file ('TeX-header-end'), it can figure out for itself that this is a master file. Otherwise, it will ask for the name of the master file associated with the buffer. To avoid asking you again, AUCTeX will automatically insert the name of the master file as a file variable (*note (emacs)File Variables::). You can also insert the file variable yourself, by putting the following text at the end of your files. %%% Local Variables: %%% TeX-master: "master" %%% End: You should always set this variable to the name of the top level document. If you always use the same name for your top level documents, you can set 'TeX-master' in your '.emacs' file. (setq-default TeX-master "master") ; All master files called "master". -- User Option: TeX-master The master file associated with the current buffer. If the file being edited is actually included from another file, then you can tell AUCTeX the name of the master file by setting this variable. If there are multiple levels of nesting, specify the top level file. If this variable is 'nil', AUCTeX will query you for the name. If the variable is 't', then AUCTeX will assume the file is a master file itself. If the variable is 'shared', then AUCTeX will query for the name, but will not change the file. -- User Option: TeX-one-master Regular expression matching ordinary TeX files. You should set this variable to match the name of all files, for which it is a good idea to append a 'TeX-master' file variable entry automatically. When AUCTeX adds the name of the master file as a file variable, it does not need to ask next time you edit the file. If you dislike AUCTeX automatically modifying your files, you can set this variable to '""'. By default, AUCTeX will modify any file with an extension of '.tex'. -- Command: TeX-master-file-ask ('C-c _') Query for the name of a master file and add the respective File Variables (*note (emacs)File Variables::) to the file for setting this variable permanently. AUCTeX will not ask for a master file when it encounters existing files. This function shall give you the possibility to insert the variable manually. AUCTeX keeps track of macros, environments, labels, and style files that are used in a given document. For this to work with multifile documents, AUCTeX has to have a place to put the information about the files in the document. This is done by having an 'auto' subdirectory placed in the directory where your document is located. Each time you save a file, AUCTeX will write information about the file into the 'auto' directory. When you load a file, AUCTeX will read the information in the 'auto' directory about the file you loaded _and the master file specified by 'TeX-master'_. Since the master file (perhaps indirectly) includes all other files in the document, AUCTeX will get information from all files in the document. This means that you will get from each file, for example, completion for all labels defined anywhere in the document. AUCTeX will create the 'auto' directory automatically if 'TeX-auto-save' is non-nil. Without it, the files in the document will not know anything about each other, except for the name of the master file. *Note Automatic Local::. -- Command: TeX-save-document ('C-c C-d') Save all buffers known to belong to the current document. -- User Option: TeX-save-query If non-nil, then query the user before saving each file with 'TeX-save-document'. File: auctex.info, Node: Parsing Files, Next: Internationalization, Prev: Multifile, Up: Customization 5.3 Automatic Parsing of TeX Files ================================== AUCTeX depends heavily on being able to extract information from the buffers by parsing them. Since parsing the buffer can be somewhat slow, the parsing is initially disabled. You are encouraged to enable them by adding the following lines to your '.emacs' file. (setq TeX-parse-self t) ; Enable parse on load. (setq TeX-auto-save t) ; Enable parse on save. The latter command will make AUCTeX store the parsed information in an 'auto' subdirectory in the directory each time the TeX files are stored, *note Automatic Local::. If AUCTeX finds the pre-parsed information when loading a file, it will not need to reparse the buffer. The information in the 'auto' directory is also useful for multifile documents, *note Multifile::, since it allows each file to access the parsed information from all the other files in the document. This is done by first reading the information from the master file, and then recursively the information from each file stored in the master file. The variables can also be done on a per file basis, by changing the file local variables. %%% Local Variables: %%% TeX-parse-self: t %%% TeX-auto-save: t %%% End: Even when you have disabled the automatic parsing, you can force the generation of style information by pressing 'C-c C-n'. This is often the best choice, as you will be able to decide when it is necessary to reparse the file. -- User Option: TeX-parse-self Parse file after loading it if no style hook is found for it. -- User Option: TeX-auto-save Automatically save style information when saving the buffer. -- Command: TeX-normal-mode ARG ('C-c C-n') Remove all information about this buffer, and apply the style hooks again. Save buffer first including style information. With optional argument, also reload the style hooks. When AUCTeX saves your buffer, it can optionally convert all tabs in your buffer into spaces. Tabs confuse AUCTeX's error message parsing and so should generally be avoided. However, tabs are significant in some environments, and so by default AUCTeX does not remove them. To convert tabs to spaces when saving a buffer, insert the following in your '.emacs' file: (setq TeX-auto-untabify t) -- User Option: TeX-auto-untabify Automatically remove all tabs from a file before saving it. Instead of disabling the parsing entirely, you can also speed it significantly up by limiting the information it will search for (and store) when parsing the buffer. You can do this by setting the default values for the buffer local variables 'TeX-auto-regexp-list' and 'TeX-auto-parse-length' in your '.emacs' file. ;; Only parse LaTeX class and package information. (setq-default TeX-auto-regexp-list 'LaTeX-auto-minimal-regexp-list) ;; The class and package information is usually near the beginning. (setq-default TeX-auto-parse-length 2000) This example will speed the parsing up significantly, but AUCTeX will no longer be able to provide completion for labels, macros, environments, or bibitems specified in the document, nor will it know what files belong to the document. These variables can also be specified on a per file basis, by changing the file local variables. %%% Local Variables: %%% TeX-auto-regexp-list: TeX-auto-full-regexp-list %%% TeX-auto-parse-length: 999999 %%% End: -- User Option: TeX-auto-regexp-list List of regular expressions used for parsing the current file. -- User Option: TeX-auto-parse-length Maximal length of TeX file that will be parsed. The pre-specified lists of regexps are defined below. You can use these before loading AUCTeX by quoting them, as in the example above. -- Constant: TeX-auto-empty-regexp-list Parse nothing -- Constant: LaTeX-auto-minimal-regexp-list Only parse LaTeX class and packages. -- Constant: LaTeX-auto-label-regexp-list Only parse LaTeX labels. -- Constant: LaTeX-auto-index-regexp-list Only parse LaTeX index and glossary entries. -- Constant: LaTeX-auto-class-regexp-list Only parse macros in LaTeX classes and packages. -- Constant: LaTeX-auto-pagestyle-regexp-list Only parse LaTeX pagestyles. -- Constant: LaTeX-auto-counter-regexp-list Only parse LaTeX counters. -- Constant: LaTeX-auto-length-regexp-list Only parse LaTeX lengths. -- Constant: LaTeX-auto-savebox-regexp-list Only parse LaTeX saveboxes. -- Constant: LaTeX-auto-regexp-list Parse common LaTeX commands. -- Constant: plain-TeX-auto-regexp-list Parse common plain TeX commands. -- Constant: TeX-auto-full-regexp-list Parse all TeX and LaTeX commands that AUCTeX can use. File: auctex.info, Node: Internationalization, Next: Automatic, Prev: Parsing Files, Up: Customization 5.4 Language Support ==================== TeX and Emacs are usable for European (Latin, Cyrillic, Greek) based languages. Some LaTeX and EmacsLisp packages are available for easy typesetting and editing documents in European languages. For CJK (Chinese, Japanese, and Korean) languages, Emacs or XEmacs with MULE (MULtilingual Enhancement to GNU Emacs) support is required. MULE is part of Emacs by default since Emacs 20. XEmacs has to be configured with the '--with-mule' option. Special versions of TeX are needed for CJK languages: CTeX and ChinaTeX for Chinese, ASCII pTeX and NTT jTeX for Japanese, HLaTeX and kTeX for Korean. The CJK-LaTeX package is required for supporting multiple CJK scripts within a single document. Note that Unicode is not fully supported in Emacs 21 and XEmacs 21. CJK characters are not usable. Please use the MULE-UCS EmacsLisp package or Emacs 22 (not released yet) if you need CJK. * Menu: * European:: Using AUCTeX with European Languages * Japanese:: Using AUCTeX with Japanese File: auctex.info, Node: European, Next: Japanese, Up: Internationalization 5.4.1 Using AUCTeX with European Languages ------------------------------------------ 5.4.1.1 Typing and Displaying Non-ASCII Characters .................................................. First you will need a way to write non-ASCII characters. You can either use macros, or teach TeX about the ISO character sets. I prefer the latter, it has the advantage that the usual standard emacs word movement and case change commands will work. With LaTeX2e, just add '\usepackage[latin1]{inputenc}'. Other languages than Western European ones will probably have other encoding needs. To be able to display non-ASCII characters you will need an appropriate font and a version of GNU Emacs capable of displaying 8-bit characters (e.g. Emacs 21). The manner in which this is supported differs between Emacsen, so you need to take a look at your respective documentation. A compromise is to use an European character set when editing the file, and convert to TeX macros when reading and writing the files. 'iso-cvt.el' Much like 'iso-tex.el' but is bundled with Emacs 19.23 and later. 'x-compose.el' Similar package bundled with new versions of XEmacs. 'X-Symbol' a much more complete package for both Emacs and XEmacs that can also handle a lot of mathematical characters and input methods. 5.4.1.2 Style Files for Different Languages ........................................... AUCTeX supports style files for several languages. Each style file may modify AUCTeX to better support the language, and will run a language specific hook that will allow you to for example change ispell dictionary, or run code to change the keyboard remapping. The following will for example choose a Danish dictionary for documents including '\usepackage[danish]{babel}'. This requires parsing to be enabled, *note Parsing Files::. (add-hook 'TeX-language-dk-hook (lambda () (ispell-change-dictionary "danish"))) The following style files are recognized: 'bulgarian' Runs style hook 'TeX-language-bg-hook'. Gives '"' word syntax, makes the <"> key insert a literal '"'. Typing <"> twice will insert insert '"' or '"'' depending on context. Typing <-> twice will insert '"=', three times '--'. 'czech' Runs style hook 'TeX-language-cz-hook'. Pressing <"> will insert '\uv{' and '}' depending on context. 'danish' Runs style hook 'TeX-language-dk-hook'. Pressing <"> will insert '"' and '"'' depending on context. Typing <-> twice will insert '"=', i.e. a hyphen string allowing hyphenation in the composing words. 'dutch' Runs style hook 'TeX-language-nl-hook'. 'english' Runs style hook 'TeX-language-en-hook'. 'frenchb' 'francais' Runs style hook 'TeX-language-fr-hook'. Pressing <"> will insert '\\og' and '\\fg' depending on context. Note that the language name for customizing 'TeX-quote-language-alist' is 'french'. 'german' 'ngerman' Runs style hook 'TeX-language-de-hook'. Gives '"' word syntax, makes the <"> key insert a literal '"'. Pressing the key twice will give you opening or closing German quotes ('"' or '"''). Typing <-> twice will insert '"=', three times '--'. 'icelandic' Runs style hook 'TeX-language-is-hook'. Gives '"' word syntax, makes the <"> key insert a literal '"'. Typing <"> twice will insert insert '"' or '"'' depending on context. Typing <-> twice will insert '"=', three times '--'. 'italian' Runs style hook 'TeX-language-it-hook'. Pressing <"> will insert '"<' and '">' depending on context. 'polish' Runs style hook 'TeX-language-pl-hook'. Gives '"' word syntax and makes the <"> key insert a literal '"'. Pressing <"> twice will insert '"`' or '"'' depending on context. 'polski' Runs style hook 'TeX-language-pl-hook'. Makes the <"> key insert a literal '"'. Pressing <"> twice will insert ',,' or '''' depending on context. 'slovak' Runs style hook 'TeX-language-sk-hook'. Pressing <"> will insert '\uv{' and '}' depending on context. 'swedish' Runs style hook 'TeX-language-sv-hook'. Pressing <"> will insert ''''. Typing <-> twice will insert '"=', three times '--'. Replacement of language-specific hyphen strings like '"=' with dashes does not require to type <-> three times in a row. You can put point after the hypen string anytime and trigger the replacement by typing <->. In case you are not satisfied with the suggested behavior of quote and hyphen insertion you can change it by customizing the variables 'TeX-quote-language-alist' and 'LaTeX-babel-hyphen-language-alist' respectively. -- User Option: TeX-quote-language-alist Used for overriding the default language-specific quote insertion behavior. This is an alist where each element is a list consisting of four items. The first item is the name of the language in concern as a string. See the list of supported languages above. The second item is the opening quotation mark. The third item is the closing quotation mark. Opening and closing quotation marks can be specified directly as strings or as functions returning a string. The fourth item is a boolean controlling quote insertion. It should be non-nil if if the special quotes should only be used after inserting a literal '"' character first, i.e. on second key press. -- User Option: LaTeX-babel-hyphen-language-alist Used for overriding the behavior of hyphen insertion for specific languages. Every element in this alist is a list of three items. The first item should specify the affected language as a string. The second item denotes the hyphen string to be used as a string. The third item, a boolean, controls the behavior of hyphen insertion and should be non-nil if the special hyphen should be inserted after inserting a literal '-' character, i.e. on second key press. The defaults of hyphen insertion are defined by the variables 'LaTeX-babel-hyphen' and 'LaTeX-babel-hyphen-after-hyphen' respectively. -- User Option: LaTeX-babel-hyphen String to be used when typing <->. This usually is a hyphen alternative or hyphenation aid provided by 'babel' and the related language style files, like '"=', '"~' or '"-'. Set it to an empty string or nil in order to disable language-specific hyphen insertion. -- User Option: LaTeX-babel-hyphen-after-hyphen Control insertion of hyphen strings. If non-nil insert normal hyphen on first key press and swap it with the language-specific hyphen string specified in the variable 'LaTeX-babel-hyphen' on second key press. If nil do it the other way round. File: auctex.info, Node: Japanese, Prev: European, Up: Internationalization 5.4.2 Using AUCTeX with Japanese TeX ------------------------------------ To write Japanese text with AUCTeX, you need to have versions of TeX and Emacs that support Japanese. There exist at least two variants of TeX for Japanese text (NTT jTeX and ASCII pTeX). AUCTeX can be used with MULE (MULtilingual Enhancement to GNU Emacs) supported Emacsen. To use the Japanese TeX variants, simply activate 'japanese-plain-tex-mode' or 'japanese-latex-mode' and everything should work. If not, send mail to Masayuki Ataka '', who kindly donated the code for supporting Japanese in AUCTeX. None of the primary AUCTeX maintainers understand Japanese, so they cannot help you. If you usually use AUCTeX in Japanese, setting the following variables is useful. -- User Option: TeX-default-mode Mode to enter for a new file when it cannott be determined whether the file is plain TeX or LaTeX or what. If you want to enter Japanese LaTeX mode whenever this may happen, set the variable like this: (setq TeX-default-mode 'japanese-latex-mode) -- User Option: japanese-TeX-command-default The default command for 'TeX-command' in Japanese TeX mode. The default value is '"pTeX"'. -- User Option: japanese-LaTeX-command-default The default command for 'TeX-command' in Japanese LaTeX mode. The default value is '"LaTeX"'. -- User Option: japanese-LaTeX-default-style The default style/class when creating a new Japanese LaTeX document. The default value is '"jarticle"'. See 'tex-jp.el' for more information. File: auctex.info, Node: Automatic, Next: Style Files, Prev: Internationalization, Up: Customization 5.5 Automatic Customization =========================== Since AUCTeX is so highly customizable, it makes sense that it is able to customize itself. The automatic customization consists of scanning TeX files and extracting symbols, environments, and things like that. The automatic customization is done on three different levels. The global level is the level shared by all users at your site, and consists of scanning the standard TeX style files, and any extra styles added locally for all users on the site. The private level deals with those style files you have written for your own use, and use in different documents. You may have a '~/lib/TeX/' directory where you store useful style files for your own use. The local level is for a specific directory, and deals with writing customization for the files for your normal TeX documents. If compared with the environment variable 'TEXINPUTS', the global level corresponds to the directories built into TeX. The private level corresponds to the directories you add yourself, except for '.', which is the local level. * Menu: * Automatic Global:: Automatic Customization for the Site * Automatic Private:: Automatic Customization for a User * Automatic Local:: Automatic Customization for a Directory By default AUCTeX will search for customization files in all the global, private, and local style directories, but you can also set the path directly. This is useful if you for example want to add another