6.3. Object Management

6.3.1. Overview

Object management is a collection of features which support:

the definition of special objects in configuration files
the use of these special objects in documents.

For example, a configuration file can contain a lookup table of references. Within a document:

a table of references can be inserted by simply specifying document codes - the document names are found from the lookup table
REF/DOC object phrases are validated as legal references/documents
hypertext is generated for:
- entries in the table of references
- REF and DOC object phrases
REF objects can be converted to DOC objects and visa versa.

SDF supports 4 predefined classes of objects - references, terms, products and organisations. New classes can be added via the class macro.

6.3.2. The Predefined Classes

The fields supported by the predefined classes are given below.

Class	Styles	Identifer fields	Property fields
references	REF, DOC	Reference, Document	Jump, Version, Status
terms	TERM	Term, Definition	Jump
products	PRD	Name	Jump
organisations	ORG, ORGN	Name, Long	Jump

Styles are the tags used for objects in the class. The first style is the 'normal' one. The second style is the 'long' one.

Identifier fields are the 'normal' and 'long' (if any) fields within the data tables. Property fields are the additional fields, if any.

Note: The build_title macro uses the references declarations to provide default values for DOC_CODE, DOC_VERSION, DOC_STATUS and DOC_URL.

The objects module provides some commonly used objects in these predefined classes (and matching variables).

6.3.3. Declaring Objects

To declare a table of objects, the syntax is:

  !block class; data
  field names
  object record1
  ...
  object recordN
  !endblock

An example lookup table for organisations is given below.

!block organisations; data
Name        Long                             Jump
DEC         Digital Equipment Corporation    http://www.dec.com
Frame       Frame International              http://www.frame.com
HP          Hewlett Packard                  http://www.hp.com
IBM         International Business Machines  http://www.ibm.com
Mincom      Mincom Pty Ltd                   http://www.mincom.com
Microsoft   Microsoft Corporation            http://www.microsoft.com
!endblock

To insert a table of objects, the syntax is:

  !block class
  field names
  object key or record1
  ...
  object key or recordN
  !endblock

If only the key is provided, then the 'long' name is found from the configured data, if any. For example, a configuration file may have the following declaration of terms:

  !block terms; data
  Term     Definition
  SDF      Simple Document Format
  SQL      Structured Query Language
  !endblock

These can then be inserted into a document as follows:

  !block terms
  Term     Definition
  SDF
  SQL
  WWW      World Wide Web
  !endblock

Note that the definition for a term already declared will be inserted if none is provided. Furthermore, new terms (like WWW above) can be inserted and added to the configured ones.

6.3.4. Hypertext and Name Conversion

If an object has a 'Jump' property defined for it, hypertext is automatically generated for it. For example:

 See {{DOC:My Design Document}} for further details

will have a jump created for the DOC object.

Object names can be converted between the normal and long forms by using the expand and shrink attributes. For example:

 {{PRD:Java}} was developed by {{ORG[expand]Sun}}.