# Converting Documents to DocBook XML

A variety of free and commercial tools exist for doing up conversion of non-XML formats to DocBook. A few are listed here for your convenience. A more comprehensive list is available from Convert Other Formats to DocBook.

## Text to DocBook

The txt2docbook tool allows one to convert a ascii (README-like) file to a valid docbook xml document. It simplifies the publishing of rather small papers significantly. The input format was inspired by the APT-Convert tool from .

The script can be downloaded from .

## OpenOffice.org to DocBook

As of OpenOffice.org (OOo) 1.1RC there has been support for exporting files to DocBook format.

Although OOo uses the full DocBook document type declaration, it does not actually export the full list of DocBook elements. It uses a simplified DocBook tag set which is geared to on-the-fly rendering. (Although it is not the official Simplified DocBook which is described in .) The OpenOffice simplified (or special docbook) is available from http://www.chez.com/ebellot/ooo2sdbk/.

### Open Office 1.0.x

OOo has been tested by LDP volunteers with mostly positive results. Thanks to Charles Curley (charlescurley.com) for the following notes on using OOo version 1.0.x:

#### Check the version of your OpenOffice

These notes may not apply to the version of OOo you are using.

- To be able to export to DocBook, you must have a Java runtime environment (JRE) installed and registered with OOo--a minimum of version 4.2.x is recommended. The configuration instructions will depend on how you installed your JRE. Visit the OOo web site for help with your setup.

  Contrary to the OOo documentation, the Linux OOo did not come with a JRE. I got one from Sun.

- The exported file has lots of empty lines. My 54 line exported file had 5 lines of actual XML code.

- There was no effort at pretty printing.

- The header is: `<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">`

- The pull-down menu in the File Save As dialog box for file format indicates that the export format is DocBook (simplified). There is no explanation of what that simplified indicates. Does OOo export a subset of DocBook? If so, which elements are ignored? Is there any way to enter any of them manually?

- There is NO documentation on the DocBook export filter or whether OOo will import it again.

Conclusions: OOo 1.1RC is worth looking at if you want a word processor for preparing DocBook documents.

However, I hope they cure the lack of documentation. For one thing, it would be nice to know which native OOo styles map to which DocBook elements. It would also be nice to know how to map one's own OOo styles to DocBook elements.

### Open Office 1.1

Tabatha Marshall offers the following additional information for OOo 1.1.

> The first problem was when I tried to do everything on version 1.0.1. That was obviously a problem. I have RH8, and it was installed via rpm packages, so I ripped it out and did a full, new install of OpenOffice 1.1. It took a while to find out 1.1 was a requirement for XML to work.

> During the install process I believe I was offered the choice to install the XML features. I have a tendency to do full installs of my office programs, so I selected everything.

> I can't offer any advice to those trying to update their current OO 1.1. Their 3 ways aren't documented very well at the site (xml.openoffice.org) and as of this writing, I can't even find THAT on their site anymore. I think more current documentation is needed there to walk people through the process. Most of this was unclear and I had to pretty much experiment to get things working.

> Well, after I installed everything I had some configuration to do. I opened the application, and got started by opening a new file, choosing templates, then selecting the DocBook template. A nice menu of Paragraph Styles popped up for me, which are the names for all those tags, I noticed (you can see I don't use WYSIWYG often).

> With a blank doc before me (couldn't get to the XML Filter Settings menu unless some type of doc was opened), I went into Tools XML Filter Settings, and edited the entry for DocBook file. I configured mine as follows:

> - Doctype `-//OASIS//DTD DocBook XML V4.2//EN`

> - DTD `http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd`

> - XSLT for export `/usr/local/OpenOffice.org1.1.0/share/xslt/docbook/ldp-html.xsl`

> - XSLT for import `/usr/local/OpenOffice.org1.1.0/share/xslt/docbook/docbooktosoffheadings.xsl` (this is the default)

> - Template for import `/home/tabatha/OpenOffice/user/template/DocBook File/DocBookTemplate.stw`

> At first, if I opened an XML file that had even one parsing error, it would just open the file anyway and display the markup in OO. I have many XML files that use &copy; and other types of entities which show up as parse errors (depending on the encoding) even though they can be processed through. But today I was unable to open any of those files. I got input/output errors instead. Still investigating that one.

> However when you do successfully open a document (one parsing with no errors), it puts it automatically into WYSIWYG based on the markup, and you can then work from the paragraph styles menu like any other such editor.

> To validate the document, I used Tools XML Filter Settings, then clicked the Test XSLTs button. On my screen, I set up the XSLT for export to be `ldp-html.xsl`. If you test and there are errors, a new window pops up with error messages at the bottom, and the lines that need to be changed up at the top. You can change them there and progress through the errors until they're all gone, and keep testing until they're gone.

> If you want to open a file to see the source instead of the processed results, go to Tools XML Filter Settings Test XSLTs, and then under the Import section, check the Display Source box. My import XSLT is currently `docbooktosoffheadings.xsl` (the default) and the template for import is `DocBookTemplate.stw` (also default).

> I think this might work for some people, but unfortunately not for me. I've never used WYSIWYG to edit markup. Emacs with PSGML can tell me what my next tag is no matter where I am, validate by moving through the trouble spots, and I can parse and process from command line.

> With OpenOffice, you have to visit http://xml.openoffice.org/filters.html to find conversion tools.

## Microsoft Word to DocBook

Even if you want to use MS Word to write your documents, you may find w2XML useful. Note that this is not free software--the cost is around $130USD. There is, however, a trial version of the software.

## LaTeX to DocBook

Siep Kroonenberg reports that there is a package tex4ht that converts TeX and LaTeX to various flavors of XML. Currently, its support for DocBook output is limited. If you want to use tex4ht in its current state for LDP you will probably have to hack your LaTeX source beforehand and the generated XML afterwords.

## LyX to DocBook

This section is contributed by Chris Karakas.

You can use the LyX-to-X package to write your document conveniently in LyX (a visual editor originally developped as a graphical frontend to LaTeX), then export it to DocBook SGML and submit it to The LDP. This method is presented by Chris Karakas Document processing with LyX and SGML.

In the LyX-to-X project, LyX is used as a comfortable graphical SGML editor. Once the document is exported to SGML from LyX, it undergoes a series of transformations through sed and awk scripts that correct the SGML code, computes the Index, inserts the Bibliography and the Appendix and takes care of the correct invocation of openjade, pdftex, pdfjadetex and all the other necessary programs for the generation of HTML (chunked or not), PDF (with images, bookmarks, thumbnails and hyperlinks), PS, RTF and TXT versions.

All aspects of document processing are handled, including automatic Index generation, display of Mathematics in TeX quality both online and in print formats, as well as the use of bibliographic databases with RefDB. Special care is taken so that the document processing is as transparent to the user as possible - the aim being that the user writes in LyX, then presses a button, and the LyX-to-X script does the rest. Download the documentation and the LyX-to-X package from the Formats section.

## DocBook to DocBook Transformations

### XML and SGML DocBook

There are a few changes between DocBook XML and SGML. Handling these differences should be relatively easy for most small documents, and many authors will not need to make any changes to convert their documents other than the XML and DocBook declarations at the start of their document.

For others, here is a list of what you should keep in mind when converting your documents from SGML to XML.

#### Differences between XML and SGML elements

An XML element typically has three parts: the start tag, the content (your words) and the end tag. Qualifiers are added in the start tag and are known as attributes. They will always have a name and a quoted value.

    <filename class="directory">/usr/local<filename>

The start tag contains one attribute (class) with a value of directory. The end tag (also filename) must not contain any attributes.

- Element names (tags) and their attributes are case-dependent--typically lowercase. The following will not validate because the end tag <PARA> is uppercase:

      <para>This part will fail XML validation</PARA>

- All attributes in the start tag must be "quoted". This can be either single (') or double (") quotes, but not reverse (`) or smart quotes. The quote used to start a name="value" pair must be the same quote used at the end of the value. In other words: "this" would validate, but 'that" would not.

- Tags that have a start tag, but no end tag are referred to as empty because they do not contain (wrap around) anything. These tags must still be closed with a trailing slash (/). For example: `xref` must be written as <xref linkend="software"/>. You may not have any spaces between the / and >. (Although you may have a space after the final attribute: <xref linkend="foo" />.)

- Processing instructions that get sent to the transformation engine (DSSSL or XSLT) and must have a question mark at the end of the tag. All processing instructions are removed from the output stream. The XML version of this tag would look like this:

      <?dbhtml filename="foo"?>

- If you're converting from SGML to XML, be sure file names refer to .xml files instead of .sgml. Some tools may get confused if a .sgml file contains XML.

- Tag minimizations were used in SGML instead of writing out the element name in the end tag. Example: `para`This is foo.`` Tag minimizations are not supported in XML and their use is discouraged in DocBook.

### Changing DTDs

The significant changes between version changes in the DTD involve changes to the elements (tags). Elements may be: deprecated (which means they will be removed in future versions); removed; modified; or added. Almost all authors will run into a changed or deprecated tag when going from a lower version of DocBook to a higher version.

DocBook: The Definitive Guide does an excellent job of showing you how elements fit together. For each element it tells you what an element must contain (its content model) and what is may be contained in (who its parents are). For example: a `note` must contain a `para`. If you try to write <note>Content in a note</note> your document will not validate. Learning how elements are assembled will make it a lot easier to understand any validation errors that are thrown at you. If you get truly stuck you can also email the LDP's docbook mailing list for extra hints. Information on subscribing is available from

All tags that have been deprecated or changed for 4.x are listed in DocBook: The definitive guide, published by O'Reilly and Associates. This book is also available on-line from http://www.docbook.org.

#### Differences between version 3.x and 4.x

Here are a few elements that are of particular relevance to LDP authors:

- ##### `artheader`

  has been changed to `articleinfo`. Most other header elements have been renamed to info.

- ##### `graphic`

  has been deprecated and will be removed as of DocBook 5.x. To prepare for this, start using `mediaobject`. There is more information about `mediaobject` in .

- ##### `imagedata`

  file formats must now be written in UPPERCASE letters. If you use lowercase or mixed-case spellings for your file formats, it will fail.

  Valid:

      <imagedata format="EPS" fileref="foo.eps">

  Invalid:

      <imagedata format="eps" fileref="foo.eps">