"Smelling the barn"—an expression that horsey people use to describe the sudden enthusiasm of a horse when it nears the end of a long ride. Do horses really do that? Whatever; I'm starting to smell the end of this project. I'm alternating between writing the code that will call a Translator and updating the document that tells the Translator's author what will happen. And it all feels like it's coming together at last. I have serious hopes of delivering the 1.0 product by the end of this month!
But the API doc... I started writing it in Markdown. It's simple; it's designed for documenting code; it's also slightly less stupidly inconsistent than reST. But then I tried to process it for display. Aagghhh!
One would expect that John Gruber, the inventor of Markdown, could write an accurate preview widget—wouldn't one? So the first place I tried my document was at his "markdown dingus". And it is terrible! Although the sidebar clearly states that a four-space indent means a code block, my document has numerous indented code blocks and Gruber's "dingus" renders them all in normal text font. It preserves the line breaks in these sections, at least, but does not preserve the white-space indents.
Worse, it does not automatically escape either underscores or HTML codes within a code block. So where the code contains an underscore in a variable name, the underscore disappears and the "code" suddenly turns italic. And where there's a bit of HTML in the code block, it takes effect. It's just a mess. Shame on you, John Gruber.
There's a pretty decent Markdown extension for Chrome. It renders my code blocks fine. But I'm just confused because for Gruber's widget I have to escape underscores inside variable names, but then the Chrome widget renders the backslash. I'm going to assume that the Chrome extension is accurate (whatever "accurate" means when discussing Markdown). But Markdown is a mess, a very unsatisfactory medium. Ordinary manual HTML, like I do in this blog, would be less confusing for sure.
No comments:
Post a Comment