7. Reference manual : document model

7.1. SchemaDoc elements
7.2. DocBook elements
7.3. Schema elements

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

Attribute sd:defaultNs

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

Element sd:schemaDef

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

defaultNsnsDeclmapN10D82
mapN10DDD

Attribute group sd:linkendAsCharReq

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.

Element glossentry

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.

glosstermacronymabbrevndxterm.classindextermrevhistoryglossseeglossdefmapN10F1E

Complex type sd:documentedObjects

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

defaultNsshowObjGraphicalsoDocumentsdivcomponent.mixlist.classitemizedlistorderedlistvariablelistadmon.classcautionimportantnotetipwarningattributeDocRefelemDocRefattributeGroupDocRefcomplexTypeDocRefgroupDocRefsimpleTypeDocReftoBeSolvedglossentrylinespecific.classliterallayoutprogramlistingpara.classparainformal.classmediaobjectgraphicformal.classequationexamplefigureinformalfiguretabletbl.table.mdlinformaltableinformal.tbl.table.mdlmapN10FCD

Complex type 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.

defaultNsshowObjGraphicobjAttributeDocalsoDocumentsdivcomponent.mixlist.classitemizedlistorderedlistvariablelistadmon.classcautionimportantnotetipwarningattributeDocRefelemDocRefattributeGroupDocRefcomplexTypeDocRefgroupDocRefsimpleTypeDocReftoBeSolvedglossentrylinespecific.classliterallayoutprogramlistingpara.classparainformal.classmediaobjectgraphicformal.classequationexamplefigureinformalfiguretabletbl.table.mdlinformaltableinformal.tbl.table.mdlmapN1110E

Element sd:objAttributeDoc

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

localAttributeDoclocalAttributeDocTypelocalAttributeGroupDoclocalAttributeDocTypemapN11246

Element sd:alsoDocuments

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

attributeGroupRefattributeRefcomplexTypeRefelemRefgroupRefsimpleTypeRefmapN1128B

Element sd:attributeDocRef

— Element for creating documentation of an attribute

Block component documenting an xs:attribute element.

Element sd:attributeGroupDocRef

— Element for creating documentation of an attribute group

Block component documenting an xs:attributeGroup element.

Element sd:complexTypeDocRef

— Element for creating documentation of a complex type

Block component documenting an xs:complexType element.

Element sd:elemDocRef

— Element for creating documentation of an element

Block component documenting an xs:element element.

Element sd:groupDocRef

— Element for creating documentation of a group

Block component documenting an xs:group element.

Element sd:simpleTypeDocRef

— Element for creating documentation of a simple type

Block component documenting an xs:simpleType element.

Element sd:toBeSolved

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

para.char.mixxref.char.classfootnoterefxrefattributeGroupRefattributeRefcomplexTypeRefelemRefgroupReflocalAttributeReflocalElemRefsimpleTypeRefschemaRefglossrefgen.char.classacronymemphasisquotetrademarklink.char.classlinkulinktech.char.classcommandcomputeroutputfilenameliteralcodebase.char.classanchorother.char.classsubscriptsuperscriptinlineobj.char.classinlinemediaobjectinlinegraphicinlineequationinlineequation.contentmapN1192D

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:

Element sd:attributeRef

— Referencing an attribute

Inline reference component documenting an xs:attribute element.

Element sd:attributeGroupRef

— Referencing an attribute group

Inline reference component documenting an xs:attributeGroup element.

Element sd:complexTypeRef

— Referencing a complex type

Inline reference component documenting an xs:complexType element.

Element sd:elemRef

— Referencing an element

Inline reference component documenting an xs:element element.

Element sd:groupRef

— Referencing a group

Inline reference component documenting an xs:group element.

Element sd:simpleTypeRef

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

Attribute group sd:globalObjType

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.

Element sd:localElemRef

— 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

path

Defines a path within the object. The path is understood as an XPath that may be found within a document issued from the model.

sd:globalObjType

see sd:globalObjType.

schemaIddefaultNsmapN11C7B

Element sd:localAttributeRef

— 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

path

Defines a path within the object. The path is understood as an XPath that may be found within a document issued from the model.

sd:globalObjType

see sd:globalObjType.

defaultNsmapN11D36

All a SchemaDoc documentation is contained within a DocBook article element which have been redefined for this purpose.

Element article

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.

In order to add SchemaDoc elements, there is a redefinition of component.mix, at block level and of xref.char.class, at inline level.

Group component.mix

Redefinition in order to add all specific SchemaDoc elements to accessible components (block level).

list.classitemizedlistorderedlistvariablelistadmon.classcautionimportantnotetipwarningattributeDocRefelemDocRefattributeGroupDocRefcomplexTypeDocRefgroupDocRefsimpleTypeDocReftoBeSolvedglossentrylinespecific.classliterallayoutprogramlistingpara.classparainformal.classmediaobjectgraphicformal.classequationexamplefigureinformalfiguretabletbl.table.mdlinformaltableinformal.tbl.table.mdlmapN12106

Group xref.char.class

Redefinition in order to add all specific references needed for being able to link from DocBook to Schema within text.

footnoterefxrefattributeGroupRefattributeRefcomplexTypeRefelemRefgroupReflocalAttributeReflocalElemRefsimpleTypeRefschemaRefglossrefmapN121EA

Complex type xs:schema

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.

Attribute group sd:doc-loc

   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.

mapN1236B
mapN12378

Complex type xs:appinfo

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