FlexDoc/XML - XSDDoc - FAQ

Using HTML markup in annotations

The descriptions specified in <xs:documentation> elements may be preformatted with HTML tags, which can be used in the generated documentation (both HTML and RTF output).

There are three ways how you can use HTML in your XSD annotations:

  1. XHTML elements
  2. HTML-like elements
  3. Escaping HTML markup

XHTML elements

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?

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>

XHTML use demo

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}/XSDDoc/demo/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)

HTML-like elements

Another possibility is that you define your HTML markup in the form of XML elements, however without XHTML namespace (i.e. in no-namespace). So, you have something looking like XHTML but not exactly it.

Example:

<xs:documentation>
  <h3>Complete List of all Salutations</h3>
  Only three forms allowed:
  <ol>
    <li>MR.</li>
    <li>MS.</li>
    <li>MRS</li>
  </ol>
</xs:documentation>
Processing of that is enabled by the following settings:

Escaping HTML markup

At last, you can use no XML elements at all to express your HTML markup. Instead you specify the HTML tags directly within the text by escaping XML special characters using XML entities.
That's the worst case and we highly discourage you from using such formatting. However, some XML schemas authors do use it. So, XSDDoc supports that as well.
Example:
<xs:documentation>
  &lt;h3&gt;Complete List of all Salutations&lt;/h3&gt;
  Only three forms allowed:
  &lt;ol&gt;
    &lt;li&gt;MR.&lt;/li&gt;
    &lt;li&gt;MS.&lt;/li&gt;
    &lt;li&gt;MRS&lt;/li&gt;
  &lt;/ol&gt;
</xs:documentation>
Such things can be processed/rendered as well. That can be achieved by the following settings:

How to make my HTML markup formatting work?

When you have just downloaded FlexDoc/XML and installed it, all default settings will be such that any XHTML markup in your annotations (as described in How to use XHTML?) 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 «Description» 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 HTML 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 HTML markup in annotations (the default parameter values are underlined):

Parameter Name / Type / Description
HTML Markup This parameter/group controls the processing (rendering) of the HTML markup embedded in the various decription text (e.g. within the content of <xs:documentation> elements).
For Files Specify for which XML schema files the HTML markup in annotations should be processed.
XHTML Tags desc.ehtml.tags.xhtml : boolean

Specify whether to process XHTML tags embedded in the annotation text.

XHTML tags are considered any XML elements that belong to XHTML namespace, which is associated with the following URI:

http://www.w3.org/1999/xhtml
Specifically, this particular URI, which is used by the templates to identify the XHTML elements, is specified in xsddoc.xmltype configuration file, where you can change it when you need.
When this parameter is true (checked), any XHTML elements will be converted to normal HTML tags (that is, the namespace prefix will be removed from each tag's name and everything else rewritten as it was). That will make the annotation text look as a fragment of normal HTML, which will be further inserted directly into the documentation output (in case of HTML) or rendered (in case of RTF).

When this parameter is false (unchecked), the XHTML elements will not be specifically processed in any way. The element tags will be simply removed or printed as normal text, which is controlled by the parameter: Other Tags

Include Images desc.ehtml.tags.xhtml.images : boolean

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

If 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 desc.ehtml.tags.xhtml.images.copy : boolean

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

If 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 desc.ehtml.tags.other : enum {"show", "xhtml", "no"}

Control what to do with any other XML tags that have not been specifically processed as XHTML markup.

Possible Choices:

"show"

All unprocessed XML tags will appear in the generated documentation as text.

For example, if in the input data there is:

<tag> blah-blah </tag>
the same you will see in the result documentation.
"process as XHTML"
The unprocessed tags will be treated as XHTML tags.
For that to happen, this parameter must be also selected: Descriptions | HTML Markup | XHTML Tags
For example, if in the input data there is:
<i>blah-blah</i>
and the element <i> is in no-namespace, then in the result documentation you will still see (italic text):
blah-blah
"no processing"
Any unprocessed tags will be ignored.

For example, if in the input data there is:

<tag> blah-blah </tag>
in the result documentation you will see only:
blah-blah
Encode markup characters desc.ehtml.encode.markup.chars : boolean

Specifies whether to encode HTML markup characters contained in the annotation text.

The following table shows all such characters and the entities into which they are encoded:

Character Entity
< &lt;
> &gt;
& &amp; 

The encoding will be done only when the output format supports rendering of embedded HTML, and it is switched on (see output format options).

The purpose of this parameter is the following:
  1. Suppose you use XHTML elements to format your annotations and some annotation contains a text like this:
    A < B
    You need to show the '<' character as it is. Since the whole annotation will be converted into HTML, that character needs to be encoded. In that case, this parameter should be selected.
  2. However, some XML schema authors do not rely on XHTML to format annotation (probably because few tools process it). Instead, they insert HTML markup directly into the annotation text, like the following:
    <xs:annotation>
      <xs:documentation>
        This is &lt;b&gt;keyword&lt;/b&gt;
      </xs:documentation>
    </xs:annotation>
    An XML parser will convert such an annotation text into the string:
    This is <b>keyword</b>
    which could be immediately passed to an HTML viewer or added to HTML output. In that case, the HTML markup characters should not be encoded!

    Therefore, if you have an XML schema like this, you should unselect this parameter.

Flatten desc.ehtml.flatten : enum {"never", "tbl"}

Specify whether to flatten the HTML markup.

Flattening means removing from the HTML markup
  • All block-level HTML tags (e.g. <p>)
  • All other HTML tags that cause a line break (e.g. <br>)
So, the result text will form a single text line or paragraph when interpreted as HTML.
Possible Choices:

"never"

Do not flatten HTML markup.
"in tables"
Flatten HTML markups for descriptions that appear in table cells (typically in some summaries).

When the summary displays only the first sentence of the full description, it will always be flattened.

Related HTML/RTF Options

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

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

What HTML 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 HTML markup 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 <span>, <b>, <strong>, <i>, <em>, <cite>, <code>, <tt>, <u>, <s>, <strike>, <sub>, <sup>, <font>, <br>
Paragraphs <div>, <p>, <center>, <pre>, <blockquote>, <h1>, <h2>, <h3>, <h4>, <h5>, <h6>
Lists <ul>, <ol>, <li>, <dl>, <dt>, <dd>
Table <table>, <caption>, <tbody>, <thead>, <tfoot>, <tr>, <th>, <td>
Other <hr>, <img>, <a>...</a>

How to insert images using HTML markup?

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 «Description» 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:

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

What settings control the processing of HTML markup 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 HTML markup and images

Template parameters to suppress <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 HTML markup processed?

The initial processing of HTML markup happens in either text.tpl or textFS.tpl template: All of that is controlled by the parameters in "Descriptions | HTML Markup" 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: