Re: SGML declarations for subdocuments

[Norman Gray <norman@xxxxxxxxxxxxxxx>]

Greetings, 

Matthias Clasen <clasen@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx> wrote, in
response to a question of mine:

> > I'm using Jade to process documents which conform to a DTD which uses
> > an SGML declaration which has NAMECASE GENERAL NO, and which has
> > subdocuments.  The NAMECASE declaration seems not to apply to the
> > subdocuments, though I thought it would, since subdocuments may not
> > have their own SGML declaration, and must instead use the same
> > declaration as their parent.
> 
> This restriction applies (unless you use the annex K extensions which
> are not - yet - fully implemented in SP) to references to subdoc entities
> which are resolved by the SGML parser. But your example below uses
> subdoc entities in attribute values. Those are ignored by the parser;
> it is the applications task to resolve them. Your style sheet does
> that using sgml-parse. But this is not the same as parsing the entity
> as a subdocument of the current document, it simply parses the entity
> as an sgml document, using the default SGML declaration which has
> NAMECASE GENERAL YES.

Many thanks: this was a significant misunderstanding on my part.  It
simply hadn't occurred to me that subdoc entities could be used like
other external entities, and (so?) I didn't realise that DSSSL's
(sgml-parse) function was a completely independent parse.

This left me with the problem of how to resolve my case, and I'll
describe this briefly here, in case anyone else finds themself in a
similar situation (or can suggest anything better).

Using SGMLDECL in the catalog doesn't work (all this is described on
the SP pages[1], as well as the Oasis Technical Resolution on
catalogs[2]).  That means that _everything_ is read using that SGML
declaration, including things which shouldn't be.  This seems to
confound Jade's DSSSL processing.  SGMLDECL in a delegated catalog has
no effect.

Using DTDDECL seemed a good idea, but SP seems not to support it.

I thought of trying to get Jade to resolve a public-id for the
declaration, but realised that Jade doesn't have direct access to the
entity manager (in the sense of being able to ask `which system-id does
this public-id map to?'), but can only do that via entities, and the
only places where you can define entities are in the document and the
DTD (the ENTITY declaration in the catalog is for overriding declared
entities, not declaring new ones, as far as I understand it).

What I've done, therefore, is to define an entity in the document's
DTD which refers to the declaration via a public-id, and have Jade
resolve this using (entity-generated-system-id).  In the simple
example, I therefore have:

% cat simple.dtd
<!ELEMENT simple O O (a|xref)+>
<!ELEMENT a      - O EMPTY>
<!ELEMENT xref   - O EMPTY>
<!ATTLIST a
        name NAME #REQUIRED
        >
<!ATTLIST xref
        doc ENTITY #REQUIRED
        >
<!ENTITY my-decl SYSTEM '/home/norman/s/src/sgml/w/sgml/dtd/starlink.decl'>
% cat simple.dsl
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN">

(define (document-element #!optional (node (current-node)))
  (node-property 'document-element node default: (empty-node-list)))

(define (normalize str)
  (if (string? str)
      (general-name-normalize str (current-node))
      str))

(element a
  (let ((name (attribute-string (normalize "name") (current-node))))
    (literal (string-append "name=" name))))

(element xref
  (let* ((xrefent (attribute-string (normalize "doc") (current-node))))
    (process-node-list
     (document-element (sgml-parse (string-append
                                    (entity-generated-system-id "my-decl")
                                    (entity-generated-system-id xrefent)))))))

And this works.  The crucial thing was to recall that a `system
identifier' is actually composed of a sequence of `storage object
specifications', which are concatenated.

It seems slightly odd -- incestuous even! -- for the DTD to be
declaring an entity for its own declaration.  It's also unappealing that it
should be doing so merely to support a down-converter, since the
entity is never referenced elsewhere in the DTD or in any document
conforming to it.  It's not obvious, however, how to do better.

By the way, Eliot Kimber has an illuminating article on SUBDOCs (which
deprecates the notion of simply including them in documents) at [3].

I hope this is of some help to anyone else in this situation.

All the best,

Norman


[1] http://www.jclark.com/sp/catalog.htm
[2] http://www.oasis-open.org/html/a401.htm
[3] http://www.isogen.com/papers/subdoc.html

---------------------------------------------------------------------------
Norman Gray                        http://www.astro.gla.ac.uk/users/norman/
Physics and Astronomy, University of Glasgow, UK     norman@xxxxxxxxxxxxxxx


 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist