Re: PHP Language Spec

Am 24.07.2014 22:35, schrieb Sara Golemon:

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

Hey Sara, i suggest to use AsciiDoc - http://www.methods.co.nz/asciidoc/. Markdown and RestructuredText are nice, but not robust enough for serious technical documentation. AsciiDoc has better features regarding the creation of large, book-style documents. It's easier to parse and more flexible than XML. AsciiDoc plain-text is converted to DocBook XML and then the normal conversion toolchain kicks in. It's easy to generate HTML, PDF, EPUB, Slides and Latext and Mobi book formats from that DocBook, while nobody has to mess around in XML files. It's a part of O’Reilly’s publishing toolchain and a supported format on Github. Please take a look at the user-guide, created with the tool itself. HTML - http://www.methods.co.nz/asciidoc/userguide.html PDF - http://www.methods.co.nz/asciidoc/asciidoc.pdf Let me point to a few things, which might become handy: - Book-Sections - Footnotes - http://www.methods.co.nz/asciidoc/userguide.html#X92 - References - URLs between documents, anchors & xref - http://www.methods.co.nz/asciidoc/asciidoc.html#_inline_macros - Glossary & Index - Bibliography - Callouts - http://www.methods.co.nz/asciidoc/userguide.html#X105 With callouts you can annotate text with numbered markers. This also works on highlighted source-code in the document or in external source-code files. Who uses this: - Neo4J Docs (heavily tweaked and Graphviz supported added) http://docs.neo4j.org/chunked/milestone/community-docs.html#_toolchain - Git Users's Manual (with unmodified, raw AsciiDoc stylesheet) https://www.kernel.org/pub/software/scm/git/docs/user-manual.html I would strongly encourage you to use AsciiDoc. Best Regards, Jens