On May 12, 2012, at 5:06 PM, Marvin Humphrey wrote: > Conceptually, the option I find most attractive is integrating Markdown > with Javadoc-style @tags, which has been done more than once:
+1. Love Markdown, warts and all. > Instead, I think it might make sense to work with the C library Sundown: > > https://github.com/tanoku/sundown > > At first look, Sundown seems appropriate as a dependency for us: > cross-platform, no configuration, just a handful of .c and .h files. > > Here's an approach I hope will work well: > > 1. Extract comment text from .cfh file. > 2. Remove C comment artifacts and make content flush left. > 3. Preprocess select @tags, converting them into an intermediate > Markdown format. At this point, the transformation of the original > comment into pure Markdown is complete. > 4. Parse intermediate Markdown with Sundown. > 5. Use Sundown plus custom plugins to render content in host-specific > output formats, e.g. POD, Rdoc. > > Committing to Markdown as Clownfish's documentation language also gives us > the option of writing docs as pure .mdtext files. > > Thoughts? The one complaint I have about Sundown is its lack of support for definition lists. https://github.com/tanoku/sundown/issues/10 This is especially important, I find, for documenting lists of parameters for methods. Definition lists are perfect for this. POD does that, too, with the `=item text` syntax. But Sundown does not. At least, not yet. Maybe you'd want to add it? Last time I asked tanoku about it, he said that the PHP Markdown syntax is terrible to parse. https://twitter.com/tanoku/status/197424671887589376 Anyway, just something to be aware of. Other possibilities: * [Discount](http://www.pell.portland.or.us/~orc/Code/discount/). BSD license. Fast, but kind of weird, both in its additional syntax (definition lists are kind of ugly) and in its interface. * [peg-multimarkdown](https://github.com/fletcher/peg-multimarkdown). But that's just too bloody big, isn't it? * [upskirt](http://fossil.instinctive.eu/libupskirt/index). From which Sundown was forked. Bare-bones parser-only implementation. Might require more work to use, I don't know. Anyway, Sundown seems decent overall, so it might be the best choice, though I think upskirt at least deserves a look. Best, David
