This package gives you all the tools you need to author books and articles with the open-source Docbook toolchain.
Contained in this package are the Docbook XSLT stylesheets, a validation package, XML-FO to PDF translation, and a project generator with build scripts. This uses the dookbook-xsl-ns stylesheets.
In order to use this, you’ll need a Java Runtime Environment. JRE 1.6 is fine.
You also need Ruby 1.8.7 or higher with RubyGems and Rake. Most standard installations of Ruby will include these dependencies.
This repository is for technical people who want to get the latest bleeding-edge version of this toolchain so they can customize it to fit their needs. Authors and other end users should download the re-distributable packages available at www.napcs.com/products/docbook which are more stable.
If you’re interested in creating a more customized toolchain as part of a continuous build process, etc, you should clone the repository
git clone git://github.com/napcs/docbook
Then run
rake install
This copies only the necessary files to c:/docbook on windows or ~/docbook on Linux and Mac OS. If you want to install elsewhere, specify a path
sudo rake install DIR=/opt/docbook
You’ll be prompted to add the install directory to your path. Also add the SHORT_ATTENTION_SPAN_DOCBOOK_PATH environment variable to the installation directory to make it easier to run the generators and find everything.
If you really want to keep current, you can clone the repo
git clone git://github.com/napcs/docbook ~/docbook_edge
And set your ENV variable for SHORT_ATTENTION_SPAN_DOCBOOK_PATH to point there. You may also wish to add ~/docbook_edge to your path.
Then you can fetch updates with
git pull origin master
This way you can write against the most current files.
Create a new book with sample info using the generate script.
generate book foobook with_sample
That creates
Creating docbook project... - foobook/xsl - foobook/images - foobook/images/sample.png - foobook/book.xml - foobook/chapter01.xml - foobook/Rakefile - foobook/w3centities-f.ent - foobook/xsl/pdf.xsl - foobook/xsl/epub.xsl - foobook/xsl/epub.css - foobook/xsl/mobi.xsl - foobook/xsl/mobi.css - foobook/xsl/html.xsl - foobook/xsl/html.css - foobook/xsl/rtf.xsl
Create a PDF of the book:
cd foobook rake book.pdf
or simply
rake
Edit book.xml to add your own information, chapters, images, and more. Edit xsl/pdf.xml to change how things look.
Create an HTML version the same way
rake book.html
You’ll see the output at html/index.html
This package can create EPUB files too. And while RTF files will build, the support here is relatively weak and is a limitation of Apache FOP’s RTF support.
See readme_files/docbook.pdf for more information, like how to use Draft mode, pre-and-postprocessing hooks, and adding covers. There’s also more on installation and usage for end users there, and it serves as documentation, as the PDF’s docbook source is available there as well.
The build system works best when you have an environment variable set. On Linux, you would add this to your .bashrc or other profile scripts.
export SHORT_ATTENTION_SPAN_DOCBOOK_PATH="~/docbook"
On Windows, add this to your environment variables in Control Panel.
Please fork and pull. Don’t update the changelog. Make small patches I can pull in.
2014-07-19 -v1.7
* Updates Docbook XSLT to 1.78.1
2014-03-14 -v1.6.2.1
* When rendering fails, book.tmp.xml is no longer deleted, making error discovery easier. * Added .rhtml (erb) highlighting file * Modified the Ruby highlighting file to add new tokens for Rails * Modified the HTML highlighting file to recognize some HTML5 elements
2013-04-30 -v1.6.2
* Updated FOP to 1.1 * Minor changes to the default PDF stylesheet
2012-07-20 - v1.6.1
* Added highlighting for CoffeeScript * fixed incorrect xpath which was always using article instead of book. Closes #11 * readme fixes, minor comment changes in template Rakefile * changed error message to make kindlegen path clearer. Closes #17 * Fixed load paths so installation works.
2011-10-25 - v1.6.0
* Fixed sample template issues * Added basic support for .mobi format for Amazon Kindle. You'll need kindlegen on your path though. * Removed Relames validation and replaced with Jing so that validation actually validates included files. * Added validation before preprocessor. This will result in validation running twice, but this now handles cases where you are transforming book.tmp.xml in your own preprocessor. * Fixed issue where epubs were not getting the right cover file added. * Removed sections of the README that are now out of date.
2011-10-20 - v1.5.2
* Now properly catching issues where FO to PDF conversion encounters errors.
2011-09-19 - v1.5.1
* Changed how external commands are run to prevent blocking on larger books.
2011-09-19 - v1.5.0
* Changed to local validation (Eric Davis) * Refactored generators for projects and added tests * Refactored validation and added tests * Created quieter output by default and added VERBOSE=true option * Colored output on OSX and Linux. (Win32console was too buggy with STDERR so it's not enabled.)
2011-08-28 - v1.4.2
* Changed HTML generation slightly. Cleans up after itself much better, and html files are also removed by the cleanup task.
2011-08-28 - v1.4.1.1
* Fixed install script's documentation rake task that was aborting improperly.
2011-04-19 -v1.4.1
* Fixed the validation code. You'll find out if you have a bad doc much quicker now.
2011-03-22 -v1.4.0
* Updated FOP to 1.0. * Improved RTF output * Cover support for ePub is done. It requires the use of the <tt>cover</tt> element though, so it's different than PDF covers. * PDF cover support is now the default. No need for an extra task. If the cover.pdf file exists, it will be used. * Updated Docbook XSL-NS to 1.76.1. See xsl/RELEASE-NOTES.txt for more details. * Downgraded Docbook XSL-NS ePub XSLT to 1.76.0 due to regression bug with epub ToC. * Improved HTML output. HTML output is now copied to the html/ directory and all images are collected and copied there as well. * Added an HTML stylesheet. * Added examples to the default stylesheet that show how to customize the generated text for cross references. * Added entries to the ePub stylesheet * Tested ePub output on Adobe Digital Editions, iBooks 1.2 and Stanza on the iPad.
2010-09-00 -v1.3.0.3
* Builds PDFs under Ruby 1.9.2 * Postprocess callbacks work (Thanks Eric Davis)
2010-08-08 -v1.3.0.2
* Fixed issue where book.pdf could not be rebuilt unless the pdf was removed * Fixed chapter generation to not create a useless folder when not using chapter subfolders.
2010-07-12 - v1.3.0.1
* Fixed issue with epub interfering with PDF and other file creation - bad regex.
2010-06-30 - v1.3
* Disabled ePub support for Windows for now. * Refactoring of libraries to lay the groundwork for alternate adapters like Prince, PDFKit, XEP, and others. * Minor work on epub output. Looks decent in Stanza and iBooks now.
2010-04-20 - v1.2.1.1
* Added a DEBUG=true flag to help troubleshoot setup errors.
2010-03-29 - v1.2.1
* MUCH improved cleanup routine now finds any pdf with the same name as one of your xml files. * rake book.pdf now builds if you change any xml file in the project. Useful for rebuilding a book after changing a chapter. * Created a method to share rake tasks between projects. Put tasks in $HOME/.docbook_rakefile. It's loaded after all other tasks, so you can use this to extend existing tasks, or provide common pre/postprocess hooks for all of your book projects.
2010-03-24 - v1.2.0
* Added preprocess and postprocess hooks. Detailed information is in the readme_files/docbook.pdf file.
2010-03-21 - v1.1.4.1
* PDF XSLT improvements for TOC and xrefs. Fixed rake task
2010-03-18 - v1.1.4
* Refactored code in the makefile into much more organized modules so that the build chain can be expanded better. Much more to do. * Fixed erroneous installation messages for exporting environment vars on linux * Fixed missing dependent doc task on install
2010-02-22 - v1.1.3
* Added style rule to template pdf.xsl to keep code listings together.
2010-02-02 - v1.1.2
* Changed where the cover script looks for covers. Covers should be in the covers/subfolder of your project
2009-12-31 - v1.1.1
* Added multivalent library for merging * New "add cover" support - slap a nice cover on your books * Minor documentation updates * Added "clean" task * Made buiding "book.pdf" or "article.pdf" default tasks * Default task "touches" the book or article file to force a rebuild even if nothing changed
2009-12-09 - v1.1.01
* HTML stylesheet customization layer * added version flag for generator and for rakefiles * added VERSION file containing the version of the buildchain used by the generator.
2009-12-09 - v1.1.0
* Installation tasks, fixed Windows issues
2009-12-08 - v1.1rc3
* Added Rake tasks for building, testing, and installing * Updated stylesheet
2009-12-03 - v1.1rc2
-
added DRAFT option
2009-09-18 - v1.1rc1
-
Highlighting support works differently which changes a lot of the process.The highlighting customizations needed to be changed, and an additional layer needed to be placed inbetween your customization layer and the base styles. Unfortunately, this breaks your existing projects. However, just generate a new book and move your xml files into the new project. If you’ve made customizations, manually move those into the pdf.xsl file.
-
The stylesheets now take the path parameter via an external XML property, which is set in the make file. You need the new make file to make things work on your projects.
-
Added support for entitites
-
Updated FOP to 0.9.5
-
Updated stylesheets to 1.75.2
-
Updated XSLHL to 2.0.2 and added in the support for Javascript, C#, and INI files.