Re: Local DocBook Processing?

On Thu, Mar 19, 2015 at 8:16 AM, Hollenbeck, Scott <shollenbeck@verisign.com> wrote: > I'm working on the documentation for a PHP extension that I might one day submit to PECL. > I've successfully used docgen.php to process my extension and produce DocBook XML files. How > can I convert those files into PDF or HTML for local viewing? I've tried Publican, but it fails > with an XML parser error. I've also tried dblatex, but it doesn't like the undefined > entity references in the book.xml file produced by docgen. Should I edit book.xml and add the entity > definitions manually? > If you intend on publishing the documentations of your extension separately then you'll need to jump through some hoops: - Move the docgen.php generates sources into en/reference/myextname/ (en/reference/myextname/book.xml should exist) - Generate a standalone .xml file with partial view of the docs: $ php doc-base/configure.php --with-partial=myid # example: book.myextname (the xml:id from the <book> in book.xml) - or something like $ xmllint --noent --noxincludenode --postvalid --output doc-base/.manual.book.myextname.xml en/reference/myextname/developers.book.xml - That will generate a complete standalone XML file called doc-base/.manual.book.myextname.xml that includes all the missing entities - Optionally install pecl/haru if you want pdf output: $ pecl install haru - Install PhD - pear install doc.php.net/phd* - Render the docs - see available formats with $ phd --list # (xhtml, bigxhtml, manpage, pdf, bigpdf may be of interest for bundling your docs separately from php.net) - phd -d doc-base/.manual.book.myextname.xml --package PHP --format manpage Note that we have tiny docbook customizations that render most off-the-shelv docbook renderes useless (phpdoc:classref, phpdoc:exceptionref, phpdoc:varentry, phd:chunk, phd:args, ....). -Hannes