Source

reftex / NUTSHELL

Introduction
************

   RefTeX is a specialized package for support of labels, references,
citations, and the index in LaTeX.  RefTeX wraps itself round 4 LaTeX
macros: `\label', `\ref', `\cite', and `\index'.  Using these macros
usually requires looking up different parts of the document and
searching through BibTeX database files.  RefTeX automates these
time-consuming tasks almost entirely.  It also provides functions to
display the structure of a document and to move around in this
structure quickly.

   *Note Imprint::, for information about who to contact for help, bug
reports or suggestions.

Environment
===========

   RefTeX needs to access all files which are part of a multifile
document, and the BibTeX database files requested by the
`\bibliography' command.  To find these files, RefTeX will require a
search path, i.e. a list of directories to check.  Normally this list
is stored in the environment variables `TEXINPUTS' and `BIBINPUTS'
which are also used by RefTeX.  However, on some systems these
variables do not contain the full search path.  If RefTeX does not work
for you because it cannot find some files, read *Note Finding Files::.

Entering RefTeX Mode
====================

   To turn RefTeX Mode on and off in a particular buffer, use `M-x
reftex-mode'.  To turn on RefTeX Mode for all LaTeX files, add the
following lines to your `.emacs' file:

     (add-hook 'LaTeX-mode-hook 'turn-on-reftex)   ; with AUCTeX LaTeX mode
     (add-hook 'latex-mode-hook 'turn-on-reftex)   ; with Emacs latex mode

RefTeX in a Nutshell
====================

  1. Table of Contents
     Typing `C-c =' (`reftex-toc') will show a table of contents of the
     document.  This buffer can display sections, labels and index
     entries defined in the document.  From the buffer, you can jump
     quickly to every part of your document.  Press `?' to get help.

  2. Labels and References
     RefTeX helps to create unique labels and to find the correct key
     for references quickly.  It distinguishes labels for different
     environments, knows about all standard environments (and many
     others), and can be configured to recognize any additional labeled
     environments you have defined yourself (variable
     `reftex-label-alist').

        * Creating Labels
          Type `C-c (' (`reftex-label') to insert a label at point.
          RefTeX will either
             - derive a label from context (default for section labels)

             - prompt for a label string (default for figures and
               tables) or

             - insert a simple label made of a prefix and a number (all
               other environments)

          Which labels are created how is configurable with the variable
          `reftex-insert-label-flags'.

        * Referencing Labels
          To make a reference, type `C-c )' (`reftex-reference').  This
          shows an outline of the document with all labels of a certain
          type (figure, equation,...) and some label context.
          Selecting a label inserts a `\ref{LABEL}' macro into the
          original buffer.

  3. Citations
     Typing `C-c [' (`reftex-citation') will let you specify a regular
     expression to search in current BibTeX database files (as
     specified in the `\bibliography' command) and pull out a list of
     matches for you to choose from.  The list is _formatted_ and
     sorted.  The selected article is referenced as `\cite{KEY}' (see
     the variable `reftex-cite-format' if you want to insert different
     macros).

  4. Index Support
     RefTeX helps to enter index entries.  It also compiles all entries
     into an alphabetically sorted `*Index*' buffer which you can use
     to check and edit the entries.  RefTeX knows about the standard
     index macros and can be configured to recognize any additional
     macros you have defined (`reftex-index-macros').  Multiple indices
     are supported.

        * Creating Index Entries
          To index the current selection or the word at point, type
          `C-c /' (`reftex-index-selection-or-word').  The default macro
          `reftex-index-default-macro' will be used.  For a more
          complex entry type `C-c <' (`reftex-index'), select any of
          the index macros and enter the arguments with completion.

        * The Index Phrases File (Delayed Indexing)
          Type `C-c \' (`reftex-index-phrase-selection-or-word') to add
          the current word or selection to a special _index phrase
          file_.  RefTeX can later search the document for occurrences
          of these phrases and let you interactively index the matches.

        * Displaying and Editing the Index
          To display the compiled index in a special buffer, type `C-c
          >' (`reftex-display-index').  From that buffer you can check
          and edit all entries.

  5. Viewing Cross-References
     When point is on the KEY argument of a cross-referencing macro
     (`\label', `\ref', `\cite', `\bibitem', `\index', and variations)
     or inside a BibTeX database entry, you can press `C-c &'
     (`reftex-view-crossref') to display corresponding locations in the
     document and associated BibTeX database files.
     When the enclosing macro is `\cite' or `\ref' and no other message
     occupies the echo area, information about the citation or label
     will automatically be displayed in the echo area.

  6. Multifile Documents
     Multifile Documents are fully supported.  The included files must
     have a file variable `TeX-master' or `tex-main-file' pointing to
     the master file.  RefTeX provides cross-referencing information
     from all parts of the document, and across document borders
     (`xr.sty').

  7. Document Parsing
     RefTeX needs to parse the document in order to find labels and
     other information.  It does it automatically once and updates its
     list internally when `reftex-label' and `reftex-index' are used.
     To enforce reparsing, call any of the commands described above
     with a raw `C-u' prefix, or press the `r' key in the label
     selection buffer, the table of contents buffer, or the index
     buffer.

  8. AUCTeX
     If your major LaTeX mode is AUCTeX, RefTeX can cooperate with it
     (see variable `reftex-plug-into-AUCTeX').  AUCTeX contains style
     files which trigger appropriate settings in RefTeX, so that for
     many of the popular LaTeX packages no additional customizations
     will be necessary.

  9. Useful Settings
     To make RefTeX faster for large documents, try these:
          (setq reftex-enable-partial-scans t)
          (setq reftex-save-parse-info t)
          (setq reftex-use-multiple-selection-buffers t)

     To integrate with AUCTeX, use
          (setq reftex-plug-into-AUCTeX t)

     To make your own LaTeX macro definitions known to RefTeX,
     customize the variables
          `reftex-label-alist'          (for label macros/environments)
          `reftex-section-levels'       (for sectioning commands)
          `reftex-cite-format'          (for `\cite'-like macros)
          `reftex-index-macros'         (for `\index'-like macros)
          `reftex-index-default-macro'  (to set the default macro)
     If you have a large number of macros defined, you may want to write
     an AUCTeX style file to support them with both AUCTeX and RefTeX.

 10. Where Next?
     Go ahead and use RefTeX.  Use its menus until you have picked up
     the key bindings.  For an overview of what you can do in each of
     the different special buffers, press `?'.  Read the manual if you
     get stuck, of if you are curious what else might be available.
     The first part of the manual explains in a tutorial way how to use
     and customize RefTeX.  The second part is a command and variable
     reference.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.