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.