[This local archive copy mirrored from the canonical site: http://www.isogen.com/papers/valueref/valrfsld.html; links may not have complete integrity, so use the canonical document at this URL if possible.]

HyTime Valueref in Aircraft Manual Authoring Management

Author: W. Eliot Kimber

Or, how I spent my summer vacation applying an obscure feature of an unpublished standard to a difficult document management problem that everybody faces (but that aircraft manufactures face in spades).

1 Introduction
2 Logical vs. SGML Document
3 Making Compound Documents
4 The Challenge: Saying What We Mean
5 What is "Content"? or "Parsing is not Processing"
6 Making Yourself Clear: Content-of or Hyperlink?
7 Applying Value Reference to Aircraft Maintenance Manuals

1 Introduction

Need to manage authoring and production of aircraft maintenance manuals
Existing data management system is primarily a storage object manager
Used text entities for storage objects
Use of text entities caused a number of problems that appeared to be difficult to solve
We determined that using subdocuments for storage objects would solve most, if not all, of the problems
The use of subdocuments does raise some design and implementation issues
The HyTime value reference facility addresses many of these issues

2 Logical vs. SGML Document

There is always a distinction between syntactic SGML documents...
...and logical compound documents
Most current systems limit a logical document to a single syntactic document
There is no good reason for this.

3 Making Compound Documents

Compound documents built by addressing real content of element
Doesn't matter how the addressing is done
SGML and HyTime provide a variety of addressing methods:
- Entity references
- ID references
- Queries
The same addressing method can be used for different purposes

4 The Challenge: Saying What We Mean

If you can't determine purpose of address from the address...
...then you must say what the purpose is
In particular, need to distinguish the type of relationship the address establishes:
- Property of
- Content of
- Annotation of

4.2 Property-Of Relationships

Describe base properties of objects
In SGML, properties are usually represented syntactically as attributes
Properties may be represented syntactically by other means

4.3 Content-Of Relationships

Define the semantic content of objects
In SGML, usually represented by syntactic containment
Content may be defined by reference
Weakly expressed in ISO 8879 by #CONREF attributes
#CONREF is a syntactic mechanism...
...does not define a single clear semantic for the use of this #CONREF.

4.4 Annotation-of Relationships

Associate objects with properties that are not base properties of those objects
E.g., hyperlinks

5 What is "Content"? or "Parsing is not Processing"

Why do systems only enable use of single syntactic SGML documents as logical documents?
Because most systems
- Conflate parsing with processing
- Impose unnecessary validation constraints on logical document
- Or just didn't think it through completely
The key to keep in mind is "parsing is not processing"

5.2 Value Reference Processing Picture

Figure 1. Value Reference Processing

5.3 Groves Make It Clear

The grove model makes it clearer that parsing is not processing
Application processing is applied to groves
Application can do whatever it wants or needs to do
Once you have a grove, storage organization is not necessarily relevant.
In a grove, everything's a node...
...it doesn't necessarily matter what kind of nodes you have...
...as long as the processing application can make sense of them.

5.4 "Content" is Defined by Processor

It's up to the processor to decide what it considers to be content

6 Making Yourself Clear: Content-of or Hyperlink?

Must be able to distinguish addressing used for different purposes
Can't tell by looking just at address
How do we tell?
HyTime provides two basic methods:
- Declaring an element type to be a kind of hyperlink
- Indicating that a particular address creates a content-of or property-of relationship
May need to use both methods for the same element type

6.2 The HyTime Value Reference Facility

Uses one attribute to characterize the semantic of other attributes of the same element..
...that is, referential attributes
Referential attributes are attributes that do addressing

Looks like:

<!ELEMENT Warning -- An invocation of a warning. --
  - O (Para) >
<!ATTLIST Warning
  warning-content -- Reference to re-used content of the warning --
   IDREF #CONREF
  valueref -- Define who's value is being referenced. --
   CDATA #FIXED
   "#CONTENT warning-content"
>

6.3 How Valueref Works

Value of attribute is list of name pairs
First name is thing whose value is being addressed
Second name is the attribute (or content) doing the addressing
The things whose value you can address are:
- The effective value of an attribute of the element
- The content of the element
- The value of the element

6.4 Valueref for Subdoc Example

<!DOCTYPE MyDoc [
 ...
<!ELEMENT Warning -- An invocation of a warning. --
  - O (Para) >
<!ATTLIST Warning
  warning-value -- Reference to re-used warning subdocument --
   ENTITY #CONREF
  valueref -- Define who's value is being referenced. --
   CDATA #FIXED 
   "#ELEMENT warning-value"
>
<!ENTITY dont-poke-subdoc SYSTEM "dontpoke.sgm" SUBDOC >
]>
<MyDoc>
 <warning warning-value="dont-poke-subdoc">
</MyDoc>

<!DOCTYPE Warning SYSTEM >
<Warning>
<para id="dont-poke">Don't poke yourself in the eye.  It hurts.
</para>
<Warning>

6.5 What is the Value of An Element?

The data that the application uses where it expects to have an SGML element
Could be the original element at point it occurred in the document
Could be another element that element points to
The result is an application-specific union of the attributes of the original element...
...and the properties of the referenced element.

6.6 Most Obvious Case

Most obvious case is pointing to a subdocument entity...
...(but subdocument references are not the only choice)
Reference to a subdocument entity is really a reference to...
...the document element of the subdocument...
...(by the rules of ISO/IEC 10744:1997)

7 Applying Value Reference to Aircraft Maintenance Manuals

Business rules reflected
Authoring implementation approach
Data management implementation approach
Production implementation approach

7.2 The Business Rules

All components of a document conform to the same base architecture
Authoring granularity defined by storage object (entity) granularity
Re-usable objects must be storage objects
These rules are satisfied in the documents by using subdocument entity references to define content-of relationships
Use the value reference facility to distinguish content-of addresses from other addresses

7.3 Typical Declaration

<!ELEMENT pageblock - O (%pageblock-content;) >
<!ATTLIST pageblock
  subdoc   ENTITY #CONREF
  valueref CDATA  #FIXED 
   "#ELEMENT subdoc"
>

7.4 Authoring and Value Reference

Must enable the use of subdocument references in editor:
- Create references to subdocuments
- Follow references to subdocuments (view or edit)
- Expand effective element values in line
Were able to do all of this in ADEPT*Editor
Only show inline was hard...
...and only because editor imposes unnecessary constraint

7.5 Data Management and Value Reference

Data management system was always an entity manager
Doesn't care whether entities are document or text entities
Structure of compound document mirrored in database to enable access
No significant change to data management system
Tends to make the data management task easier
Each object can be completely validated on check-in

7.6 Value Reference and Production

Have to provide single-instance view of document for brain-dead tools
Can build into transform you always have to have
Ken Holman built instance generator using Omnimark
Does validation of both syntax and application-specific semantics of entire logical document
Should be doable with any useful and general SGML processing tool

7.7 Subdoc Integration Implementation

Hard but not all that hard
Has been demonstrated with the following tools:
- DSSSL and JADE (0.8)
- NSGMLS and Perl
- Omnimark
- Balise
- ADEPT*Editor

8. Summary

Needed to use subdocuments to manage document components
Needed to distinguish references to subdocuments that define content-of relationships from other references
Didn't want to hard-code processing to attributes in a particular document type
Value reference facility gives us a standardized way to express our intent
If intent is clear, no significant implementation difficulty...
...at least within the set of constraints we had
Approach is general and can be enhanced as needed without breaking the system or requiring re-architecting

Generated from the original SGML using the JADE DSSSL engine. Style sheet developed by ISOGEN International Corp.