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. Error solving
9.6. How do I
9.7. Working with Spy graphics

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.

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

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

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