 |
| ||||||
|---|---|---|---|---|---|---|---|
|
| ||||||
|---|---|---|---|---|---|---|---|
In order to coordinate a set of documentation and its associated set of schemas, SchemaDoc uses a group of elements that links the DocBook namespace and the XML Schema namespace. These elements are declared either as block components (for example, sd:elemDocRef) or as inline references (for example, sd:elemRef).
— Defines a default namespace reference for all links declaration used by sd elements.
This mechanism is used in order to solve namespaces naming used by the documented DTDs while referencing. The idea is to enable different mechanisms.
All xxxRef elements have at
least two attributes: linkend and sd:defaultNs. linkend may contain a local name (myObject) or a prefixed name (test:myObject); this is the first mechanism. As an alternative, if a sole local
name is provided, sd:defaultNs can be
used in conjunction. Then, as a generalisation, if sd:defaultNs attribute is not provided, all processes
should look on the stack of open elements in order to find a default
namespace. At least, the one defined at article level will be found.
— Container for all schema files used within the documentation
Also documents sd:nsDecl
This element is called within article at the end, in order to make the integration of all defined Schemas within the documentation. Prior to make the integration, it requires namespace prefix declarations, using the sd:nsDecl element.
As a restriction, and for the purpose to ease namespace resolution in Schema object called from the documentation, all namespace prefixes needs to be declared. There is one sd:nsDecl declaration by namespace prefix used and if different prefixes are used for the same namespace, all of them need to be declared. At least, there is for now a need for one declaration: the default namespace used by the Schema in reference.
Attribute used as soon as the ID/IDREF mechanism is required.
linkend attribute is used for
enabling an ID/IDREF mechanism but the information is declared as
character just because of fragment editing.
schemaId enables to define
which object is documented, in which Schema in case of two roots within
a grove defining the same object.
Block components are present in documentation as para. They are containers for documentation of an object. For the moment, block components can only document a global element, in the XML Schema meaning. This restriction may be removed later, on a per need basis.
The provision for these kind of blocks includes the following declarations.
This element enables it, providing a term to be defined (glossterm) plus its formal definition (glossdef) with a provision of different kind of blocks for the definition wording. The information is supposed to be concise and will be also provided as a glossary in the different outputs. As a replacement of the definition, there may be a glosssee element forwarding to a yet existing definition.
| Name | Type | Use | Default val. | Facets |
| (Group) common.attrib | ||||
| (Group) glossentry.role.attrib | ||||
| sortas | ||||
— Model for content documentation of all xs objects that does not have attributes
This defines standard attribute set and content model of all block references components. As a special case, see sd:documentedObjectsHavingAttributes.
— Model for content documentation of all xs objects that does have attributes
This type is an extension of the preceding sd:documentedObjects enabling to have specific documentation sets on xs:attribute or xs:attributeGroup straight within the element. This documentation will be fully formatted later, as a special object. Mainly, the content has, in first, a sd:objAttributeDoc element.
— Enable to document attributes of a specific container
Enables to define attribute or attribute group documentation. This information is useful as-is in the documentation; later, it may be used for different schema or DTD output information.
For now, it is not a requirement of documenting all attributes.
— defines all objects also documented by its container
At top level of all xxx.DocRef elements, enable to define which are the other objects that are also documented in the container.
This feature enables to reduce the amount of documented objects and help to have an synthetic view of a set of documentation information.
— Element for creating documentation of an attribute
Block component documenting an xs:attribute element.
— Element for creating documentation of an attribute group
Block component documenting an xs:attributeGroup element.
— Element for creating documentation of a complex type
Block component documenting an xs:complexType element.
— Element for creating documentation of an element
Block component documenting an xs:element element.
— Element for creating documentation of a group
Block component documenting an xs:group element.
— Element for creating documentation of a simple type
Block component documenting an xs:simpleType element.
— Enable to communicate between people of a same project
Block component enabling to shared comments between different actors of a project. Should never exists when a documentation is published.
Inline components happen as references, straight within text. All references are made on the basis of global elements. As soon as a local element is referenced, it is done regarding to its use within a global element.
The provision for these kind of inline references includes the following declarations:
— Referencing an attribute
Inline reference component documenting an xs:attribute element.
— Referencing an attribute group
Inline reference component documenting an xs:attributeGroup element.
— Referencing a complex type
Inline reference component documenting an xs:complexType element.
— Referencing an element
Inline reference component documenting an xs:element element.
— Referencing a group
Inline reference component documenting an xs:group element.
— Referencing a simple type
Inline reference component documenting an xs:simpleType element.
In plus of these elements, there is a provision for local attributes (sd:localAttributeRef) or elements (sd:localElemRef).
Is either element or complexType. It is needed in order to find the right
global object: a complexType and an element can both have the same
qualified name.
— Referencing an element local to a global object
Enables to identify an element local to a global element. The element is identified using its logical path within the object.
Attributes and attr. groups
Defines a path within the object. The path is understood as an XPath that may be found within a document issued from the model.
see sd:globalObjType.
| Name | Type | Use | Default val. | Facets |
| sd:defaultNs | ||||
| (Group) sd:globalObjType | ||||
| (Group) sd:linkendAsCharReq | ||||
| path | xs:string | required | ||
| schemaId | ||||
— Referencing an attribute local to a global object
Enables to identify an attribute, within a global element. The attribute is identified using its logical path within the object.
Attributes and attr. groups
Defines a path within the object. The path is understood as an XPath that may be found within a document issued from the model.
see sd:globalObjType.
| Name | Type | Use | Default val. | Facets |
| sd:defaultNs | ||||
| (Group) sd:globalObjType | ||||
| (Group) sd:linkendAsCharReq | ||||
| path | xs:string | required | ||
All a SchemaDoc documentation is contained within a DocBook article element which have been redefined for this purpose.
The modifications to a standard DocBook article are the following ones:
Before the end of the element, there is a call enabling to include all schema information, using sd:schemaDef.
A sd:defaultNs attribute is added. Because of the propagation mechanism, this will be the default value used everywhere within all the documentation.
sdLang.attribute attribute enables to define the language in which the documentation is made. This attribute is useful at output generation in order to have all labels depending on it.
sd:publicName: the public name of the Schema. This information will be used, later for catalog, as defined by OASIS Recommendation. Actually, this information is used in the formatting interface for identifying Schemas with some more meaningful identification than the sole ID. Person making the documentation is responsible for the unicity of this information.
| Name | Type | Use | Default val. | Facets |
| role | schemadoc | Enumerated values: schemadoc | ||
| (Group) SCHEMADOC.article.attributes | ||||
All sections of the DocBook hierarchy needs to be able to support the default namespace referencing attribute (sd:defaultNs) in order to be able to change it locally. This is the reason of redefinition of all these elements.
| Name | Type | Use | Default val. | Facets |
| (Group) common.attrib | ||||
| (Group) label.attrib | ||||
| renderas | Enumerated values: sect2 | sect3 | sect4 | sect5 | |||
| (Group) SCHEMADOC.specificAttributesForDBHierarchy | ||||
| (Group) sect1.role.attrib | ||||
| (Group) status.attrib | ||||
In order to add SchemaDoc elements, there is a redefinition of component.mix, at block level and of xref.char.class, at inline level.
Redefinition in order to add all specific SchemaDoc elements to accessible components (block level).
Redefinition in order to add all specific references needed for being able to link from DocBook to Schema within text.
The modifications are the following ones:
Before the end of the element, there is a call enabling to include all Schema information, using sd:schemaDef.
sd:defaultNs: this attribute is added, for all documentation references that may be found within xs:annotation.
manage: contains a boolean value (true or false). Enables to decide if the Schema should be managed by output programs, for formatting content either on the web or on paper.
Default is false. This means that users needs to only identify the Schema files they want to be managed.
This is usefull as soon as a model integrates other well defined models. For example, if one is writing a wrapper of the DocBook model, there is no need to manage the DocBook model itself. In this case, only the wrapper will have the manage attribute set to true.
sd:publicName: the public name of the Schema. This information will be used, later for catalog, as OASIS Recommendation. Actually, this information is used in the formatting interface for identifying Schemas with some more meaningful identification than the sole ID. Person making the documentation is responsible for the unicity of this information.
Also documents - sd:dtdLocation sd:publicName
xs:redefine, xs:include and xs:import are also both referencing Schemas. In the process of DTD generation from Schema, one may not want to generate the DTD from the Schema and will prefer its own one. In this case, he will fill this attribute, providing a valid URI using the value of sd:dtdLocation. The program of DTD generation will use this sd:dtdLocation value (and the sd:publicName value, if provided).
This feature is interesting as soon as standards for objects are used within a specific model. For example, if one model uses HTML tagging, there is no use to generate an HTML model from a Schema: it is better to straight use the well known and standardized DTD for HTML.
— add a sd:doc-loc attribute group
Also documents - xs:import xs:include
Enabling to use sd:doc-loc.
— Restricting to docbook contents
In order to output a readable documentation, the xs:appinfo element is redefined in order to give it more meaningful.
Its content model becomes a call to some DocBook hierarchies and paragraphs. This is later used to have a different formatting of the information. It should have been better to straight implement sections hierarchies within a Schema, but editing Schemas tools do not like mixing the Schema namespace with other documentation.
 |  |  |
| 6. Tools and others enablers | 8. XS2DTD documentation use |
