| 1 | \input texinfo @c -*-texinfo-*- |
| 2 | @c %**start of header |
| 3 | @setfilename ../../info/reftex |
| 4 | @settitle RefTeX User Manual |
| 5 | @synindex ky cp |
| 6 | @syncodeindex vr cp |
| 7 | @syncodeindex fn cp |
| 8 | |
| 9 | @c Version and Contact Info |
| 10 | @set VERSION 4.31 |
| 11 | @set EDITION 4.31 |
| 12 | @set DATE February 2006 |
| 13 | @set AUCTEXSITE @uref{http://www.gnu.org/software/auctex/,AUCTeX distribution site} |
| 14 | @set MAINTAINERSITE @uref{http://www.gnu.org/software/auctex/reftex.html,Ref@TeX{} web page} |
| 15 | @set MAINTAINERCONTACT @uref{mailto:auctex-devel@@gnu.org,contact the maintainers} |
| 16 | @set MAINTAINER the AUC@TeX{} project |
| 17 | @set SUPPORTADDRESS AUC@TeX{} user mailing list (@email{auctex@@gnu.org}) |
| 18 | @set DEVELADDRESS AUC@TeX{} developer mailing list (@email{auctex-devel@@gnu.org}) |
| 19 | @set BUGADDRESS AUC@TeX{} bug mailing list (@email{bug-auctex@@gnu.org}) |
| 20 | @set XEMACSFTP @uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site} |
| 21 | @c %**end of header |
| 22 | |
| 23 | @copying |
| 24 | This file documents @b{Ref@TeX{}}, a package to do labels, references, |
| 25 | citations and indices for LaTeX documents with Emacs. |
| 26 | |
| 27 | This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for |
| 28 | @b{Ref@TeX{}} @value{VERSION} |
| 29 | |
| 30 | Copyright @copyright{} 1997-2011 Free Software Foundation, Inc. |
| 31 | |
| 32 | @quotation |
| 33 | Permission is granted to copy, distribute and/or modify this document |
| 34 | under the terms of the GNU Free Documentation License, Version 1.3 or |
| 35 | any later version published by the Free Software Foundation; with no |
| 36 | Invariant Sections, with the Front-Cover texts being ``A GNU Manual'', |
| 37 | and with the Back-Cover Texts as in (a) below. A copy of the license |
| 38 | is included in the section entitled ``GNU Free Documentation License''. |
| 39 | |
| 40 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and |
| 41 | modify this GNU manual. Buying copies from the FSF supports it in |
| 42 | developing GNU and promoting software freedom.'' |
| 43 | @end quotation |
| 44 | @end copying |
| 45 | |
| 46 | @dircategory Emacs misc features |
| 47 | @direntry |
| 48 | * RefTeX: (reftex). Emacs support for LaTeX cross-references |
| 49 | and citations. |
| 50 | @end direntry |
| 51 | |
| 52 | @finalout |
| 53 | |
| 54 | @c Macro definitions |
| 55 | |
| 56 | @c Subheadings inside a table. Need a difference between info and the rest. |
| 57 | @macro tablesubheading{text} |
| 58 | @ifinfo |
| 59 | @subsubheading \text\ |
| 60 | @end ifinfo |
| 61 | @ifnotinfo |
| 62 | @item @b{\text\} |
| 63 | @end ifnotinfo |
| 64 | @end macro |
| 65 | |
| 66 | @titlepage |
| 67 | @title Ref@TeX{} User Manual |
| 68 | @subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs |
| 69 | @subtitle Edition @value{EDITION}, @value{DATE} |
| 70 | |
| 71 | @author by Carsten Dominik |
| 72 | @page |
| 73 | @vskip 0pt plus 1filll |
| 74 | @insertcopying |
| 75 | @end titlepage |
| 76 | |
| 77 | @summarycontents |
| 78 | @contents |
| 79 | |
| 80 | @ifnottex |
| 81 | @node Top,,,(dir) |
| 82 | @top RefTeX |
| 83 | |
| 84 | @b{Ref@TeX{}} is a package for managing Labels, References, |
| 85 | Citations and index entries with GNU Emacs. |
| 86 | |
| 87 | Don't be discouraged by the size of this manual, which covers |
| 88 | @b{Ref@TeX{}} in great depth. All you need to know to use |
| 89 | @b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a |
| 90 | Nutshell}). You can go back later to other parts of this document when |
| 91 | needed. |
| 92 | |
| 93 | @insertcopying |
| 94 | |
| 95 | @menu |
| 96 | * Introduction:: Quick-Start information. |
| 97 | |
| 98 | * Table of Contents:: A Tool to move around quickly. |
| 99 | * Labels and References:: Creating and referencing labels. |
| 100 | * Citations:: Creating Citations. |
| 101 | * Index Support:: Creating and Checking Index Entries. |
| 102 | * Viewing Cross-References:: Who references or cites what? |
| 103 | |
| 104 | * RefTeXs Menu:: The Ref menu in the menubar. |
| 105 | * Key Bindings:: The default key bindings. |
| 106 | * Faces:: Fontification of RefTeX's buffers. |
| 107 | * Multifile Documents:: Document spread over many files. |
| 108 | * Language Support:: How to support other languages. |
| 109 | * Finding Files:: Included TeX files and BibTeX .bib files. |
| 110 | * AUCTeX:: Cooperation with AUCTeX. |
| 111 | * Optimizations:: When RefTeX is too slow. |
| 112 | * Problems and Work-Arounds:: First Aid. |
| 113 | * Imprint:: Author, Web-site, Thanks |
| 114 | |
| 115 | * Commands:: Which are the available commands. |
| 116 | * Options:: How to extend and configure RefTeX. |
| 117 | * Keymaps and Hooks:: For customization. |
| 118 | * Changes:: A List of recent changes to RefTeX. |
| 119 | * GNU Free Documentation License:: The license for this documentation. |
| 120 | |
| 121 | The Index |
| 122 | |
| 123 | * Index:: The full index. |
| 124 | |
| 125 | @detailmenu |
| 126 | |
| 127 | Introduction |
| 128 | |
| 129 | * Installation:: How to install and activate RefTeX. |
| 130 | * RefTeX in a Nutshell:: A brief summary and quick guide. |
| 131 | |
| 132 | Labels and References |
| 133 | |
| 134 | * Creating Labels:: |
| 135 | * Referencing Labels:: |
| 136 | * Builtin Label Environments:: The environments RefTeX knows about. |
| 137 | * Defining Label Environments:: ... and environments it doesn't. |
| 138 | * Reference Info:: View the label corresponding to a \ref. |
| 139 | * xr (LaTeX package):: References to external documents. |
| 140 | * varioref (LaTeX package):: How to create \vref instead of \ref. |
| 141 | * fancyref (LaTeX package):: How to create \fref instead of \ref. |
| 142 | |
| 143 | Defining Label Environments |
| 144 | |
| 145 | * Theorem and Axiom:: Defined with @code{\newenvironment}. |
| 146 | * Quick Equation:: When a macro sets the label type. |
| 147 | * Figure Wrapper:: When a macro argument is a label. |
| 148 | * Adding Magic Words:: Other words for other languages. |
| 149 | * Using \eqref:: How to switch to this AMS-LaTeX macro. |
| 150 | * Non-Standard Environments:: Environments without \begin and \end |
| 151 | * Putting it Together:: How to combine many entries. |
| 152 | |
| 153 | Citations |
| 154 | |
| 155 | * Creating Citations:: How to create them. |
| 156 | * Citation Styles:: Natbib, Harvard, Chicago and Co. |
| 157 | * Citation Info:: View the corresponding database entry. |
| 158 | * Chapterbib and Bibunits:: Multiple bibliographies in a Document. |
| 159 | * Citations Outside LaTeX:: How to make citations in Emails etc. |
| 160 | * BibTeX Database Subsets:: Extract parts of a big database. |
| 161 | |
| 162 | Index Support |
| 163 | |
| 164 | * Creating Index Entries:: Macros and completion of entries. |
| 165 | * The Index Phrases File:: A special file for global indexing. |
| 166 | * Displaying and Editing the Index:: The index editor. |
| 167 | * Builtin Index Macros:: The index macros RefTeX knows about. |
| 168 | * Defining Index Macros:: ... and macros it doesn't. |
| 169 | |
| 170 | The Index Phrases File |
| 171 | |
| 172 | * Collecting Phrases:: Collecting from document or external. |
| 173 | * Consistency Checks:: Check for duplicates etc. |
| 174 | * Global Indexing:: The interactive indexing process. |
| 175 | |
| 176 | AUCTeX |
| 177 | |
| 178 | * AUCTeX-RefTeX Interface:: How both packages work together |
| 179 | * Style Files:: AUCTeX's style files can support RefTeX |
| 180 | * Bib-Cite:: Hypertext reading of a document |
| 181 | |
| 182 | Options, Keymaps, Hooks |
| 183 | |
| 184 | * Options (Table of Contents):: |
| 185 | * Options (Defining Label Environments):: |
| 186 | * Options (Creating Labels):: |
| 187 | * Options (Referencing Labels):: |
| 188 | * Options (Creating Citations):: |
| 189 | * Options (Index Support):: |
| 190 | * Options (Viewing Cross-References):: |
| 191 | * Options (Finding Files):: |
| 192 | * Options (Optimizations):: |
| 193 | * Options (Fontification):: |
| 194 | * Options (Misc):: |
| 195 | |
| 196 | @end detailmenu |
| 197 | @end menu |
| 198 | |
| 199 | @end ifnottex |
| 200 | |
| 201 | @node Introduction, Table of Contents, , Top |
| 202 | @chapter Introduction |
| 203 | @cindex Introduction |
| 204 | |
| 205 | @b{Ref@TeX{}} is a specialized package for support of labels, |
| 206 | references, citations, and the index in LaTeX. @b{Ref@TeX{}} wraps |
| 207 | itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite}, |
| 208 | and @code{\index}. Using these macros usually requires looking up |
| 209 | different parts of the document and searching through BibTeX database |
| 210 | files. @b{Ref@TeX{}} automates these time--consuming tasks almost |
| 211 | entirely. It also provides functions to display the structure of a |
| 212 | document and to move around in this structure quickly. |
| 213 | |
| 214 | @iftex |
| 215 | Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}} |
| 216 | in great depth. All you need to know to use @b{Ref@TeX{}} can be |
| 217 | summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go |
| 218 | back later to other parts of this document when needed. |
| 219 | @end iftex |
| 220 | |
| 221 | @xref{Imprint}, for information about who to contact for help, bug |
| 222 | reports or suggestions. |
| 223 | |
| 224 | @menu |
| 225 | * Installation:: How to install and activate RefTeX. |
| 226 | * RefTeX in a Nutshell:: A brief summary and quick guide. |
| 227 | @end menu |
| 228 | |
| 229 | @node Installation, RefTeX in a Nutshell, , Introduction |
| 230 | @section Installation |
| 231 | @cindex Installation |
| 232 | |
| 233 | @b{Ref@TeX{}} is bundled and pre--installed with Emacs since version |
| 234 | 20.2. It was also bundled and pre--installed with XEmacs 19.16--20.x. |
| 235 | XEmacs 21.x users want to install the corresponding plug-in package |
| 236 | which is available from the @value{XEMACSFTP}. See the XEmacs 21.x |
| 237 | documentation on package installation for details. |
| 238 | |
| 239 | Users of earlier Emacs distributions (including Emacs 19) can get a copy |
| 240 | of the @b{Ref@TeX{}} distribution from the maintainers web-page. |
| 241 | @xref{Imprint}, for more information. |
| 242 | |
| 243 | @section Environment |
| 244 | @cindex Finding files |
| 245 | @cindex BibTeX database files, not found |
| 246 | @cindex TeX files, not found |
| 247 | @cindex @code{TEXINPUTS}, environment variable |
| 248 | @cindex @code{BIBINPUTS}, environment variable |
| 249 | |
| 250 | @b{Ref@TeX{}} needs to access all files which are part of a multifile |
| 251 | document, and the BibTeX database files requested by the |
| 252 | @code{\bibliography} command. To find these files, @b{Ref@TeX{}} will |
| 253 | require a search path, i.e. a list of directories to check. Normally |
| 254 | this list is stored in the environment variables @code{TEXINPUTS} and |
| 255 | @code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on some |
| 256 | systems these variables do not contain the full search path. If |
| 257 | @b{Ref@TeX{}} does not work for you because it cannot find some files, |
| 258 | read @ref{Finding Files}. |
| 259 | |
| 260 | @section Entering @b{Ref@TeX{}} Mode |
| 261 | |
| 262 | @findex turn-on-reftex |
| 263 | @findex reftex-mode |
| 264 | @vindex LaTeX-mode-hook |
| 265 | @vindex latex-mode-hook |
| 266 | To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use |
| 267 | @kbd{M-x reftex-mode}. To turn on @b{Ref@TeX{}} Mode for all LaTeX |
| 268 | files, add the following lines to your @file{.emacs} file: |
| 269 | |
| 270 | @example |
| 271 | (add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode |
| 272 | (add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode |
| 273 | @end example |
| 274 | |
| 275 | @page |
| 276 | @node RefTeX in a Nutshell, , Installation, Introduction |
| 277 | @section @b{Ref@TeX{}} in a Nutshell |
| 278 | @cindex Quick-Start |
| 279 | @cindex Getting Started |
| 280 | @cindex RefTeX in a Nutshell |
| 281 | @cindex Nutshell, RefTeX in a |
| 282 | |
| 283 | @enumerate |
| 284 | @item |
| 285 | @b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show |
| 286 | a table of contents of the document. This buffer can display sections, |
| 287 | labels and index entries defined in the document. From the buffer, you |
| 288 | can jump quickly to every part of your document. Press @kbd{?} to get |
| 289 | help. |
| 290 | |
| 291 | @item |
| 292 | @b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels |
| 293 | and to find the correct key for references quickly. It distinguishes |
| 294 | labels for different environments, knows about all standard |
| 295 | environments (and many others), and can be configured to recognize any |
| 296 | additional labeled environments you have defined yourself (variable |
| 297 | @code{reftex-label-alist}). |
| 298 | |
| 299 | @itemize @bullet |
| 300 | @item |
| 301 | @b{Creating Labels}@* |
| 302 | Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point. |
| 303 | @b{Ref@TeX{}} will either |
| 304 | @itemize @minus |
| 305 | @item |
| 306 | derive a label from context (default for section labels) |
| 307 | @item |
| 308 | prompt for a label string (default for figures and tables) or |
| 309 | @item |
| 310 | insert a simple label made of a prefix and a number (all other |
| 311 | environments) |
| 312 | @end itemize |
| 313 | @noindent |
| 314 | Which labels are created how is configurable with the variable |
| 315 | @code{reftex-insert-label-flags}. |
| 316 | |
| 317 | @item |
| 318 | @b{Referencing Labels}@* To make a reference, type @kbd{C-c )} |
| 319 | (@code{reftex-reference}). This shows an outline of the document with |
| 320 | all labels of a certain type (figure, equation,...) and some label |
| 321 | context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro |
| 322 | into the original buffer. |
| 323 | @end itemize |
| 324 | |
| 325 | @item |
| 326 | @b{Citations}@* |
| 327 | Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a |
| 328 | regular expression to search in current BibTeX database files (as |
| 329 | specified in the @code{\bibliography} command) and pull out a list of |
| 330 | matches for you to choose from. The list is @emph{formatted} and |
| 331 | sorted. The selected article is referenced as @samp{\cite@{@var{key}@}} |
| 332 | (see the variable @code{reftex-cite-format} if you want to insert |
| 333 | different macros). |
| 334 | |
| 335 | @item |
| 336 | @b{Index Support}@* |
| 337 | @b{Ref@TeX{}} helps to enter index entries. It also compiles all |
| 338 | entries into an alphabetically sorted @file{*Index*} buffer which you |
| 339 | can use to check and edit the entries. @b{Ref@TeX{}} knows about the |
| 340 | standard index macros and can be configured to recognize any additional |
| 341 | macros you have defined (@code{reftex-index-macros}). Multiple indices |
| 342 | are supported. |
| 343 | |
| 344 | @itemize @bullet |
| 345 | @item |
| 346 | @b{Creating Index Entries}@* |
| 347 | To index the current selection or the word at point, type @kbd{C-c /} |
| 348 | (@code{reftex-index-selection-or-word}). The default macro |
| 349 | @code{reftex-index-default-macro} will be used. For a more complex entry |
| 350 | type @kbd{C-c <} (@code{reftex-index}), select any of the index macros |
| 351 | and enter the arguments with completion. |
| 352 | |
| 353 | @item |
| 354 | @b{The Index Phrases File (Delayed Indexing)}@* |
| 355 | Type @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) to add |
| 356 | the current word or selection to a special @emph{index phrase file}. |
| 357 | @b{Ref@TeX{}} can later search the document for occurrences of these |
| 358 | phrases and let you interactively index the matches. |
| 359 | |
| 360 | @item |
| 361 | @b{Displaying and Editing the Index}@* |
| 362 | To display the compiled index in a special buffer, type @kbd{C-c >} |
| 363 | (@code{reftex-display-index}). From that buffer you can check and edit |
| 364 | all entries. |
| 365 | @end itemize |
| 366 | |
| 367 | @page |
| 368 | @item @b{Viewing Cross-References}@* |
| 369 | When point is on the @var{key} argument of a cross--referencing macro |
| 370 | (@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, |
| 371 | @code{\index}, and variations) or inside a BibTeX database entry, you |
| 372 | can press @kbd{C-c &} (@code{reftex-view-crossref}) to display |
| 373 | corresponding locations in the document and associated BibTeX database |
| 374 | files. @* |
| 375 | When the enclosing macro is @code{\cite} or @code{\ref} and no other |
| 376 | message occupies the echo area, information about the citation or label |
| 377 | will automatically be displayed in the echo area. |
| 378 | |
| 379 | @item |
| 380 | @b{Multifile Documents}@* |
| 381 | Multifile Documents are fully supported. The included files must have a |
| 382 | file variable @code{TeX-master} or @code{tex-main-file} pointing to the |
| 383 | master file. @b{Ref@TeX{}} provides cross-referencing information from |
| 384 | all parts of the document, and across document borders |
| 385 | (@file{xr.sty}). |
| 386 | |
| 387 | @item |
| 388 | @b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in |
| 389 | order to find labels and other information. It does it automatically |
| 390 | once and updates its list internally when @code{reftex-label} and |
| 391 | @code{reftex-index} are used. To enforce reparsing, call any of the |
| 392 | commands described above with a raw @kbd{C-u} prefix, or press the |
| 393 | @kbd{r} key in the label selection buffer, the table of contents |
| 394 | buffer, or the index buffer. |
| 395 | |
| 396 | @item |
| 397 | @b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can |
| 398 | cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeX |
| 399 | contains style files which trigger appropriate settings in |
| 400 | @b{Ref@TeX{}}, so that for many of the popular LaTeX packages no |
| 401 | additional customizations will be necessary. |
| 402 | |
| 403 | @item |
| 404 | @b{Useful Settings}@* |
| 405 | To integrate RefTeX with AUCTeX, use |
| 406 | @lisp |
| 407 | (setq reftex-plug-into-AUCTeX t) |
| 408 | @end lisp |
| 409 | |
| 410 | To make your own LaTeX macro definitions known to @b{Ref@TeX{}}, |
| 411 | customize the variables |
| 412 | @example |
| 413 | @code{reftex-label-alist} @r{(for label macros/environments)} |
| 414 | @code{reftex-section-levels} @r{(for sectioning commands)} |
| 415 | @code{reftex-cite-format} @r{(for @code{\cite}-like macros)} |
| 416 | @code{reftex-index-macros} @r{(for @code{\index}-like macros)} |
| 417 | @code{reftex-index-default-macro} @r{(to set the default macro)} |
| 418 | @end example |
| 419 | If you have a large number of macros defined, you may want to write |
| 420 | an AUCTeX style file to support them with both AUCTeX and |
| 421 | @b{Ref@TeX{}}. |
| 422 | |
| 423 | @item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menus |
| 424 | until you have picked up the key bindings. For an overview of what you |
| 425 | can do in each of the different special buffers, press @kbd{?}. Read |
| 426 | the manual if you get stuck, of if you are curious what else might be |
| 427 | available. The first part of the manual explains in |
| 428 | a tutorial way how to use and customize @b{Ref@TeX{}}. The second |
| 429 | part is a command and variable reference. |
| 430 | @end enumerate |
| 431 | |
| 432 | @node Table of Contents, Labels and References, Introduction, Top |
| 433 | @chapter Table of Contents |
| 434 | @cindex @file{*toc*} buffer |
| 435 | @cindex Structure editing |
| 436 | @cindex Table of contents buffer |
| 437 | @findex reftex-toc |
| 438 | @kindex C-c = |
| 439 | |
| 440 | Pressing the keys @kbd{C-c =} pops up a buffer showing the table of |
| 441 | contents of the document. By default, this @file{*toc*} buffer shows |
| 442 | only the sections of a document. Using the @kbd{l} and @kbd{i} keys you |
| 443 | can display all labels and index entries defined in the document as |
| 444 | well. |
| 445 | |
| 446 | With the cursor in any of the lines denoting a location in the |
| 447 | document, simple key strokes will display the corresponding part in |
| 448 | another window, jump to that location, or perform other actions. |
| 449 | |
| 450 | @kindex ? |
| 451 | Here is a list of special commands in the @file{*toc*} buffer. A |
| 452 | summary of this information is always available by pressing |
| 453 | @kbd{?}. |
| 454 | |
| 455 | @table @kbd |
| 456 | |
| 457 | @tablesubheading{General} |
| 458 | @item ? |
| 459 | Display a summary of commands. |
| 460 | |
| 461 | @item 0-9, - |
| 462 | Prefix argument. |
| 463 | |
| 464 | @tablesubheading{Moving around} |
| 465 | @item n |
| 466 | Goto next entry in the table of context. |
| 467 | |
| 468 | @item p |
| 469 | Goto previous entry in the table of context. |
| 470 | |
| 471 | @item C-c C-n |
| 472 | Goto next section heading. Useful when many labels and index entries |
| 473 | separate section headings. |
| 474 | |
| 475 | @item C-c C-p |
| 476 | Goto previous section heading. |
| 477 | |
| 478 | @item N z |
| 479 | Jump to section N, using the prefix arg. For example, @kbd{3 z} jumps |
| 480 | to section 3. |
| 481 | |
| 482 | @tablesubheading{Access to document locations} |
| 483 | @item @key{SPC} |
| 484 | Show the corresponding location in another window. This command does |
| 485 | @emph{not} select that other window. |
| 486 | |
| 487 | @item @key{TAB} |
| 488 | Goto the location in another window. |
| 489 | |
| 490 | @item @key{RET} |
| 491 | Go to the location and hide the @file{*toc*} buffer. This will restore |
| 492 | the window configuration before @code{reftex-toc} (@kbd{C-c =}) was |
| 493 | called. |
| 494 | |
| 495 | @item mouse-2 |
| 496 | @vindex reftex-highlight-selection |
| 497 | Clicking with mouse button 2 on a line has the same effect as @key{RET}. |
| 498 | See also variable @code{reftex-highlight-selection}, @ref{Options |
| 499 | (Fontification)}. |
| 500 | |
| 501 | @item f |
| 502 | @vindex reftex-toc-follow-mode |
| 503 | @vindex reftex-revisit-to-follow |
| 504 | Toggle follow mode. When follow mode is active, the other window will |
| 505 | always show the location corresponding to the line at point in the |
| 506 | @file{*toc*} buffer. This is similar to pressing @key{SPC} after each |
| 507 | cursor motion. The default for this flag can be set with the variable |
| 508 | @code{reftex-toc-follow-mode}. Note that only context in files already |
| 509 | visited is shown. @b{Ref@TeX{}} will not visit a file just for follow |
| 510 | mode. See, however, the variable |
| 511 | @code{reftex-revisit-to-follow}. |
| 512 | |
| 513 | @item . |
| 514 | Show calling point in another window. This is the point from where |
| 515 | @code{reftex-toc} was last called. |
| 516 | |
| 517 | @page |
| 518 | @tablesubheading{Promotion and Demotion} |
| 519 | |
| 520 | @item < |
| 521 | Promote the current section. This will convert @code{\section} to |
| 522 | @code{\chapter}, @code{\subsection} to @code{\section} etc. If there is |
| 523 | an active region, all sections in the region will be promoted, including |
| 524 | the one at point. To avoid mistakes, @b{Ref@TeX{}} requires a fresh |
| 525 | document scan before executing this command - if necessary, it will |
| 526 | automatically do this scan and ask the user to repeat the promotion |
| 527 | command. |
| 528 | |
| 529 | @item > |
| 530 | Demote the current section. This is the opposite of promotion. It will |
| 531 | convert @code{\chapter} to @code{\section} etc. If there is an active |
| 532 | region, all sections in the region will be demoted, including the one at |
| 533 | point. |
| 534 | |
| 535 | @item M-% |
| 536 | Rename the label at point. While generally not recommended, this can be |
| 537 | useful when a package like @file{fancyref} is used where the label |
| 538 | prefix determines the wording of a reference. After a |
| 539 | promotion/demotion it may be necessary to change a few labels from |
| 540 | @samp{sec:xyz} to @samp{cha:xyz} or vice versa. This command can be |
| 541 | used to do this - it launches a query replace to rename the definition |
| 542 | and all references of a label. |
| 543 | |
| 544 | @tablesubheading{Exiting} |
| 545 | @item q |
| 546 | Hide the @file{*toc*} buffer, return to the position where |
| 547 | @code{reftex-toc} was last called. |
| 548 | |
| 549 | @item k |
| 550 | Kill the @file{*toc*} buffer, return to the position where |
| 551 | @code{reftex-toc} was last called. |
| 552 | |
| 553 | @item C-c > |
| 554 | Switch to the @file{*Index*} buffer of this document. With prefix |
| 555 | @samp{2}, restrict the index to the section at point in the @file{*toc*} |
| 556 | buffer. |
| 557 | |
| 558 | @tablesubheading{Controlling what gets displayed} |
| 559 | |
| 560 | @item t |
| 561 | @vindex reftex-toc-max-level |
| 562 | Change the maximum level of toc entries displayed in the @file{*toc*} |
| 563 | buffer. Without prefix arg, all levels will be included. With prefix |
| 564 | arg (e.g @kbd{3 t}), ignore all toc entries with level greater than |
| 565 | @var{arg} (3 in this case). Chapters are level 1, sections are level 2. |
| 566 | The mode line @samp{T<>} indicator shows the current value. The default |
| 567 | depth can be configured with the variable |
| 568 | @code{reftex-toc-max-level}. |
| 569 | |
| 570 | @item F |
| 571 | @vindex reftex-toc-include-file-boundaries |
| 572 | Toggle the display of the file borders of a multifile document in the |
| 573 | @file{*toc*} buffer. The default for this flag can be set with the |
| 574 | variable @code{reftex-toc-include-file-boundaries}. |
| 575 | |
| 576 | @item l |
| 577 | @vindex reftex-toc-include-labels |
| 578 | Toggle the display of labels in the @file{*toc*} buffer. The default |
| 579 | for this flag can be set with the variable |
| 580 | @code{reftex-toc-include-labels}. When called with a prefix argument, |
| 581 | @b{Ref@TeX{}} will prompt for a label type and include only labels of |
| 582 | the selected type in the @file{*toc*} buffer. The mode line @samp{L<>} |
| 583 | indicator shows which labels are included. |
| 584 | |
| 585 | @item i |
| 586 | @vindex reftex-toc-include-index-entries |
| 587 | Toggle the display of index entries in the @file{*toc*} buffer. The |
| 588 | default for this flag can be set with the variable |
| 589 | @code{reftex-toc-include-index-entries}. When called with a prefix |
| 590 | argument, @b{Ref@TeX{}} will prompt for a specific index and include |
| 591 | only entries in the selected index in the @file{*toc*} buffer. The mode |
| 592 | line @samp{I<>} indicator shows which index is used. |
| 593 | |
| 594 | @item c |
| 595 | @vindex reftex-toc-include-context |
| 596 | Toggle the display of label and index context in the @file{*toc*} |
| 597 | buffer. The default for this flag can be set with the variable |
| 598 | @code{reftex-toc-include-context}. |
| 599 | |
| 600 | @tablesubheading{Updating the buffer} |
| 601 | |
| 602 | @item g |
| 603 | Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the |
| 604 | document. |
| 605 | |
| 606 | @item r |
| 607 | @vindex reftex-enable-partial-scans |
| 608 | Reparse the LaTeX document and rebuild the @file{*toc*} buffer. When |
| 609 | @code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this |
| 610 | location is defined in, not the entire document. |
| 611 | |
| 612 | @item C-u r |
| 613 | Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*} |
| 614 | buffer. |
| 615 | |
| 616 | @item x |
| 617 | Switch to the @file{*toc*} buffer of an external document. When the |
| 618 | current document is using the @code{xr} package (@pxref{xr (LaTeX |
| 619 | package)}), @b{Ref@TeX{}} will switch to one of the external |
| 620 | documents. |
| 621 | |
| 622 | |
| 623 | @tablesubheading{Automatic recentering} |
| 624 | |
| 625 | @item d |
| 626 | Toggle the display of a dedicated frame displaying just the @file{*toc*} |
| 627 | buffer. Follow mode and visiting locations will not work that frame, |
| 628 | but automatic recentering will make this frame always show your current |
| 629 | editing location in the document (see below). |
| 630 | |
| 631 | @item a |
| 632 | Toggle the automatic recentering of the @file{*toc*} buffer. When this |
| 633 | option is on, moving around in the document will cause the @file{*toc*} |
| 634 | to always highlight the current section. By default, this option is |
| 635 | active while the dedicated @file{*TOC*} frame exists. See also the |
| 636 | variable @code{reftex-auto-recenter-toc}. |
| 637 | |
| 638 | @end table |
| 639 | |
| 640 | @vindex reftex-toc-map |
| 641 | In order to define additional commands for the @file{*toc*} buffer, the |
| 642 | keymap @code{reftex-toc-map} may be used. |
| 643 | |
| 644 | @findex reftex-toc-recenter |
| 645 | @vindex reftex-auto-recenter-toc |
| 646 | @vindex reftex-idle-time |
| 647 | @cindex @file{*toc*} buffer, recentering |
| 648 | @cindex Table of contents buffer, recentering |
| 649 | @kindex C-c - |
| 650 | If you call @code{reftex-toc} while the @file{*toc*} buffer already |
| 651 | exists, the cursor will immediately jump to the right place, i.e. the |
| 652 | section from which @code{reftex-toc} was called will be highlighted. |
| 653 | The command @kbd{C-c -} (@code{reftex-toc-recenter}) will only redisplay |
| 654 | the @file{*toc*} buffer and highlight the correct line without actually |
| 655 | selecting the @file{*toc*} window. This can be useful to quickly find |
| 656 | out where in the document you currently are. You can also automate this |
| 657 | by asking RefTeX to keep track of your current editing position in the |
| 658 | TOC. The TOC window will then be updated whenever you stop typing for |
| 659 | more than @code{reftex-idle-time} seconds. By default this works only |
| 660 | with the dedicated @file{*TOC*} frame. But you can also force automatic |
| 661 | recentering of the TOC window on the current frame with |
| 662 | @lisp |
| 663 | (setq reftex-auto-recenter-toc t) |
| 664 | @end lisp |
| 665 | |
| 666 | |
| 667 | @cindex Sectioning commands |
| 668 | @cindex KOMA-Script, LaTeX classes |
| 669 | @cindex LaTeX classes, KOMA-Script |
| 670 | @cindex TOC entries for environments |
| 671 | @vindex reftex-section-levels |
| 672 | The section macros recognized by @b{Ref@TeX{}} are all LaTeX section |
| 673 | macros (from @code{\part} to @code{\subsubparagraph}) and the commands |
| 674 | @code{\addchap} and @code{\addsec} from the KOMA-Script classes. |
| 675 | Additional macros can be configured with the variable |
| 676 | @code{reftex-section-levels}. It is also possible to add certain LaTeX |
| 677 | environments to the table of contents. This is probably only useful for |
| 678 | theorem-like environments. @xref{Defining Label Environments}, for an |
| 679 | example. |
| 680 | |
| 681 | @node Labels and References, Citations, Table of Contents, Top |
| 682 | @chapter Labels and References |
| 683 | @cindex Labels in LaTeX |
| 684 | @cindex References in LaTeX |
| 685 | @cindex Label category |
| 686 | @cindex Label environment |
| 687 | @cindex @code{\label} |
| 688 | |
| 689 | LaTeX provides a powerful mechanism to deal with cross--references in a |
| 690 | document. When writing a document, any part of it can be marked with a |
| 691 | label, like @samp{\label@{mark@}}. LaTeX records the current value of a |
| 692 | certain counter when a label is defined. Later references to this label |
| 693 | (like @samp{\ref@{mark@}}) will produce the recorded value of the |
| 694 | counter. |
| 695 | |
| 696 | Labels can be used to mark sections, figures, tables, equations, |
| 697 | footnotes, items in enumerate lists etc. LaTeX is context sensitive in |
| 698 | doing this: A label defined in a figure environment automatically |
| 699 | records the figure counter, not the section counter. |
| 700 | |
| 701 | Several different environments can share a common counter and therefore |
| 702 | a common label category. E.g. labels in both @code{equation} and |
| 703 | @code{eqnarray} environments record the value of the same counter - the |
| 704 | equation counter. |
| 705 | |
| 706 | @menu |
| 707 | * Creating Labels:: |
| 708 | * Referencing Labels:: |
| 709 | * Builtin Label Environments:: The environments RefTeX knows about. |
| 710 | * Defining Label Environments:: ... and environments it doesn't. |
| 711 | * Reference Info:: View the label corresponding to a \ref. |
| 712 | * xr (LaTeX package):: References to external documents. |
| 713 | * varioref (LaTeX package):: How to create \vref instead of \ref. |
| 714 | * fancyref (LaTeX package):: How to create \fref instead of \ref. |
| 715 | @end menu |
| 716 | |
| 717 | @node Creating Labels, Referencing Labels, , Labels and References |
| 718 | @section Creating Labels |
| 719 | @cindex Creating labels |
| 720 | @cindex Labels, creating |
| 721 | @cindex Labels, deriving from context |
| 722 | @kindex C-c ( |
| 723 | @findex reftex-label |
| 724 | |
| 725 | In order to create a label in a LaTeX document, press @kbd{C-c (} |
| 726 | (@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitive |
| 727 | and will figure out the environment it currently is in and adapt the |
| 728 | label to that environment. A label usually consists of a short prefix |
| 729 | indicating the type of the label and a unique mark. @b{Ref@TeX{}} has |
| 730 | 3 different modes to create this mark. |
| 731 | |
| 732 | @enumerate |
| 733 | @item |
| 734 | @vindex reftex-translate-to-ascii-function |
| 735 | @vindex reftex-derive-label-parameters |
| 736 | @vindex reftex-label-illegal-re |
| 737 | @vindex reftex-abbrev-parameters |
| 738 | A label can be derived from context. This means, @b{Ref@TeX{}} takes |
| 739 | the context of the label definition and constructs a label from |
| 740 | that@footnote{Note that the context may contain constructs which are |
| 741 | invalid in labels. @b{Ref@TeX{}} will therefore strip the accent from |
| 742 | accented Latin-1 characters and remove everything else which is not |
| 743 | valid in labels. This mechanism is safe, but may not be satisfactory |
| 744 | for non-western languages. Check the following variables if you need to |
| 745 | change things: @code{reftex-translate-to-ascii-function}, |
| 746 | @code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re}, |
| 747 | @code{reftex-abbrev-parameters}.}. This works best for section labels, |
| 748 | where the section heading is used to construct a label. In fact, |
| 749 | @b{Ref@TeX{}}'s default settings use this method only for section |
| 750 | labels. You will be asked to confirm the derived label, or edit |
| 751 | it. |
| 752 | |
| 753 | @item |
| 754 | We may also use a simple unique number to identify a label. This is |
| 755 | mostly useful for labels where it is difficult to come up with a very |
| 756 | good descriptive name. @b{Ref@TeX{}}'s default settings use this method |
| 757 | for equations, enumerate items and footnotes. The author of @b{Ref@TeX{}} |
| 758 | tends to write documents with many equations and finds it impossible |
| 759 | to come up with good names for each of them. These simple labels are |
| 760 | inserted without query, and are therefore very fast. Good descriptive |
| 761 | names are not really necessary as @b{Ref@TeX{}} will provide context to |
| 762 | reference a label (@pxref{Referencing Labels}). |
| 763 | |
| 764 | @item |
| 765 | The third method is to ask the user for a label. This is most |
| 766 | useful for things which are easy to describe briefly and do not turn up |
| 767 | too frequently in a document. @b{Ref@TeX{}} uses this for figures and |
| 768 | tables. Of course, one can enter the label directly by typing the full |
| 769 | @samp{\label@{mark@}}. The advantage of using @code{reftex-label} |
| 770 | anyway is that @b{Ref@TeX{}} will know that a new label has been defined. |
| 771 | It will then not be necessary to rescan the document in order to access |
| 772 | this label later. |
| 773 | @end enumerate |
| 774 | |
| 775 | @vindex reftex-insert-label-flags |
| 776 | If you want to change the way certain labels are created, check out the |
| 777 | variable @code{reftex-insert-label-flags} (@pxref{Options (Creating |
| 778 | Labels)}). |
| 779 | |
| 780 | If you are using AUCTeX to write your LaTeX documents, you can |
| 781 | set it up to delegate the creation of labels to |
| 782 | @b{Ref@TeX{}}. @xref{AUCTeX}, for more information. |
| 783 | |
| 784 | @node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References |
| 785 | @section Referencing Labels |
| 786 | @cindex Referencing labels |
| 787 | @cindex Labels, referencing |
| 788 | @cindex Selection buffer, labels |
| 789 | @cindex Selection process |
| 790 | @cindex @code{\ref} |
| 791 | @kindex C-c ) |
| 792 | @findex reftex-reference |
| 793 | |
| 794 | @vindex reftex-trust-label-prefix |
| 795 | @b{Ref@TeX{}} scans the document in order to find all labels. To make |
| 796 | referencing labels easier, it assigns to each label a category, the |
| 797 | @emph{label type} (for example section, table, figure, equation, etc.). |
| 798 | In order to determine the label type, RefTeX parses around each label |
| 799 | to see in what kind of environments it is located. You can speed up |
| 800 | the parsing by using type-specific prefixes for labels and configuring |
| 801 | the variable @code{reftex-trust-label-prefix}. |
| 802 | |
| 803 | Referencing Labels is really at the heart of @b{Ref@TeX{}}. Press @kbd{C-c |
| 804 | )} in order to reference a label (reftex-reference). This will start a |
| 805 | selection process and finally insert the complete @samp{\ref@{label@}} |
| 806 | into the buffer. |
| 807 | |
| 808 | First, @b{Ref@TeX{}} will determine the label category which is required. |
| 809 | Often that can be figured out from context. For example, if you |
| 810 | write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knows |
| 811 | that an equation label is going to be referenced. If it cannot figure |
| 812 | out what label category is needed, it will query for one. |
| 813 | |
| 814 | You will then be presented with a label selection menu. This is a |
| 815 | special buffer which contains an outline of the document along with all |
| 816 | labels of the given label category. In addition, next to the label |
| 817 | there will be one line of context of the label definition, which is some |
| 818 | text in the buffer near the label definition. Usually this is |
| 819 | sufficient to identify the label. If you are unsure about a certain |
| 820 | label, pressing @key{SPC} will show the label definition point in |
| 821 | another window. |
| 822 | |
| 823 | In order to reference a label, move to cursor to the correct label and |
| 824 | press @key{RET}. You can also reference several labels with a single |
| 825 | call to @code{reftex-reference} by marking entries with the @kbd{m} |
| 826 | key (see below). |
| 827 | |
| 828 | @kindex ? |
| 829 | Here is a list of special commands in the selection buffer. A summary |
| 830 | of this information is always available from the selection process by |
| 831 | pressing @kbd{?}. |
| 832 | |
| 833 | |
| 834 | |
| 835 | @table @kbd |
| 836 | @tablesubheading{General} |
| 837 | @item ? |
| 838 | Show a summary of available commands. |
| 839 | |
| 840 | @item 0-9,- |
| 841 | Prefix argument. |
| 842 | |
| 843 | @tablesubheading{Moving around} |
| 844 | @item n |
| 845 | Go to next label. |
| 846 | |
| 847 | @item p |
| 848 | Go to previous label. |
| 849 | |
| 850 | @item b |
| 851 | Jump back to the position where you last left the selection buffer. |
| 852 | Normally this should get you back to the last referenced label. |
| 853 | |
| 854 | @item C-c C-n |
| 855 | Goto next section heading. |
| 856 | |
| 857 | @item C-c C-p |
| 858 | Goto previous section heading. |
| 859 | |
| 860 | @item N z |
| 861 | Jump to section N, using the prefix arg. For example @kbd{3 z} jumps to |
| 862 | section 3. |
| 863 | |
| 864 | @tablesubheading{Displaying Context} |
| 865 | @item @key{SPC} |
| 866 | Show the surroundings of the definition of the current label in another |
| 867 | window. See also the @kbd{f} key. |
| 868 | |
| 869 | @item f |
| 870 | @vindex reftex-revisit-to-follow |
| 871 | Toggle follow mode. When follow mode is active, the other window will |
| 872 | always display the full context of the current label. This is similar |
| 873 | to pressing @key{SPC} after each cursor motion. Note that only context |
| 874 | in files already visited is shown. @b{RefTeX} will not visit a file |
| 875 | just for follow mode. See, however, the variable |
| 876 | @code{reftex-revisit-to-follow}. |
| 877 | |
| 878 | @item . |
| 879 | Show insertion point in another window. This is the point from where you |
| 880 | called @code{reftex-reference}. |
| 881 | |
| 882 | @tablesubheading{Selecting a label and creating the reference} |
| 883 | @item @key{RET} |
| 884 | Insert a reference to the label at point into the buffer from which the |
| 885 | selection process was started. When entries have been marked, @key{RET} |
| 886 | references all marked labels. |
| 887 | |
| 888 | @item mouse-2 |
| 889 | @vindex reftex-highlight-selection |
| 890 | Clicking with mouse button 2 on a label will accept it like @key{RET} |
| 891 | would. See also variable @code{reftex-highlight-selection}, @ref{Options |
| 892 | (Misc)}. |
| 893 | |
| 894 | @vindex reftex-multiref-punctuation |
| 895 | @item m - + , |
| 896 | Mark the current entry. When several entries have been marked, pressing |
| 897 | @kbd{RET} will accept all of them and place them into several |
| 898 | @code{\ref} macros. The special markers @samp{,-+} also store a |
| 899 | separator to be inserted before the corresponding reference. So marking |
| 900 | six entries with the keys @samp{m , , - , +} will give a reference list |
| 901 | like this (see the variable @code{reftex-multiref-punctuation}) |
| 902 | @example |
| 903 | In eqs. (1), (2), (3)--(4), (5) and (6) |
| 904 | @end example |
| 905 | |
| 906 | @item u |
| 907 | Unmark a marked entry. |
| 908 | |
| 909 | @c FIXME: Do we need `A' as well for consistency? |
| 910 | @cindex LaTeX packages, @code{saferef} |
| 911 | @cindex @code{saferef}, LaTeX package |
| 912 | @item a |
| 913 | Accept the marked entries and put all labels as a comma-separated list |
| 914 | into one @emph{single} @code{\ref} macro. Some packages like |
| 915 | @file{saferef.sty} support multiple references in this way. |
| 916 | |
| 917 | @item l |
| 918 | Use the last referenced label(s) again. This is equivalent to moving to |
| 919 | that label and pressing @key{RET}. |
| 920 | |
| 921 | @item @key{TAB} |
| 922 | Enter a label with completion. This may also be a label which does not |
| 923 | yet exist in the document. |
| 924 | |
| 925 | @item v |
| 926 | @cindex @code{varioref}, LaTeX package |
| 927 | @cindex @code{\vref} |
| 928 | @cindex LaTeX packages, @code{varioref} |
| 929 | Toggle between @code{\ref} and @code{\vref} macro for references. The |
| 930 | @code{\vref} macro is defined in the @code{varioref} LaTeX package. |
| 931 | With this key you can force @b{Ref@TeX{}} to insert a @code{\vref} |
| 932 | macro. The current state of this flag is displayed by the @samp{S<>} |
| 933 | indicator in the mode line of the selection buffer. |
| 934 | |
| 935 | @item V |
| 936 | @cindex @code{fancyref}, LaTeX package |
| 937 | @cindex @code{\fref} |
| 938 | @cindex @code{\Fref} |
| 939 | @cindex LaTeX packages, @code{fancyref} |
| 940 | Cycle between @code{\ref}, @code{\fref} and @code{\Fref}. The |
| 941 | @code{\fref} and @code{\Fref} macros are defined in the @code{fancyref} |
| 942 | LaTeX package. With this key you can force @b{Ref@TeX{}} to insert a |
| 943 | @code{\fref} or @code{\Fref} macro. The current state of this flag is |
| 944 | displayed by the @samp{S<>} indicator in the mode line of the |
| 945 | selection buffer. |
| 946 | |
| 947 | @tablesubheading{Exiting} |
| 948 | |
| 949 | @item q |
| 950 | Exit the selection process without inserting any reference into the |
| 951 | buffer. |
| 952 | |
| 953 | @tablesubheading{Controlling what gets displayed} |
| 954 | @vindex reftex-label-menu-flags |
| 955 | The defaults for the following flags can be configured with the variable |
| 956 | @code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}). |
| 957 | |
| 958 | @item c |
| 959 | Toggle the display of the one-line label definition context in the |
| 960 | selection buffer. |
| 961 | |
| 962 | @item F |
| 963 | Toggle the display of the file borders of a multifile document in the |
| 964 | selection buffer. |
| 965 | |
| 966 | @item t |
| 967 | Toggle the display of the table of contents in the selection buffer. |
| 968 | With prefix @var{arg}, change the maximum level of toc entries displayed |
| 969 | to @var{arg}. Chapters are level 1, section are level 2. |
| 970 | |
| 971 | @item # |
| 972 | Toggle the display of a label counter in the selection buffer. |
| 973 | |
| 974 | @item % |
| 975 | Toggle the display of labels hidden in comments in the selection |
| 976 | buffers. Sometimes, you may have commented out parts of your document. |
| 977 | If these parts contain label definitions, @b{Ref@TeX{}} can still display |
| 978 | and reference these labels. |
| 979 | |
| 980 | @tablesubheading{Updating the buffer} |
| 981 | @item g |
| 982 | Update the menu. This will rebuilt the menu from the internal label |
| 983 | list, but not reparse the document (see @kbd{r}). |
| 984 | |
| 985 | @item r |
| 986 | @vindex reftex-enable-partial-scans |
| 987 | Reparse the document to update the information on all labels and rebuild |
| 988 | the menu. If the variable @code{reftex-enable-partial-scans} is |
| 989 | non-@code{nil} and your document is a multifile document, this will |
| 990 | reparse only a part of the document (the file in which the label at |
| 991 | point was defined). |
| 992 | |
| 993 | @item C-u r |
| 994 | Reparse the @emph{entire} document. |
| 995 | |
| 996 | @item s |
| 997 | Switch the label category. After prompting for another label category, |
| 998 | a menu for that category will be shown. |
| 999 | |
| 1000 | @item x |
| 1001 | Reference a label from an external document. With the LaTeX package |
| 1002 | @code{xr} it is possible to reference labels defined in another |
| 1003 | document. This key will switch to the label menu of an external |
| 1004 | document and let you select a label from there (@pxref{xr (LaTeX |
| 1005 | package),,xr}). |
| 1006 | |
| 1007 | @end table |
| 1008 | |
| 1009 | @vindex reftex-select-label-map |
| 1010 | In order to define additional commands for the selection process, the |
| 1011 | keymap @code{reftex-select-label-map} may be used. |
| 1012 | |
| 1013 | @node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References |
| 1014 | @section Builtin Label Environments |
| 1015 | @cindex Builtin label environments |
| 1016 | @cindex Label environments, builtin |
| 1017 | @cindex Environments, builtin |
| 1018 | @vindex reftex-label-alist |
| 1019 | @vindex reftex-label-alist-builtin |
| 1020 | |
| 1021 | @b{Ref@TeX{}} needs to be aware of the environments which can be referenced |
| 1022 | with a label (i.e. which carry their own counters). By default, @b{Ref@TeX{}} |
| 1023 | recognizes all labeled environments and macros discussed in @cite{The |
| 1024 | LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley |
| 1025 | 1994.}. These are: |
| 1026 | |
| 1027 | @itemize @minus |
| 1028 | @item |
| 1029 | @cindex @code{figure}, LaTeX environment |
| 1030 | @cindex @code{figure*}, LaTeX environment |
| 1031 | @cindex @code{table}, LaTeX environment |
| 1032 | @cindex @code{table*}, LaTeX environment |
| 1033 | @cindex @code{equation}, LaTeX environment |
| 1034 | @cindex @code{eqnarray}, LaTeX environment |
| 1035 | @cindex @code{enumerate}, LaTeX environment |
| 1036 | @cindex @code{\footnote}, LaTeX macro |
| 1037 | @cindex LaTeX macro @code{footnote} |
| 1038 | @cindex LaTeX core |
| 1039 | @code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation}, |
| 1040 | @code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is |
| 1041 | the LaTeX core stuff) |
| 1042 | @item |
| 1043 | @cindex AMS-LaTeX |
| 1044 | @cindex @code{amsmath}, LaTeX package |
| 1045 | @cindex LaTeX packages, @code{amsmath} |
| 1046 | @cindex @code{align}, AMS-LaTeX environment |
| 1047 | @cindex @code{gather}, AMS-LaTeX environment |
| 1048 | @cindex @code{multline}, AMS-LaTeX environment |
| 1049 | @cindex @code{flalign}, AMS-LaTeX environment |
| 1050 | @cindex @code{alignat}, AMS-LaTeX environment |
| 1051 | @cindex @code{xalignat}, AMS-LaTeX environment |
| 1052 | @cindex @code{xxalignat}, AMS-LaTeX environment |
| 1053 | @cindex @code{subequations}, AMS-LaTeX environment |
| 1054 | @code{align}, @code{gather}, @code{multline}, @code{flalign}, |
| 1055 | @code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations} |
| 1056 | (from AMS-LaTeX's @file{amsmath.sty} package) |
| 1057 | @item |
| 1058 | @cindex @code{endnote}, LaTeX package |
| 1059 | @cindex LaTeX packages, @code{endnote} |
| 1060 | @cindex @code{\endnote}, LaTeX macro |
| 1061 | the @code{\endnote} macro (from @file{endnotes.sty}) |
| 1062 | @item |
| 1063 | @cindex @code{fancybox}, LaTeX package |
| 1064 | @cindex LaTeX packages, @code{fancybox} |
| 1065 | @cindex @code{Beqnarray}, LaTeX environment |
| 1066 | @code{Beqnarray} (@file{fancybox.sty}) |
| 1067 | @item |
| 1068 | @cindex @code{floatfig}, LaTeX package |
| 1069 | @cindex LaTeX packages, @code{floatfig} |
| 1070 | @cindex @code{floatingfig}, LaTeX environment |
| 1071 | @code{floatingfig} (@file{floatfig.sty}) |
| 1072 | @item |
| 1073 | @cindex @code{longtable}, LaTeX package |
| 1074 | @cindex LaTeX packages, @code{longtable} |
| 1075 | @cindex @code{longtable}, LaTeX environment |
| 1076 | @code{longtable} (@file{longtable.sty}) |
| 1077 | @item |
| 1078 | @cindex @code{picinpar}, LaTeX package |
| 1079 | @cindex LaTeX packages, @code{picinpar} |
| 1080 | @cindex @code{figwindow}, LaTeX environment |
| 1081 | @cindex @code{tabwindow}, LaTeX environment |
| 1082 | @code{figwindow}, @code{tabwindow} (@file{picinpar.sty}) |
| 1083 | @item |
| 1084 | @cindex @code{sidecap}, LaTeX package |
| 1085 | @cindex LaTeX packages, @code{sidecap} |
| 1086 | @cindex @code{SCfigure}, LaTeX environment |
| 1087 | @cindex @code{SCtable}, LaTeX environment |
| 1088 | @code{SCfigure}, @code{SCtable} (@file{sidecap.sty}) |
| 1089 | @item |
| 1090 | @cindex @code{rotating}, LaTeX package |
| 1091 | @cindex LaTeX packages, @code{rotating} |
| 1092 | @cindex @code{sidewaysfigure}, LaTeX environment |
| 1093 | @cindex @code{sidewaystable}, LaTeX environment |
| 1094 | @code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty}) |
| 1095 | @item |
| 1096 | @cindex @code{subfig}, LaTeX package |
| 1097 | @cindex LaTeX packages, @code{subfigure} |
| 1098 | @cindex @code{subfigure}, LaTeX environment |
| 1099 | @cindex @code{subfigure*}, LaTeX environment |
| 1100 | @code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro |
| 1101 | (@file{subfigure.sty}) |
| 1102 | @item |
| 1103 | @cindex @code{supertab}, LaTeX package |
| 1104 | @cindex LaTeX packages, @code{supertab} |
| 1105 | @cindex @code{supertabular}, LaTeX environment |
| 1106 | @code{supertabular} (@file{supertab.sty}) |
| 1107 | @item |
| 1108 | @cindex @code{wrapfig}, LaTeX package |
| 1109 | @cindex LaTeX packages, @code{wrapfig} |
| 1110 | @cindex @code{wrapfigure}, LaTeX environment |
| 1111 | @code{wrapfigure} (@file{wrapfig.sty}) |
| 1112 | @end itemize |
| 1113 | |
| 1114 | If you want to use other labeled environments, defined with |
| 1115 | @code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize |
| 1116 | them (@pxref{Defining Label Environments}). |
| 1117 | |
| 1118 | @node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References |
| 1119 | @section Defining Label Environments |
| 1120 | @cindex Label environments, defining |
| 1121 | |
| 1122 | @vindex reftex-label-alist |
| 1123 | @b{Ref@TeX{}} can be configured to recognize additional labeled |
| 1124 | environments and macros. This is done with the variable |
| 1125 | @code{reftex-label-alist} (@pxref{Options (Defining Label |
| 1126 | Environments)}). If you are not familiar with Lisp, you can use the |
| 1127 | @code{custom} library to configure this rather complex variable. To do |
| 1128 | this, use |
| 1129 | |
| 1130 | @example |
| 1131 | @kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}} |
| 1132 | @end example |
| 1133 | |
| 1134 | @vindex reftex-label-alist-builtin |
| 1135 | Here we will discuss a few examples, in order to make things clearer. |
| 1136 | It can also be instructive to look at the constant |
| 1137 | @code{reftex-label-alist-builtin} which contains the entries for |
| 1138 | all the builtin environments and macros (@pxref{Builtin Label |
| 1139 | Environments}). |
| 1140 | |
| 1141 | @menu |
| 1142 | * Theorem and Axiom:: Defined with @code{\newenvironment}. |
| 1143 | * Quick Equation:: When a macro sets the label type. |
| 1144 | * Figure Wrapper:: When a macro argument is a label. |
| 1145 | * Adding Magic Words:: Other words for other languages. |
| 1146 | * Using \eqref:: How to switch to this AMS-LaTeX macro. |
| 1147 | * Non-Standard Environments:: Environments without \begin and \end |
| 1148 | * Putting it Together:: How to combine many entries. |
| 1149 | @end menu |
| 1150 | |
| 1151 | @node Theorem and Axiom, Quick Equation, , Defining Label Environments |
| 1152 | @subsection Theorem and Axiom Environments |
| 1153 | @cindex @code{theorem}, newtheorem |
| 1154 | @cindex @code{axiom}, newtheorem |
| 1155 | @cindex @code{\newtheorem} |
| 1156 | |
| 1157 | Suppose you are using @code{\newtheorem} in LaTeX in order to define two |
| 1158 | new environments, @code{theorem} and @code{axiom} |
| 1159 | |
| 1160 | @example |
| 1161 | \newtheorem@{axiom@}@{Axiom@} |
| 1162 | \newtheorem@{theorem@}@{Theorem@} |
| 1163 | @end example |
| 1164 | |
| 1165 | @noindent |
| 1166 | to be used like this: |
| 1167 | |
| 1168 | @example |
| 1169 | \begin@{axiom@} |
| 1170 | \label@{ax:first@} |
| 1171 | .... |
| 1172 | \end@{axiom@} |
| 1173 | @end example |
| 1174 | |
| 1175 | So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new |
| 1176 | labeled environments which define their own label categories. We can |
| 1177 | either use Lisp to do this (e.g. in @file{.emacs}) or use the custom |
| 1178 | library. With Lisp it would look like this |
| 1179 | |
| 1180 | @lisp |
| 1181 | (setq reftex-label-alist |
| 1182 | '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2) |
| 1183 | ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "th.") -3))) |
| 1184 | @end lisp |
| 1185 | |
| 1186 | The type indicator characters @code{?a} and @code{?h} are used for |
| 1187 | prompts when @b{Ref@TeX{}} queries for a label type. @code{?h} |
| 1188 | was chosen for @code{theorem} since @code{?t} is already taken by |
| 1189 | @code{table}. Note that also @code{?s}, @code{?f}, @code{?e}, |
| 1190 | @code{?i}, @code{?n} are already used for standard environments. |
| 1191 | |
| 1192 | @noindent |
| 1193 | The labels for Axioms and Theorems will have the prefixes @samp{ax:} and |
| 1194 | @samp{thr:}, respectively. @xref{AUCTeX}, for information on how |
| 1195 | AUCTeX can use RefTeX to automatically create labels when a new environment |
| 1196 | is inserted into a buffer. Additionally, the following needs to be |
| 1197 | added to one's .emacs file before AUCTeX will automatically create |
| 1198 | labels for the new environments. |
| 1199 | |
| 1200 | @lisp |
| 1201 | (add-hook 'LaTeX-mode-hook |
| 1202 | (lambda () |
| 1203 | (LaTeX-add-environments |
| 1204 | '("axiom" LaTeX-env-label) |
| 1205 | '("theorem" LaTeX-env-label)))) |
| 1206 | @end lisp |
| 1207 | |
| 1208 | |
| 1209 | @noindent |
| 1210 | The @samp{~\ref@{%s@}} is a format string indicating how to insert |
| 1211 | references to these labels. |
| 1212 | |
| 1213 | @noindent |
| 1214 | The next item indicates how to grab context of the label definition. |
| 1215 | @itemize @minus |
| 1216 | @item |
| 1217 | @code{t} means to get it from a default location (from the beginning of |
| 1218 | a @code{\macro} or after the @code{\begin} statement). @code{t} is |
| 1219 | @emph{not} a good choice for eqnarray and similar environments. |
| 1220 | @item |
| 1221 | @code{nil} means to use the text right after the label definition. |
| 1222 | @item |
| 1223 | For more complex ways of getting context, see the variable |
| 1224 | @code{reftex-label-alist} (@ref{Options (Defining Label |
| 1225 | Environments)}). |
| 1226 | @end itemize |
| 1227 | |
| 1228 | The following list of strings is used to guess the correct label type |
| 1229 | from the word before point when creating a reference. E.g. if you |
| 1230 | write: @samp{As we have shown in Theorem} and then press @kbd{C-c )}, |
| 1231 | @b{Ref@TeX{}} will know that you are looking for a theorem label and |
| 1232 | restrict the menu to only these labels without even asking. |
| 1233 | |
| 1234 | The final item in each entry is the level at which the environment |
| 1235 | should produce entries in the table of context buffer. If the number is |
| 1236 | positive, the environment will produce numbered entries (like |
| 1237 | @code{\section}), if it is negative the entries will be unnumbered (like |
| 1238 | @code{\section*}). Use this only for environments which structure the |
| 1239 | document similar to sectioning commands. For everything else, omit the |
| 1240 | item. |
| 1241 | |
| 1242 | To do the same configuration with @code{customize}, you need to click on |
| 1243 | the @code{[INS]} button twice to create two templates and fill them in |
| 1244 | like this: |
| 1245 | |
| 1246 | @example |
| 1247 | Reftex Label Alist: [Hide] |
| 1248 | [INS] [DEL] Package or Detailed : [Value Menu] Detailed: |
| 1249 | Environment or \macro : [Value Menu] String: axiom |
| 1250 | Type specification : [Value Menu] Char : a |
| 1251 | Label prefix string : [Value Menu] String: ax: |
| 1252 | Label reference format: [Value Menu] String: ~\ref@{%s@} |
| 1253 | Context method : [Value Menu] After label |
| 1254 | Magic words: |
| 1255 | [INS] [DEL] String: axiom |
| 1256 | [INS] [DEL] String: ax. |
| 1257 | [INS] |
| 1258 | [X] Make TOC entry : [Value Menu] Level: -2 |
| 1259 | [INS] [DEL] Package or Detailed : [Value Menu] Detailed: |
| 1260 | Environment or \macro : [Value Menu] String: theorem |
| 1261 | Type specification : [Value Menu] Char : h |
| 1262 | Label prefix string : [Value Menu] String: thr: |
| 1263 | Label reference format: [Value Menu] String: ~\ref@{%s@} |
| 1264 | Context method : [Value Menu] Default position |
| 1265 | Magic words: |
| 1266 | [INS] [DEL] String: theorem |
| 1267 | [INS] [DEL] String: theor. |
| 1268 | [INS] [DEL] String: th. |
| 1269 | [INS] |
| 1270 | [X] Make TOC entry : [Value Menu] Level: -3 |
| 1271 | @end example |
| 1272 | |
| 1273 | @vindex reftex-insert-label-flags |
| 1274 | @vindex reftex-label-menu-flags |
| 1275 | Depending on how you would like the label insertion and selection for |
| 1276 | the new environments to work, you might want to add the letters @samp{a} |
| 1277 | and @samp{h} to some of the flags in the variables |
| 1278 | @code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)}) |
| 1279 | and @code{reftex-label-menu-flags} (@pxref{Options (Referencing |
| 1280 | Labels)}). |
| 1281 | |
| 1282 | |
| 1283 | @node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments |
| 1284 | @subsection Quick Equation Macro |
| 1285 | @cindex Quick equation macro |
| 1286 | @cindex Macros as environment wrappers |
| 1287 | |
| 1288 | Suppose you would like to have a macro for quick equations. It |
| 1289 | could be defined like this: |
| 1290 | |
| 1291 | @example |
| 1292 | \newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@} |
| 1293 | @end example |
| 1294 | |
| 1295 | @noindent |
| 1296 | and used like this: |
| 1297 | |
| 1298 | @example |
| 1299 | Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}. |
| 1300 | @end example |
| 1301 | |
| 1302 | We need to tell @b{Ref@TeX{}} that any label defined in the argument of the |
| 1303 | @code{\quickeq} is an equation label. Here is how to do this with lisp: |
| 1304 | |
| 1305 | @lisp |
| 1306 | (setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil))) |
| 1307 | @end lisp |
| 1308 | |
| 1309 | The first element in this list is now the macro with empty braces as an |
| 1310 | @emph{image} of the macro arguments. @code{?e} indicates that this is |
| 1311 | an equation label, the different @code{nil} elements indicate to use the |
| 1312 | default values for equations. The @samp{1} as the fifth element |
| 1313 | indicates that the context of the label definition should be the 1st |
| 1314 | argument of the macro. |
| 1315 | |
| 1316 | Here is again how this would look in the customization buffer: |
| 1317 | |
| 1318 | @example |
| 1319 | Reftex Label Alist: [Hide] |
| 1320 | [INS] [DEL] Package or Detailed : [Value Menu] Detailed: |
| 1321 | Environment or \macro : [Value Menu] String: \quickeq@{@} |
| 1322 | Type specification : [Value Menu] Char : e |
| 1323 | Label prefix string : [Value Menu] Default |
| 1324 | Label reference format: [Value Menu] Default |
| 1325 | Context method : [Value Menu] Macro arg nr: 1 |
| 1326 | Magic words: |
| 1327 | [INS] |
| 1328 | [ ] Make TOC entry : [Value Menu] No entry |
| 1329 | @end example |
| 1330 | |
| 1331 | @node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments |
| 1332 | @subsection Figure Wrapping Macro |
| 1333 | @cindex Macros as environment wrappers |
| 1334 | @cindex Figure wrapping macro |
| 1335 | |
| 1336 | Suppose you want to make figures not directly with the figure |
| 1337 | environment, but with a macro like |
| 1338 | |
| 1339 | @example |
| 1340 | \newcommand@{\myfig@}[5][tbp]@{% |
| 1341 | \begin@{figure@}[#1] |
| 1342 | \epsimp[#5]@{#2@} |
| 1343 | \caption@{#3@} |
| 1344 | \label@{#4@} |
| 1345 | \end@{figure@}@} |
| 1346 | @end example |
| 1347 | |
| 1348 | @noindent |
| 1349 | which would be called like |
| 1350 | |
| 1351 | @example |
| 1352 | \myfig[htp]@{filename@}@{caption text@}@{label@}@{1@} |
| 1353 | @end example |
| 1354 | |
| 1355 | Now we need to tell @b{Ref@TeX{}} that the 4th argument of the |
| 1356 | @code{\myfig} macro @emph{is itself} a figure label, and where to find |
| 1357 | the context. |
| 1358 | |
| 1359 | @lisp |
| 1360 | (setq reftex-label-alist |
| 1361 | '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3))) |
| 1362 | @end lisp |
| 1363 | |
| 1364 | The empty pairs of brackets indicate the different arguments of the |
| 1365 | @code{\myfig} macro. The @samp{*} marks the label argument. @code{?f} |
| 1366 | indicates that this is a figure label which will be listed together with |
| 1367 | labels from normal figure environments. The @code{nil} entries for |
| 1368 | prefix and reference format mean to use the defaults for figure labels. |
| 1369 | The @samp{3} for the context method means to grab the 3rd macro argument |
| 1370 | - the caption. |
| 1371 | |
| 1372 | As a side effect of this configuration, @code{reftex-label} will now |
| 1373 | insert the required naked label (without the @code{\label} macro) when |
| 1374 | point is directly after the opening parenthesis of a @code{\myfig} macro |
| 1375 | argument. |
| 1376 | |
| 1377 | Again, here the configuration in the customization buffer: |
| 1378 | |
| 1379 | @example |
| 1380 | [INS] [DEL] Package or Detailed : [Value Menu] Detailed: |
| 1381 | Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@} |
| 1382 | Type specification : [Value Menu] Char : f |
| 1383 | Label prefix string : [Value Menu] Default |
| 1384 | Label reference format: [Value Menu] Default |
| 1385 | Context method : [Value Menu] Macro arg nr: 3 |
| 1386 | Magic words: |
| 1387 | [INS] |
| 1388 | [ ] Make TOC entry : [Value Menu] No entry |
| 1389 | @end example |
| 1390 | |
| 1391 | @node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments |
| 1392 | @subsection Adding Magic Words |
| 1393 | @cindex Magic words |
| 1394 | @cindex German magic words |
| 1395 | @cindex Label category |
| 1396 | |
| 1397 | Sometimes you don't want to define a new label environment or macro, but |
| 1398 | just change the information associated with a label category. Maybe you |
| 1399 | want to add some magic words, for another language. Changing only the |
| 1400 | information associated with a label category is done by giving |
| 1401 | @code{nil} for the environment name and then specify the items you want |
| 1402 | to define. Here is an example which adds German magic words to all |
| 1403 | predefined label categories. |
| 1404 | |
| 1405 | @lisp |
| 1406 | (setq reftex-label-alist |
| 1407 | '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil")) |
| 1408 | (nil ?e nil nil nil ("Gleichung" "Gl.")) |
| 1409 | (nil ?t nil nil nil ("Tabelle")) |
| 1410 | (nil ?f nil nil nil ("Figur" "Abbildung" "Abb.")) |
| 1411 | (nil ?n nil nil nil ("Anmerkung" "Anm.")) |
| 1412 | (nil ?i nil nil nil ("Punkt")))) |
| 1413 | @end lisp |
| 1414 | |
| 1415 | @node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments |
| 1416 | @subsection Using @code{\eqref} |
| 1417 | @cindex @code{\eqref}, AMS-LaTeX macro |
| 1418 | @cindex AMS-LaTeX |
| 1419 | @cindex Label category |
| 1420 | |
| 1421 | Another case where one only wants to change the information associated |
| 1422 | with the label category is to change the macro which is used for |
| 1423 | referencing the label. When working with the AMS-LaTeX stuff, you might |
| 1424 | prefer @code{\eqref} for doing equation references. Here is how to |
| 1425 | do this: |
| 1426 | |
| 1427 | @lisp |
| 1428 | (setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil))) |
| 1429 | @end lisp |
| 1430 | |
| 1431 | @b{Ref@TeX{}} has also a predefined symbol for this special purpose. The |
| 1432 | following is equivalent to the line above. |
| 1433 | |
| 1434 | @lisp |
| 1435 | (setq reftex-label-alist '(AMSTeX)) |
| 1436 | @end lisp |
| 1437 | |
| 1438 | Note that this is automatically done by the @file{amsmath.el} style file |
| 1439 | of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX, |
| 1440 | this configuration will not be necessary. |
| 1441 | |
| 1442 | @node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments |
| 1443 | @subsection Non-standard Environments |
| 1444 | @cindex Non-standard environments |
| 1445 | @cindex Environments without @code{\begin} |
| 1446 | @cindex Special parser functions |
| 1447 | @cindex Parser functions, for special environments |
| 1448 | |
| 1449 | Some LaTeX packages define environment-like structures without using the |
| 1450 | standard @samp{\begin..\end} structure. @b{Ref@TeX{}} cannot parse |
| 1451 | these directly, but you can write your own special-purpose parser and |
| 1452 | use it instead of the name of an environment in an entry for |
| 1453 | @code{reftex-label-alist}. The function should check if point is |
| 1454 | currently in the special environment it was written to detect. If so, |
| 1455 | it must return a buffer position indicating the start of this |
| 1456 | environment. The return value must be @code{nil} on failure to detect |
| 1457 | the environment. The function is called with one argument @var{bound}. |
| 1458 | If non-@code{nil}, @var{bound} is a boundary for backwards searches |
| 1459 | which should be observed. We will discuss two examples. |
| 1460 | |
| 1461 | @cindex LaTeX commands, abbreviated |
| 1462 | |
| 1463 | Some people define abbreviations for |
| 1464 | environments, like @code{\be} for @code{\begin@{equation@}}, and |
| 1465 | @code{\ee} for @code{\end@{equation@}}. The parser function would have |
| 1466 | to search backward for these macros. When the first match is |
| 1467 | @code{\ee}, point is not in this environment. When the first match is |
| 1468 | @code{\be}, point is in this environment and the function must return |
| 1469 | the beginning of the match. To avoid scanning too far, we can also look |
| 1470 | for empty lines which cannot occur inside an equation environment. |
| 1471 | Here is the setup: |
| 1472 | |
| 1473 | @lisp |
| 1474 | ;; Setup entry in reftex-label-alist, using all defaults for equations |
| 1475 | (setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil))) |
| 1476 | |
| 1477 | (defun detect-be-ee (bound) |
| 1478 | ;; Search backward for the macros or an empty line |
| 1479 | (if (re-search-backward |
| 1480 | "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t) |
| 1481 | (if (match-beginning 2) |
| 1482 | (match-beginning 2) ; Return start of environment |
| 1483 | nil) ; Return nil because env is closed |
| 1484 | nil)) ; Return nil for not found |
| 1485 | @end lisp |
| 1486 | |
| 1487 | @cindex @code{linguex}, LaTeX package |
| 1488 | @cindex LaTeX packages, @code{linguex} |
| 1489 | A more complex example is the @file{linguex.sty} package which defines |
| 1490 | list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are |
| 1491 | terminated by @samp{\z.} or by an empty line. |
| 1492 | |
| 1493 | @example |
| 1494 | \ex. \label@{ex:12@} Some text in an exotic language ... |
| 1495 | \a. \label@{ex:13@} more stuff |
| 1496 | \b. \label@{ex:14@} still more stuff |
| 1497 | \a. List on a deeper level |
| 1498 | \b. Another item |
| 1499 | \b. and the third one |
| 1500 | \z. |
| 1501 | \b. Third item on this level. |
| 1502 | |
| 1503 | ... text after the empty line terminating all lists |
| 1504 | @end example |
| 1505 | |
| 1506 | The difficulty is that the @samp{\a.} lists can nest and that an empty |
| 1507 | line terminates all list levels in one go. So we have to count nesting |
| 1508 | levels between @samp{\a.} and @samp{\z.}. Here is the implementation |
| 1509 | for @b{Ref@TeX{}}. |
| 1510 | |
| 1511 | @lisp |
| 1512 | (setq reftex-label-alist |
| 1513 | '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) |
| 1514 | |
| 1515 | (defun detect-linguex (bound) |
| 1516 | (let ((cnt 0)) |
| 1517 | (catch 'exit |
| 1518 | (while |
| 1519 | ;; Search backward for all possible delimiters |
| 1520 | (re-search-backward |
| 1521 | (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|" |
| 1522 | "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)") |
| 1523 | nil t) |
| 1524 | ;; Check which delimiter was matched. |
| 1525 | (cond |
| 1526 | ((match-beginning 1) |
| 1527 | ;; empty line terminates all - return nil |
| 1528 | (throw 'exit nil)) |
| 1529 | ((match-beginning 2) |
| 1530 | ;; \z. terminates one list level - decrease nesting count |
| 1531 | (decf cnt)) |
| 1532 | ((match-beginning 3) |
| 1533 | ;; \ex. : return match unless there was a \z. on this level |
| 1534 | (throw 'exit (if (>= cnt 0) (match-beginning 3) nil))) |
| 1535 | ((match-beginning 4) |
| 1536 | ;; \a. : return match when on level 0, otherwise |
| 1537 | ;; increment nesting count |
| 1538 | (if (>= cnt 0) |
| 1539 | (throw 'exit (match-beginning 4)) |
| 1540 | (incf cnt)))))))) |
| 1541 | @end lisp |
| 1542 | |
| 1543 | @node Putting it Together, , Non-Standard Environments, Defining Label Environments |
| 1544 | @subsection Putting it all together |
| 1545 | |
| 1546 | When you have to put several entries into @code{reftex-label-alist}, just |
| 1547 | put them after each other in a list, or create that many templates in |
| 1548 | the customization buffer. Here is a lisp example which uses several of |
| 1549 | the entries described above: |
| 1550 | |
| 1551 | @lisp |
| 1552 | (setq reftex-label-alist |
| 1553 | '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.") -2) |
| 1554 | ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.") -3) |
| 1555 | ("\\quickeq@{@}" ?e nil nil 1 nil) |
| 1556 | AMSTeX |
| 1557 | ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3) |
| 1558 | (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) |
| 1559 | @end lisp |
| 1560 | |
| 1561 | @node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References |
| 1562 | @section Reference Info |
| 1563 | @findex reftex-view-crossref |
| 1564 | @findex reftex-mouse-view-crossref |
| 1565 | @cindex Cross-references, displaying |
| 1566 | @cindex Reference info |
| 1567 | @cindex Displaying cross-references |
| 1568 | @cindex Viewing cross-references |
| 1569 | @kindex C-c & |
| 1570 | @kindex S-mouse-2 |
| 1571 | |
| 1572 | When point is idle for more than @code{reftex-idle-time} seconds on the |
| 1573 | argument of a @code{\ref} macro, the echo area will display some |
| 1574 | information about the label referenced there. Note that the information |
| 1575 | is only displayed if the echo area is not occupied by a different |
| 1576 | message. |
| 1577 | |
| 1578 | @b{Ref@TeX{}} can also display the label definition corresponding to a |
| 1579 | @code{\ref} macro, or all reference locations corresponding to a |
| 1580 | @code{\label} macro. @xref{Viewing Cross-References}, for more |
| 1581 | information. |
| 1582 | |
| 1583 | @node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References |
| 1584 | @section @code{xr}: Cross-Document References |
| 1585 | @cindex @code{xr}, LaTeX package |
| 1586 | @cindex LaTeX packages, @code{xr} |
| 1587 | @cindex @code{\externaldocument} |
| 1588 | @cindex External documents |
| 1589 | @cindex References to external documents |
| 1590 | @cindex Cross-document references |
| 1591 | |
| 1592 | The LaTeX package @code{xr} makes it possible to create references to |
| 1593 | labels defined in external documents. The preamble of a document using |
| 1594 | @code{xr} will contain something like this: |
| 1595 | |
| 1596 | @example |
| 1597 | \usepackage@{xr@} |
| 1598 | \externaldocument[V1-]@{volume1@} |
| 1599 | \externaldocument[V3-]@{volume3@} |
| 1600 | @end example |
| 1601 | |
| 1602 | @noindent |
| 1603 | and we can make references to any labels defined in these |
| 1604 | external documents by using the prefixes @samp{V1-} and @samp{V3-}, |
| 1605 | respectively. |
| 1606 | |
| 1607 | @b{Ref@TeX{}} can be used to create such references as well. Start the |
| 1608 | referencing process normally, by pressing @kbd{C-c )}. Select a label |
| 1609 | type if necessary. When you see the label selection buffer, pressing |
| 1610 | @kbd{x} will switch to the label selection buffer of one of the external |
| 1611 | documents. You may then select a label as before and @b{Ref@TeX{}} will |
| 1612 | insert it along with the required prefix. |
| 1613 | |
| 1614 | For this kind of inter-document cross-references, saving of parsing |
| 1615 | information and the use of multiple selection buffers can mean a large |
| 1616 | speed-up (@pxref{Optimizations}). |
| 1617 | |
| 1618 | @node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References |
| 1619 | @section @code{varioref}: Variable Page References |
| 1620 | @cindex @code{varioref}, LaTeX package |
| 1621 | @cindex @code{\vref} |
| 1622 | @cindex LaTeX packages, @code{varioref} |
| 1623 | @vindex reftex-vref-is-default |
| 1624 | @code{varioref} is a frequently used LaTeX package to create |
| 1625 | cross--references with page information. When you want to make a |
| 1626 | reference with the @code{\vref} macro, just press the @kbd{v} key in the |
| 1627 | selection buffer to toggle between @code{\ref} and @code{\vref} |
| 1628 | (@pxref{Referencing Labels}). The mode line of the selection buffer |
| 1629 | shows the current status of this switch. If you find that you almost |
| 1630 | always use @code{\vref}, you may want to make it the default by |
| 1631 | customizing the variable @code{reftex-vref-is-default}. If this |
| 1632 | toggling seems too inconvenient, you can also use the command |
| 1633 | @code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}. |
| 1634 | Or use AUCTeX to create your macros (@pxref{AUCTeX}). |
| 1635 | |
| 1636 | @node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References |
| 1637 | @section @code{fancyref}: Fancy Cross References |
| 1638 | @cindex @code{fancyref}, LaTeX package |
| 1639 | @cindex @code{\fref} |
| 1640 | @cindex @code{\Fref} |
| 1641 | @cindex LaTeX packages, @code{fancyref} |
| 1642 | @vindex reftex-fref-is-default |
| 1643 | @code{fancyref} is a LaTeX package where a macro call like |
| 1644 | @code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of |
| 1645 | the referenced counter but also the complete text around it, like |
| 1646 | @samp{Figure 3 on the preceding page}. In order to make it work you |
| 1647 | need to use label prefixes like @samp{fig:} consistently - something |
| 1648 | @b{Ref@TeX{}} does automatically. When you want to make a reference |
| 1649 | with the @code{\fref} macro, just press the @kbd{V} key in the selection |
| 1650 | buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref} |
| 1651 | (@pxref{Referencing Labels}). The mode line of the selection buffer |
| 1652 | shows the current status of this switch. If this cycling seems |
| 1653 | inconvenient, you can also use the commands @code{reftex-fancyref-fref} |
| 1654 | and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c |
| 1655 | f} and @kbd{C-c F}.}. Or use AUCTeX to create your macros |
| 1656 | (@pxref{AUCTeX}). |
| 1657 | |
| 1658 | @node Citations, Index Support, Labels and References, Top |
| 1659 | @chapter Citations |
| 1660 | @cindex Citations |
| 1661 | @cindex @code{\cite} |
| 1662 | |
| 1663 | Citations in LaTeX are done with the @code{\cite} macro or variations of |
| 1664 | it. The argument of the macro is a citation key which identifies an |
| 1665 | article or book in either a BibTeX database file or in an explicit |
| 1666 | @code{thebibliography} environment in the document. @b{Ref@TeX{}}'s |
| 1667 | support for citations helps to select the correct key quickly. |
| 1668 | |
| 1669 | @menu |
| 1670 | * Creating Citations:: How to create them. |
| 1671 | * Citation Styles:: Natbib, Harvard, Chicago and Co. |
| 1672 | * Citation Info:: View the corresponding database entry. |
| 1673 | * Chapterbib and Bibunits:: Multiple bibliographies in a Document. |
| 1674 | * Citations Outside LaTeX:: How to make citations in Emails etc. |
| 1675 | * BibTeX Database Subsets:: Extract parts of a big database. |
| 1676 | @end menu |
| 1677 | |
| 1678 | @node Creating Citations, Citation Styles, , Citations |
| 1679 | @section Creating Citations |
| 1680 | @cindex Creating citations |
| 1681 | @cindex Citations, creating |
| 1682 | @findex reftex-citation |
| 1683 | @kindex C-c [ |
| 1684 | @cindex Selection buffer, citations |
| 1685 | @cindex Selection process |
| 1686 | |
| 1687 | In order to create a citation, press @kbd{C-c [}. @b{Ref@TeX{}} then |
| 1688 | prompts for a regular expression which will be used to search through |
| 1689 | the database and present the list of matches to choose from in a |
| 1690 | selection process similar to that for selecting labels |
| 1691 | (@pxref{Referencing Labels}). |
| 1692 | |
| 1693 | The regular expression uses an extended syntax: @samp{&&} defines a |
| 1694 | logic @code{and} for regular expressions. For example |
| 1695 | @samp{Einstein&&Bose} will match all articles which mention |
| 1696 | Bose-Einstein condensation, or which are co-authored by Bose and |
| 1697 | Einstein. When entering the regular expression, you can complete on |
| 1698 | known citation keys. RefTeX also offers a default when prompting for a |
| 1699 | regular expression. This default is the word before the cursor or the |
| 1700 | word before the current @samp{\cite} command. Sometimes this may be a |
| 1701 | good search key. |
| 1702 | |
| 1703 | @cindex @code{\bibliography} |
| 1704 | @cindex @code{thebibliography}, LaTeX environment |
| 1705 | @cindex @code{BIBINPUTS}, environment variable |
| 1706 | @cindex @code{TEXBIB}, environment variable |
| 1707 | @b{Ref@TeX{}} prefers to use BibTeX database files specified with a |
| 1708 | @code{\bibliography} macro to collect its information. Just like |
| 1709 | BibTeX, it will search for the specified files in the current directory |
| 1710 | and along the path given in the environment variable @code{BIBINPUTS}. |
| 1711 | If you do not use BibTeX, but the document contains an explicit |
| 1712 | @code{thebibliography} environment, @b{Ref@TeX{}} will collect its |
| 1713 | information from there. Note that in this case the information |
| 1714 | presented in the selection buffer will just be a copy of relevant |
| 1715 | @code{\bibitem} entries, not the structured listing available with |
| 1716 | BibTeX database files. |
| 1717 | |
| 1718 | @kindex ? |
| 1719 | In the selection buffer, the following keys provide special commands. A |
| 1720 | summary of this information is always available from the selection |
| 1721 | process by pressing @kbd{?}. |
| 1722 | |
| 1723 | @table @kbd |
| 1724 | @tablesubheading{General} |
| 1725 | @item ? |
| 1726 | Show a summary of available commands. |
| 1727 | |
| 1728 | @item 0-9,- |
| 1729 | Prefix argument. |
| 1730 | |
| 1731 | @tablesubheading{Moving around} |
| 1732 | @item n |
| 1733 | Go to next article. |
| 1734 | |
| 1735 | @item p |
| 1736 | Go to previous article. |
| 1737 | |
| 1738 | @tablesubheading{Access to full database entries} |
| 1739 | @item @key{SPC} |
| 1740 | Show the database entry corresponding to the article at point, in |
| 1741 | another window. See also the @kbd{f} key. |
| 1742 | |
| 1743 | @item f |
| 1744 | Toggle follow mode. When follow mode is active, the other window will |
| 1745 | always display the full database entry of the current article. This is |
| 1746 | equivalent to pressing @key{SPC} after each cursor motion. With BibTeX |
| 1747 | entries, follow mode can be rather slow. |
| 1748 | |
| 1749 | @tablesubheading{Selecting entries and creating the citation} |
| 1750 | @item @key{RET} |
| 1751 | Insert a citation referencing the article at point into the buffer from |
| 1752 | which the selection process was started. |
| 1753 | |
| 1754 | @item mouse-2 |
| 1755 | @vindex reftex-highlight-selection |
| 1756 | Clicking with mouse button 2 on a citation will accept it like @key{RET} |
| 1757 | would. See also variable @code{reftex-highlight-selection}, @ref{Options |
| 1758 | (Misc)}. |
| 1759 | |
| 1760 | @item m |
| 1761 | Mark the current entry. When one or several entries are marked, |
| 1762 | pressing @kbd{a} or @kbd{A} accepts all marked entries. Also, |
| 1763 | @key{RET} behaves like the @kbd{a} key. |
| 1764 | |
| 1765 | @item u |
| 1766 | Unmark a marked entry. |
| 1767 | |
| 1768 | @item a |
| 1769 | Accept all (marked) entries in the selection buffer and create a single |
| 1770 | @code{\cite} macro referring to them. |
| 1771 | |
| 1772 | @item A |
| 1773 | Accept all (marked) entries in the selection buffer and create a |
| 1774 | separate @code{\cite} macro for each of it. |
| 1775 | |
| 1776 | @item e |
| 1777 | Create a new BibTeX database file which contains all @i{marked} entries |
| 1778 | in the selection buffer. If no entries are marked, all entries are |
| 1779 | selected. |
| 1780 | |
| 1781 | @item E |
| 1782 | Create a new BibTeX database file which contains all @i{unmarked} |
| 1783 | entries in the selection buffer. If no entries are marked, all entries |
| 1784 | are selected. |
| 1785 | |
| 1786 | @item @key{TAB} |
| 1787 | Enter a citation key with completion. This may also be a key which does |
| 1788 | not yet exist. |
| 1789 | |
| 1790 | @item . |
| 1791 | Show insertion point in another window. This is the point from where you |
| 1792 | called @code{reftex-citation}. |
| 1793 | |
| 1794 | @tablesubheading{Exiting} |
| 1795 | @item q |
| 1796 | Exit the selection process without inserting a citation into the |
| 1797 | buffer. |
| 1798 | |
| 1799 | @tablesubheading{Updating the buffer} |
| 1800 | |
| 1801 | @item g |
| 1802 | Start over with a new regular expression. The full database will be |
| 1803 | rescanned with the new expression (see also @kbd{r}). |
| 1804 | |
| 1805 | @c FIXME: Should we use something else here? r is usually rescan! |
| 1806 | @item r |
| 1807 | Refine the current selection with another regular expression. This will |
| 1808 | @emph{not} rescan the entire database, but just the already selected |
| 1809 | entries. |
| 1810 | |
| 1811 | @end table |
| 1812 | |
| 1813 | @vindex reftex-select-bib-map |
| 1814 | In order to define additional commands for this selection process, the |
| 1815 | keymap @code{reftex-select-bib-map} may be used. |
| 1816 | |
| 1817 | @node Citation Styles, Citation Info, Creating Citations, Citations |
| 1818 | @section Citation Styles |
| 1819 | @cindex Citation styles |
| 1820 | @cindex Citation styles, @code{natbib} |
| 1821 | @cindex Citation styles, @code{harvard} |
| 1822 | @cindex Citation styles, @code{chicago} |
| 1823 | @cindex Citation styles, @code{jurabib} |
| 1824 | @cindex @code{natbib}, citation style |
| 1825 | @cindex @code{harvard}, citation style |
| 1826 | @cindex @code{chicago}, citation style |
| 1827 | @cindex @code{jurabib}, citation style |
| 1828 | |
| 1829 | @vindex reftex-cite-format |
| 1830 | The standard LaTeX macro @code{\cite} works well with numeric or simple |
| 1831 | key citations. To deal with the more complex task of author-year |
| 1832 | citations as used in many natural sciences, a variety of packages has |
| 1833 | been developed which define derived forms of the @code{\cite} macro. |
| 1834 | @b{Ref@TeX{}} can be configured to produce these citation macros as well |
| 1835 | by setting the variable @code{reftex-cite-format}. For the most |
| 1836 | commonly used packages (@code{natbib}, @code{harvard}, @code{chicago}, |
| 1837 | @code{jurabib}) this may be done from the menu, under |
| 1838 | @code{Ref->Citation Styles}. Since there are usually several macros to |
| 1839 | create the citations, executing @code{reftex-citation} (@kbd{C-c [}) |
| 1840 | starts by prompting for the correct macro. For the Natbib style, this |
| 1841 | looks like this: |
| 1842 | |
| 1843 | @example |
| 1844 | SELECT A CITATION FORMAT |
| 1845 | |
| 1846 | [^M] \cite@{%l@} |
| 1847 | [t] \citet@{%l@} |
| 1848 | [T] \citet*@{%l@} |
| 1849 | [p] \citep@{%l@} |
| 1850 | [P] \citep*@{%l@} |
| 1851 | [e] \citep[e.g.][]@{%l@} |
| 1852 | [s] \citep[see][]@{%l@} |
| 1853 | [a] \citeauthor@{%l@} |
| 1854 | [A] \citeauthor*@{%l@} |
| 1855 | [y] \citeyear@{%l@} |
| 1856 | @end example |
| 1857 | |
| 1858 | @vindex reftex-cite-prompt-optional-args |
| 1859 | If cite formats contain empty paris of square brackets, RefTeX can |
| 1860 | will prompt for values of these optional arguments if you call the |
| 1861 | @code{reftex-citation} command with a @kbd{C-u} prefix. |
| 1862 | Following the most generic of these packages, @code{natbib}, the builtin |
| 1863 | citation packages always accept the @kbd{t} key for a @emph{textual} |
| 1864 | citation (like: @code{Jones et al. (1997) have shown...}) as well as |
| 1865 | the @kbd{p} key for a parenthetical citation (like: @code{As shown |
| 1866 | earlier (Jones et al, 1997)}). |
| 1867 | |
| 1868 | To make one of these styles the default, customize the variable |
| 1869 | @code{reftex-cite-format} or put into @file{.emacs}: |
| 1870 | |
| 1871 | @lisp |
| 1872 | (setq reftex-cite-format 'natbib) |
| 1873 | @end lisp |
| 1874 | |
| 1875 | You can also use AUCTeX style files to automatically set the |
| 1876 | citation style based on the @code{usepackage} commands in a given |
| 1877 | document. @xref{Style Files}, for information on how to set up the style |
| 1878 | files correctly. |
| 1879 | |
| 1880 | @node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top |
| 1881 | @section Citation Info |
| 1882 | @cindex Displaying citations |
| 1883 | @cindex Citations, displaying |
| 1884 | @cindex Citation info |
| 1885 | @cindex Viewing citations |
| 1886 | @kindex C-c & |
| 1887 | @kindex S-mouse-2 |
| 1888 | @findex reftex-view-crossref |
| 1889 | @findex reftex-mouse-view-crossref |
| 1890 | |
| 1891 | When point is idle for more than @code{reftex-idle-time} seconds on the |
| 1892 | argument of a @code{\cite} macro, the echo area will display some |
| 1893 | information about the article cited there. Note that the information is |
| 1894 | only displayed if the echo area is not occupied by a different message. |
| 1895 | |
| 1896 | @b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database |
| 1897 | entry corresponding to a @code{\cite} macro, or all citation locations |
| 1898 | corresponding to a @code{\bibitem} or BibTeX database entry. |
| 1899 | @xref{Viewing Cross-References}. |
| 1900 | |
| 1901 | @node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations |
| 1902 | @section Chapterbib and Bibunits |
| 1903 | @cindex @code{chapterbib}, LaTeX package |
| 1904 | @cindex @code{bibunits}, LaTeX package |
| 1905 | @cindex Bibliographies, multiple |
| 1906 | |
| 1907 | @code{chapterbib} and @code{bibunits} are two LaTeX packages which |
| 1908 | produce multiple bibliographies in a document. This is no problem for |
| 1909 | @b{Ref@TeX{}} as long as all bibliographies use the same BibTeX database |
| 1910 | files. If they do not, it is best to have each document part in a |
| 1911 | separate file (as it is required for @code{chapterbib} anyway). Then |
| 1912 | @b{Ref@TeX{}} will still scan the locally relevant databases correctly. If |
| 1913 | you have multiple bibliographies within a @emph{single file}, this may |
| 1914 | or may not be the case. |
| 1915 | |
| 1916 | @node Citations Outside LaTeX, BibTeX Database Subsets, Chapterbib and Bibunits, Citations |
| 1917 | @section Citations outside LaTeX |
| 1918 | @cindex Citations outside LaTeX |
| 1919 | @vindex reftex-default-bibliography |
| 1920 | |
| 1921 | The command @code{reftex-citation} can also be executed outside a LaTeX |
| 1922 | buffer. This can be useful to reference articles in the mail buffer and |
| 1923 | other documents. You should @emph{not} enter @code{reftex-mode} for |
| 1924 | this, just execute the command. The list of BibTeX files will in this |
| 1925 | case be taken from the variable @code{reftex-default-bibliography}. |
| 1926 | Setting the variable @code{reftex-cite-format} to the symbol |
| 1927 | @code{locally} does a decent job of putting all relevant information |
| 1928 | about a citation directly into the buffer. Here is the lisp code to add |
| 1929 | the @kbd{C-c [} binding to the mail buffer. It also provides a local |
| 1930 | binding for @code{reftex-cite-format}. |
| 1931 | |
| 1932 | @lisp |
| 1933 | (add-hook 'mail-setup-hook |
| 1934 | (lambda () (define-key mail-mode-map "\C-c[" |
| 1935 | (lambda () |
| 1936 | (interactive) |
| 1937 | (let ((reftex-cite-format 'locally)) |
| 1938 | (reftex-citation)))))) |
| 1939 | @end lisp |
| 1940 | |
| 1941 | @node BibTeX Database Subsets, , Citations Outside LaTeX, Citations |
| 1942 | @section Database Subsets |
| 1943 | @cindex BibTeX database subsets |
| 1944 | @findex reftex-create-bibtex-file |
| 1945 | |
| 1946 | @b{Ref@TeX{}} offers two ways to create a new BibTeX database file. |
| 1947 | |
| 1948 | The first option produces a file which contains only the entries |
| 1949 | actually referenced in the current document. This can be useful if |
| 1950 | the database in only meant for a single document and you want to clean |
| 1951 | it of old and unused ballast. It can also be useful while writing a |
| 1952 | document together with collaborators, in order to avoid sending around |
| 1953 | the entire (possibly very large) database. To create the file, use |
| 1954 | @kbd{M-x reftex-create-bibtex-file}, also available from the menu |
| 1955 | under @code{Ref->Global Actions->Create Bibtex File}. The command will |
| 1956 | prompt for a BibTeX file name and write the extracted entries to that |
| 1957 | file. |
| 1958 | |
| 1959 | The second option makes use of the selection process started by the |
| 1960 | command @kbd{C-c [} (@pxref{Creating Citations}). This command uses a |
| 1961 | regular expression to select entries, and lists them in a formatted |
| 1962 | selection buffer. After pressing the @kbd{e} key (mnemonics: Export), |
| 1963 | the command will prompt for the name of a new BibTeX file and write |
| 1964 | the selected entries to that file. You can also first mark some |
| 1965 | entries in the selection buffer with the @kbd{m} key and then export |
| 1966 | either the @i{marked} entries (with the @kbd{e} key) or the |
| 1967 | @i{unmarked} entries (with the @kbd{E} key). |
| 1968 | |
| 1969 | @node Index Support, Viewing Cross-References, Citations, Top |
| 1970 | @chapter Index Support |
| 1971 | @cindex Index Support |
| 1972 | @cindex @code{\index} |
| 1973 | |
| 1974 | LaTeX has builtin support for creating an Index. The LaTeX core |
| 1975 | supports two different indices, the standard index and a glossary. With |
| 1976 | the help of special LaTeX packages (@file{multind.sty} or |
| 1977 | @file{index.sty}), any number of indices can be supported. |
| 1978 | |
| 1979 | Index entries are created with the @code{\index@{@var{entry}@}} macro. |
| 1980 | All entries defined in a document are written out to the @file{.aux} |
| 1981 | file. A separate tool must be used to convert this information into a |
| 1982 | nicely formatted index. Tools used with LaTeX include @code{MakeIndex} |
| 1983 | and @code{xindy}. |
| 1984 | |
| 1985 | Indexing is a very difficult task. It must follow strict conventions to |
| 1986 | make the index consistent and complete. There are basically two |
| 1987 | approaches one can follow, and both have their merits. |
| 1988 | |
| 1989 | @enumerate |
| 1990 | @item |
| 1991 | Part of the indexing should already be done with the markup. The |
| 1992 | document structure should be reflected in the index, so when starting |
| 1993 | new sections, the basic topics of the section should be indexed. If the |
| 1994 | document contains definitions, theorems or the like, these should all |
| 1995 | correspond to appropriate index entries. This part of the index can |
| 1996 | very well be developed along with the document. Often it is worthwhile |
| 1997 | to define special purpose macros which define an item and at the same |
| 1998 | time make an index entry, possibly with special formatting to make the |
| 1999 | reference page in the index bold or underlined. To make @b{Ref@TeX{}} |
| 2000 | support for indexing possible, these special macros must be added to |
| 2001 | @b{Ref@TeX{}}'s configuration (@pxref{Defining Index Macros}). |
| 2002 | |
| 2003 | @item |
| 2004 | The rest of the index is often just a collection of where in the |
| 2005 | document certain words or phrases are being used. This part is |
| 2006 | difficult to develop along with the document, because consistent entries |
| 2007 | for each occurrence are needed and are best selected when the document |
| 2008 | is ready. @b{Ref@TeX{}} supports this with an @emph{index phrases file} |
| 2009 | which collects phrases and helps indexing the phrases globally. |
| 2010 | @end enumerate |
| 2011 | |
| 2012 | Before you start, you need to make sure that @b{Ref@TeX{}} knows about |
| 2013 | the index style being used in the current document. @b{Ref@TeX{}} has |
| 2014 | builtin support for the default @code{\index} and @code{\glossary} |
| 2015 | macros. Other LaTeX packages, like the @file{multind} or @file{index} |
| 2016 | package, redefine the @code{\index} macro to have an additional |
| 2017 | argument, and @b{Ref@TeX{}} needs to be configured for those. A |
| 2018 | sufficiently new version of AUCTeX (9.10c or later) will do this |
| 2019 | automatically. If you really don't use AUCTeX (you should!), this |
| 2020 | configuration needs to be done by hand with the menu (@code{Ref->Index |
| 2021 | Style}), or globally for all your documents with |
| 2022 | |
| 2023 | @lisp |
| 2024 | (setq reftex-index-macros '(multind)) @r{or} |
| 2025 | (setq reftex-index-macros '(index)) |
| 2026 | @end lisp |
| 2027 | |
| 2028 | @menu |
| 2029 | * Creating Index Entries:: Macros and completion of entries. |
| 2030 | * The Index Phrases File:: A special file for global indexing. |
| 2031 | * Displaying and Editing the Index:: The index editor. |
| 2032 | * Builtin Index Macros:: The index macros RefTeX knows about. |
| 2033 | * Defining Index Macros:: ... and macros it doesn't. |
| 2034 | @end menu |
| 2035 | |
| 2036 | @node Creating Index Entries, The Index Phrases File, , Index Support |
| 2037 | @section Creating Index Entries |
| 2038 | @cindex Creating index entries |
| 2039 | @cindex Index entries, creating |
| 2040 | @kindex C-c < |
| 2041 | @findex reftex-index |
| 2042 | @kindex C-c / |
| 2043 | @findex reftex-index-selection-or-word |
| 2044 | |
| 2045 | In order to index the current selection or the word at the cursor press |
| 2046 | @kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the |
| 2047 | selection or word @samp{@var{word}} to be replaced with |
| 2048 | @samp{\index@{@var{word}@}@var{word}}. The macro which is used |
| 2049 | (@code{\index} by default) can be configured with the variable |
| 2050 | @code{reftex-index-default-macro}. When the command is called with a |
| 2051 | prefix argument (@kbd{C-u C-c /}), you get a chance to edit the |
| 2052 | generated index entry. Use this to change the case of the word or to |
| 2053 | make the entry a subentry, for example by entering |
| 2054 | @samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes |
| 2055 | (@kbd{C-u C-u C-c /}), you will be asked for the index macro as well. |
| 2056 | When there is nothing selected and no word at point, this command will |
| 2057 | just call @code{reftex-index}, described below. |
| 2058 | |
| 2059 | In order to create a general index entry, press @kbd{C-c <} |
| 2060 | (@code{reftex-index}). @b{Ref@TeX{}} will prompt for one of the |
| 2061 | available index macros and for its arguments. Completion will be |
| 2062 | available for the index entry and, if applicable, the index tag. The |
| 2063 | index tag is a string identifying one of multiple indices. With the |
| 2064 | @file{multind} and @file{index} packages, this tag is the first argument |
| 2065 | to the redefined @code{\index} macro. |
| 2066 | |
| 2067 | @node The Index Phrases File, Displaying and Editing the Index, Creating Index Entries, Index Support |
| 2068 | @section The Index Phrases File |
| 2069 | @cindex Index phrase file |
| 2070 | @cindex Phrase file |
| 2071 | @kindex C-c | |
| 2072 | @findex reftex-index-visit-phrases-buffer |
| 2073 | @cindex Macro definition lines, in phrase buffer |
| 2074 | |
| 2075 | @b{Ref@TeX{}} maintains a file in which phrases can be collected for |
| 2076 | later indexing. The file is located in the same directory as the master |
| 2077 | file of the document and has the extension @file{.rip} (@b{R}eftex |
| 2078 | @b{I}ndex @b{P}hrases). You can create or visit the file with @kbd{C-c |
| 2079 | |} (@code{reftex-index-visit-phrases-buffer}). If the file is empty it |
| 2080 | is initialized by inserting a file header which contains the definition |
| 2081 | of the available index macros. This list is initialized from |
| 2082 | @code{reftex-index-macros} (@pxref{Defining Index Macros}). You can |
| 2083 | edit the header as needed, but if you define new LaTeX indexing macros, |
| 2084 | don't forget to add them to @code{reftex-index-macros} as well. Here is |
| 2085 | a phrase file header example: |
| 2086 | |
| 2087 | @example |
| 2088 | % -*- mode: reftex-index-phrases -*- |
| 2089 | % Key Macro Format Repeat |
| 2090 | %---------------------------------------------------------- |
| 2091 | >>>INDEX_MACRO_DEFINITION: i \index@{%s@} t |
| 2092 | >>>INDEX_MACRO_DEFINITION: I \index*@{%s@} nil |
| 2093 | >>>INDEX_MACRO_DEFINITION: g \glossary@{%s@} t |
| 2094 | >>>INDEX_MACRO_DEFINITION: n \index*[name]@{%s@} nil |
| 2095 | %---------------------------------------------------------- |
| 2096 | @end example |
| 2097 | |
| 2098 | The macro definition lines consist of a unique letter identifying a |
| 2099 | macro, a format string and the @var{repeat} flag, all separated by |
| 2100 | @key{TAB}. The format string shows how the macro is to be applied, the |
| 2101 | @samp{%s} will be replaced with the index entry. The repeat flag |
| 2102 | indicates if @var{word} is indexed by the macro as |
| 2103 | @samp{\index@{@var{word}@}} (@var{repeat} = @code{nil}) or as |
| 2104 | @samp{\index@{@var{word}@}@var{word}} (@var{repeat} = @code{t}). In the |
| 2105 | above example it is assumed that the macro @code{\index*@{@var{word}@}} |
| 2106 | already typesets its argument in the text, so that it is unnecessary to |
| 2107 | repeat @var{word} outside the macro. |
| 2108 | |
| 2109 | @menu |
| 2110 | * Collecting Phrases:: Collecting from document or external. |
| 2111 | * Consistency Checks:: Check for duplicates etc. |
| 2112 | * Global Indexing:: The interactive indexing process. |
| 2113 | @end menu |
| 2114 | |
| 2115 | @node Collecting Phrases, Consistency Checks, , The Index Phrases File |
| 2116 | @subsection Collecting Phrases |
| 2117 | @cindex Collecting index phrases |
| 2118 | @cindex Index phrases, collection |
| 2119 | @cindex Phrases, collecting |
| 2120 | |
| 2121 | Phrases for indexing can be collected while writing the document. The |
| 2122 | command @kbd{C-c \} (@code{reftex-index-phrase-selection-or-word}) |
| 2123 | copies the current selection (if active) or the word near point into the |
| 2124 | phrases buffer. It then selects this buffer, so that the phrase line |
| 2125 | can be edited. To return to the LaTeX document, press @kbd{C-c C-c} |
| 2126 | (@code{reftex-index-phrases-save-and-return}). |
| 2127 | |
| 2128 | You can also prepare the list of index phrases in a different way and |
| 2129 | copy it into the phrases file. For example you might want to start from |
| 2130 | a word list of the document and remove all words which should not be |
| 2131 | indexed. |
| 2132 | |
| 2133 | The phrase lines in the phrase buffer must have a specific format. |
| 2134 | @b{Ref@TeX{}} will use font-lock to indicate if a line has the proper |
| 2135 | format. A phrase line looks like this: |
| 2136 | |
| 2137 | @example |
| 2138 | [@var{key}] <TABs> @var{phrase} [<TABs> @var{arg}[&&@var{arg}]... [ || @var{arg}]...] |
| 2139 | @end example |
| 2140 | |
| 2141 | @code{<TABs>} stands for white space containing at least one @key{TAB}. |
| 2142 | @var{key} must be at the start of the line and is the character |
| 2143 | identifying one of the macros defined in the file header. It is |
| 2144 | optional - when omitted, the first macro definition line in the file |
| 2145 | will be used for this phrase. The @var{phrase} is the phrase to be |
| 2146 | searched for when indexing. It may contain several words separated by |
| 2147 | spaces. By default the search phrase is also the text entered as |
| 2148 | argument of the index macro. If you want the index entry to be |
| 2149 | different from the search phrase, enter another @key{TAB} and the index |
| 2150 | argument @var{arg}. If you want to have each match produce several |
| 2151 | index entries, separate the different index arguments with @samp{ && |
| 2152 | }@footnote{@samp{&&} with optional spaces, see |
| 2153 | @code{reftex-index-phrases-logical-and-regexp}.}. If you want to be |
| 2154 | able to choose at each match between several different index arguments, |
| 2155 | separate them with @samp{ || }@footnote{@samp{||} with optional spaces, |
| 2156 | see @code{reftex-index-phrases-logical-or-regexp}.}. Here is an |
| 2157 | example: |
| 2158 | |
| 2159 | @example |
| 2160 | %-------------------------------------------------------------------- |
| 2161 | I Sun |
| 2162 | i Planet Planets |
| 2163 | i Vega Stars!Vega |
| 2164 | Jupiter Planets!Jupiter |
| 2165 | i Mars Planets!Mars || Gods!Mars || Chocolate Bars!Mars |
| 2166 | i Pluto Planets!Pluto && Kuiper Belt Objects!Pluto |
| 2167 | @end example |
| 2168 | |
| 2169 | |
| 2170 | So @samp{Sun} will be indexed directly as @samp{\index*@{Sun@}}, while |
| 2171 | @samp{Planet} will be indexed as @samp{\index@{Planets@}Planet}. |
| 2172 | @samp{Vega} will be indexed as a subitem of @samp{Stars}. The |
| 2173 | @samp{Jupiter} line will also use the @samp{i} macro as it was the first |
| 2174 | macro definition in the file header (see above example). At each |
| 2175 | occurrence of @samp{Mars} you will be able choose between indexing it as |
| 2176 | a subitem of @samp{Planets}, @samp{Gods} or @samp{Chocolate Bars}. |
| 2177 | Finally, every occurrence of @samp{Pluto} will be indexed as |
| 2178 | @samp{\index@{Planets!Pluto@}\index@{Kuiper Belt Objects!Pluto@}Pluto} |
| 2179 | and will therefore create two different index entries. |
| 2180 | |
| 2181 | @node Consistency Checks, Global Indexing, Collecting Phrases, The Index Phrases File |
| 2182 | @subsection Consistency Checks |
| 2183 | @cindex Index phrases, consistency checks |
| 2184 | @cindex Phrases, consistency checks |
| 2185 | @cindex Consistency check for index phrases |
| 2186 | |
| 2187 | @kindex C-c C-s |
| 2188 | Before indexing the phrases in the phrases buffer, they should be |
| 2189 | checked carefully for consistency. A first step is to sort the phrases |
| 2190 | alphabetically - this is done with the command @kbd{C-c C-s} |
| 2191 | (@code{reftex-index-sort-phrases}). It will sort all phrases in the |
| 2192 | buffer alphabetically by search phrase. If you want to group certain |
| 2193 | phrases and only sort within the groups, insert empty lines between the |
| 2194 | groups. Sorting will only change the sequence of phrases within each |
| 2195 | group (see the variable @code{reftex-index-phrases-sort-in-blocks}). |
| 2196 | |
| 2197 | @kindex C-c C-i |
| 2198 | A useful command is @kbd{C-c C-i} (@code{reftex-index-phrases-info}) |
| 2199 | which lists information about the phrase at point, including an example |
| 2200 | of how the index entry will look like and the number of expected matches |
| 2201 | in the document. |
| 2202 | |
| 2203 | @kindex C-c C-t |
| 2204 | Another important check is to find out if there are double or |
| 2205 | overlapping entries in the buffer. For example if you are first |
| 2206 | searching and indexing @samp{Mars} and then @samp{Planet Mars}, the |
| 2207 | second phrase will not match because of the index macro inserted before |
| 2208 | @samp{Mars} earlier. The command @kbd{C-c C-t} |
| 2209 | (@code{reftex-index-find-next-conflict-phrase}) finds the next phrase in |
| 2210 | the buffer which is either duplicate or a subphrase of another phrase. |
| 2211 | In order to check the whole buffer like this, start at the beginning and |
| 2212 | execute this command repeatedly. |
| 2213 | |
| 2214 | @node Global Indexing, , Consistency Checks, The Index Phrases File |
| 2215 | @subsection Global Indexing |
| 2216 | @cindex Global indexing |
| 2217 | @cindex Indexing, global |
| 2218 | @cindex Indexing, from @file{phrases} buffer |
| 2219 | |
| 2220 | Once the index phrases have been collected and organized, you are set |
| 2221 | for global indexing. I recommend to do this only on an otherwise |
| 2222 | finished document. Global indexing starts from the phrases buffer. |
| 2223 | There are several commands which start indexing: @kbd{C-c C-x} acts on |
| 2224 | the current phrase line, @kbd{C-c C-r} on all lines in the current |
| 2225 | region and @kbd{C-c C-a} on all phrase lines in the buffer. It is |
| 2226 | probably good to do indexing in small chunks since your concentration |
| 2227 | may not last long enough to do everything in one go. |
| 2228 | |
| 2229 | @b{Ref@TeX{}} will start at the first phrase line and search the phrase |
| 2230 | globally in the whole document. At each match it will stop, compute the |
| 2231 | replacement string and offer you the following choices@footnote{Windows |
| 2232 | users: Restrict yourself to the described keys during indexing. Pressing |
| 2233 | @key{Help} at the indexing prompt can apparently hang Emacs.}: |
| 2234 | |
| 2235 | @table @kbd |
| 2236 | @item y |
| 2237 | Replace this match with the proposed string. |
| 2238 | @item n |
| 2239 | Skip this match. |
| 2240 | @item ! |
| 2241 | Replace this and all further matches in this file. |
| 2242 | @item q |
| 2243 | Skip this match, start with next file. |
| 2244 | @item Q |
| 2245 | Skip this match, start with next phrase. |
| 2246 | @item o |
| 2247 | Select a different indexing macro for this match. |
| 2248 | @item 1-9 |
| 2249 | Select one of multiple index keys (those separated with @samp{||}). |
| 2250 | @item e |
| 2251 | Edit the replacement text. |
| 2252 | @item C-r |
| 2253 | Recursive edit. Use @kbd{C-M-c} to return to the indexing process. |
| 2254 | @item s |
| 2255 | Save this buffer and ask again about the current match. |
| 2256 | @item S |
| 2257 | Save all document buffers and ask again about the current match. |
| 2258 | @item C-g |
| 2259 | Abort the indexing process. |
| 2260 | @end table |
| 2261 | |
| 2262 | The @samp{Find and Index in Document} menu in the phrases buffer also |
| 2263 | lists a few options for the indexing process. The options have |
| 2264 | associated customization variables to set the defaults (@pxref{Options |
| 2265 | (Index Support)}). Here is a short explanation of what the options do: |
| 2266 | |
| 2267 | @table @i |
| 2268 | @item Match Whole Words |
| 2269 | When searching for index phrases, make sure whole words are matched. |
| 2270 | This should probably always be on. |
| 2271 | @item Case Sensitive Search |
| 2272 | Search case sensitively for phrases. I recommend to have this setting |
| 2273 | off, in order to match the capitalized words at the beginning of a |
| 2274 | sentence, and even typos. You can always say @emph{no} at a match you |
| 2275 | do not like. |
| 2276 | @item Wrap Long Lines |
| 2277 | Inserting index macros increases the line length. Turn this option on |
| 2278 | to allow @b{Ref@TeX{}} to wrap long lines. |
| 2279 | @item Skip Indexed Matches |
| 2280 | When this is on, @b{Ref@TeX{}} will at each match try to figure out if |
| 2281 | this match is already indexed. A match is considered indexed if it is |
| 2282 | either the argument of an index macro, or if an index macro is directly |
| 2283 | (without whitespace separation) before or after the match. Index macros |
| 2284 | are those configured in @code{reftex-index-macros}. Intended for |
| 2285 | re-indexing a documents after changes have been made. |
| 2286 | @end table |
| 2287 | |
| 2288 | Even though indexing should be the last thing you do to a document, you |
| 2289 | are bound to make changes afterwards. Indexing then has to be applied |
| 2290 | to the changed regions. The command |
| 2291 | @code{reftex-index-phrases-apply-to-region} is designed for this |
| 2292 | purpose. When called from a LaTeX document with active region, it will |
| 2293 | apply @code{reftex-index-all-phrases} to the current region. |
| 2294 | |
| 2295 | @node Displaying and Editing the Index, Builtin Index Macros, The Index Phrases File, Index Support |
| 2296 | @section Displaying and Editing the Index |
| 2297 | @cindex Displaying the Index |
| 2298 | @cindex Editing the Index |
| 2299 | @cindex Index entries, creating |
| 2300 | @cindex Index, displaying |
| 2301 | @cindex Index, editing |
| 2302 | @kindex C-c > |
| 2303 | @findex reftex-display-index |
| 2304 | |
| 2305 | In order to compile and display the index, press @kbd{C-c >}. If the |
| 2306 | document uses multiple indices, @b{Ref@TeX{}} will ask you to select |
| 2307 | one. Then, all index entries will be sorted alphabetically and |
| 2308 | displayed in a special buffer, the @file{*Index*} buffer. From that |
| 2309 | buffer you can check and edit each entry. |
| 2310 | |
| 2311 | The index can be restricted to the current section or the region. Then |
| 2312 | only entries in that part of the document will go into the compiled |
| 2313 | index. To restrict to the current section, use a numeric prefix |
| 2314 | @samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current |
| 2315 | region, make the region active and use a numeric prefix @samp{3} (press |
| 2316 | @kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the |
| 2317 | restriction can be moved from one section to the next by pressing the |
| 2318 | @kbd{<} and @kbd{>} keys. |
| 2319 | |
| 2320 | One caveat: @b{Ref@TeX{}} finds the definition point of an index entry |
| 2321 | by searching near the buffer position where it had found to macro during |
| 2322 | scanning. If you have several identical index entries in the same |
| 2323 | buffer and significant changes have shifted the entries around, you must |
| 2324 | rescan the buffer to ensure the correspondence between the |
| 2325 | @file{*Index*} buffer and the definition locations. It is therefore |
| 2326 | advisable to rescan the document (with @kbd{r} or @kbd{C-u r}) |
| 2327 | frequently while editing the index from the @file{*Index*} |
| 2328 | buffer. |
| 2329 | |
| 2330 | @kindex ? |
| 2331 | Here is a list of special commands available in the @file{*Index*} buffer. A |
| 2332 | summary of this information is always available by pressing |
| 2333 | @kbd{?}. |
| 2334 | |
| 2335 | @table @kbd |
| 2336 | @tablesubheading{General} |
| 2337 | @item ? |
| 2338 | Display a summary of commands. |
| 2339 | |
| 2340 | @item 0-9, - |
| 2341 | Prefix argument. |
| 2342 | |
| 2343 | @tablesubheading{Moving around} |
| 2344 | @item ! A..Z |
| 2345 | Pressing any capital letter will jump to the corresponding section in |
| 2346 | the @file{*Index*} buffer. The exclamation mark is special and jumps to |
| 2347 | the first entries alphabetically sorted below @samp{A}. These are |
| 2348 | usually non-alphanumeric characters. |
| 2349 | @item n |
| 2350 | Go to next entry. |
| 2351 | @item p |
| 2352 | Go to previous entry. |
| 2353 | |
| 2354 | @tablesubheading{Access to document locations} |
| 2355 | @item @key{SPC} |
| 2356 | Show the place in the document where this index entry is defined. |
| 2357 | |
| 2358 | @item @key{TAB} |
| 2359 | Go to the definition of the current index entry in another |
| 2360 | window. |
| 2361 | |
| 2362 | @item @key{RET} |
| 2363 | Go to the definition of the current index entry and hide the |
| 2364 | @file{*Index*} buffer window. |
| 2365 | |
| 2366 | @item f |
| 2367 | @vindex reftex-index-follow-mode |
| 2368 | @vindex reftex-revisit-to-follow |
| 2369 | Toggle follow mode. When follow mode is active, the other window will |
| 2370 | always show the location corresponding to the line in the @file{*Index*} |
| 2371 | buffer at point. This is similar to pressing @key{SPC} after each |
| 2372 | cursor motion. The default for this flag can be set with the variable |
| 2373 | @code{reftex-index-follow-mode}. Note that only context in files |
| 2374 | already visited is shown. @b{Ref@TeX{}} will not visit a file just for |
| 2375 | follow mode. See, however, the variable |
| 2376 | @code{reftex-revisit-to-follow}. |
| 2377 | |
| 2378 | @tablesubheading{Entry editing} |
| 2379 | @item e |
| 2380 | Edit the current index entry. In the minibuffer, you can edit the |
| 2381 | index macro which defines this entry. |
| 2382 | |
| 2383 | @item C-k |
| 2384 | Kill the index entry. Currently not implemented because I don't know |
| 2385 | how to implement an @code{undo} function for this. |
| 2386 | |
| 2387 | @item * |
| 2388 | Edit the @var{key} part of the entry. This is the initial part of the |
| 2389 | entry which determines the location of the entry in the index. |
| 2390 | |
| 2391 | @item | |
| 2392 | Edit the @var{attribute} part of the entry. This is the part after the |
| 2393 | vertical bar. With @code{MakeIndex}, this part is an encapsulating |
| 2394 | macro. With @code{xindy}, it is called @emph{attribute} and is a |
| 2395 | property of the index entry that can lead to special formatting. When |
| 2396 | called with @kbd{C-u} prefix, kill the entire @var{attribute} |
| 2397 | part. |
| 2398 | |
| 2399 | @item @@ |
| 2400 | Edit the @var{visual} part of the entry. This is the part after the |
| 2401 | @samp{@@} which is used by @code{MakeIndex} to change the visual |
| 2402 | appearance of the entry in the index. When called with @kbd{C-u} |
| 2403 | prefix, kill the entire @var{visual} part. |
| 2404 | |
| 2405 | @item ( |
| 2406 | Toggle the beginning of page range property @samp{|(} of the |
| 2407 | entry. |
| 2408 | |
| 2409 | @item ) |
| 2410 | Toggle the end of page range property @samp{|)} of the entry. |
| 2411 | |
| 2412 | @item _ |
| 2413 | Make the current entry a subentry. This command will prompt for the |
| 2414 | superordinate entry and insert it. |
| 2415 | |
| 2416 | @item ^ |
| 2417 | Remove the highest superordinate entry. If the current entry is a |
| 2418 | subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy |
| 2419 | (@samp{bbb!ccc}). |
| 2420 | |
| 2421 | @tablesubheading{Exiting} |
| 2422 | @item q |
| 2423 | Hide the @file{*Index*} buffer. |
| 2424 | |
| 2425 | @item k |
| 2426 | Kill the @file{*Index*} buffer. |
| 2427 | |
| 2428 | @item C-c = |
| 2429 | Switch to the Table of Contents buffer of this document. |
| 2430 | |
| 2431 | @tablesubheading{Controlling what gets displayed} |
| 2432 | @item c |
| 2433 | @vindex reftex-index-include-context |
| 2434 | Toggle the display of short context in the @file{*Index*} buffer. The |
| 2435 | default for this flag can be set with the variable |
| 2436 | @code{reftex-index-include-context}. |
| 2437 | |
| 2438 | @item @} |
| 2439 | Restrict the index to a single document section. The corresponding |
| 2440 | section number will be displayed in the @code{R<>} indicator in the |
| 2441 | mode line and in the header of the @file{*Index*} buffer. |
| 2442 | |
| 2443 | @item @{ |
| 2444 | Widen the index to contain all entries of the document. |
| 2445 | |
| 2446 | @item < |
| 2447 | When the index is currently restricted, move the restriction to the |
| 2448 | previous section. |
| 2449 | |
| 2450 | @item > |
| 2451 | When the index is currently restricted, move the restriction to the |
| 2452 | next section. |
| 2453 | |
| 2454 | @tablesubheading{Updating the buffer} |
| 2455 | @item g |
| 2456 | Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the |
| 2457 | document. However, it sorts the entries again, so that edited entries |
| 2458 | will move to the correct position. |
| 2459 | |
| 2460 | @item r |
| 2461 | @vindex reftex-enable-partial-scans |
| 2462 | Reparse the LaTeX document and rebuild the @file{*Index*} buffer. When |
| 2463 | @code{reftex-enable-partial-scans} is non-@code{nil}, rescan only the file this |
| 2464 | location is defined in, not the entire document. |
| 2465 | |
| 2466 | @item C-u r |
| 2467 | Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*} |
| 2468 | buffer. |
| 2469 | |
| 2470 | @item s |
| 2471 | Switch to a different index (for documents with multiple |
| 2472 | indices). |
| 2473 | @end table |
| 2474 | |
| 2475 | |
| 2476 | @node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support |
| 2477 | @section Builtin Index Macros |
| 2478 | @cindex Builtin index macros |
| 2479 | @cindex Index macros, builtin |
| 2480 | @vindex reftex-index-macros |
| 2481 | @cindex @code{multind}, LaTeX package |
| 2482 | @cindex @code{index}, LaTeX package |
| 2483 | @cindex LaTeX packages, @code{multind} |
| 2484 | @cindex LaTeX packages, @code{index} |
| 2485 | |
| 2486 | @b{Ref@TeX{}} by default recognizes the @code{\index} and |
| 2487 | @code{\glossary} macros which are defined in the LaTeX core. It has |
| 2488 | also builtin support for the re-implementations of @code{\index} |
| 2489 | in the @file{multind} and @file{index} packages. However, since |
| 2490 | the different definitions of the @code{\index} macro are incompatible, |
| 2491 | you will have to explicitly specify the index style used. |
| 2492 | @xref{Creating Index Entries}, for information on how to do that. |
| 2493 | |
| 2494 | @node Defining Index Macros, , Builtin Index Macros, Index Support |
| 2495 | @section Defining Index Macros |
| 2496 | @cindex Defining Index Macros |
| 2497 | @cindex Index macros, defining |
| 2498 | @vindex reftex-index-macros |
| 2499 | |
| 2500 | When writing a document with an index you will probably define |
| 2501 | additional macros which make entries into the index. |
| 2502 | Let's look at an example. |
| 2503 | |
| 2504 | @example |
| 2505 | \newcommand@{\ix@}[1]@{#1\index@{#1@}@} |
| 2506 | \newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@} |
| 2507 | \newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@} |
| 2508 | @end example |
| 2509 | |
| 2510 | The first macro @code{\ix} typesets its argument in the text and places |
| 2511 | it into the index. The second macro @code{\nindex} typesets its |
| 2512 | argument in the text and places it into a separate index with the tag |
| 2513 | @samp{name}@footnote{We are using the syntax of the @file{index} package |
| 2514 | here.}. The last macro also places its argument into the index, but as |
| 2515 | subitems under the main index entry @samp{Astronomical Objects}. Here |
| 2516 | is how to make @b{Ref@TeX{}} recognize and correctly interpret these |
| 2517 | macros, first with Emacs Lisp. |
| 2518 | |
| 2519 | @lisp |
| 2520 | (setq reftex-index-macros |
| 2521 | '(("\\ix@{*@}" "idx" ?x "" nil nil) |
| 2522 | ("\\nindex@{*@}" "name" ?n "" nil nil) |
| 2523 | ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil t))) |
| 2524 | @end lisp |
| 2525 | |
| 2526 | Note that the index tag is @samp{idx} for the main index, and |
| 2527 | @samp{name} for the name index. @samp{idx} and @samp{glo} are reserved |
| 2528 | for the default index and for the glossary. |
| 2529 | |
| 2530 | The character arguments @code{?x}, @code{?n}, and @code{?o} are for |
| 2531 | quick identification of these macros when @b{Ref@TeX{}} inserts new |
| 2532 | index entries with @code{reftex-index}. These codes need to be |
| 2533 | unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the |
| 2534 | @code{\index}, @code{\index*}, and @code{\glossary} macros, |
| 2535 | respectively. |
| 2536 | |
| 2537 | The following string is empty unless your macro adds a superordinate |
| 2538 | entry to the index key - this is the case for the @code{\astobj} macro. |
| 2539 | |
| 2540 | The next entry can be a hook function to exclude certain matches, it |
| 2541 | almost always can be @code{nil}. |
| 2542 | |
| 2543 | The final element in the list indicates if the text being indexed needs |
| 2544 | to be repeated outside the macro. For the normal index macros, this |
| 2545 | should be @code{t}. Only if the macro typesets the entry in the text |
| 2546 | (like @code{\ix} and @code{\nindex} in the example do), this should be |
| 2547 | @code{nil}. |
| 2548 | |
| 2549 | To do the same thing with customize, you need to fill in the templates |
| 2550 | like this: |
| 2551 | |
| 2552 | @example |
| 2553 | Repeat: |
| 2554 | [INS] [DEL] List: |
| 2555 | Macro with args: \ix@{*@} |
| 2556 | Index Tag : [Value Menu] String: idx |
| 2557 | Access Key : x |
| 2558 | Key Prefix : |
| 2559 | Exclusion hook : nil |
| 2560 | Repeat Outside : [Toggle] off (nil) |
| 2561 | [INS] [DEL] List: |
| 2562 | Macro with args: \nindex@{*@} |
| 2563 | Index Tag : [Value Menu] String: name |
| 2564 | Access Key : n |
| 2565 | Key Prefix : |
| 2566 | Exclusion hook : nil |
| 2567 | Repeat Outside : [Toggle] off (nil) |
| 2568 | [INS] [DEL] List: |
| 2569 | Macro with args: \astobj@{*@} |
| 2570 | Index Tag : [Value Menu] String: idx |
| 2571 | Access Key : o |
| 2572 | Key Prefix : Astronomical Objects! |
| 2573 | Exclusion hook : nil |
| 2574 | Repeat Outside : [Toggle] on (non-nil) |
| 2575 | [INS] |
| 2576 | @end example |
| 2577 | |
| 2578 | With the macro @code{\ix} defined, you may want to change the default |
| 2579 | macro used for indexing a text phrase (@pxref{Creating Index Entries}). |
| 2580 | This would be done like this |
| 2581 | |
| 2582 | @lisp |
| 2583 | (setq reftex-index-default-macro '(?x "idx")) |
| 2584 | @end lisp |
| 2585 | |
| 2586 | which specifies that the macro identified with the character @code{?x} (the |
| 2587 | @code{\ix} macro) should be used for indexing phrases and words already |
| 2588 | in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}). |
| 2589 | The index tag is "idx". |
| 2590 | |
| 2591 | @node Viewing Cross-References, RefTeXs Menu, Index Support, Top |
| 2592 | @chapter Viewing Cross--References |
| 2593 | @findex reftex-view-crossref |
| 2594 | @findex reftex-mouse-view-crossref |
| 2595 | @kindex C-c & |
| 2596 | @kindex S-mouse-2 |
| 2597 | |
| 2598 | @b{Ref@TeX{}} can display cross--referencing information. This means, |
| 2599 | if two document locations are linked, @b{Ref@TeX{}} can display the |
| 2600 | matching location(s) in another window. The @code{\label} and @code{\ref} |
| 2601 | macros are one way of establishing such a link. Also, a @code{\cite} |
| 2602 | macro is linked to the corresponding @code{\bibitem} macro or a BibTeX |
| 2603 | database entry. |
| 2604 | |
| 2605 | The feature is invoked by pressing @kbd{C-c &} |
| 2606 | (@code{reftex-view-crossref}) while point is on the @var{key} argument |
| 2607 | of a macro involved in cross--referencing. You can also click with |
| 2608 | @kbd{S-mouse-2} on the macro argument. Here is what will happen for |
| 2609 | individual classes of macros: |
| 2610 | |
| 2611 | @table @asis |
| 2612 | |
| 2613 | @item @code{\ref} |
| 2614 | @cindex @code{\ref} |
| 2615 | Display the corresponding label definition. All usual |
| 2616 | variants@footnote{all macros that start with @samp{ref} or end with |
| 2617 | @samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for |
| 2618 | cross--reference display. This works also for labels defined in an |
| 2619 | external document when the current document refers to them through the |
| 2620 | @code{xr} interface (@pxref{xr (LaTeX package)}). |
| 2621 | |
| 2622 | @item @code{\label} |
| 2623 | @cindex @code{\label} |
| 2624 | @vindex reftex-label-alist |
| 2625 | Display a document location which references this label. Pressing |
| 2626 | @kbd{C-c &} several times moves through the entire document and finds |
| 2627 | all locations. Not only the @code{\label} macro but also other macros |
| 2628 | with label arguments (as configured with @code{reftex-label-alist}) are |
| 2629 | active for cross--reference display. |
| 2630 | |
| 2631 | @item @code{\cite} |
| 2632 | @cindex @code{\cite} |
| 2633 | Display the corresponding BibTeX database entry or @code{\bibitem}. |
| 2634 | All usual variants@footnote{all macros that either start or end with |
| 2635 | @samp{cite}} of the @code{\cite} macro are active for cross--reference |
| 2636 | display. |
| 2637 | |
| 2638 | @item @code{\bibitem} |
| 2639 | @cindex @code{\bibitem} |
| 2640 | Display a document location which cites this article. Pressing |
| 2641 | @kbd{C-c &} several times moves through the entire document and finds |
| 2642 | all locations. |
| 2643 | |
| 2644 | @item BibTeX |
| 2645 | @cindex BibTeX buffer, viewing cite locations from |
| 2646 | @cindex Viewing cite locations from BibTeX buffer |
| 2647 | @kbd{C-c &} is also active in BibTeX buffers. All locations in a |
| 2648 | document where the database entry at point is cited will be displayed. |
| 2649 | On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to |
| 2650 | the document you want to search. Subsequent calls will use the same |
| 2651 | document, until you break this link with a prefix argument to @kbd{C-c |
| 2652 | &}. |
| 2653 | |
| 2654 | @item @code{\index} |
| 2655 | @cindex @code{\index} |
| 2656 | Display other locations in the document which are marked by an index |
| 2657 | macro with the same key argument. Along with the standard @code{\index} |
| 2658 | and @code{\glossary} macros, all macros configured in |
| 2659 | @code{reftex-index-macros} will be recognized. |
| 2660 | @end table |
| 2661 | |
| 2662 | @vindex reftex-view-crossref-extra |
| 2663 | While the display of cross referencing information for the above |
| 2664 | mentioned macros is hard--coded, you can configure additional relations |
| 2665 | in the variable @code{reftex-view-crossref-extra}. |
| 2666 | |
| 2667 | @iftex |
| 2668 | @chapter All the Rest |
| 2669 | @end iftex |
| 2670 | |
| 2671 | @node RefTeXs Menu, Key Bindings, Viewing Cross-References, Top |
| 2672 | @section @b{Ref@TeX{}}'s Menu |
| 2673 | @cindex RefTeXs Menu |
| 2674 | @cindex Menu, in the menu bar |
| 2675 | |
| 2676 | @b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems |
| 2677 | which support this. From this menu you can access all of |
| 2678 | @b{Ref@TeX{}}'s commands and a few of its options. There is also a |
| 2679 | @code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s |
| 2680 | entire set of options. |
| 2681 | |
| 2682 | @node Key Bindings, Faces, RefTeXs Menu, Top |
| 2683 | @section Default Key Bindings |
| 2684 | @cindex Key Bindings, summary |
| 2685 | |
| 2686 | Here is a summary of the available key bindings. |
| 2687 | |
| 2688 | @kindex C-c = |
| 2689 | @kindex C-c - |
| 2690 | @kindex C-c ( |
| 2691 | @kindex C-c ) |
| 2692 | @kindex C-c [ |
| 2693 | @kindex C-c & |
| 2694 | @kindex S-mouse-2 |
| 2695 | @kindex C-c / |
| 2696 | @kindex C-c \ |
| 2697 | @kindex C-c | |
| 2698 | @kindex C-c < |
| 2699 | @kindex C-c > |
| 2700 | @example |
| 2701 | @kbd{C-c =} @code{reftex-toc} |
| 2702 | @kbd{C-c -} @code{reftex-toc-recenter} |
| 2703 | @kbd{C-c (} @code{reftex-label} |
| 2704 | @kbd{C-c )} @code{reftex-reference} |
| 2705 | @kbd{C-c [} @code{reftex-citation} |
| 2706 | @kbd{C-c &} @code{reftex-view-crossref} |
| 2707 | @kbd{S-mouse-2} @code{reftex-mouse-view-crossref} |
| 2708 | @kbd{C-c /} @code{reftex-index-selection-or-word} |
| 2709 | @kbd{C-c \} @code{reftex-index-phrase-selection-or-word} |
| 2710 | @kbd{C-c |} @code{reftex-index-visit-phrases-buffer} |
| 2711 | @kbd{C-c <} @code{reftex-index} |
| 2712 | @kbd{C-c >} @code{reftex-display-index} |
| 2713 | @end example |
| 2714 | |
| 2715 | Note that the @kbd{S-mouse-2} binding is only provided if this key is |
| 2716 | not already used by some other package. @b{Ref@TeX{}} will not override an |
| 2717 | existing binding to @kbd{S-mouse-2}. |
| 2718 | |
| 2719 | Personally, I also bind some functions in the users @kbd{C-c} map for |
| 2720 | easier access. |
| 2721 | |
| 2722 | @c FIXME: Do we need bindings for the Index macros here as well? |
| 2723 | @c C-c i C-c I or so???? |
| 2724 | @c How about key bindings for reftex-reset-mode and reftex-parse-document? |
| 2725 | @kindex C-c t |
| 2726 | @kindex C-c l |
| 2727 | @kindex C-c r |
| 2728 | @kindex C-c c |
| 2729 | @kindex C-c v |
| 2730 | @kindex C-c s |
| 2731 | @kindex C-c g |
| 2732 | @example |
| 2733 | @kbd{C-c t} @code{reftex-toc} |
| 2734 | @kbd{C-c l} @code{reftex-label} |
| 2735 | @kbd{C-c r} @code{reftex-reference} |
| 2736 | @kbd{C-c c} @code{reftex-citation} |
| 2737 | @kbd{C-c v} @code{reftex-view-crossref} |
| 2738 | @kbd{C-c s} @code{reftex-search-document} |
| 2739 | @kbd{C-c g} @code{reftex-grep-document} |
| 2740 | @end example |
| 2741 | |
| 2742 | @noindent These keys are reserved for the user, so I cannot bind them by |
| 2743 | default. If you want to have these key bindings available, set in your |
| 2744 | @file{.emacs} file: |
| 2745 | |
| 2746 | @vindex reftex-extra-bindings |
| 2747 | @lisp |
| 2748 | (setq reftex-extra-bindings t) |
| 2749 | @end lisp |
| 2750 | |
| 2751 | @vindex reftex-load-hook |
| 2752 | Changing and adding to @b{Ref@TeX{}}'s key bindings is best done in the hook |
| 2753 | @code{reftex-load-hook}. For information on the keymaps |
| 2754 | which should be used to add keys, see @ref{Keymaps and Hooks}. |
| 2755 | |
| 2756 | @node Faces, AUCTeX, Key Bindings, Top |
| 2757 | @section Faces |
| 2758 | @cindex Faces |
| 2759 | |
| 2760 | @b{Ref@TeX{}} uses faces when available to structure the selection and |
| 2761 | table of contents buffers. It does not create its own faces, but uses |
| 2762 | the ones defined in @file{font-lock.el}. Therefore, @b{Ref@TeX{}} will |
| 2763 | use faces only when @code{font-lock} is loaded. This seems to be |
| 2764 | reasonable because people who like faces will very likely have it |
| 2765 | loaded. If you wish to turn off fontification or change the involved |
| 2766 | faces, see @ref{Options (Fontification)}. |
| 2767 | |
| 2768 | @node Multifile Documents, Language Support, AUCTeX, Top |
| 2769 | @section Multifile Documents |
| 2770 | @cindex Multifile documents |
| 2771 | @cindex Documents, spread over files |
| 2772 | |
| 2773 | The following is relevant when working with documents spread over many |
| 2774 | files: |
| 2775 | |
| 2776 | @itemize @bullet |
| 2777 | @item |
| 2778 | @b{Ref@TeX{}} has full support for multifile documents. You can edit parts of |
| 2779 | several (multifile) documents at the same time without conflicts. |
| 2780 | @b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and |
| 2781 | @code{query-replace} on all files which are part of a multifile |
| 2782 | document. |
| 2783 | |
| 2784 | @item |
| 2785 | @vindex tex-main-file |
| 2786 | @vindex TeX-master |
| 2787 | All files belonging to a multifile document should define a File |
| 2788 | Variable (@code{TeX-master} for AUCTeX or @code{tex-main-file} for the |
| 2789 | standard Emacs LaTeX mode) containing the name of the master file. For |
| 2790 | example, to set the file variable @code{TeX-master}, include something |
| 2791 | like the following at the end of each TeX file: |
| 2792 | |
| 2793 | @example |
| 2794 | %%% Local Variables: *** |
| 2795 | %%% mode:latex *** |
| 2796 | %%% TeX-master: "thesis.tex" *** |
| 2797 | %%% End: *** |
| 2798 | @end example |
| 2799 | |
| 2800 | AUCTeX with the setting |
| 2801 | |
| 2802 | @lisp |
| 2803 | (setq-default TeX-master nil) |
| 2804 | @end lisp |
| 2805 | |
| 2806 | will actually ask you for each new file about the master file and insert |
| 2807 | this comment automatically. For more details see the documentation of |
| 2808 | the AUCTeX (@pxref{Multifile,,,auctex, The AUC TeX User Manual}), the |
| 2809 | documentation about the Emacs (La)TeX mode (@pxref{TeX Print,,,emacs, |
| 2810 | The GNU Emacs Manual}) and the Emacs documentation on File Variables |
| 2811 | (@pxref{File Variables,,,emacs, The GNU Emacs Manual}). |
| 2812 | |
| 2813 | @item |
| 2814 | The context of a label definition must be found in the same file as the |
| 2815 | label itself in order to be processed correctly by @b{Ref@TeX{}}. The only |
| 2816 | exception is that section labels referring to a section statement |
| 2817 | outside the current file can still use that section title as |
| 2818 | context. |
| 2819 | @end itemize |
| 2820 | |
| 2821 | @node Language Support, Finding Files, Multifile Documents, Top |
| 2822 | @section Language Support |
| 2823 | @cindex Language support |
| 2824 | |
| 2825 | Some parts of @b{Ref@TeX{}} are language dependent. The default |
| 2826 | settings work well for English. If you are writing in a different |
| 2827 | language, the following hints may be useful: |
| 2828 | |
| 2829 | @itemize @bullet |
| 2830 | @item |
| 2831 | @vindex reftex-derive-label-parameters |
| 2832 | @vindex reftex-abbrev-parameters |
| 2833 | The mechanism to derive a label from context includes the abbreviation |
| 2834 | of words and omission of unimportant words. These mechanisms may have |
| 2835 | to be changed for other languages. See the variables |
| 2836 | @code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}. |
| 2837 | |
| 2838 | @item |
| 2839 | @vindex reftex-translate-to-ascii-function |
| 2840 | @vindex reftex-label-illegal-re |
| 2841 | Also, when a label is derived from context, @b{Ref@TeX{}} clears the |
| 2842 | context string from non-ASCII characters in order to make a valid label. |
| 2843 | If there should ever be a version of @TeX{} which allows extended |
| 2844 | characters @emph{in labels}, then we will have to look at the |
| 2845 | variables @code{reftex-translate-to-ascii-function} and |
| 2846 | @code{reftex-label-illegal-re}. |
| 2847 | |
| 2848 | @item |
| 2849 | When a label is referenced, @b{Ref@TeX{}} looks at the word before point |
| 2850 | to guess which label type is required. These @emph{magic words} are |
| 2851 | different in every language. For an example of how to add magic words, |
| 2852 | see @ref{Adding Magic Words}. |
| 2853 | |
| 2854 | @vindex reftex-multiref-punctuation |
| 2855 | @vindex reftex-cite-punctuation |
| 2856 | @item |
| 2857 | @b{Ref@TeX{}} inserts ``punctuation'' for multiple references and |
| 2858 | for the author list in citations. Some of this may be language |
| 2859 | dependent. See the variables @code{reftex-multiref-punctuation} and |
| 2860 | @code{reftex-cite-punctuation}. |
| 2861 | @end itemize |
| 2862 | |
| 2863 | @node Finding Files, Optimizations, Language Support, Top |
| 2864 | @section Finding Files |
| 2865 | @cindex Finding files |
| 2866 | |
| 2867 | In order to find files included in a document via @code{\input} or |
| 2868 | @code{\include}, @b{Ref@TeX{}} searches all directories specified in the |
| 2869 | environment variable @code{TEXINPUTS}. Similarly, it will search the |
| 2870 | path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for |
| 2871 | BibTeX database files. |
| 2872 | |
| 2873 | When searching, @b{Ref@TeX{}} will also expand recursive path |
| 2874 | definitions (directories ending in @samp{//} or @samp{!!}). But it will |
| 2875 | only search and expand directories @emph{explicitly} given in these |
| 2876 | variables. This may cause problems under the following circumstances: |
| 2877 | |
| 2878 | @itemize @bullet |
| 2879 | @item |
| 2880 | Most TeX system have a default search path for both TeX files and BibTeX |
| 2881 | files which is defined in some setup file. Usually this default path is |
| 2882 | for system files which @b{Ref@TeX{}} does not need to see. But if your |
| 2883 | document needs TeX files or BibTeX database files in a directory only |
| 2884 | given in the default search path, @b{Ref@TeX{}} will fail to find them. |
| 2885 | @item |
| 2886 | Some TeX systems do not use environment variables at all in order to |
| 2887 | specify the search path. Both default and user search path are then |
| 2888 | defined in setup files. |
| 2889 | @end itemize |
| 2890 | |
| 2891 | @noindent |
| 2892 | There are three ways to solve this problem: |
| 2893 | |
| 2894 | @itemize @bullet |
| 2895 | @item |
| 2896 | Specify all relevant directories explicitly in the environment |
| 2897 | variables. If for some reason you don't want to mess with the default |
| 2898 | variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own |
| 2899 | variables and configure @b{Ref@TeX{}} to use them instead: |
| 2900 | |
| 2901 | @lisp |
| 2902 | (setq reftex-texpath-environment-variables '("MYTEXINPUTS")) |
| 2903 | (setq reftex-bibpath-environment-variables '("MYBIBINPUTS")) |
| 2904 | @end lisp |
| 2905 | |
| 2906 | @item |
| 2907 | Specify the full search path directly in @b{Ref@TeX{}}'s variables. |
| 2908 | |
| 2909 | @lisp |
| 2910 | (setq reftex-texpath-environment-variables |
| 2911 | '("./inp:/home/cd/tex//:/usr/local/tex//")) |
| 2912 | (setq reftex-bibpath-environment-variables |
| 2913 | '("/home/cd/tex/lit/")) |
| 2914 | @end lisp |
| 2915 | |
| 2916 | @item |
| 2917 | Some TeX systems provide stand--alone programs to do the file search just |
| 2918 | like TeX and BibTeX. E.g. Thomas Esser's @code{teTeX} uses the |
| 2919 | @code{kpathsearch} library which provides the command @code{kpsewhich} |
| 2920 | to search for files. @b{Ref@TeX{}} can be configured to use this |
| 2921 | program. Note that the exact syntax of the @code{kpsewhich} |
| 2922 | command depends upon the version of that program. |
| 2923 | |
| 2924 | @lisp |
| 2925 | (setq reftex-use-external-file-finders t) |
| 2926 | (setq reftex-external-file-finders |
| 2927 | '(("tex" . "kpsewhich -format=.tex %f") |
| 2928 | ("bib" . "kpsewhich -format=.bib %f"))) |
| 2929 | @end lisp |
| 2930 | @end itemize |
| 2931 | |
| 2932 | @cindex Noweb files |
| 2933 | @vindex reftex-file-extensions |
| 2934 | @vindex TeX-file-extensions |
| 2935 | Some people like to use RefTeX with noweb files, which usually have the |
| 2936 | extension @file{.nw}. In order to deal with such files, the new |
| 2937 | extension must be added to the list of valid extensions in the variable |
| 2938 | @code{reftex-file-extensions}. When working with AUCTeX as major mode, |
| 2939 | the new extension must also be known to AUCTeX via the variable |
| 2940 | @code{TeX-file-extension}. For example: |
| 2941 | |
| 2942 | @lisp |
| 2943 | (setq reftex-file-extensions |
| 2944 | '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib"))) |
| 2945 | (setq TeX-file-extensions |
| 2946 | '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo")) |
| 2947 | @end lisp |
| 2948 | |
| 2949 | @node Optimizations, Problems and Work-Arounds, Finding Files, Top |
| 2950 | @section Optimizations |
| 2951 | @cindex Optimizations |
| 2952 | |
| 2953 | @b{Note added 2002. Computers have gotten a lot faster, so most of the |
| 2954 | optimizations discussed below will not be necessary on new machines. I |
| 2955 | am leaving this stuff in the manual for people who want to write thick |
| 2956 | books, where some of it still might be useful.} |
| 2957 | |
| 2958 | Implementing the principle of least surprises, the default settings of |
| 2959 | @b{Ref@TeX{}} ensure a safe ride for beginners and casual users. However, |
| 2960 | when using @b{Ref@TeX{}} for a large project and/or on a small computer, |
| 2961 | there are ways to improve speed or memory usage. |
| 2962 | |
| 2963 | @itemize @bullet |
| 2964 | @item |
| 2965 | @b{Removing Lookup Buffers}@* |
| 2966 | @cindex Removing lookup buffers |
| 2967 | @b{Ref@TeX{}} will load other parts of a multifile document as well as BibTeX |
| 2968 | database files for lookup purposes. These buffers are kept, so that |
| 2969 | subsequent use of the same files is fast. If you can't afford keeping |
| 2970 | these buffers around, and if you can live with a speed penalty, try |
| 2971 | |
| 2972 | @vindex reftex-keep-temporary-buffers |
| 2973 | @lisp |
| 2974 | (setq reftex-keep-temporary-buffers nil) |
| 2975 | @end lisp |
| 2976 | |
| 2977 | @item |
| 2978 | @b{Partial Document Scans}@* |
| 2979 | @cindex Partial documents scans |
| 2980 | @cindex Document scanning, partial |
| 2981 | A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label} |
| 2982 | (@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}), |
| 2983 | @code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c |
| 2984 | =}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates |
| 2985 | re-parsing of the entire document in order to update the parsing |
| 2986 | information. For a large document this can be unnecessary, in |
| 2987 | particular if only one file has changed. @b{Ref@TeX{}} can be configured |
| 2988 | to do partial scans instead of full ones. @kbd{C-u} re-parsing then |
| 2989 | does apply only to the current buffer and files included from it. |
| 2990 | Likewise, the @kbd{r} key in both the label selection buffer and the |
| 2991 | table-of-contents buffer will only prompt scanning of the file in which |
| 2992 | the label or section macro near the cursor was defined. Re-parsing of |
| 2993 | the entire document is still available by using @kbd{C-u C-u} as a |
| 2994 | prefix, or the capital @kbd{R} key in the menus. To use this feature, |
| 2995 | try |
| 2996 | |
| 2997 | @vindex reftex-enable-partial-scans |
| 2998 | @lisp |
| 2999 | (setq reftex-enable-partial-scans t) |
| 3000 | @end lisp |
| 3001 | |
| 3002 | @item |
| 3003 | @b{Saving Parser Information}@* |
| 3004 | @cindex Saving parser information |
| 3005 | @cindex Parse information, saving to a file |
| 3006 | @vindex reftex-parse-file-extension |
| 3007 | Even with partial scans enabled, @b{Ref@TeX{}} still has to make one full |
| 3008 | scan, when you start working with a document. To avoid this, parsing |
| 3009 | information can be stored in a file. The file @file{MASTER.rel} is used |
| 3010 | for storing information about a document with master file |
| 3011 | @file{MASTER.tex}. It is written automatically when you kill a buffer |
| 3012 | in @code{reftex-mode} or when you exit Emacs. The information is |
| 3013 | restored when you begin working with a document in a new editing |
| 3014 | session. To use this feature, put into @file{.emacs}: |
| 3015 | |
| 3016 | @vindex reftex-save-parse-info |
| 3017 | @lisp |
| 3018 | (setq reftex-save-parse-info t) |
| 3019 | @end lisp |
| 3020 | |
| 3021 | @item |
| 3022 | @b{Identifying label types by prefix}@* |
| 3023 | @cindex Parse information, saving to a file |
| 3024 | @vindex reftex-trust-label-prefix |
| 3025 | @b{Ref@TeX{}} normally parses around each label to check in which |
| 3026 | environment this label is located, in order to assign a label type to |
| 3027 | the label. If your document contains thousands of labels, document |
| 3028 | parsing will take considerable time. If you have been using label prefixes |
| 3029 | like tab: and fn: consistently, you can tell @b{Ref@TeX{}} to get the |
| 3030 | label type directly from the prefix, without additional parsing. This |
| 3031 | will be faster and also allow labels to end up in the correct category |
| 3032 | if for some reason it is not possible to derive the correct type from |
| 3033 | context. For example, to enable this feature for footnote and |
| 3034 | equation labels, use |
| 3035 | |
| 3036 | @lisp |
| 3037 | (setq reftex-trust-label-prefix '("fn:" "eq:")) |
| 3038 | @end lisp |
| 3039 | |
| 3040 | @item |
| 3041 | @b{Automatic Document Scans}@* |
| 3042 | @cindex Automatic document scans |
| 3043 | @cindex Document scanning, automatic |
| 3044 | At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the |
| 3045 | document. If this gets into your way, it can be turned off with |
| 3046 | |
| 3047 | @vindex reftex-allow-automatic-rescan |
| 3048 | @lisp |
| 3049 | (setq reftex-allow-automatic-rescan nil) |
| 3050 | @end lisp |
| 3051 | |
| 3052 | @b{Ref@TeX{}} will then occasionally annotate new labels in the selection |
| 3053 | buffer, saying that their position in the label list in uncertain. A |
| 3054 | manual document scan will fix this. |
| 3055 | |
| 3056 | @item |
| 3057 | @b{Multiple Selection Buffers}@* |
| 3058 | @cindex Multiple selection buffers |
| 3059 | @cindex Selection buffers, multiple |
| 3060 | Normally, the selection buffer @file{*RefTeX Select*} is re-created for |
| 3061 | every selection process. In documents with very many labels this can |
| 3062 | take several seconds. @b{Ref@TeX{}} provides an option to create a |
| 3063 | separate selection buffer for each label type and to keep this buffer |
| 3064 | from one selection to the next. These buffers are updated automatically |
| 3065 | only when a new label has been added in the buffers category with |
| 3066 | @code{reftex-label}. Updating the buffer takes as long as recreating it |
| 3067 | - so the time saving is limited to cases where no new labels of that |
| 3068 | category have been added. To turn on this feature, use |
| 3069 | |
| 3070 | @vindex reftex-use-multiple-selection-buffers |
| 3071 | @lisp |
| 3072 | (setq reftex-use-multiple-selection-buffers t) |
| 3073 | @end lisp |
| 3074 | |
| 3075 | @noindent |
| 3076 | @cindex Selection buffers, updating |
| 3077 | You can also inhibit the automatic updating entirely. Then the |
| 3078 | selection buffer will always pop up very fast, but may not contain the |
| 3079 | most recently defined labels. You can always update the buffer by hand, |
| 3080 | with the @kbd{g} key. To get this behavior, use instead |
| 3081 | |
| 3082 | @vindex reftex-auto-update-selection-buffers |
| 3083 | @lisp |
| 3084 | (setq reftex-use-multiple-selection-buffers t |
| 3085 | reftex-auto-update-selection-buffers nil) |
| 3086 | @end lisp |
| 3087 | @end itemize |
| 3088 | |
| 3089 | @need 2000 |
| 3090 | @noindent |
| 3091 | @b{As a summary}, here are the settings I recommend for heavy use of |
| 3092 | @b{Ref@TeX{}} with large documents: |
| 3093 | |
| 3094 | @lisp |
| 3095 | @group |
| 3096 | (setq reftex-enable-partial-scans t |
| 3097 | reftex-save-parse-info t |
| 3098 | reftex-use-multiple-selection-buffers t) |
| 3099 | @end group |
| 3100 | @end lisp |
| 3101 | |
| 3102 | @node AUCTeX, Multifile Documents, Faces, Top |
| 3103 | @section AUC@TeX{} |
| 3104 | @cindex @code{AUCTeX}, Emacs package |
| 3105 | @cindex Emacs packages, @code{AUCTeX} |
| 3106 | |
| 3107 | AUCTeX is without doubt the best major mode for editing TeX and LaTeX |
| 3108 | files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}). |
| 3109 | If AUCTeX is not part of your Emacs distribution, you can get |
| 3110 | it@footnote{XEmacs 21.x users may want to install the corresponding |
| 3111 | XEmacs package.} by ftp from the @value{AUCTEXSITE}. |
| 3112 | |
| 3113 | @menu |
| 3114 | * AUCTeX-RefTeX Interface:: How both packages work together |
| 3115 | * Style Files:: AUCTeX's style files can support RefTeX |
| 3116 | * Bib-Cite:: Hypertext reading of a document |
| 3117 | @end menu |
| 3118 | |
| 3119 | @node AUCTeX-RefTeX Interface, Style Files, , AUCTeX |
| 3120 | @subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface |
| 3121 | |
| 3122 | @b{Ref@TeX{}} contains code to interface with AUCTeX. When this |
| 3123 | interface is turned on, both packages will interact closely. Instead of |
| 3124 | using @b{Ref@TeX{}}'s commands directly, you can then also use them |
| 3125 | indirectly as part of the AUCTeX |
| 3126 | environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be |
| 3127 | needed for all of this to work. Parts of it work also with earlier |
| 3128 | versions.}. The interface is turned on with |
| 3129 | |
| 3130 | @lisp |
| 3131 | (setq reftex-plug-into-AUCTeX t) |
| 3132 | @end lisp |
| 3133 | |
| 3134 | If you need finer control about which parts of the interface are used |
| 3135 | and which not, read the docstring of the variable |
| 3136 | @code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x |
| 3137 | customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}. |
| 3138 | |
| 3139 | The following list describes the individual parts of the interface. |
| 3140 | |
| 3141 | @itemize @bullet |
| 3142 | @item |
| 3143 | @findex reftex-label |
| 3144 | @vindex LaTeX-label-function, @r{AUCTeX} |
| 3145 | @kindex C-c C-e |
| 3146 | @kindex C-c C-s |
| 3147 | @findex LaTeX-section, @r{AUCTeX} |
| 3148 | @findex TeX-insert-macro, @r{AUCTeX} |
| 3149 | @b{AUCTeX calls @code{reftex-label} to insert labels}@* |
| 3150 | When a new section is created with @kbd{C-c C-s}, or a new environment |
| 3151 | is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to |
| 3152 | go with it. With the interface, @code{reftex-label} is called instead. |
| 3153 | For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and |
| 3154 | @b{Ref@TeX{}} will insert |
| 3155 | |
| 3156 | @example |
| 3157 | \begin@{equation@} |
| 3158 | \label@{eq:1@} |
| 3159 | |
| 3160 | \end@{equation@} |
| 3161 | @end example |
| 3162 | |
| 3163 | @noindent |
| 3164 | without further prompts. |
| 3165 | |
| 3166 | Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}} |
| 3167 | will offer its default label which is derived from the section title. |
| 3168 | |
| 3169 | @item |
| 3170 | @b{AUCTeX tells @b{Ref@TeX{}} about new sections}@* |
| 3171 | When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not |
| 3172 | have to rescan the buffer in order to see it. |
| 3173 | |
| 3174 | @item |
| 3175 | @findex reftex-arg-label |
| 3176 | @findex TeX-arg-label, @r{AUCTeX function} |
| 3177 | @findex reftex-arg-ref |
| 3178 | @findex TeX-arg-ref, @r{AUCTeX function} |
| 3179 | @findex reftex-arg-cite |
| 3180 | @findex TeX-arg-cite, @r{AUCTeX function} |
| 3181 | @findex reftex-arg-index |
| 3182 | @findex TeX-arg-index, @r{AUCTeX function} |
| 3183 | @findex TeX-insert-macro, @r{AUCTeX function} |
| 3184 | @kindex C-c @key{RET} |
| 3185 | @b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro |
| 3186 | interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for |
| 3187 | macro arguments. Internally, it uses the functions |
| 3188 | @code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to |
| 3189 | prompt for arguments which are labels, citation keys and index entries. |
| 3190 | The interface takes over these functions@footnote{@code{fset} is used to |
| 3191 | do this, which is not reversible. However, @b{Ref@TeX{}} implements the |
| 3192 | old functionality when you later decide to turn off the interface.} and |
| 3193 | supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms. For |
| 3194 | example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}} |
| 3195 | will supply its label selection process (@pxref{Referencing |
| 3196 | Labels}). |
| 3197 | |
| 3198 | @item |
| 3199 | @b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@* |
| 3200 | @b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list. |
| 3201 | @end itemize |
| 3202 | |
| 3203 | @node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX |
| 3204 | @subsection Style Files |
| 3205 | @cindex Style files, AUCTeX |
| 3206 | @findex TeX-add-style-hook, @r{AUCTeX} |
| 3207 | Style files are Emacs Lisp files which are evaluated by AUCTeX in |
| 3208 | association with the @code{\documentclass} and @code{\usepackage} |
| 3209 | commands of a document (@pxref{Style Files,,,auctex}). Support for |
| 3210 | @b{Ref@TeX{}} in such a style file is useful when the LaTeX style |
| 3211 | defines macros or environments connected with labels, citations, or the |
| 3212 | index. Many style files (e.g. @file{amsmath.el} or @file{natbib.el}) |
| 3213 | distributed with AUCTeX already support @b{Ref@TeX{}} in this |
| 3214 | way. |
| 3215 | |
| 3216 | Before calling a @b{Ref@TeX{}} function, the style hook should always |
| 3217 | test for the availability of the function, so that the style file will |
| 3218 | also work for people who do not use @b{Ref@TeX{}}. |
| 3219 | |
| 3220 | Additions made with style files in the way described below remain local |
| 3221 | to the current document. For example, if one package uses AMSTeX, the |
| 3222 | style file will make @b{Ref@TeX{}} switch over to @code{\eqref}, but |
| 3223 | this will not affect other documents. |
| 3224 | |
| 3225 | @findex reftex-add-label-environments |
| 3226 | @findex reftex-add-to-label-alist |
| 3227 | A style hook may contain calls to |
| 3228 | @code{reftex-add-label-environments}@footnote{This used to be the |
| 3229 | function @code{reftex-add-to-label-alist} which is still available as an |
| 3230 | alias for compatibility.} which defines additions to |
| 3231 | @code{reftex-label-alist}. The argument taken by this function must have |
| 3232 | the same format as @code{reftex-label-alist}. The @file{amsmath.el} |
| 3233 | style file of AUCTeX for example contains the following: |
| 3234 | |
| 3235 | @lisp |
| 3236 | @group |
| 3237 | (TeX-add-style-hook "amsmath" |
| 3238 | (lambda () |
| 3239 | (if (fboundp 'reftex-add-label-environments) |
| 3240 | (reftex-add-label-environments '(AMSTeX))))) |
| 3241 | @end group |
| 3242 | @end lisp |
| 3243 | |
| 3244 | @noindent |
| 3245 | @findex LaTeX-add-environments, @r{AUCTeX} |
| 3246 | while a package @code{myprop} defining a @code{proposition} environment |
| 3247 | with @code{\newtheorem} might use |
| 3248 | |
| 3249 | @lisp |
| 3250 | @group |
| 3251 | (TeX-add-style-hook "myprop" |
| 3252 | (lambda () |
| 3253 | (LaTeX-add-environments '("proposition" LaTeX-env-label)) |
| 3254 | (if (fboundp 'reftex-add-label-environments) |
| 3255 | (reftex-add-label-environments |
| 3256 | '(("proposition" ?p "prop:" "~\\ref@{%s@}" t |
| 3257 | ("Proposition" "Prop.") -3)))))) |
| 3258 | @end group |
| 3259 | @end lisp |
| 3260 | |
| 3261 | @findex reftex-set-cite-format |
| 3262 | Similarly, a style hook may contain a call to |
| 3263 | @code{reftex-set-cite-format} to set the citation format. The style |
| 3264 | file @file{natbib.el} for the Natbib citation style does switch |
| 3265 | @b{Ref@TeX{}}'s citation format like this: |
| 3266 | |
| 3267 | @lisp |
| 3268 | (TeX-add-style-hook "natbib" |
| 3269 | (lambda () |
| 3270 | (if (fboundp 'reftex-set-cite-format) |
| 3271 | (reftex-set-cite-format 'natbib)))) |
| 3272 | @end lisp |
| 3273 | |
| 3274 | @findex reftex-add-index-macros |
| 3275 | The hook may contain a call to @code{reftex-add-index-macros} to |
| 3276 | define additional @code{\index}-like macros. The argument must have |
| 3277 | the same format as @code{reftex-index-macros}. It may be a symbol, to |
| 3278 | trigger support for one of the builtin index packages. For example, |
| 3279 | the style @file{multind.el} contains |
| 3280 | |
| 3281 | @lisp |
| 3282 | (TeX-add-style-hook "multind" |
| 3283 | (lambda () |
| 3284 | (and (fboundp 'reftex-add-index-macros) |
| 3285 | (reftex-add-index-macros '(multind))))) |
| 3286 | @end lisp |
| 3287 | |
| 3288 | If you have your own package @file{myindex} which defines the |
| 3289 | following macros to be used with the LaTeX @file{index.sty} file |
| 3290 | @example |
| 3291 | \newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@} |
| 3292 | \newcommand@{\aindex@}[1]@{#1\index[author]@{#1@} |
| 3293 | @end example |
| 3294 | |
| 3295 | you could write this in the style file @file{myindex.el}: |
| 3296 | |
| 3297 | @lisp |
| 3298 | (TeX-add-style-hook "myindex" |
| 3299 | (lambda () |
| 3300 | (TeX-add-symbols |
| 3301 | '("molec" TeX-arg-index) |
| 3302 | '("aindex" TeX-arg-index)) |
| 3303 | (if (fboundp 'reftex-add-index-macros) |
| 3304 | (reftex-add-index-macros |
| 3305 | '(("molec@{*@}" "idx" ?m "Molecules!" nil nil) |
| 3306 | ("aindex@{*@}" "author" ?a "" nil nil)))))) |
| 3307 | @end lisp |
| 3308 | |
| 3309 | @findex reftex-add-section-levels |
| 3310 | Finally the hook may contain a call to @code{reftex-add-section-levels} |
| 3311 | to define additional section statements. For example, the FoilTeX class |
| 3312 | has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here |
| 3313 | is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these: |
| 3314 | |
| 3315 | @lisp |
| 3316 | (TeX-add-style-hook "foils" |
| 3317 | (lambda () |
| 3318 | (if (fboundp 'reftex-add-section-levels) |
| 3319 | (reftex-add-section-levels '(("foilhead" . 3) |
| 3320 | ("rotatefoilhead" . 3)))))) |
| 3321 | @end lisp |
| 3322 | |
| 3323 | @node Bib-Cite, , Style Files, AUCTeX |
| 3324 | @subsection Bib-Cite |
| 3325 | @cindex @code{bib-cite}, Emacs package |
| 3326 | @cindex Emacs packages, @code{bib-cite} |
| 3327 | |
| 3328 | Once you have written a document with labels, references and citations, |
| 3329 | it can be nice to read it like a hypertext document. @b{Ref@TeX{}} has |
| 3330 | support for that: @code{reftex-view-crossref} (bound to @kbd{C-c |
| 3331 | &}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and |
| 3332 | @code{reftex-search-document}. A somewhat fancier interface with mouse |
| 3333 | highlighting is provided (among other things) by Peter S. Galbraith's |
| 3334 | @file{bib-cite.el}. There is some overlap in the functionalities of |
| 3335 | Bib-cite and @b{Ref@TeX{}}. Bib-cite.el comes bundled with |
| 3336 | AUCTeX. |
| 3337 | |
| 3338 | Bib-cite version 3.06 and later can be configured so that bib-cite's |
| 3339 | mouse functions use @b{Ref@TeX{}} for displaying references and citations. |
| 3340 | This can be useful in particular when working with the LaTeX @code{xr} |
| 3341 | package or with an explicit @code{thebibliography} environment (rather |
| 3342 | than BibTeX). Bib-cite cannot handle those, but @b{Ref@TeX{}} does. To |
| 3343 | make use of this feature, try |
| 3344 | |
| 3345 | @vindex bib-cite-use-reftex-view-crossref |
| 3346 | @lisp |
| 3347 | (setq bib-cite-use-reftex-view-crossref t) |
| 3348 | @end lisp |
| 3349 | |
| 3350 | @page |
| 3351 | @node Problems and Work-Arounds, Imprint, Optimizations, Top |
| 3352 | @section Problems and Work-arounds |
| 3353 | @cindex Problems and work-arounds |
| 3354 | |
| 3355 | @itemize @bullet |
| 3356 | @item |
| 3357 | @b{LaTeX commands}@* |
| 3358 | @cindex LaTeX commands, not found |
| 3359 | @code{\input}, @code{\include}, and @code{\section} (etc.) statements |
| 3360 | have to be first on a line (except for white space). |
| 3361 | |
| 3362 | @item |
| 3363 | @b{Commented regions}@* |
| 3364 | @cindex Labels, commented out |
| 3365 | @b{Ref@TeX{}} sees also labels in regions commented out and will refuse to |
| 3366 | make duplicates of such labels. This is considered to be a feature. |
| 3367 | |
| 3368 | @item |
| 3369 | @b{Wrong section numbers}@* |
| 3370 | @cindex Section numbers, wrong |
| 3371 | @vindex reftex-enable-partial-scans |
| 3372 | When using partial scans (@code{reftex-enable-partial-scans}), the section |
| 3373 | numbers in the table of contents may eventually become wrong. A full |
| 3374 | scan will fix this. |
| 3375 | |
| 3376 | @item |
| 3377 | @b{Local settings}@* |
| 3378 | @cindex Settings, local |
| 3379 | @findex reftex-add-label-environments |
| 3380 | @findex reftex-set-cite-format |
| 3381 | @findex reftex-add-section-levels |
| 3382 | The label environment definitions in @code{reftex-label-alist} are |
| 3383 | global and apply to all documents. If you need to make definitions |
| 3384 | local to a document, because they would interfere with settings in other |
| 3385 | documents, you should use AUCTeX and set up style files with calls to |
| 3386 | @code{reftex-add-label-environments}, @code{reftex-set-cite-format}, |
| 3387 | @code{reftex-add-index-macros}, and @code{reftex-add-section-levels}. |
| 3388 | Settings made with these functions remain local to the current |
| 3389 | document. @xref{AUCTeX}. |
| 3390 | |
| 3391 | @item |
| 3392 | @b{Funny display in selection buffer}@* |
| 3393 | @cindex @code{x-symbol}, Emacs package |
| 3394 | @cindex Emacs packages, @code{x-symbol} |
| 3395 | @cindex @code{isotex}, Emacs package |
| 3396 | @cindex Emacs packages, @code{isotex} |
| 3397 | @cindex @code{iso-cvt}, Emacs package |
| 3398 | @cindex Emacs packages, @code{iso-cvt} |
| 3399 | When using packages which make the buffer representation of a file |
| 3400 | different from its disk representation (e.g. x-symbol, isotex, |
| 3401 | iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimes |
| 3402 | reflects the disk state of a file. This happens only in @emph{unvisited} |
| 3403 | parts of a multifile document, because @b{Ref@TeX{}} visits these files |
| 3404 | literally for speed reasons. Then both short context and section |
| 3405 | headings may look different from what you usually see on your screen. |
| 3406 | In rare cases @code{reftex-toc} may have problems to jump to an affected |
| 3407 | section heading. There are three possible ways to deal with |
| 3408 | this: |
| 3409 | @itemize @minus |
| 3410 | @item |
| 3411 | @vindex reftex-keep-temporary-buffers |
| 3412 | @code{(setq reftex-keep-temporary-buffers t)}@* |
| 3413 | This implies that @b{Ref@TeX{}} will load all parts of a multifile |
| 3414 | document into Emacs (i.e. there won't be any temporary buffers). |
| 3415 | @item |
| 3416 | @vindex reftex-initialize-temporary-buffers |
| 3417 | @code{(setq reftex-initialize-temporary-buffers t)}@* |
| 3418 | This means full initialization of temporary buffers. It involves |
| 3419 | a penalty when the same unvisited file is used for lookup often. |
| 3420 | @item |
| 3421 | Set @code{reftex-initialize-temporary-buffers} to a list of hook |
| 3422 | functions doing a minimal initialization. |
| 3423 | @end itemize |
| 3424 | @vindex reftex-refontify-context |
| 3425 | See also the variable @code{reftex-refontify-context}. |
| 3426 | |
| 3427 | @item |
| 3428 | @b{Labels as arguments to \begin}@* |
| 3429 | @cindex @code{pf}, LaTeX package |
| 3430 | @cindex LaTeX packages, @code{pf} |
| 3431 | Some packages use an additional argument to a @code{\begin} macro |
| 3432 | to specify a label. E.g. Lamport's @file{pf.sty} uses both |
| 3433 | @example |
| 3434 | \step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@} |
| 3435 | @var{claim} |
| 3436 | \end@{step+@} |
| 3437 | @end example |
| 3438 | |
| 3439 | @noindent |
| 3440 | We need to trick @b{Ref@TeX{}} into swallowing this: |
| 3441 | |
| 3442 | @lisp |
| 3443 | @group |
| 3444 | ;; Configuration for Lamport's pf.sty |
| 3445 | (setq reftex-label-alist |
| 3446 | '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St.")) |
| 3447 | ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000))) |
| 3448 | @end group |
| 3449 | @end lisp |
| 3450 | |
| 3451 | @noindent |
| 3452 | The first line is just a normal configuration for a macro. For the |
| 3453 | @code{step+} environment we actually tell @b{Ref@TeX{}} to look for the |
| 3454 | @emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first} |
| 3455 | argument (which really is a second argument to the macro @code{\begin}) |
| 3456 | as a label of type @code{?p}. Argument count for this macro starts only |
| 3457 | after the @samp{@{step+@}}, also when specifying how to get |
| 3458 | context. |
| 3459 | |
| 3460 | @item |
| 3461 | @b{Idle timers in XEmacs}@* |
| 3462 | @cindex Idle timer restart |
| 3463 | @vindex reftex-use-itimer-in-xemacs |
| 3464 | In XEmacs, idle timer restart does not work reliably after fast |
| 3465 | keystrokes. Therefore @b{Ref@TeX{}} currently uses the post command |
| 3466 | hook to start the timer used for automatic crossref information. When |
| 3467 | this bug gets fixed, a real idle timer can be requested with |
| 3468 | @lisp |
| 3469 | (setq reftex-use-itimer-in-xemacs t) |
| 3470 | @end lisp |
| 3471 | |
| 3472 | @item |
| 3473 | @b{Viper mode}@* |
| 3474 | @cindex Viper mode |
| 3475 | @cindex Key bindings, problems with Viper mode |
| 3476 | @findex viper-harness-minor-mode |
| 3477 | With @i{Viper} mode prior to Vipers version 3.01, you need to protect |
| 3478 | @b{Ref@TeX{}}'s keymaps with |
| 3479 | |
| 3480 | @lisp |
| 3481 | (viper-harness-minor-mode "reftex") |
| 3482 | @end lisp |
| 3483 | |
| 3484 | @end itemize |
| 3485 | |
| 3486 | @page |
| 3487 | @node Imprint, Commands, Problems and Work-Arounds, Top |
| 3488 | @section Imprint |
| 3489 | @cindex Imprint |
| 3490 | @cindex Maintainer |
| 3491 | @cindex Acknowledgments |
| 3492 | @cindex Thanks |
| 3493 | @cindex Bug reports |
| 3494 | @cindex @code{http}, @b{Ref@TeX{}} home page |
| 3495 | @cindex @code{ftp}, @b{Ref@TeX{}} site |
| 3496 | |
| 3497 | Ref@TeX{} was written by @i{Carsten Dominik} |
| 3498 | @email{dominik@@science.uva.nl}, with contributions by @i{Stephen |
| 3499 | Eglen}. Ref@TeX{} is currently maintained by @value{MAINTAINER}, see |
| 3500 | the @value{MAINTAINERSITE} for detailed information. |
| 3501 | |
| 3502 | If you have questions about Ref@TeX{}, you can send email to the |
| 3503 | @value{SUPPORTADDRESS}. If you want to contribute code or ideas, write |
| 3504 | to the @value{DEVELADDRESS}. And in the rare case of finding a bug, |
| 3505 | please use @kbd{M-x reftex-report-bug @key{RET}} which will prepare a |
| 3506 | bug report with useful information about your setup. Remember to add |
| 3507 | essential information like a recipe for reproducing the bug, what you |
| 3508 | expected to happen, and what actually happened. Send the bug report to |
| 3509 | the @value{BUGADDRESS}. |
| 3510 | |
| 3511 | There are also several Usenet groups which have competent readers who |
| 3512 | might be able to help: @code{comp.emacs}, @code{gnu.emacs.help}, |
| 3513 | @code{comp.emacs.xemacs}, and @code{comp.text.tex}. |
| 3514 | |
| 3515 | @b{Ref@TeX{}} is bundled and pre-installed with Emacs since version 20.2. |
| 3516 | It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs |
| 3517 | 21.x users want to install the corresponding plugin package which is |
| 3518 | available from the @value{XEMACSFTP}. See the XEmacs 21.x |
| 3519 | documentation on package installation for details. |
| 3520 | |
| 3521 | Users of earlier Emacs distributions (including Emacs 19) can get a |
| 3522 | @b{Ref@TeX{}} distribution from the @value{MAINTAINERSITE}. Note that |
| 3523 | the Emacs 19 version supports many but not all features described in |
| 3524 | this manual. |
| 3525 | |
| 3526 | Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped |
| 3527 | developing it with their reports. In particular thanks to @i{Ralf |
| 3528 | Angeli, Fran Burstall, Alastair Burt, Lars Clausen, Soren Dayton, |
| 3529 | Stephen Eglen, Karl Eichwalder, Erik Frisk, Peter Galbraith, Kai |
| 3530 | Grossjohann, Frank Harrell, Till A. Heilmann, Peter Heslin, Stephan |
| 3531 | Heuel, Alan Ho, Lute Kamstra, Dieter Kraft, David Kastrup, Adrian Lanz, |
| 3532 | Juri Linkov, Rory Molinari, Stefan Monnier, Laurent Mugnier, Dan |
| 3533 | Nicolaescu, Sudeep Kumar Palat, Daniel Polani, Alan Shutko, Robin Socha, |
| 3534 | Richard Stanton, Allan Strand, Jan Vroonhof, Christoph Wedler, Alan |
| 3535 | Williams, Roland Winkler, Hans-Christoph Wirth, Eli Zaretskii}. |
| 3536 | |
| 3537 | |
| 3538 | The @code{view-crossref} feature was inspired by @i{Peter Galbraith's} |
| 3539 | @file{bib-cite.el}. |
| 3540 | |
| 3541 | Finally thanks to @i{Uwe Bolick} who first got me interested in |
| 3542 | supporting LaTeX labels and references with an editor (which was |
| 3543 | MicroEmacs at the time). |
| 3544 | |
| 3545 | @node Commands, Options, Imprint, Top |
| 3546 | @chapter Commands |
| 3547 | @cindex Commands, list of |
| 3548 | |
| 3549 | Here is a summary of @b{Ref@TeX{}}'s commands which can be executed from |
| 3550 | LaTeX files. Command which are executed from the special buffers are |
| 3551 | not described here. All commands are available from the @code{Ref} |
| 3552 | menu. See @xref{Key Bindings}. |
| 3553 | |
| 3554 | @deffn Command reftex-toc |
| 3555 | Show the table of contents for the current document. When called with |
| 3556 | one ore two @kbd{C-u} prefixes, rescan the document first. |
| 3557 | @end deffn |
| 3558 | |
| 3559 | @deffn Command reftex-label |
| 3560 | Insert a unique label. With one or two @kbd{C-u} prefixes, enforce |
| 3561 | document rescan first. |
| 3562 | @end deffn |
| 3563 | |
| 3564 | @deffn Command reftex-reference |
| 3565 | Start a selection process to select a label, and insert a reference to |
| 3566 | it. With one or two @kbd{C-u} prefixes, enforce document rescan first. |
| 3567 | @end deffn |
| 3568 | |
| 3569 | @deffn Command reftex-citation |
| 3570 | Make a citation using BibTeX database files. After prompting for a regular |
| 3571 | expression, scans the buffers with BibTeX entries (taken from the |
| 3572 | @code{\bibliography} command or a @code{thebibliography} environment) |
| 3573 | and offers the matching entries for selection. The selected entry is |
| 3574 | formatted according to @code{reftex-cite-format} and inserted into the |
| 3575 | buffer. @* |
| 3576 | When called with a @kbd{C-u} prefix, prompt for optional arguments in |
| 3577 | cite macros. When called with a numeric prefix, make that many citations. |
| 3578 | When called with point inside the braces of a @code{\cite} command, it |
| 3579 | will add another key, ignoring the value of |
| 3580 | @code{reftex-cite-format}. @* |
| 3581 | The regular expression uses an expanded syntax: @samp{&&} is interpreted |
| 3582 | as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain |
| 3583 | both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion |
| 3584 | on knows citation keys is possible. @samp{=} is a good regular |
| 3585 | expression to match all entries in all files. |
| 3586 | @end deffn |
| 3587 | |
| 3588 | @deffn Command reftex-index |
| 3589 | Query for an index macro and insert it along with its arguments. The |
| 3590 | index macros available are those defined in @code{reftex-index-macro} or |
| 3591 | by a call to @code{reftex-add-index-macros}, typically from an AUCTeX |
| 3592 | style file. @b{Ref@TeX{}} provides completion for the index tag and the |
| 3593 | index key, and will prompt for other arguments. |
| 3594 | @end deffn |
| 3595 | |
| 3596 | @deffn Command reftex-index-selection-or-word |
| 3597 | Put current selection or the word near point into the default index |
| 3598 | macro. This uses the information in @code{reftex-index-default-macro} |
| 3599 | to make an index entry. The phrase indexed is the current selection or |
| 3600 | the word near point. When called with one @kbd{C-u} prefix, let the |
| 3601 | user have a chance to edit the index entry. When called with 2 |
| 3602 | @kbd{C-u} as prefix, also ask for the index macro and other stuff. When |
| 3603 | called inside TeX math mode as determined by the @file{texmathp.el} |
| 3604 | library which is part of AUCTeX, the string is first processed with the |
| 3605 | @code{reftex-index-math-format}, which see. |
| 3606 | @end deffn |
| 3607 | |
| 3608 | @deffn Command reftex-index-phrase-selection-or-word |
| 3609 | Add current selection or the word at point to the phrases buffer. |
| 3610 | When you are in transient-mark-mode and the region is active, the |
| 3611 | selection will be used - otherwise the word at point. |
| 3612 | You get a chance to edit the entry in the phrases buffer - to save the |
| 3613 | buffer and return to the LaTeX document, finish with @kbd{C-c C-c}. |
| 3614 | @end deffn |
| 3615 | |
| 3616 | @deffn Command reftex-index-visit-phrases-buffer |
| 3617 | Switch to the phrases buffer, initialize if empty. |
| 3618 | @end deffn |
| 3619 | |
| 3620 | @deffn Command reftex-index-phrases-apply-to-region |
| 3621 | Index all index phrases in the current region. |
| 3622 | This works exactly like global indexing from the index phrases buffer, |
| 3623 | but operation is restricted to the current region. |
| 3624 | @end deffn |
| 3625 | |
| 3626 | @deffn Command reftex-display-index |
| 3627 | Display a buffer with an index compiled from the current document. |
| 3628 | When the document has multiple indices, first prompts for the correct one. |
| 3629 | When index support is turned off, offer to turn it on. |
| 3630 | With one or two @kbd{C-u} prefixes, rescan document first. |
| 3631 | With prefix 2, restrict index to current document section. |
| 3632 | With prefix 3, restrict index to active region. |
| 3633 | @end deffn |
| 3634 | |
| 3635 | @deffn Command reftex-view-crossref |
| 3636 | View cross reference of macro at point. Point must be on the @var{key} |
| 3637 | argument. Works with the macros @code{\label}, @code{\ref}, |
| 3638 | @code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of |
| 3639 | these. Where it makes sense, subsequent calls show additional |
| 3640 | locations. See also the variable @code{reftex-view-crossref-extra} and |
| 3641 | the command @code{reftex-view-crossref-from-bibtex}. With one or two |
| 3642 | @kbd{C-u} prefixes, enforce rescanning of the document. With argument |
| 3643 | 2, select the window showing the cross reference. |
| 3644 | @end deffn |
| 3645 | |
| 3646 | @deffn Command reftex-view-crossref-from-bibtex |
| 3647 | View location in a LaTeX document which cites the BibTeX entry at point. |
| 3648 | Since BibTeX files can be used by many LaTeX documents, this function |
| 3649 | prompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset this |
| 3650 | link to a document, call the function with a prefix arg. Calling |
| 3651 | this function several times find successive citation locations. |
| 3652 | @end deffn |
| 3653 | |
| 3654 | @deffn Command reftex-create-tags-file |
| 3655 | Create TAGS file by running @code{etags} on the current document. The |
| 3656 | TAGS file is also immediately visited with |
| 3657 | @code{visit-tags-table}. |
| 3658 | @end deffn |
| 3659 | |
| 3660 | @deffn Command reftex-grep-document |
| 3661 | Run grep query through all files related to this document. |
| 3662 | With prefix arg, force to rescan document. |
| 3663 | No active TAGS table is required. |
| 3664 | @end deffn |
| 3665 | |
| 3666 | @deffn Command reftex-search-document |
| 3667 | Regexp search through all files of the current document. |
| 3668 | Starts always in the master file. Stops when a match is found. |
| 3669 | No active TAGS table is required. |
| 3670 | @end deffn |
| 3671 | |
| 3672 | @deffn Command reftex-query-replace-document |
| 3673 | Run a query-replace-regexp of @var{from} with @var{to} over the entire |
| 3674 | document. With prefix arg, replace only word-delimited matches. No |
| 3675 | active TAGS table is required. |
| 3676 | @end deffn |
| 3677 | |
| 3678 | @deffn Command reftex-isearch-minor-mode |
| 3679 | Toggle a minor mode which enables incremental search to work globally |
| 3680 | on the entire multifile document. Files will be searched in th |
| 3681 | sequence they appear in the document. |
| 3682 | @end deffn |
| 3683 | |
| 3684 | @deffn Command reftex-goto-label |
| 3685 | Prompt for a label (with completion) and jump to the location of this |
| 3686 | label. Optional prefix argument @var{other-window} goes to the label in |
| 3687 | another window. |
| 3688 | @end deffn |
| 3689 | |
| 3690 | |
| 3691 | @deffn Command reftex-change-label |
| 3692 | Query replace @var{from} with @var{to} in all @code{\label} and |
| 3693 | @code{\ref} commands. Works on the entire multifile document. No |
| 3694 | active TAGS table is required. |
| 3695 | @end deffn |
| 3696 | |
| 3697 | @deffn Command reftex-renumber-simple-labels |
| 3698 | Renumber all simple labels in the document to make them sequentially. |
| 3699 | Simple labels are the ones created by RefTeX, consisting only of the |
| 3700 | prefix and a number. After the command completes, all these labels will |
| 3701 | have sequential numbers throughout the document. Any references to the |
| 3702 | labels will be changed as well. For this, @b{Ref@TeX{}} looks at the |
| 3703 | arguments of any macros which either start or end with the string |
| 3704 | @samp{ref}. This command should be used with care, in particular in |
| 3705 | multifile documents. You should not use it if another document refers |
| 3706 | to this one with the @code{xr} package. |
| 3707 | @end deffn |
| 3708 | |
| 3709 | @deffn Command reftex-find-duplicate-labels |
| 3710 | Produce a list of all duplicate labels in the document. |
| 3711 | @end deffn |
| 3712 | |
| 3713 | @deffn Command reftex-create-bibtex-file |
| 3714 | Create a new BibTeX database file with all entries referenced in document. |
| 3715 | The command prompts for a filename and writes the collected entries to |
| 3716 | that file. Only entries referenced in the current document with |
| 3717 | any @code{\cite}-like macros are used. |
| 3718 | The sequence in the new file is the same as it was in the old database. |
| 3719 | @end deffn |
| 3720 | |
| 3721 | @deffn Command reftex-customize |
| 3722 | Run the customize browser on the @b{Ref@TeX{}} group. |
| 3723 | @end deffn |
| 3724 | @deffn Command reftex-show-commentary |
| 3725 | Show the commentary section from @file{reftex.el}. |
| 3726 | @end deffn |
| 3727 | @deffn Command reftex-info |
| 3728 | Run info on the top @b{Ref@TeX{}} node. |
| 3729 | @end deffn |
| 3730 | @deffn Command reftex-parse-document |
| 3731 | Parse the entire document in order to update the parsing information. |
| 3732 | @end deffn |
| 3733 | @deffn Command reftex-reset-mode |
| 3734 | Enforce rebuilding of several internal lists and variables. Also |
| 3735 | removes the parse file associated with the current document. |
| 3736 | @end deffn |
| 3737 | |
| 3738 | @node Options, Keymaps and Hooks, Commands, Top |
| 3739 | @chapter Options, Keymaps, Hooks |
| 3740 | @cindex Options, list of |
| 3741 | |
| 3742 | Here is a complete list of @b{Ref@TeX{}}'s configuration variables. All |
| 3743 | variables have customize support - so if you are not familiar with Emacs |
| 3744 | Lisp (and even if you are) you might find it more comfortable to use |
| 3745 | @code{customize} to look at and change these variables. @kbd{M-x |
| 3746 | reftex-customize} will get you there. |
| 3747 | |
| 3748 | @menu |
| 3749 | * Options (Table of Contents):: |
| 3750 | * Options (Defining Label Environments):: |
| 3751 | * Options (Creating Labels):: |
| 3752 | * Options (Referencing Labels):: |
| 3753 | * Options (Creating Citations):: |
| 3754 | * Options (Index Support):: |
| 3755 | * Options (Viewing Cross-References):: |
| 3756 | * Options (Finding Files):: |
| 3757 | * Options (Optimizations):: |
| 3758 | * Options (Fontification):: |
| 3759 | * Options (Misc):: |
| 3760 | @end menu |
| 3761 | |
| 3762 | @node Options (Table of Contents), Options (Defining Label Environments), , Options |
| 3763 | @section Table of Contents |
| 3764 | @cindex Options, table of contents |
| 3765 | @cindex Table of contents, options |
| 3766 | |
| 3767 | @defopt reftex-include-file-commands |
| 3768 | List of LaTeX commands which input another file. |
| 3769 | The file name is expected after the command, either in braces or separated |
| 3770 | by whitespace. |
| 3771 | @end defopt |
| 3772 | |
| 3773 | @defopt reftex-max-section-depth |
| 3774 | Maximum depth of section levels in document structure. |
| 3775 | Standard LaTeX needs 7, default is 12. |
| 3776 | @end defopt |
| 3777 | |
| 3778 | @defopt reftex-section-levels |
| 3779 | Commands and levels used for defining sections in the document. The |
| 3780 | @code{car} of each cons cell is the name of the section macro. The |
| 3781 | @code{cdr} is a number indicating its level. A negative level means the |
| 3782 | same as the positive value, but the section will never get a number. |
| 3783 | The @code{cdr} may also be a function which then has to return the |
| 3784 | level. This list is also used for promotion and demotion of sectioning |
| 3785 | commands. If you are using a document class which has several sets of |
| 3786 | sectioning commands, promotion only works correctly if this list is |
| 3787 | sorted first by set, then within each set by level. The promotion |
| 3788 | commands always select the nearest entry with the correct new level. |
| 3789 | |
| 3790 | @end defopt |
| 3791 | |
| 3792 | @defopt reftex-toc-max-level |
| 3793 | The maximum level of toc entries which will be included in the TOC. |
| 3794 | Section headings with a bigger level will be ignored. In RefTeX, |
| 3795 | chapters are level 1, sections level 2 etc. This variable can be |
| 3796 | changed from within the @file{*toc*} buffer with the @kbd{t} key. |
| 3797 | @end defopt |
| 3798 | |
| 3799 | @defopt reftex-part-resets-chapter |
| 3800 | Non-@code{nil} means, @code{\part} is like any other sectioning command. |
| 3801 | This means, part numbers will be included in the numbering of chapters, and |
| 3802 | chapter counters will be reset for each part. |
| 3803 | When @code{nil} (the default), parts are special, do not reset the |
| 3804 | chapter counter and also do not show up in chapter numbers. |
| 3805 | @end defopt |
| 3806 | |
| 3807 | @defopt reftex-auto-recenter-toc |
| 3808 | Non-@code{nil} means, turn automatic recentering of @file{*TOC*} window on. |
| 3809 | When active, the @file{*TOC*} window will always show the section you |
| 3810 | are currently working in. Recentering happens whenever Emacs is idle for |
| 3811 | more than @code{reftex-idle-time} seconds. |
| 3812 | |
| 3813 | Value @code{t} means, turn on immediately when RefTeX gets started. Then, |
| 3814 | recentering will work for any toc window created during the session. |
| 3815 | |
| 3816 | Value @code{frame} (the default) means, turn automatic recentering on |
| 3817 | only while the dedicated TOC frame does exist, and do the recentering |
| 3818 | only in that frame. So when creating that frame (with @kbd{d} key in an |
| 3819 | ordinary TOC window), the automatic recentering is turned on. When the |
| 3820 | frame gets destroyed, automatic recentering is turned off again. |
| 3821 | |
| 3822 | This feature can be turned on and off from the menu |
| 3823 | (Ref->Options). |
| 3824 | @end defopt |
| 3825 | |
| 3826 | @defopt reftex-toc-split-windows-horizontally |
| 3827 | Non-@code{nil} means, create TOC window by splitting window |
| 3828 | horizontally. The default is to split vertically. |
| 3829 | @end defopt |
| 3830 | |
| 3831 | @defopt reftex-toc-split-windows-fraction |
| 3832 | Fraction of the width or height of the frame to be used for TOC window. |
| 3833 | @end defopt |
| 3834 | |
| 3835 | @defopt reftex-toc-keep-other-windows |
| 3836 | Non-@code{nil} means, split the selected window to display the |
| 3837 | @file{*toc*} buffer. This helps to keep the window configuration, but |
| 3838 | makes the @file{*toc*} small. When @code{nil}, all other windows except |
| 3839 | the selected one will be deleted, so that the @file{*toc*} window fills |
| 3840 | half the frame. |
| 3841 | @end defopt |
| 3842 | |
| 3843 | @defopt reftex-toc-include-file-boundaries |
| 3844 | Non-@code{nil} means, include file boundaries in @file{*toc*} buffer. |
| 3845 | This flag can be toggled from within the @file{*toc*} buffer with the |
| 3846 | @kbd{i} key. |
| 3847 | @end defopt |
| 3848 | |
| 3849 | @defopt reftex-toc-include-labels |
| 3850 | Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag |
| 3851 | can be toggled from within the @file{*toc*} buffer with the @kbd{l} |
| 3852 | key. |
| 3853 | @end defopt |
| 3854 | |
| 3855 | @defopt reftex-toc-include-index-entries |
| 3856 | Non-@code{nil} means, include index entries in @file{*toc*} buffer. |
| 3857 | This flag can be toggled from within the @file{*toc*} buffer with the |
| 3858 | @kbd{i} key. |
| 3859 | @end defopt |
| 3860 | |
| 3861 | @defopt reftex-toc-include-context |
| 3862 | Non-@code{nil} means, include context with labels in the @file{*toc*} |
| 3863 | buffer. Context will only be shown if the labels are visible as well. |
| 3864 | This flag can be toggled from within the @file{*toc*} buffer with the |
| 3865 | @kbd{c} key. |
| 3866 | @end defopt |
| 3867 | |
| 3868 | @defopt reftex-toc-follow-mode |
| 3869 | Non-@code{nil} means, point in @file{*toc*} buffer (the |
| 3870 | table-of-contents buffer) will cause other window to follow. The other |
| 3871 | window will show the corresponding part of the document. This flag can |
| 3872 | be toggled from within the @file{*toc*} buffer with the @kbd{f} |
| 3873 | key. |
| 3874 | @end defopt |
| 3875 | |
| 3876 | @deffn {Normal Hook} reftex-toc-mode-hook |
| 3877 | Normal hook which is run when a @file{*toc*} buffer is |
| 3878 | created. |
| 3879 | @end deffn |
| 3880 | |
| 3881 | @deffn Keymap reftex-toc-map |
| 3882 | The keymap which is active in the @file{*toc*} buffer. |
| 3883 | (@pxref{Table of Contents}). |
| 3884 | @end deffn |
| 3885 | |
| 3886 | @node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options |
| 3887 | @section Defining Label Environments |
| 3888 | @cindex Options, defining label environments |
| 3889 | @cindex Defining label environments, options |
| 3890 | |
| 3891 | @defopt reftex-default-label-alist-entries |
| 3892 | Default label alist specifications. It is a list of symbols with |
| 3893 | associations in the constant @code{reftex-label-alist-builtin}. |
| 3894 | @code{LaTeX} should always be the last entry. |
| 3895 | @end defopt |
| 3896 | |
| 3897 | @defopt reftex-label-alist |
| 3898 | Set this variable to define additions and changes to the defaults in |
| 3899 | @code{reftex-default-label-alist-entries}. The only things you |
| 3900 | @emph{must not} change is that @code{?s} is the type indicator for |
| 3901 | section labels, and @key{SPC} for the @code{any} label type. These are |
| 3902 | hard-coded at other places in the code. |
| 3903 | |
| 3904 | The value of the variable must be a list of items. Each item is a list |
| 3905 | itself and has the following structure: |
| 3906 | |
| 3907 | @example |
| 3908 | (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format} |
| 3909 | @var{context-method} (@var{magic-word} ... ) @var{toc-level}) |
| 3910 | @end example |
| 3911 | |
| 3912 | Each list entry describes either an environment carrying a counter for |
| 3913 | use with @code{\label} and @code{\ref}, or a LaTeX macro defining a |
| 3914 | label as (or inside) one of its arguments. The elements of each list |
| 3915 | entry are: |
| 3916 | |
| 3917 | @table @asis |
| 3918 | @item @var{env-or-macro} |
| 3919 | Name of the environment (like @samp{table}) or macro (like |
| 3920 | @samp{\myfig}). For macros, indicate the arguments, as in |
| 3921 | @samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional |
| 3922 | arguments, a star to mark the label argument, if any. The macro does |
| 3923 | not have to have a label argument - you could also use |
| 3924 | @samp{\label@{...@}} inside one of its arguments. |
| 3925 | |
| 3926 | Special names: @code{section} for section labels, @code{any} to define a |
| 3927 | group which contains all labels. |
| 3928 | |
| 3929 | This may also be a function to do local parsing and identify point to be |
| 3930 | in a non-standard label environment. The function must take an |
| 3931 | argument @var{bound} and limit backward searches to this value. It |
| 3932 | should return either nil or a cons cell @code{(@var{function} |
| 3933 | . @var{position})} with the function symbol and the position where the |
| 3934 | special environment starts. See the Info documentation for an |
| 3935 | example. |
| 3936 | |
| 3937 | Finally this may also be @code{nil} if the entry is only meant to change |
| 3938 | some settings associated with the type indicator character (see |
| 3939 | below). |
| 3940 | |
| 3941 | @item @var{type-key} |
| 3942 | Type indicator character, like @code{?t}, must be a printable ASCII |
| 3943 | character. The type indicator is a single character which defines a |
| 3944 | label type. Any label inside the environment or macro is assumed to |
| 3945 | belong to this type. The same character may occur several times in this |
| 3946 | list, to cover cases in which different environments carry the same |
| 3947 | label type (like @code{equation} and @code{eqnarray}). If the type |
| 3948 | indicator is @code{nil} and the macro has a label argument @samp{@{*@}}, |
| 3949 | the macro defines neutral labels just like @code{\label}. In this case |
| 3950 | the reminder of this entry is ignored. |
| 3951 | |
| 3952 | @item @var{label-prefix} |
| 3953 | Label prefix string, like @samp{tab:}. The prefix is a short string |
| 3954 | used as the start of a label. It may be the empty string. The prefix |
| 3955 | may contain the following @samp{%} escapes: |
| 3956 | |
| 3957 | @example |
| 3958 | %f Current file name, directory and extension stripped. |
| 3959 | %F Current file name relative to master file directory. |
| 3960 | %m Master file name, directory and extension stripped. |
| 3961 | %M Directory name (without path) where master file is located. |
| 3962 | %u User login name, on systems which support this. |
| 3963 | %S A section prefix derived with variable @code{reftex-section-prefixes}. |
| 3964 | @end example |
| 3965 | |
| 3966 | @noindent |
| 3967 | Example: In a file @file{intro.tex}, @samp{eq:%f:} will become |
| 3968 | @samp{eq:intro:}. |
| 3969 | |
| 3970 | @item @var{reference-format} |
| 3971 | Format string for reference insert in buffer. @samp{%s} will be |
| 3972 | replaced by the label. When the format starts with @samp{~}, this |
| 3973 | @samp{~} will only be inserted when the character before point is |
| 3974 | @emph{not} a whitespace. |
| 3975 | |
| 3976 | @item @var{context-method} |
| 3977 | Indication on how to find the short context. |
| 3978 | @itemize @minus |
| 3979 | @item |
| 3980 | If @code{nil}, use the text following the @samp{\label@{...@}} macro. |
| 3981 | @item |
| 3982 | If @code{t}, use |
| 3983 | @itemize @minus |
| 3984 | @item |
| 3985 | the section heading for section labels. |
| 3986 | @item |
| 3987 | text following the @samp{\begin@{...@}} statement of environments (not |
| 3988 | a good choice for environments like eqnarray or enumerate, where one has |
| 3989 | several labels in a single environment). |
| 3990 | @item |
| 3991 | text after the macro name (starting with the first arg) for |
| 3992 | macros. |
| 3993 | @end itemize |
| 3994 | @item |
| 3995 | If an integer, use the nth argument of the macro. As a special case, |
| 3996 | 1000 means to get text after the last macro argument. |
| 3997 | @item |
| 3998 | If a string, use as regexp to search @emph{backward} from the label. |
| 3999 | Context is then the text following the end of the match. E.g. putting |
| 4000 | this to @samp{\\caption[[@{]} will use the caption in a figure or table |
| 4001 | environment. @samp{\\begin@{eqnarray@}\|\\\\} works for |
| 4002 | eqnarrays. |
| 4003 | @item |
| 4004 | If any of @code{caption}, @code{item}, @code{eqnarray-like}, |
| 4005 | @code{alignat-like}, this symbol will internally be translated into an |
| 4006 | appropriate regexp (see also the variable |
| 4007 | @code{reftex-default-context-regexps}). |
| 4008 | @item |
| 4009 | If a function, call this function with the name of the environment/macro |
| 4010 | as argument. On call, point will be just after the @code{\label} macro. |
| 4011 | The function is expected to return a suitable context string. It should |
| 4012 | throw an exception (error) when failing to find context. As an example, |
| 4013 | here is a function returning the 10 chars following the label macro as |
| 4014 | context: |
| 4015 | |
| 4016 | @example |
| 4017 | (defun my-context-function (env-or-mac) |
| 4018 | (if (> (point-max) (+ 10 (point))) |
| 4019 | (buffer-substring (point) (+ 10 (point))) |
| 4020 | (error "Buffer too small"))) |
| 4021 | @end example |
| 4022 | @end itemize |
| 4023 | |
| 4024 | Label context is used in two ways by @b{Ref@TeX{}}: For display in the label |
| 4025 | menu, and to derive a label string. If you want to use a different |
| 4026 | method for each of these, specify them as a dotted pair. |
| 4027 | E.g. @code{(nil . t)} uses the text after the label (@code{nil}) for |
| 4028 | display, and text from the default position (@code{t}) to derive a label |
| 4029 | string. This is actually used for section labels. |
| 4030 | |
| 4031 | @item @var{magic-word-list} |
| 4032 | List of magic words which identify a reference to be of this type. If |
| 4033 | the word before point is equal to one of these words when calling |
| 4034 | @code{reftex-reference}, the label list offered will be automatically |
| 4035 | restricted to labels of the correct type. If the first element of this |
| 4036 | word--list is the symbol `regexp', the strings are interpreted as regular |
| 4037 | expressions. |
| 4038 | |
| 4039 | @item @var{toc-level} |
| 4040 | The integer level at which this environment should be added to the table |
| 4041 | of contents. See also @code{reftex-section-levels}. A positive value |
| 4042 | will number the entries mixed with the sectioning commands of the same |
| 4043 | level. A negative value will make unnumbered entries. Useful only for |
| 4044 | theorem-like environments which structure the document. Will be ignored |
| 4045 | for macros. When omitted or @code{nil}, no TOC entries will be |
| 4046 | made. |
| 4047 | @end table |
| 4048 | |
| 4049 | If the type indicator characters of two or more entries are the same, |
| 4050 | @b{Ref@TeX{}} will use |
| 4051 | @itemize @minus |
| 4052 | @item |
| 4053 | the first non-@code{nil} format and prefix |
| 4054 | @item |
| 4055 | the magic words of all involved entries. |
| 4056 | @end itemize |
| 4057 | |
| 4058 | Any list entry may also be a symbol. If that has an association in |
| 4059 | @code{reftex-label-alist-builtin}, the @code{cddr} of that association is |
| 4060 | spliced into the list. However, builtin defaults should normally be set |
| 4061 | with the variable @code{reftex-default-label-alist-entries}. |
| 4062 | @end defopt |
| 4063 | |
| 4064 | @defopt reftex-section-prefixes |
| 4065 | Prefixes for section labels. When the label prefix given in an entry in |
| 4066 | @code{reftex-label-alist} contains @samp{%S}, this list is used to |
| 4067 | determine the correct prefix string depending on the current section |
| 4068 | level. The list is an alist, with each entry of the form |
| 4069 | @w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro |
| 4070 | names like @samp{chapter}, integer section levels (as given in |
| 4071 | @code{reftex-section-levels}), and @code{t} for the default. |
| 4072 | @end defopt |
| 4073 | |
| 4074 | @defopt reftex-default-context-regexps |
| 4075 | Alist with default regular expressions for finding context. The emacs |
| 4076 | lisp form @w{@code{(format regexp (regexp-quote environment))}} is used |
| 4077 | to calculate the final regular expression - so @samp{%s} will be |
| 4078 | replaced with the environment or macro. |
| 4079 | @end defopt |
| 4080 | |
| 4081 | @defopt reftex-trust-label-prefix |
| 4082 | Non-@code{nil} means, trust the label prefix when determining label type. |
| 4083 | It is customary to use special label prefixes to distinguish different label |
| 4084 | types. The label prefixes have no syntactic meaning in LaTeX (unless |
| 4085 | special packages like fancyref) are being used. RefTeX can and by |
| 4086 | default does parse around each label to detect the correct label type, |
| 4087 | but this process can be slow when a document contains thousands of |
| 4088 | labels. If you use label prefixes consistently, you may speed up |
| 4089 | document parsing by setting this variable to a non-nil value. RefTeX |
| 4090 | will then compare the label prefix with the prefixes found in |
| 4091 | `reftex-label-alist' and derive the correct label type in this way. |
| 4092 | Possible values for this option are: |
| 4093 | |
| 4094 | @example |
| 4095 | t @r{This means to trust any label prefixes found.} |
| 4096 | regexp @r{If a regexp, only prefixes matched by the regexp are trusted.} |
| 4097 | list @r{List of accepted prefixes, as strings. The colon is part of} |
| 4098 | @r{the prefix, e.g. ("fn:" "eqn:" "item:").} |
| 4099 | nil @r{Never trust a label prefix.} |
| 4100 | @end example |
| 4101 | The only disadvantage of using this feature is that the label context |
| 4102 | displayed in the label selection buffer along with each label is |
| 4103 | simply some text after the label definition. This is no problem if you |
| 4104 | place labels keeping this in mind (e.g. @i{before} the equation, @i{at |
| 4105 | the beginning} of a fig/tab caption ...). Anyway, it is probably best |
| 4106 | to use the regexp or the list value types to fine-tune this feature. |
| 4107 | For example, if your document contains thousands of footnotes with |
| 4108 | labels fn:xxx, you may want to set this variable to the value "^fn:$" or |
| 4109 | ("fn:"). Then RefTeX will still do extensive parsing for any |
| 4110 | non-footnote labels. |
| 4111 | @end defopt |
| 4112 | |
| 4113 | @node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options |
| 4114 | @section Creating Labels |
| 4115 | @cindex Options, creating labels |
| 4116 | @cindex Creating labels, options |
| 4117 | |
| 4118 | @defopt reftex-insert-label-flags |
| 4119 | Flags governing label insertion. The value has the form |
| 4120 | |
| 4121 | @example |
| 4122 | (@var{derive} @var{prompt}) |
| 4123 | @end example |
| 4124 | |
| 4125 | If @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensible |
| 4126 | label from context. A section label for example will be derived from |
| 4127 | the section heading. The conversion of the context to a valid label is |
| 4128 | governed by the specifications given in |
| 4129 | @code{reftex-derive-label-parameters}. If @var{derive} is @code{nil}, |
| 4130 | the default label will consist of the prefix and a unique number, like |
| 4131 | @samp{eq:23}. |
| 4132 | |
| 4133 | If @var{prompt} is @code{t}, the user will be prompted for a label |
| 4134 | string. When @var{prompt} is @code{nil}, the default label will be |
| 4135 | inserted without query. |
| 4136 | |
| 4137 | So the combination of @var{derive} and @var{prompt} controls label |
| 4138 | insertion. Here is a table describing all four possibilities: |
| 4139 | |
| 4140 | @example |
| 4141 | @group |
| 4142 | @var{derive} @var{prompt} @var{action} |
| 4143 | ----------------------------------------------------------- |
| 4144 | nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.} |
| 4145 | nil t @r{Prompt for label.} |
| 4146 | t nil @r{Derive a label from context and insert. No query.} |
| 4147 | t t @r{Derive a label from context, prompt for confirmation.} |
| 4148 | @end group |
| 4149 | @end example |
| 4150 | |
| 4151 | Each flag may be set to @code{t}, @code{nil}, or a string of label type |
| 4152 | letters indicating the label types for which it should be true. Thus, |
| 4153 | the combination may be set differently for each label type. The default |
| 4154 | settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from |
| 4155 | headings (with confirmation). Prompt for figure and table labels. Use |
| 4156 | simple labels without confirmation for everything else. |
| 4157 | |
| 4158 | The available label types are: @code{s} (section), @code{f} (figure), |
| 4159 | @code{t} (table), @code{i} (item), @code{e} (equation), @code{n} |
| 4160 | (footnote), @code{N} (endnote) plus any definitions in |
| 4161 | @code{reftex-label-alist}. |
| 4162 | @end defopt |
| 4163 | |
| 4164 | @deffn Hook reftex-format-label-function |
| 4165 | If non-@code{nil}, should be a function which produces the string to |
| 4166 | insert as a label definition. The function will be called with two |
| 4167 | arguments, the @var{label} and the @var{default-format} (usually |
| 4168 | @samp{\label@{%s@}}). It should return the string to insert into the |
| 4169 | buffer. |
| 4170 | @end deffn |
| 4171 | |
| 4172 | @deffn Hook reftex-string-to-label-function |
| 4173 | Function to turn an arbitrary string into a valid label. |
| 4174 | @b{Ref@TeX{}}'s default function uses the variable |
| 4175 | @code{reftex-derive-label-parameters}. |
| 4176 | @end deffn |
| 4177 | |
| 4178 | @deffn Hook reftex-translate-to-ascii-function |
| 4179 | Filter function which will process a context string before it is used to |
| 4180 | derive a label from it. The intended application is to convert ISO or |
| 4181 | Mule characters into something valid in labels. The default function |
| 4182 | @code{reftex-latin1-to-ascii} removes the accents from Latin-1 |
| 4183 | characters. X-Symbol (>=2.6) sets this variable to the much more |
| 4184 | general @code{x-symbol-translate-to-ascii}. |
| 4185 | @end deffn |
| 4186 | |
| 4187 | @defopt reftex-derive-label-parameters |
| 4188 | Parameters for converting a string into a label. This variable is a |
| 4189 | list of the following items: |
| 4190 | @table @asis |
| 4191 | @item @var{nwords} |
| 4192 | Number of words to use. |
| 4193 | @item @var{maxchar} |
| 4194 | Maximum number of characters in a label string. |
| 4195 | @item @var{invalid} |
| 4196 | @code{nil}: Throw away any words containing characters invalid in labels.@* |
| 4197 | @code{t}: Throw away only the invalid characters, not the whole word. |
| 4198 | @item @var{abbrev} |
| 4199 | @code{nil}: Never abbreviate words.@* |
| 4200 | @code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@* |
| 4201 | @code{1}: Abbreviate words if necessary to shorten label string. |
| 4202 | @item @var{separator} |
| 4203 | String separating different words in the label. |
| 4204 | @item @var{ignorewords} |
| 4205 | List of words which should not be part of labels. |
| 4206 | @item @var{downcase} |
| 4207 | @code{t}: Downcase words before putting them into the label.@* |
| 4208 | @end table |
| 4209 | @end defopt |
| 4210 | |
| 4211 | @defopt reftex-label-illegal-re |
| 4212 | Regexp matching characters not valid in labels. |
| 4213 | @end defopt |
| 4214 | |
| 4215 | @defopt reftex-abbrev-parameters |
| 4216 | Parameters for abbreviation of words. A list of four parameters. |
| 4217 | @table @asis |
| 4218 | @item @var{min-chars} |
| 4219 | Minimum number of characters remaining after abbreviation. |
| 4220 | @item @var{min-kill} |
| 4221 | Minimum number of characters to remove when abbreviating words. |
| 4222 | @item @var{before} |
| 4223 | Character class before abbrev point in word. |
| 4224 | @item @var{after} |
| 4225 | Character class after abbrev point in word. |
| 4226 | @end table |
| 4227 | @end defopt |
| 4228 | |
| 4229 | @node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options |
| 4230 | @section Referencing Labels |
| 4231 | @cindex Options, referencing labels |
| 4232 | @cindex Referencing labels, options |
| 4233 | |
| 4234 | @defopt reftex-label-menu-flags |
| 4235 | List of flags governing the label menu makeup. The flags are: |
| 4236 | @table @asis |
| 4237 | @item @var{table-of-contents} |
| 4238 | Show the labels embedded in a table of context. |
| 4239 | @item @var{section-numbers} |
| 4240 | Include section numbers (like 4.1.3) in table of contents. |
| 4241 | @item @var{counters} |
| 4242 | Show counters. This just numbers the labels in the menu. |
| 4243 | @item @var{no-context} |
| 4244 | Non-@code{nil} means do @emph{not} show the short context. |
| 4245 | @item @var{follow} |
| 4246 | Follow full context in other window. |
| 4247 | @item @var{show-commented} |
| 4248 | Show labels from regions which are commented out. |
| 4249 | @item @var{match-everywhere} |
| 4250 | Obsolete flag. |
| 4251 | @item @var{show-files} |
| 4252 | Show begin and end of included files. |
| 4253 | @end table |
| 4254 | |
| 4255 | Each of these flags can be set to @code{t} or @code{nil}, or to a string |
| 4256 | of type letters indicating the label types for which it should be true. |
| 4257 | These strings work like character classes in regular expressions. Thus, |
| 4258 | setting one of the flags to @samp{"sf"} makes the flag true for section |
| 4259 | and figure labels, @code{nil} for everything else. Setting it to |
| 4260 | @samp{"^sf"} makes it the other way round. |
| 4261 | |
| 4262 | The available label types are: @code{s} (section), @code{f} (figure), |
| 4263 | @code{t} (table), @code{i} (item), @code{e} (equation), @code{n} |
| 4264 | (footnote), plus any definitions in @code{reftex-label-alist}. |
| 4265 | |
| 4266 | Most options can also be switched from the label menu itself - so if you |
| 4267 | decide here to not have a table of contents in the label menu, you can |
| 4268 | still get one interactively during selection from the label menu. |
| 4269 | @end defopt |
| 4270 | |
| 4271 | @defopt reftex-multiref-punctuation |
| 4272 | Punctuation strings for multiple references. When marking is used in |
| 4273 | the selection buffer to select several references, this variable |
| 4274 | associates the 3 marking characters @samp{,-+} with prefix strings to be |
| 4275 | inserted into the buffer before the corresponding @code{\ref} macro. |
| 4276 | This is used to string together whole reference sets, like |
| 4277 | @samp{eqs. 1,2,3-5,6 and 7} in a single call to |
| 4278 | @code{reftex-reference}. |
| 4279 | @end defopt |
| 4280 | |
| 4281 | @defopt reftex-vref-is-default |
| 4282 | Non-@code{nil} means, the varioref macro @code{\vref} is used as |
| 4283 | default. In the selection buffer, the @kbd{v} key toggles the reference |
| 4284 | macro between @code{\ref} and @code{\vref}. The value of this variable |
| 4285 | determines the default which is active when entering the selection |
| 4286 | process. Instead of @code{nil} or @code{t}, this may also be a string |
| 4287 | of type letters indicating the label types for which it should be |
| 4288 | true. |
| 4289 | @end defopt |
| 4290 | |
| 4291 | @defopt reftex-fref-is-default |
| 4292 | Non-@code{nil} means, the fancyref macro @code{\fref} is used as |
| 4293 | default. In the selection buffer, the @kbd{V} key toggles the reference |
| 4294 | macro between @code{\ref}, @code{\fref} and @code{\Fref}. The value of |
| 4295 | this variable determines the default which is active when entering the |
| 4296 | selection process. Instead of @code{nil} or @code{t}, this may also be |
| 4297 | a string of type letters indicating the label types for which it should |
| 4298 | be true. |
| 4299 | @end defopt |
| 4300 | |
| 4301 | @deffn Hook reftex-format-ref-function |
| 4302 | If non-@code{nil}, should be a function which produces the string to |
| 4303 | insert as a reference. Note that the insertion format can also be |
| 4304 | changed with @code{reftex-label-alist}. This hook also is used by the |
| 4305 | special commands to insert @code{\vref} and @code{\fref} references, so |
| 4306 | even if you set this, your setting will be ignored by the special |
| 4307 | commands. The function will be called with two arguments, the |
| 4308 | @var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}). |
| 4309 | It should return the string to insert into the buffer. |
| 4310 | @end deffn |
| 4311 | |
| 4312 | @defopt reftex-level-indent |
| 4313 | Number of spaces to be used for indentation per section level. |
| 4314 | @end defopt |
| 4315 | |
| 4316 | @defopt reftex-guess-label-type |
| 4317 | Non-@code{nil} means, @code{reftex-reference} will try to guess the |
| 4318 | label type. To do that, @b{Ref@TeX{}} will look at the word before the |
| 4319 | cursor and compare it with the magic words given in |
| 4320 | @code{reftex-label-alist}. When it finds a match, @b{Ref@TeX{}} will |
| 4321 | immediately offer the correct label menu - otherwise it will prompt you |
| 4322 | for a label type. If you set this variable to @code{nil}, @b{Ref@TeX{}} |
| 4323 | will always prompt for a label type. |
| 4324 | @end defopt |
| 4325 | |
| 4326 | @deffn {Normal Hook} reftex-display-copied-context-hook |
| 4327 | Normal Hook which is run before context is displayed anywhere. Designed |
| 4328 | for @w{@code{X-Symbol}}, but may have other uses as well. |
| 4329 | @end deffn |
| 4330 | |
| 4331 | @deffn Hook reftex-pre-refontification-functions |
| 4332 | @code{X-Symbol} specific hook. Probably not useful for other purposes. |
| 4333 | The functions get two arguments, the buffer from where the command |
| 4334 | started and a symbol indicating in what context the hook is |
| 4335 | called. |
| 4336 | @end deffn |
| 4337 | |
| 4338 | @deffn {Normal Hook} reftex-select-label-mode-hook |
| 4339 | Normal hook which is run when a selection buffer enters |
| 4340 | @code{reftex-select-label-mode}. |
| 4341 | @end deffn |
| 4342 | |
| 4343 | @deffn Keymap reftex-select-label-map |
| 4344 | The keymap which is active in the labels selection process |
| 4345 | (@pxref{Referencing Labels}). |
| 4346 | @end deffn |
| 4347 | |
| 4348 | @node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options |
| 4349 | @section Creating Citations |
| 4350 | @cindex Options, creating citations |
| 4351 | @cindex Creating citations, options |
| 4352 | |
| 4353 | @defopt reftex-bibliography-commands |
| 4354 | LaTeX commands which specify the BibTeX databases to use with the document. |
| 4355 | @end defopt |
| 4356 | |
| 4357 | @defopt reftex-bibfile-ignore-regexps |
| 4358 | List of regular expressions to exclude files in |
| 4359 | @code{\\bibliography@{..@}}. File names matched by any of these regexps |
| 4360 | will not be parsed. Intended for files which contain only |
| 4361 | @code{@@string} macro definitions and the like, which are ignored by |
| 4362 | @b{Ref@TeX{}} anyway. |
| 4363 | @end defopt |
| 4364 | |
| 4365 | @defopt reftex-default-bibliography |
| 4366 | List of BibTeX database files which should be used if none are specified. |
| 4367 | When @code{reftex-citation} is called from a document with neither |
| 4368 | a @samp{\bibliography@{...@}} statement nor a @code{thebibliography} |
| 4369 | environment, @b{Ref@TeX{}} will scan these files instead. Intended for |
| 4370 | using @code{reftex-citation} in non-LaTeX files. The files will be |
| 4371 | searched along the BIBINPUTS or TEXBIB path. |
| 4372 | @end defopt |
| 4373 | |
| 4374 | @defopt reftex-sort-bibtex-matches |
| 4375 | Sorting of the entries found in BibTeX databases by reftex-citation. |
| 4376 | Possible values: |
| 4377 | @example |
| 4378 | nil @r{Do not sort entries.} |
| 4379 | author @r{Sort entries by author name.} |
| 4380 | year @r{Sort entries by increasing year.} |
| 4381 | reverse-year @r{Sort entries by decreasing year.} |
| 4382 | @end example |
| 4383 | @end defopt |
| 4384 | |
| 4385 | @defopt reftex-cite-format |
| 4386 | The format of citations to be inserted into the buffer. It can be a |
| 4387 | string, an alist or a symbol. In the simplest case this is just the string |
| 4388 | @samp{\cite@{%l@}}, which is also the default. See the definition of |
| 4389 | @code{reftex-cite-format-builtin} for more complex examples. |
| 4390 | |
| 4391 | If @code{reftex-cite-format} is a string, it will be used as the format. |
| 4392 | In the format, the following percent escapes will be expanded. |
| 4393 | |
| 4394 | @table @code |
| 4395 | @item %l |
| 4396 | The BibTeX label of the citation. |
| 4397 | @item %a |
| 4398 | List of author names, see also @code{reftex-cite-punctuation}. |
| 4399 | @item %2a |
| 4400 | Like %a, but abbreviate more than 2 authors like Jones et al. |
| 4401 | @item %A |
| 4402 | First author name only. |
| 4403 | @item %e |
| 4404 | Works like @samp{%a}, but on list of editor names. (@samp{%2e} and |
| 4405 | @samp{%E} work a well). |
| 4406 | @end table |
| 4407 | |
| 4408 | It is also possible to access all other BibTeX database fields: |
| 4409 | |
| 4410 | @example |
| 4411 | %b booktitle %c chapter %d edition %h howpublished |
| 4412 | %i institution %j journal %k key %m month |
| 4413 | %n number %o organization %p pages %P first page |
| 4414 | %r address %s school %u publisher %t title |
| 4415 | %v volume %y year |
| 4416 | %B booktitle, abbreviated %T title, abbreviated |
| 4417 | @end example |
| 4418 | |
| 4419 | @noindent |
| 4420 | Usually, only @samp{%l} is needed. The other stuff is mainly for the |
| 4421 | echo area display, and for @code{(setq reftex-comment-citations t)}. |
| 4422 | |
| 4423 | @samp{%<} as a special operator kills punctuation and space around it |
| 4424 | after the string has been formatted. |
| 4425 | |
| 4426 | A pair of square brackets indicates an optional argument, and RefTeX |
| 4427 | will prompt for the values of these arguments. |
| 4428 | |
| 4429 | Beware that all this only works with BibTeX database files. When |
| 4430 | citations are made from the @code{\bibitems} in an explicit |
| 4431 | @code{thebibliography} environment, only @samp{%l} is available. |
| 4432 | |
| 4433 | If @code{reftex-cite-format} is an alist of characters and strings, the |
| 4434 | user will be prompted for a character to select one of the possible |
| 4435 | format strings. |
| 4436 | |
| 4437 | In order to configure this variable, you can either set |
| 4438 | @code{reftex-cite-format} directly yourself or set it to the |
| 4439 | @emph{symbol} of one of the predefined styles. The predefined symbols |
| 4440 | are those which have an association in the constant |
| 4441 | @code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format |
| 4442 | 'natbib)}. |
| 4443 | @end defopt |
| 4444 | |
| 4445 | @deffn Hook reftex-format-cite-function |
| 4446 | If non-@code{nil}, should be a function which produces the string to |
| 4447 | insert as a citation. Note that the citation format can also be changed |
| 4448 | with the variable @code{reftex-cite-format}. The function will be |
| 4449 | called with two arguments, the @var{citation-key} and the |
| 4450 | @var{default-format} (taken from @code{reftex-cite-format}). It should |
| 4451 | return the string to insert into the buffer. |
| 4452 | @end deffn |
| 4453 | |
| 4454 | @defopt reftex-cite-prompt-optional-args |
| 4455 | Non-@code{nil} means, prompt for empty optional arguments in cite macros. |
| 4456 | When an entry in @code{reftex-cite-format} ist given with square brackets to |
| 4457 | indicate optional arguments (for example @samp{\\cite[][]@{%l@}}), RefTeX can |
| 4458 | prompt for values. Possible values are: |
| 4459 | @example |
| 4460 | nil @r{Never prompt for optional arguments} |
| 4461 | t @r{Always prompt} |
| 4462 | maybe @r{Prompt only if @code{reftex-citation} was called with C-u prefix arg}@end example |
| 4463 | Unnecessary empty optional arguments are removed before insertion into |
| 4464 | the buffer. See @code{reftex-cite-cleanup-optional-args}. |
| 4465 | @end defopt |
| 4466 | |
| 4467 | @defopt reftex-cite-cleanup-optional-args |
| 4468 | Non-@code{nil} means, remove empty optional arguments from cite macros |
| 4469 | if possible. |
| 4470 | @end defopt |
| 4471 | |
| 4472 | @defopt reftex-comment-citations |
| 4473 | Non-@code{nil} means add a comment for each citation describing the full |
| 4474 | entry. The comment is formatted according to |
| 4475 | @code{reftex-cite-comment-format}. |
| 4476 | @end defopt |
| 4477 | |
| 4478 | @defopt reftex-cite-comment-format |
| 4479 | Citation format used for commented citations. Must @emph{not} contain |
| 4480 | @samp{%l}. See the variable @code{reftex-cite-format} for possible |
| 4481 | percent escapes. |
| 4482 | @end defopt |
| 4483 | |
| 4484 | @defopt reftex-cite-punctuation |
| 4485 | Punctuation for formatting of name lists in citations. This is a list |
| 4486 | of 3 strings. |
| 4487 | @enumerate |
| 4488 | @item |
| 4489 | normal names separator, like @samp{, } in Jones, Brown and Miller |
| 4490 | @item |
| 4491 | final names separator, like @samp{ and } in Jones, Brown and Miller |
| 4492 | @item |
| 4493 | The @samp{et al.} string, like @samp{ @{\it et al.@}} in |
| 4494 | Jones @{\it et al.@} |
| 4495 | @end enumerate |
| 4496 | @end defopt |
| 4497 | |
| 4498 | @deffn {Normal Hook} reftex-select-bib-mode-hook |
| 4499 | Normal hook which is run when a selection buffer enters |
| 4500 | @code{reftex-select-bib-mode}. |
| 4501 | @end deffn |
| 4502 | |
| 4503 | @deffn Keymap reftex-select-bib-map |
| 4504 | The keymap which is active in the citation-key selection process |
| 4505 | (@pxref{Creating Citations}). |
| 4506 | @end deffn |
| 4507 | |
| 4508 | @node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations), Options |
| 4509 | @section Index Support |
| 4510 | @cindex Options, Index support |
| 4511 | @cindex Index support, options |
| 4512 | |
| 4513 | @defopt reftex-support-index |
| 4514 | Non-@code{nil} means, index entries are parsed as well. Index support |
| 4515 | is resource intensive and the internal structure holding the parsed |
| 4516 | information can become quite big. Therefore it can be turned off. When |
| 4517 | this is @code{nil} and you execute a command which requires index |
| 4518 | support, you will be asked for confirmation to turn it on and rescan the |
| 4519 | document. |
| 4520 | @end defopt |
| 4521 | |
| 4522 | @defopt reftex-index-special-chars |
| 4523 | List of special characters in index entries, given as strings. These |
| 4524 | correspond to the @code{MakeIndex} keywords |
| 4525 | @code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}. |
| 4526 | @end defopt |
| 4527 | |
| 4528 | @defopt reftex-index-macros |
| 4529 | List of macros which define index entries. The structure of each entry |
| 4530 | is |
| 4531 | @lisp |
| 4532 | (@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude} @var{repeat}) |
| 4533 | @end lisp |
| 4534 | |
| 4535 | @var{macro} is the macro. Arguments should be denoted by empty braces, |
| 4536 | as for example in @samp{\index[]@{*@}}. Use square brackets to denote |
| 4537 | optional arguments. The star marks where the index key is. |
| 4538 | |
| 4539 | @var{index-tag} is a short name of the index. @samp{idx} and @samp{glo} |
| 4540 | are reserved for the default index and the glossary. Other indices can |
| 4541 | be defined as well. If this is an integer, the Nth argument of the |
| 4542 | macro holds the index tag. |
| 4543 | |
| 4544 | @var{key} is a character which is used to identify the macro for input |
| 4545 | with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are |
| 4546 | reserved for default index and glossary. |
| 4547 | |
| 4548 | @var{prefix} can be a prefix which is added to the @var{key} part of the |
| 4549 | index entry. If you have a macro |
| 4550 | @code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix |
| 4551 | should be @samp{Molecules!}. |
| 4552 | |
| 4553 | @var{exclude} can be a function. If this function exists and returns a |
| 4554 | non-@code{nil} value, the index entry at point is ignored. This was |
| 4555 | implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts |
| 4556 | in the LaTeX2e @code{index} package. |
| 4557 | |
| 4558 | @var{repeat}, if non-@code{nil}, means the index macro does not typeset |
| 4559 | the entry in the text, so that the text has to be repeated outside the |
| 4560 | index macro. Needed for @code{reftex-index-selection-or-word} and for |
| 4561 | indexing from the phrase buffer. |
| 4562 | |
| 4563 | The final entry may also be a symbol. It must have an association in |
| 4564 | the variable @code{reftex-index-macros-builtin} to specify the main |
| 4565 | indexing package you are using. Valid values are currently |
| 4566 | @example |
| 4567 | default @r{The LaTeX default - unnecessary to specify this one} |
| 4568 | multind @r{The multind.sty package} |
| 4569 | index @r{The index.sty package} |
| 4570 | index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.} |
| 4571 | @r{Should not be used - only for old documents} |
| 4572 | @end example |
| 4573 | Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well, |
| 4574 | so with a sufficiently new version of AUCTeX, you should not set the |
| 4575 | package here. |
| 4576 | @end defopt |
| 4577 | |
| 4578 | @defopt reftex-index-default-macro |
| 4579 | The default index macro for @code{reftex-index-selection-or-word}. |
| 4580 | This is a list with @code{(@var{macro-key} @var{default-tag})}. |
| 4581 | |
| 4582 | @var{macro-key} is a character identifying an index macro - see |
| 4583 | @code{reftex-index-macros}. |
| 4584 | |
| 4585 | @var{default-tag} is the tag to be used if the macro requires a |
| 4586 | @var{tag} argument. When this is @code{nil} and a @var{tag} is needed, |
| 4587 | @b{Ref@TeX{}} will ask for it. When this is the empty string and the |
| 4588 | TAG argument of the index macro is optional, the TAG argument will be |
| 4589 | omitted. |
| 4590 | @end defopt |
| 4591 | |
| 4592 | @defopt reftex-index-default-tag |
| 4593 | Default index tag. When working with multiple indexes, RefTeX queries |
| 4594 | for an index tag when creating index entries or displaying a specific |
| 4595 | index. This variable controls the default offered for these queries. |
| 4596 | The default can be selected with @key{RET} during selection or |
| 4597 | completion. Valid values of this variable are: |
| 4598 | @example |
| 4599 | nil @r{Do not provide a default index} |
| 4600 | "tag" @r{The default index tag given as a string, e.g. "idx"} |
| 4601 | last @r{The last used index tag will be offered as default} |
| 4602 | @end example |
| 4603 | @end defopt |
| 4604 | |
| 4605 | @defopt reftex-index-math-format |
| 4606 | Format of index entries when copied from inside math mode. When |
| 4607 | @code{reftex-index-selection-or-word} is executed inside TeX math mode, |
| 4608 | the index key copied from the buffer is processed with this format |
| 4609 | string through the @code{format} function. This can be used to add the |
| 4610 | math delimiters (e.g. @samp{$}) to the string. Requires the |
| 4611 | @file{texmathp.el} library which is part of AUCTeX. |
| 4612 | @end defopt |
| 4613 | |
| 4614 | @defopt reftex-index-phrase-file-extension |
| 4615 | File extension for the index phrase file. This extension will be added |
| 4616 | to the base name of the master file. |
| 4617 | @end defopt |
| 4618 | |
| 4619 | @defopt reftex-index-phrases-logical-and-regexp |
| 4620 | Regexp matching the @samp{and} operator for index arguments in phrases |
| 4621 | file. When several index arguments in a phrase line are separated by |
| 4622 | this operator, each part will generate an index macro. So each match of |
| 4623 | the search phrase will produce @emph{several} different index entries. |
| 4624 | Make sure this does no match things which are not separators. This |
| 4625 | logical @samp{and} has higher priority than the logical @samp{or} |
| 4626 | specified in @code{reftex-index-phrases-logical-or-regexp}. |
| 4627 | @end defopt |
| 4628 | |
| 4629 | @defopt reftex-index-phrases-logical-or-regexp |
| 4630 | Regexp matching the @samp{or} operator for index arguments in phrases |
| 4631 | file. When several index arguments in a phrase line are separated by |
| 4632 | this operator, the user will be asked to select one of them at each |
| 4633 | match of the search phrase. The first index arg will be the default. A |
| 4634 | number key @kbd{1}--@kbd{9} must be pressed to switch to another. Make |
| 4635 | sure this does no match things which are not separators. The logical |
| 4636 | @samp{and} specified in @code{reftex-index-phrases-logical-or-regexp} |
| 4637 | has higher priority than this logical @samp{or}. |
| 4638 | @end defopt |
| 4639 | |
| 4640 | @defopt reftex-index-phrases-search-whole-words |
| 4641 | Non-@code{nil} means phrases search will look for whole words, not subwords. |
| 4642 | This works by requiring word boundaries at the beginning and end of |
| 4643 | the search string. When the search phrase already has a non-word-char |
| 4644 | at one of these points, no word boundary is required there. |
| 4645 | @end defopt |
| 4646 | |
| 4647 | @defopt reftex-index-phrases-case-fold-search |
| 4648 | Non-@code{nil} means, searching for index phrases will ignore |
| 4649 | case. |
| 4650 | @end defopt |
| 4651 | |
| 4652 | @defopt reftex-index-verify-function |
| 4653 | A function which is called at each match during global indexing. |
| 4654 | If the function returns nil, the current match is skipped. |
| 4655 | @end defopt |
| 4656 | |
| 4657 | @defopt reftex-index-phrases-skip-indexed-matches |
| 4658 | Non-@code{nil} means, skip matches which appear to be indexed already. |
| 4659 | When doing global indexing from the phrases buffer, searches for some |
| 4660 | phrases may match at places where that phrase was already indexed. In |
| 4661 | particular when indexing an already processed document again, this |
| 4662 | will even be the norm. When this variable is non-@code{nil}, |
| 4663 | @b{Ref@TeX{}} checks if the match is an index macro argument, or if an |
| 4664 | index macro is directly before or after the phrase. If that is the |
| 4665 | case, that match will be ignored. |
| 4666 | @end defopt |
| 4667 | |
| 4668 | @defopt reftex-index-phrases-wrap-long-lines |
| 4669 | Non-@code{nil} means, when indexing from the phrases buffer, wrap lines. |
| 4670 | Inserting indexing commands in a line makes the line longer - often |
| 4671 | so long that it does not fit onto the screen. When this variable is |
| 4672 | non-@code{nil}, newlines will be added as necessary before and/or after the |
| 4673 | indexing command to keep lines short. However, the matched text |
| 4674 | phrase and its index command will always end up on a single line. |
| 4675 | @end defopt |
| 4676 | |
| 4677 | @defopt reftex-index-phrases-sort-prefers-entry |
| 4678 | Non-@code{nil} means when sorting phrase lines, the explicit index entry |
| 4679 | is used. Phrase lines in the phrases buffer contain a search phrase, and |
| 4680 | sorting is normally based on these. Some phrase lines also have |
| 4681 | an explicit index argument specified. When this variable is |
| 4682 | non-@code{nil}, the index argument will be used for sorting. |
| 4683 | @end defopt |
| 4684 | |
| 4685 | @defopt reftex-index-phrases-sort-in-blocks |
| 4686 | Non-@code{nil} means, empty and comment lines separate phrase buffer |
| 4687 | into blocks. Sorting will then preserve blocks, so that lines are |
| 4688 | re-arranged only within blocks. |
| 4689 | @end defopt |
| 4690 | |
| 4691 | @defopt reftex-index-phrases-map |
| 4692 | Keymap for the Index Phrases buffer. |
| 4693 | @end defopt |
| 4694 | |
| 4695 | @defopt reftex-index-phrases-mode-hook |
| 4696 | Normal hook which is run when a buffer is put into |
| 4697 | @code{reftex-index-phrases-mode}. |
| 4698 | @end defopt |
| 4699 | |
| 4700 | @defopt reftex-index-section-letters |
| 4701 | The letters which denote sections in the index. Usually these are all |
| 4702 | capital letters. Don't use any downcase letters. Order is not |
| 4703 | significant, the index will be sorted by whatever the sort function |
| 4704 | thinks is correct. In addition to these letters, @b{Ref@TeX{}} will |
| 4705 | create a group @samp{!} which contains all entries sorted below the |
| 4706 | lowest specified letter. In the @file{*Index*} buffer, pressing any of |
| 4707 | these capital letters or @kbd{!} will jump to that section. |
| 4708 | @end defopt |
| 4709 | |
| 4710 | @defopt reftex-index-include-context |
| 4711 | Non-@code{nil} means, display the index definition context in the |
| 4712 | @file{*Index*} buffer. This flag may also be toggled from the |
| 4713 | @file{*Index*} buffer with the @kbd{c} key. |
| 4714 | @end defopt |
| 4715 | |
| 4716 | @defopt reftex-index-follow-mode |
| 4717 | Non-@code{nil} means, point in @file{*Index*} buffer will cause other |
| 4718 | window to follow. The other window will show the corresponding part of |
| 4719 | the document. This flag can be toggled from within the @file{*Index*} |
| 4720 | buffer with the @kbd{f} key. |
| 4721 | @end defopt |
| 4722 | |
| 4723 | @deffn Keymap reftex-index-map |
| 4724 | The keymap which is active in the @file{*Index*} buffer |
| 4725 | (@pxref{Index Support}). |
| 4726 | @end deffn |
| 4727 | |
| 4728 | @node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support), Options |
| 4729 | @section Viewing Cross-References |
| 4730 | @cindex Options, viewing cross-references |
| 4731 | @cindex Viewing cross-references, options |
| 4732 | |
| 4733 | @defopt reftex-view-crossref-extra |
| 4734 | Macros which can be used for the display of cross references. |
| 4735 | This is used when `reftex-view-crossref' is called with point in an |
| 4736 | argument of a macro. Note that crossref viewing for citations, |
| 4737 | references (both ways) and index entries is hard-coded. This variable |
| 4738 | is only to configure additional structures for which crossreference |
| 4739 | viewing can be useful. Each entry has the structure |
| 4740 | @example |
| 4741 | (@var{macro-re} @var{search-re} @var{highlight}). |
| 4742 | @end example |
| 4743 | @var{macro-re} is matched against the macro. @var{search-re} is the |
| 4744 | regexp used to search for cross references. @samp{%s} in this regexp is |
| 4745 | replaced with the macro argument at point. @var{highlight} is an |
| 4746 | integer indicating which subgroup of the match should be highlighted. |
| 4747 | @end defopt |
| 4748 | |
| 4749 | @defopt reftex-auto-view-crossref |
| 4750 | Non-@code{nil} means, initially turn automatic viewing of crossref info |
| 4751 | on. Automatic viewing of crossref info normally uses the echo area. |
| 4752 | Whenever point is idle for more than @code{reftex-idle-time} seconds on |
| 4753 | the argument of a @code{\ref} or @code{\cite} macro, and no other |
| 4754 | message is being displayed, the echo area will display information about |
| 4755 | that cross reference. You can also set the variable to the symbol |
| 4756 | @code{window}. In this case a small temporary window is used for the |
| 4757 | display. This feature can be turned on and off from the menu |
| 4758 | (Ref->Options). |
| 4759 | @end defopt |
| 4760 | |
| 4761 | @defopt reftex-idle-time |
| 4762 | Time (secs) Emacs has to be idle before automatic crossref display |
| 4763 | or toc recentering is done. |
| 4764 | @end defopt |
| 4765 | |
| 4766 | @defopt reftex-cite-view-format |
| 4767 | Citation format used to display citation info in the message area. See |
| 4768 | the variable @code{reftex-cite-format} for possible percent |
| 4769 | escapes. |
| 4770 | @end defopt |
| 4771 | |
| 4772 | @defopt reftex-revisit-to-echo |
| 4773 | Non-@code{nil} means, automatic citation display will revisit files if |
| 4774 | necessary. When nil, citation display in echo area will only be active |
| 4775 | for cached echo strings (see @code{reftex-cache-cite-echo}), or for |
| 4776 | BibTeX database files which are already visited by a live associated |
| 4777 | buffers. |
| 4778 | @end defopt |
| 4779 | |
| 4780 | @defopt reftex-cache-cite-echo |
| 4781 | Non-@code{nil} means, the information displayed in the echo area for |
| 4782 | cite macros (see variable @code{reftex-auto-view-crossref}) is cached and |
| 4783 | saved along with the parsing information. The cache survives document |
| 4784 | scans. In order to clear it, use @kbd{M-x reftex-reset-mode}. |
| 4785 | @end defopt |
| 4786 | |
| 4787 | @node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References), Options |
| 4788 | @section Finding Files |
| 4789 | @cindex Options, Finding Files |
| 4790 | @cindex Finding files, options |
| 4791 | |
| 4792 | @defopt reftex-texpath-environment-variables |
| 4793 | List of specifications how to retrieve the search path for TeX files. |
| 4794 | Several entries are possible. |
| 4795 | @itemize @minus |
| 4796 | @item |
| 4797 | If an element is the name of an environment variable, its content is |
| 4798 | used. |
| 4799 | @item |
| 4800 | If an element starts with an exclamation mark, it is used as a command |
| 4801 | to retrieve the path. A typical command with the kpathsearch library |
| 4802 | would be @w{@code{"!kpsewhich -show-path=.tex"}}. |
| 4803 | @item |
| 4804 | Otherwise the element itself is interpreted as a path. |
| 4805 | @end itemize |
| 4806 | Multiple directories can be separated by the system dependent |
| 4807 | @code{path-separator}. Directories ending in @samp{//} or @samp{!!} will |
| 4808 | be expanded recursively. See also @code{reftex-use-external-file-finders}. |
| 4809 | @end defopt |
| 4810 | |
| 4811 | @defopt reftex-bibpath-environment-variables |
| 4812 | List of specifications how to retrieve the search path for BibTeX |
| 4813 | files. Several entries are possible. |
| 4814 | @itemize @minus |
| 4815 | @item |
| 4816 | If an element is the name of an environment variable, its content is |
| 4817 | used. |
| 4818 | @item |
| 4819 | If an element starts with an exclamation mark, it is used as a command |
| 4820 | to retrieve the path. A typical command with the kpathsearch library |
| 4821 | would be @w{@code{"!kpsewhich -show-path=.bib"}}. |
| 4822 | @item |
| 4823 | Otherwise the element itself is interpreted as a path. |
| 4824 | @end itemize |
| 4825 | Multiple directories can be separated by the system dependent |
| 4826 | @code{path-separator}. Directories ending in @samp{//} or @samp{!!} will |
| 4827 | be expanded recursively. See also @code{reftex-use-external-file-finders}. |
| 4828 | @end defopt |
| 4829 | |
| 4830 | @defopt reftex-file-extensions |
| 4831 | Association list with file extensions for different file types. |
| 4832 | This is a list of items, each item is like: |
| 4833 | @code{(@var{type} . (@var{def-ext} @var{other-ext} ...))} |
| 4834 | @example |
| 4835 | @var{type}: @r{File type like @code{"bib"} or @code{"tex"}.} |
| 4836 | @var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.} |
| 4837 | @var{other-ext}: @r{Any number of other valid extensions for this file type.} |
| 4838 | @end example |
| 4839 | When a files is searched and it does not have any of the valid extensions, |
| 4840 | we try the default extension first, and then the naked file name. |
| 4841 | @end defopt |
| 4842 | |
| 4843 | @defopt reftex-search-unrecursed-path-first |
| 4844 | Non-@code{nil} means, search all specified directories before trying |
| 4845 | recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./}, |
| 4846 | then @samp{/tex/}, and then all subdirectories of @samp{./}. If this |
| 4847 | option is @code{nil}, the subdirectories of @samp{./} are searched |
| 4848 | before @samp{/tex/}. This is mainly for speed - most of the time the |
| 4849 | recursive path is for the system files and not for the user files. Set |
| 4850 | this to @code{nil} if the default makes @b{Ref@TeX{}} finding files with |
| 4851 | equal names in wrong sequence. |
| 4852 | @end defopt |
| 4853 | |
| 4854 | @defopt reftex-use-external-file-finders |
| 4855 | Non-@code{nil} means, use external programs to find files. Normally, |
| 4856 | @b{Ref@TeX{}} searches the paths given in the environment variables |
| 4857 | @code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX |
| 4858 | database files. With this option turned on, it calls an external |
| 4859 | program specified in the option @code{reftex-external-file-finders} |
| 4860 | instead. As a side effect, the variables |
| 4861 | @code{reftex-texpath-environment-variables} and |
| 4862 | @code{reftex-bibpath-environment-variables} will be ignored. |
| 4863 | @end defopt |
| 4864 | |
| 4865 | @defopt reftex-external-file-finders |
| 4866 | Association list with external programs to call for finding files. Each |
| 4867 | entry is a cons cell @w{@code{(@var{type} . @var{program})}}. |
| 4868 | @var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a |
| 4869 | string containing the external program to use with any arguments. |
| 4870 | @code{%f} will be replaced by the name of the file to be found. Note |
| 4871 | that these commands will be executed directly, not via a shell. Only |
| 4872 | relevant when @code{reftex-use-external-file-finders} is |
| 4873 | non-@code{nil}. |
| 4874 | @end defopt |
| 4875 | |
| 4876 | @page |
| 4877 | @node Options (Optimizations), Options (Fontification), Options (Finding Files), Options |
| 4878 | @section Optimizations |
| 4879 | @cindex Options, optimizations |
| 4880 | @cindex Optimizations, options |
| 4881 | |
| 4882 | @defopt reftex-keep-temporary-buffers |
| 4883 | Non-@code{nil} means, keep buffers created for parsing and lookup. |
| 4884 | @b{Ref@TeX{}} sometimes needs to visit files related to the current |
| 4885 | document. We distinguish files visited for |
| 4886 | @table @asis |
| 4887 | @item PARSING |
| 4888 | Parts of a multifile document loaded when (re)-parsing the |
| 4889 | document. |
| 4890 | @item LOOKUP |
| 4891 | BibTeX database files and TeX files loaded to find a reference, to |
| 4892 | display label context, etc. |
| 4893 | @end table |
| 4894 | The created buffers can be kept for later use, or be thrown away |
| 4895 | immediately after use, depending on the value of this variable: |
| 4896 | |
| 4897 | @table @code |
| 4898 | @item nil |
| 4899 | Throw away as much as possible. |
| 4900 | @item t |
| 4901 | Keep everything. |
| 4902 | @item 1 |
| 4903 | Throw away buffers created for parsing, but keep the ones created for |
| 4904 | lookup. |
| 4905 | @end table |
| 4906 | |
| 4907 | If a buffer is to be kept, the file is visited normally (which is |
| 4908 | potentially slow but will happen only once). If a buffer is to be thrown |
| 4909 | away, the initialization of the buffer depends upon the variable |
| 4910 | @code{reftex-initialize-temporary-buffers}. |
| 4911 | @end defopt |
| 4912 | |
| 4913 | @defopt reftex-initialize-temporary-buffers |
| 4914 | Non-@code{nil} means do initializations even when visiting file |
| 4915 | temporarily. When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and |
| 4916 | other stuff to briefly visit a file. When @code{t}, the full default |
| 4917 | initializations are done (@code{find-file-hook} etc.). Instead of |
| 4918 | @code{t} or @code{nil}, this variable may also be a list of hook |
| 4919 | functions to do a minimal initialization. |
| 4920 | @end defopt |
| 4921 | |
| 4922 | @defopt reftex-no-include-regexps |
| 4923 | List of regular expressions to exclude certain input files from parsing. |
| 4924 | If the name of a file included via @code{\include} or @code{\input} is |
| 4925 | matched by any of the regular expressions in this list, that file is not |
| 4926 | parsed by @b{Ref@TeX{}}. |
| 4927 | @end defopt |
| 4928 | |
| 4929 | @defopt reftex-enable-partial-scans |
| 4930 | Non-@code{nil} means, re-parse only 1 file when asked to re-parse. |
| 4931 | Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}} |
| 4932 | commands, or with the @kbd{r} key in menus. When this option is |
| 4933 | @code{t} in a multifile document, we will only parse the current buffer, |
| 4934 | or the file associated with the label or section heading near point in a |
| 4935 | menu. Requesting re-parsing of an entire multifile document then |
| 4936 | requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in |
| 4937 | menus. |
| 4938 | @end defopt |
| 4939 | |
| 4940 | @defopt reftex-save-parse-info |
| 4941 | Non-@code{nil} means, save information gathered with parsing in files. |
| 4942 | The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is |
| 4943 | used to save the information. When this variable is @code{t}, |
| 4944 | @itemize @minus |
| 4945 | @item |
| 4946 | accessing the parsing information for the first time in an editing |
| 4947 | session will read that file (if available) instead of parsing the |
| 4948 | document. |
| 4949 | @item |
| 4950 | exiting Emacs or killing a buffer in reftex-mode will cause a new |
| 4951 | version of the file to be written. |
| 4952 | @end itemize |
| 4953 | @end defopt |
| 4954 | |
| 4955 | @defopt reftex-parse-file-extension |
| 4956 | File extension for the file in which parser information is stored. |
| 4957 | This extension is added to the base name of the master file. |
| 4958 | @end defopt |
| 4959 | |
| 4960 | @defopt reftex-allow-automatic-rescan |
| 4961 | Non-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seems |
| 4962 | necessary. Applies (currently) only in rare cases, when a new label |
| 4963 | cannot be placed with certainty into the internal label list. |
| 4964 | @end defopt |
| 4965 | |
| 4966 | @defopt reftex-use-multiple-selection-buffers |
| 4967 | Non-@code{nil} means use a separate selection buffer for each label |
| 4968 | type. These buffers are kept from one selection to the next and need |
| 4969 | not to be created for each use - so the menu generally comes up faster. |
| 4970 | The selection buffers will be erased (and therefore updated) |
| 4971 | automatically when new labels in its category are added. See the |
| 4972 | variable @code{reftex-auto-update-selection-buffers}. |
| 4973 | @end defopt |
| 4974 | |
| 4975 | @defopt reftex-auto-update-selection-buffers |
| 4976 | Non-@code{nil} means, selection buffers will be updated automatically. |
| 4977 | When a new label is defined with @code{reftex-label}, all selection |
| 4978 | buffers associated with that label category are emptied, in order to |
| 4979 | force an update upon next use. When @code{nil}, the buffers are left |
| 4980 | alone and have to be updated by hand, with the @kbd{g} key from the |
| 4981 | label selection process. The value of this variable will only have any |
| 4982 | effect when @code{reftex-use-multiple-selection-buffers} is |
| 4983 | non-@code{nil}. |
| 4984 | @end defopt |
| 4985 | |
| 4986 | @node Options (Fontification), Options (Misc), Options (Optimizations), Options |
| 4987 | @section Fontification |
| 4988 | @cindex Options, fontification |
| 4989 | @cindex Fontification, options |
| 4990 | |
| 4991 | @defopt reftex-use-fonts |
| 4992 | Non-@code{nil} means, use fonts in label menu and on-the-fly help. |
| 4993 | Font-lock must be loaded as well to actually get fontified |
| 4994 | display. After changing this option, a rescan may be necessary to |
| 4995 | activate it. |
| 4996 | @end defopt |
| 4997 | |
| 4998 | @defopt reftex-refontify-context |
| 4999 | Non-@code{nil} means, re-fontify the context in the label menu with |
| 5000 | font-lock. This slightly slows down the creation of the label menu. It |
| 5001 | is only necessary when you definitely want the context fontified. |
| 5002 | |
| 5003 | This option may have 3 different values: |
| 5004 | @table @code |
| 5005 | @item nil |
| 5006 | Never refontify. |
| 5007 | @item t |
| 5008 | Always refontify. |
| 5009 | @item 1 |
| 5010 | Refontify when necessary, e.g. with old versions of the x-symbol |
| 5011 | package. |
| 5012 | @end table |
| 5013 | The option is ignored when @code{reftex-use-fonts} is @code{nil}. |
| 5014 | @end defopt |
| 5015 | |
| 5016 | @defopt reftex-highlight-selection |
| 5017 | Non-@code{nil} means, highlight selected text in selection and |
| 5018 | @file{*toc*} buffers. Normally, the text near the cursor is the |
| 5019 | @emph{selected} text, and it is highlighted. This is the entry most |
| 5020 | keys in the selection and @file{*toc*} buffers act on. However, if you |
| 5021 | mainly use the mouse to select an item, you may find it nice to have |
| 5022 | mouse-triggered highlighting @emph{instead} or @emph{as well}. The |
| 5023 | variable may have one of these values: |
| 5024 | |
| 5025 | @example |
| 5026 | nil @r{No highlighting.} |
| 5027 | cursor @r{Highlighting is cursor driven.} |
| 5028 | mouse @r{Highlighting is mouse driven.} |
| 5029 | both @r{Both cursor and mouse trigger highlighting.} |
| 5030 | @end example |
| 5031 | |
| 5032 | Changing this variable requires to rebuild the selection and *toc* |
| 5033 | buffers to become effective (keys @kbd{g} or @kbd{r}). |
| 5034 | @end defopt |
| 5035 | |
| 5036 | @defopt reftex-cursor-selected-face |
| 5037 | Face name to highlight cursor selected item in toc and selection buffers. |
| 5038 | See also the variable @code{reftex-highlight-selection}. |
| 5039 | @end defopt |
| 5040 | @defopt reftex-mouse-selected-face |
| 5041 | Face name to highlight mouse selected item in toc and selection buffers. |
| 5042 | See also the variable @code{reftex-highlight-selection}. |
| 5043 | @end defopt |
| 5044 | @defopt reftex-file-boundary-face |
| 5045 | Face name for file boundaries in selection buffer. |
| 5046 | @end defopt |
| 5047 | @defopt reftex-label-face |
| 5048 | Face name for labels in selection buffer. |
| 5049 | @end defopt |
| 5050 | @defopt reftex-section-heading-face |
| 5051 | Face name for section headings in toc and selection buffers. |
| 5052 | @end defopt |
| 5053 | @defopt reftex-toc-header-face |
| 5054 | Face name for the header of a toc buffer. |
| 5055 | @end defopt |
| 5056 | @defopt reftex-bib-author-face |
| 5057 | Face name for author names in bib selection buffer. |
| 5058 | @end defopt |
| 5059 | @defopt reftex-bib-year-face |
| 5060 | Face name for year in bib selection buffer. |
| 5061 | @end defopt |
| 5062 | @defopt reftex-bib-title-face |
| 5063 | Face name for article title in bib selection buffer. |
| 5064 | @end defopt |
| 5065 | @defopt reftex-bib-extra-face |
| 5066 | Face name for bibliographic information in bib selection buffer. |
| 5067 | @end defopt |
| 5068 | @defopt reftex-select-mark-face |
| 5069 | Face name for marked entries in the selection buffers. |
| 5070 | @end defopt |
| 5071 | @defopt reftex-index-header-face |
| 5072 | Face name for the header of an index buffer. |
| 5073 | @end defopt |
| 5074 | @defopt reftex-index-section-face |
| 5075 | Face name for the start of a new letter section in the index. |
| 5076 | @end defopt |
| 5077 | @defopt reftex-index-tag-face |
| 5078 | Face name for index names (for multiple indices). |
| 5079 | @end defopt |
| 5080 | @defopt reftex-index-face |
| 5081 | Face name for index entries. |
| 5082 | @end defopt |
| 5083 | |
| 5084 | @node Options (Misc), , Options (Fontification), Options |
| 5085 | @section Miscellaneous |
| 5086 | @cindex Options, misc |
| 5087 | |
| 5088 | @defopt reftex-extra-bindings |
| 5089 | Non-@code{nil} means, make additional key bindings on startup. These |
| 5090 | extra bindings are located in the users @samp{C-c letter} |
| 5091 | map. @xref{Key Bindings}. |
| 5092 | @end defopt |
| 5093 | |
| 5094 | @defopt reftex-plug-into-AUCTeX |
| 5095 | Plug-in flags for AUCTeX interface. This variable is a list of |
| 5096 | 5 boolean flags. When a flag is non-@code{nil}, @b{Ref@TeX{}} |
| 5097 | will |
| 5098 | |
| 5099 | @example |
| 5100 | - supply labels in new sections and environments (flag 1) |
| 5101 | - supply arguments for macros like @code{\label} (flag 2) |
| 5102 | - supply arguments for macros like @code{\ref} (flag 3) |
| 5103 | - supply arguments for macros like @code{\cite} (flag 4) |
| 5104 | - supply arguments for macros like @code{\index} (flag 5) |
| 5105 | @end example |
| 5106 | |
| 5107 | You may also set the variable itself to t or nil in order to turn all |
| 5108 | options on or off, respectively.@* |
| 5109 | Supplying labels in new sections and environments applies when creating |
| 5110 | sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@* |
| 5111 | Supplying macro arguments applies when you insert such a macro |
| 5112 | interactively with @kbd{C-c @key{RET}}.@* |
| 5113 | See the AUCTeX documentation for more information. |
| 5114 | @end defopt |
| 5115 | |
| 5116 | @defopt reftex-revisit-to-follow |
| 5117 | Non-@code{nil} means, follow-mode will revisit files if necessary. |
| 5118 | When nil, follow-mode will be suspended for stuff in unvisited files. |
| 5119 | @end defopt |
| 5120 | |
| 5121 | @defopt reftex-allow-detached-macro-args |
| 5122 | Non-@code{nil} means, allow arguments of macros to be detached by |
| 5123 | whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb |
| 5124 | [xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that |
| 5125 | this will be the case even if @code{\bb} is defined with zero or one |
| 5126 | argument. |
| 5127 | @end defopt |
| 5128 | |
| 5129 | @node Keymaps and Hooks, Changes, Options, Top |
| 5130 | @section Keymaps and Hooks |
| 5131 | @cindex Keymaps |
| 5132 | |
| 5133 | @b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook. |
| 5134 | |
| 5135 | @deffn Keymap reftex-mode-map |
| 5136 | The keymap for @b{Ref@TeX{}} mode. |
| 5137 | @end deffn |
| 5138 | |
| 5139 | @deffn {Normal Hook} reftex-load-hook |
| 5140 | Normal hook which is being run when loading @file{reftex.el}. |
| 5141 | @end deffn |
| 5142 | |
| 5143 | @deffn {Normal Hook} reftex-mode-hook |
| 5144 | Normal hook which is being run when turning on @b{Ref@TeX{}} mode. |
| 5145 | @end deffn |
| 5146 | |
| 5147 | Furthermore, the 4 modes used for referencing labels, creating |
| 5148 | citations, the table of contents buffer and the phrases buffer have |
| 5149 | their own keymaps and mode hooks. See the respective sections. There |
| 5150 | are many more hooks which are described in the relevant sections about |
| 5151 | options for a specific part of @b{Ref@TeX{}}. |
| 5152 | |
| 5153 | @node Changes, GNU Free Documentation License, Keymaps and Hooks, Top |
| 5154 | @chapter Changes |
| 5155 | @cindex Changes |
| 5156 | |
| 5157 | Here is a list of recent changes to @b{Ref@TeX{}}. |
| 5158 | |
| 5159 | @noindent @b{Version 4.28} |
| 5160 | @itemize @bullet |
| 5161 | @item Support for the Jurabib package. |
| 5162 | @item Improvements when selecting several items in a selection buffer. |
| 5163 | @end itemize |
| 5164 | |
| 5165 | @noindent @b{Version 4.26} |
| 5166 | @itemize @bullet |
| 5167 | @item |
| 5168 | Support for global incremental search. |
| 5169 | @item |
| 5170 | Some improvements for XEmacs compatibility. |
| 5171 | @end itemize |
| 5172 | |
| 5173 | @noindent @b{Version 4.25} |
| 5174 | @itemize @bullet |
| 5175 | @item |
| 5176 | Fixed bug with @samp{%F} in a label prefix. Added new escapes |
| 5177 | @samp{%m} and @samp{%M} for mater file name and master directory. |
| 5178 | @end itemize |
| 5179 | |
| 5180 | @noindent @b{Version 4.24} |
| 5181 | @itemize @bullet |
| 5182 | @item |
| 5183 | Inserting citation commands now prompts for optional arguments |
| 5184 | when called with a prefix argument. Related new options are |
| 5185 | @code{reftex-cite-prompt-optional-args} and |
| 5186 | @code{reftex-cite-cleanup-optional-args}. |
| 5187 | @item |
| 5188 | New option @code{reftex-trust-label-prefix}. Configure this variable |
| 5189 | if you'd like RefTeX to base its classification of labels on prefixes. |
| 5190 | This can speed-up document parsing, but may in some cases reduce the |
| 5191 | quality of the context used by RefTeX to describe a label. |
| 5192 | @item |
| 5193 | Fixed bug in @code{reftex-create-bibtex-file} when @code{reftex-comment-citations} |
| 5194 | is non-nil. |
| 5195 | @item |
| 5196 | Fixed bugs in indexing: Case-sensitive search, quotes before and/or |
| 5197 | after words. Disabled indexing in comment lines. |
| 5198 | @end itemize |
| 5199 | |
| 5200 | @noindent @b{Version 4.22} |
| 5201 | @itemize @bullet |
| 5202 | @item |
| 5203 | New command @code{reftex-create-bibtex-file} to create a new database |
| 5204 | with all entries referenced in the current document. |
| 5205 | @item |
| 5206 | New keys @kbd{e} and @kbd{E} allow to produce a BibTeX database file |
| 5207 | from entries marked in a citation selection buffer. |
| 5208 | @end itemize |
| 5209 | |
| 5210 | @noindent @b{Version 4.21} |
| 5211 | @itemize @bullet |
| 5212 | @item |
| 5213 | Renaming labels from the toc buffer with key @kbd{M-%}. |
| 5214 | @end itemize |
| 5215 | |
| 5216 | @noindent @b{Version 4.20} |
| 5217 | @itemize @bullet |
| 5218 | @item |
| 5219 | Structure editing capabilities. The command keys @kbd{<} and @kbd{>} in |
| 5220 | the TOC buffer promote/demote the section at point or all sections in |
| 5221 | the current region. |
| 5222 | @item |
| 5223 | New option @code{reftex-toc-split-windows-fraction} to set the size of |
| 5224 | the window used by the TOC. This makes the old variable |
| 5225 | @code{reftex-toc-split-windows-horizontally-fraction} obsolete. |
| 5226 | @item |
| 5227 | A dedicated frame can show the TOC with the current section |
| 5228 | always automatically highlighted. The frame is created and |
| 5229 | deleted from the toc buffer with the @kbd{d} key. |
| 5230 | @end itemize |
| 5231 | |
| 5232 | @noindent @b{Version 4.19} |
| 5233 | @itemize @bullet |
| 5234 | @item |
| 5235 | New command `reftex-toc-recenter' (@kbd{C-c -}) which shows the current |
| 5236 | section in the TOC buffer without selecting the TOC window. |
| 5237 | @item |
| 5238 | Recentering happens automatically in idle time when the option |
| 5239 | @code{reftex-auto-recenter-toc} is turned on. |
| 5240 | @item |
| 5241 | Fixed several bugs related to automatic cursor positioning in the TOC |
| 5242 | buffer. |
| 5243 | @item |
| 5244 | The highlight in the TOC buffer stays when the focus moves to a |
| 5245 | different window. |
| 5246 | @item |
| 5247 | New command `reftex-goto-label'. |
| 5248 | @item |
| 5249 | Part numbers are no longer included in chapter numbers, and a new |
| 5250 | part does not reset the chapter counter. See new option |
| 5251 | @code{reftex-part-resets-chapter}. |
| 5252 | @end itemize |
| 5253 | |
| 5254 | @noindent @b{Version 4.18} |
| 5255 | @itemize @bullet |
| 5256 | @item |
| 5257 | @code{reftex-citation} uses the word before the cursor as a default |
| 5258 | search string. |
| 5259 | @item |
| 5260 | Simplified several regular expressions for speed. |
| 5261 | @item |
| 5262 | Better support for chapterbib. |
| 5263 | @end itemize |
| 5264 | |
| 5265 | @noindent @b{Version 4.17} |
| 5266 | @itemize @bullet |
| 5267 | @item |
| 5268 | The toc window can be split off horizontally. See new options |
| 5269 | @code{reftex-toc-split-windows-horizontally}, |
| 5270 | @code{reftex-toc-split-windows-horizontally-fraction}. |
| 5271 | @item |
| 5272 | It is possible to specify a function which verifies an index match |
| 5273 | during global indexing. See new option @code{reftex-index-verify-function}. |
| 5274 | @item |
| 5275 | The macros which input a file in LaTeX (like \input, \include) can |
| 5276 | be configured. See new option @code{reftex-include-file-commands}. |
| 5277 | @item |
| 5278 | The macros which specify the bibliography file (like \bibliography) can |
| 5279 | be configured. See new option @code{reftex-bibliography-commands}. |
| 5280 | @item |
| 5281 | The regular expression used to search for the \bibliography macro has |
| 5282 | been relaxed to allow for @samp{@{\bibliography@{...@}@}} needed by |
| 5283 | chapterbib. |
| 5284 | @item |
| 5285 | Small bug fixes. |
| 5286 | @end itemize |
| 5287 | |
| 5288 | @noindent @b{Version 4.15} |
| 5289 | @itemize @bullet |
| 5290 | @item |
| 5291 | Fixed bug with parsing of BibTeX files, when fields contain quotes or |
| 5292 | unmatched parenthesis. |
| 5293 | @item |
| 5294 | Small bug fixes. |
| 5295 | @item |
| 5296 | Improved interaction with Emacs LaTeX mode. |
| 5297 | @end itemize |
| 5298 | |
| 5299 | @noindent @b{Version 4.12} |
| 5300 | @itemize @bullet |
| 5301 | @item |
| 5302 | Support for @file{bibentry} citation style. |
| 5303 | @end itemize |
| 5304 | |
| 5305 | @noindent @b{Version 4.11} |
| 5306 | @itemize @bullet |
| 5307 | @item |
| 5308 | Fixed bug which would parse @samp{\Section} just like @samp{\section}. |
| 5309 | @end itemize |
| 5310 | |
| 5311 | @noindent @b{Version 4.10} |
| 5312 | @itemize @bullet |
| 5313 | @item |
| 5314 | Renamed @file{reftex-vcr.el} to @file{reftex-dcr.el} because of conflict |
| 5315 | with @file{reftex-vars.el} on DOS machines. |
| 5316 | @item |
| 5317 | New options @code{reftex-parse-file-extension} and |
| 5318 | @code{reftex-index-phrase-file-extension}. |
| 5319 | @end itemize |
| 5320 | |
| 5321 | @noindent [.....] |
| 5322 | @ignore |
| 5323 | @noindent @b{Version 4.09} |
| 5324 | @itemize @bullet |
| 5325 | @item |
| 5326 | New option @code{reftex-toc-max-level} to limit the depth of the toc. |
| 5327 | New key binding @kbd{t} in the @file{*toc*} buffer to change this |
| 5328 | setting. |
| 5329 | @item |
| 5330 | RefTeX maintains an @file{Index Phrases} file in which phrases can be |
| 5331 | collected. When the document is ready, RefTeX can search all |
| 5332 | these phrases and assist indexing all matches. |
| 5333 | @item |
| 5334 | The variables @code{reftex-index-macros} and |
| 5335 | @code{reftex-index-default-macro} have changed their syntax slightly. |
| 5336 | The @var{repeat} parameter has move from the latter to the former. |
| 5337 | Also calls to @code{reftex-add-index-macros} from AUCTeX style files |
| 5338 | need to be adapted. |
| 5339 | @item |
| 5340 | The variable @code{reftex-section-levels} no longer contains the |
| 5341 | default stuff which has been moved to a constant. |
| 5342 | @item |
| 5343 | Environments like theorems can be placed into the TOC by putting |
| 5344 | entries for @samp{"begin@{theorem@}"} in |
| 5345 | @code{reftex-setion-levels}. |
| 5346 | @end itemize |
| 5347 | |
| 5348 | @noindent @b{Version 4.06} |
| 5349 | @itemize @bullet |
| 5350 | @item |
| 5351 | @code{reftex-section-levels} can contain a function to compute the level |
| 5352 | of a sectioning command. |
| 5353 | @item |
| 5354 | Multiple @code{thebibliography} environments recognized. |
| 5355 | @end itemize |
| 5356 | |
| 5357 | @noindent @b{Version 4.04} |
| 5358 | @itemize @bullet |
| 5359 | @item |
| 5360 | New option @code{reftex-index-default-tag} implements a default for queries. |
| 5361 | @end itemize |
| 5362 | |
| 5363 | @noindent @b{Version 4.02} |
| 5364 | @itemize @bullet |
| 5365 | @item |
| 5366 | macros ending in @samp{refrange} are considered to contain references. |
| 5367 | @item |
| 5368 | Index entries made with @code{reftex-index-selection-or-word} in TeX |
| 5369 | math mode automatically get enclosing @samp{$} to preserve math mode. See |
| 5370 | new option @code{reftex-index-math-format}. Requires AUCTeX. |
| 5371 | @end itemize |
| 5372 | |
| 5373 | @noindent @b{Version 4.01} |
| 5374 | @itemize @bullet |
| 5375 | @item |
| 5376 | New command @code{reftex-index-globally} to index a word in many |
| 5377 | places in the document. Also available from the index buffer with |
| 5378 | @kbd{&}. |
| 5379 | @item |
| 5380 | The first item in a @code{reftex-label-alist} entry may now also be a parser |
| 5381 | function to do non-standard parsing. |
| 5382 | @item |
| 5383 | @code{reftex-auto-view-crossref} no longer interferes with |
| 5384 | @code{pop-up-frames} (patch from Stefan Monnier). |
| 5385 | @end itemize |
| 5386 | |
| 5387 | @noindent @b{Version 4.00} |
| 5388 | @itemize @bullet |
| 5389 | @item |
| 5390 | RefTeX has been split into several smaller files which are autoloaded on |
| 5391 | demand. |
| 5392 | @item |
| 5393 | Index support, along with many new options. |
| 5394 | @item |
| 5395 | The selection of keys for @code{\ref} and @code{\cite} now allows to |
| 5396 | select multiple items by marking entries with the @kbd{m} key. |
| 5397 | @item |
| 5398 | Fancyref support. |
| 5399 | @end itemize |
| 5400 | |
| 5401 | @noindent @b{Version 3.43} |
| 5402 | @itemize @bullet |
| 5403 | @item |
| 5404 | Viewing cross-references generalized. Now works on @code{\label}, |
| 5405 | @code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of |
| 5406 | these, and from BibTeX buffers. |
| 5407 | @item |
| 5408 | New option @code{reftex-view-crossref-extra}. |
| 5409 | @item |
| 5410 | Support for the additional sectioning commands @code{\addchap} and |
| 5411 | @code{\addsec} which are defined in the LaTeX KOMA-Script classes. |
| 5412 | @item |
| 5413 | Files in @code{reftex-default-bibliography} will be searched along |
| 5414 | @code{BIBINPUTS} path. |
| 5415 | @item |
| 5416 | Reading a parse file now checks consistency. |
| 5417 | @end itemize |
| 5418 | |
| 5419 | @noindent @b{Version 3.42} |
| 5420 | @itemize @bullet |
| 5421 | @item |
| 5422 | File search further refined. New option @code{reftex-file-extensions}. |
| 5423 | @item |
| 5424 | @file{*toc*} buffer can show the file boundaries of a multifile |
| 5425 | document, all labels and associated context. New keys @kbd{i}, @kbd{l}, |
| 5426 | and @kbd{c}. New options @code{reftex-toc-include-labels}, |
| 5427 | @code{reftex-toc-include-context}, |
| 5428 | @code{reftex-toc-include-file-boundaries}. |
| 5429 | @end itemize |
| 5430 | |
| 5431 | @noindent @b{Version 3.41} |
| 5432 | @itemize @bullet |
| 5433 | @item |
| 5434 | New options @code{reftex-texpath-environment-variables}, |
| 5435 | @code{reftex-use-external-file-finders}, |
| 5436 | @code{reftex-external-file-finders}, |
| 5437 | @code{reftex-search-unrecursed-path-first}. |
| 5438 | @item |
| 5439 | @emph{kpathsearch} support. See new options and |
| 5440 | @code{reftex-bibpath-environment-variables}. |
| 5441 | @end itemize |
| 5442 | |
| 5443 | @noindent @b{Version 3.38} |
| 5444 | @itemize @bullet |
| 5445 | @item |
| 5446 | @code{reftex-view-crossref} no longer moves to find a macro. Point has |
| 5447 | to be on the macro argument. |
| 5448 | @end itemize |
| 5449 | |
| 5450 | @noindent @b{Version 3.36} |
| 5451 | @itemize @bullet |
| 5452 | @item |
| 5453 | New value @code{window} for option @code{reftex-auto-view-crossref}. |
| 5454 | @end itemize |
| 5455 | |
| 5456 | @noindent @b{Version 3.35} |
| 5457 | @itemize @bullet |
| 5458 | @item |
| 5459 | ISO 8859 Latin-1 chars are converted to ASCII to derive better labels. |
| 5460 | This takes back the related changes in 3.34 for safety reasons. |
| 5461 | @end itemize |
| 5462 | |
| 5463 | @noindent @b{Version 3.34} |
| 5464 | @itemize @bullet |
| 5465 | @item |
| 5466 | Additional flag in @code{reftex-derive-label-parameters} do make only |
| 5467 | lowercase labels (default @code{t}). |
| 5468 | @item |
| 5469 | All @file{.rel} files have a final newline to avoid queries. |
| 5470 | @item |
| 5471 | Single byte representations of accented European letters (ISO-8859-1) |
| 5472 | are now valid in labels. |
| 5473 | @end itemize |
| 5474 | |
| 5475 | @noindent @b{Version 3.33} |
| 5476 | @itemize @bullet |
| 5477 | @item |
| 5478 | Multiple selection buffers are now hidden buffers (they start with a |
| 5479 | SPACE). |
| 5480 | @item |
| 5481 | Fixed bug with file search when TEXINPUTS environment variable is empty. |
| 5482 | @end itemize |
| 5483 | |
| 5484 | @noindent @b{Version 3.30} |
| 5485 | @itemize @bullet |
| 5486 | @item |
| 5487 | In @code{reftex-citation}, the regular expression used to scan BibTeX |
| 5488 | files can be specified using completion on known citation keys. |
| 5489 | @item |
| 5490 | New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all} |
| 5491 | entries. |
| 5492 | @item |
| 5493 | New command @code{reftex-renumber-simple-labels} to renumber simple |
| 5494 | labels like @samp{eq:13} sequentially through a document. |
| 5495 | @end itemize |
| 5496 | |
| 5497 | @noindent @b{Version 3.28} |
| 5498 | @itemize @bullet |
| 5499 | @item |
| 5500 | Auto view crossref for XEmacs uses @code{post-command-hook} to restart the |
| 5501 | timer, since itimer restart is not reliable. |
| 5502 | @item |
| 5503 | Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}. |
| 5504 | @item |
| 5505 | Expansion of recursive tex and bib path rewritten. |
| 5506 | @item |
| 5507 | Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers. |
| 5508 | @item |
| 5509 | Fixed bug with section numbering after *-red sections. |
| 5510 | @end itemize |
| 5511 | |
| 5512 | @noindent @b{Version 3.27} |
| 5513 | @itemize @bullet |
| 5514 | @item |
| 5515 | Macros can define @emph{neutral} labels, just like @code{\label} |
| 5516 | itself. |
| 5517 | @item |
| 5518 | New option @code{reftex-allow-detached-macro-args}, default @code{nil}! |
| 5519 | @end itemize |
| 5520 | |
| 5521 | @noindent @b{Version 3.26} |
| 5522 | @itemize @bullet |
| 5523 | @item |
| 5524 | [X]Emacs 19 no longer supported. Use 3.22 for Emacs 19. |
| 5525 | @item |
| 5526 | New hooks @code{reftex-translate-to-ascii-function}, |
| 5527 | @code{reftex-string-to-label-function}. |
| 5528 | @item |
| 5529 | Made sure automatic crossref display will not visit/scan files. |
| 5530 | @end itemize |
| 5531 | |
| 5532 | @noindent @b{Version 3.25} |
| 5533 | @itemize @bullet |
| 5534 | @item |
| 5535 | Echoing of citation info caches the info for displayed entries. |
| 5536 | New option @code{reftex-cache-cite-echo}. |
| 5537 | @item |
| 5538 | @kbd{M-x reftex-reset-mode} now also removes the file with parsing |
| 5539 | info. |
| 5540 | @item |
| 5541 | Default of @code{reftex-revisit-to-follow} changed to nil. |
| 5542 | @end itemize |
| 5543 | |
| 5544 | @noindent @b{Version 3.24} |
| 5545 | @itemize @bullet |
| 5546 | @item |
| 5547 | New option @code{reftex-revisit-to-echo}. |
| 5548 | @item |
| 5549 | Interface with X-Symbol (>=2.6) is now complete and stable. |
| 5550 | @item |
| 5551 | Adapted to new outline, which uses overlays. |
| 5552 | @item |
| 5553 | File names in @code{\bibliography} may now have the @code{.bib} |
| 5554 | extension. |
| 5555 | @item |
| 5556 | Fixed Bug with parsing "single file" from master file buffer. |
| 5557 | @end itemize |
| 5558 | |
| 5559 | @noindent @b{Version 3.23} |
| 5560 | @itemize @bullet |
| 5561 | @item |
| 5562 | Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs. |
| 5563 | @item |
| 5564 | @code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse |
| 5565 | file. |
| 5566 | @item |
| 5567 | The cursor inside a @code{\ref} or @code{\cite} macro can now trigger |
| 5568 | automatic display of crossref information in the echo area. See |
| 5569 | variable @code{reftex-auto-view-crossref}. |
| 5570 | @item |
| 5571 | AUCTeX interface updates: |
| 5572 | @itemize @minus |
| 5573 | @item |
| 5574 | AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections. |
| 5575 | @item |
| 5576 | @b{Ref@TeX{}} notifies AUCTeX about new labels. |
| 5577 | @item |
| 5578 | @code{TeX-arg-ref} no longer used (introduction was unnecessary). |
| 5579 | @item |
| 5580 | @code{reftex-arg-label} and @code{reftex-arg-cite} fixed up. |
| 5581 | @item |
| 5582 | Settings added to @b{Ref@TeX{}} via style files remain local. |
| 5583 | @end itemize |
| 5584 | @item |
| 5585 | Fixed bug with @code{reftex-citation} in non-latex buffers. |
| 5586 | @item |
| 5587 | Fixed bug with syntax table and context refontification. |
| 5588 | @item |
| 5589 | Safety-net for name change of @code{font-lock-reference-face}. |
| 5590 | @end itemize |
| 5591 | |
| 5592 | @noindent @b{Version 3.22} |
| 5593 | @itemize @bullet |
| 5594 | @item |
| 5595 | Fixed bug with empty context strings. |
| 5596 | @item |
| 5597 | @code{reftex-mouse-view-crossref} is now bound by default at |
| 5598 | @kbd{S-mouse-2}. |
| 5599 | @end itemize |
| 5600 | |
| 5601 | @noindent @b{Version 3.21} |
| 5602 | @itemize @bullet |
| 5603 | @item |
| 5604 | New options for all faces used by @b{Ref@TeX{}}. They're in the |
| 5605 | customization group @code{reftex-fontification-configurations}. |
| 5606 | @end itemize |
| 5607 | |
| 5608 | @noindent @b{Version 3.19} |
| 5609 | @itemize @bullet |
| 5610 | @item |
| 5611 | Fixed bug with AUCTeX @code{TeX-master}. |
| 5612 | @end itemize |
| 5613 | |
| 5614 | @noindent @b{Version 3.18} |
| 5615 | @itemize @bullet |
| 5616 | @item |
| 5617 | The selection now uses a recursive edit, much like minibuffer input. |
| 5618 | This removes all restrictions during selection. E.g. you can now |
| 5619 | switch buffers at will, use the mouse etc. |
| 5620 | @item |
| 5621 | New option @code{reftex-highlight-selection}. |
| 5622 | @item |
| 5623 | @kbd{mouse-2} can be used to select in selection and @file{*toc*} |
| 5624 | buffers. |
| 5625 | @item |
| 5626 | Fixed some problems regarding the interaction with VIPER mode. |
| 5627 | @item |
| 5628 | Follow-mode is now only used after point motion. |
| 5629 | @item |
| 5630 | @b{Ref@TeX{}} now finally does not fontify temporary files anymore. |
| 5631 | @end itemize |
| 5632 | |
| 5633 | @noindent @b{Version 3.17} |
| 5634 | @itemize @bullet |
| 5635 | @item |
| 5636 | Additional bindings in selection and @file{*toc*} buffers. @kbd{g} |
| 5637 | redefined. |
| 5638 | @item |
| 5639 | New command @code{reftex-save-all-document-buffers}. |
| 5640 | @item |
| 5641 | Magic word matching made more intelligent. |
| 5642 | @item |
| 5643 | Selection process can switch to completion (with @key{TAB}). |
| 5644 | @item |
| 5645 | @code{\appendix} is now recognized and influences section numbering. |
| 5646 | @item |
| 5647 | File commentary shortened considerably (use Info documentation). |
| 5648 | @item |
| 5649 | New option @code{reftex-no-include-regexps} to skip some include files. |
| 5650 | @item |
| 5651 | New option @code{reftex-revisit-to-follow}. |
| 5652 | @end itemize |
| 5653 | |
| 5654 | @noindent @b{Version 3.16} |
| 5655 | @itemize @bullet |
| 5656 | @item |
| 5657 | New hooks @code{reftex-format-label-function}, |
| 5658 | @code{reftex-format-ref-function}, @code{reftex-format-cite-function}. |
| 5659 | @item |
| 5660 | TeXInfo documentation completed. |
| 5661 | @item |
| 5662 | Some restrictions in Label inserting and referencing removed. |
| 5663 | @item |
| 5664 | New variable @code{reftex-default-bibliography}. |
| 5665 | @end itemize |
| 5666 | |
| 5667 | @noindent @b{Version 3.14} |
| 5668 | @itemize @bullet |
| 5669 | @item |
| 5670 | Selection buffers can be kept between selections: this is faster. |
| 5671 | See new variable @code{reftex-use-multiple-selection-buffers}. |
| 5672 | @item |
| 5673 | Prefix interpretation of reftex-view-crossref changed. |
| 5674 | @item |
| 5675 | Support for the @code{varioref} package (@kbd{v} key in selection |
| 5676 | buffer). |
| 5677 | @end itemize |
| 5678 | |
| 5679 | @noindent @b{Version 3.12} |
| 5680 | @itemize @bullet |
| 5681 | @item |
| 5682 | There are 3 new keymaps for customization: @code{reftex-toc-map}, |
| 5683 | @code{reftex-select-label-map}, @code{reftex-select-bib-map}. |
| 5684 | @item |
| 5685 | Refontification uses more standard font-lock stuff. |
| 5686 | @item |
| 5687 | When no BibTeX database files are specified, citations can also use |
| 5688 | @code{\bibitem} entries from a @code{thebibliography} environment. |
| 5689 | @end itemize |
| 5690 | |
| 5691 | @noindent @b{Version 3.11} |
| 5692 | @itemize @bullet |
| 5693 | @item |
| 5694 | Fixed bug which led to naked label in (e.g.) footnotes. |
| 5695 | @item |
| 5696 | Added scroll-other-window functions to RefTeX-Select. |
| 5697 | @end itemize |
| 5698 | |
| 5699 | @noindent @b{Version 3.10} |
| 5700 | @itemize @bullet |
| 5701 | @item |
| 5702 | Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19. |
| 5703 | @item |
| 5704 | Removed unimportant code which caused OS/2 Emacs to crash. |
| 5705 | @item |
| 5706 | All customization variables now accessible from menu. |
| 5707 | @end itemize |
| 5708 | |
| 5709 | @noindent @b{Version 3.07} |
| 5710 | @itemize @bullet |
| 5711 | @item |
| 5712 | @code{Ref} menu improved. |
| 5713 | @end itemize |
| 5714 | |
| 5715 | @noindent @b{Version 3.05} |
| 5716 | @itemize @bullet |
| 5717 | @item |
| 5718 | Compatibility code now first checks for XEmacs feature. |
| 5719 | @end itemize |
| 5720 | |
| 5721 | @noindent @b{Version 3.04} |
| 5722 | @itemize @bullet |
| 5723 | @item |
| 5724 | Fixed BUG in the @emph{xr} support. |
| 5725 | @end itemize |
| 5726 | |
| 5727 | @noindent @b{Version 3.03} |
| 5728 | @itemize @bullet |
| 5729 | @item |
| 5730 | Support for the LaTeX package @code{xr}, for inter-document |
| 5731 | references. |
| 5732 | @item |
| 5733 | A few (minor) Mule-related changes. |
| 5734 | @item |
| 5735 | Fixed bug which could cause @emph{huge} @file{.rel} files. |
| 5736 | @item |
| 5737 | Search for input and @file{.bib} files with recursive path definitions. |
| 5738 | @end itemize |
| 5739 | |
| 5740 | @noindent @b{Version 3.00} |
| 5741 | @itemize @bullet |
| 5742 | @item |
| 5743 | @b{Ref@TeX{}} should work better for very large projects: |
| 5744 | @item |
| 5745 | The new parser works without creating a master buffer. |
| 5746 | @item |
| 5747 | Rescanning can be limited to a part of a multifile document. |
| 5748 | @item |
| 5749 | Information from the parser can be stored in a file. |
| 5750 | @item |
| 5751 | @b{Ref@TeX{}} can deal with macros having a naked label as an argument. |
| 5752 | @item |
| 5753 | Macros may have white space and newlines between arguments. |
| 5754 | @item |
| 5755 | Multiple identical section headings no longer confuse |
| 5756 | @code{reftex-toc}. |
| 5757 | @item |
| 5758 | @b{Ref@TeX{}} should work correctly in combination with buffer-altering |
| 5759 | packages like outline, folding, x-symbol, iso-cvt, isotex, etc. |
| 5760 | @item |
| 5761 | All labeled environments discussed in @emph{The LaTeX Companion} by |
| 5762 | Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of |
| 5763 | @b{Ref@TeX{}}'s defaults. |
| 5764 | @end itemize |
| 5765 | |
| 5766 | @noindent @b{Version 2.17} |
| 5767 | @itemize @bullet |
| 5768 | @item |
| 5769 | Label prefix expands % escapes with current file name and other stuff. |
| 5770 | @item |
| 5771 | Citation format now with % escapes. This is not backward |
| 5772 | compatible! |
| 5773 | @item |
| 5774 | TEXINPUTS variable recognized when looking for input files. |
| 5775 | @item |
| 5776 | Context can be the nth argument of a macro. |
| 5777 | @item |
| 5778 | Searching in the select buffer is now possible (@kbd{C-s} and |
| 5779 | @kbd{C-r}). |
| 5780 | @item |
| 5781 | Display and derive-label can use two different context methods. |
| 5782 | @item |
| 5783 | AMSmath @code{xalignat} and @code{xxalignat} added. |
| 5784 | @end itemize |
| 5785 | |
| 5786 | @noindent @b{Version 2.14} |
| 5787 | @itemize @bullet |
| 5788 | @item |
| 5789 | Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with |
| 5790 | AUCTeX. |
| 5791 | @end itemize |
| 5792 | |
| 5793 | @noindent @b{Version 2.11} |
| 5794 | @itemize @bullet |
| 5795 | @item |
| 5796 | Submitted for inclusion to Emacs and XEmacs. |
| 5797 | @end itemize |
| 5798 | |
| 5799 | @noindent @b{Version 2.07} |
| 5800 | @itemize @bullet |
| 5801 | @item |
| 5802 | New functions @code{reftex-search-document}, |
| 5803 | @code{reftex-query-replace-document}. |
| 5804 | @end itemize |
| 5805 | |
| 5806 | @noindent @b{Version 2.05} |
| 5807 | @itemize @bullet |
| 5808 | @item |
| 5809 | Support for @file{custom.el}. |
| 5810 | @item |
| 5811 | New function @code{reftex-grep-document} (thanks to Stephen Eglen). |
| 5812 | @end itemize |
| 5813 | |
| 5814 | @noindent @b{Version 2.03} |
| 5815 | @itemize @bullet |
| 5816 | @item |
| 5817 | @code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to |
| 5818 | default environments. |
| 5819 | @item |
| 5820 | @code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari). |
| 5821 | @item |
| 5822 | New functions @code{reftex-arg-label}, @code{reftex-arg-ref}, |
| 5823 | @code{reftex-arg-cite}. |
| 5824 | @item |
| 5825 | Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is |
| 5826 | required. |
| 5827 | @item |
| 5828 | @code{reftex-add-to-label-alist} (to be called from AUCTeX style |
| 5829 | files). |
| 5830 | @item |
| 5831 | Finding context with a hook function. |
| 5832 | @item |
| 5833 | Sorting BibTeX entries (new variable: |
| 5834 | @code{reftex-sort-bibtex-matches}). |
| 5835 | @end itemize |
| 5836 | |
| 5837 | @noindent @b{Version 2.00} |
| 5838 | @itemize @bullet |
| 5839 | @item |
| 5840 | Labels can be derived from context (default for sections). |
| 5841 | @item |
| 5842 | Configuration of label insertion and label referencing revised. |
| 5843 | @item |
| 5844 | Crossref fields in BibTeX database entries. |
| 5845 | @item |
| 5846 | @code{reftex-toc} introduced (thanks to Stephen Eglen). |
| 5847 | @end itemize |
| 5848 | |
| 5849 | @noindent @b{Version 1.09} |
| 5850 | @itemize @bullet |
| 5851 | @item |
| 5852 | Support for @code{tex-main-file}, an analogue for |
| 5853 | @code{TeX-master}. |
| 5854 | @item |
| 5855 | MS-DOS support. |
| 5856 | @end itemize |
| 5857 | |
| 5858 | @noindent @b{Version 1.07} |
| 5859 | @itemize @bullet |
| 5860 | @item |
| 5861 | @b{Ref@TeX{}} gets its own menu. |
| 5862 | @end itemize |
| 5863 | |
| 5864 | @noindent @b{Version 1.05} |
| 5865 | @itemize @bullet |
| 5866 | @item |
| 5867 | XEmacs port. |
| 5868 | @end itemize |
| 5869 | |
| 5870 | @noindent @b{Version 1.04} |
| 5871 | @itemize @bullet |
| 5872 | @item |
| 5873 | Macros as wrappers, AMSTeX support, delayed context parsing for |
| 5874 | new labels. |
| 5875 | @end itemize |
| 5876 | @end ignore |
| 5877 | |
| 5878 | @noindent @b{Version 1.00} |
| 5879 | @itemize @bullet |
| 5880 | @item |
| 5881 | released on 7 Jan 1997. |
| 5882 | @end itemize |
| 5883 | |
| 5884 | @node GNU Free Documentation License, Index, Changes, Top |
| 5885 | @appendix GNU Free Documentation License |
| 5886 | @include doclicense.texi |
| 5887 | |
| 5888 | @node Index, , GNU Free Documentation License, Top |
| 5889 | @unnumbered Index |
| 5890 | @printindex cp |
| 5891 | |
| 5892 | @bye |