 |
| ||||||
|---|---|---|---|---|---|---|---|
Long experience with SGML DTDs has shown that it is necessary to provide documentation along with a document model. This documentation is useful for all people who directly manipulate a document model, either to understand it or to use it to create an application.
SchemaDoc targets two types of user:
End users who create, modify, and use XML documents. These users need to understand the structure of the XML document or the XML data set that they manipulate and to know the meaning of all markup and attributes.
Users who have to maintain the consistency of set of models and need to maintain information about a document model for themselves, perhaps with a different point of view.
SchemaDoc provides a way to associate the necessary documentation of XML reference models (schemas and DTDs). SchemaDoc publishes that documentation as HTML files and printable Adobe PDF files.
Documents are often complex, i.e. they can have a structure composed of different autonomous subparts.
The exploitation of one kind of document may require more than one DTD/schema, each one adapted for a specific use.
Moreover, families of associated types of documentation generally share at least one structure of subparts: it is appopriate that the organization of metadata covering reference numbers, authors, revision date, etc. would be identical for all documents of the same family. DTDs/schemas of documents in the same family will share some identical parts.
It is recommended to fragment schemas in order to achieve and maintain consistency among a set of schemas that share identical subparts.
There is also a technical and ergonomic reason to fragment schemas: statistics indicate that a 400KB schema would generate a 6MB HTML file that uses 100MB of memory within Internet Explorer 6. In order to reduce the size of the HTML file to below 150K (a reasonable publication limit) fragments should not exceed 10K.
Typically, the error is like :
[Error:MSG_ATTRIBUTE_NOT_DECLARED]: Attribute "xmlns:ipx" must be declared for element type "xs:schema". (file:/T:/proj/ipx/maquette/model/Item.xsd:170) (Attribute "xmlns:ipx" must be declared for element type "xs:schema".)
If you got this error, it means that you are validating your documentation against the SchemaDoc DTD which is not, as all DTD are not, namespace aware. For turning around this limitation, DTDs often declares namespace declarations as attributes. This works as soon as you manage the predix declaration of your namespace.
Practically, you need to add tell SchemaDoc DTD what are the different namespace declaration that may be encountered. This is done using the local.added.namespace.attr parameter entity.
For example, for solving the above message, you need to change your DOCTYPE declaration as follows :
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//TIREME//DTD Documentation Of Schema Reference//EN" "T:\proj\tireme\SchemaDocV2\models\dtds\SchemaDoc.dtd" [
...
<!ENTITY % local.added.namespace.attr " xmlns:ipx CDATA #IMPLIED ">]>
<article id="newSchemaID" sd:defaultNs="
If, in your schema, you use the XML schema namespace, accessing attributes such as xml:lang, you may get, either in french or in english, an error like:
Pas de référence(s) possible(s) dans findAnXSObject !! (xs:attribute xml:lang --> xs:annotation)
And then, a little bit later in your log you have:
--> Error: no ID for constraint linkend: nothing.
--> XRef to nonexistent id: nothing
For solving the problem, you need to add the XML schema namespace under control of your document, in the sd:schemaDef section. In plus, you need to declare its prefix in an sd:nsDecl element.
SchemaDoc provides a template example to help begin a new documentation set. Templates are available in French and English in the directory /SchemaDoc/data/daUsr/SchemaDoc.
Once the environment is prepared (i.e. all files customized with proper links between them and their resources) it is useful to check it, generating an empty documentation set using the "generate
missing option".
That option of the SchemaDoc documentation publisher provides an XML file as below :
<sect1
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:tbl="http://www.oasis-open.org/tables/exchange/1.0"
xmlns:sd="http://www.tireme.fr/XMLSchema/documentation/V1/"
xmlns:temp="http://www.tireme.fr/SchemaDoc/temporaryAttributes/"
xmlns:doc="http://nwalsh.com/xsl/documentation/1.0"
xmlns:db="http://www.oasis-open.org/docbook/xmlschema/4.1.2" >
<title>Missing documentation</title>
<sd:elemDocRef linkend="NomElementNonDocumente"/>
<sd:elemDocRef linkend="NomAutreElementNonDocumente"/>
<sd:complexTypeDocRef linkend="NomTypeElementNonDocumente"/>
</sect1>
...
With the result of that first generation, you can generate the skeleton of your documentation using an XSL transformation like those (missing-english.xsl or missing-french.xsl) provided in the directory : SchemaDoc\pgm\tips-xsl. The name and place of the result should be consistent with the entity declaration you have made for it in your main documentation
file
The actual documentation work will consist in editing that result using an XML editor
Reoperating SchemaDoc with HTML option, without the missing option will provide you a first complete frame of the documentation of your Schema.
If you want to have messages in French or English, use the command line switch -l. If you want the labels generated in French or English within the documents themselves, use
the sdLang.attribute attribute.
Why does my index for all existing objects not contain anything?
Check your xs:schema elements. It's likely that no manage attributes have been set up to true.
How do I change the text labels generated within the documentation from English to French?
Check the article attribute called sdLang.attribute. It needs to be equal to fr.
I have redefined an object and I cannot set hyperlinks to it. How can I set links?
Check the sd:complexTypeDocRef/@linkendRedef attribute value (same for sd:groupDocRef, sd:groupRef and sd:complexTypeRef). It must link to the xs:schema/@id of the xs:schema containing the redefinition. A common error is to use the xs:redefine/@id attribute.
How can I resolve a parsing error in the SchemaDoc document?
Most times, it means that your documentation does not conform to the DTD. Nevertheless, earlier versions require an internal subset with a declaration of a parameter entity local.article.attribute. This declaration needs to be removed now.
A complex type is defined twice but in two schema files different.
If you got a message like “ --> Attention, la documentation de element_1Type est définie deux ou plusieurs fois.”, this certainly means that you are not using the schemaId attribute of the object (<sd:complexTypeDocRef linkend="element_1Type" schemaId="root1" ...) on one of the different occurrences of the same object name.
Make all my hyperlinks and file names coherent along different output generations.
Be sure to affect an ID to all section levels, and other elements. SchemaDoc itself will use them.
I lost some png files generated by XML Spy but they are needed
If you check "remove unused XML Spy graphics" and uncheck "with documentation model" buttons, all graphics that are not used straight by the documentation are removed. Therefore, if you need to uncheck "with documentation model" button, be sure that you will never need all graphics that will be removed.
In all cases, you now need to regenerate SPY graphics documentation now.
I got a message from graphic manager of SchemaDoc explaining that it was impossible to find a schema file
The message looks like : Problem while loading graphic document : unable to find the model file {0} referenced by the ID "{1}" of a Spy documentation. See also "hints" section within the documentation.
This is due to XMLSpy limitation: while trying to find all SPY needed graphics in the documentation, the program uses the information generated by XMLSpy on where is stored the schema.
If the file is no more at the place defined within the XMLSpy documentation, an error is raised. This mainly happends as soon as you move a documentation from a file system to an other one.
In order to solve the problem, you can either regenerate the spy documentation or defines the anchor link as a relative path, as it is done in the sample.
I got a message complaining about an internal Doctype
Because version 2008SP2 of XMLSpy is using XHTML, the HTML documentation have a doctype as first line. If toy try to use this file, along with other ones in using entities mechanism, you may have this parsing error.
Through the Source spy field of the interface, users can indicate to SchemaDoc where to look for the Spy graphics. If SchemaDoc does not find the graphics where it is asked
to, it will look for then in the directory of the SchemaDoc source document (document SchemaDoc field).
SchemaDoc uses the tables (html files) generated by Spy to resolve elements-graphics matching. In these tables, Spy attaches elements to XML Schema files which, in turn, refer to ids. If graphics are generated on another platform than the one running the SchemaDoc generator, this matching through file name would always fail. To avoid this dead-end, the generator will not treat this situation as an error. It assumes that the files names which appear in this table, as absolute names in the Spy executing context, can be resolved in the source documentation base directory.
 |  |  |
| 8. XS2DTD documentation use | 10. Limitations |