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

  http://daringfireball.net/projects/markdown/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.
> 
>    http://en.wikipedia.org/wiki/ReStructuredText
> 
> 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.

  https://github.com/theory/text-markup/commits/master

>> 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:
> 
>    http://six.pairlist.net/pipermail/markdown-discuss/2011-October/002342.html
> 
>> 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.

  http://www.justatheory.com/computers/markup/markdown-table-rfc.html

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.

+1

David



Mime
View raw message