[Okular-devel] [PATCH] Re: how to invoke okular with inverse search with pdf?
Jochen.Trumpf at anu.edu.au
Mon Dec 28 10:26:39 CET 2009
On Saturday 26 December 2009 06:03:19 Albert Astals Cid wrote:
> Yes i could and want to commit it, just that i would like to ask you for a
> way to setup things so i can test the problem on my system and understand
> better what the patch does. Could you give me through a way to setup the
> files/programs needed to reproduce this behaviour?
OK. I am not sure how familiar you are with tex/latex, so I will start with
the basics. My apologies if this is wasting your time.
The macro package latex sits on top of the tex typesetting engine and provides
in essence a markup language to describe the structure and appearance of
documents. In a sense it is similar to html just without the focus on
hyperlinks. A document written in latex gets compiled into a page description
format so it can be viewed or printed. The most common formats for that are
dvi (somewhat superseded I dare say) and pdf (the more modern choice).
Since the description of the document (in a pure text document with latex
syntax) and the viewable/printable version (in dvi or pdf) are typically
handled by different programs, there is a need to "synchronise" between the
two formats to enable "forward search" (= click on a source line in the text
editor will jump to the corresponding area of the page in the dvi/pdf viewer)
and "inverse search" (= click somewhere into the page in the dvi/pdf viewer
will locate the corresponding source code in the editor).
There are several combinations of editors/viewers that will handle this to
varying degrees. My favourite combination is emacs plus okular. You can also
use kile, etc. More about this later.
The synchronization mechanism is provided by metadata, the format of which has
evolved somewhat over time.
The current way for latex<->dvi are so called "source specials". They are
particular byte sequences embedded into dvi files that carry information about
line numbers and source file names corresponding to symbols ("glyphs") on the
The current way for latex<->pdf is synctex. Here the metadata (in form of
"nodes" linking pdf page coordinates and line/column numbers plus source file
names) is compressed and stored in a separate file (.synctex.gz).
The tex compiler ("latex" for producing dvi resp. "pdflatex" for producing
pdf) needs to be told to generate the metadata with a command line switch:
"latex -src-specials test.tex" will produce test.dvi with embedded source
specials, resp. "pdflatex -synctex=1 test.tex" will produce test.pdf and
So the first thing you need is a modern tex distribution. I recommend
texlive-2008 (or 2009 if it is available for your OS). You won't need the
whole lot (it includes zillions of macro packages for all sorts of document
types) but only a basic install that gives you the latex and pdflatex
commands, basic fonts and basic macros. See http://www.tug.org/texlive/ for
instructions. Most up-to date linux distributions ship texlive packages. And
please don't hesitate to ask if in doubt about anything.
Inverse search is usually implemented as follows. Upon receiving a click on
the page the viewer determines the closest source reference from the metadata
and then calls the editor with a command line switch containing source file
name and line number. Upon receiving this the editor places the cursor into
that line. This creates the illusion that the page area in the viewer is
"linked" to the source code in the editor. If you then change something in the
source, you need to save the source file, run the tex compiler and then your
viewer should update automatically and show the changes.
Using emacs this is very simple: just install the emacs macro package auctex.
It contains all the necessary commands for interaction with the tex compiler
and the dvi/pdf viewer. If you want to go down that route please let me know
and I will send you an excerpt of my init file for emacs that works well in
conjunction with okular. Otherwise just use your favourite editor and invoke
the tex compiler from a command line.
As far as I can tell inverse search in okular now works very well for both dvi
(using source specials) and pdf (using synctex). You just need to configure
your editor and use shift plus left mouse click to invoke inverse search.
Now to the actual topic of this thread: forward search. Here the editor calls
the viewer either with a command line switch or via dbus (or any other IPC
mechanism). Typically, the editor provides the viewer with a line number and a
source file name and it is up to the viewer to locate a corresponding source
special or synctex link and set the viewport accordingly.
While this has been working quite well since quite some time for latex<->dvi
(using source specials) in okular, the corresponding code for latex<->pdf
(using synctex) was missing. This is what my patch provides.
Forward search can be invoked with the command line syntax
okular test.(dvi|pdf)#src:<line no.>test.tex
Note that there are no blanks between the file names and the other stuff and
that the dvi/pdf file and the source (.tex) file need to be in the same folder
for this syntax to work. You can use paths if you need to. This will cause
okular to jump to a part of the document that corresponds to the given line
no. in the source document.
Now, even if you use my patch that provides the basic metadata lookup for the
latex<->pdf using synctex case, there are still a couple of bugs that hinder
productive use of forward search. I'll explain that next.
The real power of inverse and forward search comes if you configure your
editor and your viewer in a way that no new program instance gets started if
the requested source or dvi/pdf file is already open. Then it really feels
like the viewer and the editor are magically linked and you get as close to
wysiwyg as you can with this sort of setup.
For emacs, this is done by using emacs server. The default editor
configuration for emacs that is shipped with okular already does this. You
just need to start the server from your emacs init file.
For okular, this is provided by the command line switch --unique that
relegates the file open command to a dbus call on an existing instance. This
is where the bugs are. Bug #205076 concerns the handling of the "#src:" syntax
in the case of a dbus call. I have commented in detail in the bug report
including a possible fix. Bug #205084 concerns a bug in the viewport update
where the document has been reloaded via dbus. Again, I have left detailed
comments in the bug report including a possible fix. This one requires
somebody with a deeper understanding of viewport handling to have a closer
So, summing up:
- get texlive-2008 (or 2009)
- use a good editor such as emacs plus auctex plus my init macros for
communication with okular (email me for the latter)
- patch okular
- test with a latex file
The easiest way to get a nontrivial latex file is to use one of the latex
documentation files that come with texlive. They are written in latex ("eat
your own dog food") ...
Puh, this was rather lengthy. Hope you didn't fall asleep in the meantime.
Please ask if any of this is still unclear.
More information about the Okular-devel