boost.png (6897 bytes) Home Libraries People FAQ More

PrevUpHomeNext

From HTML to BoostBook

Most library authors are comfortable with writing HTML documentation. Writing DocBook documentation (and, by extension, BoostBook documentation) is quite similar to writing HTML, except that BoostBook uses different element names from HTML (see Table 15.1, “Converting HTML elements to BoostBook”) and BoostBook XML is a much more rigid format than HTML.

One of the easiest ways to convert HTML documentation into BoostBook documentation is to use HTML Tidy to transform your HTML into valid XHTML, which will make sure that all elements are properly closed, then apply the transformations in Table 15.1, “Converting HTML elements to BoostBook” to the body of the XHTML document. The following command uses HTML Tidy to transform HTML into valid XHTML:

  tidy -asxhtml input.html > output.xhtml

When converting documentation from HTML to BoostBook, note that some redundant information that has to be manually maintained in HTML is automatically generated in BoostBook: for instance, the library categorizations, purpose, and author list described in the section called “Defining a BoostBook library” are used both in the documentation for the library and to build alphabetical and categorized lists of known libraries; similarly, tables of contents are built automatically from the titles of sections in the BoostBook document.

Table 15.1. Converting HTML elements to BoostBook

HTML BoostBook

<h1>, <h2>, etc.

<section>, <title>; See the section called “Sectioning in BoostBook”

<i>, <em>

<emphasis>

<b>

<emphasis role="bold">

<ol>

<orderedlist>

<ul>

<itemizedlist>

<li>

<listitem>

<pre>

<programlisting>

<code>

<computeroutput>,<code>

<p>

<para>, <simpara>

<a>

<xref>, <link>, <ulink>;, See the section called “Linking in BoostBook”

<table>, <tr>, <th>, <td>

<table>, <informaltable>, <tgroup>, <thead>, <tfoot>, <tbody>, <row>, <entry>, <entrytbl>; BoostBook tables are equivalent to DocBook tables, for which there is a good tutorial here

Copyright © 2003 Douglas Gregor

PrevUpHomeNext