Re: Including source files

["W. Eliot Kimber" <eliot@xxxxxxxxxx>]

Thomas G. Lockhart wrote:
> 
> > > 1) Is it possible to "include" source files from another source
> file
> > > which has itself been included?
> >
> > Yes, you can include entities inside other entities.
> 
> Uh, how? I'm sure I've got the syntax wrong, but could use an example:
> 
> golem> cat man/manpages.sgml
> <!entity manrefs system "refs.sgml">

Yes, if you are using external text entities, then all the entity
declarations go in the DOCTYPE declaration of the root document. An
external text entity (the sort declared in the example above) is just
like an internal entity except that its replacement text is in an
external file.  That means that it's essentially a macro that gets
expanded--it has no meaningful separate existence outside the context of
the document that declares it.  Thus, it doesn't have its own DOCTYPE
declaration and therefore can't declare it's own entities.

However, SGML does provide a mechanism that gives you what you were
expecting: subdocuments.  A subdocument entity is an external entity
that is syntactically a complete document but that is intended to be a
component of a larger logical document.  Subdocuments are parsed
independently of the document that declares them but can be processed as
part of the processing of the larger document (remembering that parsing
and processing are two separate stages).

You can do this in DSSSL (with one limitation). For example, I use this
technique to manage the materials for my HyTime course (and for my
HyTime book).  A simple example would be:

<!DOCTYPE MyDoc SYSTEM "mydoc.dtd" 
 [
  <!ENTITY subdoc1 SYSTEM "subdoc1.sgml" SUBDOC >
  <!ELEMENT ChapterRef - O EMPTY >
  <!ATTLIST ChapterRef -- Reference to Chapter subdocs
                          to create "compound documents" --
      subdoc  ENTITY #REQUIRED
      reftype CDATA  #FIXED "subdoc Chapter"
       -- Limit the subdoc attribute to references to Chapter 
          elements. Reftype is a facility of ISO/IEC 10744:1997 --
  >
 ]
>
<MyDoc>
 <ChapterRef subdoc=subdoc1>
</MyDoc>

<!-- Subdoc1.sgml: -->
<!DOCTYPE Chapter SYSTEM "mydoc.dtd" [
  <!ENTITY subdoc2 SYSTEM "subdoc2.sgml" SUBDOC >
]> 
<Chapter>
 <SectionRef subdoc=subdoc2>
</Chapter>

These three documents (I leave subdoc2 as an exercise to the reader)
form a compound document with this structure:

MyDoc.sgml  
 '---subdoc1.sgml
      '---subdoc2.sgml

In DSSSL, you handle the subdocument reference using the sgml-parse
function:

(element (ChapterRef)
  (process-node-list
    (sgml-parse 
     (entity-system-id 
       (attribute-string "subdoc" (current-node))
       (current-node))
     parent: (current-node))))

The only limitation I've found with this is that functions that process
the subdocument can't "look up" past the reference to examine the
context in which they're referenced.  In discussing this with James, he
seemed to agree that this was a design bug in DSSSL that should be
addressed.  There may be a clever way around it, but I haven't taken the
time to try to figure it out.

The only other limitation is that if the starting document was processed
with respect to an architecture, there is no way to convey that to the
sgml-parse function :-(.

You can get more information on using subdocs with DSSSL and Jade at
"http://www.isogen.com/demos/dovalueref.html";. This provides sample
DSSSL code more complete than the above example.

Note that in XML, the official equivalent of subdoc references will
almost certainly be simple links with a show value of "embed", which
expresses the same "use-by-reference" semantic that subdoc references
do.  Note also that the use of subdoc entities is not strictly required
for the above--you could also use NDATA or CDATA entities with a
notation of SGML, e.g.:

<!NOTATION SGML public "ISO 8879:1986//NOTATION Standard Generalized
Markup Language//EN" >
<!ENTITY otherdoc1 SYSTEM "otherdoc1.sgml" CDATA SGML >

A SUBDOC entity is just a special case of CDATA SGML entity that SGML
provides out of the box.  Thus, with XML, which doesn't provide subdoc
entities, you could still do the above example with CDATA (or NDATA)
SGML entities.

Cheers,

Eliot


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