VIM-LaTeX Modification: Forward Searching in OS X

UPDATE 3: If it doesn't seem like commands are launching from within Vim, check out my post on setting PATH in Vim. In particular, if you are using the nascent MacVim, checking the "Launch Vim processes in a login shell" preference may fix your problems.

UPDATE 2: I've updated the patch file to fix a few bugs in my original implementation (thanks to Ross M. Richardson for the help!). This version supports forward searching from multi-file projects. By the way, if you didn't know, if you have a project with multiple files where the main LaTeX document is called my_latex_file.tex, you should create a dummy file called my_latex_file.latexmain in the same directory. That way, VIM-LaTeX will know to run its compiler and viewer on the main file and not on any of the smaller constituent files.

UPDATE 1: Skim 0.6 and up supports spell checking of a PDF. This is a strange feature of a PDF viewer since Skim does not allow you to edit the PDF text directly. However, it makes a lot of sense when inverse searches are supported. After doing Shift+Command+CLICK on the misspelled word, the TeX editor will open up near the line of TeX where the word is found.

I have already commented on doing inverse searches (or backward searches) in Vim on OS X. However, I have not handled forward searches. Ross M. Richardson offers a hack for doing forward searches into PDFView; however, it's clear that while this is a hack it is certainly not a lifehack. What I really want is a version of VIM-LaTeX that supports using PDFView, Skim, TeXniscope, or any UNIX shell script as a forward-search-compatible viewer.

The script I presented in an earlier post makes backward searches compatible in nearly any PDF/DVI viewer. Now, I just need to hack compiler.vim to do the reverse. I did this by modifying the Tex_ViewLaTeX and Tex_ForwardSearchLaTeX functions from the 20060325 release of VIM-LaTeX. You can find my changes in VIM-LaTeX-osx-inverse-search-compiler.patch. To apply the patch, go into your ~/.vim/ftplugin/latex-suite/ directory, backup your old compiler.vim file, and try

patch -p0 < VIM-LaTeX-osx-inverse-search-compiler.patch

Of course, you should either drop the patch file into that directory or change the patch command so it has the full path to the patch. Now, all you need to do is configure your ~/.vimrc and you'll be able to use \lv for viewing and \ls for forward searches.

OS X Applications: Say that I want to use Preview to view PostScript files, TeXniscope to view DVI files, and Skim to view PDF files (note that both TeXniscope and Skim can open all of these, but only TeXniscope supports DVI source specials). In that case, I could put these lines in my ~/.vimrc file:

let g:Tex_ViewRule_ps = 'Preview'
let g:Tex_ViewRule_pdf = 'Skim'
let g:Tex_ViewRule_dvi = 'TeXniscope'

Now, VIM-LaTeX will use these whenever \lv (for viewing) or \ls (for forward search) are used. That's right, it will do forward searches with these OS X applications (well, Skim and TeXniscope)! That's easy enough.

UNIX Viewer Scripts: Now, let's say I wanted to use the skim and texniscope scripts that I built earlier. In this case, I use the following in my ~/.vimrc file:

let g:Tex_TreatMacViewerAsUNIX = 1
let g:Tex_ExecuteUNIXViewerInForeground = 1
let g:Tex_ViewRule_ps = 'skim'
let g:Tex_ViewRule_pdf = 'skim'
let g:Tex_ViewRule_dvi = 'texniscope'

That g:Tex_TreatMaxViewerAsUNIX tells VIM-LaTeX not to use open -a to open the viewer. The g:Tex_ExecuteUNIXViewerInForeground gets rid of the & appended to the end of the execution strings used by VIM-LaTeX. For some reason, this option needs to be set to get UNIX viewers to work in MacVim.

Empty Viewer Scripts and Other Stuff: As before, if those ViewRule variables are set to empty values (i.e., ''), open -a will be used. On the other hand, if g:Tex_TreatMacViewerAsUNIX is set, VIM-LaTeX will act like it does on a UNIX machine, and xdvi, xdvik, and kdvi can be used. These three DVI viewers are handled specially. Any other UNIX script should follow the convention:

script "%target_file" %line "%source_file"

where script is the UNIX command, %target_file is the main PDF, PS, or DVI file to open, and %line is the line in the TeX source file %source_file for forward searching (i.e., using \ls). If \lv is being used, the %line and %source_file parts are omitted.

Using Skim, PDFSync, and TeXShop

UPDATE 3: I have updated the script to support command-line options that will prevent TeXShop from doing things like refreshing text (and trashing your unsaved changes), activating (taking your focus away), and opening (possibly getting in front of your view). Try the -h option for details.

UPDATE 2: There is a related Skim revision that will make it easier to use AppleScript for PDFSync interfacing. This change will prevent having to make UNIX shell scripts that must be modified with chmod.

UPDATE 1: As you can see in the Skim revision history, future versions of Skim will include their "Application Support" directory (e.g., ~/Library/Application Support/Skim/) as well as a "Scripts" subdirectory in their path. When that occurs, scripts like the one below can be stored there and executed from Skim without specifying the full path name.

I know there are ways to change TeXShop's previewer; however, I don't know how to do them. Additionally, I don't use TeXShop, so I have little incentive to look those things up.

However, I do use Skim, which is compatible with pdfsync, and recently someone asked me how they could get Skim to call up TeXShop at a particular line (as someone would want to do when using pdfsync).

For that, I generated a texshop script that looks like this (an earlier version of this can be found on the Skim wiki):

fileName="$1"
lineNumber="$2"
gotoString=""

[ "${fileName:0:1}" == "/" ] || fileName="${PWD}/${fileName}"
[ "${lineNumber}" == "" ] || gotoString="goto line ${lineNumber}"

exec osascript \
  -e "set texFile to POSIX file \"${fileName}\"" \
  -e "tell application \"TeXShop\"" \
    -e "activate" \
    -e "open texFile" \
    -e "tell front document" \
      -e "refreshtext" \
      -e "${gotoString}" \
    -e "end tell" \
  -e "end tell"

To use this script, follow these steps:

1. Save that file as something (preferably in the PATH somewhere, but this is not necessary) like

   /usr/local/bin/texshop

   or anywhere you would like (e.g., /Users/username/bin/texshop). However, if you place it somewhere differently, be sure to update the red text in these instructions.


2. Next, chmod it 0755, as in

   chmod 0755 /usr/local/bin/texshop

   This can be done from the Terminal.


3. Finally, tell Skim's PDFSync preferences (under Preferences->LaTeX or Preferences->Sync depending on your Skim version) to use a "Custom" editor with

   Command: /usr/local/bin/texshop
   Arguments: "%file" %line

   Make sure you click AWAY (e.g., onto a different tab) from the PDFSync settings before you close the Preferences. Otherwise, one of your text boxes may not get saved.

After this is done, doing Shift+Command+CLICK in Skim on a location in the PDF will bring up the source in TeXShop located at the that generated that point in the PDF.

Note that if you have saved texshop somewhere in your PATH, then you should be able to drop the /usr/local/bin/ from the front of the Command: line.