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

[Albert Astals Cid]

Jochen did you receive my mail in one of the bugs asking for files to 
reproduce it?

Albert

A Dilluns 28 Desembre 2009 09:26:39, Jochen Trumpf va escriure:
> 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
> _______________________________________________
> Okular-devel mailing list
> Okular-devel at kde.org
> https://mail.kde.org/mailman/listinfo/okular-devel
>