Welcome!

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

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
Early Bird Registration Discount Expires on August 31, 2018 Conference Registration Link ▸ HERE. Pick from all 200 sessions in all 10 tracks, plus 22 Keynotes & General Sessions! Lunch is served two days. EXPIRES AUGUST 31, 2018. Ticket prices: ($1,295-Aug 31) ($1,495-Oct 31) ($1,995-Nov 12) ($2,500-Walk-in)
Andrew Keys is Co-Founder of ConsenSys Enterprise. He comes to ConsenSys Enterprise with capital markets, technology and entrepreneurial experience. Previously, he worked for UBS investment bank in equities analysis. Later, he was responsible for the creation and distribution of life settlement products to hedge funds and investment banks. After, he co-founded a revenue cycle management company where he learned about Bitcoin and eventually Ethereal. Andrew's role at ConsenSys Enterprise is a mul...
Nicolas Fierro is CEO of MIMIR Blockchain Solutions. He is a programmer, technologist, and operations dev who has worked with Ethereum and blockchain since 2014. His knowledge in blockchain dates to when he performed dev ops services to the Ethereum Foundation as one the privileged few developers to work with the original core team in Switzerland.
René Bostic is the Technical VP of the IBM Cloud Unit in North America. Enjoying her career with IBM during the modern millennial technological era, she is an expert in cloud computing, DevOps and emerging cloud technologies such as Blockchain. Her strengths and core competencies include a proven record of accomplishments in consensus building at all levels to assess, plan, and implement enterprise and cloud computing solutions. René is a member of the Society of Women Engineers (SWE) and a m...
Digital Transformation and Disruption, Amazon Style - What You Can Learn. Chris Kocher is a co-founder of Grey Heron, a management and strategic marketing consulting firm. He has 25+ years in both strategic and hands-on operating experience helping executives and investors build revenues and shareholder value. He has consulted with over 130 companies on innovating with new business models, product strategies and monetization. Chris has held management positions at HP and Symantec in addition to ...
The challenges of aggregating data from consumer-oriented devices, such as wearable technologies and smart thermostats, are fairly well-understood. However, there are a new set of challenges for IoT devices that generate megabytes or gigabytes of data per second. Certainly, the infrastructure will have to change, as those volumes of data will likely overwhelm the available bandwidth for aggregating the data into a central repository. Ochandarena discusses a whole new way to think about your next...
CloudEXPO | DevOpsSUMMIT | DXWorldEXPO are the world's most influential, independent events where Cloud Computing was coined and where technology buyers and vendors meet to experience and discuss the big picture of Digital Transformation and all of the strategies, tactics, and tools they need to realize their goals. Sponsors of DXWorldEXPO | CloudEXPO benefit from unmatched branding, profile building and lead generation opportunities.
Dynatrace is an application performance management software company with products for the information technology departments and digital business owners of medium and large businesses. Building the Future of Monitoring with Artificial Intelligence. Today we can collect lots and lots of performance data. We build beautiful dashboards and even have fancy query languages to access and transform the data. Still performance data is a secret language only a couple of people understand. The more busine...
All in Mobile is a place where we continually maximize their impact by fostering understanding, empathy, insights, creativity and joy. They believe that a truly useful and desirable mobile app doesn't need the brightest idea or the most advanced technology. A great product begins with understanding people. It's easy to think that customers will love your app, but can you justify it? They make sure your final app is something that users truly want and need. The only way to do this is by ...
DXWorldEXPO LLC announced today that Big Data Federation to Exhibit at the 22nd International CloudEXPO, colocated with DevOpsSUMMIT and DXWorldEXPO, November 12-13, 2018 in New York City. Big Data Federation, Inc. develops and applies artificial intelligence to predict financial and economic events that matter. The company uncovers patterns and precise drivers of performance and outcomes with the aid of machine-learning algorithms, big data, and fundamental analysis. Their products are deployed...