This document describes the files and process used to generate techniques documents developed by the i18n GEO task force. NOTE: this is all subject to change.
The 'base' directory for this discussion is /International/geo/html-tech/.
There are currently three types of file to be edited.
Information relating to a particular technique in a view will be identified in the view's source by a placeholder, or technique-include statement, that simply points to that technique in the repository. It is the publishing process that actually inserts the appropriate content from the technique description in the repository. The content of the view is therefore largely limited to headings, introductory paragraphs, cross-references and technique-include statements.
We currently only have one file of each type.
Any editing of xml files must always be done with a validating editor. Invalid or not well-formed xml must never be uploaded.
This type of file gathers techniques related to a specific technique. Currently we only have one such file, specific to (X)HTML techniques. (Note that all information related to a particular technique should be added to the repository, not directly into the view document.)
To make changes, edit the file html-tech.xml.
Any images should be stored in the images directory.
This file is an entity referenced by the repository. Each reference has an id that must match the idrefs in the repository.
There are currently two special entries:
This file gathers and merges information from various databases for presentation to the user as a single document. Currently we only have one such file. Use the include element to indicate where information related to a technique should go.
To make changes, edit the file html-authoring.xml.
The lowest common denominator is a repository plus the refs.xml file (which is included as an entity).
XSLT is used to create a full view from one or more repositories. Information about which repositories are sourced by a view is contained only in the include elements of a particular view.
XSLT is also used to create an outline view and a resources view from a full view. The outline presents only some of the information in the full view, and presents it in a different arrangement. The resources view presents only the resource information. (All views are linked together for the user through hyperlinks.) The end-results and the processing files (XSLT) to create these views are located in the outline directory.
To publish this file use build-html-tech.bat on a Windows platform.
The publishing process will produce the xhtml file html-tech.html that should be uploaded to the web site.
Don't forget to upload any new or modified images stored in the images directory.
To publish this file use build-html-auth.bat on a Windows platform.
The publishing process will produce the xhtml file html-authoring.html that should be uploaded to the web site.
To publish these files use outline/build-html-outline.bat and outline/build-html-resource.bat on a Windows platform.
The publishing process will produce the xhtml files outline/html-authoring-outline.html and outline/html-authoring-resource.html that should be uploaded to the web site.
The dtd is xmlspec-tech.dtd, which is derived from a version of xmlspec. See the documentation. This dtd is used for all xml files.
The following file is useful only if you are editing in XMetal.
When XMetal starts up it will generate additional files in the directory on your hard drive. These will typically include xmlspec-tech.ctm, xmlspec-tech.rlx and xmlspec-tech.tbr. (Tip: if you change the dtd you should close XMetal, delete the lc.rlx file, then reopen the lc.xml file in XMetal to ensure the rules are updated in the editing environment.)
Each html file for uploading is generated by an XSLT file, as follows.
To follow the publishing process outlined here, you will need a copy of MSXSL.EXE in the main directory, and you will have to have installed msxml4 or above.
documentation/documentation-build.html: This file.
For an overview of the xmlspec dtd see http://people.w3.org/rishida/xmlspec-guide.html. This is a version of the original documentation that I have slightly re-styled to aid readability. I also made it possible to jump back to the toc by clicking on most headers. Xmlspec, once you get past the meta data at the top of the document, allows for a very free reign in terms of structure. The most important reference material in the documentation is section 7's tables, which I have augmented with the names of most of the elements that each entity across the top contains. You should also read the notes for techniques related additions to the spec in documentation/documentation-dtd.html.
documentation/xml-spec-dtd.html: summarises the dtd with elements, attributes and entities listed in order in which they are defined
documentation/xml-spec-dtd-alpha.html: summarises the above in alphabetic order.