Giters

aanno / db-toolchain

An update-to-date docbook toolchain (xslt20, fop 2.4.0-dev, ...)

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

db-toolchain

Asciidoc and DocBook to PDF (or FO, HTML, ...) conversion made easy!

This project has similiar aims as the following tools:

Make using Asciidoc(tor) and DocBook convertion tools as easy as it can be.

In detail:

  • Provide several processing pipelines for conversion.
  • Provide the most up-to-date pipelines possible.
  • Provide an unified CLI access to the different pipelines.
  • Only depend on an installed Java JDK 11 (and some standard Linux tools).
  • Support for MathML (work-in-progress, depending on the pipeline).
  • Support for (code) syntax highlighting (work-in-progress, depending on the pipeline).

State

This project is a work-in-progress, but most things work now: Using pipelines to convert Asciidoc(tor) or DocBook to PDF, HTML and/or FO.

Pipelines

So far the following pipelines are implemented:

  • xsl30:
    (X)Html conversion of Asciidoc(tor) and DocBook (5.1) using the DocBook xslTNG 3.0 Stylesheets (This does not support FO, see here.)
  • xsl20-fo:
    PDF (or intermediate) conversion of Asciidoc(tor) and DocBook (5.1) using the DocBook Xslt 2.0 Stylesheets (2.6.0) and Apache FOP (2.6)
  • xsl20-css:
    PDF (or intermediate) conversion of Asciidoc(tor) and DocBook (5.1) using the DocBook Xslt 2.0 Stylesheets (2.6.0) and Prince 14
  • ad:
    PDF (or intermediate) conversion of Asciidoc(tor) using the acsiidoctorj port of asciidoctor
  • xsl10-html:
    (X)Html conversion of Asciidoc(tor) and DocBook (5.1) using the DocBook Xslt 1.0 Stylesheets (snapshot 2020-06-03)
  • xsl10-css: (not implemented so far)
    PDF (or intermediate) conversion of Asciidoc(tor) and DocBook (5.1) using the DocBook Xslt 1.0 Stylesheets (snapshot 2020-06-03) and Prince 14
  • xsl10-fo: (not implemented so far)
    PDF (or intermediate) conversion of Asciidoc(tor) and DocBook (5.1) using the DocBook Xslt 1.0 Stylesheets (snapshot 2020-06-03) and Apache FOP (2.6)
  • fo:
    PDF conversion of XSLT-FO (i.e. FO) using Apache FOP (2.6)

Prerequisite

  • Java 17 JDK installed and set as JAVA_HOME environment.
  • Apache Maven (mvn) in PATH.
  • Apache Ant (ant) in PATH.
  • Some Linux tools (e.g. zip, unzip, bash, wget) in PATH.
  • A github account, with an associated SSH certificate (so that you clone with SSH)

Quick start

  1. Check out the project from github.
  2. cd db-toolchain
  3. ./script/bootstrap.sh
  4. ./gradlew build
  1. ./scripts/unzip-distribution.sh
  2. You have now a distribution Zip at build/distributions/db-toolchain.zip that you can unzip and use independent of the build process.
  3. cp scripts/env.sh.template scripts/env.sh and adopt copied file to your needs
  4. Use ./scripts/run-with-modulepath.sh to invoke the program
  5. E.g. ./scripts/run-with-modulepath.sh transform -d . -w ./submodules/asciidoctor.org/docs --pipeline xsl20-fo -of HTML5 -i ./submodules/asciidoctor.org/docs/asciidoc-writers-guide.adoc

Usage

The most important (sub-)command is transform and the help gives you:

> ./bin/db-toolchain transform -h
Usage: <main class> transform [-ch] [--princeapi] [-d=<outDir>] -i=<in>
                              [-if=<inFormat>] [-o=<out>] [-of=<outFormat>]
                              [-p=<pipeline>] [-w=<workDir>]
transform input file to output file
  -c, --check, --validate
  -d, --cwd, --outdir=<outDir>
                            output directory (and current working directory)
  -h, --help
  -i, --in=<in>
      -if, --informat=<inFormat>

  -o, --out=<out>
      -of, --outformat=<outFormat>

  -p, --pipeline=<pipeline>
      --princeapi           use the prince API for cssprint (nop for fo
                              pipeline)
  -w, -b, --workdir, --basedir=<workDir>
                            basedir of relative paths

Hence, a conversion from *.adoc to *.pdf using the xsl-fo pipeline (see above) would be:

> ./bin/db-toolchain transform --outdir . -p xsl-fo -if AD -of PDF \
  -w downloads \
  -i downloads/integrator-guide.adoc

Currently supported formats are:

  • AD asciidoctor text file format (extension: *.adoc)
  • DB docbook (5.1) XML format (extension *.db.xml)
  • FO XSL formatting objects XML format (extension *.fo.xml)
  • XHTML markup (extensions: *.xhtml and *.html.xml)
  • HTML5 markup (extensions: *.html5 and *.html)
  • PDF document format (extension: *.pdf)

Docbook

Resources

Instructions

References

Big Examples

DB Tools

asciidoctor
Convert to asciidoctor

Tools with DB output

Docbook Stylesheets

XSLT 1.0 Stylesheets

XSLT 2.0 Stylesheets

XSLT 3.0 Stylesheets

BBC XSLT Stylesheets for Html5 (old)

Technology used with DB XSLT 2.0

XSLT 1.0

Customization

Html, xHtml, Html5

Parser

Validating DB

Technology used for DB Validation

Math with DB

MathML Implementations

Other Technology for Math

Diagrams

DB to ePub

Other Technology for ePub

(Source) Code Syntax Highlighting in DB

FOP

FOP and SVG

dblatex

Asciidoctor

Print-CSS

CSS Print Stylesheets

Print-CSS Renderer

Open Source Implementations

CSS drafts

Alternative Technology

Tex based

Markdown to Book (e.g. pandoc)

Markdown editors

Markdown to asciidoc

IPC

Java to Java

Java to JS

About

An update-to-date docbook toolchain (xslt20, fop 2.4.0-dev, ...)

Languages

Language:Java 73.7%Language:Kotlin 18.6%Language:Shell 3.5%Language:JavaScript 2.4%Language:XProc 0.9%Language:TypeScript 0.8%