Inverse Search with Xdvi(k)

Please send corrections and suggestions to Stefan Ulrich.

Introduction

• A mouse click (Ctrl-Button1 by default) in the xdvi window can open an editor with the corresponding place in the (La)TeX source (also called `reverse search'), and
• xdvi can jump to (and visually highlight) a position in the DVI file that corresponds to a certain line number in the (La)TeX source file (`forward search').

This functionality is supported by xdvi(k) versions 22.38 and upwards. It uses so-called `source specials' in the DVI file, which can be inserted via a macro package or a command-line option to the (La)TeX program (executable).

The macro packages are available as srctex.sty (for plain TeX) or srcltx.sty (for LaTeX) from CTAN:macros/latex/contrib/srcltx/.

The (La)TeX version that comes with teTeX-2.0 provides a command line option `-src' to insert these specials automatically. While the macro version might interact badly with other macro packages, the option for the (La)TeX executable should be more robust. However, both versions may affect the line breaks of your document, so it's generally a good idea to disable source specials for the final version of the document.

(X)Emacs and AUCTeX

If you are not using AUCTeX, please see the instructions here.

Vim v6.0 upwards

1. Reverse search

   As `editor' option/X resource for xdvi(k), use:

         gvim --servername xdvi --remote +%l %f
         

   (The option `--servername xdvi' will cause gvim to run a dedicated instance for the files opened by xdvi.)
2. Forward search

   The following information was taken from http://vim.sourceforge.net/tips/tip.php?tip_id=225: From the window with the `master' TeX file (the file with the same base name as the DVI file), you can use a vim command like (all in one line):

         :execute "!xdvi -sourceposition " . line(".") . expand("%") . " " .
             expand("%:r") . ".dvi"
         

   You can also assign this command to a key. An example for more sophisticated configuration settings is available here.

Nedit and nc

1. Reverse search
   • Start nedit with the -server option.
   • As `editor' option/X resource for xdvi(k), use:

           nc -noask +%l %f
           

2. Forward search

   Nedit has a fairly powerful macro language that can be used to implement forward search. The following macro might serve as a starting point - it's not perfect in that it doesn't work with included files. Suggestions on this are welcome.

   define forward_search {
        dvifile = $file_path substring($file_name, 0, \
                  search_string($file_name, "\\.[Tt][Ee][Xx]$", \
                                0, "regex")) ".dvi"
        srcspec = "\"" $line " " $file_name "\""
   
        ### If xdvi is not running yet, we use `screen' to
        ### explicitly detach it from the controlling terminal (xdvi
        ### forks to put itself in the background, but doesn't
        ### detach from the terminal); otherwise, nedit would wait
        ### forever for xdvi to terminate.
        if (search_string(shell_command("ps x", ""), \
            "^.*xdvi.* " dvifile "$", 0, "regex") == -1 )
        shell_command("screen -m -d xdvi " dvifile "; sleep 1", "")
        shell_command("xdvi -sourceposition " srcspec " " dvifile, "")
   }
         

   Put the above definition into your Nedit macro file (~/.neditmacros by default), then launch Nedit and open the menu

         Preferences > Default Settings > Customize Menus > Macro Menu
         

   Enter a name for your macro, and as macro command enter: forward_search(). You may also want to define an accelerator key for the menu entry as well as a keyboard shortcut (called "mnemonic" in Nedit).

Other editors

All above examples are with editors that provide a `server mode', which allows you to load a new file into the already running editor instance. You can also use reverse search with editors that don't have this functionality, with the slight disadvantage that a new instance of the editor will be started for every reverse search. One thing to keep in mind is that non-X editors should be started in a separate window, to avoid clobbering the editor display with xdvi's diagnostic output. To do this, pass the editor command to the -e option of an xterm, e.g. for classic vi, use the following `editor' option/X resource for xdvi(k):

      xterm -e vi +%l %f
      

If you set the editor via the VISUAL or EDITOR resources, xdvi will pass it to an `xterm -e' command automatically.

For X editors, just use the editor name, e.g. (for xjed):

      xdvi -editor xjed test.dvi
      

      export XEDITOR=xjed