Docbook and LyX Part 1

Category: Techwriter

LyX excels as a word processor that takes out the complications of typesetting and format conversion. LyX has support for LaTeX, XHTML, and PDF output while providing adequate support for XML and even Docbook. Although Docbook is still best written using a text editor or a capable XML editor such as Bluefish and XML Copy Editor, there are advantages to using non-commercial LyX. Longtime users of earlier versions of Docbook know that one of the advantages of Docbook is its very specific library of tags, which are arguably more restrictive than HTML5 and Dita. LyX doesn't provide access to these tags nor the typical features associated with commercial and open source XML editors. However, LyX's word processor interface and ability to export to XML make it a good starting point to begin work with a Docbook article.

In this article, we'll use LyX to create a simple Docbook article. We'll also examine the resulting XML file in XML Copy Editor while validating it with the most recent Docbook XML DTD.

Getting started using the Docbook Article template

Before beginning, check that your system has the required Docbook dependencies. This tutorial uses LyX ver. 2.06 running on Fedora 18 Xfce, which already includes most Docbook packages.  Most Linux distributions already include Docbook packages but you can check if this requirement is fulfilled in LyX.

To check Docbook support in Lyx:

1. Click Help then LaTeX Configuration.
2. Check if Docbook is "found" on the system.




If LyX reports that Docbook requirements are all right then you can begin writing your Docbook article.

To create a new document using the Docbook template:

1. Click File then New from Template...
2. Select Docbook_article.lyx
3. Click Open
4. The LyX document window will display placeholders for title, date, author, abstract, section, and a paragraph.




Since I plan to write a simple contiguous list of articles, I deleted the Abstract. Most technical writers would also probably want to adjust the depth of numbering of the sections, subsections and paragraphs.

To change section numbering in LyX:

1. Click Document then Settings . . .
2. Click Numbering & TOC on the left pane.
3. Drag the slider to determine which parts of the document will automatically be numbered by LyX.




Note: If you intend to use LyX to export the document as PDF, these settings directly control the PDF bookmarks that will be added to the PDF output. However, if you intend to export to XML and use xslt for transformations then you can skip these settings.

Docbook is a structured approach to markup so it's very useful to open LyX's Outline pane to check if your document is structured properly. Of course, LyX's structure pane won't reflect the XML tags that will be later visible once the LyX document is saved as Docbook XML but it will help keep your text organized.

To display the Outline view in LyX:

1. Click Document, then Outline.
2. Click the control buttons to manually increase or decrease the depth of sections. You can also click the arrows to move whole text blocks across the document tree. This makes arranging document sections extremely easy as compared to cutting, copying and pasting text in an XML editor.



Continued in Docbook and LyX Part 2