9. Hints and tips

9.1. What is SchemaDoc useful for ?
9.2. Schema management
9.3. Technical hints
9.4. Frequently asked questions
9.5. How do I
9.6. Working with Spy graphics
9.7. Parametrization of output managements

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

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.

  1. How do I change the text labels generated within the documentation from English to French?

  2. I have redefined an object and I cannot set hyperlinks to it. How can I set links?

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