FlexDoc/XML - XSDDoc - Parameter Tree

About XSDDoc parameters

«Descriptions» parameter group

This parameter group controls the processing and formatting of descriptions found in XSD files.

In case of XML schemas, the descriptions come from the content of <xs:annotation> elements. They appear in particular "Description" sections of the generated documentation.

See Also:

FlexDoc/XML | XSDDoc | FAQ | Working with annotations
Related Templates:
annotation.tpl, annotationText.tpl, text.tpl,
Parameter Name / Type / Description
XSD Annotations desc.xsd.annotation

This parameter group controls some specifics about processing of XML schema annotations (i.e. the content of <xs:annotation> elements).

The annotation text, which appears in a particular "Annotation" section of the generate documentation, is produced from all <xs:documentation> elements found by the path:

xs:annotated/xs:annotation/xs:documentation
where 'xs:annotated' is an XSD element that defines either the XML schema itself (xs:schema) or a schema component (e.g. xs:complexType) being documented.

Multiple <xs:documentation> elements will produce different sections of the annotation text.

<appinfo>

desc.xsd.annotation.appinfo : boolean

Specify whether to process <xs:appinfo> elements.

If true (selected), all <xs:appinfo> elements will be treated the same as <xs:documentation> elements.

Nested Parameters:

Control processing of specific attributes of <xs:appinfo> elements.

<documentation>

desc.xsd.annotation.documentation : boolean

Specify whether to process <xs:documentation> elements.

The <xs:documentation> elements are primary holders of any information about the XML schema (components and etc.) intended for human readers.

Nested Parameters:

Control processing of specific attributes of <xs:documentation> elements.

Language

desc.xsd.annotation.documentation.lang : list of strings {separators: ';', newline}

When you annotate your XML schema simultaneously in different languages, this parameter will allow you to generate the documentation localized for only one of them (that is, only the annotations written in the selected language will be included in the documentation).

Parameter Value:

The 2- or 3-letter code identifying the language. This must be the same code which you have specified in the 'xml:lang' attribute of the <xs:documentation> elements you want to process.

You may also specify multiple language codes separated with semicolons (';'). For example:

de;deu
In that case, only those <xs:documentation> elements will be processed, which contain the 'xml:lang' attribute assigned with one of the specified language codes.

When this parameter is not specified (empty string), all sibling <xs:documentation> elements are processed, which will produce a single (however, multi-sectional) annotation text.

Example: 

<xs:annotation>

   <xs:documentation xml:lang="en">
      This description is in English...
   </xs:documentation>

   <xs:documentation xml:lang="de">
      Die deutsche Beschreibung...
   </xs:documentation>

</xs:annotation>
When you specify "de" in this parameter, you will get in the documentation only this text: "Die deutsche Beschreibung..."

Nested Parameter:

Specifies an alternative language

Alternative Language

desc.xsd.annotation.documentation.lang.alt : list of strings {separators: ';', newline}

When the “Language” parameter is specified, only the <xs:documentation> elements marked with the specified language code(s) will be process. All others will be ignored.

However, you may have a situation that not all annotations in your XML schema are translated into a specific language. When you generate the documentation targeted to that language, it is preferable to have all descriptions written in it. However, when such a localized description is missing, a description written in some basic language (e.g. English) would also suffice.

Using this parameter you may specify such an alternative language.

The value of this parameter must be specified the same way as of “Language” parameter.

For example, let's suppose that in the “Language” parameter you have specified "de" and the value of this (“Alternative Language”) parameter is "en". Then, when German annotations are found only them will get into the generated documentation. However, when a German annotation is missing and the English one exists, it will be used instead.

Source URI

desc.xsd.annotation.documentation.source : enum {"see_link", "title", "xml_source", "no"}

Specifies how to process the value of source attribute of <xs:documentation> elements.

Possible Choices:

"document as see-link"
The value will be documented in a section below annotation text looking as the following:
See:  <source url link>
"document as annotation title"
The value will be documented as a title printed before annotation text obtained from this <xs:documentation> element.
"include XML source"
The value is interpreted as an URL of some XML file, which will be included (reproduced) in the documentation below the annotation text.

Relative URLs are interpreted against the location of the XML schema file.

"no processing"
The value of source attribute will not be documented.

Show part headings

desc.xsd.annotation.show.part.headings : boolean

Specify, whether to generate multipart annotation headings.

A human-written description of an XML schema or schema component is generated from the content of an <xs:documentation> element found within the <xs:annotation> element that is direct child of an XSD element defining the schema or component. For example: 

<xs:element name="SomeElement">
  <xs:annotation>
    <xs:documentation>
      element description
    <xs:documentation>
  </xs:annotation>
  ...
</xs:element>
However, <xs:annotation> elements are allowed to have multiple <xs:documentation> children (and <xs:schema> element may have even multiple <xs:annotation> children). In that case, the result description text will be produced from the content of all <xs:documentation> element found by the path:
component/annotation/documentation
When the component description is generated from the content of multiple <xs:documentation> elements, each of them will produce a separate part of the entire description text. In that case, each part will have a separate heading, so the whole text will look like the following:
Annotation 1:

Text 1...

Annotation 2:

Text 2 ...
...

This parameter allows you to suppress the generation of part headings, so the result text will be:
Text 1...
Text 2 ...
...
HTML Markup desc.ehtml

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).

See Also:

FlexDoc/XML | XSDDoc | FAQ | Using HTML markup in annotations

For Files

desc.ehtml.files

Specify for which XML schema files the HTML markup in annotations should be processed.

Include

desc.ehtml.files.include : list of strings {separators: ';', newline}

Specify the list of XML schemas whose annotations may contain XHTML markup.

Each XML schema is specified with its file name (the last name in the pathname's name sequence, e.g. "xml.xsd"). Multiple file names should be separated with the allowed item separator (e.g. newline).

When this parameter is assigned (with a non-empty string specifying the schema list), the XHTML tags will be processed in annotations of only those schemas whose file names are found in that list.

Exclude

desc.ehtml.files.exclude : list of strings {separators: ';', newline}

Specify the list of XML schemas whose annotations contain no XHTML markup (or it should ignored).

Each XML schema is specified with its file name (the last name in the pathname's name sequence, e.g. "xml.xsd"). Multiple file names should be separated with an allowed item separator (e.g. newline).

When this parameter is assigned (with a non-empty string specifying the schema list), the XHTML tags will be processed in annotations of only those schemas whose file names are not found in that list.

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 the 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:

Descriptions | HTML Markup | Other Tags
Important:
To have XHTML embedded in your annotations work, when generating documentation (both HTML and RTF), check also that “Text | Render embedded HTML” option of the destination output format is selected! This can be specified in the generator dialog.
See Also:
FlexDoc/XML | XSDDoc | FAQ | Using HTML markup in annotations

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.

Nested Parameter:

Specifies whether the images must be copied to the documentation destination directory.

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.