8 Hyperlinks module

8.2.1 Hyperlink

The element form hyperlink (hylink) is a hyperlink whose location in a document need have no relation to the location of its anchors. The significance of the location (if any) is determined by the application.

NOTE 235 A hylink can be used in situations where it is not possible to modify the anchors (perhaps because there is no write access). If there are two anchors and one can be modified, it may be more convenient to use a contextual link.

NOTE 236 Link types that could be independent links include external thesauri and indexes, indicators of various kinds of alternative versions, and graphical user interface objects, such as menus and radio button sets.

NOTE 237 One useful application of hyperlinks that could be modelled on the hylink form is known as a "property link". It allows a value of a specified property type to be associated with a location, as when a collaborative author or reviewer is annotating a document. There are two anchors: the "subject", which identifies the location with which the property is being associated, and the "property value", which identifies the value of the property. The traversal rules must at least permit traversal to begin from the subject and return from the property value, although a designer could choose to make the link bidirectional.

The attribute anchor roles (anchrole) identifies the number of anchors by specifying a role name for each. The same role name cannot be used for more than one anchor (enabling addressing of anchors by anchor role name). The number of anchors can exceed two only if the "manyanch" option is supported and is specified with no value or a value greater than "2". The anchor roles must be constant in a client document. Each anchor role name can be followed by either of the following keywords:

#LIST

The anchor is a "list anchor": the anchor may be a node list of one or more nodes.

#CORLIST

The anchor is a "correspondent list anchor": the anchor may be a node list of one or more nodes. In addition, for each member of a correspondent list anchor, there must be a corresponding member in all the other correspondent list anchors of the same hyperlink. If there is only one #CORLIST anchor, it is treated as a normal #LIST anchor.

Anchors that are not list anchors are "singleton anchors" and may only resolve to a single node.

For each anchor role (except self anchors), there must be an attribute whose name is the name of an anchor role and that is a referential attribute. Each such attribute addresses, directly or indirectly, the members of the anchor with that role. These attributes are referred to generically as the "anchor addressing attributes" of the link.

8.2.2 Contextual link

The element form contextual link (clink) represents the most common form of generic cross reference. The clink form is derived from the hylink form.

NOTE 244 Any hyperlink may, potentially, be "contextual" by using itself as one of its anchors and making that anchor a traversal initiating anchor.

The link type of a contextual link expresses the type of reference. There are two anchor roles: the "reference mark" (named "REFMARK"), which is the link element, and the "reference subject" (named "REFSUB"), which is identified by the attribute reference subject (refsub). The reference subject can be a list.

NOTE 245 The contextual link is an optimization of the configuration of hylink that occurs most frequently in conventional documents; it can model such common reference elements as footnote references and figure references. If more complex configurations are wanted (such as more anchors), the hylink element form can be used.

The reference mark can be empty if it is simply a point in the document, rather than an object.

8.2.3 Aggregation link

The element form aggregation link (agglink) represents the grouping of a list of nodes into an "aggregate". The aggregate represents the list of members as a whole, providing the semantic that the list of members can be treated as a single object.

NOTE 247 In particular, aggregate links can be members of list anchors, enabling the representation of "nested" lists or cascading menus.

An agglink has two anchor roles, the "aggregate" (agg) and "members of the aggregate" (members).

NOTE 248 An aggregation link is not a location address. Therefore a reference to an agglink element is always a reference to the element itself, not the members of the members anchor.

                      <!-- Aggregation Link -->
<![ %agglink; [
<!element
   agglink        -- Aggregation link --
                  -- Clause 8.2.3 --
   - O
   (%HyCFC;)*

-- Attributes [links]: agglink
-- OptionalAttributes [links]: traverse --
-- CommonAttributes [GenArc]: dafe, dvlatt, etfullnm, id,
   ireftype, lextype, opacity --
-- CommonAttributes [base]: activity, conloc, dtxtatt, valueref --
-- CommonAttributes [locs]: refctl, refloc, reftype, rflocspn --
>
<!attlist
   agglink        -- Aggregation link --
                  -- Clause 8.2.3 --

   HyBase   NAME     #FIXED hylink
   anchrole CDATA    #FIXED "agg members #LIST"
   anchcstr NAMES    "self required"
   loctype  CDATA    "members IDLOC"

   members        -- Members of aggregate --
      CDATA       -- Reference --
                  -- Note: Because members is by default given the
                     location address type IDLOC, its value is
                     interpreted by default as if it were IDREFS,
                     though the interpretation can be changed by
                     specifying a different value for the loctype
                     attribute. --
      #IMPLIED    -- Default: omitted or conditional --
                  -- Constraint: if left unspecified, must specify
                     COND in anchcstr --
>
]]><!-- agglink -->

8.2.4 Variable link

The element form variable link (varlink) represents hyperlinks in which the anchor roles need not be constant for a given link type.

Rather than individual anchor-addressing attributes, the varlink form uses anchor specification (anchspec) subelements to define each anchor role and address the members of that anchor. The content of the anchspec element contains the address of the anchor. The attribute anchor role (anchrole) specifies the anchor role name. If no anchrole attribute is specified, the element type of the anchspec element is used as the anchor role. If multiple anchspec elements in a single varlink exhibit the same anchor role, the nodes they address are combined to form a single list of members for that anchor, listed in the order the anchspec elements occur within the varlist. The number of anchors can exceed two only if the "manyanch" option is supported and is specified with no value or a value greater than "2".

The attribute may anchor have multiple members? (multmem) indicates whether or not the anchor allows multiple members (list), multiple members that correspond to members in other anchors (corlist), or only a single member (single). If multiple anchspec elements in a single varlink have the same anchor role, they must specify the same value for multmem, either "list" or "corlist".

The other attributes are as defined for the hylink element form.

The varlink element may be a self anchor, indicated by specifying a value for the anchrole attribute of the varlink element form.

For the purposes of associating anchor roles with link types, the link type associated with a given varlink element type is the union of all anchor role names used for that element type in a single document (e.g., as though all the anchor roles had been explicitly declared and given an anchor existence constraint of "OMIT").

            <!-- Variable Link -->
<![ %varlink; [
<!element
   varlink        -- Variable link --
                  -- Clause: 8.2.4 --
   - O
   (anchspec)+

-- Attributes [links]: ancspcat, varlink, vartrav --
-- CommonAttributes [GenArc]: dafe, dvlatt, etfullnm, id,
   ireftype, lextype, opacity --
-- CommonAttributes [base]: activity, conloc, dtxtatt, valueref --
-- CommonAttributes [locs]: refctl, refloc, reftype, rflocspn --
>
<!element
   anchspec       -- Anchor specification --
                  -- Clause: 8.2.4 --
   - O
   (%HyCFC;)*     -- Reference --
                  -- Note: Use of refloc facility required --

-- Attributes [links]: anchspec, ancspcat, vartrav --
-- CommonAttributes [GenArc]: dafe, dvlatt, etfullnm, id,
   ireftype, lextype, opacity --
-- CommonAttributes [base]: activity, conloc, dtxtatt, valueref --
-- CommonAttributes [locs]: refctl, refloc, reftype, rflocspn --
>
<!attlist
   anchspec       -- Anchor specification --
                  -- Clause: 8.2.4 --

   multmem        -- May anchor have multiple members? --
      (single|list|corlist)
      single

   emptyanc       -- Is empty anchor an error? --
      (error|noterror)
      error
>

<!attlist
-- ancspcat --    -- Anchor specification attributes --
                  -- Clause: 8.2.4 --
   (anchspec,varlink)

   anchrole       -- Anchor role --
      NAME
      #IMPLIED    -- Default: for anchspec, anchor role is GI of element --
                  -- Default: for varlink, varlink is not self anchor --
>
<![ %traverse; [
<!attlist
-- vartrav --     -- Varlink traversal rules --
                  -- Constraint: ignored on varlink element if it is
                     not a self anchor --
   (anchspec,varlink)

   linktrav       -- Hyperlink traversal rules --
                  -- Traversal between anchors of hyperlinks:
                       A  any traversal or departure (EID)
                       D  departure after internal arrival
                       E  traversal after external arrival
                       I  traversal after internal arrival
                       N  no traversal after internal arrival
                       P  no internal arrival
                       R  return traversal after internal arrival --
      (A|EI|ER|ED|EN|EP|ERD|I|ID|D|N|P|R|RD)
      A

   listtrav       -- List traversal rules --
                  -- Traversal between members of list anchors:
                       A  adjacent (both left and right) traversal
                       L  left traversal
                       N  no traversal
                       R  right traversal
                       W  wrapping traversal --
      (A|AW|L|LW|N|R|RW)
                  -- Constraint: ignored if anchor is not a list --
      N
>
]]><!-- traverse -->
]]><!-- varlink -->

8.2.5 Independent link

The element form independent link is a hyperlink that uses a single IDREFS attribute to address its anchors. The ilink form is semantically identical to hylink but provides an alternative syntax for addressing its anchors.

The attribute anchor roles (anchrole) identifies the number of anchors by specifying a role name for each. The same role name cannot be used for more than one anchor. The anchor roles must be constant for a given link type in a client document.

The keyword "#AGG" is a synonym for "#LIST".

NOTE 249 The "#AGG" keyword is provided for existing ilink elements.

The number of anchors can exceed two only if the "manyanch" option is supported and is specified with no value or a value greater than "2".

Each ID specified by the linkends attribute is associated with the corresponding anchor role name specified by the anchrole attribute, in the order specified in the source document.

NOTE 250 An application designer can constrain the element types of the anchors by means of a reftype attribute.

The ilink element itself can be designated as an anchor by specifying the element's ID as a link end or by specifying exactly one fewer IDs than there are anchor roles, in which case the ilink element is taken to be its own first anchor (equivalent to using an anchor existence constraint of SELF for the first anchor).

                      <!-- Independent Link -->
<![ %ilink; [
<!element
   ilink          -- Independent link --
                  -- Clause: 8.2.5 --
   - O
   (%HyCFC;)*

-- Attributes [links]: ilink --
-- OptionalAttributes [links]: traverse --
-- CommonAttributes [GenArc]: dafe, dvlatt, etfullnm, id,
   ireftype, lextype, opacity --
-- CommonAttributes [base]: activity, conloc, dtxtatt, valueref --
-- CommonAttributes [locs]: refctl, refloc, reftype, rflocspn --
>
<!attlist
   ilink          -- Independent link --
                  -- Clause: 8.2.5 --

   anchrole       -- Anchor roles --
      CDATA       -- Lextype: (NAME,("#AGG"|"#LIST"|"#CORLIST")?)+ --
                  -- Constraint: one per anchor --
      #REQUIRED   -- Constant --

   linkends       -- Link ends --
      IDREFS      -- Reference --
                  -- Constraint: One ID per anchor role, except
                     that the first ID may be omitted if the first
                     anchor is the link element itself. --
      #REQUIRED
>
]]><!-- ilink -->