The provided environment is a simple adaptation of DocBook; for professional use, it would needs to be reworked for being more efficient.
 |
| ||||||
|---|---|---|---|---|---|---|---|
|
| ||||||
|---|---|---|---|---|---|---|---|
Tools are divided into two categories:
Editing tools parameters sets.
This is mainly the text editing tool. For now, environments has been created for being used with Arbortext Editor 5.x and XMLmind XML Editor 2.9.
Java specific tools or enablers
These tools are grouped within a sole and specific user interface ad are used to generate output published outputs, to manage DTD and to manage quality.
DTD is brand new and experimental, enabling to generate DTD from SchemaDoc managed schemas
An editing tool and it's proper parameters set define what will be called an editing environment. To activate a SchemaDoc editing environment, the editing tool has to be bound to it's SchemaDoc parameter set.
A simple environment is provided in order to edit the documentation. This environment does not include Schema editing.
 |
The environment uses a doctype model packaging which is provided in the SchemaDoc_ENV_HOME directory, under the pgm/daUsr/SchemaDoc sub directory. In
order to use it, the %SchemaDoc_ENV_HOME%/pgm/daUsr path needs to be referenced in the Epic catalog path manager.
An XMLMind XML Editor (XXE) environment is provided in order to edit the documentation. The environment includes minimal Schema features editing. It's been proven to be fully compatible with XXE 3.5.2. It's been successfully tested with previous versions (such as 3.1.0) which generate some error messages that can be safely ignored.
 |
The environment uses a doctype model packaging which is provided by the SchemaDoc installer, under the ~SchemaDoc/pgm/xxe sub directory. The easy way to activate
an XXE SchemaDoc environment is to set the XXE_ADDON_PATH environment variable to an absolute path to that sub directory. On a MS-Windows system, the appropriate set command will be
something like this :
set XXE_ADDON_PATH=@file:///~SchemaDoc/pgm/xxe
The provided environment is a simple adaptation of DocBook plus the schema environments provided by Pixware.
Using the XXE_ADDON_PATH environment variable will override previous XXE settings and make the editor a dedicated SchemaDoc editor. Users who intend to use XXE to edit non SchemaDoc
documents will need to use more elaborated XXE customizing techniques which allow multiple concurrent editing environments (see XXE documentation).
An early stage implementation is now provided that needs to be more comforted.
No tools are provided for this activity: all tools may be used and SchemaDoc assumes that the provides Schemas are fully valid regarding to the W3C specifications.
Nevertheless, a specific enabler helps to use XMLSpy generated graphics within SchemaDoc outputs. See section "Section 6.2.2, “Configuring connection with XMLSpy generated graphics”"
All these tools are provided as a sole Swing Java Interface. The Javadoc documentation of this program is also provided.
The tool works either under Linux or Windows. Note that because the graphics used are made with XML Spy, which is a Windows software, there is a need to tune some parameters while building a documentation set.
The tool is managing the generation of different outputs : HTML, PDF (using FOP) and an experimental JavaHelp. For the purpose of showing the model in a best way, the tool is actually using graphics generated by XML Spy.
Specific Windows and Unix scripts are provided, both in %SchemaDoc_ENV_HOME%/bin and respectively called sdOutput.bat and sdOutput.sh. both using the SchemaDoc_ENV_HOME environment variable.
The command line is:
java
-Djava.endorsed.dirs=%SchemaDoc_ENV_HOME%\lib\endorsed-classpath ...
-DSchemaDoc_pgm_home="%SchemaDoc_ENV_HOME%"
-Djava.util.logging.config.file=%SchemaDoc_ENV_HOME%\conf\properties\logging.properties
fr.tireme.SchemaDoc.Xml2output [options]
With:
-Djava.endorsed.dirs : used to overwrite the standard SUN JDK implementation of Xalan;
-DSchemaDoc_pgm_home : the passing of the Windows (Unix) environment variable to Java;
-Djava.util.logging.config.file : the parameters for the logging mechanism;
fr.tireme.SchemaDoc.Xml2output : the main starting class.
Options are:
-l (or--language): language of the user interface. This value can be fr or en ; default value is en;
The language here defined is the one used by the user interface. In order to address labelling language in the output documents, the attribute sdLang.attribute needs to be used.
-d (or --debug): runs in a debug mode, more verbose;
-c (or --configFile): defines an alternative to the standard configuration file stored under %SchemaDoc_ENV_HOME%/data/config.xml. This may
be useful when different peoples shares the same installation on a network. In this case, each may needs to have its own configuration file.
-h (or --help): prints a help message.
Once all this installation is done, one may test all generation programs using the documentation contains within the %SchemaDoc_ENV_HOME%/sample directory (see Section 6.2.1.3, “Testing with the "sample" documentation”).
In a DOS window, start the sdOutput.bat commands ; under Unix environment, starts sdOutput.sh. A window opens as in the following figure.
With:
Is there also a reference model output or only documentation to be created ?
It is possible to get a sole documentation and, in plus, an ordered view presentation of the Schema iself. This option enables to remove the second part.
Generates an HTML output.
The program generates an HTML version of the documentation regarding to parameters of the output directory set in step 10 : subdirectory html.
Generates a PDF output using Apache FOP.
The program generates a FO version of the documentation regarding to parameters of the output directory set in step 10 : subdirectory pdf.
This file may be used by any FO formatter engine. From this file, and automatically, the engine generates a PDF version, using the Apache FOP engine. If someone wants to use its own engine, he will take the FO file generated.
item no more used.
Generate a list of all objects that are not documented.
This file is generated regarding to parameters of the output directory set in step 10 onto missing.xml.
It is a good starting point for copying it in the documentation and begin to document it.
Generate the DTD from the Schema inputs (see Section 8, “XS2DTD documentation use” ).
Use images generated from XML Spy for the model?
See section "Section 6.2.2, “Configuring connection with XMLSpy generated graphics”" for more informations.
Path of the XMLSpy wrapper documentation.
See section "Section 6.2.2, “Configuring connection with XMLSpy generated graphics”" for more informations.
Path of the XML source documentation file.
Defines where is the input source XML document.
Output path where all documentations will be issued.
Defines where all documentations will be generated. There should be two sub directories within : html for HTML files and pdf for the paper output.
Path for the generated DTD (not yet implemented).
For test and debug purpose, defines a schema to be converted in DTD (see also item 14 for launching the conversion).
Log window.
For test and debug purpose, launch the conversion of the schema identified in (12) to a DTD in directory defined in (11).
Remove all non needed Spy files
XMLSpy may generate a lot of images files that will not been used by SchemaDoc: for example, all graphics of local element declarations. This feature remove all unneeded files.
Create a new configuration (see Section 5.2, “Creating model documentation using the graphical user interface”).
Remove a configuration (add configuration not yet implemented).
Actual configuration managed.
Because of all parameters that needs to be provides, are heavy to setup, a configurator enables to keep different sets of parameters in a same configuration file.
For creating a new configuration, just type its name and tune all parameters. For using one, just select it. For deleting one, use the right button, down the configurator menu.
See the HTML generated
See the PDF generated
View full log result as text file ... in your favorite textpad viewer.
Launch the generation, regarding to parameter sets.
Generates java help files.
In debug mode, enables to see the generated debug log file.
Enable, as soon as there are a lot of objects to rename, to make this by program (see Section 6.3, “Renaming elements”). Provide the name of the file explaining what to rename.
Run the renaming features.
For huge and heavy schemas, using the area map clicks generated for HTML may really be time consuming. This option enable to manage this.
One may test the tool using the sample documentation provided within : SchemaDoc_ENV_HOME/sample.
All documentations will be generated within the inner out directory.
This tool enables to manage different configurations that are called and set using (16, 17 and 18 items) in Figure 6, “Main user interface of sdOutput”. All this information is stored in the $SchemaDoc_env_home/data/config.xml file that may be edited by hand if needed. Here are the different definition needed.
— Top level of a parameter file
High level of a Tirème configuration file. Nothing specific is packaged here for SchemaDoc environment.
— A specific configuration designated by it name attribute
Because there may be a lot of information to store for one generation, SchemaDoc allows to store as many configurations as needed.
Each individual configuration is stored using this element and its name is defined in the local name attribute. The selected local attribute is used by the program
in order to remember which was the last configuration selected.
— Named section of parameters
In the model, there may be as many section on parameters within a specific configuration. Nevertheless, in SchemaDoc, only one is used always calles "general". A section contains
all needed parameters.
— Specific parameter using type and value
All needed parameter are defined here using a simple type/value model. The type is provided as an attribute ; the value is defins as the element contents.
Here are the different values used by SchemaDoc :
Values defined also using the GUI (Only a reference to the mark item on figure Figure 6, “Main user interface of sdOutput” is provided):
lastImgOpenned: see item 8
FilelastOpennedFile: see item 9
repOut: see item 10
repDTD: see item 11
schemaFile: see item 12
modelDef: see item 1
html: see item 2
missing: see item 5
FO: see item 3
useSpy: see item 7
dtd: see item 6
javahelp: see item 23
removeSpyNotNeededImages: see item 15
Values not defined also using the GUI :
It is possible to use graphics generated by XML Spy in its HTML documentation. In order to use these graphic files, the needed option should be clicked in the SchemaDoc interface and a source path should also be provided to a special XML wrapper file described here.
XML Spy generates a file per all Schema called within a main Schema. Therefore, if the documentation concerns a sole Schema, one file is needed. If the documentation concerns different main Schemas, different XML Spy files are needed.
In all cases, there is a need for a wrapper of all documentations generated. This wrapper will call one or many different XML Spy generated files. This wrapper also solves some parsing problems of the information generated by XML Spy ; reason why it is needed even in the case of a sole XML Spy documentation.
The wrapper looks like :
<?xml version="1.0" encoding="UTF-8"?>
The encoding is important, regarding at what encoding is used by XML Spy.
<!DOCTYPE spydoc:allhtml [ <!ENTITY nbsp "#xa0">
<!-- nbsp defines the entity often used by XML Spy and never declared. -->
<!ENTITY massSchemaBase SYSTEM "xmlspy_massSchemaBase.html">
<!ENTITY massSchemaSave SYSTEM "xmlspy_massSchemaSave.html">
<!-- List of all needed documentation generated by XMLSpy. -->
]>
<spydoc:allhtml>
<spydoc:oneSpyHTML id="masSchemaBase">&massSchemaBase;</spydoc:oneSpyHTML>
<!-- Call to all individual documentation. The id information is not used for now. It should be the same as the one defined within the Schema. --><spydoc:oneSpyHTML id="massSchemaSave">&massSchemaSave;</spydoc:oneSpyHTML>
</spydoc:allhtml>
The generation program is using all information provided by the HTML Spy documentation. In doing that, it is also using the defined path to schema documented.
In the example, Spy provide the information that the schema location is under T:\mutu-xml\bin\SchemaDoc\models\schemas\SchemaDocObjects.xsd in order to convert this path to a
Linux one, some information needs to be added to the configuration file, providing a mapping between the UNIX graphics installation path and the Windows one. This is made with the two parameter
entries of the configuration file called UnixSpyPathEquiv and DOSSpyPathEquiv.
<parameters>
<config name="shemaDoc sample" selected="true">
<section type="general">
<param type="lastImgOpennedFile">/usr/local/projets/SchemaDoc/sample/out/SchemaDoc/docWrapper.xml</param>
<param type="lastOpennedFile">/usr/local/projets/SchemaDoc/sample/doc.xml</param>
<param type="repOut">/usr/local/projets/SchemaDoc/sample/out</param>
<param type="repDTD">/usr/local/projets/SchemaDoc/sample/DTD</param>
<param type="schemaFile">/usr/local/projets/scheamdoc/sample/sample.xsd</param>
<param type="modelDef">true</param>
<param type="html">true</param>
<param type="missing">false</param>
<param type="FO">false</param>
<param type="useSpy">true</param>
<param type="dtd">false</param>
<param type="UNIXSpyPathEquiv">/usr/local/projets/SchemaDoc</param><param type="DOSSpyPathEquiv">T:\mutu-xml\bin\SchemaDoc</param><param type="javahelp">false</param>
<param type="removeSpyNotNeededImages">false</param>
</section>
</config>
</parameters>
For example, there is defined that as soon as a Windows path is using T:\mutu-xml\bin\SchemaDoc, it needs to be substituted with /usr/local/projets/SchemaDoc.
For being able to understand the format assumed by the program, a model has been made.
— Top level element enabling to concatenate different XML Spy HTML documentation
Top level element declaring all documentations generated by XML Spy that need to be browsed in order to find all images needed.
— One XML Spy HTML documentation
One documentation file generated by XMLSpy. Note that included or redefined model may be present within different documentation models XMLSpy outputs ... this is managed by the actual program.
Attributes and attr. groups
An identifier actually not managed. It is a good practice to put here the id of the Schema from wich the documentation is generated.
Not used for now. Will enable to know which object is referenced as soon as the same object is defined twice, or more, within different XMLSpy documentations.
In order to generate a documentation, it is necessary to open the Schema in XML Spy. Once selected, choose the "Generate documentation" of the "Schema settings" menu. A user interface is opened which looks like :
The minimum needed features are defined in the graphics: it need to be an HTML documentation, with, at least, diagrams and namespaces plus the index where all information is taken from.
Because the generated file contains a lot of HTML tags, it is a good thing to un-select all non needed items. In the reverse case, the file becomes big and it slows down the generation process. Sometimes, it bugs all the process, because of memory limitations.
In this mind, local attribute and element generation should be avoided if using XMLSpy 2007 SP3 and higher.
The information taken from the Spy documentation is internalized within a SchemaDoc model defined here. When working in debug mode, this information file is provided in the output directory.
— All objects contained within an xsd file which are linked to a graphic
A unique graphic set corresponding to an XML Schema file. Attributes enables to identify the file and its ID.
— One Object and all its information for link within SchemaDoc IDs references
All objects having an image in XML Spy documentation are provided here. The element provides within a set of attributes image information SPY and SchemaDoc ID mechanism.
— The map of hyperlinks extracted from the documentation
Also documents gr:area
Contained HTML map when it exist; used for hyper link purpose. This element contains all defined gr:area
Area HTML element where the href attribute is modified for being part of the SchemaDoc ID mechanism and where information is added for being able to manage the alt area attribute later on.
This tool enable to rename a set of schema objects defined in the documentation and/or in the different managed schemas. As an entry, it takes an XML document according to repl:replacements object. As an output, it generates all replaced files, in a temporary directory for being sure not to override the input files. The temporary directory is called temp and is created in the directory containing the main XML documentation file.
The output is a set of file representing either sect1, articleinfo or xs:schema objects. It is the responsibility of the user to assemble them in the right directories structure.
— Defines all replacements
Also documents repl:replace
repl:replace is an EMPTY object and only its two attributes needs to be declared. If your documentation is using namespaces, be sure to use declared prefix defined in one sd:nsDecl of your documentation.
 |  |  |
| 5. Creating documentation for a new model | 7. Reference manual : document model |
