Mailing-List: contact dev-help@lucy.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@lucy.apache.org
Received-SPF: pass (athena.apache.org: local policy)
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;
  s=s1024; d=yahoo.com;
  h=X-YMail-OSG:Received:X-Mailer:References:Message-ID:Date:From:Reply-To:Subject:To:In-Reply-To:MIME-Version:Content-Type;
  b=RFOt2pVXGrKHUvuEU9gYoOsViR04xpmQEkNRZOUyKKHoNCSWwXr8joUADH3dq6ZXtYOWGQe3JuxvXlu5AeiBQI9fHe72Vu/QUUlRAou9C2m/lBHFtwd9sDSE/oIlImRqABaYZzeL8B3bxO4SNXtEonw396//ERpx4Dk77jdfI0o=;
References: 
 <CAAS6=7iJuWF-4M1BTnYNsEWjWmrWT00kSYRpzYNzq9FuqUgbuw@mail.gmail.com>
 <97A7DC4C-8524-490F-92B6-1251A86DC1A8@justatheory.com>
 <CAAS6=7jWN0-Wv5wBnY_whKDE5ySXX25KeiKMwpjwVx+L3QpgiQ@mail.gmail.com>
 <2B79A5C0-4637-4EE0-93D7-1D5C9C6FF889@justatheory.com>
 <CAAS6=7i_c_n3mKRd+4o-aANPyas7zJo8DJJ=rYB0jWLfBDBnOw@mail.gmail.com>
Message-ID: <1337311818.5158.YahooMailNeo@web160902.mail.bf1.yahoo.com>
Date: Thu, 17 May 2012 20:30:18 -0700 (PDT)
From: Joe Schaefer <joe_schaefer@yahoo.com>
Reply-To: Joe Schaefer <joe_schaefer@yahoo.com>
To: "dev@lucy.apache.org" <dev@lucy.apache.org>
In-Reply-To: 
 <CAAS6=7i_c_n3mKRd+4o-aANPyas7zJo8DJJ=rYB0jWLfBDBnOw@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/alternative;
 boundary="498176207-568526374-1337311818=:5158"
Subject: Re: [lucy-dev] Markdown for documentation

--498176207-568526374-1337311818=:5158
Content-Type: text/plain; charset=iso-8859-1
Content-Transfer-Encoding: quoted-printable

FWIW we finally settled on the python markdown implementation=0Afor the www=
 sitelargely because it has sane extension mechanisms.=0A=0AWe take advanta=
ge of that in order to properly identify headings=0Aand such, that works gr=
eat.=A0 The table fu is kinda-sorta useful=0Ain many cases, but it's very l=
imited.=A0 Automatic code highlighting=0Ais nifty when it's using the right=
 programming language ;-).=0A=0A=0AYes I am aware that socially the markdow=
n situation sucks, but=0Awe had to pick something.=A0 Markdown at least has=
 name-brand=0Arecognition for what little it's worth, we could've went with=
=0ATextile if there was a decent webgui for editing it.=0A=0A=0AFWIW python=
 and php at one point or another tried to keep parity=0Awith markdown exten=
sion features.=A0 Dunno where that stands=0Atoday.=A0 But really from a usa=
ge standpoint nobody complains=0Aabout which version of markdown you're usi=
ng from a holier-=0Athan-tho perspective, if it works go for it.=0A=0A=0A=
=0A=0A=0A=0A>________________________________=0A> From: Marvin Humphrey <ma=
rvin@rectangular.com>=0A>To: dev@lucy.apache.org =0A>Sent: Thursday, May 17=
, 2012 11:18 PM=0A>Subject: Re: [lucy-dev] Markdown for documentation=0A> =
=0A>Hi David,=0A>=0A>As this discussion has progressed, I've been having se=
cond thoughts about=0A>Markdown.=A0 Perhaps we should consider reStructured=
Text as an alternative.=0A>=0A>In my opinion, our number one priority shoul=
d be to commit to an external spec=0A>that is carved in stone.=A0 Debating =
lightweight markup syntax might be even=0A>less fun than debating query par=
ser syntax. :P=A0 By implementing an=0A>authoritative spec, we limit the sc=
ope of debate and shut down a lot of=0A>bikeshedding before it starts.=0A>=
=0A>To my mind, the stability of the Markdown spec is one of its most=0A>at=
tractive features.=A0 However, after further investigation, I have come to=
=0A>understand that the spec is rarely implemented as-is and that the Markd=
own=0A>community is deeply Balkanized and embittered on the subject of exte=
nding=0A>it[1].=A0 I'm uneasy about inviting Markdown's controversies into =
our house.=0A>=0A>My preference is still for vanilla Markdown, more or less=
.=A0 To simplify=0A>things, let's tweak the proposal to relegate @tags to t=
he end of the comment,=0A>eliminating inline @tag expansion.=0A>=0A>=A0 =A0=
 A DocuComment has two sections.=0A>=0A>=A0 =A0 =A0 =A0 body=0A>=A0 =A0 =A0=
 =A0 =A0 =A0 Description, formatted in Markdown.=A0 The first sentence must=
 be a=0A>=A0 =A0 =A0 =A0 =A0 =A0 summary that can stand on its own.=A0 Term=
inated by the first line=0A>=A0 =A0 =A0 =A0 =A0 =A0 which begins with an "@=
" character or by the end of the comment.=0A>=0A>=A0 =A0 =A0 =A0 tags=0A>=
=A0 =A0 =A0 =A0 =A0 =A0 The comment may end with an optional tags block.=A0=
 Each tag begins=0A>=A0 =A0 =A0 =A0 =A0 =A0 with a supported @label at the =
beginning of a line, and is=0A>=A0 =A0 =A0 =A0 =A0 =A0 terminated by either=
 the next tag or the end of the comment.=0A>=0A>There's only one Markdown e=
xtension I believe we can't live without: links=0A>without a protocol shoul=
d be interpreted as API links.=0A>=0A>=A0 =A0 @param query A [Query](Lucy::=
Search::Query).=0A>=0A>Then there's one more change I'd consider optional, =
since nearly all Markdown=0A>implemenations have it: disable intra-word emp=
hasis so that foo_bar_baz=0A>doesn't become foo<em>bar</em>baz.=A0 I don't =
really care one way or the other=0A>because 99% of the time `foo_bar_baz` s=
hould be enclosed in backticks.=0A>=0A>I realize that by adding those two e=
xtensions we start down the slippery=0A>slope...=A0 IMO, that's an argument=
 against Markdown...=0A>=0A>I hope that's good enough.=A0 If it's not -- if=
 we believe that ultimately it=0A>will be necessary to add additional exten=
sions -- then I think we ought to=0A>consider reStructuredText instead.=0A>=
=0A>=A0 =A0 http://en.wikipedia.org/wiki/ReStructuredText=0A>=0A>From a hig=
h level, the syntactical differences between reStructuredText and=0A>extend=
ed Markdown are IMO superficial and the feature sets are similar -- but=0A>=
reStructuredText has a canonical spec which has been stable for 10 years.=
=0A>reStructuredText is like extended Markdown, minus the bikeshedding and =
the=0A>resentment towards the original author.=0A>=0A>> I prefer definition=
 lists to bulleted lists, myself.=0A>=0A>Fortunately, the choice of whether=
 we expand @param tags to bullet-lists or=0A>definition-lists is an impleme=
ntation detail which is separate from whether we=0A>support lightweight mar=
kup within comments.=A0 Let's leave this topic for=0A>another day.=0A>=0A>>=
 Well, MultiMarkdown is pretty well accepted as the #2 definition. Most=0A>=
> implementations follow its examples (FBOFW).=0A>=0A>I'm skeptical.=A0 Fro=
m what I can tell, "GitHub Flavored Markdown" -- a=0A>particularly destruct=
ive variant given how incompatible it is with the=0A>original Markdown spec=
 -- looks like a significant competitor.=0A>=0A>And here's what happened wh=
en someone tried to assert the dominance of=0A>MultiMarkdown on the markdow=
n-discuss list last October:=0A>=0A>=A0 =A0 http://six.pairlist.net/piperma=
il/markdown-discuss/2011-October/002342.html=0A>=0A>=A0 =A0 > pandoc assess=
ed 'em all, and decided on multimarkdown.=0A>=0A>=A0 =A0 Huh? No. Pandoc's =
markdown extensions aren't the same as mmd's. I have=0A>=A0 =A0 explained i=
n earlier posts why I don't like mmd's table and metadata=0A>=A0 =A0 syntax=
. Pandoc goes back to 2005 and was not influenced by mmd.=0A>=0A>Adjudicati=
ng internet popularity contests is tiresome. :P=0A>=0A>> Note that Sundown =
supports quite a lot more than just vanilla Markdown. How=0A>> would you en=
force that?=0A>=0A>It looks like you have to enable syntax extensions manua=
lly in Sundown -- so=0A>we "enforce" vanilla Markdown simply by not enablin=
g those extensions.=0A>=0A>However, I'm concerned that choosing Sundown may=
 set us up for failure because=0A>it means that we'll have this argument ag=
ain later with someone who is=0A>*outraged* to discover that we've got thei=
r pet Markdown extension disabled.=0A>=0A>That's why I would like to determ=
ine whether we have consensus about forgoing=0A>additional Markdown extensi=
ons.=A0 If we don't have consensus, we should=0A>evaluate reStructuredText.=
=0A>=0A>Marvin Humphrey=0A>=0A>[1] http://six.pairlist.net/pipermail/markdo=
wn-discuss/2008-March/001163.html=0A>=A0 =A0 http://www.codinghorror.com/bl=
og/2009/12/responsible-open-source-code-parenting.html=0A>=0A>=0A>
--498176207-568526374-1337311818=:5158--