auctex: I/O Correlation
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'. 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))))