= DocBook Bootstrap

== Purpose Setting up a DocBook build environment seems to be extra difficult and cumbersome. The goal of this project is to create a platform independent, easy to depoly environment that brings you to the core tasks of getting started with THE document within seconds.

.Objectives

• Incorate all wisdom and hints from http://www.docbook.org/tdg51/en/html/
• Be platform independent -> embrace the Java eco-system as much as possible
• Make using DocBook a breeze

== Setup and Usage

image::https://github.com/jceb/docbook-bootstrap/blob/master/examples/clone-template.gif[Set up docbook project]

1. Get all the additional software (see section <<additional-software-needed,Additional Software Needed>>). Hopefully, you've to do this just once (in a while).
2. Make a copy of the template folder and put it where you want to create your next document/project.
   • The clone-template script will do the work under Linux and MacOSX.
   • For Windows adjust the Makefile as needed. (The document can also be passed as an argument to make: make in=FILE)
   • Many <<input_formats,input formats>> are supported
3. Start writing your document!
4. Run make to convert the document to PDF. It will be stored in the build directory.
   • Additional <<output_formats,outupt formats>> are supported
   • Example: make html to create HTML output
   • Example2: make help to get a list of supported output formats
5. Run make watch and make stopwatch to automatically start/stop document builds through <<additional-software-needed,watchman>>.
6. Do you need more customization? Ok, here you go: The file build.properties holds the general settings for building a DocBook file. Platform specific values are stored in the build.properties.PLATFORM files. Customization of stylesheets is possible. Check out the included stylesheet for some ideas: stylesheets/fo/docbook.xsl

== Details

[[output_formats]] === Output Formats / Build Tasks Run the following tasks the create the desired output format, e.g. ant pdf. All output is stored it the directory build, it's customizable throught the variable output.dir:

• pdf : create PDF output (default task)
• epub : create EPUB output
• epub3 : create EPUB3 output
• xhtml : create XHTML output
• xhtmlchunk : create chunked XHTML output
• xhtml5 : create XHTML5 output
• xhtml5chunk : create chunked XHTML5 output
• validate : validates the DocBook document
• clean : delete all dynamically created files/the "out" directory
• test : execute all creation tasks one after the other

[[input_formats]] === Input Formats

• http://asciidoc.org/[AsciiDoc]
• http://docbook.org/[DocBook]
• http://daringfireball.net/projects/markdown/[Markdown]
• http://orgmode.org[Org mode]
• http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html[reStructuredText]
• and many more through http://pandoc.org/[Pandoc]

See section <<additional_software,Additional Software Needed>> for more information. Set property file.format to asciidoc and change file.suffix to the suffix of the input file - it's necessary because there doesn't seem to be way to figure this out using Ant.

=== Examples .Convert any DocBook file to PDF without editing build.properties This takes advantage of ant's ability to specify properties on the commmand line.

ant -Dfile=myfile.xml pdf

.Convert this AsciiDoc file to PDF Actually, it doesn't work yet! The reason is that AsciiDoc doesn't ship a DocBook 5 backend. When you run this command, you can take the resulting DocBook file (build/README.xml) and tweak it to make compile properly.

ant -Dfile=README.adoc -Dfile.format=asciidoc -Dfile.suffix=adoc pdf

== Customization

=== Include custom Fonts It is possible to include custom fonts into fop-generated documents. Follow these steps:

.Include True Type Fonts Copy all required True Type Fonts in the directory lib/fonts.

.Generate XML description for the custom True Type Font Execute the following command in the fop folder lib/fop to generate an XML description for each font:

for font in ../fonts/*.ttf; do java -cp lib/commons-io-1.3.1.jar:lib/commons-logging-1.0.4.jar:build/fop.jar:lib/avalon-framework-cvs-20020806.jar:lib/xml-apis.jar:lib/xercesImpl-2.2.1.jar:lib/xalan-2.4.1.jar org.apache.fop.fonts.apps.TTFReader "${font}" "${font%.ttf}.xml" done

On Linux and Mac OS X systems executing the command lib/fonts/compile.sh will perform this task as well.

The following discussions might also be of interest to you:

• Discussion at http://www.mail-archive.com/fop-user@xml.apache.org/msg13631.html
• More information at http://xmlgraphics.apache.org/fop/0.94/fonts.html#register

.Include fonts in fop.xconf Add the custom font to the fonts section. Here is an example for the ukai font:

... ...

.Include fonts in stylesheet Add the font to the fo-stylesheet (stylesheets/fo/docbook.xsl):

sans-serif,ARPLZenKaiUni serif,ARPLZenKaiUni There are even more font family parameters that can be set: monospace Symbol,ZapfDingbats === More to come ... [[additional_software]] == Additional Software Needed! * Make sure you have a working https://www.java.com/[Java] and http://ant.apache.org/[Ant] setup * For AsciiDoc input http://ascidoctor.org[Asciidoctor] needs to be installed * For any other input form http://pandoc.org/[Pandoc] needs to be installed * For automatic builds, https://facebook.github.io/watchman/[watchman] needs to be installed IMPORTANT: *You also need to download the software listed in file link:SETUP[].* * If you are running Linux or Mac OS X, executing `setup.sh` will download all dependencies == Licensing and Copyright ---- Copyright (C) 2013-2015 Jan Christoph Ebersbach Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ---- // vi: ft=asciidoc:tw=72:sw=2:ts=4