Tag Archives: sublime text

LaTeXTools updates

Well, it’s been a while…

Unfortunately, I’ve been extremely busy at work lately, so LaTeXTools development has had to take a back seat. However, a number of contributors have submitted patches. Over the past couple of weeks, I’ve been able to incorporate some of the most useful and significant ones. Among them:

  • Fill helper: think of this as reference/citation insertion, but for included files, graphics, and even LaTeX packages.
  • LaTeX compilation options: the “traditional” builder supports these in two ways. One is to add a %!TEX option = line at the top of the file (or root file in a multi-file document). The other is to use the LaTeXTools.sublime-settings file: specify your options using the options setting in the Builder Settings section.
  • Support for the LaTeX-cwl package. I don’t really use it, but it’s been requested often.
  • Jump to included files, ability to hide the panel upon a successful build, and improvements to the delete temp files feature (including the ability to specify which files to delete, and which directories to leave alone).

Please refer to the README file for acknowledgements of the above contributions. My role has only been that of testing, integrating and sometimes documenting the new features. The credit for the actual code goes to the wonderful LaTeXTools community.

LaTeXTools: a new, customizable build system

Edited 3/13/14: updated name of configuration file. Also, this code is now in the master branch! More details in a later post.

One of the requests I receive most frequently, especially from LaTeX power user, is the ability to customize the build process. In principle, this is possible. However, it requires modifying the LaTeX.sublime-build file. This is inconvenient for a number of reasons. First, the file must be copied to the User directory, or it will be clobbered by subsequent updates of the plugin. Second, the file also contains internal settings that cannot and must not be customized. Third, the Sublime Text build system is really designed to launch a single, command-line program, or else a “make”-like utility. Indeed, LaTeXTools uses it to invoke either texify or latexmk, which are essentially TeX-specific “make” utilities. In principle, one can write one’s own custom build script and use that in lieu of the default build command; however, most users will not want to do that. Also, one is somewhat limited by the fact that external scripts do not “know” about Sublime Text, and hence cannot meaningfully communicate with it.

Enter the new “master builder” system; you will find it in the mbuilder branch on GitHub. Here’s what’s new:

  1. All user settings are now in the LaTeXTools.sublime-settings file. This includes the path to tex & friends, and all the settings discussed below. With the new code, LaTeX.sublime-build becomes effectively just an internal file that users need not and, indeed, must not modify. NOTE: if you want to play with the mbuilder branch, make sure to delete any stray LaTeX.sublime-build files you may have in the User directory. Also, as for any Sublime Text settings file, LaTeXTools.sublime-settings should be placed in User directory and customized there.
  2. The build system is now split into two components. One is the “master builder,” which takes care of handling the Cmd/Ctrl-B command and manages the (delicate) threading infrastructure required to run external commands such as pdflatex or latexmk; this is the code in the file makePDF.py. The other is the actual “builder” or “build engine,”  which examines the tex root file, decides how to process it, and tells the master builder which external commands to run. Indeed, there are currently two build engines (called “traditional” and “simple”), with a third (“script”) coming soon: you will find the code in the builders directory.
  3. The “traditional” build engine does exactly what the current code in the master branch does: it calls latexmk or texify (and also allows for the selection of a tex engine). The “simple” build engine, on the other hand, requires no external tools, and can be useful, for instance, if you don’t want to install latexmk on OS X or Linux. It runs pdflatex, then bibtex if needed, then pdflatex again, as needed, until references / citations are either resolved or just missing. Thus, the “simple” engine is an example of a (simple!) “make” tool for tex & friends that runs entirely in Python, within Sublime Text. I hope one day to write (or, better yet, receive as a user contribution…) an actual, robust replacement for texify / latexmk. For now, the “simple” engine serves as an example to aspiring contributors… Finally, the “script” engine, when ready, will simply invoke a user-specified external command.
  4. All parameters of the build engines are configurable in LaTeXTools.sublime-settings. Again, you can forget about LaTeX.build-settings. In particular, the “builder” option selects your preferred build engine. When the “script” engine is ready, this is where you will specify which external script to use, and whether to set any environment variables, for instance.
  5. Techie note: the beauty of this system is that build engines can access the Sublime Text API, as well as the whole Python library, but they do not need to know anything about threading. Instead, builders use the powerful Python mechanism of generator functions. Each time a build engine wants to run an external command (pdflatex etc.), it uses the Python yield command to send it to the master builder. The master builder runs the external command, captures its output, and returns it to the build engine.

The code is still beta quality; I’m running it daily myself, but I’m interested in feedback from adventurous users. When I’m reasonably confident that things are working, I’ll merge it into the master branch.

LaTeXTools: Sublime Text 3 support is now live!

I have just merged support for Sublime Text 3 into the main (master) branch. So, this is no longer in development: you will be getting it automatically via Package Control (update manually if necessary), or you can get it from GitHub.

As I explained in a previous post, the same code will work on Sublime Text 2 and Sublime Text 3. Hence, there will be feature parity on both versions of our beloved editor.

I have done my best to test extensively on various combinations of ST versions and platforms, but let me know if you see something strange.

Also, in case something is seriously broken, I have created an “st2” branch on GitHub hosting the code right before today’s merge. Consider this an emergency fallback only; the new code on the master branch should work fine.

LaTeXTools: two major new features

I’m in a bit of a rush, but I wanted to share the news as soon as possible. Over the last couple of days, I pushed one major update to the LaTeXtools plugin, and started a new branch that provides initial support for (yes!) the newly-beta Sublime Text 3 (ST3 for short).

The major update incorporates a revamped completion system for citations and references. Most of the new code comes from contributions by users westacular and jlegewie; I just did some cleaning up / harmonization, plus I incorporated other fixes and improvements to the previous code base. You just have to take a look at the README to see what this is about. The highlight feature is autotrigger: as soon as you type, e.g., “\ref{“, the quick panel pops up with a list of all labels in your file; and if you type “\cite{“, you get a nicely formatted and searchable display of your bibliography. (If you don’t like this behavior, you can turn it off). Also, you can finally insert multiple citations in one “\cite{}” command: the quick panel is autotriggered as soon as you enter “,” after an existing citation key, inside the braces. Again, go read the README!

Support for ST3 is based on the excellent work by phyllisstein. I couldn’t quite pull his code in as-is due to some divergence, and also (frankly) because I thought I’d learn more about the required changes by doing the work myself. Also, I wanted the same code to work for both ST2 and ST3. However, I cheated and copied profusely. First, phyllisstein sketched the essentials of the port in an issue report, and elaborated in  an email to me. So, I broadly knew what I had to do, and what to watch out for (great subject matter for a follow-up post!). Second, I kept his code open in my browser, and consulted it when I got stuck. In fact, I cut-and-pasted it whenever I could. Bottom line: thank you phyllisstein!

Remember: the st3 branch is still somewhat experimental. But, go ahead and try it! It is based on the most recent master branch, and hence includes all the ref/cite goodies above, plus all recent fixes and improvements.

To install it, get the .zip file from Github, unzip it in your ST3 package directory, restart ST3 if you have it running, and enjoy! Of course, you need to configure your previewer (SumatraPDF or Skim–evince on Linux should work out of the box, but I can’t test myself) to launch ST3, not ST2, for inverse search. Check the path to ST3 on your system.

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!