This is Info file ../info/reftex, produced by Makeinfo version 1.68 from the input file reftex.texi. INFO-DIR-SECTION Editors START-INFO-DIR-ENTRY * reftex: (reftex). Support for LaTeX labels, references, and citations with Emacs. END-INFO-DIR-ENTRY This file documents RefTeX, a package to do labels, references and citations for LaTeX documents with Emacs. This is edition 3.43 of the RefTeX User Manual for RefTeX 3.43 Copyright (c) 1997, 1998 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 derive 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 Free Software Foundation.  File: reftex, Node: Faces, Next: AUCTeX, Prev: Keybindings, Up: Top Faces ===== RefTeX uses faces when available to structure the selection and table of contents buffers. It does not create its own faces, but uses the ones defined in `font-lock.el'. Therefore, RefTeX will use faces only when `font-lock' is loaded. This seems to be reasonable because people who like faces will very likely have it loaded. If you wish to turn off fontification or change the involved faces, see *Note Options (Fontification)::.  File: reftex, Node: Multifile Documents, Next: Language Support, Prev: AUCTeX, Up: Top Multifile Documents =================== The following is relevant when working with documents spread over many files: * RefTeX has full support for multifile documents. You can edit parts of several (multifile) documents at the same time without conflicts. RefTeX provides functions to run `grep', `search' and `query-replace' on all files which are part of a multifile document. * All files belonging to a multifile document should have a File Variable (`TeX-master' for AUCTeX or `tex-main-file' for the standard Emacs LaTeX mode) set to the name of the master file. See the documentation of your (La)TeX mode and *Note File Variables: (emacs)File Variables. * The context of a label definition must be found in the same file as the label itself in order to be processed correctly by RefTeX. The only exception is that section labels referring to a section statement outside the current file can still use that section title as context.  File: reftex, Node: Language Support, Next: Finding Files, Prev: Multifile Documents, Up: Top Language Support ================ Some parts of RefTeX are language dependent. The default settings work well for English. If you are writing in a different language, the following hints may be useful: * The mechanism to derive a label from context includes the abbreviation of words and omission of unimportant words. These mechanisms may have to be changed for other languages. See the variables `reftex-derive-label-parameters' and `reftex-abbrev-parameters'. * Also, when a label is derived from context, RefTeX clears the context string from non-ASCII characters in order to make a legal label. If you are using a special version of TeX which allows extended characters *in labels*, then you should look at the variables `reftex-translate-to-ascii-function' and `reftex-label-illegal-re'. * When a label is referenced, RefTeX looks at the word before point to guess which label type is required. These *magic words* are different in every language. For an example of how to add magic words, see *Note Adding Magic Words::.  File: reftex, Node: Finding Files, Next: Optimizations, Prev: Language Support, Up: Top Finding Files ============= In order to find files included in a document via `\input' or `\include', RefTeX searches all directories specified in the environment variable `TEXINPUTS'. Similarly, it will search the path specified in the variables `BIBINPUTS' and `TEXBIB' for BibTeX database files. When searching, RefTeX will also expand recursive path definitions (directories ending in `//' or `!!'). But it will only search and expand directories *explicitly* given in these variables. This may cause problems under the following circumstances: * Most TeX system have a default search path for both TeX files and BibTeX files which is defined in some setup file. Usually this default path is for system files which RefTeX does not need to see. But if your document needs TeX files or BibTeX database files in a directory only given in the default search path, RefTeX will fail to find them. * Some TeX systems do not use environment variables at all in order to specify the search path. Both default and user search path are then defined in setup files. There are three ways to solve this problem: * Specify all relevant directories explicitly in the environment variables. If for some reason you don't want to mess with the default variables `TEXINPUTS' and `BIBINPUTS', define your own variables and configure RefTeX to use them instead: (setq reftex-texpath-environment-variables '("MYTEXINPUTS")) (setq reftex-bibpath-environment-variables '("MYBIBINPUTS")) * Specify the full search path directly in RefTeX's variables. (setq reftex-texpath-environment-variables '("./inp:/home/cd/tex//:/usr/local/tex//")) (setq reftex-bibpath-environment-variables '("/home/cd/tex/lit/")) * Some TeX systems provide stand-alone programs to do the file search just like TeX and BibTeX. E.g. Thomas Esser's `teTeX' uses the `kpathsearch' library which provides the command `kpsewhich' to search for files. RefTeX can be configured to use this program. Note that the exact syntax of the `kpsewhich' command depends upon the version of that program. (setq reftex-use-external-file-finders t) (setq reftex-external-file-finders '(("tex" "kpsewhich -format=.tex %f") ("bib" "kpsewhich -format=.bib %f")))  File: reftex, Node: Optimizations, Next: Problems and Work-Arounds, Prev: Finding Files, Up: Top Optimizations ============= Implementing the principle of least surprises, the default settings of RefTeX ensure a safe ride for beginners and casual users. However, when using RefTeX for a large project and/or on a small computer, there are ways to improve speed or memory usage. * Removing Lookup Buffers RefTeX will load other parts of a multifile document as well as BibTeX database files for lookup purposes. These buffers are kept, so that subsequent use of the same files is fast. If you can't afford keeping these buffers around, and if you can live with a speed penalty, try (setq reftex-keep-temporary-buffers nil) * Partial Document Scans A `C-u' prefix on the major RefTeX commands `reftex-label' (`C-u C-c ('), `reftex-reference' (`C-u C-c )'), `reftex-citation' (`C-u C-c ['), `reftex-toc' (`C-u C-c ='), and `reftex-view-crossref' (`C-u C-c &') initiates re-parsing of the entire document in order to update the parsing information. For a large document this can be unnecessary, in particular if only one file has changed. RefTeX can be configured to do partial scans instead of full ones. `C-u' re-parsing then does apply only to the current buffer and files included from it. Likewise, the `r' key in both the label selection buffer and the table-of-contents buffer will only prompt scanning of the file in which the label or section macro near the cursor was defined. Re-parsing of the entire document is still available by using `C-u C-u' as a prefix, or the capital `R' key in the menus. To use this feature, try (setq reftex-enable-partial-scans t) * Saving Parser Information Even with partial scans enabled, RefTeX still has to make one full scan, when you start working with a document. To avoid this, parsing information can be stored in a file. The file `MASTER.rel' is used for storing information about a document with master file `MASTER.tex'. It is written automatically when you kill a buffer in `reftex-mode' or when you exit Emacs. The information is restored when you begin working with a document in a new editing session. To use this feature, put into `.emacs': (setq reftex-save-parse-info t) * Automatic Document Scans At rare occasions, RefTeX will automatically rescan a part of the document. If this gets into your way, it can be turned off with (setq reftex-allow-automatic-rescan nil) RefTeX will then occasionally annotate new labels in the selection buffer, saying that their position in the label list in uncertain. A manual document scan will fix this. * Multiple Selection Buffers Normally, the selection buffer `*RefTeX Select*' is re-created for every selection process. In documents with very many labels this can take several seconds. RefTeX provides an option to create a separate selection buffer for each label type and to keep this buffer from one selection to the next. These buffers are updated automatically only when a new label has been added in the buffers category with `reftex-label'. Updating the buffer takes as long as recreating it - so the time saving is limited to cases where no new labels of that category have been added. To turn on this feature, use (setq reftex-use-multiple-selection-buffers t) You can also inhibit the automatic updating entirely. Then the selection buffer will always pop up very fast, but may not contain the most recently defined labels. You can always update the buffer by hand, with the `g' key. To get this behavior, use instead (setq reftex-use-multiple-selection-buffers t reftex-auto-update-selection-buffers nil) As a summary, here are the settings I recommend for heavy use of RefTeX with large documents: (setq reftex-enable-partial-scans t reftex-save-parse-info t reftex-use-multiple-selection-buffers t)  File: reftex, Node: AUCTeX, Next: Multifile Documents, Prev: Faces, Up: Top AUC TeX ======= AUCTeX is without doubt the best major mode for editing TeX and LaTeX files with Emacs. AUCTeX is part of the XEmacs distribution. It is also available from the AUCTeX distribution site (http://www.sunsite.auc.dk/auctex/). * Menu: * AUCTeX-RefTeX Interface:: How both packages work together * Style Files:: AUCTeX's style files can support RefTeX * Bib-Cite:: Hypertext reading of a document  File: reftex, Node: AUCTeX-RefTeX Interface, Next: Style Files, Up: AUCTeX The AUCTeX-RefTeX Interface --------------------------- RefTeX contains code to interface with AUCTeX. When this interface is turned on, both packages will interact closely. Instead of using RefTeX's commands directly, you can then also use them indirectly as part of the AUCTeX environment(1). The interface is turned on with (setq reftex-plug-into-AUCTeX t) If you need finer control about which parts of the interface are used and which not, customize this variable with `M-x customize-variable reftex-plug-into-AUCTeX '. The following list describes the individual parts of the interface. * AUCTeX calls `reftex-label' to insert labels When a new section is created with `C-c C-s', or a new environment is inserted with `C-c C-e', AUCTeX normally prompts for a label to go with it. With the interface, `reftex-label' is called instead. For example, if you type `C-c C-e equation ', AUCTeX and RefTeX will insert \begin{equation} \label{eq:1} \end{equation} without further prompts. Similarly, when you type `C-c C-s section ', RefTeX will offer its default label which is derived from the section title. * AUCTeX tells RefTeX about new sections When creating a new section with `C-c C-s', RefTeX will not have to rescan the buffer in order to see it. * RefTeX supplies macro arguments When you insert a macro interactively with `C-c ', AUCTeX normally prompts for macro arguments. Internally, it uses the functions `TeX-arg-label' and `TeX-arg-cite' to prompt for arguments which are labels and citation keys. The interface takes over these functions(2) and supplies the macro arguments with RefTeX's mechanisms. For example, when you type `C-c ref ', RefTeX will supply its label selection process (*note Referencing Labels::.). * RefTeX tells AUCTeX about new labels and citations keys RefTeX will add all newly created labels to AUCTeX's completion list. ---------- Footnotes ---------- (1) RefTeX 3.23 and AUCTeX 9.9c will be needed for all of this to work. Parts of it work also with earlier versions. (2) `fset' is used to do this, which is not reversible. However, RefTeX implements the old functionality when you later decide to turn off the interface.  File: reftex, Node: Style Files, Next: Bib-Cite, Prev: AUCTeX-RefTeX Interface, Up: AUCTeX Style Files ----------- Style files are Emacs Lisp files which are evaluated by AUCTeX in association with the `\documentclass' and `\usepackage' commands of a document. Support for RefTeX in such a style file is useful when the LaTeX style defines macros or environments connected with labels and citations. Some style files (e.g. `amsmath.el' or `natbib.el') distributed with AUCTeX already support RefTeX in this way. Before calling a RefTeX function, the style hook should always test for the availability of the function, so that the style file will also work for people who do not use RefTeX. Additions made with style files in the way described below remain local to the current document. For example, if one package uses AMSTeX, the style file will make RefTeX switch over to `\eqref', but this will not affect other documents. A style hook may contain calls to `reftex-add-label-environments'(1) which defines additions to `reftex-label-alist'. The argument taken by this function must have the same format as `reftex-label-alist'. The `amsmath.el' style file of AUCTeX for example contains the following: (TeX-add-style-hook "amsmath" (lambda () (if (fboundp 'reftex-add-label-environments) (reftex-add-label-environments '(AMSTeX))))) while a package `myprop' defining a `proposition' environment with `\newtheorem' might use (TeX-add-style-hook "myprop" (lambda () (LaTeX-add-environments '("proposition" LaTeX-env-label)) (if (fboundp 'reftex-add-label-environments) (reftex-add-label-environments '(("proposition" ?p "prop:" "~\\ref{%s}" t ("Proposition" "Prop."))))))) Similarly, a style hook may contain a call to `reftex-set-cite-format' to set the citation format. The style file `natbib.el' for the Natbib citation style does switch RefTeX's citation format like this: (TeX-add-style-hook "natbib" (lambda () (if (fboundp 'reftex-set-cite-format) (reftex-set-cite-format 'natbib)))) Finally, the hook may contain a call to `reftex-add-section-levels' to define additional section statements. For example, the FoilTeX class has just two headers, `\foilhead' and `\rotatefoilhead'. Here is a style file `foils.el' that will inform RefTeX about these: (TeX-add-style-hook "foils" (lambda () (if (fboundp 'reftex-add-section-levels) (reftex-add-section-levels '(("foilhead" . 3) ("rotatefoilhead" . 3)))))) ---------- Footnotes ---------- (1) This used to be the function `reftex-add-to-label-alist' which is still available as an alias for compatibility.  File: reftex, Node: Bib-Cite, Prev: Style Files, Up: AUCTeX Bib-Cite -------- Once you have written a document with labels, references and citations, it can be nice to read it like a hypertext document. RefTeX has some support for that: `reftex-view-crossref' (bound to `C-c &'), `reftex-mouse-view-crossref' (bound to `S-mouse-2'), and `reftex-search-document'. A somewhat fancier interface with mouse highlighting is provided (among other things) by Peter S. Galbraith's `bib-cite.el'. There is some overlap in the functionalities of Bib-cite and RefTeX. Bib-cite.el comes bundled with AUCTeX. Bib-cite version 3.06 and later can be configured so that bib-cite's mouse functions use RefTeX for displaying references and citations. This can be useful in particular when working with the LaTeX `xr' package or with an explicit `thebibliography' environment (rather than BibTeX). Bib-cite cannot handle those, but RefTeX does. To make use of this feature, try (setq bib-cite-use-reftex-view-crossref t)  File: reftex, Node: Problems and Work-Arounds, Next: Imprint, Prev: Optimizations, Up: Top Problems and Work-arounds ========================= * LaTeX commands `\input', `\include', `\bibliography' and `\section' (etc.) statements have to be first on a line (except for white space). * Command abbreviations Some people define abbreviations for environments, like `\be' for `\begin{equation}', and `\ee' for `\end{equation}'. RefTeX cannot be configured to see these--you will have to used the full `\begin' and `\end' statements. * Commented regions RefTeX sees also labels in regions commented out and will refuse to make duplicates of such labels. This is considered to be a feature. * Wrong section numbers When using partial scans (`reftex-enable-partial-scans'), the section numbers in the table of contents may eventually become wrong. A full scan will fix this. * Local settings The label environment definitions in `reftex-label-alist' are global and apply to all documents. If you need to make definitions local to a document, because they would interfere with settings in other documents, you should use AUCTeX and set up style files with calls to `reftex-add-label-environments', `reftex-set-cite-format', and `reftex-add-section-levels'. Settings made with these functions remain local to the current document. *Note AUCTeX::, for more information. * Funny display in selection buffer When using packages which make the buffer representation of a file different from its disk representation (e.g. x-symbol, isotex, iso-cvt) you may find that RefTeX's parsing information sometimes reflects the disk state of a file. This happens only in *unvisited* parts of a multifile document, because RefTeX visits these files literally for speed reasons. Then both short context and section headings may look different from what you usually see on your screen. In rare cases `reftex-toc' may have problems to jump to an affected section heading. There are three possible ways to deal with this: - `(setq reftex-keep-temporary-buffers t)' This implies that RefTeX will load all parts of a multifile document into Emacs (i.e. there won't be any temporary buffers). - `(setq reftex-initialize-temporary-buffers t)' This means full initialization of temporary buffers. It involves a penalty when the same unvisited file is used for lookup often. - Set `reftex-initialize-temporary-buffers' to a list of hook functions doing a minimal initialization. See also the variable `reftex-refontify-context'. * Labels as arguments to \begin Some packages use an additional argument to a `\begin' macro to specify a label. E.g. Lamport's `pf.sty' uses both \step{LABEL}{CLAIM} and \begin{step+}{LABEL} CLAIM \end{step+} We need to trick RefTeX into swallowing this: ;; Configuration for Lamport's pf.sty (setq reftex-label-alist '(("\\step{*}{}" ?p "st:" "~\\stepref{%s}" 2 ("Step" "St.")) ("\\begin{step+}{*}" ?p "st:" "~\\stepref{%s}" 1000))) The first line is just a normal configuration for a macro. For the `step+' environment we actually tell RefTeX to look for the *macro* `\begin{step+}' and interpret the *first* argument (which really is a second argument to the macro `\begin') as a label of type `?p'. Argument count for this macro starts only after the `{step+}', also when specifying how to get context. * Idle timers in XEmacs In XEmacs, idle timer restart does not work reliably after fast keystrokes. Therefore RefTeX currently uses the post command hook to start the timer used for automatic crossref information. When this bug gets fixed, a real idle timer can be requested with (setq reftex-use-itimer-in-xemacs t) * Viper mode With Viper mode prior to Vipers version 3.01, you need to protect RefTeX's keymaps with (viper-harness-minor-mode "reftex")  File: reftex, Node: Imprint, Next: Commands, Prev: Problems and Work-Arounds, Up: Top Imprint ======= RefTeX was written by Carsten Dominik , with contributions by Stephen Eglen. RefTeX is currently maintained by Carsten Dominik If you have questions about RefTeX, there are several Usenet groups which have competent readers: `comp.emacs', `gnu.emacs.help', `comp.emacs.xemacs', `comp.text.tex'. You can also write directly to the maintainer. If you find a bug in RefTeX or its documentation, or if you want to contribute code or ideas, please contact the maintainer (mailto:dominik@strw.leidenuniv.nl). Remember to provide all necessary information such as version numbers of Emacs and RefTeX, and the relevant part of your configuration in `.emacs'. When reporting a bug which throws an exception, please include a backtrace if you know how to produce one. RefTeX is bundled and preinstalled with Emacs since version 20.2. It was also bundled and preinstalled with XEmacs 19.16-20.x. XEmacs 21.x users want to install the corresponding plugin package which is available from the XEmacs `ftp' site. See the XEmacs 21.x documentation on package installation for details. Users of earlier Emacs distributions (including Emacs 19) can get a RefTeX distribution from the maintainers webpage (http://www.strw.leidenuniv.nl/~dominik/Tools/). Thanks to the people on the Net who have used RefTeX and helped developing it with their reports. In particular thanks to Fran Burstall, Alastair Burt, Soren Dayton, Stephen Eglen, Karl Eichwalder, Peter Galbraith, Kai Grossjohann, Dieter Kraft, Adrian Lanz, Rory Molinari, Laurent Mugnier, Sudeep Kumar Palat, Daniel Polani, Robin Socha, Richard Stanton, Allan Strand, Jan Vroonhof, Christoph Wedler, Alan Williams. The `view-crossref' feature was inspired by Peter Galbraith's `bib-cite.el'. Finally thanks to Uwe Bolick who first got me (some years ago) into supporting LaTeX labels and references with an editor (which was MicroEmacs at the time).  File: reftex, Node: Commands, Next: Options, Prev: Imprint, Up: Top Commands ******** Here is a summary of RefTeX's commands. All commands are available from the `Ref' menu. For keybindings, *note Keybindings::.. - Command: reftex-toc Show the table of contents for the current document. When called with one ore two `C-u' prefixes, rescan the document first. - Command: reftex-label Insert a unique label. With one or two `C-u' prefixes, enforce document rescan first. - Command: reftex-reference Start a selection process to select a label, and insert a reference to it. With one or two `C-u' prefixes, enforce document rescan first. - Command: reftex-citation Make a citation using BibTeX database files. After prompting for a regular expression, scans the buffers with BibTeX entries (taken from the `\bibliography' command or a `thebibliography' environment) and offers the matching entries for selection. The selected entry is formated according to `reftex-cite-format' and inserted into the buffer. When called with one or two `C-u' prefixes, first rescans the document. When called with a numeric prefix, make that many citations. When called with point inside the braces of a `\cite' command, it will add another key, ignoring the value of `reftex-cite-format'. The regular expression uses an expanded syntax: `&&' is interpreted as `and'. Thus, `aaaa&&bbb' matches entries which contain both `aaaa' and `bbb'. While entering the regexp, completion on knows citation keys is possible. `=' is a good regular expression to match all entries in all files. - Command: reftex-view-crossref View cross reference of macro at point. Point must be on the KEY argument. Works with the macros `\label', `\ref', `\cite', `\bibitem', `\index' and many derivatives of these. Where it makes sense, subsequent calls show additional locations. See also the variable `reftex-view-crossref-extra' and the command `reftex-view-crossref-from-bibtex'. With one or two `C-u' prefixes, enforce rescanning of the document. With argument 2, select the window showing the cross reference. - Command: reftex-view-crossref-from-bibtex View location in a LaTeX document which cites the BibTeX entry at point. Since BibTeX files can be used by many LaTeX documents, this function promps upon first use for a buffer in RefTeX mode. To reset this link to a document, call the function with with a prefix arg. Calling this function several times find successive citation locations. - Command: reftex-create-tags-file Create TAGS file by running `etags' on the current document. The TAGS file is also immediately visited with `visit-tags-table'. - Command: reftex-grep-document Run grep query through all files related to this document. With prefix arg, force to rescan document. No active TAGS table is required. - Command: reftex-search-document Regexp search through all files of the current document. Starts always in the master file. Stops when a match is found. No active TAGS table is required. - Command: reftex-query-replace-document Run a query-replace-regexp of FROM with TO over the entire document. With prefix arg, replace only word-delimited matches. No active TAGS table is required. - Command: reftex-change-label Query replace FROM with TO in all `\label' and `\ref' commands. Works on the entire multifile document. No active TAGS table is required. - Command: reftex-renumber-simple-labels Renumber all simple labels in the document to make them sequentially. Simple labels are the ones created by RefTeX, consisting only of the prefix and a number. After the command completes, all these labels will have sequential numbers throughout the document. Any references to the labels will be changed as well. For this, RefTeX looks at the arguments of any macros which either start or end with the string `ref'. This command should be used with care, in particular in multifile documents. You should not use it if another document refers to this one with the `xr' package. - Command: reftex-find-duplicate-labels Produce a list of all duplicate labels in the document. - Command: reftex-customize Run the customize browser on the RefTeX group. - Command: reftex-show-commentary Show the commentary section from `reftex.el'. - Command: reftex-info Run info on the top RefTeX node. - Command: reftex-parse-document Parse the entire document in order to update the parsing information. - Command: reftex-reset-mode Enforce rebuilding of several internal lists and variables. Also removes the parse file associated with the current document.  File: reftex, Node: Options, Next: Keymaps and Hooks, Prev: Commands, Up: Top Options, Keymaps, Hooks *********************** Here is a complete list of RefTeX's configuration variables. All variables have customize support--so if you are not familiar with Emacs Lisp (and even if you are) you might find it more comfortable to use `customize' to look at and change these variables. `M-x reftex-customize' will get you there. * Menu: * Options (Table of Contents):: * Options (Defining Label Environments):: * Options (Creating Labels):: * Options (Referencing Labels):: * Options (Creating Citations):: * Options (Viewing Cross-References):: * Options (Finding Files):: * Options (Optimizations):: * Options (Fontification):: * Options (Misc)::  File: reftex, Node: Options (Table of Contents), Next: Options (Defining Label Environments), Up: Options Table of Contents ================= - User Option: reftex-toc-keep-other-windows Non-`nil' means, split the selected window to display the `*toc*' buffer. This helps to keep the window configuration, but makes the *toc* small. When `nil', all other windows except the selected one will be deleted, so that the `*toc*' window fills half the frame. - User Option: reftex-toc-include-labels Non-`nil' means, include labels in `*toc*' buffer. This flag can be toggled from within the `*toc*' buffer with the `l' key. - User Option: reftex-toc-include-context Non-`nil' means, include context with labels in the `*toc*' buffer. Context will only be shown if the labels are visible as well. This flag can be toggled from within the `*toc*' buffer with the `c' key. - User Option: reftex-toc-include-file-boundaries Non-`nil' means, include file boundaries in `*toc*' buffer. This flag can be toggled from within the `*toc*' buffer with the `i' key. - User Option: reftex-toc-follow-mode Non-`nil' means, point in `*toc*' buffer (the table-of-contents buffer) will cause other window to follow. The other window will show the corresponding part of the document. This flag can be toggled from within the `*toc*' buffer with the `f' key. - Normal Hook: reftex-toc-mode-hook Normal hook which is run when a `*toc*' buffer is created. - Keymap: reftex-toc-map The keymap which is active in the `*toc*' buffer. (*note Table of Contents::.).  File: reftex, Node: Options (Defining Label Environments), Next: Options (Creating Labels), Prev: Options (Table of Contents), Up: Options Defining Label Environments =========================== - User Option: reftex-default-label-alist-entries Default label alist specifications. It is a list of symbols with associations in the constant `reftex-label-alist-builtin'. `LaTeX' should always be the last entry. - User Option: reftex-label-alist Set this variable to define additions and changes to the defaults in `reftex-default-label-alist-entries'. The only things you *must not* change is that `?s' is the type indicator for section labels, and for the `any' label type. These are hard-coded at other places in the code. The value of the variable must be a list of items. Each item is a list itself and has the following structure: (ENV-OR-MACRO TYPE-KEY LABEL-PREFIX REFERENCE-FORMAT CONTEXT-METHOD (MAGIC-WORD ... )) Each list entry describes either an environment carrying a counter for use with `\label' and `\ref', or a LaTeX macro defining a label as (or inside) one of its arguments. The elements of each list entry are: ENV-OR-MACRO Name of the environment (like `table') or macro (like `\myfig'). For macros, indicate the arguments, as in `\myfig[]{}{}{*}{}'. Use square brackets for optional arguments, a star to mark the label argument, if any. The macro does not have to have a label argument--you could also use `\label{...}' inside one of its arguments. Special names: `section' for section labels, `any' to define a group which contains all labels. This may also be `nil' if the entry is only meant to change some settings associated with the type indicator character (see below). TYPE-KEY Type indicator character, like `?t', must be a printable ASCII character. The type indicator is a single character which defines a label type. Any label inside the environment or macro is assumed to belong to this type. The same character may occur several times in this list, to cover cases in which different environments carry the same label type (like `equation' and `eqnarray'). If the type indicator is `nil' and the macro has a label argument `{*}', the macro defines neutral labels just like `\label'. In this case the reminder of this entry is ignored. LABEL-PREFIX Label prefix string, like `tab:'. The prefix is a short string used as the start of a label. It may be the empty string. The prefix may contain the following `%' escapes: %f Current file name, directory and extension stripped. %F Current file name relative to master file directory. %u User login name, on systems which support this. Example: In a file `intro.tex', `eq:%f:' will become `eq:intro:'. REFERENCE-FORMAT Format string for reference insert in buffer. `%s' will be replaced by the label. When the format starts with `~', this `~' will only be inserted when the character before point is *not* a whitespace. CONTEXT-METHOD Indication on how to find the short context. - If `nil', use the text following the `\label{...}' macro. - If `t', use - the section heading for section labels. - text following the `\begin{...}' statement of environments (not a good choice for environments like eqnarray or enumerate, where one has several labels in a single environment). - text after the macro name (starting with the first arg) for macros. - If an integer, use the nth argument of the macro. As a special case, 1000 means to get text after the last macro argument. - If a string, use as regexp to search *backward* from the label. Context is then the text following the end of the match. E.g. putting this to `\\caption[[{]' will use the caption in a figure or table environment. `\\begin{eqnarray}\|\\\\' works for eqnarrays. - If any of `caption', `item', `eqnarray-like', `alignat-like', this symbol will internally be translated into an appropriate regexp (see also the variable `reftex-default-context-regexps'). - If a function, call this function with the name of the environment/macro as argument. On call, point will be just after the `\label' macro. The function is expected to return a suitable context string. It should throw an exception (error) when failing to find context. As an example, here is a function returning the 10 chars following the label macro as context: (defun my-context-function (env-or-mac) (if (> (point-max) (+ 10 (point))) (buffer-substring (point) (+ 10 (point))) (error "Buffer too small"))) Label context is used in two ways by RefTeX: For display in the label menu, and to derive a label string. If you want to use a different method for each of these, specify them as a dotted pair. E.g. `(nil . t)' uses the text after the label (`nil') for display, and text from the default position (`t') to derive a label string. This is actually used for section labels. MAGIC-WORD-LIST List of magic words which identify a reference to be of this type. If the word before point is equal to one of these words when calling `reftex-reference', the label list offered will be automatically restricted to labels of the correct type. If the first element of this word-list is the symbol `regexp', the strings are interpreted as regular expressions(1). If the type indicator characters of two or more entries are the same, RefTeX will use - the first non-`nil' format and prefix - the magic words of all involved entries. Any list entry may also be a symbol. If that has an association in `reftex-label-alist-builtin', the `cddr' of that association is spliced into the list. However, builtin defaults should normally be set with the variable `reftex-default-label-alist-entries'. - User Option: reftex-section-levels Commands and levels used for defining sections in the document. The `car' of each cons cell is the name of the section macro. The `cdr' is a number indicating its level. A negative level means the same as the positive value, but the section will never get a number. - User Option: reftex-default-context-regexps Alist with default regular expressions for finding context. The emacs lisp form `(format regexp (regexp-quote environment))' is used to calculate the final regular expression--so `%s' will be replaced with the environment or macro. ---------- Footnotes ---------- (1) Careful: RefTeX will add stuff to the beginning and end of these regular expressions.  File: reftex, Node: Options (Creating Labels), Next: Options (Referencing Labels), Prev: Options (Defining Label Environments), Up: Options Creating Labels =============== - User Option: reftex-insert-label-flags Flags governing label insertion. The value has the form (DERIVE PROMPT) If DERIVEis `t', RefTeX will try to derive a sensible label from context. A section label for example will be derived from the section heading. The conversion of the context to a legal label is governed by the specifications given in `reftex-derive-label-parameters'. If DERIVE is `nil', the default label will consist of the prefix and a unique number, like `eq:23'. If PROMPT is `t', the user will be prompted for a label string. When PROMPT is `nil', the default label will be inserted without query. So the combination of DERIVE and PROMPT controls label insertion. Here is a table describing all four possibilities: DERIVE PROMPT ACTION ----------------------------------------------------------- nil nil Insert simple label, like `eq:22' or `sec:13'. No query. nil t Prompt for label. t nil Derive a label from context and insert. No query. t t Derive a label from context, prompt for confirmation. Each flag may be set to `t', `nil', or a string of label type letters indicating the label types for which it should be true. Thus, the combination may be set differently for each label type. The default settings `"s"' and `"sft"' mean: Derive section labels from headings (with confirmation). Prompt for figure and table labels. Use simple labels without confirmation for everything else. The available label types are: `s' (section), `f' (figure), `t' (table), `i' (item), `e' (equation), `n' (footnote), plus any definitions in `reftex-label-alist'. - Hook: reftex-format-label-function If non-`nil', should be a function which produces the string to insert as a label definition. The function will be called with two arguments, the LABEL and the DEFAULT-FORMAT (usually `\label{%s}'). It should return the string to insert into the buffer. - Hook: reftex-string-to-label-function Function to turn an arbitrary string into a legal label. RefTeX's default function uses the variable `reftex-derive-label-parameters'. - Hook: reftex-translate-to-ascii-function Filter function which will process a context string before it is used to derive a label from it. The intended application is to convert ISO or Mule characters into something legal in labels. The default function `reftex-latin1-to-ascii' removes the accents from Latin-1 characters. X-Symbol (>=2.6) sets this variable to the much more general `x-symbol-translate-to-ascii'. - User Option: reftex-derive-label-parameters Parameters for converting a string into a label. This variable is a list of the following items: NWORDS Number of words to use. MAXCHAR Maximum number of characters in a label string. ILLEGAL `nil': Throw away any words containing characters illegal in labels. `t': Throw away only the illegal characters, not the whole word. ABBREV `nil': Never abbreviate words. `t': Always abbreviate words (see `reftex-abbrev-parameters'). `1': Abbreviate words if necessary to shorten label string. SEPARATOR String separating different words in the label. IGNOREWORDS List of words which should not be part of labels. DOWNCASE `t': Downcase words before putting them into the label. - User Option: reftex-label-illegal-re Regexp matching characters not legal in labels. - User Option: reftex-abbrev-parameters Parameters for abbreviation of words. A list of four parameters. MIN-CHARS Minimum number of characters remaining after abbreviation. MIN-KILL Minimum number of characters to remove when abbreviating words. BEFORE Character class before abbrev point in word. AFTER Character class after abbrev point in word.  File: reftex, Node: Options (Referencing Labels), Next: Options (Creating Citations), Prev: Options (Creating Labels), Up: Options Referencing Labels ================== - User Option: reftex-label-menu-flags List of flags governing the label menu makeup. The flags are: TABLE-OF-CONTENTS Show the labels embedded in a table of context. SECTION-NUMBERS Include section numbers (like 4.1.3) in table of contents. COUNTERS Show counters. This just numbers the labels in the menu. NO-CONTEXT Non-`nil' means do *not* show the short context. FOLLOW Follow full context in other window. SHOW-COMMENTED Show labels from regions which are commented out. MATCH-EVERYWHERE Obsolete flag. SHOW-FILES Show begin and end of included files. Each of these flags can be set to `t' or `nil', or to a string of type letters indicating the label types for which it should be true. These strings work like character classes in regular expressions. Thus, setting one of the flags to `"sf"' makes the flag true for section and figure labels, `nil' for everything else. Setting it to `"^sf"' makes it the other way round. The available label types are: `s' (section), `f' (figure), `t' (table), `i' (item), `e' (equation), `n' (footnote), plus any definitions in `reftex-label-alist'. Most options can also be switched from the label menu itself--so if you decide here to not have a table of contents in the label menu, you can still get one interactively during selection from the label menu. - Hook: reftex-format-ref-function If non-`nil', should be a function which produces the string to insert as a reference. Note that the insertion format can also be changed with `reftex-label-alist'. The function will be called with two arguments, the LABEL and the DEFAULT-FORMAT (usually `~\ref{%s}'). It should return the string to insert into the buffer. - User Option: reftex-vref-is-default Non-`nil' means, the varioref macro `\vref' is used as default. In the selection buffer, the `v' key toggles the reference macro between `\ref' and `\vref'. The value of this variable determines the default which is active when entering the selection process. Instead of `nil' or `t', this may also be a string of type letters indicating the label types for which it should be true. - User Option: reftex-level-indent Number of spaces to be used for indentation per section level. - User Option: reftex-guess-label-type Non-`nil' means, `reftex-reference' will try to guess the label type. To do that, RefTeX will look at the word before the cursor and compare it with the magic words given in `reftex-label-alist'. When it finds a match, RefTeX will immediately offer the correct label menu--otherwise it will prompt you for a label type. If you set this variable to `nil', RefTeX will always prompt for a label type. - Normal Hook: reftex-display-copied-context-hook Normal Hook which is run before context is displayed anywhere. Designed for `X-Symbol', but may have other uses as well. - Hook: reftex-pre-refontification-functions `X-Symbol' specific hook. Probably not useful for other purposes. The functions get two arguments, the buffer from where the command started and a symbol indicating in what context the hook is called. - Normal Hook: reftex-select-label-mode-hook Normal hook which is run when a selection buffer enters `reftex-select-label-mode'. - Keymap: reftex-select-label-map The keymap which is active in the labels selection process (*note Referencing Labels::.).