5. Creating documentation for a new model

5. Creating documentation for a new model

5. Creating documentation for a new model

5.1. Creating model documentation from scratch
5.2. Creating model documentation using the graphical user interface

Model documentation is structured as a book composed of chapters and appended with all schemas that need to be documented. This section provides a basic walkthrough of the steps necessary to create a new document. If you require a more complete explanation, refer to the DTD documentation (Section 7, “Reference manual : document model”). A sample is provided in the installation directory, in the sample sub directory.

To create documentation for a new model, two approaches are available:

Create the document from scratch, using your own editor (see Section 5.1, “Creating model documentation from scratch”)
Create the document using a simplified user interface (see Section 5.2, “Creating model documentation using the graphical user interface”)

5.1. Creating model documentation from scratch

In order to create documentation for a new model, you need to create a skeleton file that conforms to the SchemaDoc DTD. The skeleton contains an article element, which has been modified from the DocBook standard. These are the necessary steps:

Define the document type and entities
The document type declaration must be associated with the location of the SchemaDoc DTD because the public name is not enough.
```
<!DOCTYPE article PUBLIC
"-//TIREME//DTD Documentation Of Schema Reference//EN" "..\models\dtds\SchemaDoc.dtd"
[
```
All required parameter entities are defined within the document type declaration. This is a requirement for all schema used because the XML Schema specification relies on file organization.
```
<!ENTITY mod1 SYSTEM "./myFirstModel.xsd"> <!ENTITY
mod2 SYSTEM "../models/schemas/anOtherModel.xsd">
```
Note
For large volume documentation, it is possible to create fragments. This may be done at the sect1 level. In order to do this, all sections are created in separate files and are included within the documentation as new parameter entities.
Namespaces
SchemaDoc tools are namespace aware so the article element must declare all required namespaces for SchemaDoc.
```
<article 
```
```
	xmlns:sd="http://www.tireme.fr/XMLSchema/documentation/V1/" 
```
```
	xmlns:tbl="http://www.oasis-open.org/tables/exchange/1.0" 
```
```
	xmlns:xs="http://www.w3.org/2001/XMLSchema" 
```
```
	xmlns="http://www.oasis-open.org/docbook/xmlschema/4.1.2"
```
```
 ... >
```
The required namespaces to be declared are:
- the SchemaDoc namespace: "http://www.tireme.fr/XMLSchema/documentation/V1/"
- the XML Schema namespace: "http://www.w3.org/2001/XMLSchema"
- the DocBook namespace, which is the default namespace: "http://www.oasis-open.org/docbook/xmlschema/4.1.2"
Note
If your schema declares namespaces and you are validating your XML SchemaDoc documentation against the SchemaDoc DTD, see Section 9.2.2, “I got an error related to the declaration of a namespace in a schema”the explanation on how to tune the SchemaDoc DTD externally.
Default namespace for references
In order to simplify references from the DTD to objects defined within XML Schema, qualified names are used. This is not useful while writing documentation because there is too much information to provide. Therefore, SchemaDoc makes it possible to put at all section levels of documentation (sect1, sect2, etc.) a default namespace for all contained references. This default namespace must be initialized at the level of the article element.
```
<article 	... 	sd:defaultNS="http://www.tireme.fr/XMLSchema/documentation/V1/">
```
Language
All programs that generate output provide explanation of labels. This information must be in the same language as the documentation itself. A sdLang.attribute attribute defines whether the documentation is in French or English. These are the only languages available at present.
```
<article 	... 	sd:language="fr">
```
Documentation information
Once the article element has been created, you specify all documentation sections. If required, you can add standard DocBook articleinfo to provide metadata information such as author, version, and titles.
If sect1 and articleinfo elements have been defined as parameter entities, they are called here.
```
&info;
```
```
&docIntro; 
```
```
&tools; 
```
```
&xs2dtdSpec; 
```
Schema information
Following the documentation section, you use a SchemaDoc sd:schemaDef container element to define the schema used in the model.
```
<sd:schemaDef>
```
```
 ... 
```
```
</sd:schemaDef>
```
Namespace identification
As the first element within sd:schemaDef, you declare all namespace prefixes used within the documentation. This is a current limitation of SchemaDoc and is necessary to facilitate reference solving algorithms.
If different prefixes are used for the same namespace within the documentation, they must all be declared. The default namespace must also be declared.
```
<nsDecl 
```
```
 nsPrefix="db"
```
```
	nsName="http://www.oasis-open.org/docbook/xmlschema/4.1.2"/>
```
```
<nsDecl 
```
```
 nsPrefix="sd"
```
```
 nsName="http://www.tireme.fr/XMLSchema/documentation/V1/"/>
```
```
<nsDecl 
```
```
 nsPrefix="xs"
```
```
 nsName="http://www.w3.org/2001/XMLSchema"/>
```
Note
The limitation on declared namespaces also exists at schema levels where the schema itself needs to have a target namespace that needs to be declared here:
```
<nsDecl 
```
```
 nsPrefix="mySchema"
```
```
 nsName="http://www.myCompany.com/guide/xmlschema/2.0"/>
```
Including schemas
You must reference all schemas used by the documentation as parameter entities.
```
<sd:schemaDef>
```
```
	
```
```
	...
```
```
	
```
```
	&mod1;
```
```
	&mod2;
```
```
</sd:schemaDef>
```
Note
For the schema element itself, refer to xs:schema definition in order to understand the different attributes that need to be set up.
That's all!
All necessary information for the skeleton of documentation is defined.

5.2. Creating model documentation using the graphical user interface

A graphical user interface is provided to create the skeleton of documentation for a new model. A new set of documentation is generated from information defined in the interface. This documentation can then be extended as needed.

Note

This interface is provide from the main SchemaDoc user interface (see Section 6.2.1.2, “Using the tool”).

Figure 5.

With:

Name of the configuration. This name will be used as a reminder in the output user interface.

Path to the initial schema location.
Note
This schema will be modified slightly to conform to SchemaDoc conventions. These modifications will not affect the model defined in the schema.
Directory where PDF or HTML documentation will be generated according to SchemaDoc conventions (see Section 6.2.1.2, “Using the tool”).
Name and path of the SchemaDoc documentation to be created.
Language of the documentation (different from the one of the user interface).
Launch the generation based on the new configuration.
Cancel the task.

Once the new documentation is created, everything will need to be tuned if there is a need to add other schemas or to add new chapters of documentation (see Section 5.1, “Creating model documentation from scratch”).


4. Getting started		6. Tools and others enablers