Welcome!

Linux Containers Authors: Pat Romanski, Liz McMillan, Yeshim Deniz, Elizabeth White, Zakia Bouachraoui

Related Topics: Linux Containers

Linux Containers: Article

DocBook can be a sysadmin's best friend

Failure to document your processes and policies will probably come back to haunt you. Here's a free, open process that can help.

(LinuxWorld) -- Technical documentation is the savior and bane of every programmer and system administrator. On one hand, we need documentation as it helps us learn and understand what we need to accomplish. As long as we don't need to write it, we value documentation above all else.

Most technical people I know don't like to write. They put Post-it Notes all over the place describing how to do this or that, and usually nothing more organized than a really big text file.

The big-text-file system may work for some, but what happens when your not-so-technical manager comes to you and says, "What is our policy on XYZ?" Of course, you can extemporaneously pronounce the policy until the manager's eyes glaze over. Sometimes that works.

Then there is the manager who's not technical, but sharp as a whip. That manager says, "Yeah, yeah, let's see the documentation." Now you're in trouble. The documentation is not structured, organized, thought-out, or presentable.

How do you keep track of your documentation, provide PDF or RTF for the brass, and not go insane? The answer comes in two parts. The first is CVS, a tool for concurrent version control. We will not be covering CVS in this article. Instead we will be covering the second, DocBook. DocBook is an SGML/XML DTD that provides an easy way to write technical documentation. DocBook is similar to HTML/XHTML in that it is tag-based, and intended to be structured through formal mark-up.

A great advantage to DocBook is that you have a source-compilable document that can be transformed easily into other formats. Typically, the available formats are HTML, Postscript, PDF, and RTF (Rich Text Format), which is the Esperanto of Microsoft Word files. If your documentation needs to be placed on the Web, you transform the source to HTML. If your documentation needs to be manager editable, you transform it to RTF, or if your documentation needs to be business presentable, you transform it to PDF. All transformations are available from the original source.

There is a misconception among many new users that DocBook is overly complicated. This is not the case. New users tend to get overwhelmed by the flexibility DocBook offers.

DocBook formats at a glance

Today, there are three DocBook types:

  • Book
  • Article
  • Simplified

Book and Article work as XML or SGML and are specified within the DTD declaration. They are as they appear, designed to be either read as an article or a book. For example, an article will look similar to this:

<Article>
 <Author>
  <firstname>Joshua</firstname><surname>Drake</surname>
 </Author>
<section><title>Introduction</title>
 <para>
  blah blah blah
 </para>
</section>
</Article>

DocBook's tags are topic identified. If you look at the tags, the identify what you are writing about, e.g. author identifies the author of the document. This is the exceptional part of Docbook because the document structure makes the author stay on topic. If I have a <section><title>C++ Programming</title> I obviously won't write about Pascal.

Some examples

I'll talk mainly about DocBook SGML. Here is a simple DocBook document:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<book>
  <bookinfo>
    <title>An Example DocBook Document.</title>
  </bookinfo>
  <chapter>
    <title>First Chapter</title>
     <para>
       This is the first chapter of my new policy manual.
     </para>
    <sect1>
      <title>Which policy</title>
       <para>
        This is the first section in my new policy manual.
	</para>
     </sect1>
  </chapter>
 </book>

As you can see, it really doesn't look all that different from HTML. There are some notable differences, however. DocBook is forcibly structured. If you do not write Docbook in valid SGML (or XML) the output, will not look correct, and may fail entirely. HTML is a bit more forgiving. For example:

<title>HTML Document</title>
<body>
 <table border="1">
  <tr><td>
   Hello
  <tr><td>
   Good Bye
  </td></tr>
 </table>

While most Web browsers will render the previous example in a useful manner, it is not technically valid HTML. The valid HTML is:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
                  "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
<title>HTML Document</title>
<body>
 <table border="1">
  <tr><td>
   Hello
  </td></tr>
  <tr><td>
   Good Bye
  </td></tr>
 </table>
</body>

Notice that every opened tag is subsequently closed. DocBook, outside of some specific exclusions, requires that all tags be closed, and in the corresponding tag depth to where they were opened. DocBook also provides tags for the identification of almost any element that would be needed with a document. The following example shows a slightly more advanced DocBook document:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<book>
  <bookinfo>
    <title>An Example DocBook Document.</title>
    <authorgroup>
      <author>
        <firstname>Joshua</firstname>
        <surname>Drake</surname>
        <affiliation>
          <shortaffil>Command Prompt, Inc.</shortaffil>
        </affiliation>
      </author>
    </authorgroup>
    <pubdate>August 2001</pubdate>
    <edition>1st</edition>
    <copyright>
      <year>2001</year>
      <holder>Command Prompt, Inc</holder>
    </copyright>
  </bookinfo>
  <chapter>
    <title>First Chapter</title>
    <para>
      This is the first chapter of my new policy manual.
    </para>
    <sect1>
      <title>Which policy</title>
      <para>
      This is the first section in my new policy manual.
      </para>
      <sect2>
        <title>This is a subsection of the first section.</title>
        <para>
          Welcome to my subsection
        </para>
      </sect2>
    </sect1>
    <sect1>
      <title>This is the second section of my document.</title>
      <para>Welcome to the second section.</para>
      <sect2>
        <title>This is a subsection of the second section</title>
        <para>
          Welcome to my subsection of the second section.
        </para>
        <sect3>
          <title>This is a subsection of my subsection</title>
          <para>
             Welcome to my subsection of my subsection.
          </para>
        </sect3>
      </sect2>
    </sect1>
  </chapter>
</book>

This structure may seem complicated, especially if you are coming from a word processing background. Word processors are great for writing letters, but they are not designed to meet the needs of a technical documenter. DocBook provides the ability to concentrate on writing your documentation, and worry about the processing and presentation later. Considerations such as fonts, and the generation of the table of contents are automatically completed through the use of SGML/XML processors such as OpenJade, and DSSSL stylesheets (or XSL for DocBook XML).

The stylesheets are customizable, but they are typically global to an installation. This means that when you write your documentation in DocBook you will not have to worry about consistency. In other words, all of your documents will look how you want them to look, every time. There isn't any struggle in getting the table style to be just right, or the section heading to look a certain way. For an example of the HTML output of the above example refer to the resources.

This was a very rudimentary introduction to DocBook. I wrote the examples to illustrate the core simplicity of the SGML. The potentially difficult task in writing DocBook is not the actual writing, but it is processing the source document once you are complete. In a future article, I will discuss methods of processing your SGML source to produce not only HTML, but RTF, Postscript, and PDF.

More Stories By Joshua Drake

Joshua Drake is the co-founder of Command Prompt, Inc., a PostgreSQL and Linux custom development company. He is also the current author of the Linux Networking HOWTO, Linux PPP HOWTO, and Linux Consultants HOWTO. His most demanding project at this time is a new PostgreSQL book for O'Reilly, 'Practical PostgreSQL'

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


IoT & Smart Cities Stories
Headquartered in Plainsboro, NJ, Synametrics Technologies has provided IT professionals and computer systems developers since 1997. Based on the success of their initial product offerings (WinSQL and DeltaCopy), the company continues to create and hone innovative products that help its customers get more from their computer applications, databases and infrastructure. To date, over one million users around the world have chosen Synametrics solutions to help power their accelerated business or per...
A valuable conference experience generates new contacts, sales leads, potential strategic partners and potential investors; helps gather competitive intelligence and even provides inspiration for new products and services. Conference Guru works with conference organizers to pass great deals to great conferences, helping you discover new conferences and increase your return on investment.
Business professionals no longer wonder if they'll migrate to the cloud; it's now a matter of when. The cloud environment has proved to be a major force in transitioning to an agile business model that enables quick decisions and fast implementation that solidify customer relationships. And when the cloud is combined with the power of cognitive computing, it drives innovation and transformation that achieves astounding competitive advantage.
Digital Transformation: Preparing Cloud & IoT Security for the Age of Artificial Intelligence. As automation and artificial intelligence (AI) power solution development and delivery, many businesses need to build backend cloud capabilities. Well-poised organizations, marketing smart devices with AI and BlockChain capabilities prepare to refine compliance and regulatory capabilities in 2018. Volumes of health, financial, technical and privacy data, along with tightening compliance requirements by...
DXWorldEXPO LLC announced today that ICOHOLDER named "Media Sponsor" of Miami Blockchain Event by FinTechEXPO. ICOHOLDER gives detailed information and help the community to invest in the trusty projects. Miami Blockchain Event by FinTechEXPO has opened its Call for Papers. The two-day event will present 20 top Blockchain experts. All speaking inquiries which covers the following information can be submitted by email to [email protected] Miami Blockchain Event by FinTechEXPOalso offers sp...
Digital Transformation is much more than a buzzword. The radical shift to digital mechanisms for almost every process is evident across all industries and verticals. This is often especially true in financial services, where the legacy environment is many times unable to keep up with the rapidly shifting demands of the consumer. The constant pressure to provide complete, omnichannel delivery of customer-facing solutions to meet both regulatory and customer demands is putting enormous pressure on...
SYS-CON Events announced today that IoT Global Network has been named “Media Sponsor” of SYS-CON's @ThingsExpo, which will take place on June 6–8, 2017, at the Javits Center in New York City, NY. The IoT Global Network is a platform where you can connect with industry experts and network across the IoT community to build the successful IoT business of the future.
The best way to leverage your Cloud Expo presence as a sponsor and exhibitor is to plan your news announcements around our events. The press covering Cloud Expo and @ThingsExpo will have access to these releases and will amplify your news announcements. More than two dozen Cloud companies either set deals at our shows or have announced their mergers and acquisitions at Cloud Expo. Product announcements during our show provide your company with the most reach through our targeted audiences.
Machine learning has taken residence at our cities' cores and now we can finally have "smart cities." Cities are a collection of buildings made to provide the structure and safety necessary for people to function, create and survive. Buildings are a pool of ever-changing performance data from large automated systems such as heating and cooling to the people that live and work within them. Through machine learning, buildings can optimize performance, reduce costs, and improve occupant comfort by ...
@DevOpsSummit at Cloud Expo, taking place November 12-13 in New York City, NY, is co-located with 22nd international CloudEXPO | first international DXWorldEXPO and will feature technical sessions from a rock star conference faculty and the leading industry players in the world. The widespread success of cloud computing is driving the DevOps revolution in enterprise IT. Now as never before, development teams must communicate and collaborate in a dynamic, 24/7/365 environment. There is no time t...