
Overview
------------------------------------------------------------------------

This directory includes QtDBus Proxies for Evince. They were initially 
generated by using the qdbusxml2cpp utility on the evince Daemon and 
Window intefaces. The Daemon interface was obtained using this command:

dbus-send --session --type=method_call --print-reply \
  --dest=org.gnome.evince.Daemon /org/gnome/evince/Daemon \
  org.freedesktop.DBus.Introspectable.Introspect

The Window interface was obtained from the introspection_xml[] static
in ev_window.c (from the evince source code).

We are maintaining these interfaces manually now because (a) there
was a problem marshalling the point structure which we couldn't
work around; and (b) we need to modify the Window interface to 
deal with the fact that pre 2.9.1 versions of evince don't include 
a timestamp parameter.

Synctex Version History
-----------------------------------------------------------------------

2.31.5 -- introduced
2.31.6 -- updated synctex parser
2.91.0 -- add timestamp to SyncView & fix crash when reverse search fails
2.91.3 -- add timestamp to SyncSource signal
3.1.90 -- update parser to 1.16
3.3.20 -- update parser to 1.17 (more liberal path parsing)

Notes
-----------------------------------------------------------------------

- The addition of the timestamp parameter in 2.91.* creates a requirement
that this parameter be excluded from dBus calls in these versions and prior 
(see: https://bugzilla.gnome.org/show_bug.cgi?id=632313).

   NOTE: We attempted to modify our Qt DBus bindings to call the earlier
   version of the API however initial testing of this against Evince 2.32.0
   did not work correctly. This attempt is on the gnome2-synctex branch if
   we want to experiment further.

   NOTE: We also attempted to do a lightweight version of syncing based
   on passing the -i parameter to evince. This worked only for when the
   document wasn't open yet so didn't really buy us much. This attempt is
   on the gnome2-pagesync branch if we want to experiment further.

- It has been noted that in Synctex parser versions < 1.17 that there is a 
requirement of including ./ in paths. For example see:
http://jlebl.wordpress.com/2011/01/13/vim-evince-and-forward-and-backward-latex-synctex-search/
We pass full paths in to evince and in our own testing on Evince 3.2.0 we
have not observed this problem (perhaps addressed in 1.16?). There are
some notes about TexLive 2011 -- perhaps the issue only occurs when running
against synctex files created by TexLive 2011? (not yet in Ubuntu 12.04)
 
- If for some reason the 1.16 parser is enough to overcome the issue then
we should be OK, as mainstream distros (Debian, Ubuntu, and Fedora) all had
evince 3.2 as the first appearance in their distros (none had 2.91.*). See 
distro notes below. 
 
- Here are some additional notes on the changes made to the synctex parser 
regarding path handling:
http://ftp.tug.org/svn/texlive/trunk/Build/source/texk/web2c/synctexdir/synctex_parser_readme.txt?view=markup

- We've also discovered some other differences across versions highlighted in this thread: http://comments.gmane.org/gmane.emacs.auctex.general/4434. See particularly this comment:

Mandar, I also checked when the needed Evince Daemon DBUS service was
introduced.  It was around Evince version 2.30, but the API changed
several times before 3.0.0.  Most importantly, before 3.0 you couldn't
spawn a new evince instance via DBUS, which means AUCTeX would need to
check if evince is running via DBUS, spawn a new instance via the
command line if not, and then sync the view again via DBUS.  Another
major API incompatibility is that until 2.91.3 (an unstable release) you
needed to provide the local path to the document, and now evince wants a
URI.  All in all, I think it's not worth the complexity to support the
unstable pre-3.0 evince DBUS API.


Evince Versions in Distributions
-----------------------------------------------------------------------

NOTE: Neither Ubuntu nor Fedora are shipping TexLive 2011 as of their
most current versions (12.04 and 16 respectively). This means that if
there is a problem confined concurrent use of Evince < 3.3.20 and 
TexLive >= 2011 that no user would see it in the default configuration
(they'd have to have installed TexLive 2011 directly)

Ubuntu

- 10.04 -- 2.30.3 (no synctex)
- 10.10 -- 2.32.0 (first synctex)
- 11.04 -- 2.32.0
- 11.10 -- 3.2.0 (timestamp params)
- 12.04 -- 3.4.0 (new 1.17 file parsing)

Debian

- Debian 6 -- 2.30.3 (no synctex)
- Wheezy   -- 3.2.1

Fedora

- Fedora 13 -- 2.30.3 (no synctex)
- Fedora 14 -- 2.32 (first synctex)
- Fedora 15 -- 2.91.90 (timestamp for SyncView but NOT for SyncSource)
- Fedora 16 -- 3.20 (timestamp also in SyncSource)
- Fedora 17 -- 3.4.0 (new 1.17 file parsing)


