lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joe Schaefer <>
Subject Re: [lucy-dev] Markdown for documentation
Date Fri, 18 May 2012 03:30:18 GMT
FWIW we finally settled on the python markdown implementation
for the www sitelargely because it has sane extension mechanisms.

We take advantage of that in order to properly identify headings
and such, that works great.  The table fu is kinda-sorta useful
in many cases, but it's very limited.  Automatic code highlighting
is nifty when it's using the right programming language ;-).

Yes I am aware that socially the markdown situation sucks, but
we had to pick something.  Markdown at least has name-brand
recognition for what little it's worth, we could've went with
Textile if there was a decent webgui for editing it.

FWIW python and php at one point or another tried to keep parity
with markdown extension features.  Dunno where that stands
today.  But really from a usage standpoint nobody complains
about which version of markdown you're using from a holier-
than-tho perspective, if it works go for it.

> From: Marvin Humphrey <>
>Sent: Thursday, May 17, 2012 11:18 PM
>Subject: Re: [lucy-dev] Markdown for documentation
>Hi David,
>As this discussion has progressed, I've been having second thoughts about
>Markdown.  Perhaps we should consider reStructuredText as an alternative.
>In my opinion, our number one priority should be to commit to an external spec
>that is carved in stone.  Debating lightweight markup syntax might be even
>less fun than debating query parser syntax. :P  By implementing an
>authoritative spec, we limit the scope of debate and shut down a lot of
>bikeshedding before it starts.
>To my mind, the stability of the Markdown spec is one of its most
>attractive features.  However, after further investigation, I have come to
>understand that the spec is rarely implemented as-is and that the Markdown
>community is deeply Balkanized and embittered on the subject of extending
>it[1].  I'm uneasy about inviting Markdown's controversies into our house.
>My preference is still for vanilla Markdown, more or less.  To simplify
>things, let's tweak the proposal to relegate @tags to the end of the comment,
>eliminating inline @tag expansion.
>    A DocuComment has two sections.
>        body
>            Description, formatted in Markdown.  The first sentence must be a
>            summary that can stand on its own.  Terminated by the first line
>            which begins with an "@" character or by the end of the comment.
>        tags
>            The comment may end with an optional tags block.  Each tag begins
>            with a supported @label at the beginning of a line, and is
>            terminated by either the next tag or the end of the comment.
>There's only one Markdown extension I believe we can't live without: links
>without a protocol should be interpreted as API links.
>    @param query A [Query](Lucy::Search::Query).
>Then there's one more change I'd consider optional, since nearly all Markdown
>implemenations have it: disable intra-word emphasis so that foo_bar_baz
>doesn't become foo<em>bar</em>baz.  I don't really care one way or the other
>because 99% of the time `foo_bar_baz` should be enclosed in backticks.
>I realize that by adding those two extensions we start down the slippery
>slope...  IMO, that's an argument against Markdown...
>I hope that's good enough.  If it's not -- if we believe that ultimately it
>will be necessary to add additional extensions -- then I think we ought to
>consider reStructuredText instead.
>From a high level, the syntactical differences between reStructuredText and
>extended Markdown are IMO superficial and the feature sets are similar -- but
>reStructuredText has a canonical spec which has been stable for 10 years.
>reStructuredText is like extended Markdown, minus the bikeshedding and the
>resentment towards the original author.
>> I prefer definition lists to bulleted lists, myself.
>Fortunately, the choice of whether we expand @param tags to bullet-lists or
>definition-lists is an implementation detail which is separate from whether we
>support lightweight markup within comments.  Let's leave this topic for
>another day.
>> Well, MultiMarkdown is pretty well accepted as the #2 definition. Most
>> implementations follow its examples (FBOFW).
>I'm skeptical.  From what I can tell, "GitHub Flavored Markdown" -- a
>particularly destructive variant given how incompatible it is with the
>original Markdown spec -- looks like a significant competitor.
>And here's what happened when someone tried to assert the dominance of
>MultiMarkdown on the markdown-discuss list last October:
>    > pandoc assessed 'em all, and decided on multimarkdown.
>    Huh? No. Pandoc's markdown extensions aren't the same as mmd's. I have
>    explained in earlier posts why I don't like mmd's table and metadata
>    syntax. Pandoc goes back to 2005 and was not influenced by mmd.
>Adjudicating internet popularity contests is tiresome. :P
>> Note that Sundown supports quite a lot more than just vanilla Markdown. How
>> would you enforce that?
>It looks like you have to enable syntax extensions manually in Sundown -- so
>we "enforce" vanilla Markdown simply by not enabling those extensions.
>However, I'm concerned that choosing Sundown may set us up for failure because
>it means that we'll have this argument again later with someone who is
>*outraged* to discover that we've got their pet Markdown extension disabled.
>That's why I would like to determine whether we have consensus about forgoing
>additional Markdown extensions.  If we don't have consensus, we should
>evaluate reStructuredText.
>Marvin Humphrey
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message