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