Re: PHP Language Spec

On 7/24/14, 3:35 PM, Sara Golemon wrote:

Restarting this thread on the standards list. We're working on getting everything converted/formatted/ready for serious collaboration on github and have three format front-runners: 1) Markdown - Works natively on github, simple syntax and fairly expressive. Downshot: Cross-references are hacky, and it's fairly important to have these working right. 2) LaTeX - Much more descriptive syntax without being horribly over-verbose and is still collaboration friendly. Downshot: A bit arcane in the syntax department, needs an explicit render step to verify changes. 3) Docbook - This is what we use for the PHP manual, so it would make sense to not fragment our toolchain. Downshot: XML is really verbose and generating renders from docbook is a bit sluggish (the phpdoc teams knows all these pain points all too well). Of course, we can always convert later-on, but it'd be really helpful to start with something sensible and avoid that transition point if we can. What are people's thoughts and reactions to these options? Is there a fourth, better option which you'd like to champion? -Sara

Frist post! :-) I used to maintain a fairly large Docbook project. (> 1 MB source) Docbook is nice in that it's very descriptive, but the toolchain for it is a nightmare and a half. It's a widely used standard but its main advocate, O'Reilly, has been moving away from it in favor of their new spec, HTMLBook. Markdown: There is no one Markdown. There are many different syntaxes. PHP-FIG is using "GitHub Markdown" as its canonical format, not because it's good but because it's convenient for a team that doesn't want to spend time on proper maintenance. :-) I freely admit to hating Markdown with a passion. I have no experience with LaTeX. Another option: Just go HTML? It's semantic, everyone knows it, it has support for links (they're kind of a thing), and it can be styled to whatever the hell we want. Anyone know what W3C uses? --Larry Garfield