lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marvin Humphrey <mar...@rectangular.com>
Subject [lucy-dev] Markdown for documentation
Date Sun, 13 May 2012 00:06:17 GMT
Greets,

The POD documentation that Perl users of Lucy see is mostly autogenerated
from "DocuComments" in our cfh files.  DocuComments probably look a lot
like Javadocs to most observers, though there are many similar
documentation systems out there[1].

Much of Lucy's documentation was originally written in POD, and there are
still some legacy POD-isms here and there, especially POD-style
L<links|perlpod>.  Mixing POD and C-style comments is awkard, though; we
should really find a better syntax for those.  Also, for inline code
snippets, we currently support XML-style <code>code tags</code>.  I think
it would be a mistake to continue the transition to XML-style, a la C#.

Conceptually, the option I find most attractive is integrating Markdown
with Javadoc-style @tags, which has been done more than once:

    http://www.stack.nl/~dimitri/doxygen/markdown.html
    http://code.google.com/p/markdown-doclet/wiki/Examples

Honorable mention goes to Scaladoc, which mixes @tags with Trac-style wiki
markup.

    https://wiki.scala-lang.org/display/SW/Syntax

None of those products would work for Clownfish as a direct dependency,
though.  Doxygen has its advantages, but it's huge, it's GPL, its
generated HTML is funky, it's completely baffled by our autogenerated C
code, and its Markdown integration is idiosyncratic -- in short, I don't
think it's in Clownfish's interest to lash itself to Doxygen.

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?

Marvin Humphrey

[1] http://www.stack.nl/~dimitri/doxygen/links.html

Mime
View raw message