Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/jceb/docbook-bootstrap

Bootstrapping environment for getting started with DocBook
https://github.com/jceb/docbook-bootstrap

Last synced: about 1 year ago
JSON representation

Bootstrapping environment for getting started with DocBook

Awesome Lists containing this project

README 

          
= 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

   <>).

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

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