Paul Jones has posted about a new tool he's worked up specifically for authors looking to write using Markdown and wanting it to generate out like DocBook results. His tool, Bookdown, uses Markdown and JSON files instead of XML configurations.

Yes, I know, there’s a ton of static site generators for PHP out there already [...but they're] not DocBook-like documentation. By “DocBook-like”, I mean (among other things) numbered headers, auto-generated tables-of-contents on their own pages, hierarchical multi-page presentation, and the next/previous/up linking at the top and bottom of pages.

[...] So: Bookdown. This scratches my particular itch, with very few dependencies. Bookdown, although it can be used as a site generator, is only incidentally a site generator. What it really is is a page generator, with the idea that you can integrate the pages into any other site you want.

The library is separate from the project and is written to use a dependency injection methodology to keep things decoupled and well-structured. If this sounds interesting either for personal use or if you'd like to check out the code, head over to the project site for more information.

In a new post to his site Hannes Magnusson talks some about the current PHP documentation (and PHP.net site) formatting and how, while changes to it are quick, they should be instant. He suggests a path to get there and a new tool that could help.

Since 2008 there have been numerous efforts to create a new design for www.php.net, all of which have failed - so far. We've never come as close as two years ago, when the "beta mode" option was added to our website, but we never really got around to finish it. The "beta design" has even received a lot of makeover compared to what is "beta mode" now. To make things a little bit more awesome, there is also a new branch called "responsive" which has a lot of changes in it too, especially for manual pages. Hopefully, one day, we'll actually finish one of these and flip the switch forever.

While he's been a fan of the DocBook structure that's currently in use, he points out that learning the markup can be a hinderance to people contributing. His tool, PhD, does some custom parsing too adding additional complexity. To help, he's working on a new tool (WTFM) to use Markdown formatting instead of DocBook, a more common format.

Padraic Brady has posted part one in a new series he's developed covering documentation (and using Docbook, Phing and Apache FOP to create some professional looking results).

This article series proposes using Docbook XML as the ultimate source format for all documentation. The difference between most formats and Docbook, is that Docbook can be used to generate numerous final formats. [...] The series was written to introduce programmers to a PHP oriented publishing process which uses Docbook XML as the basis for generating professional looking HTML and PDF output.

Part one introduces the "ingredients" - Docbook XML, PHP5, Phing and Apache FOP - and includes an install process to help you get things set up.

Christian Weiske set out on a project - no small thing - to convert the current PEAR documentation info over to the PhD DocBook rendering system. In a new post he talks about the conversion process and some of the technology involved.

The reason for PhD to exist was that the previously used DSSSL based system was slow: a full build (all formats and all languages) took 24 hours to complete. Further, the tools the system based on were old, rusty and nobody understood why they broke on some machines, but also why they worked on other ones. Having a php-based system for PHP ensures that there is always someone around who can fix it if it's broken. This wasn't the case with the old documentation build system.

The conversion was spurred on by the fact that the PEAR documentation stopped building and more and more people were finding it hard to build on their machines too. He walks through the steps he took - installing PhD, converting over the docs to the DocBook 5 format and the first builds with the new system.

Now that at the XML was shiny, too, it was time to actually use PhD on it. The numbers were amazing: While a build for one format and one language took around 40 minutes on my system (dual core Macbook with 2GHz and 2GiB RAM), building the same with PhD takes 45 seconds!

Rudy Nappee has just finished what he calls the hardest week in his Google Summer of Code project - work on the PDF output methods:

Here was the hardest GSoC week ! I wrote a big part of the PDF output and both the themes "phppdf" (each PHP manual part in a file) and "phpbigpdf" (a big PDF file with all the sections).

Rudy's project for the GSoC is to create a Docbook renderer that can take in a standard Docbook file and output it into multiple formats. This past week saw the development of the PDF output method but he's also created methods for making a CHM (Windows help file) and a manpage output format. You can keep up with his latest progress on his blog.

Padraic Brady has posted a new entry in his series on developing blogging software with the Zend Framework today. It's no new content, but it is a contained version of a previous part (part 9) marked up in Docbook and pushed out into a PDF.

After my playtime with Docbook and PDF generation, I decided to make a sample PDF of the current Part 9 of the tutorial series. Your comments as to layout, style, portability and other facets that make a PDF worth downloading are very welcome. Eventually the whole series will be available in this format as well as HTML.

He's using Docbook 5, Docbook XSL and Apache FOP to generate the files. Syntax highlighting is done through Phing.

The main PHP website has announced the release of the new documentation build system (as Hannes Magnusson mentioned previously) is ready and has been launched for testing.

The PHP documentation team is pleased to announce the initial release of the new build system that generates the PHP Manual. Written in PHP, PhD ([PH]P based [D]ocBook renderer) builds are now available for viewing at docs.php.net. Everyone is encouraged to test and use this system so that bugs will be found and squashed.

Once the new build system is stable, expect additional changes to the PHP manual that will include an improved navigation system and styling for OOP documentation.

You can use the my.php page to set it as your default mirror if you'd like to use it seamlessly.

The main PHP website has announced the release of the new documentation build system (as Hannes Magnusson mentioned previously) is ready and has been launched for testing.

The PHP documentation team is pleased to announce the initial release of the new build system that generates the PHP Manual. Written in PHP, PhD ([PH]P based [D]ocBook renderer) builds are now available for viewing at docs.php.net. Everyone is encouraged to test and use this system so that bugs will be found and squashed.

Once the new build system is stable, expect additional changes to the PHP manual that will include an improved navigation system and styling for OOP documentation.

You can use the my.php page to set it as your default mirror if you'd like to use it seamlessly.

Hannes Magnusson has bloccked about the latest release of their application, PhD (the [PH]P based [D]ocbook renderer) that builds up documentation, like that for the PHP manual.

Quick note; We released PhD0.1RC1 today o/ Building the php.net documentations has never been as easy or as fast. [...] It takes less than 2 minutes (on my two years old Precision M70 laptop) to render the entire php.net documentations in three formats.

He includes instructions on fetching the packages needed/documents to compile, modify the configuration files and installing and rendering the php.net documentation. They've also set up a special mirror of the PHP documentation with experimental builds of the docs.

Hannes Magnusson has bloccked about the latest release of their application, PhD (the [PH]P based [D]ocbook renderer) that builds up documentation, like that for the PHP manual.

Quick note; We released PhD0.1RC1 today o/ Building the php.net documentations has never been as easy or as fast. [...] It takes less than 2 minutes (on my two years old Precision M70 laptop) to render the entire php.net documentations in three formats.

He includes instructions on fetching the packages needed/documents to compile, modify the configuration files and installing and rendering the php.net documentation. They've also set up a special mirror of the PHP documentation with experimental builds of the docs.