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, schemas and components throughout the whole documentation.

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

It directly affects:

1. The order in which the namespaces are listed in the Overview Frame (see also the parameter: Navigation | Overview Frame).
2. In the case of framed documentation, the order in which namespace become fully processed and documented.

   That determines which namespace gets documented the first, which, in turn, may affect the initial content of the frames:

   • List Frame. (See parameter: Navigation | List Frame)
   • Detail Frame. (See parameter: Navigation | Detail Frame)
3. In the case of single file documentation, the order in which the full details of namespaces follow in the file.

   Those details may include the Namespace Overview and the details of all components belonging to the namespace (Component Documentation blocks).

Details | Overview | Namespace Summary | Sorting

The parameter has the following meaning:

• 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 will not be sorted anyhow. In that case, the ordering of namespaces will be defined by how the initial XML schemas (to be documented) have been specified as well as how these schemas import other XML schemas.

  For more information about this, see also the parameter group: Generate Details | For schemas

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 documentation, the order in which XML schemas become fully documented (which includes the generation of the Schema Components and Schema Overview 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 parameter: Navigation | List Frame)
   • Detail Frame. (See 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.

• Details | Overview | Schema Summary | Sorting
• Details | Namespace | Schema Summary | Sorting

The parameter has the following meaning:

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

  For more information about this, see also the parameter group: Generate Details | For schemas

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

1. The sorting of components summaries.

   In fact, that is controlled via other parameters:

   • Details | All Components | Sorting
   • Details | Namespace | Component Summaries | Sorting
   • Details | Schema | Component Summaries | Sorting
   However, this parameter provides the default value to all of them. (Thereby, in most cases you don't need to specify any of those parameters directly.)
2. In the case of framed documentation, the sorting of component navigation lists.

   Precisely, this is controlled via the following parameters (for which this parameter provides the default value):

   • Navigation | List Frame | All Components | Sorting
   • Navigation | List Frame | Namespace | Sorting
   • Navigation | List Frame | Schema | Sorting
3. In the case of single file documentation, this parameter directly controls the ordering of component details (called Component Documentation).

• When the parameter is selected (true), the 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 a local element, 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 components will not be sorted. In that case they will follow in a certain "physical" order produced according to the following.

  When the components come from different XML schemas, first, they will be grouped by their schemas. The ordering of those groups is determined by how the initial XML schemas (to be documented) have been specified as well as how these schemas import other XML schemas (for that matter, see also the parameter group: Generate Details | For schemas).

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

  This gives you a possibility to specify a particular ordering of the 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 the 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.

The Overview Summary may be generated only once for the entire XML schema documentation. It appears the first in the Detail Frame of framed documentation (when it is started) or on the first page of single file documentation (RTF).

The exact content of the Overview Summary is controlled by the parameter group:

Details | Overview

Pagination | Start from new page | Overview

overview.tpl

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

This page/block may be generated only once for the entire XML schema documentation. It contains summaries of all schema components of the specified types throughout all schemas being documented.

The exact content of the All Component Summary is controlled by the parameter group:

Details | All Components

Pagination | Start from new page | All Components

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.

When specified, the Namespace Overview will be generated for each namespace being documented (i.e. targeted by at least one of the documented XML schemas).

The exact content of the Namespace Overview is controlled by the parameter group:

Details | Namespace

Pagination | Start from new page | Namespace

namespace.tpl

Specifies whether to generate the Schema Overview pages/blocks.

When specified, the Schema Overview will be generated for each XML schema being documented.

The exact content of the Schema Overview is controlled by the parameter group:

Details | Schema

Pagination | Start from new page | Schema

schema.tpl

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

The exact content of the Component Documentation is controlled by the parameter group:

Details | Component

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

Pagination | Start from new page | Components

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

Nested Parameter:

Specify which of the local element components must be documented.

Pagination | Start from new page | Components | Element

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 Namespace Bindings report.

This report will allow you to quickly find by any namespace prefix used in the source XSD files the namespace URI associated with it and the exact location where that namespace binding is specified.

See Also Parameter (only for SingleDoc.tpl):

Pagination | Start from new page | XML Namespace Bindings

xmlns-bindings.tpl