Re: Specification live on git.php.net

Joel's emails aren't getting through to the list, so I'm sending this one on his behalf: On Wed, Jul 30, 2014 at 3:20 PM, Joel Marcey <joelm@fb.com> wrote: > On 7/30/14, 12:35 PM, "Hannes Magnusson" <hannes.magnusson@gmail.com> > wrote: >>On Wed, Jul 30, 2014 at 10:53 AM, Florian Anderiasch <ml@anderiasch.de> >>wrote: >>> First roadblock for the FORMATTING.md, which flavor of markdown is >>> actually sensible to support? >>> >>> From the last minutes reading it, it seems to be pretty vanilla, with a >>> few exceptions. >>> >>> - uses tables >>> - the github/markdown gem does not seem to parse >>> #Intro, it would >>> expect # Intro although it renders just fine on >>> [1] >>> >>> So these are the implementations I can think of form the top of my head: >>> >>> - Gruber's original Markdown [2] >>> - GitHub flavored markdown [3] >>> - pandoc markdown [4] >>> - Multimarkdown [5] >>> >>> Tables are kind of neat, GFM is is kind of common these days, and MMD is >>> overkill, imho. >> >>Then... fix the header to include a space after # and call it GFM. Or >>maybe Joel can chime in with what his goal was? >>If it turns out later we need something more/else then.. we upgrade. No >>biggie. >> >>As a side note: >>I haven't seen "MMD" before, but that looks awesome and looks like it >>includes all that phpdoc needs! :D >> >> > I chose GMD because we were hosting the initial draft on GitHub and it is > a Markdown format that provides just enough extra functionality to be > useful (tables) without losing its conversion to other formats flavor. > Markdown is a good choice for converting to a variety of other formats > (PDF, HTML, ReStructuredText, etc.) using something like pandoc. > > I personally like the GMD format. It is simple, expressive enough and > readable. And tooling can workaround any flaws (like numbered headings). > But I am not putting a stake in the ground on GMD. > > One thing I definitely want to do is split the current monolithic document > into multiple, topic-based files. The gating factor here has been the > internal links, but I think tooling can get around that. >