Just posted the following to my blog (you can post feedback here or on the blog post, if you have any):
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.
<!--more-->
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](http:// macromates.com/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] (http://daringfireball.net/projects/markdown/) then for the records let me just state that the documentation was written in Markdown and I absolutely love it!
Le vendredi 16 décembre 2005 à 13:08 +0100, Allan Odgaard a écrit :
Just posted the following to my blog (you can post feedback here or on the blog post, if you have any): [...]
Very nice indeed. Will the final release be in HTML format like this? It would be nice as it would allow everyone to customize it!
Ever thought to publish it in a Wiki? (like, say Wikipedia ;) so that every user can add his own material (mainly examples).
Have a nice day,
On 16/12/2005, at 17:07, José Campos wrote:
[...] Will the final release be in HTML format like this? It would be nice as it would allow everyone to customize it!
The plan was HTML for the online + help book and then a PDF version for printing. But whatever people want, really, as long as it's not too much work for me :)
Ever thought to publish it in a Wiki? (like, say Wikipedia ;) so that every user can add his own material (mainly examples).
I'd like to open up the pages for user comments -- the important thing however is that it is easy for me to maintain, which currently is flat files in Markdown format, but that doesn't exclude allowing comments to be associated with each page.
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.
Fantastic! Just browsed through and it looks great! Will this be the help section of TM 1.1? If not, maybe you can make PDF available? I'd like to have a local copy to reference.
Anyway, it looks very nice Allan! First Rails 1.0, now this, and next week TM 1.1. Now if Steve Jobs would only bring us some speedy Intel laptops next January ;-)
Sean
:::: DataFly.Net :::: Complete Web Services http://www.datafly.net
It currently is, but I may pull it from the nightly builds (and then link to the online version), since with all the screen grabs it's actually adding 1.5 MB to the download.
You could make the images remote links couldn't you? Might be better to include the images for the major releases but for the nightlies it'd work.
On Dec 16, 2005, at 7:08 AM, Allan Odgaard wrote:
Should you somehow have missed my countless references to [Markdown] (http://daringfireball.net/projects/markdown/) then for the records let me just state that the documentation was written in Markdown and I absolutely love it!
Meta question: are you maintaining the item numbering manually, then? To me, the big weaknesses in Markdown have been lack of support for (1) internal references and (2) autonumbering.
Chris
On 17 Dec 2005, at 03:47, Chris Thomas wrote:
Meta question: are you maintaining the item numbering manually, then? To me, the big weaknesses in Markdown have been lack of support for (1) internal references
Ah, I wondered about that! I spent the past few days working on documentation in Markdown and really enjoyed working with it, but couldn't find a nice way of doing internal references, which surprised me. I was kinda hoping that doing something along the lines of "see #Semantic Use of XHTML# below" would automagically link to the section headed "Semantic Use of XHTML"...
and (2) autonumbering.
I've a sneaking suspicion that you could do that with CSS: http:// www.w3.org/TR/CSS21/generate.html#counters
On 17/12/2005, at 10:16, Graeme Mathieson wrote:
Meta question: are you maintaining the item numbering manually, then? To me, the big weaknesses in Markdown have been lack of support for (1) internal references
Ah, I wondered about that! I spent the past few days working on documentation in Markdown and really enjoyed working with it, but couldn't find a nice way of doing internal references, which surprised me. I was kinda hoping that doing something along the lines of "see #Semantic Use of XHTML# below" would automagically link to the section headed "Semantic Use of XHTML"...
It only has named references, like: see [language grammars] [LanguageGrammars]. And then to tell it about the link target, you'll need this later:
[LanguageGrammars]: language_grammars.html#intro
I have an aggregated reference list with all my references, so effectively I do: "cat some_file.markdown references|Markdown.pl", and I use named references for all but external links.
I have a script to update my references file (i.e. find named references in the document which have no entry in the references file, and add one as a stub).
Further more, when I generate the HTML I ensure that each heading gets its name (in a lowercased, underscore-separated version) as ID, so that I can link to all headings in the documentation. I.e. basically the following transformation happen:
# Language Grammars => <h1 id="language_grammars">Language Grammars</ h1>.
So while I can't insert labels, each heading is implicitly a label. I don't link to figures and tables, so for me that's all I need.
and (2) autonumbering.
I've a sneaking suspicion that you could do that with CSS: http:// www.w3.org/TR/CSS21/generate.html#counters
I don't think this is actually implemented by any of the browsers ;) I also have my chapters in separate files, so even if it was, I'd still need to calculate the starting number for each chapter.
So I have a script to auto-number my sections. It's the same script which inserts the ID argument on headings, and it also puts the previous/next headers/footers in the result, extract the table of contents, and add dimensions (width/height) to image tags, and it uses `tee` to also create the all_pages.html (for printing) at the same time.
On 17.12.2005, at 10:51, Allan Odgaard wrote:
I have a script to update my references file (i.e. find named references in the document which have no entry in the references file, and add one as a stub).
So I have a script to auto-number my sections. It's the same script which inserts the ID argument on headings, and it also puts the previous/next headers/footers in the result, extract the table of contents, and add dimensions (width/height) to image tags, and it uses `tee` to also create the all_pages.html (for printing) at the same time.
As I am writing some documentation in markdown myself at the moment it would be a great help if you could share those scripts (along with your modified markdown bundle maybe). I bet there is more magic in them than I could come up with when trying to write them myself :)
Soryu
PS: Merry Christmas, everyone.
On 23/12/2005, at 13:17, soryu2@gmail.com wrote:
As I am writing some documentation in markdown myself at the moment it would be a great help if you could share those scripts (along with your modified markdown bundle maybe).
I've attached an archived version of my `manual` folder, which is self-contained. My Markdown bundle modifications are limited to the completion command mentioned (for references) and a custom drag command for images to work with my path setup.
The archive contains:
pages/*.markdown -- the actual manual (written in markdown.) images/*.png -- the images (although I removed these from the archive.) templates/*.rhtml -- three templates for how the Markdown should look as HTML. markdown.references -- my reference list used by the pages.
update_references.sh -- grep through `pages/*.markdown` for references not in the list (and add these with a stub) plus tell if there are unused references.
add_image_size.rb -- add width/height arguments to image tags which lack them (read from stdin, write to stdout), also converts the src argument to an absolute (macromates.com) path. This is used by `generate.rb`.
generate.rb -- this generate HTML versions of the markdown pages, it writes these to `html`. The script goes through `pages/*.markdown` in alphabetital order and strips any numeric prefix in the HTML versions.
You can provide other templates or another output folder to the `generate.rb` script. E.g. to generate the online version of the documentation I call:
./generate.rb \ -toc_template="../site/templates/sidebar.rhtml" \ -chapter_template="../site/templates/doc_chapter.rhtml" \ -all_template="../site/templates/doc_all.rhtml" \ -output_dir="../site/html/textmate/manual"
In practice you should be able to just replace the contents of `pages` with your stuff, and run `./generate.rb` (with `manual` as cwd) -- though you'll have to modify the `add_image_size.rb` to not have it alter relative image paths (and/or edit `generate.rb` from where it's called, which btw also set `images` as cwd for this script).
Allan,
I started using your layed out manual folder for a documentation project I have, however, i've run into an issue. I have 2 pages right now, preface and Developer: Reports API
What's happening, is i keep getting this funky text at the bottom of the developer page:
[ActivatingBundleItems]: bundles.html#activationofbundle_items []: MISSING []: MISSING
What's happening, is i keep getting this funky text at the bottom of the developer page:
[ActivatingBundleItems]: bundles.html#activationofbundle_items []: MISSING []: MISSING
Well,
of course you should clear the markdown.references file first. You won't have the same references as Allans Manual I guess ;)
Soryu.
Thanks,
i could have sworn I did that already, but I guess I didn't..
-- Eric Coleman
On Jan 2, 2006, at 7:40 PM, soryu2@gmail.com wrote:
What's happening, is i keep getting this funky text at the bottom of the developer page:
[ActivatingBundleItems]: bundles.html#activationofbundle_items []: MISSING []: MISSING
Well,
of course you should clear the markdown.references file first. You won't have the same references as Allans Manual I guess ;)
Soryu.
For new threads USE THIS: textmate@lists.macromates.com (threading gets destroyed and the universe will collapse if you don't) http://lists.macromates.com/mailman/listinfo/textmate
Hi Allan,
I studied the documentation yesterday night: The documentation is just awesome!!! I learned quite a few tricks and keystrokes: The more I know about TextMate the better, it is a joy to work with!
Thanks for your great work Ruben
On 12/16/05, Allan Odgaard throw-away-1@macromates.com wrote:
Just posted the following to my blog (you can post feedback here or on the blog post, if you have any):
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.
<!--more-->
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](http:// macromates.com/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] (http://daringfireball.net/projects/markdown/) then for the records let me just state that the documentation was written in Markdown and I absolutely love it!
For new threads USE THIS: textmate@lists.macromates.com (threading gets destroyed and the universe will collapse if you don't) http://lists.macromates.com/mailman/listinfo/textmate
Hi all,
In the latest update to TextMate, 1.1b17 (847), the behavior of moving around in a document by option-arrows has changed. (Or, maybe it changed before then and I didn't know it.)
For example in the paragraph above, before the change, moving by option-right-arrow with the cursor at the beginning of the line would take the cursor to the end of "In". Subsequent option-right-arrows would move from "the" to "latest" to "update" etc.
Now, though, the option-right-arrow takes the cursor to the end of "TextMate" and then to the decimal point in "1.1b17" and then to the left of the parenthesis of 847.
It would seem that moving by option-arrows would match the behavior of most other OS X apps. Mail, for example, has the expected behavior of moving word by word instead of by punctuation marks. Perhaps I have a corrupted install? Or, is this an expected change?
Thanks for a great application!
--Tracy
On 19/12/2005, at 6:09, Tracy Ruggles wrote:
[...] Now, though, the option-right-arrow takes the cursor to the end of "TextMate" and then to the decimal point in "1.1b17" and then to the left of the parenthesis of 847.
Go to Preferences -> Text Editing and see if it's not because you added a space to the word characters.
On Dec 19, 2005, at 7:44 AM, Allan Odgaard wrote:
[...] Now, though, the option-right-arrow takes the cursor to the end of "TextMate" and then to the decimal point in "1.1b17" and then to the left of the parenthesis of 847.
Go to Preferences -> Text Editing and see if it's not because you added a space to the word characters.
Well, that was it. My keyboard has some sticky keys and every once in a while it thinks I'm holding down the apple/cmd key when I'm not and if I happen to type a comma when that's happening, then the prefs panel of the app I'm in comes up and any characters that I'm typing gets sent to the prefs panel (and in this case there was a space in there)... PEBKAC!
Thanks! --Tracy
inestimably useful. Thanks - i only get to use TM at home and need this sorely.
I think this is the killer feature TM has been lacking ;-)
cheers, David
On 16/12/2005, at 11:08 PM, Allan Odgaard wrote:
Just posted the following to my blog (you can post feedback here or on the blog post, if you have any):
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.
snip-
-
Alain Ravet -
Allan Odgaard -
Chris Thomas -
David Lee -
Eric Coleman -
Graeme Mathieson -
José Campos -
Michael Sheets -
Ruben Bakker -
Sean Schertell -
soryu2＠gmail.com -
Tracy Ruggles