new section for P4 on HTML linking

Sat Mar 9 10:40:33 EST 2002

As actioned in London, I have now drafted some extra text for the
chapter on external linking to document how HTML-style linking
should be represented in TEI documents. Comments from the Council
would be much appreciated: though the window for change is VERY SMALL!

There is much that could be added, obviously, but I think this is a bare
minimum which is at least not actually wrong.

I have not yet updated the website/s with this new material, or the other
revisions I hope to complete this weekend but that should happen early
next week

Lou

---------

I have added the following paragraph at the end of the section
introducing the extended pointer syntax (i.e. immediately before the
start of 14.2.1)

---
<p>The most widespread application of such external document linking
is, of course, provided by the World Wide Web. The original version of
these Guidelines did not provide specific guidance concerning the
representation of simple HTML linking in TEI, since the Guidelines
predate the wide take-up of HTML as a means to this end. For the
present edition, a brief note on recommended ways of providing this
capability in TEI documents has been added below (<ptr target="SAHTML"/>).
---

<p>and the following subsection 14.2.4 following the current 14.2.3

<p>---

<div3 id="SAHTML"><head>Representation of HTML links in TEI</head>

As we have indicated, linking to another document (in any format)
should be done by means of the <gi>xref</gi> or <gi>xptr</gi> element,
the former being used if some text is to be supplied to identify the
title of the intended link, the latter if it is not. HTML documents
may also be linked to in this way. In either case, it is the
responsibility of the processor to determine what the target URL for
the link should be. In canonical TEI, this target must be supplied as
a predefined external entity, the name of which is supplied as the
value of the <att>doc</att> attribute on the pointer element
concerned:

<eg><![CDATA[
<p>This is discussed in <xref doc="TEIP3">The TEI Guidelines</xref>
</p>
]]></eg>
or, equivalently,

<eg><![CDATA[
This is discussed in <xptr doc="TEIP3"/>

]]></eg>

In either case, the DTD must also include a declaration for the
external entity <ident>TEIP3</ident>, which a processor can use to determine
the intended URL, such as the following:
<eg><![CDATA[
<!ENTITY TEIP3 SYSTEM "http://www.tei-c.org/TEI/Guidelines/" NDATA HTML>
]]</eg>

The target of a link of this kind must always be a
complete document. If it is desired to link to some element within the
target HTML document, the <att>from</att> attribute may be used to
specify its identifier:
<eg><![CDATA[
This is discussed in <xref doc="TEIP3" from="id(SAPT)">The
chapter on linking</xref>

]]></eg>
This is equivalent to the following HTML link:
<eg><![CDATA[
This is discussed in <a
href="http://www.tei-c.org/TEI/Guidelines/#SAPT">the chapter on
linking</a>
]]></eg>

and assumes that somewhere in the target document there exists an
<gi>a</gi> element whose <att>name</att> attribute has the value
<code>SAPT</code>, which will be the target of the above URL. (If the
target is an XML document, then the assumption is that there exists
somewhere within it an element whose <att>id</att> attribute has the
value <code>SAPT</code>) Note that it is illegal to supply a URL like
the example above as value for an external entity.

The requirement to predefine all target URLs as external entities
has some obvious advantages, from the point of view of simplifying the
maintenance of a suite of reliable links. It may be easier to
maintain a single document containing declarations for all external
links than to search through a large suite of documents checking that
each link is still valid. However, it may also be regarded as an
unnecessary additional chore; it also depends on the ability to define
and embed external entity declarations, which may not be appropriate
in an XML processing environment.

For these reasons, TEI encoders may wish to declare an additional
attribute <att>url</att> for the elements <gi>xptr</gi> and
<gi>xref</gi>. Since in XML it is permissable to add attributes to an
existing element by means of an additional ATTLIST declaration, all
that is needed is to provide a DOCTYPE declaration like the following:

<eg><![CDATA[
<!DOCTYPE TEI.2 PUBLIC "" ""[
<!ENTITY % TEI.prose "INCLUDE">
<!ENTITY % TEI.linking "INCLUDE">
<!ATTLIST %n.xptr; url CDATA #IMPLIED>
<!ATTLIST %n.ref; url CDATA #IMPLIED>
]>
]]></eg>
</p>
<p>A document with these additional declarations can then simply
specify the intended target of a cross-reference using the new
<att>url</att> attribute without further formality:
<eg><![CDATA[
<p>This is discussed in <xref url"http://www.tei-c.org/TEI/Guidelines/#SAPT">the chapter on
linking</xref>
]]></eg>
</p>
<p>This extension is not currently a formal recommendation of the TEI
Guidelines. Its use is not recommended in documents intended for
interchange.
</p>
<p>It is often convenient to specify the URL from which a document is
canonically available within the document itself. This should be done witin the
<gi>publicationStmt</gi> of the document's TEI Header (<ptr
target="HD24"/>) as in the following example:
<eg><![CDATA[
<publicationStmt>
<distributor>Made available by the  TEI Consortium
at <a href="http://www.tei-c.org/Guidelines</distributor">http://www.tei-c.org/Guidelines</distributor</a>>
</publicationStmt>
]]></eg>
or, equivalently, any of the following:
<eg><![CDATA[
<!-- assuming availability of URL attribute -->
<publicationStmt>
<distributor>Made available by the  TEI Consortium
at <xptr url="http://www.tei-c.org/Guidelines"/></distributor>
</publicationStmt>
<!-- assuming pre-declaration of TEIP3 external entity -->
<publicationStmt>
<distributor>Made available by the  TEI Consortium
at <xptr doc="TEIP3"/></distributor>
</publicationStmt>
]]></eg>
</p>
</div3>
---