Using XHTML/HTML Comments

The XHTML/HTML comment model is based on the XHTML and HTML markup standards defined by W3C. While originally developed for create web pages, TechWriter extends the use of XHTML/HTML for commenting XML schemas.

If you are using or plan to use XHTML or HTML for your XML schema comments, you must set the comment format to XHTML/HTML on the XML Schema Settings dialog.

The XHTML comment model includes support for the following tags that can be used for formatting.

HTML Tag Description

<B> or <STRONG> or <CODE> Changes the font to bold.

<I> or <EM> Changes the font to italic.

<SUP> Changes the text to a superscript

<SUB> Changes the text to a subscript

<OL> and <LI>
Formats a numbered list. The type attribute can also be specified to control the numbering scheme for the list as follows:

A - Uppercase alphabetic (ie. A, B, C)
a - Lowercase alphabetic (ie. a, b, c)
I - Uppercase Roman numerals (ie. I, II, III)
i - Lowercase Roman numerals (ie. i, ii, iii)
1 - Arabic numerals (ie. 1, 2, 3)

<UL> and <LI> Formats a bulleted list.

<A HREF='...'> Represents a link. See Creating Topic Links for more information.

<DL class='enums'>, <DT> and <DD> Represents a list of values and descriptions for enumerated types.

<DIV class='example'> Represents an example instance of an element.

<DIV class='othertitle'> Formats the text as a document title

<H1>,<H2>,<H3> and <H4> Formats the text as a heading

<BLOCKQUOTE> Indents the text

<P> Starts a new paragraph and separates the description from the remarks section of the comments.

<PRE> Starts a block of pre-formatted text used for code listings.

<BR> Inserts a line break

<IMG SRC='...'>
References an image. The style attribute can also be specified that includes one or more of the following CSS attributes:

height
width
text-align

See Referencing Images for more information.

<TABLE>, <COL>, <THEAD>, <TBODY>, <TR>, <TH> and <TD> Used to create a table. See "Using Table Tags" below for an example.

HTML Tag	Description
<B> or <STRONG> or <CODE>	Changes the font to bold.
<I> or <EM>	Changes the font to italic.
<SUP>	Changes the text to a superscript
<SUB>	Changes the text to a subscript
<OL> and <LI>	Formats a numbered list. The type attribute can also be specified to control the numbering scheme for the list as follows: A - Uppercase alphabetic (ie. A, B, C) a - Lowercase alphabetic (ie. a, b, c) I - Uppercase Roman numerals (ie. I, II, III) i - Lowercase Roman numerals (ie. i, ii, iii) 1 - Arabic numerals (ie. 1, 2, 3)
<UL> and <LI>	Formats a bulleted list.
<A HREF='...'>	Represents a link. See Creating Topic Links for more information.
<DL class='enums'>, <DT> and <DD>	Represents a list of values and descriptions for enumerated types.
<DIV class='example'>	Represents an example instance of an element.
<DIV class='othertitle'>	Formats the text as a document title
<H1>,<H2>,<H3> and <H4>	Formats the text as a heading
<BLOCKQUOTE>	Indents the text
<P>	Starts a new paragraph and separates the description from the remarks section of the comments.
<PRE>	Starts a block of pre-formatted text used for code listings.
<BR>	Inserts a line break
<IMG SRC='...'>	References an image. The style attribute can also be specified that includes one or more of the following CSS attributes: height width text-align See Referencing Images for more information.
<TABLE>, <COL>, <THEAD>, <TBODY>, <TR>, <TH> and <TD>	Used to create a table. See "Using Table Tags" below for an example.

Horizontal Alignment

The style attribute that contains a definition for the CSS text-align property can be used to specify specify horizontal alignment for the following tags:

<P>
<TH>
<TD>
<H1>
<H2>
<H3>
<H4>
<DIV>
<IMG>

Example

Below is an example of a comment that uses XHTML:

<p>
Job status.
</p>
<p>
Represents the status of the <a href="Complex+Types.MySchema#JobType">job</a>.
</p>
<dl class="enums">
<dt>NotStarted</dt><dd>The job has not yet been started.</dd>
<dt>InProgress</dt><dd>The job has started but is not yet complete.</dd>
<dt>Complete</dt><dd>The job has been completed.</dd>
</dl>

In the above example, the <p> tag separates the text that represents the description from the text that represents the remarks.

Using Table Tags

Below is an example of a table created using XHTML tags:

<table>
<col width="25%"/>
<col width="75%"/>
<thead>
    <tr><th>Role</th><th>Description</th></tr>
<thead>
<tbody>
     <tr><td>User</td><td>Typical end-user</td></tr>
     <tr><td>Admin</td><td>System administrator</td></tr>
     <tr><td>Manager</td><td>Project manager</td></tr>
</tbody>
</table>

Encoded XHTML/HTML

If you have already embedded XHTML/HTML tags within your comments, but have done so by encoding the tags, you will want to select the XHTML/HTML (encoded) model. For example, if you have encoded your paragraph tag as <P> instead of <P>, this alternative to the standard XHTML/HTML model will decode your encoded tags replacing the character entities such as the less than sign so that the tags can be properly parsed.