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" \
      "$TM_DIRECTORY/markdown.references"';
   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!

16 Comments

  1. 16 Dec 2005 | # jasper wrote…

    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?

  2. 16 Dec 2005 | # Harrold wrote…

    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 :-)

  3. 16 Dec 2005 | # mattl wrote…

    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.

  4. 16 Dec 2005 | # Matt Ronge wrote…

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

  5. 16 Dec 2005 | # William D. Neumann wrote…

    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&gt; 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.

  6. 16 Dec 2005 | # Allan Odgaard wrote…

    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! :)

  7. 16 Dec 2005 | # tom wrote…

    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".

  8. 17 Dec 2005 | # Bob Monsour wrote…

    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.

  9. 17 Dec 2005 | # Bob Monsour wrote…

    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.

  10. 17 Dec 2005 | # Gerry wrote…

    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.

  11. 17 Dec 2005 | # mardoen wrote…

    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.

  12. 17 Dec 2005 | # Steven Hepting wrote…

    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).

  13. 17 Dec 2005 | # William D. Neumann wrote…

    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).

  14. 20 Dec 2005 | # Tilman wrote…

    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.

  15. 20 Dec 2005 | # Allan Odgaard wrote…

    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.

  16. 22 Dec 2005 | # kellan wrote…

    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.

Comments closed, you can use the mailing list for discussion.