FlexDoc/XML - XSDDoc - FAQ
- Running XSDDoc
- Generator Settings
- Working with annotations
- Using HTML markup in annotations
- Troubleshooting
- Where to learn more about XML schemas?
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:
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:- 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?
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 the
{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>
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/
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>
- XSDDoc Template Parameters:
- Descriptions | HTML Markup =
true
- Descriptions | HTML Markup | XHTML Tags =
true
- Descriptions | HTML Markup | Other Tags =
"xhtml"
- Descriptions | HTML Markup =
- Output Format Options (HTML/RTF):
- Text | Render embedded HTML =
true
- Text | Render embedded HTML =
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.
<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>
- XSDDoc Template Parameters:
- Descriptions | HTML Markup =
true
- Descriptions | HTML Markup | Encode markup characters =
false
- Descriptions | HTML Markup =
- Output Format Options (HTML/RTF):
- Text | Render embedded HTML =
true
- Text | Render embedded HTML =
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.
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:
Specifically, this particular URI, which is used by the templates to identify the XHTML elements,
is specified in
When this parameter is xsddoc.xmltype configuration file, where you can change it when you need.
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 |
||||||||
Include Images |
desc.ehtml.tags.xhtml.images : boolean
Controls whether to include images specified with XHTML
If this parameter is
When the parameter is |
||||||||
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
When the parameter is |
||||||||
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"
|
||||||||
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:
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:
|
||||||||
Flatten |
desc.ehtml.flatten : enum {"never", "tbl"}
Specify whether to flatten the HTML markup.
Flattening means removing from the HTML markup
Possible Choices:
"never"
|
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):
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!
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:
- Descriptions | HTML Markup =
true
- Descriptions | HTML Markup | XHTML Tags =
true
- Descriptions | HTML Markup | XHTML Tags | Include Images =
true
- Descriptions | HTML Markup | XHTML Tags | Include Images | Copy Images =
true
- Text | Render embedded HTML =
true
- Text | Render embedded HTML =
true
- Images | Store graphics in RTF =
true
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
-
Descriptions | HTML Markup =
true
, to enable the processing of HTML markup in annotations -
Descriptions | HTML Markup | XHTML Tags =
true
, to recognize the XHTML or HTML-like elements -
Descriptions | HTML Markup | XHTML Tags | Include Images =
true
, to have the images specified with<img>
elements processed (to appear in the documentation) -
Descriptions | HTML Markup | XHTML Tags | Include Images | Copy Images =
true
, to have the images specified in annotations copied to the documentation destination directory
- Details | Schema | XML Source | Remove <xs:annotation>
- Details | Component | XML Source | Remove <xs:annotation>
- Details | Component | Attribute Detail | XML Source | Remove <xs:annotation>
- Details | Component | Content Element Detail | XML Source | Remove <xs: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 =
true
, to have the embedded HTML markup rendered (interpreted) -
Text | Render line breaks =
true
, if you want your original line breaks to be interpreted along with your XHTML markup
-
Text | Render embedded HTML =
true
, to have the embedded HTML markup rendered (interpreted) -
Text | Render line breaks =
true
, if you want your original line breaks to be interpreted along with your XHTML markup -
Images | Store graphics in RTF =
true
, to have all images stored directly in the generated RTF file.
How is HTML markup processed?
The initial processing of HTML markup happens in either text.tpl or textFS.tpl template:-
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 the parameter "Copy Images" 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 the option
"Text | Render embedded HTML" 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 HTML tags can I use?).