FlexDoc/XML - XSDDoc - FAQ

- Running XSDDoc
- Generator Settings
- Working with annotations
- Formatting annotations with XHTML
- Troubleshooting
- Where to learn more about XML schemas?
Formatting annotations with XHTML
Using XHTML you can enrich your XML schema annotations with all sorts of things:- text formatting: font, size, bold, italic, color, etc.
- borders & backgrounds
- paragraphs, headings
- tables
- lists
- hyperlinks
- images
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:- All HTML tags and their attributes become XHTML elements and attributes.
-
All XHTML elements belong to «XHTML» namespace associated with the URI:
-
http://www.w3.org/1999/xhtml
-
-
Unlike in HTML, each XHTML container element must always have both opening and closing tags:
-
<tag> ... </tag>
-
-
Each XHTML element with empty content must be specified like this:
-
<tag/>
'<tag>'
, which would be valid in HTML.) -
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- Take care of rules 3-4 above
- Tell the XML parser that those 'HTML' elements belong to
{http://www.w3.org/1999/xhtml}
namespace
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”:
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 SalutationsOnly three forms allowed:
|
There are three ways how you can do that:
-
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> -
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> -
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.
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:
|
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/
![]() |
![]() |
![]() |
![]() |
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):
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!

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):
- Processing | Annotations | Tags | XHTML
- Processing | Annotations | Tags | XHTML | Include Images
- Processing | Annotations | Tags | XHTML | Include Images | Copy Images
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
-
Processing | Annotations | Tags | XHTML – should be
true
to have XHTML tags in annotations processed -
Processing | Annotations | Tags | XHTML | Include Images – should be
true
to have images specified with<img>
elements processed (to appear in the documentation) -
Processing | Annotations | Tags | XHTML | Include Images | Copy Images –
should be
true
to have the images specified in annotations copied to the documentation destination directory
- Details | Schema Overview | XML Source | Remove Annotation
- Details | Component Documentation | XML Source | Remove Annotation
- Details | Component Documentation | Attribute Detail | XML Source | Remove Annotation
- Details | Component Documentation | Content Element Detail | XML Source | Remove Annotation
-
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).
-
Text | Render embedded HTML –
should be
true
to have the embedded HTML markup rendered (interpreted) -
Text | Render line breaks –
should be
true
, if you want your original line breaks to be interpreted along with your XHTML markup
-
Text | Render embedded HTML –
should be
true
to have the embedded HTML markup rendered (interpreted) -
Text | Render line breaks –
should be
true
, if you want your original line breaks to be interpreted along with your XHTML markup -
Images | Store graphics in RTF –
should be
true
to have all images stored directly in the generated RTF file.
How is XHTML processed?
The initial processing of XHTML elements happens in annotation.tpl template (as well as independently in firstSentence.tpl):-
All XHTML tags are converted to normal HTML tags:
- Any namespace prefixes are removed
-
Elements with empty content, which in XHTML must be
<tag/>
are converted to the HTML form:<tag>
-
The
<img/>
elements are processed specially. When “Copy Images” parameter istrue
, the image referenced insrc
attribute is copied to the documentation destination directory and the attribute value is changed accordingly.
<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:
-
In case of HTML, when the option
“Text | Render embedded HTML” is
true
, the annotation text with the HTML markup will be written directly to the output file. It will be already the job of an HTML browser to render it. -
In case of RTF, when
“Text | Render embedded HTML” option is
true
, all HTML tags embedded the annotation text are parsed and interpret with the corresponding formatting features available in RTF, which are also merged with the formatting imposed by the settings in the templates. Only limited set of HTML tags is supported in that way (see What XHTML tags can I use?).