FlexDoc/XML - XSDDoc - FAQ

Formatting annotations with XHTML

Using XHTML you can enrich your XML schema annotations with all sorts of things: All of that will be rendered and appear in both HTML and RTF documentation output.

What is XHTML?

XHTML is basically the old HTML that is well-formed enough to be a valid XML at the same time. In particular, that means:
  1. All HTML tags and their attributes become XHTML elements and attributes.
  2. All XHTML elements belong to «XHTML» namespace associated with the URI:
    http://www.w3.org/1999/xhtml
  3. Unlike in HTML, each XHTML container element must always have both opening and closing tags:
    <tag> ... </tag>
  4. Each XHTML element with empty content must be specified like this:
    <tag/>
    (Rather than simply '<tag>', which would be valid in HTML.)
In anything else, XHTML may be used the same as the normal HTML.

For more information about XHTML, you can see these links:

How to use XHTML in annotations?

Practically, you can use HTML tag in your XML schema annotations the same as is normal HTML text, however you need to

Here is how you can do it.

Suppose, you have a little XML schema like the one shown below, with the plain-text annotation “Complete List of all Salutations”:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:simpleType name="SalutationType">
<xs:annotation>
<xs:documentation>
Complete List of all Salutations
</xs:documentation>
</xs:annotation>
<xs:restriction base="xs:string">
<xs:enumeration value="MR."/>
<xs:enumeration value="MS."/>
<xs:enumeration value="MRS"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>

Now, you want, instead of that pain-text annotation, to use an HTML-formatted one (as shown below on the left), so that, when it's properly rendered, to get a result description looking like on the right:

<h3>Complete List of all Salutations</h3>
Only three forms allowed:
<ol>
<li>MR.</li>
<li>MS.</li>
<li>MRS</li>
</ol>

Complete List of all Salutations

Only three forms allowed:
  1. MR.
  2. MS.
  3. MRS

There are three ways how you can do that:

  1. Switching default namespace within <xs:documentation> element

    Below is the modified XML schema. The new XHTML-annotation is highlighted with the red background. The switch of the default namespace to XHTML within the <xs:documentation> element is highlighted with yellow:

    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:simpleType name="SalutationType">
    <xs:annotation>
    <xs:documentation xmlns="http://www.w3.org/1999/xhtml">
    <h3>Complete List of all Salutations</h3>
    Only three forms allowed:
    <ol>
    <li>MR.</li>
    <li>MS.</li>
    <li>MRS</li>
    </ol>
    </xs:documentation>
    </xs:annotation>
    <xs:restriction base="xs:string">
    <xs:enumeration value="MR."/>
    <xs:enumeration value="MS."/>
    <xs:enumeration value="MRS"/>
    </xs:restriction>
    </xs:simpleType>
    </xs:schema>
  2. Switching default namespace within <div> container

    If you do not want to touch <xs:documentation>, you can switch to XHTML namespace within a <div> container (it's a proper HTML/XHTML element as well) enclosing your XHTML-formatted text.

    Below is the modified XML schema. The new XHTML-annotation is highlighted with the red background. The <div> container is highlighted with yellow:

    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:simpleType name="SalutationType">
    <xs:annotation>
    <xs:documentation>
    <div xmlns="http://www.w3.org/1999/xhtml">
    <h3>Complete List of all Salutations</h3>
    Only three forms allowed:
    <ol>
    <li>MR.</li>
    <li>MS.</li>
    <li>MRS</li>
    </ol>
    </div>
    </xs:documentation>
    </xs:annotation>
    <xs:restriction base="xs:string">
    <xs:enumeration value="MR."/>
    <xs:enumeration value="MS."/>
    <xs:enumeration value="MRS"/>
    </xs:restriction>
    </xs:simpleType>
    </xs:schema>
  3. Using «xhtml» namespace prefix

    At last, you do not have to bother with switching the default namespace at all. Instead, you can indicate that each particular HTML-looking element belongs to XHTML namespace using a special namespace prefix (e.g. 'xhtml') bound to XHTML namespace URI in your <xs:schema> element.

    Below is the sample XML schema modified accordingly. The new XHTML-annotation is highlighted with the red background. The bounding of 'xhtml' prefix to XHTML namespace and using it is highlighted with yellow:

    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xhtml="http://www.w3.org/1999/xhtml">
    <xs:simpleType name="SalutationType">
    <xs:annotation>
    <xs:documentation>
    <xhtml:h3>Complete List of all Salutations</xhtml:h3>
    Only three forms allowed:
    <xhtml:ol>
    <xhtml:li>MR.</xhtml:li>
    <xhtml:li>MS.</xhtml:li>
    <xhtml:li>MRS</xhtml:li>
    </xhtml:ol>
    </xs:documentation>
    </xs:annotation>
    <xs:restriction base="xs:string">
    <xs:enumeration value="MR."/>
    <xs:enumeration value="MS."/>
    <xs:enumeration value="MRS"/>
    </xs:restriction>
    </xs:simpleType>
    </xs:schema>

How to make my XHTML formatting work?

When directly out of the box (i.e. you have just downloaded FlexDoc/XML and installed it), all default settings will be such that any XHTML markup in your annotations (as described above) will be processed and immediately visible in the generated documentation (in both HTML and RTF formats).

For instance, you may copy any of three sample schemas above into a plain-text XSD file (e.g. 'schema.xsd') and try to run XSDDoc for it. Then, you will see the properly formatted annotation in the «Annotation» section of SalutationType documentation.

However, there are a few settings (template parameters and output format options) that allow you to turn processing/rendering of XHTML off, so as to see your XHTML tags directly in the output (e.g. for debugging) or completely remove them.

Related Template Parameters

Below is the fragment of the Parameter Inspector with the template parameters related to processing of XHTML markup in annotations (expanded and highlighted with red). Click on the screenshot to see the corresponding parameter description:

The descriptions of the XSDDoc parameters that control processing of XHTML markup in annotations (the default parameter values are underlined):

Parameter Name / Type / Description
Tags The parameter group to control processing of any non-XSD element tags embedded in annotation text (i.e. within the content of <xs:documentation> elements).
XHTML proc.annotation.tags.xhtml : boolean

Controls whether XHTML tags in annotations are processed. This parameter should be true (checked), if you want to get your XHTML formatting visible (rendered) in the generated documentation.

When the parameter is false (unchecked), the XHTML tags won't be specifically processed and treated as any other tags according to the setting of “Other Tags” parameter.
For schemas This parameter group allows you to filter precisely for which XML schemas the XHTML markup in annotations should be processed.
Include Images proc.annotation.tags.xhtml.images : boolean

Controls whether to include images specified with XHTML <img/> elements.

When this parameter is true (checked), all <img/> elements will be processed and the images specified in them inserted in the generated documentation.

When the parameter is false (unchecked), the <img/> elements will be recognized still, however just passed over without particular processing.
Copy Images proc.annotation.tags.xhtml.images.copy : boolean

Specifies whether the images embedded in the annotation text must be copied to the documentation destination directory.

When this parameter is true (checked), all images referred from <img> tags will be automatically copied to the associated files directory (e.g. "doc-files") of the schema documentation. The src attribute of each <img> tag will be altered to point to the new image location.

When the parameter is false (unchecked), no images will be physically copied. Instead, the original image source URLs (specified in XHTML <img> elements) will be used as image references in the generated output as well.
Other Tags proc.annotation.tags.other : enum {"show", "xhtml", "no"}

Controls what to do with any other (unknown) XML tags that are not specifically processed as XHTML markup.

Possible Choices:
"show"
All unknown XML tags will appear in the generated documentation as is (as text).
"process as XHTML"
The unknown tags will be treated as XHTML tags.

In some XML schemas the HTML-looking tags/elements may be used to format annotations. However, nowhere is specified that those elements belong to {http://www.w3.org/1999/xhtml} namespace. We discourage such practice, however this parameter setting does allow you to process such situations anyway.

Notes:
  • Rendering of unknown tags as XHTML will happen only for those schemas, for which XHTML is specified to be processed (see “XHTML” and “For schemas” parameters).
  • When an unknown tag cannot be treated as XHTML markup, its effect will be unpredictable.
"no processing"
Any unknown tags will be ignored (that is completely removed from the output).

Related HTML/RTF Options

HTML options related to rendering of XHTML markup in annotations (highlighted with red; click on the screenshot to see an option description):

RTF options related to rendering of XHTML markup in annotations (highlighted with red; click on the screenshot to see an option description):

What XHTML tags can I use?

In case of HTML output

You can use any HTML tags and attributes as you want. The only condition is that anything you want to be treated as HTML tags in the result output, must be framed as XHTML elements in XML schema source.

XSDDoc doesn't parse the XHTML markup, rather just converts it to ordinary HTML (see How is XHTML processed?). Then, it is passed to the HTML generator that sends everything directly to the output file.

In case of RTF output

Unlike HTML browsers, RTF readers cannot process HTML markup. So, the RTF generator itself has to fully parse all HTML tags embedded in the input text and interpret them with the corresponding formatting features available in RTF (at that, everything must be also merged with the formatting imposed by the settings in the templates). So, only limited set of HTML tags is supported.

Here is the list of all HTML tags currently supported by the RTF generator:

Text <b>, <strong>, <i>, <em>, <code>, <tt>, <u>, <s>, <strike>, <sub>, <sup>, <font>, <br>
Paragraphs <p>, <center>, <div>, <pre>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>, <blockquote>
Lists <ul>, <ol>, <li>, <dl>, <dt>, <dd>
Table <table>, <tr>, <td>, <th>
Other <hr>, <img>, <a>...</a>

Demo of XHTML use

FlexDoc/XML archive includes a great demo of usage of XHTML in XML schema annotations. It is a sample XML schema that consists mostly of various XHTML markup (including the formatting of text, lots of images, tables, hyperlinks, etc.). You can find it in the directory:
{flexdoc-xml}/samples/HumanEvolution/
The following is the documentation generated by that XML schema. The leftmost screenshot shows the full XML source of that schema. The second is the screenshots of framed HTML documentation. The last two screenshots are pages of the RTF documentation. Click on each screenshot to view what it depicts or enlarge:

Here you can download all these demo docs together: HumanEvolution.zip (1.3 MB)

How to insert images using XHTML?

Using <img> tag (element), you can insert in XML schema annotations any your special images.

Below is a little XML schema with the XHTML-annotation containing an <img> element (highlighted with green):

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:annotation>
<xs:documentation xmlns="http://www.w3.org/1999/xhtml">
<b>Mystic Flowers:</b>
<p/>
<img src="http://www.flexdoc.xyz/images/flowers.png"/>
</xs:documentation>
</xs:annotation>
</xs:schema>

Note that the default namespace within the <xs:documentation> is switched to XHTML (highlighted with yellow) – that's the key thing to make it work (see above)!

The sample above it a complete XML schema. You can copy it into a plain-text XSD file (e.g. 'schema.xsd') and to run XSDDoc for it. Then, you can find the HTML fragment with the image (as shown below) in the «Annotation» section of «Schema Overview» page/block. That should equally work both in HTML and RTF!

After processing such an annotation, the generator will produce the following fragment:

Mystic Flowers:

Related template parameters & generator options

By default (when you've just downloaded FlexDoc/XML and installed it), all settings will be such that any XHTML markup and images in your annotations will be processed and immediately visible in the generated documentation (in both HTML and RTF formats). However, if you changed something, make sure the following settings are set correctly.

These template parameters should be selected (true):

In case of HTML output, this HTML option should be selected (true): In case of RTF output, these RTF options should be selected (true):

What settings control the processing of XHTML and images?

This is the summary of template parameters and generator options relevant to processing of XHTML and images.

Template parameters that enable processing of XHTML and images

Template parameters suppressing <xs:annotation> elements in reproduced XML source
When you use XHTML to format your annotations, you may want to suppress <xs:annotation> elements in the reproduced XML source because the XHTML markup elements may occupy too much space (so they will overwhelm anything else).
HTML Options RTF Options

How is XHTML processed?

The initial processing of XHTML elements happens in annotation.tpl template (as well as independently in firstSentence.tpl): All of that is controlled by the parameters in “Processing | Annotations | Tags | XHTML” group. As a result, the entire content of each <xs:documentation> element produces a piece of normal HTML, which is to the output generator.

What happens next is called rendering of embedded HTML and depends on the particular output format: