ISO/IEC JTC1/SC18/WG8 **N1873**

# ISO/IEC JTC1/SC18/WG8 Document Processing and Related Communication--- Document Description and Processing Languages {#isoiec-jtc1sc18wg8-document-processing-and-related-communication-document-description-and-processing-languages .Heading-0-(nobreak)}

  -------------------- --------------------------------------------------
  **Title:**           A Proposal to Introduce \"Module\" Structures into
                       SGML

  **Source:**          WG8 Japan (Author: Toru Takahashi)

  **Project:**         JTC1.18.15.1

  **Project editor:**  Charles F. Goldfarb

  **Status of          Contribution to the SGML RG in the WG8 Meeting at
  document:**          Boston

  **Requested          For Discussion about the Revision of SGML
  action:**            

  **Date**             November 12, 1996

  **Distribution:**    WG8 and liaisons

  **References:**      WG8 N1855

  **Supersedes:**      WG8 N1677
  -------------------- --------------------------------------------------

# Introduction

Designing a large, complex DTD is a very difficult job. One reason of
this difficulty comes from SGML's restriction on name spaces.

For element type names, SGML allows only one name space per document.
This restriction means, that if you intend to design a new DTD, you have
to be familiar with all the element types you wish to use to construct
the DTD, and have to select their names very carefully to avoid name
conflicts.

This lack of modularity makes difficult to use separately designed
declaration sets (parts of DTDs) in mixture to build up a complete DTD.
For example, if you want to use pre-defined declaration sets for
\"tables\" and \"math expressions\" together to construct your own
\"report\" DTD, you have to examine whether there are any name conflicts
between them or not. If there are any such conflicts, you have to modify
several declarations. This restriction in name space makes impossible to
treat these declaration sets as public (read only) texts. Similar
problems may occur on the parameter entity names.

To solve these problems, we propose to introduce the concept of
\"Module\" into SGML.

**Author's Note:** This document is the revised version of my previous
proposal shown in WG8 N1677. Through the discussion done in the SGML RG
meeting in the WG8 meeting held at Alexandria (April 1994) and
discussions with Japanese WG8 members, some problems had been pointed
out on the previous proposal. These are:

1.  There are no means to refer to more than one element types defined
    in a module from the outside. (The element type name opened to the
    outside is restricted to the name of the "top-level" element of the
    module.)

2.  If a module contains the definition of an element type which has the
    same element type name with another one defined in the outside, it
    is impossible to refer to the definition of the outer element type
    from the inside of the module.

3.  There are no means to parameterize some parts of an module
    definition and controls them from the outside.

4.  In document instances whose DTD contains one or more module
    declarations, the meaning of a GI may be changed according to the
    position where the tag appeared. It may cause some confusions to the
    user.

    The new proposal shown in this document is still incomplete and
    needs more refinements, but I believe the issues listed above are
    solved in principle.

# Concept of \"Module\"

## Separation of Name Spaces

A module is a set of declarations which has its own name spaces. Each
module has a name space for element type names and has another one for
parameter entity names.

All these names declared in a module are registered in the corresponding
name space of the module. In principle (with some exceptions explained
below), all names declared in a module are hidden from the outside, and
all names declared at the outside of a module are hidden from the inside
of the module.

With this separation of name spaces, most of the problems on name
conflicts can be avoided.

## Import and Export of Names

The following lines (exp.1) show an example of module.

\<!IMPORT (mg1, mg2)\>

\<!EXPORT (a, c)\>

\<!ELEMENT a - O (b, c) \>

\<!ELEMENT b - O (d \| e)\* \>

\<!ELEMENT c - O (%mg1;) \>

\<!ELEMENT d - O (#PCDATA) \>

\<!ELEMENT e - O (%mg2;)+ \>

exp.1: An Example of Module

The declaration shown in the first line is called "import declaration".
The declaration shown in the second line is called "export declaration".

### Import Declaration

A import declaration declares the names of *parameter entities* whose
values are imported from the outside. In exp.1, the names "mg1" and
"mg2" are declared in a import declaration, so these names can be used
as parameter entity names without defining the corresponding entity
values. Each module may have zero or one import declaration. As the
usual parameter entity declarations, the import declaration have to
appear before the first place where one of the declared names is
referred.

Not as the usual parameter entities, the names declared in a import
declaration can be used (referred) only in the content models of element
types which are defined in the module. References to those names in any
other place are prohibited.

**Author's Note:** I believe that this restriction is essential to
enable to distinguish the element type names imported through a import
declaration from the names of element types defined inside of the
module. The alternative means to enable this distinction is to introduce
a new construct for referring to the parameters imported from the
outside.

### Export Declaration

On the contrary, an export declaration declares *element type names*
which will be opened to the outside. All the element type names which
are not declared in an export declaration are hidden from the outside.
Each module must have one (and may have only one) export declaration.
The export declaration have to declare one or more element type names to
export.

## Module Declaration

The construct "module declaration" declares and invokes a module. The
following lines (exp. 2) show an typical example of module declaration.

\<!MODULE mod ("(#PCDATA)", "(x, y)")

SYSTEM "moddef1.mod" \>

exp.2: An Example of Module Declaration

This module declaration invokes a module defined in an external entity
which can be referred to by the system identifier "moddef1.mod", with a
module name "mod". Furthermore, this module declaration gives two
parameter values ("(#PCDATA)" and "(x, y)") to the invoked module. At
the inside of the module, these parameter values will become the values
of parameter entities declared in the import declaration.

The number of parameter values must be the same to the number of
parameter entity names specified in the import declaration of the
invoked module. Each character string given as a parameter value must
satisfy the syntax of "model group".

**Author's Note:** The second restriction are also required to
distinguish the element type names imported through the import
declaration from the names of element types defined in the module.

Instead of referring to an external entity which contains the definition
of a module, a module declaration may have its own definition of the
invoking module at the inside of the declaration itself. If the external
entity "moddef1.mod" has the content shown in exp.1, the following
declaration (exp.3) has the same effect to exp.2.

\<!MODULE mod ("(#PCDATA)", "(x, y)") \[

\<!IMPORT (mg1, mg2)\>

\<!EXPORT (a, c)\>

\<!ELEMENT a - O (b, c) \>

\<!ELEMENT b - O (d \| e)\* \>

\<!ELEMENT c - O (%mg1;) \>

\<!ELEMENT d - O (#PCDATA) \>

\<!ELEMENT e - O (%mg2;)+ \>

\]\>

exp.3: Another Example of Module Declaration

As the result of interpretation of the module declaration shown above,
the element types which refer to the imported parameters will have the
following definitions. (Redundant parentheses are deleted.)

\<!ELEMENT c - O (#PCDATA) \>

\<!ELEMENT e - O (x, y)+ \>

The element type names imported from the outside through the import
declaration will be semantically distinguished from the element type
names defined in the module. In this case, even if this module contains
a declaration of element type "x", the instance of the element type "x"
defined in this module can't appear in the content of element "e". Only
the instances of element type "x" defined outside of the module can
appear in the content of a instance of element type "e".

Module declarations may be appeared in a document type declaration
subset, in mixture with other declarations (element type declarations,
attribute definition list declarations, general entity declarations,
etc.).

In a document type declaration subset, element type names exported from
a module which is invoked by a module declaration appeared in the
declaration subset, may be used to construct content models of element
type declarations in the declaration subset. In principle, these element
type names must be qualified by "module prefix". A module prefix is
constructed from a module name and a module prefix connector "::".
Module prefixes may be omitted if there are no ambiguities.

In the following example (exp.4), the element type "a" and "c" defined
in module "mod" and exported to the outside are used to construct the
content model of element type "doc" and "p" respectively.

\<!DOCTYPE doc \[

\<!ELEMENT doc - - (fm, (p \| mod::a)+, bm) \>

\<!ELEMENT p - O (q \| hp \| mod::c)\* \>

\<!ELEMENT x - O (#PCDATA) \>

\<!ELEMENT y - O (#PCDATA) \>

\...

\<!MODULE mod ("(#PCDATA)", "(x, y)") \[

\<!IMPORT (mg1, mg2)\>

\<!EXPORT (a, c)\>

\<!ELEMENT a - O (b, c, x) \>

\<!ELEMENT b - O (d \| e)\* \>

\<!ELEMENT c - O (%mg1;) \>

\<!ELEMENT d - O (#PCDATA) \>

\<!ELEMENT e - O (%mg2;)+ \>

\<!ELEMENT x - O (#PCDATA) \>

\]\>

\...

\]\>

exp.4: An Example Using the Element Type Names Defined in a Module

All other element types defined in the module (in this case, "b", "d",
"e" and "x") are hidden from outside. They can't be used in the outside
of the module.

# Modules in the Document Instances

In principle, all the instances of element types defined in a module
will be marked up by start-tags and end-tags which have an "extended
GI". An extended GI is a element type name qualified by a module prefix
(defined above).

For example, an instance of a document which has the document type
declaration shown in exp.4 may be as follows.

\<doc\>

\<fm\>\...

p.  \...

\<mod::a\>

\<mod::b\>

\<mod::d\>content of "d" defined in the module\</mod::d\>

\<mod::e\>

\<x\>content of "x" defined outside of the module\</x\>

\<y\>content of "y" defined outside of the module\</y\>

\<mod::d\>content of "d" defined in the module\</mod::d\>

\...

\</mod::b\>

\<mod::c\>content of "c" defined in the module\</mod::c\>

\<mod::x\>content of "x" defined in the module\</mod::x\>

\</mod::a\>

\<bm\>\...

\</doc\>

exp.4: An Example of Document Instance Contains an Instance of Module

If a element type which has the same element type name is not declared
outside of the module (in other words, there are no ambiguities), the
module prefixes in an extended GI may be omitted. Therefore, the example
above can also be represented as follows.

\<doc\>

\<fm\>\...

p.  \...

\<a\>

\<b\>

\<d\>content of "d" defined in the module\</d\>

\<e\>

\<x\>content of "x" defined outside of the module\</x\>

\<y\>content of "y" defined outside of the module\</y\>

\<d\>content of "d" defined in the module\</d\>

\...

\</b\>

\<c\>content of "c" defined in the module\</c\>

\<mod::x\>content of "x" defined in the module\</mod::x\>

\</a\>

\<bm\>\...

\</doc\>

exp.5: Another Representation of the Document Instance shown in exp.4

# More Concrete (but still much simplified) Examples

## A Module for Math Expressions

The following is an example of a module which has definitions for math
expressions. This module exports two element type names ("f" for inline
formulae, and "df" for displayed formulae).

\<!EXPORT (f, df) \>

\<!ENTITY % math.expr "#PCDATA\|power\|root\|sq\|sqrt\|frac\|\..." \>

\<!ELEMENT f - O (%math.expr;) \>

\<!ELEMENT df - O (%math.expr;)+ \>

\<!ELEMENT power - O (coef, of) \>

\<!ELEMENT root - O (coef, of) \>

\<!ELEMENT coef O O (%math.expr;) \>

\<!ELEMENT of - O (%math.expr;) \>

\...

If this module is invoked from a DTD with the module name "math", and if
the name "f" and "root" are used for other element types in the DTD, the
document instance may be described as follows.

\<p\>

bra bra bra \<math::f\>\<power\>3\<of\>(a + b)\</math::f\> bra bra\...

bra bra bra\...

\<df\>

x = \<math::root\>4\<of\>c - d\</math::root\>

\</df\>

\<p\>

bra bra bra bra\...

## Two "Table" Modules in a Document

If there are separately designed two modules for tables (they have
different structures), and if you intend to use them together to
construct your own DTD, you can accomplish this even if both modules use
the same element type name (for example, "table") for the top-level
element of tables.

Suppose that these modules are defined as follows.

In an external entity whose system identifier is "table-a.mod":

\<!IMPORT (cell-cont) \>

\<!EXPORT (table) \>

\<!ELEMENT table - - (row)+ \>

\<!ELEMENT row - O (cell)+ \>

\<!ELEMENT cell - O (%cell-cont;)\* \>

In an external entity whose system identifier is "table-b.mod":

\<!IMPORT (field-cont) \>

\<!EXPORT (table) \>

\<!ELEMENT table - - (field)+ \>

\<!ATTLIST table

nrow NUMBER #REQUIRED

ncell NUMBER #REQUIRED

\>

\<!ELEMENT field - O (%field-cont;)\*\>

\<!ATTLIST field

r NUMBER #REQUIRED

c NUMBER #REQUIRED

\>

An example of document which contains both tables in its DTD may be
described as follows.

\<!DOCTYPE doc \[

\<!ENTITY % para "p\|lq\|ul\|ol\|cell-tab::table\|field-tab::table"\>

\<!ENTITY % ph "#PCDATA\|q\|hp"\>

\<!MODULE cell-tab ("(%ph;)\*") SYSTEM "table-a.mod" \>

\<!MODULE field-tab ("(%ph;)\*") SYSTEM "table-b.mod" \>

\<!ELEMENT doc - - (fm, body, bm) \>

\...

\<!ELEMENT h1 - O (h1t, (%para;)\*, h2\*) \>

\<!ELEMENT h2 - O (h2t, (%para;)\*, h3\*) \>

\...

\]\>

\<doc\>\...

\<h1\>\<h1t\>bra bra bra\...\</h1t\>

\<p\>

bra bra bra\...

\</p\>

\<cell-tab::table\>

\<row\>

\<cell\>123\<cell\>456\<cell\>\<hp\>0\</hp\>\</cell\>

\</row\>

\<row\>

\<cell\>abc\<cell\>def\<cell\>\<hp\>Z\</hp\>\</cell\>

\</row\>

\...

\</cell-tab::table\>

\<p\>

bra bra bra\...

\</p\>

\<field-tab::table nrow=5 ncell=3\>

\<field r=1 c=1\>123\<field r=1 c=2\>456\<field r=1
c=3\>\<hp\>0\</hp\>\</field\>

\<field r=2 c=1\>abc\<field r=2 c=2\>def\<field r=2
c=3\>\<hp\>Z\</hp\>\</field\>

\...

\</field-tab::table\>

\...

# Conclusion

As shown above, DTD designers can use a module as a building-block to
build up their own DTDs. It enables the structured design of DTDs, and
reduces the cost to design complex DTDs. It also enables DTD designers
to use simple and natural element type names, without worrying about
name conflicts.

Furthermore, the syntax proposed in this docuemnt for module require no
changes to the interpretation of any existing constructs. So it can be
introduced to SGML with keeping the upward compatibility completely.