A clever man solves a problem, a wise man avoids it.
— Albert Einstein

Introduction

● Manual ● DockerHub ● Introduction ● Usage ● Configuration ● Docbook ● Plantuml ● Pandoc ● Maven ● Note

As a software engineer I love to work with source code that comes with Unit Tests and a well written documentation. Markdown is surely a good way to write your documents. But sometimes it comes in handy to have a shiny PDF to store offline, send via email or print in high resolution. For those cases Docbook (co-founder O’Reilly Media) is a good solution because it supports different output formats like pdf, epub or html. My project livingfire-docbook shows a easy way to get started with Docbook and alter this example for your own needs. The software can also covert Markdown to Docbook using pandoc and combine multiple Markdown files like a GitLab Wiki into one PDF. In addtion to that you can write UML diagrams in PlantUML and have them rendered into pictures in your book.

Prerequirements

Make sure you have a working Docker and docker-compose environment.

Usage

● Manual ● DockerHub ● Introduction ● Usage ● Configuration ● Docbook ● Plantuml ● Pandoc ● Maven ● Note

# download project files
git clone https://phoen1x@gitlab.com/phoen1x/livingfire-docbook.git
cd livingfire-docbook

# start livingfire-docbook
docker-compose up -d

# convert docbook to pdf
docker-compose exec docbook /book/convertBook.sh
xdg-open book/target/docbkx/pdf/book.pdf

# write Markdown or import wiki
cd tmp/wiki
git init
git remote add origin https://gitlab.com/phoen1x/livingfire-docbook.wiki.git
git pull
rm -rf .git
cd ../..

# convert plantuml to images - http://plantuml.com/
docker-compose exec docbook /book/convertPlantuml.sh

# convert markdown to docbook
docker-compose exec docbook /book/convertWiki2Docbook.sh
xdg-open book/target/docbkx/pdf/book.pdf

# stop  livingfire-docbook and get PDF
docker-compose down
cat book/target/docbkx/pdf/book.pdf > book.pdf

Configuration

● Manual ● DockerHub ● Introduction ● Usage ● Configuration ● Docbook ● Plantuml ● Pandoc ● Maven ● Note

Directory structure

    book
    |-- pom.xml
    `-- src
        `-- main
            `-- documentation
                `-- docbook
                |   |-- book.xml
                |   |-- template_chapter.xml
                |   `-- chapters
                |       |-- chapter_1.xml
                |       |-- chapter_2.xml
                |       |-- chapter_n.xml
                |       `-- media
                |           |-- cover.png
                |           `-- logo.png
                |-- fonts
                |-- xsd
                `-- xslt
                    `-- docbook.xsl

Probably everything you ever need to write a book is within the livingfire-docbook/ book/src/main/documentation/docbook directory. Here you can find the book.xml and a templates for your own content. To tweak the style of your book alter docbook.xsl and pom.xml.

Writing Docbook

● Manual ● DockerHub ● Introduction ● Usage ● Configuration ● Docbook ● Plantuml ● Pandoc ● Maven ● Note

You can use a Markdown Wiki like Gollumn to create your docbook chapters and then further refine the document using these links:

• DocBook Cheat Sheet
• DocBook Tutorial
• Page layout
• Headers and Footers
• Maven + Docbook

Plantuml

● Manual ● DockerHub ● Introduction ● Usage ● Configuration ● Docbook ● Plantuml ● Pandoc ● Maven ● Note

The project is also capable of converting PlantUML

@startuml
Bob   ->  Alice : Hello Alice
Alice ->  Bob   : Hello Bob
@enduml

into an image

Advanced example

@startuml
Script -> Markdown: get file content
Script  -> Script : text multiline grep for Plantuml CONTENT
loop CONTENT found
    Script  -> Script : generate hash from CONTENT -- 693d9a0698aff95c
    Script  -> 693d9a0698aff95c.puml: save CONTENT to 693d9a0698aff95c.puml
    Script  -> Markdown: replace CONTENT with ![uml](693d9a0698aff95c.png)
end
Script  -> Plantuml: convert media/*.puml to media/*.png
Plantuml -> 693d9a0698aff95c.puml: get
Plantuml -> 693d9a0698aff95c.png: create
@enduml

More information on Plantuml can be found at the PlantUML website.

Converter

The source code of my converter can be found here.

Gitlab Wiki / Markdown / Pandoc

● Manual ● DockerHub ● Introduction ● Usage ● Configuration ● Docbook ● Plantuml ● Pandoc ● Maven ● Note

To manually convert Markdown you need to install pandoc

# apt-get install pandoc
pandoc --chapters -t docbook --output page.xml page.md

Usage without Docker

● Manual ● DockerHub ● Introduction ● Usage ● Configuration ● Docbook ● Plantuml ● Pandoc ● Maven ● Note

Maven

# install Java -- https://java.com/en/download/
git clone https://phoen1x@gitlab.com/phoen1x/livingfire-docbook.git
cd livingfire-docbook

# Linux
./mvnw clean site
xdg-open target/docbkx/pdf/book.pdf

# Windows
mvnw.cmd clean site
# Open target/docbkx/pdf/book.pdf in file browser

Note

● Manual ● DockerHub ● Introduction ● Usage ● Configuration ● Docbook ● Plantuml ● Pandoc ● Maven ● Note

This book was written in a GitLab Wiki. Feel free to add your improvements via Merge Request or open an issue if you find a bug.