XMLspec ADEPT application

[From:  http://www.w3.org/XML/1998/06/xmlspec-v20.zip, 1999-07-24]
Readme for the XMLspec ADEPT application
(instructions for Windows)

12 July 1999
Eve Maler (elm@arbortext.com, +1 781 529 1012)
with contributions from Paul Grosso

                        *               *               *

DISTRIBUTION CONTENTS

This distribution consists of a zip archive containing the following files:

catalog
  SGML Open/OASIS catalog entry file

pubrc
  Initialization file for the editing environment

readme.txt
  The file you are reading

packages/spec2html.cmd
packages/spec2html.tbl
  HTML conversion facility implemented in ADEPT Command Language

template.xml
  Template document conforming to XMLspec

xmlspec.atd
  "Auxiliary tag data" file that customizes the editing environment
  (please note that this has not been updated yet to reflect changes
  from the 1998-12-3 version to Version 2.0; it should still work fine)

xmlspec.dcl
  XML-friendly SGML declaration for use by ADEPT

xmlspec.dtd
  XMLspec DTD, Version 2.0

xmlspec.fos
  FOSI stylesheet for XMLspec (please note that this has not been
  updated yet to reflect changes from the 1998-12-3 version to
  Version 2.0; it should still work fine)

                        *               *               *

INSTRUCTIONS FOR INSTALLATION AND SETUP

To set up the XMLspec application:

1. If you don't already have such a directory set up, create a
directory that will be dedicated to user-installed ADEPT
applications, such as c:\myadept (the path that these intructions
will assume), and within it, create a subdirectory called doctypes.
Finally, within the doctypes subdirectory, create a subdirectory
call xmlspec.

2. Unpack this archive into the newly created xmlspec subdirectory,
retaining the internal directory structure of the archive, so that
you end up with c:\myadept\doctypes\xmlspec and
c:\myadept\doctypes\xmlspec\packages.

3. If you don't already have a catalog file in this doctypes
directory (e.g., because you just created it in step 1 above),
move the catalog file in the xmlspec directory up one level so
that it is in the doctypes directory.  If you already have a
catalog file in the doctypes directory (because you skipped step 1
above because you had previously set up such a directory), then
merge the line in the catalog file in the xmlspec directory
into the existing catalog file in the doctypes directory.

4. In ADEPT, choose Options->Preferences... and the File tab.  At the
beginning of the Catalog Path field, add c:\myadept\doctypes followed by
a semicolon if it is not already listed.  Also ensure that the Window tab
has the Command Line box checked.  Check the Save Current Settings as
Preferences box at the bottom, and click on Update Current Settings.

5. Edit the c:\myadept\doctypes\xmlspec\pubrc file with a regular text
editor (or ADEPT itself).  On line 251 of that file (second-to-last line),
there is a hardcoded reference to the pathname of the packages directory;
edit that reference to match the actual location on your system.

6. Type the following command at the ADEPT command line (with the actual
directory where the xmlspec.dtd file resides substituted for this sample):

  compile_doctype -toptag spec c:\myadept\doctypes\xmlspec

Click OK in the response panel that appears.

7. To create a new XMLspec-compliant document, make a copy of
the c:\myadept\doctypes\xmlspec\template.xml to whatever directory
you wish (preferably, *not* in the \myadept tree) giving it whatever
name you wish.  You can then Open that file in Adept.

8. If you have an existing XMLspec-compliant document that you wish to
use with ADEPT, ensure that the public identifier in its DOCTYPE declaration
matches the entry in the catalog file, that is:

  -//W3C//DTD Specification V2.0//EN



To take advantage of the *optional*, unsupported HTML conversion facility
included with this distribution:

1. Edit the c:\myadept\doctypes\xmlspec\packages\spec2html.cmd
file with a regular text editor (or ADEPT itself).  On line 41 of that file,
there is a hardcoded reference to the pathname of the spec2html.tbl file;
edit that reference to match the actual location on your system (for example,
c:\myadept\doctypes\xmlspec\packages\spec2html.tbl).  If you have Adept
currently open, exit out of it and restart it before continuing to ensure
it loads the updated version of this file.

2. To convert the template.xml file, type the following command on the ADEPT
command line:

  gen_html

A file with the same base name but with a ".htm" extension should be
generated in the same directory as the .xml file.  If you wish to see
this in Adept, you can use the Open menu choice to open the .htm file.

3. The following character entity references get generated by Adept
automatically:  &ldquol, &rdquo;, &mdash, and &ndash;.  Since these
do not view properly in many browsers, after generating the HTML,
you may wish to bring it up in Adept and use the "Tools -> HTML ->
Fix character entities for browsers" menu choice to convert these
into ", ", --, and - respectively; finish by using the then "File ->
Save for HTML browsers" menu choice to ensure no PIs are saved in
the file.

                        *               *               *

KNOWN BUGS IN THE HTML CONVERSION FACILITY

1.  XMLspec allows ulist, olist, glist, and eg either
    between p's or within p's.

    However, since, in HTML, ul, ol, dl, and pre are only
    allowed between p's (but not within one), and since this
    package doesn't do any fancy rearranging, if a valid HTML
    document is to be generated, the author of the xmlspec
    document must ensure that all ulist, olist, glist, and
    eg elements are not nested within a p element.

2.  The specref element isn't fully implemented per the
    processing expectations in the XMLspec documentation.

3.  I'm sure there are a variety of other elements not
    handled properly.  Send comments to pgrosso@arbortext.com.

4.  If the HTML document is open and you try to run gen_html,
    you'll get an error that ADEPT can't access it.  You need
    to close (exit) out of the HTML document first.

                        *               *               *

TROUBLESHOOTING

If you need help, contact Eve Maler (elm@arbortext.com, +1 781 529 1012).
The licenses provided with your ADEPT software will expire after one year;
if you need a renewal in order to continue working on W3C specifications,
contact Eve.

You can find online versions of the DTD and its documentation at:

  http://www.w3.org/XML/1998/06/xmlspec-v20.dtd (V2.0 DTD)
  http://www.w3.org/XML/1998/06/xmlspec.dtd  (latest DTD)
  http://www.w3.org/XML/1998/06/xmlspec-report-v20.dtd (V2.0 report)
  http://www.w3.org/XML/1998/06/xmlspec-report.dtd (latest report)

Enjoy!