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
Fast/Flexible Linux OS Recovery
On Demand Now
In this live one-hour webinar, learn how to enhance your existing backup strategies for complete disaster recovery preparedness using Storix System Backup Administrator (SBAdmin), a highly flexible full-system recovery solution for UNIX and Linux systems.
Join Linux Journal's Shawn Powers and David Huffman, President/CEO, Storix, Inc.
Free to Linux Journal readers.Register Now!
- Download "Linux Management with Red Hat Satellite: Measuring Business Impact and ROI"
- Profiles and RC Files
- Astronomy for KDE
- Understanding Ceph and Its Place in the Market
- Maru OS Brings Debian to Your Phone
- Git 2.9 Released
- OpenSwitch Finds a New Home
- SoftMaker FreeOffice
- What's Our Next Fight?
- The Giant Zero, Part 0.x
With all the industry talk about the benefits of Linux on Power and all the performance advantages offered by its open architecture, you may be considering a move in that direction. If you are thinking about analytics, big data and cloud computing, you would be right to evaluate Power. The idea of using commodity x86 hardware and replacing it every three years is an outdated cost model. It doesn’t consider the total cost of ownership, and it doesn’t consider the advantage of real processing power, high-availability and multithreading like a demon.
This ebook takes a look at some of the practical applications of the Linux on Power platform and ways you might bring all the performance power of this open architecture to bear for your organization. There are no smoke and mirrors here—just hard, cold, empirical evidence provided by independent sources. I also consider some innovative ways Linux on Power will be used in the future.Get the Guide