Getting started with DocBook using XML Copy Editor

Category: Techwriter

If you're only getting started with a markup language like DocBook, XML editors can be helpful in learning the different elements, tags, and attributes available in the language.  However, editors won't teach you to write markup and you would still need a reference such as the online Definitive DocBook Guide .  That said, XML Copy Editor, available for Linux and Windows, is a popular XML editor used by enthusiasts and professionals and can be a great tool for learning DocBook.

Before beginning, it's important to note that you may still prefer a plain text editor especially if you're accustomed to Notepad+, Gedit,Vim, or Kwrite.   Using an XML editor can be intrusive and difficult to get used to at first but it's a good stepping stone if you want to learn how to author quickly. 

Setting up XML and Adding a DocBook Declaration

Before beginning, determine if you want to write an earlier DocBook 4.x version or the somewhat newer DocBook 5.x.  To understand the difference, visit the OASIS site or the overview found in the Definitive DocBook Guide. For this tutorial, we will be focusing on Docbook XML Version 5.0b3.  After launching XML Copy Editor, follow the steps below to begin writing your first DocBook file:

1. Click File and then New.

2. In the New Document window, select DocBook 5.0b book (*.xml).

3. XML Copy Editor will open a new document tab.  Click File then Save As... By default, XML Copy Editor will not add a file extension, so type a filename with the .xml extension.

4. On the document window, line 2 indicates the OASIS URL  path for the DTD.  If you're using a different DTD for your document, such as docbookx.dtd, then change or modify the path.   Visit the Docbook.org or the OASIS web site for more details and a list of the available DTD's or ask your school, organization, or company which DocBook DTD they use.  Think of DTD as a pattern your document has to follow strictly in order to be considered a legitimate DocBook file. 

At this point, it's important to note that if you want to validate your DocBook document with the publicly available DTD, you should be connected to the Internet.  XML Copy Editor uses the URL in line 2 to check if your document  followed the rules and structure of that version of DocBook.

Validating the Document

Even without changing XML Copy Editor's template, you can already validate the document with the 5.0b3 DTD. 

To validate the document with the DocBook DTD defined in your declaration using XML Copy Editor:

1. Click the green checkmark on the control bar or click XML, Validate, then DTD/XML Schema.  Alternately, click F5.

2. A message will be displayed in the Information box found at the bottom of the editor. 

3. As you start writing your document and using your DocBook reference, you would want to validate the DocBook every now and then to make sure you used the write tags and followed proper child and parent structure and sequence.

Adding Elements

1. The template XML Copy Editor provides is a great way to get started but obviously, there are many more tags available in DocBook.  For this example, we will remove the Appendix and Legal Notice tags.

2. After filling out the title and author, we're going to add the publisher.  According to our DocBook reference, publisher information is found under the <info> tag and can be followed with a <publishername> and <address>.

3. Press the Return key after the close tag </author> to create a new line.  Type <   and XML Copy Editor will display a list of possible tags that can be used under the <info> tag.  Select publisher.

4. Press > and XML Copy Editor will automatically place a close tag </publisher>. 

5. Press the Return key and press tab.  This "nests" the next set of information within the <publisher> tag.

6. Use the same process to add the <publishername> information and <address> which are all child elements of the <publisher> tag.

Adding Attributes

1. We will now add the label attribute for the first <chapter> tag.

2. Press the spacebar after <chapter and XML Copy Editor will display a list of possible attributes for the <chapter> tag. 

3. Select label and type = and XML Copy Editor will immediately add quotation marks.  Type your chapter label.

Well-Formed and Validated

To check if the XML was written based on XML rules and syntax, click on the Blue checkmark on the control panel or press F2.  Alternately, click XML and then Check for Well-formedness . The Information box will display an error or indicate if the document is well-formed.

Validate the document to the DocBook DTD again by clicking F5.

You have successfully created your first XML DocBook file and well on your way to using XML Copy Editor and DocBook for future projects.  XML Copy Editor has many more functions to try out and supports a variety of standards while providing useful tools like checking the Xpath and associating stylesheets.   It's a great way to learn various types of markup language even if you eventually plan to use a plain text editor, Terminal-based editors, or applications like Bluefish.