How and Why to use TextMate for LaTeX

Latex LogoIn a previous post, we talked about how to install latex. (It would be really great if someone could synthesize and transfer the information in that post to the LaTeX wiki page.) Tom also recently gave us a rundown the various text editors for OS X. Here, I’m going to go through the details of setting up and using TextMate as your primary LaTeX editor.

Why TextMate?

The main reasons I use TextMate are:

It’s a multitasker
It’s one application that includes language specific bundles to meet all of your text editing, coding, and web development needs. I use it for editing plain ascii files, writing blog posts, editing CSS, writing code in IDL and Python, and writing LaTeX. TeXShop, on the other hand, is a unitasker—only good for LaTeX—while TextMate, like emacs, is good for everything.
Consistent keyboard shortcuts
The keyboard shortcuts are consistent between the various bundles. Commenting text is always ⌘/, regardless of what type of code you’re writing. You don’t have to remember when to use #, % or <!–…–>. Similarly, “running” the code, texifying the tex, refreshing the browser displaying the HTML is always ⌘R.

I think the primary reason many people hesitate to use TextMate is cost. It’s not cheap: an individual license is $56 or $48 with the educational discount. But, as I always say, you get what you pay for and this is money well spent. This summer, I paid $170 for a five-seat license for my group.

The only feature that I wish TextMate had is split-screen editing. But I’m hoping it won’t be too long before that’s implemented.

LaTeX in TextMate

There are two (relatively old) screencasts that demonstrate the beauty of the LaTex Bundle in TextMate much better than I can describe it.

  • LaTeX Intro: Includes folding markers, insert item shortcut (⌅ = enter, fn-Return on laptops), smart typing/autocompletion, columnar editing mode (similar to rectangle mode in emacs), insert environment shortcut (⌘{), typeset and view (⌘R, regardless of what he says). The bit at the end about how to use PDFSync and having to setup shell variables is outdated; see below for updated instructions.
  • LaTeX Projects: Includes using projects to deal with complex LaTeX documents that contain lots of includes, toggle comment (⌘/), ⇧⌘-click on PDF to go back to tex, file manager (⌘T), go to PDF (^⌥-⌘O), section navigation (⇧⌘T), setup master tex file, using BibDesk to include citations, and using \label and \ref.

Setup

There are a couple webpages out there that describe various parts of the process of setting up the LaTeX bundle in TextMate, but I’ve found them to be outdated and/or incomplete. The steps outlined below should take you from a fresh install of TextMate and LaTeX to the final product of PDF documents. Once these steps get vetted, they will be moved to the wiki (eventually). (Update: TextMate wiki page created.)

  • Set Latex Bundle preferences: Bundles > LaTeX > Preferences. These options are now set in this dialog box rather than via shell variables.
    • Default engine: pdfTeX. In this day and age, there’s no reason to go through the whole dvi > ps > pdf nonsense. Use pdfTeX to go straight to PDF. pdfTeX can include TIFF, JPG, and PDF figures but to include EPS, add \usepackage{epstopdf} in the preamble.
    • Options: -shell-escape. Need for epstopdf to work.
    • Use latexmk.pl
    • View in: Skim. Must use Skim for PDFSync to work.
  • Set master tex file in project so texify (⌘R) shortcut will work properly regardless of which file is active.
    • In project drawer, with nothing selected, click ⓘ on the bottom bar of the project drawer.
    • Add variable TM_LATEX_MASTER and set it to the full path of the primary tex file for that project.
  • PDFSync to easily go between PDF and tex: ⇧⌘-click in PDF to go to source, ^⌥-⌘O to go from source to pdf.
    • Must use Skim to use PDfSync.
    • In Skim, Preferences > Sync, Set PDF-Tex sync support to TextMate Preset.
    • No longer need \usepackage{pdfsync} in the preamble.
  • Make sure LaTeX executables are in TextMate’s Path. If TextMate’s PATH variable doesn’t exist or doesn’t include the path to latex, the first time you run tex (⌘R), TextMate will give you an option to set it to your current PATH: Set PATH and Relaunch. Click that button. Then, go back to Preferences and add the tex path to the end if necessary. Preferences > Advanced > Shell Variables. Add /usr/texbin, /opt/local/bin/latex, or output of which latex to PATH.
  • OPTIONAL: When I upgraded to 10.6, I started getting some error in the LaTeX log about Cannot find executable for CFBundle 0x100121ca0 . Turns out it was some Adobe 32-bit to 64-bit problem. Here’s the fix.

Alright, that should do it. What do ya’ll think? Have I convinced anyone or is everyone going to stick with TeXShop?

14 comments… add one
  • Mike Cushing Oct 11, 2010 @ 11:14

    I still use X11 emacs for all of my editing, and in particular, LaTeX needs. The one thing that has kept me there has been J.D. Smith’s LaTeX+Emacs tip at his website (http://tir.astro.utoledo.edu/jdsmith/code/latex_emacs.php) that allows you to do the equivalent of latex+bib+latex+latex with a single key, F5. F6 views the document in XDVI and “queue[s] it to the exact enclosing paragraph, table, figure, etc., highlighting it with a colored box around it.” “In XDVI, control-click on any paragraph, table, figure, etc. to have your LaTeX buffer automatically queued up at that exact position. Wow.” On the same page, he shows how to search your .bib file and insert a reference at the current cursor position with the keystroke C-c [. Both tips have made my writing life MUCH better and will keep me using X11 emacs for a long time.

    The one problem I am hoping someone may solve if they try this tip is a “broken” F6. Once I have an xdvi window running, I can’t hit F6 again to highlight text or another XDVI window will appear. This hasn’t always been the case but seems to have started with 10.6. F5 still updates the XDVI window so it isn’t a show stopper for me.

  • Kelle Oct 11, 2010 @ 14:52

    On one hand, don’t fix it if it ain’t broke. If you like working in X11 and this is working for you, great!

    BUT, all of that functionality is in TextMate:
    – cmd-R does the whole latex, bibtex, latex thing (that’s what I call “texify”) and displays the *PDF*, not the DVI.
    – ctrl-alt-cmd-O in the latex takes you to that location in the PDF. It will highlight the text, but doesn’t draw a pretty box. (this shortcut could be changed if you wanted.)
    – shift-cmd-click in the PDF takes you to that location in the tex.
    – alt-Esc will give you a popup with your current .bib library, and will ever filter it based on what you’ve already typed. e.g., if I type \cite{Cushing}, then do alt-Esc, it will only show me the refs with Cushing somewhere in them. (but it is case sensitive.)

  • Eric G. Barron Oct 11, 2010 @ 17:11

    The only feature that I wish TextMate had is split-screen editing. But I’m hoping it won’t be too long before that’s implemented.

    The author said that split-screen editing will be in TextMate 2. The bad news is, it looks like TextMate 2 is vaporware. It was supposed to be released *years* ago. I guess the author wasn’t kidding when he said it would be released “after Leopard” or that it was his Duke Nukem: Forever (though that might even be a bad comparison, given that now even DNF has an estimated release date!).

    Anyway, I actually dislike the one-editor-for-everything approach. I suppose it works if one only handles small projects, but for large projects I prefer specific tools that are designed for specific purposes. For me, that means NetBeans for C/C++, Javascript, and CSS (though I might go back to CSSEdit for that), PyCharm (a new, *excellent* Python IDE) for Python/Django, and…I’m still looking for a good editor for LaTeX. I only need syntax highlighting and basic macro functionality, since I already have an automated workflow in place for processing the LaTeX file into a PDF, with different prepress options depending on the project.

    I used to use TextMate 1.5 for LaTeX until it started crashing in Snow Leopard. Apparently, one or more of the bundles I had installed were the source of those crashes…and apparently TextMate will just crash due to malformed bundles instead of safely handling them. I’m looking forward to taking a look at UltraEdit (http://www.ultraedit.com/products/mac-text-editor.html) when the Mac version is released. I’ve heard from multiple sources that UltraEdit is the best text editor for Windows, but I’m not sure it’s LaTeX support is all that good.

  • Florian Oct 12, 2010 @ 9:32

    I must confess, that I never liked the ‘one-for-all’ approach and the several dicussions about TextMate remind me of similar discussions on Emacs years ago. Certainly, you can use Emacs to do almost everything but is it always the best choice? I think, this question is justified, although poeple might find different answers depending on their pesonal needs. I can only write about my own personal needs here, of course.

    I tried TextMate, but have not found it to be that superior that it would justify its rather high price, and so I deleted it after the trial period. Don’t get me wrong, I’m not a ‘every-software-must-be-free-of-charge’ dogmatic and actually purchased Papers, Versions and the Intel Compilers (which are all great pieces of software), but I do a strict cost-benefit analysis on every application before I spend money on something. When it comes to editors, however, I’m rather old school (although I’m not that old…). For coding, I use vim, mainly because it is available everywhere which is a huge advantage if one needs to code on clusters or supercomputers, where often some clone of vi is the only editor available.

    Regarding LaTeX, here I have always used a specialized environment. In my pre-Mac days, I stuck to some flavour of Linux/KDE and used Kile for texing. These days, on the Mac, I use TexMakerX (don’t like TexShop) and I’m pretty happy with it: I configured it to do the whole pdflatex-bibtex-… stuff just by hitting , and PdfSync with Skim also works nicely (although configuring this was not so straightforward).

  • Kelle Oct 12, 2010 @ 19:53

    Thanks for all of the great other perspectives! It’s funny but I think what really put me over the edge was getting frustrated trying to remember different keyboard shortcuts for the same task in different apps. My fingers are only starting to forget ctrl-x-s in favor of cmd-s. It’s also nice when multitasking to be able to have just one app open instead of several.

    But what I’m really surprised about is the lack of an outcry for TeXShop. I definitely have the impression that it’s the most widely used tex editor….

  • Michael Aye Oct 14, 2010 @ 10:07

    I tested textmate before and also did not find it THAT superior, but i will give it another go now, considering it’s all-implemented approach for LaTex (which I didn’t use so much recently).
    But I’m also quite worried about TM2.0, as I found blogpost from Allan saying last year in September, that 2.0 is almost done, but now, 1 year later, we even don’t have any date suggestion. Guess it will never come. 🙁

  • Panagiotis Atmatzidis Jan 12, 2012 @ 8:39

    Hello,

    thanks for the great info. I can’t find pdftex on my textmate’s engine menu. It’s weird because pdftex and pdflatex sit on the same directory:
    greyjewel:~ atma$ which pdftex pdflatex
    /usr/texbin/pdftex
    /usr/texbin/pdflatex

    Is there any way I can make TextMate list pdftex on the engine selection?

    Thanks

  • Kelle Mar 20, 2012 @ 20:03

    In the process of getting this setup in TextMate 2:
    If Error = “There is a loop in your ‘%!TEX root =’ directives”
    Remove %!TEX root = declaration from the main file. Only need to set Master File for child files.

  • michele Mar 7, 2013 @ 11:47

    Hi, I did not find how to set up bibdesk completion in the latex bundle, do you have any link I can refer to?

    • Gunnar Mar 14, 2013 @ 2:21

      Once you’re within the brackets of a command like \cite{…}, and start typing something, you can press Esc. That’s the shortcut for the generic Edit > Completion > Next Completion command, which in this case cycles alphabetically through all the BibDesk keys that happen to *start* with the exact (case-sensitive) string you’ve typed. You can cycle backwards with shift-Esc.

      But I think what you’re referring to is the much more useful alt-Esc, which brings up a little window with all the BibDesk entries that *contain* the (again, case-sensitive) string you’ve started typing. In the nested pull-down menu that command is hidden away as Bundles > LaTeX > Insert > “Command Completion” (because it works for other aspects of LaTeX code as well).

  • Moses Dec 28, 2013 @ 19:42

    Thank you for the guidance here, just transitioned from SublimeText 2 to Textmate, and it seems to have gone super smoothly. I followed all your guidance, except:

    Set master tex file in project so texify (⌘R) shortcut will work properly regardless of which file is active.

    In project drawer, with nothing selected, click ⓘ on the bottom bar of the project drawer.
    Add variable TM_LATEX_MASTER and set it to the full path of the primary tex file for that project.

    I could not figure where this is? But ⌘R builds just super fine. PDFSync is also great.

    Thank you.

    P.s. Believe it or not Textmate looks more beautiful than SublimeText

  • Kenneth T. Kjelsnes Oct 7, 2014 @ 3:11

    Thanks for this guide!

    But I have encountered a problem I can’t find any information about in your guide or any other place which I hope you can help me with:

    The document gets compiled with dvips + GPL Ghostscript 9.10, not pdflatex.

    I’ve set pdflatex as default engine in Bundles > LaTeX > Preferences.

    I don’t use Projects, I just open the .tex-file and compile it by using CMD-R. I’ve tried the Projects way too and added the TM_LATEX_MASTER variable, but with the same result upon compiling.

    I have these three shell variables under Preferences > Advanced > Shell Variables:

    PATH /usr/bin:/bin:/usr/sbin:/sbin:/usr/texbin/latex:/opt/local/bin/latex

    PATH /opt/local/bin:/opt/local/sbin:/Users/kenneth/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/opt/X11/bin:/usr/local/MacGPG2/bin:/usr/texbin

    PATH /opt/local/bin:/opt/local/sbin:/Users/kenneth/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/opt/X11/bin:/usr/local/MacGPG2/bin:/usr/texbin

    The main problem with the resulting PDF is that I have an item in my references list with a long URL that doesn’t wrap over several lines but continues beyond the right border upon compiling with dvips and gs. When I manually compile with

    pdflatex file
    bibtex file
    pdflatex file
    pdflatex file

    … I get the desired result. But this is a bit tedious and I’m very interested in using TextMate all the way.

    • Abhimat Mar 13, 2015 @ 22:02

      Hi, I stumbled across your question when I was trying to figure out a solution to the same problem.

      One solution that I have discovered since is inserting the line “%!TEX TS-program = pdflatex” in your tex file. This forces the script that typesets your file in TextMate to use pdflatex instead of that whole dvips + GPL Ghostscript 9.10.

      This is kinda not ideal, since ideally it would use pdflatex like you tell it to, but it works. I’m still trying to figure out what causes it to switch away from the pdflatex engine in the bundle. Will update if I do find out, but a workaround until then.

  • Sami May 17, 2015 @ 5:46

    Hi,

    I did not find anymore these features “insert item shortcut (⌅ = enter, fn-Return on laptops)” and “columnar editing mode” in TextMate 2. I did not find them in the homepage’s search. Do they exist anymore?

Leave a Reply

Your email address will not be published. Required fields are marked *