lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David E. Wheeler" <da...@justatheory.com>
Subject Re: [lucy-dev] Markdown for documentation
Date Sun, 13 May 2012 05:01:56 GMT
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


Mime
View raw message