6 Base module

Conceptually speaking, when determining which objects are members of the HyTime BOS of a HyTime hyperdocument, a HyTime application uses an "entity tree discovery" process in which entities that are recursively declared are examined and reported as being candidates for membership in the HyTime BOS (see 6.2.4 Bounded object set (BOS)). The attribute maximum bounded object set level (maxbos) specifies the nominal maximum number of recursions permitted in the normal entity tree discovery process. The value of the maxbos attribute applies to all entities declared in the hub document except subhub document entities (see 6.5.2 HyTime BOS control data attributes).

NOTE 97 The value of maxbos is said to specify the "nominal" number of recursions because it may be overridden by the inbos common data attribute, by the inclusion of subhubs, and by the bosspec attribute of the HyDoc element.

A maxbos value of 0 means that the number of recursions to be made in the course of the normal entity tree discovery process is not limited. A maxbos value of 1 means that only the hub document has nominal membership in the HyTime BOS.

NOTE 98 In other words, if maxbos is 1, the normal entity tree discovery process does not recurse at all.

A maxbos value of 2 means that the normal entity tree discovery process should stop after one recursion, that is, all of the entities declared in the hub document are nominally members of the HyTime BOS, but there should be no examination of the entities declared in the entities declared in the hub document. A maxbos value of 3 means there is a limit of two recursions, and so on.

The maxbos value takes precedence over the boslevel attribute of a data entity when the data entity's boslevel would result in a BOS larger than that allowed by the maxbos level.

NOTE 99 In other words, the nominal maximum number of recursions in the normal entity tree discovery process whose root is an entity declared in the hub document is actually limited to the smaller of the value of the maxbos attribute of the hub document's HyDoc element and the value of the boslevel common data attribute of such entity.

The attribute bounded object set level (boslevel) specifies the default bounding level to be used for data entities that do not specify a boslevel data attribute. The semantics of the numbers used in its value are the same as those of the maxbos attribute. If no value is specified for the boslevel attribute, there is no HyTime BOS; the author of the hyperdocument is, in effect, delegating responsibility to the system and asking that the application BOS govern the assembly of the effective BOS (see 6.2.4 Bounded object set (BOS)).

<![ %bos; [
<!attlist
   -- bos --      -- HyTime bounded object set --
                  -- Clause: 6.5.1 --
  (HyDoc)

   maxbos         -- Maximum bounded object set level --
                  -- Bounding level of HyTime bounded object set when
                     document is a hub or subhub. --
      NUMBER      -- Constraint: depth of nested entities to include
                     in BOS (0=no limit, 1=hub only) --
      0

   boslevel       -- Bounded object set level --
                  -- Default BOS level used by data entities declared
                     in hub document. --
      NUMBER      -- Constraint: depth of nested entities to include
                     in BOS (0=no limit, 1=this entity only) --
      #IMPLIED    -- Default: No HyTime BOS --

>
]]><!-- bos -->

The attribute BOS level (boslevel) specifies the depth of entity reference relative to this entity to include in the bounded object set (see 6.2.4 Bounded object set (BOS)). If not specified, the BOS level specified for the HyTime document element is used. The boslevel value is subordinate to the maximum BOS defined for the hub or subhub document. The boslevel value cannot cause entities to be included in the BOS if doing so would exceed the maximum BOS level.

The attribute include in BOS (inbos) indicates whether the entity must be unconditionally included in the BOS ("inbos") or is to be unconditionally excluded from the BOS ("notinbos"). If no value is specified, the entity is included when allowed by the governing BOS level. When "inbos" is specified, the entity will be included in the BOS unconditionally. Entities declared by an entity so included are included in the BOS only if they do not exceed the maximum BOS level or if they are also declared with a value of "inbos".

NOTE 100 Entities "unconditionally" included or excluded are still subject to inclusion or exclusion by bosspecs, which are always the final arbiters of inclusion or exclusion in a HyTime BOS.

Some objects are considered by hyperdocument authors to be so critical for proper operation of the hyperdocument that they must be integrated into the effective BOS before the hyperdocument can be considered complete enough for any use to begin. Such critical objects have "foreground priority" in the HyTime BOS. The remaining objects of the HyTime BOS have "background priority". The bounded object set priority (bosprrty) attribute sets the default priority for itself and for all of the entities in the entity subtree of which it is the root.

NOTE 101 For example, it may be necessary to comply with activity policies appearing in objects that are external to the hub document; such objects should be specified as having foreground priority.

NOTE 102 Applications may choose to assemble the HyTime BOS or not. Similarly, if they do assemble the HyTime BOS, the objects can be assembled in any order. The concept of BOS priority provides a way to suggest a performance optimization for applications that, due to time constraints, must assemble the "foreground priority" objects (objects that are essential to making a minimally adequate presentation of the hyperdocument) first. Once the foreground priority objects of the HyTime BOS have been incorporated into the effective BOS, access to the hyperdocument could begin, while the remaining "background priority" objects are still being incorporated.

The hub document always has, in effect, foreground priority in the HyTime BOS. For all objects in an entity tree, the default priority is specified by the "bosprrty" common notation data attribute of the root entity of that tree. The bosprrty attributes of child entities, if present, specify the default priority for themselves and their children.

NOTE 103 For any given set of objects in an entity tree, the default priority specification may be overridden by one or more bosspec elements referenced by the bosspec attribute of HyDoc (see 6.5 HyTime Bounded object set).

An entity declared by a hub document whose subhub attribute's value is "subhub" is not subject to the normal entity tree discovery process from the perspective of the hub document. Instead, it is regarded as an independent hub document with its own normal entity tree discovery process, whose HyTime BOS is added to the hub document's tentative HyTime BOS. The subhub's maxbos, boslevel, inbos, and bosspec specifications are all taken into account before the resulting subhub HyTime BOS is added to the hub document's HyTime BOS. The hub document specifies that an entity should be considered a subhub by specifying a value of "subhub" for the subhub common notation data attribute. The maxbos and boslevel of the parent hub document are ignored by the subhub, which defines its own, local maxbos and default boslevel.

NOTE 104 A hyperdocument author may wish to include another hyperdocument in the new hyperdocument without having to worry about whether or not his own hyperdocument's boslevel (etc.) will inadvertently render that included hyperdocument's BOS incomplete, without requiring the author to duplicate and edit that hyperdocument's (perhaps very complex) BOS rules in the new hub document. The subhub facility satisfies this requirement.

NOTE 105 Like all other objects reported by the entity tree discovery process, objects added to the HyTime BOS by virtue of their membership in the HyTime BOS of a subhub document can be removed from the HyTime BOS by bosspec elements referenced by the bosspec attribute of HyDoc.

NOTE 106 Subhubs can declare subhubs.

             <!-- HyTime BOS Control Data Attributes -->
<![ %bos; [
<!attlist #NOTATION
-- bosdatt --     -- HyTime BOS control data attributes --
                  -- Clause: 6.5.2 --
   #ALL

   boslevel       -- BOS level --
                  -- Bounded object set level for the entity --
      NUMBER      -- Constraint: depth of nested entities to include
                     in BOS (0=no limit, 1=this entity only) --
      #IMPLIED    -- Default: value of boslevel attribute of HyDoc
                     element. --

   inbos          -- Include in BOS --
                  -- Unconditional include in, or exclude from, BOS --
      (inbos|notinbos)
      #IMPLIED    -- Default: inclusion controlled by BOS level --

   bosprrty       -- Bounded object set priority --
                  -- Default BOS priority of objects in entity tree
                     rooted at this entity. --
      (foregrnd|backgrnd)
      foregrnd

   subhub         -- Is entity a subhub? --
      (subhub|nosubhub)
      nosubhub
>
]]><!-- bos -->

<![ %bosspec; [
<!attlist
-- bosspcat --    -- BOS except specification attributes --
                  -- Clause: 6.5.3 --
   (HyDoc)
   bosspec        -- Bounded object set exception specification --
                  -- Adjustments to be made to the bounded object
                     set. --
      IDREFS      -- Reference --
                  -- Reftype: bosspec+ --
                  -- Constraint: must be internal reference --
      #IMPLIED    -- Default: no BOS exception specification --
>
]]><!-- bosspec -->

The boslevel, inbos, and bosprrty attributes are as defined for the common data attributes of the same names (see 6.5.2 HyTime BOS control data attributes).

The hub document's bosspecs are applied after all subhub and non-subhub entity tree discovery has been completed. The final adjustments to the HyTime BOS are made by the hub document's bosspecs, and of those adjustments, the ones whose inbos attribute's value is "notinbos" are applied last of all, so they can exclude any objects from the HyTime BOS, regardless of how they came to be tentatively included in it.

NOTE 107 Conceptually, every subhub's BOS is established before the BOS of the hub or subhub with respect to which it is a subhub. Therefore, conceptually, the sub-most subhub's BOS is established first, and the hub's BOS established last, so that the hub's bosspecs are the final arbiters. Whatever is contributed to the hub's BOS (or any subhub's BOS) by the hub's (or subhub's) own subhubs can be discarded selectively by the hub's (or subhub's) own bosspecs. Each hub or subhub applies its own bosspecs as part of the establishment of its own BOS, and these can be used to exceptionally include or exclude any entity included in or excluded from the BOS established by combining the BOSs of all of its own subhubs, together with the BOS established by its own entity declarations, boslevel, maxbos, etc. The bos control attributes do not apply to the contributions to the BOS that are the BOSs of subhubs. A subhub's BOS is incorporated wholesale, and only a bosspec can override it.

If the same storage object is declared as an entity more than once in the BOS, excluding one of its declarations with a bosspec will not automatically exclude its other declarations; complete exclusion of the storage object requires exclusion of all the entities for which it is the replacement data.

NOTE 108 In other words, there is no SGML- or HyTime-defined mechanism for determining that two different entities are in fact the same storage object (although processing applications are free to define their own algorithms for doing so).

         <!-- Bounded Object Set Exception Specification -->
<![ %bosspec; [
<!element
   bosspec        -- Bounded object set exception specification --
                  -- Clause: 6.5 --
                  -- Used to affect the HyTime BOS by overriding the
                     inclusion or exclusion and priority of the
                     entities identified by the BOS path or paths
                     given as content. --
   - O
   (#PCDATA)      -- Lextype: ((ENTITY,(csname|literal)*)|
                               (GRPO,ENTITY,(csname|literal)*,GRPC)+)
                     --
                  -- Constraint: If parentheses are used, each
                     parenthesized list is a separate BOS path. --
                  -- Constraint: Each word or literal in a BOS path is
                     the name of an entity declared in the entity
                     identified by the previous word, literal, or
                     entity name. --

-- Attributes [base]: bosspec --
-- CommonAttributes [GenArc]: dafe, dvlatt, etfullnm, id, irefmodl,
   ireftype, lextype, opacity --
-- CommonAttributes [base]: activity, conloc, dtxtatt, valueref --
-- CommonAttributes [locs]: refctl, refloc, reftype, rflocspn --
-- Referrers [base]: HyDoc:bosspec --
>
<!attlist
   bosspec        -- Bounded object set exception specification --
                  -- Clause: 6.5 --

   boslevel       -- BOS level --
                  -- The BOS level from the last entity named in
                     each specified BOS path to be affected by this
                     bosspec. --
      NUMBER      -- Constraint: depth of nested entities to include
                     in BOS (0=no limit, 1=last entity only) --
      1

   inbos          -- Include in BOS --
                  -- Unconditionally include or exclude objects
                     declared by the last entity named in each BOS
                     path, to the BOS level specified by this
                     bosspec's boslevel attribute. --
      (inbos|notinbos)
      #IMPLIED    -- Default: BOS unaffected --

   bosprrty       -- Bounded object set priority --
                  -- Unconditionally specify the BOS priority of
                     objects declared by the last entity named in each
                     BOS path, to the BOS level specified by this
                     bosspec's boslevel attribute. --
                  -- Note: The semantic of the bosprrty attribute is
                     not affected by the value of the inbos attribute
                     (that is, whether it is explicitly "inbos" or the
                     value is implied). --
      (foregrnd|backgrnd)
      #IMPLIED    -- Default: no priority change --
>
]]><!-- bosspec -->