FlexDoc/XML - XSDDoc - Parameter Tree

This group of parameters allows you to select which XML schema files (and components defined in them) will be documented.

The XML schema files you initially specify on the command line (or in the generator dialog) are the primary XML files to be processed by the XSDDoc template set.

However, those initial XML schemas may call (reference) from themselves some other XML schema files (via <xs:import>, <xs:include> and <xs:redefine> elements) and they, in turn, yet more extra schemas.

All those initial and referenced XML schema files will constitute the whole your XML schema project. Generally, all of them must be loaded and processed in order to make sense of the declarations specified in your initial XML schemas. Some of the imported extra XML schemas may be the standard (and fairly big) ones used in other your projects.

So, do you need to document all the involved XML schemas? If not, which ones? That can be specified with the parameters in this group.

Specify whether to document the XML schema files initially specified on the generator command line (or in the generator dialog).

You may need to unselect this parameter, when you specify a precise list XML schema files to be documented (see “Include” parameter in this group).

Specify whether to document all additional XML schema files loaded by <xs:import> elements.

When an XML schema is both specified initially on the command line and referred from an <xs:import> element, it is loaded only once as the initial XML schema, however, it will be marked as the imported schema as well.

Included

Specify whether to document the additional XML schema files referenced from <xs:include> elements.

Specify whether to document the additional XML schema files referenced from <xs:redefine> elements.

With this parameter, you can add a precise list of XML schemas to be documented.

Each XML schema is specified in the list 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 (';' or newline).

This parameter works in addition to other schema selection parameters (above) and won't override them.

Using this parameter, you can filter out some schemas from those initially selected with the parameters above.

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

Note: This parameter overrides the “Include” parameter (above). That is, when a schema file is specified in both “Include” and “Exclude” parameters, it will be excluded from the documentation scope.

This parameter group allows you to control the sorting of

• Namespaces
• XML schemas
• XSD components

This parameter allows you to control how namespaces are sorted throughout the whole documentation.

It directly affects:

1. The sorting of namespace summary in the Overview Summary.
2. In the case of framed HTML documentation:
   • The ordering of namespaces in the Overview Frame.
     See also the parameter: Navigation | Overview Frame | Namespaces
   • The order in which namespaces get fully processed and documented.

     This determines which namespace gets documented first. That, in turn, may affect the initial content of the frames: List Frame, Detail Frame.

3. In the case of single-file documentation, the order in which the Namespace Overviews follow each other.

• When it is selected (true), the namespaces will be sorted alphabetically by their URIs (ignoring letter case).
• When the parameter is unselected (false), the namespaces won't be sorted anyhow. Then, the ordering of namespaces will be determined by what XSD files have been specified initially and how they reference (e.g. import) other XSD files.

This parameter allows you to control how XML schemas are sorted throughout the documentation.

It directly affects:

1. The order in which XML schemas are listed in the Overview Frame (see also the parameter: Navigation | Overview Frame).
2. In the case of framed HTML documentation, the order, in which XML schemas become fully processed and documented.
   This includes the generation of Schema Overview and Component Documentation pages for a schema.
   That determines which XML schema gets documented the first, which, in turn, may affect the initial content of the frames:
   • List Frame. (See the parameter: Navigation | List Frame)
   • Detail Frame. (See the parameter: Navigation | Detail Frame)
3. In the case of single file documentation, the order in which the Schema Overview blocks (generated for each XML schema) follow in the file.

• When it is selected (true), the XML schemas will be sorted alphabetically by their file names (ignoring letter case).
• When the parameter is unselected (false), the XML schemas will follow in a certain physical order, which is determined by how the initial XML schemas (to be documented) have been specified as well as how these schemas import other XML schemas.

With this parameter you can specify the sorting order of components for a number of locations throughout the documentation. This includes:

1. The sorting of components summaries.
2. In the case of framed HTML documentation, the sorting of XSD components in navigation list.
3. In the case of single file documentation, this parameter directly controls the ordering of component details (see Component Documentation).

• When it is selected (true), the XSD components will be sorted alphabetically by their names (ignoring letter case).
  The component name is assumed to be that under which the component appears (is referenced to) at the given documentation location. This is typically the component qualified name (which is the actual namespace prefix plus the component local name). That, however, can be changed using the parameter: Show | Namespace Prefixes Additionally, in the case of local elements, the component name may also include a special extension used to distinguish the equally named local elements. For more details about this, please see the parameter: Show | Element Name Extensions
• When the parameter is unselected (false), the XSD components are not sorted. In that case they will follow in a certain physical order produced as explained below.
  If components come from different XML schemas, first, they will be grouped by their schemas. The ordering of those groups is determined by what XSD files have been specified initially and how they reference (e.g. import) other XSD files.

  Within a group of components that belong to the same XML schema, they will follow in the same order as they are defined in that schema.

  This allows you to control a particular ordering of components (e.g. elements) by yourself. Simply define the most important components (e.g. an XML document's root element) on the top of the XML schema. If you have several schemas to document, specify the most important of them first. That will produce the component ordering as you wish (or something close to it).

Available only in SingleDoc.tpl

The title page is available only in single-file documentation. When generated, it will be the very first page of the entire documentation.

Related Template:

The title page is generated by the template: title-page.tpl

By default, it just prints (with a large font) the text specified in the parameter:

Literal Input | Documentation Title

That text may also include some HTML markup, which will be recognized and rendered.

You may easily edit the title-page.tpl template and add/change whatever you need (e.g. you can add you company logo or other images).

Available only in SingleDoc.tpl

Pagination | Start from new page | Table Of Contents

TOC.tpl

Specifies whether to generate the Overview Summary page/block.

overview.tpl

Specifies whether to generate the All Component Summary page/block.

all-components.tpl

Specify whether the summary of all components should be added to the Overview Summary page (instead of creating a separate page for it).

That may be more convenient for small XML schemas.

Specifies whether to generate the Namespace Overview pages/blocks.

Related Template:

namespace.tpl

Specifies whether to generate the Schema Overview pages/blocks.

Related Template:

schema.tpl

Specifies whether to generate details of XSD components (that is Component Documentation pages/blocks).

Nested Parameters:

Specify particular types of XSD component, for which the details page/block will be generated.

Specifies whether to generate the detailed Component Documentation for each global element component and some of the local element components (that are defined in all XML schemas being documented).

Nested Parameter:

Specify which of the local element components must be documented.

element.tpl, elements.tpl

Specify whether top-level elements should be grouped separately from all other elements (i.e. at the top of the whole element list/summary and under a separate heading).

This parameter affects:

• All navigation list frames
• All element summaries
• The ordering of element details in single-file documentation

Specify whether to sort the list (summary etc.) of top-level elements.

Typically, there is only one such an element. So, no sorting is needed. But in some cases, there may be several elements satisfying the top-level criteria. In that case, you may want to have them sorted.

When sorting is disabled, the elements will follow in the same order as they are defined in the schemas and those schemas are processed.

Default Value:

Provided by the parameter: Generate Details | Sorting | Components

Specifies whether to generate the separate (global) Component Documentation for local elements (i.e. locally defined element components).

Possible Choices:

"all"

Document all local elements the same way as global ones (see Global Documenting below).

Generate the detailed Component Documentation only for local elements with complex types.

Certain XML schema design patterns avoid using global element components almost entirely. Instead, they define a single global element component that describes the root element of a possible XML document. Any other elements, which may be contained in that XML document, are defined using only global types and local element components.

Moreover, frequently, those XML schemas also define no element attributes. Instead, to store in an XML document the elementary data normally supposed for attributes, they define lots of local elements with primitive simple types.

As a result, such an XML schema contains great a lot of insignificant local element components. When all of them are documented separately (and appear in main element component lists) they may overwhelm everything else.

If your XML schemas is designed according to that pattern, this parameter value allows you to avoid exactly such a mess!

Do not generate separate Component Documentation for local elements.

Details | Component – controls the exact content of the separate (global) Component Documentation.

Specify whether to unify local elements by type:

• If true, all local elements that share the same name (in the same namespace) and the same global type are documented as a single entity – unified local element.
• If false, every local element component will be documented separately.

Specify how the documentation of local elements (and their diagrams) must be stored.

Namely, for a local element 'localElement' defined in a parent component, its documentation file will be stored as follows:

.../schemas/schemaName_xsd/elements/

.../schemas/schemaName_xsd/elements/elementName_3.html

However, if you don't need that, the produced HTML documentation files will be more compact (as all links to local element docs will be shorter).

See Also Parameter:

Details | Component | Content Element Detail | Content Model | Diagram | Store By Parents

Specifies whether to generate the detailed Component Documentation for each global complex type component.

See Also Parameter (only for SingleDoc.tpl):

Pagination | Start from new page | Components | Complex Type

complexType.tpl, complexTypes.tpl

Specifies whether to generate the detailed Component Documentation for each global simple type component.

See Also Parameter (only for SingleDoc.tpl):

Pagination | Start from new page | Components | Simple Type

simpleType.tpl, simpleTypes.tpl

Specifies whether to generate the detailed Component Documentation for each global element group component.

See Also Parameter (only for SingleDoc.tpl):

Pagination | Start from new page | Components | Element Group

group.tpl, groups.tpl

Specifies whether to generate the detailed Component Documentation for each global attribute group component.

See Also Parameter (only for SingleDoc.tpl):

Pagination | Start from new page | Components | Attribute Group

attributeGroup.tpl, attributeGroups.tpl

Specifies whether to generate the detailed Component Documentation for each global attribute component.

See Also Parameter (only for SingleDoc.tpl):

Pagination | Start from new page | Components | Global Attribute

globalAttribute.tpl, globalAttributes.tpl

Specifies whether to generate the XML Namespace Bindings page/block.

Related Template:

xmlns-bindings.tpl