# $Id$
#
# >>Copyright::
# Copyright (c) 1992-1996, Ian Clatworthy (ianc@mincom.com).
# You may distribute under the terms specified in the LICENSE file.
#
# >>History::
# -----------------------------------------------------------------------
# Date      Who     Change
# 29-Feb-96 ianc    SDF 2.000
# -----------------------------------------------------------------------
#

H1: Object Management

H2: 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
{{CLASS: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 - {{CLASS:references}},
{{CLASS:terms}}, {{CLASS:products}} and {{CLASS:organisations}}.
New classes can be added via the {{MAC:class}} macro.

H2: The Predefined Classes

The fields supported by the predefined classes are given below.

!block table
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
!endblock

{{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 {{MAC:build_title}} macro uses the {{CLASS:references}} declarations
to provide default values for DOC_CODE, DOC_VERSION, DOC_STATUS and DOC_URL.

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

H2: Declaring Objects

To declare a table of objects, the syntax is:

E:  !block {{class}}; data
E:  {{field names}}
E:  {{object record1}}
E:  ...
E:  {{object recordN}}
E:  !endblock

An example lookup table for organisations is given below.

!block example; wide
!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
!endblock

To insert a table of objects, the syntax is:

E:  !block {{class}}
E:  {{field names}}
E:  {{object key or record1}}
E:  ...
E:  {{object key or recordN}}
E:  !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 {{CLASS:terms}}:

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

These can then be inserted into a document as follows:

E:  !block terms
E:  Term     Definition
E:  SDF
E:  SQL
E:  WWW      World Wide Web
E:  !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.

H2: Hypertext and Name Conversion

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

V: 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 {{OATTR:expand}} and {{OATTR:shrink}} attributes.
For example:

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

!end_topic
