Mapping List HTML -> DocBook XML

Transformation of HTML Tag a

1. If the attribute name is set, an anchor element is created. The attribute name becomes the attribute id in DocBook. The value of the id attribute starts with the prefix "dbdoclet.id.". The original value is transformed in a way that it meets the requirements of a DocBook id. It must start with a letter and any non word characters are replaced by the underscore. Because the id's must be unique, an optional number can follow the index name to ensure uniqueness.

   Example 3.1. Example of mapping a to anchor

   The HTML code

   <a name="introduction" />

   will be converted to DocBook XML

   <anchor id="dbdoclet.id.introduction" />

   
   

2. If the attribute href starts with a "#" character, a link is created that points to the referenced spot in the content. If no spot with the appropiate name can be found a dummy spot is created at the beginning of the document.

   Example 3.2. Example of mapping a to link

   The HTML code

   <a href="#introduction">the introduction</a>

   will be converted to DocBook XML

   <link linkend="dbdoclet.id.introduction"/>

   
   

3. If the value of the attribute href doesn't start with "#" an ulink is created.

   Example 3.3. Example of mapping a to ulink

   The HTML code

   <a hef="http://www.dbdoclet.org">The dbdoclet homepage</a>

   will be converted to DocBook XML

   <ulink url="http://www.dbdoclet.org">DBDoclet Home</ulink>

   
   

4. A special case is the apprearance of an img inside an a, because in DocBook the nesting is the other way round.

   Example 3.4. Example of mapping a -> img to mediaobject -> ulink

   The HTML code

   <a href="http://www.dbdoclet.org"> <img src="image.gif" alt="Image"> </a>

   will be converted to DocBook XML

   <informalfigure>
     <mediaobject>
       <imageobject> 
         <imagedata fileref="./image.gif" format="GIF"/>
       </imageobject> 
     </mediaobject> 
     <ulink url="http://www.dbdoclet.org"></ulink>
   </informalfigure>
                     

   
   

Transformation of the HTML tag abbr

The tag abbr becomes the tag abbrev in DocBook.

Example 3.5. Example of mapping abbr to abbrev

The HTML code

<abbr>Mr.</abbr>

will be converted to DocBook XML

<abbrev>Mr.</abbrev>

Transformation of the HTML tag acronym

The tag acronym becomes the tag acronym in DocBook.

Example 3.6. Example of mapping acronym to acronym

The HTML code

<acronym>SGML</acronym>

will be converted to DocBook XML

<acronym>SGML</acronym>

Transformation of the HTML tag address

The tag address becomes the tag address in DocBook.

Example 3.7. Example of mapping address to address

The HTML code

<address>Hofbräuhaus, München</address>

will be converted to DocBook XML

<address>Hofbräuhaus, München</address>

Transformation of the HTML tag applet

The tag applet is ignored.

Transformation of the HTML tag area

The tag area is ignored.

Transformation of the HTML tag b

The tag b becomes emphasis with the attribute role set to bold.

Example 3.8. Example of mapping b to emphasis

The HTML code

<b>Hippopotamomus</b>

will be converted to DocBook XML

<emphasis role="bold">Hippopotamomus</emphasis>

Transformation of the HTML tag base

The tag base is ignored.

Transformation of the HTML tag basefont

The tag basefont is ignored.

Transformation of the HTML tag bdo

The tag bdo is ignored.

Transformation of the HTML tag big

The tag big is ignored.

Transformation of the HTML tag blockquote

The tag blockquote becomes the tag blockquote in DocBook.

Example 3.9. Example of mapping blockquote to blockquote

The HTML code

<blockquote>
Once upon a midnight dreary, while I pondered weak and weary,
Over many a quaint and curious volume of forgotten lore, 
While I nodded, nearly napping, suddenly there came a tapping,
As of some one gently rapping, rapping at my chamber door.
`'Tis some visitor,' I muttered, `tapping at my chamber door
 - Only this, and nothing more.'
</blockquote>

will be converted to DocBook XML

<blockquote>
  <para>Once upon a midnight dreary, while I pondered weak and weary,
Over many a quaint and curious volume of forgotten lore,
While I nodded, nearly napping, suddenly there came a tapping,
As of some one gently rapping, rapping at my chamber door.
`'Tis some visitor,' I muttered, `tapping at my chamber door
- Only this, and nothing more.'<para>
</blockquote>

Transformation of the HTML tag body

The tag body is ignored.

Transformation of the HTML tag br

The tag br becomes a new para, if the current element is also a para. Otherwise a simple newline is inserted into the output.

Transformation of the HTML tag button

The tag button is ignored.

Transformation of the HTML tag caption

The tag caption becomes the tag title in DocBook.

Example 3.10. Example of mapping caption to title

The HTML code

<caption>Caption</caption>

will be converted to DocBook XML

<title>Caption</title>

Transformation of the HTML tag center

The tag center is ignored.

Transformation of the HTML tag cite

The tag cite is ignored.

Transformation of the HTML tag code

The tag code becomes one of the tags literal or programlistingin DocBook, depending on the model of the parent DocBook element. If it is of kind "Content Model" the tag programlisting is used, otherwise literal is used.

Example 3.11. Example of mapping code to literal

The HTML code

<code>public class Brain</code>

will be converted to DocBook XML

<literal>public class Brain</literal>

Transformation of the HTML tag col

The tag col is ignored.

Transformation of the HTML tag colgroup

The tag colgroup is ignored.

Transformation of the HTML tag dd

The tag dd becomes listem - para in DocBook.

Example 3.12. Example of mapping dd to listitem

The HTML code

<dd>description</dd>

will be converted to DocBook XML

<listitem><para>description</para></listitem>

Transformation of the HTML tag del

The tag del is ignored.

Transformation of the HTML tag dfn

The tag dfn is ignored.

Transformation of the HTML tag dir

The tag dir becomes itemizedlist in DocBook.

Transformation of the HTML tag div

The tag div can be used for creating formal examples. If a div tag contains the attribute id with a value that starts with "example" (caseinsensitive) an example tag is created in the resulting DocBook code. Furthermore, if the attribute title is present, a formal example with a title is created, otherwise an informal one. The following paragraph shows an example.

Example 3.13. Example for the DocBook tag example

<div id="example_class_service" title="Example for the class service">
  <pre> 
public class Service { private String name; . . . }
  </pre>
</div>

              

The tag div can also be used for creating the DocBook tags Caution, Important, Note, Tip and Warning. If a div tag contains the attribute id with a value that starts with one of the name of these tags (caseinsensitive) an appropriate tag is created in the resulting DocBook code. Furthermore, if the attribute title is present, a formal tag with a title is created, otherwise an informal one. The following paragraph shows an example.

Example 3.14. Example for the DocBook tag tip

<div id="tip_class_service" title="Use DocBook Doclet">
  <p>Use the DocBook Doclet for generating reference handbooks out of your
  javadoc comments.</p>
</div>

              

Transformation of the HTML tag dl

The tag dl becomes variablelist in DocBook.

If the list is a nested list, the surrounding listitem tag is created automatically.

Transformation of the HTML tag dt

The tag dt becomes varlistentry - term in DocBook.

Example 3.15. Example of mapping dt to varlistentry

The HTML code

<dt>Term</dt><dd>Description</dd>

will be converted to DocBook XML

<varlistentry> 
  <term>Term</term>
  <listitem><para>description</para></listitem>
</varlistentry>

Transformation of the HTML tag em

The tag em becomes emphasis in DocBook.

Transformation of the HTML tag fieldset

The tag fieldset is ignored.

Transformation of the HTML tag font

The tag font is ignored.

Transformation of the HTML tag form

The tag form is ignored.

Transformation of the HTML tag frameset

The tag frameset is ignored.

Transformation of the HTML tags h1-6

The header tags of HTML are transformed to sect1-5 and bridgehead DocBook tags. The concrete mapping depends on the context in the created DocBook tree. dbdoclet keeps the nesting of section in the correct order, even if the nesting in the HTML source is somewhat strange.

Transformation of the HTML tag head

The tag head is ignored.

Transformation of the HTML tag hr

The tag hr is ignored.

Transformation of the HTML tag html

The tag html is ignored.

Transformation of the HTML tag i

The tag i becomes emphasis in DocBook.

Transformation of the HTML tag iframe

The tag iframe is ignored.

Transformation of the HTML tags img

The tag img becomes InlineMediaObject, if the DocBook parent element is one of Emphasis, Entry, Screen, Term or ULink. Otherwise it becomes MediaObject.

Transformation of the HTML tag input

The tag input is ignored.

Transformation of the HTML tag ins

The tag ins is ignored.

Transformation of the HTML tag isindex

The tag isindex is ignored.

Transformation of the HTML tag kbd

The tag kbd is ignored.

Transformation of the HTML tag label

The tag label is ignored.

Transformation of the HTML tag legend

The tag legend is ignored.

Transformation of the HTML tag li

The tag li becomes listem - para in DocBook.

Example 3.16. Example of mapping li to listitem

The HTML code

<li>description</li>

will be converted to DocBook XML

<listitem><para>description</para></listitem>

Transformation of the HTML tag link

The tag link is ignored.

Transformation of the HTML tag map

The tag map is ignored.

Transformation of the HTML tag menu

The tag menu becomes itemizedlist in DocBook.

Transformation of the HTML tag meta

The tag meta is ignored.

Transformation of the HTML tag noframes

The tag noframes is ignored.

Transformation of the HTML tag noscript

The tag noscript is ignored.

Transformation of the HTML tag object

The tag object is ignored.

Transformation of the HTML tag ol

The tag ol becomes orderedlist in DocBook.

If the list is a nested list, the surrounding listitem tag is created automatically.

Transformation of the HTML tag optgroup

The tag optgroup is ignored.

Transformation of the HTML tag option

The tag option is ignored.

Transformation of the HTML tag p

The tag p becomes para in DocBook.

Transformation of the HTML tag param

The tag param is ignored.

Transformation of the HTML tag pre

The tag pre becomes literal if the DocBook parent is entry, programlisting if the DocBook parent is Example or InformalExample. In all other cases pre becomes screen.

Transformation of the HTML tag q

The tag q is ignored.

Transformation of the HTML tag s

The tag s is ignored.

Transformation of the HTML tag samp

The tag samp is ignored.

Transformation of the HTML tag script

The tag script is ignored.

Transformation of the HTML tag select

The tag select is ignored.

Transformation of the HTML tag small

The tag small is ignored.

Transformation of the HTML tag span

The tag span can be used to insert index entries in the html code. Use the follwoing syntax to create an indexterm entry:

<span title="indexterm:primary=Animals:secondary=Tiger">Tiger</span>

The preceding code will result in the following DocBook XML:

<indexterm>
  <primary>Animals</primary>
  <secondary>Tiger</secondary>
</indexterm>           

Transformation of the HTML tag strike

The tag strike is ignored.

Transformation of the HTML tag strong

The tag strong becomes emphasis with the attribute role set to bold.

Example 3.17. Example of mapping strong to emphasis

The HTML code

<strong>Hippopotamomus</strong>

will be converted to DocBook XML

<emphasis role="bold">Hippopotamomus</emphasis>

Transformation of the HTML tag style

The tag style is ignored.

Transformation of the HTML tag sub

The tag sub becomes subscript in DocBook.

Transformation of the HTML tag sup

The tag sup becomes superscript in DocBook.

Transformation of the HTML tag table

The tag table becomes entrytbl, table or informaltable in DocBook.

1. If the current DocBook parent is row or entry the a nested entrytbl is created.

2. If the HTML tag table has a child element caption a DocBook table created. Otherwise an informaltable is created.

Transformation of the HTML tag tbody

The tag tbody becomes tbody in DocBook.

Transformation of the HTML tag td

The tag td becomes entry - para in DocBook.

Example 3.18. Example of mapping td to entry

The HTML code

<td>description</td>

will be converted to DocBook XML

<entry><para>description</para></entry>

Transformation of the HTML tag textarea

The tag textarea is ignored.

Transformation of the HTML tag tfoot

The tag tfoot becomes tfoot in DocBook.

Transformation of the HTML tag th

The tag th becomes entry - para - emphasis in DocBook.

Example 3.19. Example of mapping th to entry

The HTML code

<th>table column header</th>

will be converted to DocBook XML

<entry><para><emphasis role="bold">table column header</emphasis></para> </entry>

Transformation of the HTML tag thead

The tag thead becomes thead in DocBook.

Transformation of the HTML tag title

The tag title is ignored.

Transformation of the HTML tag tr

The tag tr becomes row in DocBook.

Transformation of the HTML tag tt

The tag tt becomes literal in DocBook.

Transformation of the HTML tag u

The tag u becomes emphasis with the attribute role set to underline.

Example 3.20. Example of mapping u to emphasis

The HTML code

<u>Hippopotamomus</u>

will be converted to DocBook XML

<emphasis role="underline">Hippopotamomus</emphasis>

Transformation of the HTML tag ul

The tag ul becomes itemizedlist in DocBook.

If the list is a nested list, the surrounding listitem tag is created automatically.

Transformation of the HTML tag var

The tag var becomes programlisting if the tag is inside a blockquote, otherwise it becomes a literal tag.