Our practices for linking between documents have grown by accretion, and have now reached a point where they're confusing and complicated. They need to be re-thought and re-coded. This is the beginning of a process of thinking through the issue.
This is a list of all the types of linking we do:
- Linking from one document in the anthology to another.
- Linking from one anthology document to a specific anchor in another anthology document (by
@xml:id
). - Linking from one anthology document to
- Linking from an article to a bibliographical reference inside the same article.
- Linking from an article to a bibliographical reference in the central bibliography.
- Linking from a document in the database to an entry in the references files.
These break down into two basic types:
- Linking to other documents in the collection (moving to another page).
- Linking to fragments that should show up as popups inside the current document.
What I propose is this:
For both cases, we need a practice which references other documents (and fragments in them) based on a real model of the database collection structure (which is just a file-system structure). This will enable validation, but because we're using usefully-named collections, it will also enable the processing code to access items efficiently. In the second case, we can rely on XQuery to retrieve and inject all the items we want into the document that's linking to them before processing.
This is what references would look like:
- A biblio reference in an article:
<ref target="../biblio/biblio.xml#timmermans_1993">Timmermanns 1993</ref>
. This points to the bibliography collection (biblio) and the biblio.xml file within it, and identifies the entry which is required. It climbs up the tree one level before going down to /biblio/ because articles are in the /articles/ collection which is a sibling of /biblio/. Here, the processing code can easily retrieve the item through the relative path, and also knows what kind of item it is because it's in the biblio collection; thus we have no need of a type attribute on the<ref>
element. - A link to a reference ("allusions/notes" entry) from a document in the anthology:
<ref target="../../references/references.xml#achelous">Achéloos</ref>
Here, the link comes from a document in /db/anthology/texts_original/ collection; to get to the /references/ collection, we need to go up two levels and then down. The tag identifies the reference as being in the references.xml file. We do have multiple references files, in fact, and occasionally references move from one to another, but the backend processing can be very robust in this situation because it can ignore the file name and simply retrieve the<div>
element with the requisite@xml:id
. - A link from an article to a document in the anthology:
<ref target="../anthology/texts_original/advis_salutaire.xml">Advis salutaire</ref>
Again, we specify the subcollection (texts_original) explicitly for precision's sake, but the processor will know that all anthology documentxml:id
s are unique, so it can construct a relative link in the XHTML based purely on the id. - Linking to a fragment or anchor in another document:
<ref target="../../anthology/images/invention_femmes_2#scalpel">Invention des Femmes (2)</ref>
Here we might actually be linking from within the same collection, but we go up the tree first for absolute clarity. If we go up to the root of the tree every time, we have a degree of robustness to withstand the moving of documents into different subcollections, because we can always assume when processing the URI that the first component of the path is the first subcollection under the base "mariage" collection. Note that this kind of linking requires that the target element have an @xml:id attribute, and that this is converted into an id attribute in the output XHTML. We need to ensure that this is always the case, which may mean restricting the range of elements that are normally linked to, so that the XSLT can be sure to pass through any @xml:id it finds. There are situations in which an underlying TEI element does not result in the generation of an XHTML element in the output, which would preclude the passing through of an attribute because there would be nothing to put it on.
Multiple linking is handled the same way as in these other cases; @target can take multiple space-separated URIs. Of course, this is problematic for processing, since an XHTML link can only point at one location, but we can probably handle this with a "see also" kind of structure that's automatically added after a link where there are multiple targets.
So much for encoding. Next, we need to handle processing and rendering.
For fragments intended to be used as popups, all the content should be retrieved by the XQuery and inserted into a <back>
element of the document. Since there can only be one <back>
element, and the original markup itself might require one (we have no such examples yet, but we may), this many need some rethinking; we may need to insert the content at the end of the <back>
element. Whether or not this content is displayed at the end of the document by default is problematic; we need some simple rules that can be applied both to articles and to anthology documents, and this is by no means easy; but in most cases, notes-allusions information from the references collection will be linked from anthology documents, and bibliographical info will be linked from articles, so we could default to displaying biblios and hiding notes-allusions.
In any case, all types of popup content should be displayed in exactly the same manner, using the same mechanism. Anything else is confusing and fragile. We need one box which shows up on the right, of a reasonable size, scrolling, and position: fixed. Content going into that box should be cloned from the content in the target element; this allows us to leave the original content visible (and printable) at the end of the document while we're also displaying it in the margin.
One issue remains to be solved: inline notes, which are <note>
elements. These also need to be displayed as popups, and ideally they would use the same mechanism. There is a need to link to these notes, however, so they will probably need to be handled differently. They can presumably be rendered inline but hidden, at their original position, and styled to be marginal but not position: fixed; then when they're linked to, they'd automatically pop up through an onload event.
This looks like a plan. It involves considerable changes, but most can be accomplished through search-and-replace or XQuery, and the simpler rules will be easy to teach and give us better XML and a better interface.