From f181466634e87254d81d161ff8b81996d8d16d8e Mon Sep 17 00:00:00 2001 From: Arash Esbati Date: Tue, 7 Jan 2025 22:02:13 +0100 Subject: [PATCH] Update RefTeX manual * doc/misc/reftex.texi: (Builtin Label Environments): Mention supported LaTeX packages ctable, minted and listings. (Reference Styles): Update the supported reference styles and the corresponding macros. (Citation Styles): Mention support for biblatex package. (Language Support): Describe usage of non-ASCII characters in the LaTeX \label definition. (Style Files): Mention biblatex.el as well. (Options - Defining Label Environments): Add entry for `reftex-label-regexps' option. Other minor improvements. (cherry picked from commit 8d687695c528e4edb04cca5602470d349e333258) --- doc/misc/reftex.texi | 214 +++++++++++++++++++++++++++++-------------- 1 file changed, 145 insertions(+), 69 deletions(-) diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi index 20e9b15e94e..5973140734f 100644 --- a/doc/misc/reftex.texi +++ b/doc/misc/reftex.texi @@ -259,8 +259,8 @@ To turn @RefTeX{} Mode on and off in a particular buffer, use LaTeX files, add the following lines to your @file{.emacs} file: @example -(add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode -(add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode +(add-hook 'LaTeX-mode-hook #'turn-on-reftex) ; with AUCTeX LaTeX mode +(add-hook 'latex-mode-hook #'turn-on-reftex) ; with Emacs latex mode @end example That's all! @@ -333,11 +333,11 @@ Which labels are created how is configurable with the variable @code{reftex-insert-label-flags}. @item -@b{Referencing Labels}@* To make a reference, type @kbd{C-c )} -(@code{reftex-reference}). This shows an outline of the document with -all labels of a certain type (figure, equation,...) and some label -context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro -into the original buffer. +@b{Referencing Labels}@* +To make a reference, type @kbd{C-c )} (@code{reftex-reference}). This +shows an outline of the document with all labels of a certain type +(figure, equation,...) and some label context. Selecting a label +inserts a @code{\ref@{@var{label}@}} macro into the original buffer. @end itemize @item @@ -352,12 +352,11 @@ different macros). @item @b{Index Support}@* -@RefTeX{} helps to enter index entries. It also compiles all -entries into an alphabetically sorted @file{*Index*} buffer which you -can use to check and edit the entries. @RefTeX{} knows about the -standard index macros and can be configured to recognize any additional -macros you have defined (@code{reftex-index-macros}). Multiple indices -are supported. +@RefTeX{} helps to enter index entries. It also compiles all entries +into an alphabetically sorted @file{*Index*} buffer which you can use to +check and edit the entries. @RefTeX{} knows about the standard index +macros and can be configured to recognize any additional macros you have +defined (@code{reftex-index-macros}). Multiple indices are supported. @itemize @bullet @item @@ -383,7 +382,8 @@ all entries. @end itemize @page -@item @b{Viewing Cross-References}@* +@item +@b{Viewing Cross-References}@* When point is on the @var{key} argument of a cross-referencing macro (@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, and variations) or inside a @BibTeX{} database entry, you @@ -403,20 +403,21 @@ all parts of the document, and across document borders (@file{xr.sty}). @item -@b{Document Parsing}@* @RefTeX{} needs to parse the document in -order to find labels and other information. It does it automatically -once and updates its list internally when @code{reftex-label} and -@code{reftex-index} are used. To enforce reparsing, call any of the -commands described above with a raw @kbd{C-u} prefix, or press the -@kbd{r} key in the label selection buffer, the table of contents -buffer, or the index buffer. +@b{Document Parsing}@* +@RefTeX{} needs to parse the document in order to find labels and other +information. It does it automatically once and updates its list +internally when @code{reftex-label} and @code{reftex-index} are used. +To enforce reparsing, call any of the commands described above with a +raw @kbd{C-u} prefix, or press the @kbd{r} key in the label selection +buffer, the table of contents buffer, or the index buffer. @item -@b{@AUCTeX{}} @* If your major @LaTeX{} mode is @AUCTeX{}, @RefTeX{} can -cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). @AUCTeX{} -contains style files which trigger appropriate settings in -@RefTeX{}, so that for many of the popular @LaTeX{} packages no -additional customizations will be necessary. +@b{@AUCTeX{}}@* +If your major @LaTeX{} mode is @AUCTeX{}, @RefTeX{} can cooperate with +it (see variable @code{reftex-plug-into-AUCTeX}). @AUCTeX{} contains +style files which trigger appropriate settings in @RefTeX{}, so that for +many of the popular @LaTeX{} packages no additional customizations will +be necessary. @item @b{Useful Settings}@* @@ -438,13 +439,14 @@ If you have a large number of macros defined, you may want to write an @AUCTeX{} style file to support them with both @AUCTeX{} and @RefTeX{}. -@item @b{Where Next?}@* Go ahead and use @RefTeX{}. Use its menus -until you have picked up the key bindings. For an overview of what you -can do in each of the different special buffers, press @kbd{?}. Read -the manual if you get stuck, or if you are curious what else might be -available. The first part of the manual explains in -a tutorial way how to use and customize @RefTeX{}. The second -part is a command and variable reference. +@item +@b{Where Next?}@* +Go ahead and use @RefTeX{}. Use its menus until you have picked up the +key bindings. For an overview of what you can do in each of the +different special buffers, press @kbd{?}. Read the manual if you get +stuck, or if you are curious what else might be available. The first +part of the manual explains in a tutorial way how to use and customize +@RefTeX{}. The second part is a command and variable reference. @end enumerate @node Table of Contents @@ -1066,21 +1068,36 @@ the @LaTeX{} core stuff) @code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations} (from AMS-@LaTeX{}'s @file{amsmath.sty} package) @item -@cindex @code{endnote}, LaTeX package -@cindex LaTeX packages, @code{endnote} -@cindex @code{\endnote}, LaTeX macro -the @code{\endnote} macro (from @file{endnotes.sty}) -@item @cindex @code{fancybox}, LaTeX package @cindex LaTeX packages, @code{fancybox} @cindex @code{Beqnarray}, LaTeX environment @code{Beqnarray} (@file{fancybox.sty}) @item +@cindex @code{ctable}, LaTeX package +@cindex LaTeX packages, @code{ctable} +@cindex @code{\ctable}, LaTeX macro +the @code{\ctable} macro (from @file{ctable.sty}) +@item +@cindex @code{endnote}, LaTeX package +@cindex LaTeX packages, @code{endnote} +@cindex @code{\endnote}, LaTeX macro +the @code{\endnote} macro (from @file{endnotes.sty}) +@item @cindex @code{floatfig}, LaTeX package @cindex LaTeX packages, @code{floatfig} @cindex @code{floatingfig}, LaTeX environment @code{floatingfig} (@file{floatfig.sty}) @item +@cindex @code{minted}, LaTeX package +@cindex LaTeX packages, @code{minted} +@cindex @code{listing}, LaTeX environment +@code{listing} (@file{minted.sty}) +@item +@cindex @code{listings}, LaTeX package +@cindex LaTeX packages, @code{listings} +@cindex @code{lstlisting}, LaTeX environment +@code{lstlisting} (@file{listings.sty}) +@item @cindex @code{longtable}, LaTeX package @cindex LaTeX packages, @code{longtable} @cindex @code{longtable}, LaTeX environment @@ -1104,7 +1121,7 @@ the @code{\endnote} macro (from @file{endnotes.sty}) @cindex @code{sidewaystable}, LaTeX environment @code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty}) @item -@cindex @code{subfig}, LaTeX package +@cindex @code{subfigure}, LaTeX package @cindex LaTeX packages, @code{subfigure} @cindex @code{subfigure}, LaTeX environment @cindex @code{subfigure*}, LaTeX environment @@ -1210,10 +1227,10 @@ automatically create labels for the new environments. @lisp (add-hook 'LaTeX-mode-hook - (lambda () - (LaTeX-add-environments - '("axiom" LaTeX-env-label) - '("theorem" LaTeX-env-label)))) + (lambda () + (LaTeX-add-environments + '("axiom" LaTeX-env-label) + '("theorem" LaTeX-env-label)))) @end lisp @@ -1599,12 +1616,15 @@ convenient way. @RefTeX{} comes equipped with a set of so-called reference styles where each relates to one or more reference macros. The standard macros -@samp{\ref} and @samp{\pageref} or provided by the ``Default'' style. -The ``Varioref'' style offers macros for the @samp{varioref} @LaTeX{} -package (@samp{\vref}, @samp{\Vref}, @samp{\Ref}, @samp{\vpageref}), -``Fancyref'' for the @samp{fancyref} package (@samp{\fref}, -@samp{\Fref}) and ``Hyperref'' for the @samp{hyperref} package -(@samp{\autoref}, @samp{\autopageref}). +@samp{\ref}, @samp{\Ref}, @samp{\footref} and @samp{\pageref} are +provided by the ``Default'' style. The ``Varioref'' style offers macros +for the @samp{varioref} @LaTeX{} package (@samp{\vref}, @samp{\Vref}, +and @samp{\vpageref}), ``Fancyref'' for the @samp{fancyref} package +(@samp{\fref}, @samp{\Fref}), ``Hyperref'' for the @samp{hyperref} +package (@samp{\autoref}, @samp{\autopageref}), ``Cleveref'' for the +@samp{cleveref} package (@samp{\cref}, @samp{\Cref}, @samp{\cpageref} +and @samp{\Cpageref}) and ``AMSmath'' for the @samp{amsmath} package +(@samp{\eqref}). @vindex reftex-ref-style-default-list A style can be toggled by selecting the respective entry in the @@ -1885,11 +1905,13 @@ buffers by adding the following expression to your init file: @node Citation Styles @section Citation Styles @cindex Citation styles +@cindex Citation styles, @code{biblatex} @cindex Citation styles, @code{natbib} @cindex Citation styles, @code{harvard} @cindex Citation styles, @code{chicago} @cindex Citation styles, @code{jurabib} @cindex Citation styles, @ConTeXt{} +@cindex @code{biblatex}, citation style @cindex @code{natbib}, citation style @cindex @code{harvard}, citation style @cindex @code{chicago}, citation style @@ -1903,12 +1925,12 @@ citations as used in many natural sciences, a variety of packages has been developed which define derived forms of the @code{\cite} macro. @RefTeX{} can be configured to produce these citation macros as well by setting the variable @code{reftex-cite-format}. For the most commonly -used @LaTeX{} packages (@code{natbib}, @code{harvard}, @code{chicago}, -@code{jurabib}) and for @ConTeXt{} this may be done from the menu, under -@code{Ref->Citation Styles}. Since there are usually several macros to -create the citations, executing @code{reftex-citation} (@kbd{C-c [}) -starts by prompting for the correct macro. For the Natbib style, this -looks like this: +used @LaTeX{} packages (@code{biblatex}, @code{natbib}, @code{harvard}, +@code{chicago}, @code{jurabib}) and for @ConTeXt{} this may be done from +the menu, under @code{Ref->Citation Styles}. Since there are usually +several macros to create the citations, executing @code{reftex-citation} +(@kbd{C-c [}) starts by prompting for the correct macro. For the Natbib +style, this looks like this: @example SELECT A CITATION FORMAT @@ -1925,6 +1947,31 @@ SELECT A CITATION FORMAT [y] \citeyear@{%l@} @end example +@noindent +And for the Biblatex style, it looks like this: + +@example +SELECT A CITATION FORMAT + +[^M] \cite[][]@{%l@} +[C] \cite*[][]@{%l@} +[t] \textcite[][]@{%l@} +[T] \textcite*[][]@{%l@} +[p] \parencite[][]@{%l@} +[P] \parencite*[][]@{%l@} +[f] \footcite[][]@{%l@} +[s] \smartcite[][]@{%l@} +[u] \autocite[][]@{%l@} +[U] \autocite*[][]@{%l@} +[a] \citeauthor@{%l@} +[A] \citeauthor*@{%l@} +[i] \citetitle@{%l@} +[I] \citetitle*@{%l@} +[y] \citeyear@{%l@} +[Y] \citeyear*@{%l@} +[n] \nocite@{%l@} +@end example + @vindex reftex-cite-prompt-optional-args If citation formats contain empty pairs of square brackets, @RefTeX{} will prompt for values of these optional arguments if you call the @@ -1942,6 +1989,13 @@ To make one of these styles the default, customize the variable (setq reftex-cite-format 'natbib) @end lisp +@noindent +Or this if you prefer the biblatex package: + +@lisp +(setq reftex-cite-format 'biblatex) +@end lisp + You can also use @AUCTeX{} style files to automatically set the citation style based on the @code{usepackage} commands in a given document. @xref{Style Files}, for information on how to set up the style @@ -2909,23 +2963,28 @@ settings work well for English. If you are writing in a different language, the following hints may be useful: @itemize @bullet -@item @vindex reftex-derive-label-parameters @vindex reftex-abbrev-parameters +@item The mechanism to derive a label from context includes the abbreviation of words and omission of unimportant words. These mechanisms may have to be changed for other languages. See the variables @code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}. -@item @vindex reftex-translate-to-ascii-function @vindex reftex-label-illegal-re -Also, when a label is derived from context, @RefTeX{} clears the -context string from non-ASCII characters in order to make a valid label. -If there should ever be a version of @TeX{} which allows extended -characters @emph{in labels}, then we will have to look at the -variables @code{reftex-translate-to-ascii-function} and -@code{reftex-label-illegal-re}. +@item +Also, when a label is derived from context, @RefTeX{} clears the context +string from non-ASCII characters in order to make a label. Starting +with @LaTeX{} release 2019-10-01, non-ASCII characters are allowed in +@LaTeX{}'s @code{\label}/@code{\ref} mechanism. If you want to change +@RefTeX{}'s behavior and allow extended characters in labels, then take +a look at the variables @code{reftex-translate-to-ascii-function} and +@code{reftex-label-illegal-re}. The following example allows any +letters and digits (among other characters) in the label definition: +@lisp +(setq reftex-label-illegal-re "[^-[:alnum:]_+=:;,.]") +@end lisp @item When a label is referenced, @RefTeX{} looks at the word before point @@ -3025,7 +3084,7 @@ the new extension must also be known to @AUCTeX{} via the variable (setq reftex-file-extensions '(("nw" "tex" ".tex" ".ltx") ("bib" ".bib"))) (setq TeX-file-extensions - '( "nw" "tex" "sty" "cls" "ltx" "texi" "texinfo")) + '("nw" "tex" "sty" "cls" "ltx" "texi" "texinfo")) @end lisp @node Optimizations @@ -3289,11 +3348,11 @@ Labels}). Style files are Emacs Lisp files which are evaluated by @AUCTeX{} in association with the @code{\documentclass} and @code{\usepackage} commands of a document (@pxref{Style Files,,,auctex}). Support for -@RefTeX{} in such a style file is useful when the @LaTeX{} style -defines macros or environments connected with labels, citations, or the -index. Many style files (e.g., @file{amsmath.el} or @file{natbib.el}) -distributed with @AUCTeX{} already support @RefTeX{} in this -way. +@RefTeX{} in such a style file is useful when the @LaTeX{} style defines +macros or environments connected with labels, citations, or the index. +Many style files (e.g., @file{amsmath.el}, @file{natbib.el} or +@file{biblatex.el}) distributed with @AUCTeX{} already support @RefTeX{} +in this way. Before calling a @RefTeX{} function, the style hook should always test for the availability of the function, so that the style file will @@ -4127,6 +4186,23 @@ spliced into the list. However, builtin defaults should normally be set with the variable @code{reftex-default-label-alist-entries}. @end defopt +@defopt reftex-label-regexps +List of regular expressions matching @samp{\label} definitions. The +default value matches usual @samp{\label@{@dots{}@}} definitions and key +value style @samp{[@dots{}, label = @{@dots{}@}, @dots{}]} label +definitions. The regular expression for key value style explicitly +looks for environments provided by the packages @code{listings} +(@code{lstlisting}), @code{beamer} (@code{frame}), @code{breqn} +(@code{dmath}, @code{dseries}, @code{dgroup}, @code{darray}) and the +macro @code{\ctable} provided by the package of the same name. + +It is assumed that the regexp group 1 matches the label text, so you +have to define it using @samp{\(?1:...\)} when adding new regexps. + +When changed from Lisp, make sure to call +@code{reftex-compile-variables} afterwards to make the change effective. +@end defopt + @defopt reftex-section-prefixes Prefixes for section labels. When the label prefix given in an entry in @code{reftex-label-alist} contains @samp{%S}, this list is used to -- 2.39.5