The Unoptimized SGML-Bundle Relations Schema
From: http://www.wco.com/~books/draft.5feb97.txt (Feb 09, 1997)

The Unoptimized SGML-Bundle Relations Schema

Terry Allen (tallen@fsc.fujitsu.com)

Version 3, 5 Feb 97

& header;

& boilerplate;

[If this were an Internet Draft it would begin with a page
or so of information everyone already knows anyway.]

This document defines a schema for use 
in a multipart/related MIME 
message (MR), as defined in RFC 1872.  Somehow it ought
to be possible to express it in Ron's application/relations
format, but I haven't figured out how yet.

The Unoptimized SGML-Bundle schema (USB) is intended to 
describe the relations among *all* the necessary parts of a 
complex SGML document, along with necessary related 
entities, as they might be packed in a MIME message.  It is 
called "Unoptimized" because
it is an exercise is to determine what all these
parts are; any practical implementation would probably be 
much less verbose and possible less restrictive.  
This schema is deliberately prescriptive, to further
the goal of the exercise.  

Several DTDs are defined for use within certain Parts of
a USB MIME message and for storing information in a 
structure that can be used by a MIME packing engine to
create a USB MIME message.  Don't take these DTDs seriously.
They are placeholders for more optimized syntaxes.
Several liberties have been taken with FPIs and the 
Docbook DTD for purposes of illustration.  

Readers of this document are encouraged to comment on
its use of MIME and on whether the information
it requires in a MIME message is sufficient to parse
and render a complex SGML document.  Suggestions for
optimization will be filed for future reference.

This schema may be compared to Donald Stinchfield's 
expired Internet Draft, "Using Catalogs and MIME to 
Exchange SGML Documents," written for the moribund
IETF MIMESGML Working Group.  That document required
the use of SGML Open catalogues.  This document defines
requirements most of which could be met with SGML
Open catalogues, but does not employ them directly.
(Catalogues may be included within a USB MIME message,
and this document takes no position on whether catalogues
are a good thing or not.)  

A MIME message that employs the USB schema encapsulates a 
single SGML document, called here the "main document," or MD, although that MD may be arbitrarily complex and may have 
SUBDOCs.

A Multipart/Related MIME message must have a Type parameter 
(per RFC 1872), which is a media type/subtype.  For now I
have made this "Unoptimized SGML-Bundle," but I suspect
this may be the wrong approach.  Within the message I use
application/SGML (RFC 1874) in preference to text/SGML,
because SGML documents are readable by humans only 
sometimes.  I omit the application/SGML,
optional parameters SGML-bctf and SGML-boot, and 
I take the application/SGML optional
"charset" parameter to describe the character encoding
of ROOT-SDECL (see below).  

I have deliberately evaded dealing with issues of encoding 
of character sets, and I have not (yet) provided a way
for pointing to the SGML declarations of documents 
other than ROOT.

A USB MR message consists of the following required Parts
(the capitalized string before the colon is a USB Part Name):

 - MIMEMAP:  list that maps MIME Content-IDs to URNs of 
     Parts.  The Parts may refer to each other by URN, not
     by Content-ID, so that they need not be rewritten when
     packed in a MIME Multipart/Related message.  This list 
     must be marked up using the USB-Package DTD, see below, 
     and apparently must be created by the MIME packer.  
     This Part's mapping allows URNs to be used without 
     requiring external resolution.

 - ROOT-SDECL:  SGML declaration for the root entity.
	This describes the character repertoire of the ROOT.
     This part either begins with "<!SGML", in which case
     it is the actual SGML declaration, or contains a URN
     or URL, or is empty.  If empty, the RCS is used.
	
 - ROOT:  root SGML entity of the MD.  Along with 
     ROOT-SDECL, this contains all the information
	needed to start parsing (though not necessarily to    
     finish rendering).

 - MD-META:  bibliographic metadata for the MD.  No format 
     specified

 - MD-INTPROP:  intellectual property information for the 
     MD.  It is called out so that it can be recognized by 
     convention.

 - ALLENTS:  list of all text entities that compose the MD.
     This does not include DTDs or ISO 8879 character entity
     sets, although perhaps it should. 	This list must be 
     marked up in USB-Package DTD format, see below, and 
     supplies a concept missing in SGML and HyTime.  When 
     the application has collected all these entities it has 
     all of the MD and should not traverse any links located 
     within the MD in order to gather more entities.

 - STARTPARSE:  list of all entities required to start 
     parsing ROOT.  This list must be marked up in 
     USB-Package DTD format, see below, and provides a 
     shortcut alternative to examining ROOT for its DOCTYPE 
     declaration and internal subset, then obtaining the DTD 
     referred to by the DOCTYPE declaration.  It does not 
     supersede the DOCTYPE declaration.  If its contents
     differ from the DOCTYPE declaration they are wrong.

 - ALLOPTS:  list of all optional parts, with their Optional 
     Part Names.  This list must be marked up in 
     USB-Package DTD format, see below.  The contents of 
     this list attach semantics to the (otherwise unknown) 
     Optional Part Names.  If the list is empty, the start- 
     and end-tags of the USB-Package DTD should be supplied.

A USB MR message may also contain the following Optional Parts:

 - SOCAT:  SGML Open catalogue(s).  If more than one, 
     something further may be required, dunno.

 - STYLESHEET:  style sheet(s).  If more than one, ditto

 - REQENTS:  list of all Parts that must be processed for 
     presentation.  Use of this list, which must be marked 
     up in package.dtd, see below, guards against partial 
     presentation of a mutilated document.  Some of the XML 
     folks think parsers and applications should
	be allowed to drop content on the floor.  If you don't 
     agree, supply REQENTS.  In place of a list of Parts, 
     the content of REQENTS may be the exact string "ALL" 
     (without the quotes).

 - URNHINTS:  URN resolution hints.  Format to be determined 
     by further URN work.  

 - DTD:  DTDs.
	
 - SGML-ENTITY:  SGML entity files of all kinds.

 - SUBDOC:  SUBDOCs.  Each SUBDOC must be treated like an 
     MD, so a USB message including SUBDOCs is recursive.

 - PACKAGE-SDECL:  SGML declaration for package.dtd (if not 
     the RCS).

 - MORE-APPINFO:  APPINFO expansions.  SGML declarations may 
     have APPINFO parameters, the format of which is 
     unspecified by ISO 8879.  For USB use, these parameters
	should point to these expansions by URN; the expansions 
     themselves may be prose or executables, such as 
     setup.exe files.

 - [OTHER]:  the list is extensible; novel Parts should be 
     given Optional Part Names in ALLOPTS.

The USB-Package DTD is supplied in an appendix.  It wraps a 
list of USB Parts, identified by USB Part Name, and for each 
of them provides the URN of that Part and a URN or URL 
identifying the semantics of that Part with respect to the MD.  TODO:  describe what else it does.

Provision has been made for URLs and well as URNs, because the URNs of choice for SGML are FPIs, 
and FPIs cannot apparently point to fragments of entities.  

URNs for entities composing complex SGML documents may be 
stored in the storage.dtd DTD (suuplied in an appendix), 
which describes the structure of a USB.  Use of the 
storage.dtd DTD is entirely optional.


Appendix:  A Complex Document Packed with the Unoptimized 
SGML-Bundle Relations Schema for MIME

The complex document is marked up
in the Complex DTD, which is included in this
message.  It points to two other documents, which
are also included.   The Complex DTD is not strictly
relevant to the USB schema, but it is an 
illustration of what is necessary to associate
annotations with a main text; the annotations
and the main text use the HTML 2.0 and Docbook 3.0
DTDs, which are not included, on the possibly bogus
assumption that they are well known and can be 
obtained by means of their FPIs if need be.

For sanity, FPI URNs are not percent-encoded.  Please
pretend that they are.  Nearly all of these URNs are
imaginary.

Certain semantics for SGML entities are assumed
to be well known (DOCENTITY is a placeholder for more
exact SGML terminology).  Imaginary URNs for them are:

SDECL (SGML declaration)        urn:burble:sdecl
DTD                             urn:burble:dtd
DOCENTITY                       urn:burble:docentity

Commentary within square brackets is not part of the
MIME message.


BEGIN EXAMPLE

Content-Type: Multipart/Related; boundary=cuthere
   start="where-the-mimemap-is";
   type="Unoptimized SGML-Bundle"

--cuthere  
      [docbook.dcl has no FPI, so a URL is used]
Content-Type:Application/SGML
Content-Description:MIMEMAP
Content-ID:where-the-mimemap-is

<packlist>
<partname>MIMEMAP
</partname>

<cidpair
itemurn="NULL" 
itemurl="http://www.ora.com/davenport/docbook/docbook.dcl"
cidofitem="where-the-root-sdecl-is">

<cidpair
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT complex-doc//EN"
itemurl="NULL"
cidofitem="where-the-root-is">

<cidpair
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT underlying.meta//EN"
itemurl="NULL"
cidofitem="where-the-meta-is">

<cidpair
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT underlying.intprop//EN"
itemurl="NULL"
cidofitem="where-the-intprop-is">

<cidpair
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT underlying.allents//EN"
itemurl="NULL"
cidofitem="where-allents-is">

<cidpair
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT underlying.startparse//EN"
itemurl="NULL"
cidofitem="where-the-startparse-is">

<cidpair
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT underlying.allopts//EN"
itemurl="NULL"
cidofitem="where-the-allopts-is">

<cidpair
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT underlying//EN" 
itemurl="NULL"
cidofitem="underlying.html-is-here">

<cidpair
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT annoset//EN"
itemurl="NULL"
cidofitem="annoset.sgm-is-here">

<cidpair
itemurn="urn:fpi:-//Palm Tree Books//DTD Complex DTD v0.1//EN"
itemurl="NULL"
cidofitem="complex.dtd-is-here">

</packlist>

--cuthere
      [docbook.dcl has no FPI, so a URL is used.  It is 
       necessary for parsing but is considered well known,
       so is not supplied.]
Content-Type:Application/SGML
Content-Description:ROOT-SDECL
Content-ID:where-the-root-sdecl-is

url:http://www.ora.com/davenport/docbook/docbook.dcl

--cuthere
      [This is the document that relates the annotations
       to the underlying document.]
Content-Type:Application/SGML
Content-Description:ROOT
Content-ID:where-the-root-is

<!doctype complex public 
"-//Palm Tree Books//DTD Complex DTD v0.1//EN">
<complex>
<title>Complex Enough?</title>
<iset display="overlay"
location="urn:fpi:-//Palm Tree Books//DOCUMENT annoset//EN">
<core location="urn:fpi:-//Palm Tree Books//DOCUMENT underlying//EN">
</complex>

--cuthere
      [I use Docbook here only for convenience; should find 
       another format.]
Content-Type:Application/SGML
Content-Description:MD-META
Content-ID:where-the-meta-is

<!doctype docinfo public "-//Davenport//DTD DocBook V3.0//EN">
<docinfo>
<title>Complex Enough?</title>
<author>Terry Allen</author>
</docinfo>

--cuthere
      [This is a section which it could be required that
       defined applications honor.  Again, Docbook used,
       and in fact misused, only for convenience.]
Content-Type:Application/SGML
Content-Description:MD-INTPROP
Content-ID:where-the-intprop-is

<!doctype legalnotice public "-//Davenport//DTD DocBook V3.0//EN">
<legalnotice>
<para>This document is copyright Palm Tree Books, 1997, and 
is offered as is.</para>
</legalnotice>

--cuthere
      [All the text entities that compose the main document,
       *not* all the entities in the MIME message.  A style
       sheet would not be listed here.]
Content-Type:Application/SGML
Content-Description:ALLENTS
Content-ID:where-allents-is

<!doctype packlist public "-//Palm Tree Books//DTD USB-Package v0.1//EN">

<packlist>
<partname>ALLENTS
</partname>

<an-entity
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT complex-doc//EN" 
itemurl="NULL">

<an-entity
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT underlying//EN" 
itemurl="NULL">

<an-entity
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT annoset//EN" 
itemurl="NULL">

</packlist>

--cuthere
      [Only what is required to *start* parsing.]
Content-Type:Application/SGML
Content-Description:STARTPARSE
Content-ID:where-the-startparse-is

<packlist>
<partname>STARTPARSE
</partname>

<urnpair
semanticurn="urn:burble:sdecl"
itemurn="NULL"
itemurl="http://www.ora.com/davenport/docbook/docbook.dcl">

<urnpair
semanticurn="urn:burble:dtd"
itemurn="urn:fpi:-//Palm Tree Books//DTD Complex DTD v0.1//EN"
itemurl="NULL">

<urnpair
semanticurn="urn:burble:docentity"
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT complex-doc//EN" 
itemurl="NULL">

</packlist>

--cuthere
      [The required Parts are known; this completes the
       list of actually supplied Parts.]
Content-Type:Application/SGML
Content-Description:ALLOPTS
Content-ID:where-the-allopts-is

<packlist>
<partname>ALLOPTS
</partname>

<urnpair
semanticurn="urn:burble:dtd"
itemurn="urn:fpi:-//Palm Tree Books//DTD Complex DTD v0.1//EN"
itemurl="NULL">

<cidpair
itemurn="NULL" 
itemurl="urn:fpi:-//Palm Tree Books//DOCUMENT underlying//EN"
cidofitem="underlying.html-is-here">

<cidpair
itemurn="urn:fpi:-//Palm Tree Books//DOCUMENT annoset//EN"
itemurl="NULL"
cidofitem="annoset.sgm-is-here">

</packlist>

--cuthere
      [The text to which the annotations are applied.]
Content-Type:Application/SGML
Content-Description:DOCUMENT
Content-ID:underlying.html-is-here

<!doctype html public "-//IETF//DTD HTML 2.0//EN">
<html><title>A Short but Demonstrative Chapter</title>
<p><a name="a1">This is the first paragraph.</a></p>
<p><a name="a2">This is a paragraph in French.</a></p>

--cuthere
      [The annotations.  Docbook's ULink element has
       a URL attribute but no URN attribute, as shown
       here, and FPIs cannot apparently have fragment
       identifiers, as used here.  Pretend.]
Content-Type:Application/SGML
Content-Description:DOCUMENT
Content-ID:annoset.sgm-is-here

<!doctype simplelist public "-//Davenport//DTD DocBook V3.0//EN">
<simplelist role="annotations">
<member>
<ulink urn="urn:fpi:-//Palm Tree Books//DOCUMENT underlying//EN#a1">this
statement is true</ulink></member>
</ulink></member>
<ulink urn="urn:fpi:-//Palm Tree Books//DOCUMENT underlying//EN#a2">this
statement is false</ulink></member>
</ulink></member>
</simplelist>

--cuthere
Content-Type:Application/SGML
Content-Description:DTD
Content-ID:complex.dtd-is-here

<!element complex - - (iset+, core)>
<!element iset - o EMPTY>
<!attlist iset location CDATA #required
               display (overlay|hide) #implied>
<!element core - o EMPTY>
<!attlist core location CDATA #required>


Appendix:  USB-Package DTD

<!-- USB-Package DTD, for which the FPI is
      "-//Palm Tree Books//DTD USB-Package v0.1//EN" -->

<!-- packlist wraps the whole list, which may be a list of
     urnpairs or cidpairs -->
<!element packlist - - (partname, 
       (urnpair*|cidpair*|an-entity*))>

<!-- partname supplies the USB Part name for this list -->
<!element partname - - (#PCDATA)>

<!-- urnpair is an independent link connecting the 
   URN of a semantic definition with the URN or URL of an
   entity; both URNs and URLs may be used, and as yet no
   precedence is defined.  While multiple urnpairs for the
   same entity are allowed, no use is proposed for them -->
<!element urnpair - o EMPTY>
<!attlist urnpair
    semanticurn CDATA #REQUIRED
    itemurn CDATA #REQUIRED -- use NULL if itemurl supplied -- 
    itemurl CDATA #REQUIRED -- use NULL if itemurn supplied -- >

<!-- cidpair maps a URN or URL to a MIME Content-ID.  
     No meaning is assigned to use of both a URN and 
     a URL.  Yet.  -->
<!element cidpair - o EMPTY>
<!attlist cidpair
    itemurn CDATA #REQUIRED -- use NULL if itemurl supplied -- 
    itemurl CDATA #REQUIRED -- use NULL if itemurn supplied -- 
    cidofitem CDATA #REQUIRED >

<!-- an-entity is just an entry in a list of entities -->
<!element an-entity - o EMPTY>
<!attlist an-entity
    itemurn CDATA #REQUIRED -- use NULL if itemurl supplied -- 
    itemurl CDATA #REQUIRED -- use NULL if itemurn supplied -- >


Appendix:  USB-Storage DTD 

<!-- storage.dtd, for which the FPI is
      "-//Palm Tree Books//DTD USB-Storage v0.1//EN" -->

<!-- This DTD only maps URNs to storage objects, identified
     by their URLs.  It is a management tool and could be 
     used by a MIME packer to construct a USB MIME 
     message.  It is optional. -->

<!element USB-storage - - (req,opt*)>
<!attlist USB-storage
   URN CDATA #REQUIRED -- urn of this entity -- >

<!-- mimemap is not included as it is constructed by the
     MIME packer for a specific MIME packing -->

<!element req - - (root-sdecl, root, md-meta, 
   md-intprop, allents, startparse, allopts)>

<!element opt - - (optpart+)>

<!element optpart - - (partname)>
<!attlist optpart
   URN CDATA #REQUIRED -- urn of this entity -- >

<!element partname - - (#PCDATA)>
<!attlist partname
   URN CDATA #REQUIRED -- urn of the part --
   URL CDATA #REQUIRED -- url of the part -- >

<!element root-sdecl - o EMPTY>
<!attlist root-sdecl
   URN CDATA #REQUIRED
   URL CDATA #REQUIRED>

<!element root - o EMPTY>
<!attlist root
   URN CDATA #REQUIRED
   URL CDATA #REQUIRED>

<!element md-meta - o EMPTY>
<!attlist md-meta
   URN CDATA #REQUIRED
   URL CDATA #REQUIRED>

<!element md-intprop - o EMPTY>
<!attlist md-intprop
   URN CDATA #REQUIRED
   URL CDATA #REQUIRED>

<!element allents - o EMPTY>
<!attlist allents
   URN CDATA #REQUIRED
   URL CDATA #REQUIRED>

<!element startparse - o EMPTY>
<!attlist startparse
   URN CDATA #REQUIRED
   URL CDATA #REQUIRED>

<!element allopts - o EMPTY>
<!attlist allopts
   URN CDATA #REQUIRED
   URL CDATA #REQUIRED>


Appendix:  USB-Storage DTD Example Document

<!doctype USB-storage public "-//Palm Tree Books//DTD USB-Storage v0.1//EN">

<USB-storage URN="urn:fpi:-//Palm Tree Books//DOCUMENT 001//EN">

<!-- Aren't these awful URNs? -->

<req>

<root-sdecl URN="urn:fpi:-//Palm Tree Books//DOCUMENT 004//EN"
URL="sdecl.sgm">
<root URN="urn:fpi:-//Palm Tree Books//DOCUMENT 003//EN"
URL="root.sgm">
<md-meta URN="urn:fpi:-//Palm Tree Books//DOCUMENT 005//EN"
URL="biblio.sgm">
<md-intprop URN="urn:fpi:-//Palm Tree Books//DOCUMENT 006//EN"
URL="intprop.sgm">
<allents URN="urn:fpi:-//Palm Tree Books//DOCUMENT 007//EN"
URL="allents.sgm">
<startparse URN="urn:fpi:-//Palm Tree Books//DOCUMENT 008//EN"
URL="startparse.sgm">
<allopts URN="urn:fpi:-//Palm Tree Books//DOCUMENT 009//EN"
URL="optlist.sgm">

</req>
<opt>
<!-- shows some entities not used in the example MIME 
     message -->
<optpart URN="urn:fpi:-//Palm Tree Books//DOCUMENT 010//EN">
<partname URN="urn:fpi:-//Palm Tree Books//DOCUMENT 011//EN"
URL="stylesh.dsl">style-sheet
</partname>
</optpart>
<optpart URN="urn:fpi:-//Palm Tree Books//DOCUMENT 012//EN">
<partname URN="urn:fpi:-//Palm Tree Books//DOCUMENT 013//EN"
URL="urnres.hnt">urn-resolution-hints
</partname>
</optpart>
</opt>

</USB-storage>