While writing in LaTeX, you often want to reference (through the \ref
macro) things just above or just below point. Some LaTeX packages
offer special macros that are always expanded in this sense (for
example, a macro \Next that expands into a \ref{LABEL} if the first
label macro after \Next is \label{LABEL}).
However, this is somewhat of an antipattern: it is a convenient
feature (because so often you want to refer to something close to
point), but it can cause serious headaches if you happen to
restructure the text where these references occur. It may be very
hard to notice that the reference you intended is now different
because a different \label than the one you intended to refer to
intervenes between the \Next macro and the item it should refer to.
The convenience provided by these macros is better delivered by your
text editor (ideally, GNU Emacs).
This functionality is what this package provides. There are three entry points (three interactive commands):
quick-latex-refquick-latex-ref-previousquick-latex-ref-next
If you want to refer to the first \label following point, call
quick-late-ref-next: the appropriate \ref macro will be inserted. The
opposite effect of course is obtained by quick-latex-ref-previous.
Note that these commands will retrieve the closest \label even if that
occurs in a hidden section (e.g. folded by outline-mode) or outside
the narrowed portion of the buffer.
Once you call any of these commands you actually enter a loop, whereby
you can “walk” up and down the \label macros in the buffer through the
characters you can set as the values of these two variables:
quick-latex-ref-previous-key(pby default)quick-latex-ref-next-key(nby default).
If you want to use k and j instead, for example, add this to your
configuration:
(setq quick-latex-ref-previous-key ?k
quick-latex-ref-next-key ?j)
All three of these commands can be called with the prefix argument, in
which case only the label itself (i.e., the argument of the \label
macro) is inserted at point. Furthermore, if the variable
quick-latex-ref-only-label-if-in-argument is set to t (as it is by
default), only the label (and not a full \ref macro) is inserted if
point is already inside the braces that determine the argument of a
\ref macro.
As you can see in the gif, \label macros that are in comments are
completely ignored, and so are the ones that have a blank argument
(that is, have no label). If the variable
quick-latex-ref-show-context is t (as per default), the context of the
current \label candidate is shown in the echo area, to help you
determine whether that is indeed the label you are interested in. The
context is the three lines (visual lines, if you are in
visual-line-mode) where the candidate \label is in.
The value of quick-latex-ref-show-context is ignored if the value of
quick-latex-ref-move-point is set to t (default is nil), in which case
the point in the buffer will move along with your search, rendering
the echoing of the label’s context in the echo area useless. If you
set quick-latex-ref-move-point to t, point will return where it was
when you entered the loop, when you exit in any way other than by
choosing to go to the selected label (more on this below).
The faces that highlight the expression at point (either the label or
the whole \ref macro) and the current target \label macro are defined
as the values of quick-latex-ref-at-point and
quick-latex-current-target respectively. By default, they are the
same face with which the current theme treats the active region.
When you have found the label you were looking for, you can select it
and exit the loop by entering the character that is the value of
quick-latex-ref-select-key (?\s by default, which corresponds to
white space).
A fourth action you can take while being in the loop, through the
character specified as the value of quick-latex-ref-goto-key (. by
default). This action will do the following things:
- move point to the buffer position corresponding to the currently selected label;
- exit the loop;
- undo any insertion that was done after entering the loop you just exited.
While in the loop, entering any self-insertable character that is not
the value of quick-latex-ref-previous-key, quick-latex-ref-next-key,
quick-latex-ref-select-key or quick-latex-ref-goto-key will have the
same effect as accepting the currently selected label. Any other
action (for example, keyboard-quit, to which C-g is bound by default),
will leave or return point to the position it was when the loop was
entered and any modification done to the buffer since is effectively
undone.
Remember that whenever the loop is entered with any of the three above interactive commands, the position of point is pushed to the mark ring, so that you can easily return to that point after exiting the loop somewhere else in the buffer.