How to avoid learning XML

David Cramer

1.1

Copyright © 2003 David Cramer

May 18, 2003

Revision History
Revision 1.1May 18, 2004
Mentioning new editors like XMLMind's XXE and Syntext's Serna. Other minor updates.
Revision 1.0March 25, 2003
Version delivered to Online SIG at local STC meeting.
Revision .1March 23, 2003
Initial draft.

Why would I want to avoid learning XML?

The title of this talk is actually an allusion to Mike Smith's article Don't learn XML , where he suggests using the DocBook DTD and stylesheets to get started using XML for documentation rather than starting from scratch, writing your own DTD, stylesheets, and so on. My title is more than a little misleading. I'll explain how to get started with DocBook without learning much XML, but I also hope to show you how to get started learning the technologies that make a DocBook-based system tick.

Note

The html version of this page can be viewed with any browser. If you're viewing this page as html in the Opera web browser, press F11 to view the slide show version in full screen.

Goals of this talk

What is DocBook?

What is this “DocBook” you speak of?

What does DocBook look like?

A DocBook XML document looks a lot like the xhtml source—both are instances XML DTDs. The key difference is that DocBook is primarily semantic markup for describing software and hardware documentation. xhtml is more general and less focused on semantics.

Sample DocBook XML:

<para><command>ControlProcess</command> writes 
its trace information to <filename>
<envar>$BJROOT</envar>/logs/ControlProcess_
<replaceable>hostname</replaceable>.out</filename> 
(where <replaceable>hostname</replaceable> is the name 
of the activation host on which 
<command>ControlProcess</command> is running).</para>

Sample XHTML:

<p><tt>ControlProcess</tt> writes 
its trace information to <tt>
<i><tt>$BJROOT</tt></i>/logs/ControlProcess_
<i>hostname</i>.out</tt> 
(where <i>hostname</i> is the name 
of the activation host on which 
<tt>ControlProcess</tt> is running).</p>

The DocBook converted to html and rendered:

ControlProcess writes its trace information to $BJROOT/logs/ControlProcess_hostname.out (where hostname is the name of the activation host on which ControlProcess is running).

Ok, but what is DocBook really?

More broadly defined, DocBook is the DTD mention above and the mechanisms to transform DocBook documents to a useful format.

There are at least three separate existing mechanisms that I know of for transforming DocBook instances, each based on a different stylesheet language. If none of these mechanisms suit your needs, it is possible to create a new one from scratch, though that would be non-trivial. The important point is that DocBook is an open standard, so ultimately you own your data.

Of the existing mechanisms, two are free (as in freedom and beer) open source and a third is commercial:

What can DocBook be made to look like?

XML facilitates creating multiple output from a single source. All of the documents linked below were created from the identical XML file. This talk also is what it is about. I wrote it in a form of DocBook (the slides DTD) and use XSLs to transform it into various output types.

  • The slide show you're looking at now/a single, monolithic htmlIf you are viewing this page on the web, open this page in the Opera web browser and press F11 to view as a full screen slide show.

  • “chunked” html (example) : each chapter, section, and so on is broken into a separate html page to create an online book.

  • HTML Help or RoboHELP's WebHelp (example) : We also created chms from our server books because that format was more convenient in some circumstances. We used a less booklike variant for help sets. If you have a chm file, you can easily create WebHelp by opening the .hhp file in RoboHELP and generating the WebHelp. This requires owning RoboHELP.

  • Print output using the stock DocBook XSLs: the output of the DocBook XSL stylesheets if you don't customize anything.

  • The Motive pdf (example) : this is the output from the stylesheets we use at Motive. After Motive acquired BroadJump, I customized the DocBook stylesheets to mimic the FrameMaker template they were using.

  • Eclipse documentation plugins.

  • The BroadJump pdf (example) : this is the output from the stylesheets we used at BroadJump.

  • The BroadJump “technical whitepaper” pdf (example) : We created this stylesheet for a series of whitepapers that described our product's architecture.

  • The DocBook 'slides' XSLs : A browser based slide show that doesn't depend on Opera like the one you're viewing now does. There are XSLs to create html with and without frames as well as fo/pdf.

  • You can even create a Word doc out of it. (example)

How do I write a DocBook document?

This is easily the most difficult thing to get used to when composing in DocBook or DTD that tries to focus on semantics rather than presentation. There's not one short or even long answer to the question of what the best authoring environment is, but recently a couple of editors have made strides in solving the problem of how to represent semantics and reasonable presentation at the same time.

WYSIWYG is ultimately impossible any time you produce multiple outputs from a single source. This subject is discussed every few months on one of the XML or DocBook lists.

See a list of DocBook authoring tools at the DocBook Wiki.

In addition to providing help authoring instances of DocBook XML (or any DTD) by indicating what elements are valid at what points, these tools validate documents. When a tool validates a document, it compares the XML to its DTD to see if it conforms to the DTD. If the document does not conform to the DTD, the tools typically try to indicate what and where the problem is, though they can't always tell you exactly what is wrong.

There are a few other editors at various levels of maturity. I hear Oxygen and Morphon mentioned sometimes.

How do I transform a DocBook document?

I'm not discussing DSSSL or fosi here.

Most of the tools that transform XML documents are command line. Example using xsltproc: 

xsltproc -o output.xml path/to/html/docbook.xsl input.xml

To use XSL to go to HTML Help, you must also run hhc or use the HTML Help workshop to compile the chm.

XSL does not take you directly to pdf. You use XSL to convert the DocBook document to xsl-fo, then use a fo renderer to convert that document to a pdf or postscript file.

There are several convenience tools that hide the transformation process from you to one degree or another. You certainly need either one of these or something you write yourself (a batch file, shell script, perl script, make file, ant script)

What is fo and what is a fo renderer?

FO (Formatting Objects) is part of the w3c's XSL specification. It is like html in that it describes how content should be presented, but unlike html, fo focuses on the printed page, so it provides for headers, footers, page number, and so on.

 

XSL is a language for expressing stylesheets. It consists of three parts: XSL Transformations (XSLT): a language for transforming XML documents, the XML Path Language (XPath), an expression language used by XSLT to access or refer to parts of an XML document. (XPath is also used by the XML Linking specification). The third part is XSL Formatting Objects: an XML vocabulary for specifying formatting semantics. An XSL stylesheet specifies the presentation of a class of XML documents by describing how an instance of the class is transformed into an XML document that uses the formatting vocabulary.

 
-- w3c  

See the DocBook Wiki for a complete list.

How do I change the way the output looks?

For many aspects of a document's appearance, you can control the behavior of the stylesheets by changing parameters. 

<xsl:param name="double.sided" select="1"/>
<xsl:param name="page.margin.inner">
  <xsl:choose>
    <xsl:when test="$double.sided != 0">1.25in</xsl:when>
    <xsl:otherwise>1in</xsl:otherwise>
  </xsl:choose>
</xsl:param>
<xsl:param name="page.margin.outer">
  <xsl:choose>
    <xsl:when test="$double.sided != 0">0.75in</xsl:when>
    <xsl:otherwise>1in</xsl:otherwise>
  </xsl:choose>
</xsl:param>

The parameters are described in the documentation that comes with the distribution.

Generated text

In addition to parameters, the stylesheets come with translations for strings that are generated. For example, one of the parameters lets you control how titles are formatted: 

   <l:context name="title-numbered">
      <l:template name="appendix" text="Appendix %n. %t"/>
      <l:template name="article/appendix" text="%n. %t"/>
      <l:template name="chapter" text="Chapter %n. %t"/>
      <l:template name="section" text="%n. %t"/>
   </l:context>
Separate files exist for each language and the stylesheets come with translations for around 40 languages.

What if there is no parameter for the thing I want to change?

In that case, you have 2 choices:

  1. If the thing you want to control would be generally useful to other users of the DocBook XSLs, submit an RFE to the maintainers.

  2. Change the behavior of the XSLs by overriding the templates.

    Overriding the templates requires that you know 1) Enough XSL to change the right code, and 2) what you want the resulting XML to do. So if you're changing the fo stylesheets, you have to know enough FO to know what you want the stylesheets to do.

Bob Stayton's book, DocBook XSL: The Complete Guide , is essential reading for learning how to customize the DocBook XSLs.

Glossary generation

One handy feature of the DocBook Open XSLs is that you can have a master glossary from which a custom glossary is built when you generate a document.

Note

The inclusion of terms in the glossary is not recursive. If the definitions of terms contain glossterms, these are not pulled into the glossary.

Pointing the XSLs to your master glossary

<xsl:param name="glossary.collection" 
select="'/local/path/to/glossary.xml'"/>

A very small master glossary

<!DOCTYPE glossary PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<glossary>
  <glossentry>
    <glossterm>0</glossterm>
     <glossdef>
      <para>Numeric zero, as opposed to the letter 'O'.</para>
    </glossdef>
  </glossentry>
</glossary>

Using glossary term in your document

<para>There's no Roman numeral for <glossterm 
   baseform="0">zero</glossterm>.</para>

Profiling

Another feature of the DocBook Open XSLs is the ability to filter out elements. This is like conditional text in FrameMaker.

Some paras ready to be profiled

<para>A common introductory paragraph.</para>
<para os="Windows">A paragraph specific to Windows.</para>
<para os="UNIX;MacOSX;Linux">A paragraph pertains to several UNIXes.
<phrase userlevel="beginner">When in doubt, use <userinput>man -k</userinput>
</phrase>
</para>

Running Saxon with profiling

java com.icl.saxon.StyleSheet -o sample.html sample.xml \
      ../html/profile-docbook.xsl \
      "profile.os=Windows" \
      "userlevel.os="beginner"

This behaves a little differently than FrameMaker. In FrameMaker, if you turn on a condition, then it appears even if it occurs within text that has been conditioned out.

Caution

Profiling, in part because it is more powerful than Frame's conditional text, provides an easy way for you to hang yourself.

The directory structure of the distribution

The XSL stylesheet distribution comes with several sets of stylesheets. The folder names indicate their purpose: fo, html, htmlhelp. See Profiling for information about profiling.

html/

Use docbook.xsl to generate a flat html file.

Use profile-docbook.xsl to generate a flat html file using profiling.

Use chunk.xsl...

Use profile-chunk.xsl...

htmlhelp/

Use htmlhelp.xsl to generate the collection of html pages, .hhc, .hhp, and .hhk files necessary to make a chm.

Use profile-htmlhelp.xsl to generate the collection of html pages, .hhc, .hhp, and .hhk files necessary to make a chm using profiling.

fo/

Use docbook.xsl to generate an xsl-fo file.

Use profile-docbook.xsl to generate an xsl-fo file using profiling.

References and Resources

The problem with DocBook is not a lack of documentation. In fact, there are probably too many guides for getting started that well meaning people have posted on the web over the years, but you may have difficulty figuring out which of these guides is current, which addresses your needs, and so on.

DocBook

Notice that you have to go to two separate places to get the DTD and stylesheets. That may seem strange (and even inconvenient), but there's a reason behind it. The DTD dictates the semantics of a DocBook document. There are some processing expectations associated with many elements, but it is not a requirement and further, there is no presupposition about what tool will be used to process the document. The stylesheets maintained at the DocBook Open Repository are not the last word on processing DocBook documents. You are free to build or buy a different implementation because you own your data.

XSLT

XSLFO

Questions and Answers

Is everything clear as mud?