[TxMt] TextMate Manual

[Allan Odgaard]

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.