XInclude Markdown inside DocBook
Description
DocBook is a semantics and well-structured markup language that require:
- to hand-write xml,
- or to use a specific WYSIWYG editor.
Therefore, it can be a brake to the adoption of a docbook toolchain within a team or a company… and let users writing documentation with their favorite word processor (or not!) or with additionnal tools like wikis, …
In that case, a simple and more flexible solution may respond to the initial need by mixing:
- docbook to aggregate contents,
- plain text to write human readable content.
Markdown is a lightweight markup languages
- easy to read,
- easy to write,
- easy to convert, (see ant + pandoc)
- easy to xinclude in docbook documents. This is (one of) the aim of ant4docbook.
Ant4docbook allow to take advantages of the two worlds by including Markdown plain text format within docbook documents.
Use case
Xinclude docbook-markdown.md inside docbook-markdown.xml.
docbook-markdown.xml
<?xml version="1.0" encoding="utf-8"?>
<article xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Test xinclude markdown</title>
<xi:include href="docbook-markdown.md"/>
</article>
docbook-markdown.md
A First Level Header
====================
A Second Level Header
---------------------
Now is the time for all good men to come to
the aid of their country. This is just a regular paragraph.
The quick brown fox jumped over the lazy dog's back.
### Header 3
> This is a blockquote.
>
> This is the second paragraph in the blockquote.
>
> ## This is an H2 in a blockquote
build.xml
<project name="docbook-markdown" default="docbook-and-markdown">
<taskdef name="dbk"
classname="net.sourceforge.ant4docbook.taskdefs.DocbookTask"
classpath="PATH/TO/ant4docbook.jar"/>
<!-- xinclude markdown -->
<target name="xinclude-markdown">
<dbk file="docbook-markdown.xml" tofile="docbook-markdown.pdf" />
</target>
<!-- or process markdown -->
<target name="process-markdown">
<dbk file="markdown.md" tofile="markdown.html" />
</target>
</project>
see: docbook-markdown.pdf