You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

85 lines
2.6 KiB

4 years ago
////
Included in:
- user-manual: DocBook
////
Asciidoctor can produce DocBook 5.0 output.
Since the AsciiDoc syntax was designed with DocBook output in mind, the conversion is very good.
There's a corresponding DocBook element for each markup in the AsciiDoc syntax.
To convert the `mysample.adoc` document to DocBook 5.0 format, call the processor with the backend flag set to `docbook`.
$ asciidoctor -b docbook mysample.adoc
A new XML document, named `mysample.xml`, will now be present in the current directory.
$ ls
mysample.adoc mysample.html mysample.xml
Here's a snippet of the XML generated by the DocBook converter.
.XML generated from AsciiDoc
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<article xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info>
<title>Hello, AsciiDoc!</title>
<date>2013-09-03</date>
<author>
<personname>
<firstname>Doc</firstname>
<surname>Writer</surname>
</personname>
<email>doc@example.com</email>
</author>
<authorinitials>DW</authorinitials>
</info>
<simpara>
An introduction to <link xl:href="http://asciidoc.org">AsciiDoc</link>.
</simpara>
<section xml:id="_first_section">
<title>First Section</title>
<itemizedlist>
<listitem>
<simpara>item 1</simpara>
</listitem>
<listitem>
<simpara>item 2</simpara>
</listitem>
</itemizedlist>
</section>
</article>
----
If you're on Linux, you can view the DocBook file with {uri-yelp}[Yelp].
$ yelp mysample.xml
And of course, if you're using the Asciidoctor Ruby API, you can generate a DocBook document directly from your application.
.Generate DocBook output from the API
[source,ruby]
----
Asciidoctor.convert_file 'mysample.adoc', backend: 'docbook'
----
By default, the docbook converter produces DocBook 5.0 output that is compliant to the DocBook 5.0 specification.
A summary of the differences are as follows:
* XSD declarations are used on the document root instead of a DTD
* `<info>` elements for document info instead of `<articleinfo>` and `<bookinfo>`
* elements that hold the author's name are wrapped in a `<personname>` element
* the id for an element is defined using an `xml:id` attribute
* `<link>` is used for links instead of `<ulink>`
* the URL for a link is defined using the `xl:href` attribute
Refer to {uri-docbook5}[What's new in DocBook v5.0?] for more details about how DocBook 5.0 differs from DocBook 4.5.
If you need to output DocBook 4.5, you may find the community-supported {uri-docbook45}[DocBook 4.5 Converter] useful.
$ asciidoctor -b docbook45 mysample.adoc