FlexDoc/XML - XSDDoc - Parameter Tree

About XSDDoc parameters

«Processing | Annotations» parameter group

This parameter group controls processing and formatting of annotations (the content of <xs:annotation> elements specified in XML schemas).

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.

Parameter Name / Type / Description
<appinfo> proc.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> proc.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

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

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

proc.annotation.documentation.source : enum {"as_see_link", "as_title", "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.
"no processing"
The value of source attribute will not be documented.
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

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 “Processing | Annotations | Tags | Other Tags” parameter.

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 | Formatting annotations with XHTML

For Schemas

Specify for which schemas the XHTML markup in annotations should be processed.

Include

proc.annotation.tags.xhtml.schemas.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

proc.annotation.tags.xhtml.schemas.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.

Include Images

proc.annotation.tags.xhtml.images : boolean

Controls whether to include images specified with the 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

proc.annotation.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

proc.annotation.tags.other : enum {"show", "xhtml", "no"}

Controls 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.
"process as XHTML"
The unprocessed tags will be treated as XHTML tags.

Note: The “Processing | Annotations | Tags | XHTML” parameter should be also selected for this.

"no processing"
Any unprocessed tags will be ignored.
Encode markup characters proc.annotation.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; 
Note: 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.

Show part headings proc.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 ...
...