Skip to content

Latest commit

 

History

History
158 lines (101 loc) · 6.48 KB

README.rdoc

File metadata and controls

158 lines (101 loc) · 6.48 KB
Raw

Short Attention Span Docbook ↑

This package makes it easy for you to set up all of the tools you need to start authoring 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 package is intended for developers who want to integrate this into their existing programs, want to be on the bleeding edge, and who wish to do a manual installation. Authors and other end users can download the re-distributable packages available at www.napcs.com/products/docbook which are more stable.

This uses the dookbook-xsl-ns stylesheets.

Installation and Usage ↑

In order to use this, you’ll need a Java Runtime Environment. JRE 1.6 is fine.

You also need Ruby 1.8.6 or 1.8.7. 1.9 is not supported yet though it will be very soon.

Finally, you need Rake.

The easiest way to set this up on your machine is to 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 environment variable to the installation directory.

Staying on the Bleeding Edge ↑

Clone the repo

git clone git://github.com/napcs/docbook ~/docbook_edge

And set your ENV variable for SHORT_ATTENTION_SPAN_DOCBOOK to point there.

Fetch updates with

git pull origin master

Creating a book ↑

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.xml

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.

More Usage ↑

This package can create HTML files too. And while RTF and EPUB files will build, the support here is pretty weak. I’m working on that.

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.

Paths ↑

The build system works best when you have an environment variable set. On Linux, you would add this to your .bash_profile or other profile scripts.

export SHORT_ATTENTION_SPAN_DOCBOOK_PATH="~/docbook"

On Windows, add this to your environment variables in Control Panel.

This step is not necessary, but can ease collaboration between multiple authors, as Docbook may be installed in different locations on each person’s machine.

Upgrading from previous versions ↑

Due to changes in the way things worked, your best bet is to generate a new project for your book and move your xml files and images into this new project, then add your customizations into the pdf.xsl file manually. Code highlighting customizations are different now. If you’re not getting code highlighting to work, generate a new book and review the new Rakefile and the new pdf.xsl file. Also note that entities are included in the projects and the new templates use them.

Remember - to build your books, you now use

rake book.pdf
rake book.pdf VALIOATE=false

Patches ↑

Please fork and pull. Don’t update the changelog. Make small patches I can pull in.

Changes ↑

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 yo ucan 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.