Re: PHP Language Spec

Hi! > 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. I like markdown as an option. > 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. Latex is fine if you already have set of macros and if you enjoy programming your documents. However the learning curve may be a bit steep and unless we have somebody that undrestands the arcana of Latex macros, it may be a bit hard to keep the text in good shape. OTOH, if we have such expertise we could create much better looking document. But for this case, conversion from Markdown to something Latex can process should be easily scriptable. > 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). Docbook looks like a bit of PITA to me, but if it'd be easier to integrate into the toolchain for the docs team, it'd work too. -- Stanislav Malyshev, Software Architect SugarCRM: http://www.sugarcrm.com/