Skip to main content

4.2.2 Forward and Inverse Search

Forward and inverse search refer to the correlation between the document source in the editor and the typeset document in the viewer. Forward search allows you to jump to the place in the previewed document corresponding to a certain line in the document source and inverse search vice versa.

AUCTeX supports three methods for forward and inverse search: source specials (only DVI output), the pdfsync LaTeX package (only PDF output) and SyncTeX (any type of output). If you want to make use of forward and inverse searching with source specials or SyncTeX, switch on TeX-source-correlate-mode. See Processor Options, on how to do that. The use of the pdfsync package is detected automatically if document parsing is enabled. Customize the variable TeX-source-correlate-method to select the method to use.

user option TeX-source-correlate-method​

Method to use for enabling forward and inverse search. This can be ‘source-specials’ if source specials should be used, ‘synctex’ if SyncTeX should be used, or ‘auto’ if AUCTeX should decide.

When the variable is set to ‘auto’, AUCTeX will always use SyncTeX if your latex processor supports it, source specials otherwise. You must make sure your viewer supports the same method.

It is also possible to specify a different method depending on the output, either DVI or PDF, by setting the variable to an alist of the kind

((dvi . <source-specials or synctex>)  (pdf . <source-specials or synctex>))

in which the CDR of each entry is a symbol specifying the method to be used in the corresponding mode. The default value of the variable is

((dvi . source-specials)  (pdf . synctex))

which is compatible with the majority of viewers.

Forward search happens automatically upon calling the viewer, e.g. by typing C-c C-v (TeX-view). This will open the viewer or bring it to front and display the output page corresponding to the position of point in the source file. AUCTeX will automatically pass the necessary command line options to the viewer for this to happen.

Upon opening the viewer you will be asked if you want to start a server process (Gnuserv or Emacs server) which is necessary for inverse search. This happens only if there is no server running already. You can customize the variable TeX-source-correlate-start-server to inhibit the question and always or never start the server respectively.

user option TeX-source-correlate-start-server​

If TeX-source-correlate-mode is active and a viewer is invoked, the default behavior is to ask if a server process should be started. Set this variable to t if the question should be inhibited and the server should always be started. Set it to nil if the server should never be started. Inverse search will not be available in the latter case.

Inverse search, i.e. jumping to the part of your document source in Emacs corresponding to a certain position in the viewer, is triggered from the viewer, typically by a mouse click. Refer to the documentation of your viewer to find out how it has to be configured and what you have to do exactly. In xdvi you normally have to use C-down-mouse-1.

Note that inverse search with the Evince PDF viewer or its MATE fork Atril might fail in raising the Emacs frame after updating point in your document’s buffer. There is simply no way to raise the Emacs frame reliably accross different operating systems and different window managers with their different focus stealing policies. If the Emacs frame is not raised after performing an inverse search from Evince or Atril, you can customize the following option.

user option TeX-raise-frame-function​

A function that will be called after performing an inverse search from Evince or Atril in order to raise the current Emacs frame.

If your Emacs frame is already raised in that situation, just leave this variable set to its default value raise-frame. Otherwise, here are some alternative settings that work for some users.

;; Alternative 1: For some users, `x-focus-frame' works. (setq TeX-raise-frame-function #'x-focus-frame)  ;; Alternative 2: Under GNOME 3.20 (and probably others), it ;; seems some focus stealing prevention policy prohibits that ;; some window gets the focus immediately after the user has ;; clicked in some other window.  Here waiting a bit before ;; issuing the request seems to work. (setq TeX-raise-frame-function       (lambda ()     (run-at-time 0.5 nil #'x-focus-frame)))  ;; Alternative 3: Use the external wmctrl tool in order to ;; force Emacs into the focus. (setq TeX-raise-frame-function       (lambda ()  (call-process    "wmctrl" nil nil nil "-i" "-R"      (frame-parameter (selected-frame) 'outer-window-id))))