[Mirrored from: http://info.admin.kth.se/SGML/Anvandarforening/Arbetsgrupper/HyTime/Reports/tr1v1.html]
Technical Report 1 from the HyTime Working Group, Swedish SGML User's Group, document version identifier TR1V1.
This document has been written by Peter Bergström, EuroSTEP AB, Hasse Haitto, Synex Information AB, Erik Helander, Saab Service Partner AB, Anna Ran, Saab Service Partner AB, and Per-Åke Ling, Ericsson Utvecklings AB on behalf of the HyTime Working Group of the Swedish SGML User's Group. (C)1996 by the authors and the Swedish SGML User's Group (sgml@sunet.se.)
This Quick Guide to HyTime Basics is an easy introduction to HyTime Linking, to enable people and organisations to adapt HyTime linking concepts for their needs.
HyTime, formally known as "Hypermedia/Time-based Structuring Language" ISO/IEC 10744:1992, is a complex and powerful standard. In our experience, it is however quite difficult to read and understand how to use the most basic part of its linking functionality.
This document assumes basic knowledge of SGML. The structure of the document is as follows:
HyTime is an enabling technology: you can describe virtually any kind of connected or temporal information. It covers many different aspects on linking, as well as a full repertoir of features for multimedia purposes, including virtual time, scheduling, synchronisation and so on.
Due to the broad scope of the standard it is quite difficult to get into the standard and understand all details of how links are created. Poeple often ask How do I convert my old documents to HyTime? or Does it have to be so complex to create links?. In this document we will try to answer those questions, and provide the reader with a good basic knowledge of hyperlinks using HyTime, in order for him to continue the exploration of the standard on his own, because support for these features is readily available.
HyTime is described in the form of "cookbook" element forms, as recipes for general construct. Because of this, HyTime is sometimes called a meta-DTD: Its SGML constructs should be used as templates. Contrary to an existing DTD or tag naming scheme, HyTime lets you define the names (generic identifiers, or GIs) of element types freely. This is possible through a specific HyTime attribute that is assigned the name of the corresponding HyTime element template. The HyTime attribute lets a HyTime-aware application recognize and apply to the element any particular processing associated with the specific HyTime construct. This simple yet powerful idea is fundamental to HyTime; it is called an architectural form or enabling architecture. A HyTime engine can be regarded as an SGML parser that understands the processing required for HyTime attributes.
As you may freely add other attributes for your own purposes, the architectural form is rather like a super-class with single inheritance, to use object-oriented terminology. A recent change to HyTime (the so-called HyTime corrigendum) extends HyTime with multiple inheritance.
Historically, many hypertext systems and notations have not differentiated between a link and its connected endpoints (the locations or anchors). Rather, the link information has been treated as a logical whole: any editing change affects the entire linking construct. Also, the hypertext terminology has not been used consistently, so that what constitutes a link anchor can be anything from an entire document to a selected span of a few words, or a chunk of information on a card, depending on the hypertext system. The fineness of granularity of the addressed information has thus varied.
HyTime makes a distinct difference between links and locations. A link is a reference between two or more locations. A location is the address of a potential anchor point, which is the actual, physical point where the link ends.
This step of indirection can first be regarded as an extra level of complexity to the links, but as soon as you try to create documents with hyperlinks between them, you will notice that it is very hard to maintain and update hyperlinks without this step of indirection. The locations in HyTime are one of the basic building blocks that make HyTime such a powerful standard.
HyTime brings about a consistent way of describing hyperlinks between any media. As HyTime builds upon SGML, it is especially powerful for hypermedia documents encoded using this standard.
Linking in SGML is achieved by assigning ID attributes to elements and reference these through an IDREF or IDREFS attribute. This kind of linking is restricted to work within one and same document because of the way SGML is defined.
Although HyTime is based entirely on SGML, it transcends the limitations of SGML linking and extends it forcefully. HyTime defines but two link constructs, one of which is a special case of the other. The richness of HyTime linking lies in the many ways one can describe locations in document, often as a sequence of stepwise refined addresses known as location ladders.
Let's first have a look at a traditional SGML reference to a table in one and same document:
<p>The population in the major cities of Sweden is described in <xref idref="tab21"> <tbl id="tab21"> <tbltitle>Population in the major cities of Sweden</tbltitle> <body>.......
The contextual link or clink (pronounced see-link) is the simpler of the HyTime link constructs. One of its anchors ("the context") is part of the document where the link markup resides. The other endpoint can be in the same or somer other document. The clink is rather common as it aptly describes traditional cross-references.
Using clink, one of the anchors is part of the document contents.
The clink markup is defined as follows.
<!element clink -- Contextual link -- - O (%HyBrid;)* > <!attlist clink HyTime NAME clink id ID #IMPLIED -- Default: none -- linkend -- Link end -- -- Constraint: No HyTime reftype constraints, but application designers can constrain element types with reftype attribute -- IDREF #REQUIRED >
The SGML reference in the example above is easy to convert to a HyTime clink in a two step procedure. First, add a HyTime attribute to the element type xref in the DTD:
<!ELEMENT xref - o EMPTY> <!ATTLIST xref ref IDREF #REQUIRED HyTime NAME "clink" HyName NAMES "linkend ref"
The HyTime attribute tells the HyTime engine that this element is a HyTime clink element, and the HyName attribute can be used to map the ref attribute to the attribute name linkend, which the HyTime engine interprets and understands.
Secondly, trigger the HyTime engine: Formally, the SGML declaration needs to contain additional data for this processing to take place; however, this requirement is not enforced by current end-user applications. One such requirement is the HyTime statement in the APPINFO section of the SGML declaration:
APPINFO "HyTime"
Just as the SGML declaration provides information for the SGML parser, HyTime-specific declarations inform the HyTime engine what parts of HyTime that will be used in the DTD. The HyTime declarations take the form of processing instructions prior to the DTD:
<?HyTime VERSION "ISO/IEC 10744:1992" HYQCNT=32 > <?HyTime MODULE base > <?HyTime MODULE locs > <?HyTime MODULE links >
These declarations make all references behave as HyTime clinks, without changing anything in the document markup. The required HyTime declarations have been revised in the HyTime corrigendum so that there now is an alternative to processing instructions. How to make existing SGML documents conform to HyTime is explained in more detail below.
Below is a clink that emanates from the first paragraph and points to the element with the ID attribute whose value is id17.
<P>This <clink linkend=id17>clink</clink> is linked to an element whose id is the value assigned to the linkend attribute.</P> ... <P ID=id17>This paragraph is a target of a clink from the previous paragraph.</P>
The independent link or ilink (pronounced eye-link) permits the link data to be stored externally, separate from the document(s) that the link markup connects. One can thus make changes to the link data without modifying the documents being linked.
In this ilink, the ID attributes XYZ and ABC reference elements with addressing data locators, illustrating the separation of links from the addressing anchor.
The HyTime links are complemented by rich addressing schemes that specify locations down to (virtually) any granularity. The location addresses can be defined using different methods. Two of the most common address entire elements:
To transcend the granularity of the markup, one can use a counting addressing scheme:
A dynamic method of addressing is through queries, where the exact location is not known but resolved through matching against properties, it in real time. HyTime defines a query language (HyQ) which has since been superseded by the DSSSL query language (SDQL).
The separation of links from anchors make it possible to have links between any kind of media, such as musical notes--assuming an addressing mechanism for referencing within the notation.
Instead of letting links point directly to target elements, one can point out a locator. HyTime thus supports indirection, where the ultimate link target is resolved in a series of steps.
The element type form named location address or nameloc contains one or several nmlist elements, where the nmlist element contains of one or several names. The names are either entity or element names (actually, ID attribute values). The nameloc element locates all of these elements. Links to entities are considered as links to the root element of the entity document.
Typical declarations take the following form:
<!ELEMENT nameloc ... > <!ATTLIST nameloc HyTime NAME "nameloc" id ID #IMPLIED > <!ELEMENT nmlist ... > <!ATTLIST nmlist HyTime NAME "nmlist" nametype (entity|element) element docorsub ENTITY #IMPLIED >
If the nametype attribute of nmlist has the value entity the element content is interpreted as entity names. Each name should then have a corresponding ENTITY declaration (unless it is implicitly defined by a #DEFAULT entity declaration). The target is interpreted as the root element of the named document.
If the nametype attribute of nmlist has the value element, its content is interpreted as element names, i.e. IDs, whose location depend on the document entity defined by the attribute docorsub. If docorsub is implied, it defaults to the document containing the nmlist element.
To make a cross-document reference to an entire document (i.e., an external entity), the document should contain the following declarations:
<nameloc id="locid"> <nmlist nametype="entity">docref</nmlist> </nameloc> ...The target document is identified by the entity docref. In the document instance, one would have markup such as:
See also the <clink linkend="locid">related document</clink> ...
The clink spanning the string "related document" is a hypertext link to the docref entity, where the clink is resolved to the nameloc with the id locid. In the nameloc, the nametype attribute of the nmlist element is declared as an entity: the contents of the nmlist ("docref") is thus an entity.
The next sample markup is a cross-document reference to an element with the ID eid in the docref entity:
... <nameloc id="locid"> <nmlist nametype="element" docorsub="docref"> eid </nmlist> </nameloc> ... See also the<clink linkend="locid">related section</clink> ...
The clink spanning "related section" points to the element with an ID attribute with the value eid in the document corresponding to the docref entity.
You can have any numbers of names in an nmlist element, and any number of nmlist elements in an nameloc element.
Just as SGML allows for multiple link endpoints, the same effect can be achieved using a clink to a nameloc:
<nameloc ID=re-nmloc> <nmlist nametype=element>first.para also amazing</nmlist> </nameloc> ... <P>Here's a reference to <clink linkend=re-nmloc>three paragraphs</clink> in the section "Multiple IDREFS links" above. </P>
As nameloc addressing pre-supposes the existence of an ID
attribute, how do you address other elements? Because the SGML markup
is hierarchical--elements either contain one another entirely or are
disjunct--the document can be viewed as a
The tree structure can be referred to using the HyTime construct treeloc, whose content describes a path along siblings. However, elements whose content model is mixed content (which allows for both #pcdata and elements) make treeloc addressing more complex than is readily apparent: each portion of data content becomes a pseudo element, that counts as an element in the tree. The somewhat confusing handling of line breaks complicates the picture further. For this reason, treeloc addressing is best suited for programs to generate.
The example below creates a treeloc link to the element target. The treeloc addressing is necessary since the target element does not have an ID attribute.
... <chapter id=chp3> <title>Chapter 3</title> <para>The treeloc link ends <target>here!</target> </para> ... <treeloc id=treeloc.demo locsrc=chp3> <marklist>1 2 2</marklist> </treeloc> ... This is a <clink linkend=treeloc.demo>clink that uses treeloc addressing</clink> ...
Because they are based on the SGML markup, the granularity of the previous addressing mechanisms is equal to the granularity imparted by the content markup.
The data location address or dataloc architectural form is used to refer to content within elements, by counting tokens such as words: typically, an offset into the element, and a number of subsequent tokens.
The example below creates a link to the word "HERE" by specifying an offset of five words and then counting one word. The dataloc addressing is necessary since no element markup encapsulates the target.
... <para id=target> The dataloc link ends HERE </para> ... <dataloc id=dataloc.demo locsrc=target> <dimlist>5 1</dimlist> </dataloc> ... This is a <clink linkend=dataloc.demo>link that uses dataloc addressing</clink> to transcend the markup boundaries. ...
A dataloc element contains a dimlist element. The dimlist element contains two integers. The first integer specifies the number of tokens to the beginning of the target, the second its size (in number of tokens).
Typical declarations have the form
<!ELEMENT dataloc (dimlist*) > <!ATTLIST dataloc id ID #IMPLIED locsrc IDREF #IMPLIED quantum (norm) norm HyTime NAME "dataloc" > <!ELEMENT dimlist (#PCDATA) > <!ATTLIST dimlist HyTime NAME "dimlist" >
The locsrc attribute specifies the start location of the dataloc address. Locsrc can in turn point at a HyTime location address. If locsrc is implied, the beginning of the source document is used.
HyTime specifies several other counting strategies, and ways of specifying the counting direction (such as counting backwards, from the end of the element).
As HyTime linking and addressing are based on indirection, one can use a sequence of locators to create durable links. A typical such location ladder might consist of a clink referring to a nameloc, addressing a treeloc, addressing a dataloc.
There is no need to scratch your head and start counting hours before your documents are HyTime conformant with respect to linking within documents. Here we will show how easy it is to make existing documents HyTime conformant.
There are several ways to convert existing documents to HyTime; which one suits you is dependent on the nature of the source documents, and on your knowledge of HyTime. In the text that follows, we assume that we are dealing with SGML documents and links within single documents.
We will assume that the links in the documents are constructed using the standard ID-IDREF mechanism. This means that the target element of the link must contain an attribute of type ID. See the example below:
<!-- reference somewhere in the text --> <para>For more information, see <ref refto=3D"explanation2"></ref> below.</para> <!-- explanations in some other place in the document --> <explanation explid=3D"explanation1">Words...<explanation> <explanation explid=3D"explanation2">More words...<explanation>
The key to this simple conversion is that the actual change takes place in the DTD. You do not really have to edit the source (i.e. the documents), because you add fixed values to the attributes of the reference elements.
Here is a fragment of a DTD that could be used for the document above.
<!-- DTD fragment --> <!ELEMENT text - - (para*) > <!ELEMENT para - - (#PCDATA | ref)* > <!ELEMENT ref - - (#PCDATA) > <!ELEMENT explanation - - (#PCDATA) > <!ATTLIST ref refto IDREF #REQUIRED > <!ATTLIST explanation explid ID #REQUIRED >
We will now add what is needed for the clink construction in the DTD.
<!-- DTD fragment --> <!ELEMENT text - - (para*) > <!ELEMENT para - - (#PCDATA | ref)* > <!ELEMENT ref - - (#PCDATA) > <!ELEMENT explanation - - (#PCDATA) > <!ATTLIST ref refto IDREF #REQUIRED HyTime NAME #FIXED "clink" HyNames NAMES #FIXED "linkend refto"> <!ATTLIST explanation explid ID #IMPLIED >
As you see, the only changes are two extra lines in the attribute list of the element ref.
Today you have to add some application information between the SGML declaration and the DTD. This information can be added at the end of the file containing the SGML-declaration or it can be put before the reference to the DTD in the document instance if there is a reference. The APPINFO section in the SGML declaration is also changed.
FORMAL Yes APPINFO "HyTime"
The whole transformation does also require an application that understands the concepts of HyTime--at least the clink construction, in order to resolve and use the linking functionality. There is no need for a fully complient HyTime engine. It is in most cases enough with the capabilities of the API of your current SGML-aware system.
This section briefly points out that you can have all your documents as is, creating hyperlinks within (or between) any document using a HyTime hub document as a map of all the links.
Please refer to documents describing more about HyTime ilinks to see the correct syntax and examples. This section will only describe the ideas of hyperlinking from a hub document.
Since there in HyTime are several different accessing methods to the "targets" of your links, you can always pinpoint any kind of information in the documents. It may be an element, a word or some pixels in a bitmap.
In this case we are interested in going from an existing pointer (an element) to the element it refers to. In the example above this would mean a reference from the element ref to the element explanation.
The HyTime hub document merely consist of the HyTime ilinks, which are used to create the links between HyTime namelocs, which in their turn points to the "targets" in the document(s).
A HyTime engine reads the hub document and processes the links, which in the end are presented by the application as hotspots, underlined words or whatever. All the specific HyTime processing will take place without us having to make any changes to the existing documents.
It is very easy to make your ID-IDREF links in your documents comply with the HyTime standard. There is not much work involved and your environment will not have to change.
The benefits are immediate, you have made your documents and linking more robust. Adding more HyTime constructs, such as HyTime ilinks, is a logical next step. With HyTime, your documents will be better prepared for the next century.