LaTeXTools plugin: new features

I have recently added two simple but hopefully useful features to the LaTeXTools plugin. I hope they will make your TeX life more comfortable.

As usual, you will get the updated plugin automatically if you installed LaTeXTools using Package Control, which, as I noted earlier, I strongly encourage you to do.

Switching to the PDF viewer after compiling

By default, LaTeXTools keeps the focus on the Sublime Text 2 (ST2) window after compiling a TeX source file to PDF. This is convenient in two scenarios. First, if you have a large screen (or two monitors), you can keep ST2 and your PDF viewer side by side, and just glance at the output to see that all is OK. It would be quite annoying if the viewer window was brought to the foreground in this case: in order to continue editing, you would have to manually switch back to ST2 (using Alt-Tab or Cmd-Tab, depending on your platform). The other scenario is when you are making many small changes to the file sequentially; you compile to make sure that there are no errors or warnings, but do not need to check the PDF output every time. I also have friends and coauthors who simply don’t need to look at the PDF output all that often–they can read LaTeX easily, and would much rather not be distracted by the viewer window popping up.

That said, it is sometimes convenient to switch to the PDF output, especially if you are using a small screen and running both ST2 and your viewer in full-screen mode. In such cases, it would be nice if LaTeXTools could automatically bring up the viewer after compiling. Yet, the previous paragraph gives a few reasons why this shouldn’t be hard-wired.

Enter the Toggle Focus command (bound to Shift+Win+F on Windows and Ctrl+Cmd+F on OSX). It does what you think: every time you invoke it, it changes what the Build command does after compilation. Again, by default, the Build command refreshes the PDF viewer but makes sure that ST2 keeps the focus; so, if you invoke the Toggle Focus command, the next time around Build will actually tell the PDF viewer to grab the focus, i.e. pop us as the frontmost window. Invoke Toggle Focus again, and you get the default behavior back. Every time you switch, a short notification appears in the Status Bar (at the bottom of the ST2 window), so you know what you just did.

Note that this setting is preserved with your session; if you quit ST2 without first closing the tab you are working on, ST2 will remember the status of the focus toggle.

Wrapping existing text in LaTeX commands or environments

The current facilities for entering LaTeX commands or environments (Alt-Shift-[ and Alt-Shift-] on Windows, Cmd-Shift-[ and Cmd-Shift-] on OSX) are useful when you want to first specify the type of environment or command you want, and then enter text in it. However, sometimes you want to wrap some existing text in a command or environment. The most common use case is to emphasize text, or make it bold. I don’t use this feature that often myself, but a colleague mentioned it as one of the main reason why he was sticking with TextMate for the time being.

I have now added a nice collection of wrap commands. They are all bound to Alt-Shift-W on Windows and Option-Shift-W on OSX, followed by an additional key (i.e. you use a “key chord” to invoke them). You must select some text prior to invoking these commands.

Alt+Shift+W followed by n wraps the selected text in an environment, which by default is called “env”: that is, if “blah” is the text currently selected, it gets replaced by

\begin{env}
blah
\end{env}

and the env is highlighted. Enter your desired environment (e.g. “theorem”). When you are done, hit Tab to jump to the end of the environment.

Alt+Shift+W followed by c instead enters a command: “blah” becomes \cmd{blah}, with cmd selected so you can change it to whatever you like.

Finally, a few common commands have dedicated key bindings: Alt+Shift+W followed by e, b and u respectively give you \emph{...}, \textbf{...} and \underline{...}.

Happy TeXing!

LaTeXTools plugin: a slew of fixes

I finally got around to committing a bunch of fixes for my LaTeX plugin for the Sublime Text 2 editor. I describe the main changes below. First though I really want to give a shout-out to the outstanding Package Control plugin, which makes it trivially easy to install and update LaTeXTools and most other Sublime Text 2 plugins. If you have Package Control installed, getting LaTeXTools on your Mac or PC is just a matter of invoking Package Control: Install Package via either the Command Palette or the Preferences menu. See the aforelinked page for details. Incidentally, I didn’t have to do anything to make sure LaTeXTools was picked up by Package Control: it happened automagically, to my surprise and delight. Yay!

Now for the fixes. In no particular order:

• I expanded the README file so it now covers most, if not all, of the current functionality. I also provide some ideas on how to troubleshoot issues. By the way, if you do find something is wrong, please let me know!
• I finally understood that latexmk does not automatically force the TeX engine (e.g. pdflatex) to work in batch mode. Errors will cause latexmk to stop. You can check this by running it from the command line. However, on OS X, somehow invoking latexmk via subprocess.Popen still works, in the sense that all processes terminate regularly and the plugin can then look for errors in the TeX log file. On the other hand, on Windows, using TeXlive, this is not the case: the build command essentially hangs, and even if you terminate it, the pdflatex process keeps waiting for input in the background. This makes further compilations fail (because the synctex file is locked), and forces you to terminate the stray process with Task Manager. Ugly! Well, I hope I have fixed at least the most egregious causes of such inappropriate behavior by passing the -silent option to latexmk.
• A user had a lot of trouble with on-the-fly conversion of EPS files to PDF on OS X, using the epstopdf package. Ends up the problem was path-related: epstopdf relies on Ghostscript, and MacTeX puts Ghostscript in /usr/local/bin rather than /usr/texbin. When compiling from the command line, everything worked–because MacTeX also helpfully fixes your $PATH; but, building from Sublime Text 2 always failed. Adding the former path in LaTeX.sublime-build fixed the issue. Thanks Jon and Sublimator for helping me track down this bug!
• SumatraPDF, the supported PDF reader on Windows, only reloads recently changed files if they are local: it does not automatically reload files on network shares when they change. As a result, recompiling a file on a network share resulted in SumatraPDF not automatically showing the updated text. This was a problem for me when running Windows in a Parallels virtual machine: Mac directories are accessible are network drives, and there is no problem editing files with Sublime Text 2 on the virtual Windows side; however, I had to manually reload PDF files every time. Bottom line: I now explicitly force a reload before issuing the forward search DDE command.

Enjoy, and as usual report back any issues you may have!

LaTeXTools: updated SumatraPDF setup information

Just a quick heads-up: I just added detailed instructions in the README file on how to set up inverse search with SumatraPDF on Windows.

If you were using SumatraPDF with another text editor that supported inverse search, you probably didn’t have any trouble reconfiguring inverse search to work with Sublime Text. However, it turns out that a fresh install of SumatraPDF does not show a GUI for the inverse-search command, until you actually open a PDF file that has actual synchronization information in an accompanying .synctex.gz file.

The revised README file shows how to proceed. Basically, if you already have a PDF file with an attendant .synctex.gz file, open the PDF in SumatraPDF, and you’ll see the GUI when you select Settings|Options. Otherwise, you can either compile any latex document with pdflatex and sync information (i.e. compile with pdflatex -synctex=1 ), or else configure SumatraPDF from the command line. See the README file for details. As usual, you can read that file at Github (you may need to scroll down a bit).

I’m sorry things are not more straightforward. Good luck!

TeXlive is a go (plus, a better README)

Last night I pushed the changes I made to the LaTeX.sublime-build to GitHub. You may say that TeXlive is now “officially supported” on Windows, in addition to MikTeX. As I noted earlier, I fully expected Sublime Text 2 to eventually fix its handling of non-normalized file paths and different drive letter cases. As usual, Jon has come through: as of version 2120, everything works just fine!

Also, I finally got around to beefing up the README file for the plugin. It’s in Markdown format, so it’s human-readable, but you can see it in all its HTML-formatted glory if you just go to the LaTeXTools page at Github and scroll down. I hope this will encourage more people to give Sublime Text 2 and LaTeXTools a whirl.

One final note on the choice of TeXlive vs. MikTeX. As I see it, the trade-off is this: MikTeX’s management tools, and its DVI previewer Yap, are Windows-native, whereas TeXlive’s management tools feel like ports of Unix tools, which they are (even the GUI ones). On the other hand, TeXlive has full support for spaces in file names and paths, which MikTeX currently lacks. As a further advantage, TeXlive has a working version of latexmk, which means that it is very easy to change the tex engine from pdflatex to, say, xelatex: just change the appropriate line in LaTeX.sublime-build. Finally, TeXlive on Windows is essentially the same as, and package-wise in sync with, MacTeX on OSX, which may be convenient if you’re a platform hopper like me.

TeXlive on Windows: forward and inverse search

Yesterday’s post ended with a conjecture: TeXlive should be able to generate correct sync info on Windows. Today I decided to test that conjecture; I installed TeXlive 2011, which turned out to be surprisingly simple, with one caveat: the MiKTeX installer adds its binary directory to the system path, and if you run the TeXlive installer in user mode you obviously can’t change that. To fix this, you need to add the TeXlive binary path manually, before the MikTeX path. However, if you plan on using Sublime Text 2, you don’t even need to do that, and you can use both distros  side-by-side: read on.

Supporting TeXlive/Windows in the LaTeXTools plugin turns out to be trivial. You only need to modify the LaTeX.sublime-build file! Chalk that up to Sublime Text 2′s build system design, which my plugin’s makePDF command takes advantage of.

I’ll push the changes (commented out, so the default is still MikTeX) soon; for the time being, if you want to experiment, with TeXLive, modify the “windows” section of the file LaTeX.sublime-build so that the “cmd” option looks exactly the same as it does in the “osx” (i.e. Mac) section. This is not surprising: after all, the underlying TeXlive distro is the same. Furthermore, you can use the “path” option to specify the TeXlive binary directory, so you don’t even have to mess with environment variables (make sure to add “;$PATH” after the TeXlive path).

The result is that Sublime Text 2 now works happily with TeXlive! So, does synchronization (forward and inverse search) work, even with file names that have spaces? Yes! Well, I should be precise.

First, the .synctex.gz file is correctly generated. Recall that MikTeX 2009 does not generate it if the file name contains spaces, so this is an improvement.

Second, forward search works beautifully [an aside: Ctrl-Shift-J is now bound to a folding operation, so I need to change the keyboard shortcut. Use Ctrl-B for the time being: if no compilation is required, the net effect is the same, i.e. you jump to the right position in the PDF file. Again, I'll push a fix soon].

Third, backward search (from the PDF to the tex file) sort of works. The problem is that the most recent version of synctex “extends” file paths so that

C:\Users\YourName\Documents\test.tex

becomes

C:\Users\YourName\Documents\.\test.tex

(the same is true on the Mac, btw). Clearly, both paths point to the same file. However, when you double-click in the PDF file, SumatraPDF invokes Sublime Text 2 (or whatever editor you designate) with the second, longer version of the the file name. Now, most likely, you already have the file test.tex open in a tab in Sublime Text 2; however, if you opened that file yourself (e.g. from an Explorer window, or from the Open dialog), the path name associated with the file is the first, “normal-looking” one. As a result, Sublime Text 2 opens a second tab, with the same actual file, but a different path name (the “extended” one). You can check for yourself by hovering on the two tabs: the path names are indeed different, as described above. On the positive side though, the cursor is positioned correctly, corresponding to the point in the PDF file where you double-clicked in SumatraPDF.

Now, this is not a Sublime Text problem: the exact same behavior results if you use TeXnicCenter. Furthermore, no such problem exists with Sublime Text 2 on the Mac (with the Skim previewer). Finally, neither Sublime Text 2 nor the underlying Mac OS do anything special to make sure that files of the form

/Users/YourName/Documents/test.tex

and

/Users/YourName/Documents/./test.tex

are treated as one and the same: you can try this for yourself by opening a file using the two above specifications of the file name from the Terminal.

Bottom line: it is SumatraPDF’s fault. Or, more precisely: on the Mac, the Skim app is smart enough to send a “normal” file name to your text editor when you perform an inverse search. SumatraPDF is not as smart.

Presumably, the problem does not arise if you use MikTeX because it uses a version of synctex that does not use “extended” path names—but that version, unfortunately, does not handle spaces in file names either!

The bottom line is that it’s a bit of a catch-22: either you use MikTeX, but avoid spaces in file names; or, you use TeXlive, but are forced to open files in Sublime Text 2 by using their “extended” pathname. This is easy to do: open your tex file normally, then build it, then double-click in SumatraPDF; when the second tab pops up in Sublime Text 2, close the first, and from then on work in the new  tab. Of course, you can also open the PDF file first, then double-click, and work in the tab that Sublime Text 2 opens for you. Ugly, but functional.

I will report the issue on the SumatraPDF bug tracker. Hopefully it will get fixed in a later version.

MikTeX synchronization and spaces in file names

In three words: it doesn’t work (does “doesn’t” count as 1 or 2 words though?).

A bit more detail. After a long hiatus, I fired up a Parallels 7 virtual machine and decided to use SumatraPDF and Sublime Text 2 under Win7 for my day’s work (which is, as usual, LaTeX-heavy). However, synchronization (i.e. jumping from the LaTeX source to the PDF output and conversely) kept failing with the particular file I was working on . This was both surprising and worrisome: I have been developing the LaTeXTools plugin for ST2 under Mac OSX lately, but my focus has been on cross-platform features; I assumed that the sync infrastructure, which is very platform-specific, was in a stable state by now. Still, one can never rule out new bugs with updates to both ST2 and SumatraPDF; this is the reason why I occasionally take a trip to the Win7 side, as I did today.

Ends up the problem is not with ST2 or with the LaTeXTools plugin: the sync infrastructure is still solid on Win7. Rather, the failure of synchronization is a well-known issue that affects the (otherwise excellent) MikTeX distribution. Like many other TeX distros, MikTeX relies on a library called “synctex” to generate the synchronization information (the “.synctex.gz” files that get created whenever you pass the “-synctex=1″ option to pdflatex). Unfortunately, if the LaTeX source file name (more precisely, its full path name) contains a space, the generated sync information is incorrect.

I double-checked this two ways: first, if there are no spaces in the path name, ST2+SumatraPDF work just fine; second, if there is a space in the file name, then synchronization also fails in TeXworks. Google says it fails with WinEdt, TeXmaker and other editors as well. Incidentally, the TeXworks test exonerates SumatraPDF, because TeXworks and SumatraPDF use different libraries to render PDF files (although they both use synctex for backward and forward searches).

Now, in principle, the problem may be with the synctex library itself. However, on Mac OSX, synchronization works fine with file names that include spaces. The synctex code is largely cross-platform, so the problem must be in the way MikTeX incorporates or adapts it on Windows. One way to test this would be to run the TeXlive distribution on Windows; it, too, includes synctex, and the standard Mac TeX distribution, aptly named MacTeX, is essentially just TeXlive compiled under OSX, with some additional apps. Since MacTeX generates correct sync info with or without spaces in file names, I suspect that TeXlive under Windows does, too. If anyone has experience with this, please let me know in the Comments.

Bottom line: this is a Windows- and MikTeX-specific, back-end problem that unfortunately I cannot fix. I hope a future release of MikTeX will resolve the issue, because I do occasionally use spaces in file names. In the meantime, the fix is to, well, stick to file and directory names that have no spaces in them.

LaTeX plugin: build paths are in!

A long-standing stumbling block for people getting started with ST2 on the Mac was the need to specify the TeX binaries path in a somewhat esoteric (and hidden) OSX plist file.

Well, no more! To make a long story short, my hard disk crashed, so I had to reinstall and reconfigure the OS and software on my Macbook Pro. In particular, my now-virgin system no longer has the .MacOS/environment.plist file correctly set up. I decided to use this opportunity to fix things the right way.

Now, the LaTeX.sublime-build file recognizes a new option, “path”. On the Mac, it is preconfigured so it works with any recent default install of MacTex. You can change it if necessary, but most likely you won’t need to: the build system should now just work.

On Windows, recent versions of MikTex do the right thing and set up the path so no special setting is needed, but the option is available in any case to handle non-standard configurations. (Note: you still need to manually add the Sumatra directory to your path; I plan to fix this next.)

As usual, please pull from GitHub, test, and report any breakage.

LaTeX plugin: Terminating a lengthy build process.

I just pushed a few patches to GitHub. If you get a fresh copy of the LaTeX plugin for Sublime Text 2, you will now be able to stop (Unix: “kill”; Windows: “terminate”) a lengthy build process simply by invoking the build command while a build is ongoing.

To clarify: say you start a build, e.g. by hitting CMD-B on the Mac. Suppose that you are compiling a Beamer presentation, which typically takes a while. Suddenly, you realize that there is a nasty typo in a slide. Instead of waiting for the build to end, you can now issue the build command again (e.g. by hitting CMD-B on the Mac): this will stop the currently running build, and print a message to this effect in the output panel. You can then fix the typo, and launch a new build as usual.

Caveats: this is my first stab at build killing. The required code (in makePDF.py) definitely hits the ceiling of my Python threading abilities. So far, it seems to be working (I’ve been using it myself all day, as I prepare for two upcoming conferences), but please test it yourself and let me know how things are.

Second, I have only tested this on the Mac. The Python code I use is fully cross-platform, but you never know. If you are on Windows, I’m even more curious to know if things work for you.

Final note to self and to fellow Python coders: I initially had quite a bit of trouble, because I used to execute the actual TeX commands via Popen.communicate. Trying to use Popen.kill() on a Popen object did not really work, in the sense that considerable time elapsed between the time the kill() method was called and the time the process actually exited. I am now using Popen.wait() to execute the TeX command, and the process is terminated almost instantaneously. There seems to be some funny business having to do with capturing output going to STDOUT in Popen.communicate(); using Popen.wait() avoids this (although you then have to send output to a temp file, if you need to capture it–which I don’t at the moment).

LaTeX Plugin: Build system activated

This post is a quick update on the revamped LaTeX build system.

If you pull the current master branch from Github, you will now be able to invoke the custom make_pdf command using the default build system: in particular, you can hit Command+B on Mac and F5 on Windows. The temporary ctrl+alt+t shortcut no longer works: on Mac, it does nothing, whereas on Windows it errors out (I’ll fix this soon). So, just don’t use it.

This is achieved by using the “target” option in the LaTeX.sublime-build file. By default (i.e. if no “target” option is provided), the build system invokes the “exec” command. However, you can instruct it to invoke any Python-written ST2 command; in my case, I set “target” to “make_pdf”, and ST2 automagically does the right thing.

In particular, any options in the sublime-build configuration file are passed as named arguments to the make_pdf command. Even better, you can set Windows- and OSX-specific options in the sublime-build file, and make_pdf will automagically receive the settings that are appropriate to your platform!

One final bit of awesomeness. If you open the LaTeX.sublime-build file, you will see that you can pass any configuration options to the latexmk (OSX) or texify (Windows) compiler drivers, IF YOU KNOW WHAT YOU ARE DOING. For instance, on Mac, you can easily change the tex engine from pdflatex to xelatex (it’s not so easy on Windows because texify is not as flexible as latexmk). Now, I was worried that any tweaks to the sublime-build file would be lost every time the user downloads a new version of the plugin. However (and this is the above-mentioned awesomeness), it turns out that you can save a copy of the LaTeX.sublime-build file in the Packages/User directory (rather than Packages/LaTeXTools), then tweak it to your heart’s content: when you invoke the build system, the file in Packages/User will take precedence, so your tweaks will still be there! Thanks jps

There are two items on my immediate TODO list. First, I want to add an option to the sublime-build file to specify the path of TeX executables (with sane defaults that should work on most systems). This will ensure that, with a minimum of configuration (or no configuration), tex and friends will work even if the PATH is not set (or, on the Mac, you have not created an .MacOSX/environment.plist file, as per this comment). This is the main cause of grief for new users; hopefully this will solve the issue once and for all.

Second, I would like to make the viewer configurable as well. Right now it is not: you must use Skim on the Mac and Sumatra on Windows. There is an issue as to where this setting should be; the sublime-build file does not seem appropriate, strictly speaking, but on the other hand it makes sense to keep all configuration settings in the same file.

One final note: the old sublime-settings file is still available, but I appended an “.OLD” extension to it so it’s not active. However, if you really prefer the old-style build system, you can still use it (remove or rename the new sublime-build file, then remove the “.OLD” extension to the old sublime-build file). In particular, this allows you to set your favorite PDF viewer (on the Mac), although you will lose inverse and forward search.

Comments, are usual, are very welcome!

LaTeX plugin: the new build engine is in!

I have decided to merge my ongoing work on a LaTeX-specific build engine. See my previous post for details on the new goodness. If you now pull the master branch from github, you’ll get the new engine. The relevant file is makePDF.py, but I had to change jumpToPDF.py as well.

A few notes. First, the quality of the code is, er, less than ideal. It works on all the (many!) test cases I have thrown at it, but it’s not pretty to look at. I’ll fix this in time. However, in the meantime, I’d like to get more people to try it out.

Second, the new build engine is bound to ctrl+alt+t (which is control+option+t on the Mac). The old, ST2-based build system is still available and bound to F5 on Windows and Command-B on the Mac (these are the ST2-standard bindings). Eventually, I plan to phase out the old build system, but not yet…

Third, due to the logic of log file parsing, you cannot use file names with parentheses. However, I am happy to report that spaces in file names (and directory names, too) are OK.

Fourth, there is still limited support for multi-file documents. Specifically, the log-file parsing logic is smart enough to pick up errors in different files and place the appropriate lines in the exec panel. However, compilation must be invoked from the master file (i.e. you must switch to the tab containing the master file before invoking compilation). The same is true of the old build system, by the way. Setting master files so you can compile from any file in the project is high on my agenda (together with certain other build and display customizations).

If you see any breakage, please let me know! In particular, if you see the line saying ‘Compiling ‘ in the exec panel, but nothing else happens after a while, hit ctrl+` to bring up the output panel; if you see any Python error messages, that’s breakage! Reports are greatly appreciated.