Free Tools for Free Books

Several people have asked if they could use the tools we used to make Modern Perl: the book. I've always said yes. Like the book's credits say, we used many pieces of free software to make the book, and there's no reason not to share the resulting code with others.

Unfortunately, using those tools meant extracting them manually from the Modern Perl book repository and editing several hard-coded values to get the necessary flexibility.

I'm happy to announce that a new project will render that work unnecessary.

Pod::PseudoPod::Book is a CPAN distribution in progress which is to writing a book what Dist::Zilla is to managing a CPAN distribution. It uses the App::Cmd model to make the ppbook command.

To create a new book:

$ ppbook create my_awesome_book
Please edit 'my_awesome_book/book.conf' to configure your book
$ vi my_awesome_book/book.conf

This creates the skeleton of a book and a basic configuration file. From there, if you follow the default layout of the book (tutorial coming), you can use several ppbook commands to render your book into the appropriate output format:

• buildcredits turns a CREDITS file in the book's root directory into an alphabetized and Unicode-safe sections/CREDITS.pod file
• buildchapters weaves all of the sections and chapters in sections/ together into a series of PseudoPod files
• buildhtml converts woven chapters into XHTML
• buildepub converts XHTML into a valid ePub file

Each command is idempotent and has strict dependencies, so that if you run ppbook buildepub, the output will reflect any changes in the dependencies.

The code is reasonably good and works for my use cases, but it needs polishing before it's ready for the CPAN. Patches and pull requests are very welcome. As well, I don't have the LaTeX to PDF chain enabled yet, because that requires some specific non-Perl dependencies, and I don't want to get into maintaining my own Alien:: bundles.

Regardless of those caveats, I believe these tools can lower the barriers to writing better standalone documentation in Perl. I welcome everyone interested in such things to join me in continuing to improve the state of the publishing art.