XML & DocBook: Structured Technical Documentation Authoring
If you are an author, it is okay to skim or skip the above technical explanations, although it helps if you have an idea about the process. If anything, it ensures that you don't need to bother with formatting and layout, because that all is done after you've written and sent the content.
What you should be concerned about as the author of technical documentation is restricted to things such as choosing the subject and scope of the document, developing a good outline or plan that guides you through the writing process, researching and checking the accuracy of your resources and statements and the like. For easy maintenance, it also might be a good idea to use a versioning system such as CVS. Versioning systems allow you to keep track of changes and to do a roll-back or restore in case of trouble. They also help if multiple people are working on the same set of files.
Once you know what to write and have installed all the tools and subsystems, the time has come to pour your content into an XML file. Whether you have chosen to use an XML editor or a plain-text editor, it is good to have an idea about the structure of an XML document and about the tags available in the standard DocBook vocabulary. Thus, if you want to represent an entity or object, such as a screenshot or terminal input, you know which tags to select or, at least, where to look for an overview of the possibilities. The full element reference can be consulted here. You also can check which tags are allowed to be included within other tags; parent tags are listed along with all possible child tags.
All DocBook XML files start with a declaration of the XML type being used, specifying the XML version, character encoding, document type and location of the DTD. This article you are reading now, for instance, begins with the following lines:
<?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">
Documents that contain only a few pages worth of data usually are put in an article structure using the <article> </article> tags around the text that follows the declaration. A simple sample article is represented by the following code:
Listing 1. Example of a Simple Article
<article> <articleinfo> <title>Example article</title> <author> <firstname>Machtelt</firstname> <surname>Garrels</surname> <affiliation> <orgname>CoreSequence.com</orgname> <address><email>spam.me@my domain</email></address> </affiliation> <pubdate>20040625</pubdate> <abstract> <para>This is an example article demonstrating simple DocBook XML tags. </para> </abstract> </articleinfo> <section><title>This is the first section</title> <para>It is a very short section containing only one paragraph, enclosed by para tags. The section has a title enclosed by title tags and is in turn enclosed by the section tags.</para> </section> <section><title>This is the second section</title> <para>It also has only one paragraph.</para> </section> </article>
In Listing 1, the first line after the declaration contains the opening article tag. The line after that begins the information about the article, including the title, author, affiliation, publication date and abstract tags. The title tag can be given as a child to many other tags. Next comes the author information, which allows for specifications of name, e-mail address and company or organization. Apart from company or organization, you also can specify organizational divisions, job titles and so on. After the author information comes the publication date, a section that also can contain remarks, trademarks, links and more. Next comes the abstract, a short description of the document's content.
Once the introductory information is supplied and the document has moved on to the main content, divisions in the document can be marked by sections and subsections. Sections and subsections have titles and consist of paragraphs. Normal text usually is enclosed by paragraph tags.
Other types of content can be added using a variety of tags. The DocBook DTD consists of over 300 tags altogether. Among the more commonly used are:
itemizedlist or orderedlist parents and listitem children, used to create lists such as the one you currently are reading
figure and informalfigure parents with mediaobject, imageobject and textobject children, used to include graphics
screen and programlisting tags, used to display terminal output, eventually using another type or size of font in the converted files
command, option, parameter and application tags, used to specify the type of entity between these tags, which usually results in italic or bold rendering or a different size or type of font
qandaset parents with qandaentry, question and answer children, used in a FAQ list
sect1 parents with sect2, sect3 and sect4 children, used to specify subsections
table parent tags with row and entry children, used to specify table rows and columns
Special Reports: DevOps
Have projects in development that need help? Have a great development operation in place that can ALWAYS be better? Regardless of where you are in your DevOps process, Linux Journal can help!
With deep focus on Collaborative Development, Continuous Testing and Release & Deployment, we offer here the DEFINITIVE DevOps for Dummies, a mobile Application Development Primer, advice & help from the experts, plus a host of other books, videos, podcasts and more. All free with a quick, one-time registration. Start browsing now...
- The Ubuntu Conspiracy
- Science on Android
- A First Look at IBM's New Linux Servers
- Vigilante Malware
- Disney's Linux Light Bulbs (Not a "Luxo Jr." Reboot)
- Vagrant Simplified
- Bluetooth Hacks
- System Status as SMS Text Messages
- Libreboot on an X60, Part I: the Setup
- October 2015 Issue of Linux Journal: Raspberry Pi