lucy-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "David E. Wheeler" <>
Subject Re: [lucy-dev] Markdown for documentation
Date Fri, 18 May 2012 05:01:56 GMT
On May 17, 2012, at 11:18 PM, Marvin Humphrey wrote:

> Hi David,

Hi Marvin.

> As this discussion has progressed, I've been having second thoughts about
> Markdown.  Perhaps we should consider reStructuredText as an alternative.

That might be okay, though it is not as nice as Markdown in plain text.

> 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.

Well, stick to Pod, then. :-)

> 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.

Is this ReST? I don't recognize it as Markdown. Here is the official syntax:

> 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).

Yeah. Another reason to stick with Pod.

> 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.

ReST, unlike Markdown, is highly extensible. I had to work with Daniele Varrazzo pretty closely
to get a non-sucky, mostly plain ReST support into Text::Markup/PGXN.

>> 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.

As I said, I am unfamiliar with the @param syntax. Is it part of Sundown?

>> 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

Eh. Well, there is my table proposal.

But of course, no table or definition list proposal (I had one of those, too) has been accepted.
So just core, canonical Markdown might be best.

>> 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.

Ah, okay, that would probably be fine.

> 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.

Another reason to stick with Pod. ;-P

> 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.



View raw message