Print

Print


>I'm encoding a technical document where an item of the following
>form appears:
>
><hi rend="typewriter">/dev/rdsk/c0t0d0sc</hi>
>
>After this, there is a list which explains the components of
>this item.  The enumerators of this list are the letters
 
><list>
><item n="c">The SCSI Host Bus Adapter</item>
><item n="t">The target ID on that bus</item>
>
 
[... stuff deleted]
 
Presumably the fact that /dev/rdsk/c0t0d0sc appears in a typewriter font is not
the most important thing about it. My guess is that you're more interested in
the fact that it is a filename of a particular sort, the components of which
are abbreviations that can be linked to the members of the list. Leaving that
aside just for the moment, I would think you'd get more mileage out of an
encoding the filename *as a filename*.
 
Using TEI P3 you would have to do this as
  <name type=filename>/dev/rdsk/c0t0d0sc</name>
or
  <rs type=identifier>/dev/rdsk/c0t0d0sc</rs>
as there is no specific element for these features in P3. Using TEI Lite, you
could use the element IDENT which is defined for exactly this purpose in that
dtd.
 
In either case, you could then leave it to the application to decide to format
identifer names in typewriter, or arial, or in red with a nice frame round them
or whatever. You could also write a neat application which would pick out all
the filenames and change them to some other format for when you have to migrate
the system being documented to some other platform.
 
Encoding the list could be done in a number of ways. The crucial decision is
what exactly you consider the enumerators to be. (All tagging questions are
ontological ones)
 
If they are simply enumerators, then you don't care what they look like and
your proposed use of the N attribute is appropriate.
 
If they are simply enumerators, but you do care what they look like, then you
should use the <label> element with or without a REND attribute, as Nancy Ide
suggests. (Note, by the way, that labelled lists can be organized either
<list type=gloss>
<label>c</label><item>The SCSI Host Bus Adapter</item>
<label>t</label><item>The target ID on that bus</item>
</list>
or
<list type=gloss>
<item><label>c</label>The SCSI Host Bus Adapter</item>
<item><label>t</label>The target ID on that bus</item>
</list>
This is one of several things I now consider suboptimal about the <list> tag)
 
If they are really abbreviations only incidentally being used as enumerators,
you could use the <abbr> element, either alone or within a <label>
 
<list type=gloss>
<item><label><abbr>c</abbr></label>The SCSI Host Bus Adapter</item>
<item><label><abbr>t</abbr></label>The target ID on that bus</item>
</list>
 
Finally, why not show that there's a link between the letter used as the label
and the letter in the filename? To do this we must be able to address both the
content of the <ident> element containing the filename, and the <label> element
in the <list>. A rather neat  way of doing this is to use the TEi extended
pointer syntax.
 
We start by adding <xptr> elements. Assuming that the <ident> element has been
given the identifier GRACKLE (i.e. it is tagged <ident
id=GRACKLE>/dev/rdsk/c0t0d0sc</ident>) and we want to point at the "c" which is
its 11th character, here's one:
 
<xptr id=G11 from='id (GRACKLE) str(11,1)'>
 
Let's also add an <xptr> indicating the "C" used as a label identifier. We'll
assume this time that only the list has an identifier, say ZARNIEWHOOP. It
looks like this
 
<xptr id=Z2 from='id (ZARNIEWHOOP) child (1 item) child (1 label) child (1
abbr)'>
 
This might be read "the first <abbr> contained by a <label> which is the first
<label> contained by an <item>, which is the first <item> within an element
whose identifier is ZARNIEWHOOP". Relax, it's easier than reverse polish.
 
Now we want just to indicate that the thing that the <xptr> called Z2 is
pointing at, and the thing that the <xptr> called G11 are pointing at are to be
linked in some way. The element for doing this is called .... <link>, and looks
like this
 
<link targets='Z2 G11'>
 
Now to the big question. What can you do with it, now you've gone to all this
trouble? Well, an application can now very easily generate a hotlink, so that a
user can click on either the label of the list item,  or the letter of the
filename) to jump to the other. And you have made explicit to all and sundry
why on earth the first two items of your list are labelled C and T !
 
In need of a G and T,
 
Lou