[Okular-devel] [PATCH] Re: how to invoke okular with inverse search with pdf?

[Jochen Trumpf]

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 
page.
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 
test.synctex.gz.  

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 
look.

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.

Cheers,
Jochen