[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).

Copyright (c) 1997 W. Eliot Kimber and ISOGEN International Corp.

Table of Contents

1 Introduction

2 Logical vs. SGML Document

3 Making Compound Documents

4 The Challenge: Saying What We Mean

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"

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?

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 --
      valueref -- Define who's value is being referenced. --
       "#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

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

<para id="dont-poke">Don't poke yourself in the eye.  It hurts.

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

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

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