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
