TextMate News

Anything vaguely related to TextMate and macOS.

TextMate manual

I am planning to release 1.1 final next week. While I do get many repeated requests, one of the issues that has been hard to overlook lately is the lack of thorough coherent updated documentation.

This has now changed after spending a few weeks writing more or less full-time (so that’s why there has been no nightly builds, although I will likely put out one later today with a dozen minor items in the change log).

Here is the first public draft of the TextMate manual.

Don’t hesitate to post feedback as comments to this entry.

Currently the documentation is low on use-cases. I hope to iteratively improve this over time, as I think that when people ask for documentation they are in fact much more interested in how to combine the features of TextMate to solve the task at hand, than the core facts about how to move the caret and such.

This of course is quite a challenge, as the tasks and possibilities are infinite. I myself regularly find new ways to use TextMate to improve my workflow in ways I would not have thought of just a few weeks earlier. Writing the documentation was no exception. One of the cooler things I discovered was that I could add the command below as a preferences item to the entity.name.reference.markdown scope to have escape suggest completion candidates from my aggregated reference list, when inside a Markdown reference (given as [link text][REFERENCE]).

{ completionCommand = 'sed -n \
      "s/^\[\($TM_CURRENT_WORD[^]]*\).*/\1/p" \
   disableDefaultCompletion = 1;

Should you somehow have missed my countless references to Markdown then for the records let me just state that the documentation was written in Markdown and I absolutely love it!

categories General


Maybe a cookbook would be a nice format for use-cases. Maybe the wiki would be a nice location for a cookbook. Could the manual refer to cookbook items in the wiki?

This is great. I’m so glad to see a manual. Thank for putting your full time efforts into it. I did a quick scan of it and it looks really nice. I’m not a Textmate power user yet, but this will help me to become one!

A few days ago I spoke with some friends of mine in Silicon Valley in the U.S. and I told them about Textmate and they said, “we use BBEdit” and I told them that BBEdit is for old, stodgy people :-)

I guess what I’d like would be some HOWTO on using TextMate as its used in the Ruby on Rails videos. It looks awesome, but I can’t get stuff like ‘typing html and having it replace that with open and closing html tags’ for example.

Awesome! My chief complaint about TextMate has been answered! Thanks so much for the new docs.

16 December 2005

by William D. Neumann

1: You should put a link to the “printable” version on the first page. My first reaction upon seeing the opening page (well, second after “Damn that’s a big font!”), was “There’s no printable manual? Screw this…”

2: My standard complaint in the age of online publishing: HTML makes for a crappy printed page. You’ve taken some of the sting out of this by using a printing style sheet, but the quality of the printed page is still, to be charitable, lacking.

In particular, you end up with margins that are far too small (and hence, text that is far too wide), too many orphans and widows (though the newspaper style writing with lots of short choppy paragraphs minimizes this), examples that get split across pages, linked text that prints too light, and so on. There is also no table of contents (in the “printable” version) nor index for the documentation. A serious drawback.

I realize that it involves extra work to maintain two versions (though an awful lot of that work can be saved by tweaking markdown like this guy did http://www.luxagraf.com/archives/mac_os_x/hifitext to output latex code. Once you have that it’s just a bit more work to add latex specific tweaks, and the superior results are well worth it.

As I lamented the last time I commented on this subject, “Hundreds of years have been spent on figuring out what makes text pleasing to read and we’re willing to throw it all away for a bit of ease of publishing and distribution?”

3: Oh yeah. The content… lemme labor through it and I’ll get back to you.

jasper: I’ve considered opening up the documentation for user comments.

mattl: that’s a command in the HTML bundle.

William: I will likely provide a PDF made with LaTeX — I’ve experimented some with this but it’s not that easy mainly because of my heavy use of special glyphs, although XeTeX handles that, but none of the Markdown => LaTeX worked out-of-the-box for me, so likely I’ll have to write something myself (not that it’s that big a deal, but main focus was on getting out the first draft).

I will also provide table-of-contents with the printout and link to the printout from first page. As mentioned, it’s first public draft! :)

William said:
“Hundreds of years have been spent on figuring out what makes text pleasing to read and we’re willing to throw it all away for a bit of ease of publishing and distribution?”

um… yes? And doesn’t “bit of ease” discount it too much?

Allan: Thanks for the effort! I, for one, am glad to see it even if it is less than perfect. As we all know, everything you put out gets better and better over time. Looking forward to the “cookbook”.

Thank you, thank you, thank you.

I had managed to figure out some of the various productivity-enhancing drugs that you have included in the product, but the manual has now revealed even more of them; hence my continued addiction to TextMate.

Keep up the passion! It too is addictive, or should I say, contagious.

I just updated the link on the front page of the wiki where it points to http://macromates.com:3000/read/book/1 with link text as “taking place here”. It now points to the new manual.

Thanks for the ongoing effort with this tool. It keeps getting better and better and the manual will be of great help to getting even more out of the tool.

The manual is really good. I’m reading it now, and I already found some things I didn’t know although I’m faily TM-fluent. And it’s cleaner and more to the point than most manuals I’ve seen.

First off, I’d like to say I had to stop for a moment out of sheer joy when just now I opened up the two LaTeX templates. I hadn’t even gotten to reading the manual yet.

I think in section 5.2.2 Latex it says that the “Typeset & View (PDF)” command is supposed to be ⌘R. However, I think it is ⌘B (unless it’s been changed in one of the bleeding edge releases).

17 December 2005

by William D. Neumann

tom wrote: um… yes? And doesn’t “bit of ease” discount it too much?

Not at all. The difference in difficulty between creating a document with something like markdown and something like *tex is negligible. And when constructing a complex document, markdown-style tools are harder to use.

What’s more, tools like markdown which are based on an internet publishing model have limited use outside the internet (which is, in turn, limited by the need to have a computing device online and in front of you). *tex, which leverages all those years of knowledge about typesetting, can be used to create documents that are not only of publishing quality, but are easily distributable on the internet as pdfs, so there’s little win there in the ease of distribution area (really limited to areas like display on handheld devices).

I see that having the manual online and updated frequently is a great way to go. But in some situation I really would like to have this beauty on my harddrive for offline reading. Will this ever be downloadable in one piece? With table of contents, images, links and all? This would be my personal icing on the cake.

But still, this is what we were all waiting for. Thanks for doing the right thing. Merry Christmas, everybody, btw.

William: PDF’s are awfull for reading on-screen, which most will do with the manual. They also do not support deep-linking, can’t be used as the help book distributed with TextMate, and there are the problems mentioned with UniCode glyphs, which is a requirement for such manual.

Adding to that, I don’t think the difference between writing in Markdown and LaTeX is neglibable (and I have written longer texts using both systems).

So as much as I love LaTeX, it’s certainly a very bad choice for writing the TextMate manual — as mentioned though, it’s likely that there will be a PDF produced by converting the HTML to LaTeX (and using XeTeX for the Mac glyphs).

As you should know, HTML is just markup, not presentation, so by writing the manual in Markdown/HTML, I do not limit myself to a given link color, margin size, or similar.

Tilman: Try in TextMate to press ⌘? and you’ll get the offline version.

Haven’t had a chance to read the manual yet, but assuming its anywhere near as good as TM itself, I’d pay good money for a dead tree version.