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


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!


56 responses to “LaTeXTools plugin: new features

  1. Thanks so much for your LatexTools plugin. Because of this, I am close to switching over to ST2 from TM, but cannot do without “Go to symbol”. Is it in ST2 somewhere? Command-R does not have the nice outline of chapters, sections, subsections, subsubsections, all indented as in TM .

    • Hi Jenny,

      yes, Cmd-R doesn’t quite match TM’s Go to Symbol. I plan on fixing it at some point soon though, because Go To Symbol was one of my favorite TM functions.

      A bit of history: Cmd-R actually piggybacks on ST2’s “go to anything” functionality. The plugin merely tells ST2 what a “label” or “section” is, but it is up to ST2 to decide how to present them (in particular, how to sort the items in the list). When I added Cmd-R support to the plugin, this was pretty much the only way I could present the user with a list of items that could be clicked on—recall ST2 is technically still beta software.

      However, plugin writers can now (finally!) access the exact same UI that Cmd-R uses, but also provide the “plumbing”, so to speak (i.e. decide what to show and how). So, the tools are there, and it’s just a matter of me finding the time to implement the Go to Symbol functionality. If only I didn’t have letters of recommendation, referee reports, tenure letters and the like to worry about. Oh yes, and pushing my own papers through the pipeline, too 🙂

      • Don’t I know it! I just found out that TM2 is scheduled for a Christmas release. This could change everything. Alan Odgaard deserves full attention.

  2. Hi Marciano,

    Thanks for the wonderful plugin! May I suggest two features that would make Latex in ST2 even more awesome:
    – Making spell check Latex aware (although is aware of most Latex commands) by treating ~ as space: “Theorem~1” would become “Theorem 1”.
    – The cite command only displays the title field. In Textmate they also display authors. For me this makes more sense since I remember authors better than titles :-p.


    • Re. spell-checking, that’s ST2’s job: the plugin can’t really do much about it. ST2 uses Hunspell, and I guess LaTeX support could be better….

      Re. citation command, I’m actually revamping the system. It will now use the quick panel (which looks just like the Go To Anything panel), and will display (and make searchable) both the title and the author(s). Please be patient!

  3. I just read up a bit on spell checking LaTeX documents and apparently hunspell is able to spell check TeX/LaTeX files using a parameter:

    hunspell -l -t -i utf-8 yourfile.tex


    I do not know if parameters can be passed on to hunspell via ST2, but if it is possible, spell checking should be possible.

  4. I just tried spellchecking my tex document by pressing F6 in build 2162 and it works perfectly!

  5. First, thanks for the awesome plugin! It is making my typesetting so much more comfortable. I really like the new feature allowing me to switch focus to the pdf output immediately after compiling. While I like this behavior in general, it is a nuisance if there are errors in compiling. Would it be possible to enhance this feature so that it doesn’t automatically switch focus to the pdf if there are errors in compiling? Since you’re already parsing the log file for errors, this should be a relatively easy enhancement. Thanks again for your time and effort!

  6. Sorry, my code doesn’t work. The reason it was working when I was using it was a bizarre coincidence in error handling. Could you please delete my previous two comments giving the code so other people may not use it? Sorry again about that.

  7. OK, I finally figured out the right way to do it. It was quite easy as you said, although it requires changes in a few places in the file
    First, change the definition of the function finish to:

    def finish(self, errors):
           sublime.set_timeout(functools.partial(self.do_finish, errors), 0)

    Next, change the signature of do_finish() to:

    def do_finish(self, errors):

    Then, change the last line of do_finish() to:

    if not errors:

    And finally, change the last line of run() in CmdThread to:

  8. hey,
    thanks for the great plugin. I really miss it now on linux, how are the chances of pulling the changeset on github/making it work? I’d be happy to help.


  9. Hi,

    Thanks for the wonderful work. The only thing that is missing from my point of view is that citation and reference tab completion is bound to the current tex file. These commands ignore the TEX ROOT entry in a tex file’s first line. Which is a petty, especially for citations since the bibliography{} command will most likely be located in the TEX ROOT document.


  10. Hi, thanks a lot for your awesome plugin. It is clear and at the point. I have added , “-pv”] at the end of the cmd latex.sublime-build. It is magic. I used to mesh in a perl script in TextMate (and TM2) and before I had a lot of scripts to do something no so simple and powerful, in Alpha (and AlphaX –a classic editor based on Tcl).
    I am trying to do this new jump, but since ST2 has no the interactive Command Dialog TexMate had, but instead, it has so many json files to mesh with, I am feeling a bit lost, now.

    The main problem I have with your latex plugin now its keyboard commands depend on cmd-[ and so, and many of them do not function in non-english keyboards, where you need to press Option (Alt) to reach the [ char. I would like to change them and also be able to customize and add many plugins and commands I have already developed in Ruby (wonderful Ruby), like for example, to open quickly an included style/class/format just searching in the kpsewich-like directories. I would like add them to your plugins.

    Thanks in advance (and please forgive my poor English)

    – Juan F.

  11. Hi there,

    I’m a beginner in Latex and my brother told me to use ST2 together with your plugin. I have to say, it is really a pleasure to work with it.
    That said, I’ve encountered a problem lately which I would like to throw into the discussion here. I’ve configured the inverse search as written in the manual and I have one .tex-file with which everything works just fine: after texing skim opens automatically and jumps to the particular place of last change in the pdf created. But then I’ve another file which is nearly identically (only build earlier) which just is not able to induce the aforementioned behaviour. I can compile as often as I want to but Skim does not open by itself. Moreover, if it’s open already it wouldn’t show the pdf automatically – I would have to use shortkey cmd+shift+b on my mac. Doing this, it would still not jump to the place of last change. It drives me mad that the other file just works fine but the latter one doesn’t. I already tried to paste the content to the working file but then this one also doesn’t work anymore… Any suggestions why this is?


    • Hi again,
      I’ve just solved the problem and want to let you know. Im from Germany and we have special characters called Umlauts which change the pronunciation of the underlying vowel: ö,ä, and ü. The folder in which I placed the document was in another folder which contained such an Umlaut. Just changing this now did magic for the functioning of this awesome plugin. Now, I can enjoy it again as I did before with the other file (that one had an English name for the folder, so no problems there :)).

      Thanks for reading through!

  12. Hi, first of all thanks a lot for this awesome plugins! it works very well, pretty simple, clear and well integrated. I just want to know how to add the makeindex script to generate a Glossary for my report? I tried to modify the command latexmk in LaTeX.sublime-build to add $makeindex but it seems that doesn’t work, perhaps a missed some thing or I didn’t know how to misspell the command. It will be nice it you have any idea about how to resolve this. PS: I used this complete command in TexMaker before “makeindex %.glo -t %.glg -s -o %.gls”

  13. Very useful plugin… just begining to use it. Just one question:
    cmd-shift-] and [ are conflicting with panes switching (like terminal or safari tab switch). May I change / unbind it ?

  14. thanks for your incredible work, looks very awesome
    i’m a beginner … I saw in the documentation this : “By default, ST2 provides a number of snippets for LaTeX editing; the LaTeXTools plugin adds a few more. You can see what they are, and experiment, by selecting Tools|Snippets|LaTeX and Tools|Snippets|LaTeXTools from the menu.”
    but i’m not sure
    i understand where to find a list of available completions, if i go tools>snippets and write latex i have only 2 or 3 commands available : “wrap selection in latex command” and “”wrap selection in latex environment” …. any idea anyone ? ty

  15. I’m having another issue that bothers me. I defined my own package that I use like that ” \usepackage{../../../my_package}”
    then when there is error in my code (in my main file), the error refers to my_package.sty, but the number of line are correct.

    * main.tex :

    * results of building :
    There were errors in your LaTeX source
    ../../../my_package.sty:3: LaTeX Error: Environment docment undefined. [\begin{docment}]

    And when I click on the error I naturally arrived in my_package.sty

    any ideas ?

  16. some news, it is apparently related to the presence in my_package.sty of “\usepackage{comment}”, if I dont use this package everything works fine

  17. Today the shortcut for toggling the focus on pdf stopped working … it is now the shortcut for going full sreen in ST2 … it is bothering not being able to focus pdf anymore after building .. any idea ?
    and thanks for your great work !

    • Please see my earlier reply – new keybinding.

      • Yes I just saw it, perfect ! … additional question : is there a way to change the default behavior ? I would like to always get the focus to the pdf (for any tex document) … thanks again !

      • This requires adding a whole “settings” system… I would gladly avoid (I’m a fan of “convention over configuration”), but I am afraid that eventually I’ll have to bite the bullet. With that in place, keeping the focus on the PDF by default would be trivial. (Of course you can always use C-l,t,f and the setting is actually persistent, in the sense that, if you close ST2 and restart it, the behavior should remain the same).

      • weel, I must be something wrong : this setting is not persistent for me … I have to C-l,t,f everytime every document … I have to say it is not such a big deal, but still weird

    • OH,I just saw your last update with the settings : great ! I just did not figure out yet how to modify the settings without modifying the file in the package directory : when I copy the file on my home and modify it it does not seem to change anything …

  18. Thanks for the great plug-in. Everything works out of the box except for the cite completion which does not work 😦

    • Have you tried the new keybinding? C-l, Ctrl-Space, where “C-” is Ctrl on Win and Linux and Cmd on OSX. See the README for more info.

    • Same here. Doesn’t work on a multi-file documents for me (Ubuntu)!

      • Traceback (most recent call last):
        File “./”, line 337, in run_
        File “./”, line 374, in run
        File “./”, line 34, in get_tex_root
        AttributeError: ‘NoneType’ object has no attribute ‘group’

      • I see a potential issue in get_tex_root. The %!TEX root = line must indicate the master file *with a .tex extension*. In fact, I think it has to be .tex, not .TEX. Can you confirm that this is what is causing you trouble?

      • Update: I have just pushed a commit that should robustify get_tex_root and hopefully avoid yoru issue. If I’m right, the problem was that the master file had to be specified with a .tex extension. The code now accepts .TEX as well, but does require an extension; if one is not provided, the plugin fails silently but at least it doesn’t crash.

      • Thanks for your reply. Actually I did specify the .tex extension, here is how my first line of several files look like :
        %!TEX root =

      • %!TEX root =

      • Oh I see it’s not possible to put it in here but it’s in the right format.

      • OK, this is strange. Can you please open an issue in github, where you should also be able to upload a (possibly complete) test file? Thanks!

      • I wanted to open an issue in the github but noticed that things have changed due to your latest update. Now I get this error : “Undefined control sequence. [\chapter]”.
        I googled this and found someone else also had a similar issue sometime ago and you asked him whether he has spaces in the folder names or not. Well I don’t have any spaces in the names.


      • Hmm… I just compiled a file with \chapter’s and all went well.. sorry to ask the obvious, but did you use a document class that does have the \chapter command (e.g., not “article”, but “book”)?

      • It’s strange ! reinstalled sublime and it got fixed ! Many thanks for your wonderful job.

      • You’re welcome 🙂

      • and the answer to your question yes I did define a documentclass.

        Thanks again

  19. I have the same problem as Arnaud. Tried it on a multi-file document and it did not work. Also tried it on a single tex file and it did not work.

  20. Can you attach the single file? Things are working here…

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s