Table of Contents
If you are new to markup languages, or if you are unfamiliar with acronyms such as XML, RDF, XPath, or technical terms such as Unicode, you should start with this chapter, which uses a simple example to illustrate the steps typically taken to create and edit TAN files. By the end, you will have a sense of how to create and edit a simple collection of TAN transcriptions and alignments. If you are familiar with basic markup concepts, you may wish to read through the chapter very quickly, or skip it altogether.
The discussion touches on a number of general concepts that will be introduced only briefly. If you find the concept new or confusing, follow the prompts for further reading to get better grounded in a particular topic or technology.
Let us take a simple example, that of aligning two English versions of the nursery rhyme Ring-a-ring-a-roses, sometimes known as Ring around the Rosie. Our goal here is to publish two versions of the nursery rhyme in the TAN format so that they are most likely alignable with any other TAN version of the poem that someone might create.
We begin by finding previously published versions. In this case we have taken an interest in the versions published in 1881 and 1987 (one published in the UK and the other, the US). Each of these books have other rhymes, but we've already decided to focus upon the one particular nursery rhyme, so we transcribe those parts and nothing else:
Table 2.1. Ring around the Rosie
1881 (UK) version | 1987 (US) version |
---|---|
Ring-a-ring-a-roses, A pocket full of posies; Hush! Hush! Hush! Hush! We're all tumbled down. |
Ring-a-round the rosie, A pocket full of posies, Ashes! Ashes! We all fall down. |
We must be sure to save each of the two transcriptions as plain text, preferably
with .xml
at the end of each file name. Do not bother with word
processor (Word, OpenOffice, Google Docs, and so forth), because those programs are
too sophisticated for our work. They sometimes generate erroneous data, even when you
export to plain text. We will not be concerned with italics, colors, fonts, margins,
and so forth, so much better for our work is a text editor, which
works only on plain text. But even those do not check to see if the rules of the
format have been followed. So the best tool is an XML editor, which does
the same thing a text editor does, but saves much typing and prevents syntax errors.
More important, an XML editor will tell us when our TAN file is invalid, and will
provide information and help in our TAN files.
Note | |
---|---|
Software suitable for your needs comes in many styles and prices. In addition to the links in the paragraph above, you may wish to visit the comparative lists for both text editors and XML editors. TAN was developed using oXygen, which is very powerful but possibly confusing to new users. To avoid exasperation or despair, take advantage of tutorials and documentation associated with the XML editor you have chosen. |
Our first task is to get these two versions into separate files with the appropriate markup. Each TAN transcription file has two major parts: a head and a body. For now, we focus on only the second part, the body, as well as a few the necessary preliminary lines that stand above both the head and the body. First, the 1881 (UK) version:
<?xml version="1.0" encoding="UTF-8"?> <?xml-model href="http://textalign.net/release/TAN-2018/schemas/TAN-T.rnc" type="application/relax-ng-compact-syntax"?> <?xml-model href="http://textalign.net/release/TAN-2018/schemas/TAN-T.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?> <TAN-T xmlns="tag:textalign.net,2015:ns" id="tag:parkj@textalign.net,2015:ring01"> <head> . . . . . . . </head> <body xml:lang="eng" in-progress="false"> <div type="line" n="1">Ring-a-ring-a-roses,</div> <div type="line" n="2">A pocket full of posies;</div> <div type="line" n="3">Hush! Hush! Hush! Hush!</div> <div type="line" n="4">We're all tumbled down.</div> </body> </TAN-T>
And now the 1987 (US) version:
<?xml version="1.0" encoding="UTF-8"?> <?xml-model href="http://textalign.net/release/TAN-2018/schemas/TAN-T.rnc" type="application/relax-ng-compact-syntax"?> <?xml-model href="http://textalign.net/release/TAN-2018/schemas/TAN-T.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?> <TAN-T xmlns="tag:textalign.net,2015:ns" id="tag:parkj@textalign.net,2015:ring02"> <head> . . . . . . . </head> <body xml:lang="eng" in-progress="false"> <div type="l" n="1">Ring-a-round the rosie,</div> <div type="l" n="2">A pocket full of posies,</div> <div type="l" n="3">Ashes! Ashes!</div> <div type="l" n="4">We all fall down.</div> </body> </TAN-T>
These are standard eXtensible Markup Language (XML) files. (If you are already familiar with XML you may wish to skip ahead to the next section.) XML lets you take a text or a collection of data and structure it via markup. In the examples above, the markup is in boldface.
Each file begins with a prolog, marked by the
lines that begin with <?
. The first line in the prolog simply states
that what follows is an XML document. The next two lines are processing instructions that point to the files that will be used to
check to see whether or not our data is valid. For now we will not explain the
details of those first three lines, which will be identical, or nearly so, from one
TAN file to the next. We can simply cut and paste those lines when we want to start a
new one.
The fourth line is the opening tag of what is called the root element, here called <TAN-T>
. That opening tag, <TAN-T...>
is
answered by a closing tag, </TAN-T>
, the last line. The paired-tag
relationship is true for all the other elements in this example. <head>
is answered by
</head>
, <body>
by </body>
and each
<div...>
by </div>
. These elements nest within or
beside each other, but they never overlap. (The prohibition on overlapping elements
is one of the cardinal rules of XML.) This relationship means that every XML file can
be thought of as a tree, with the root at the trunk and the enveloped elements as
branches, terminating in metaphorical leaves. It is helpful to use the tree metaphor
when we describe the path we take, toward either the leaves or the root. In this
manual, we may use the terms rootward and
leafward when we want to trace movement up and
down the hierarchy of an XML document.
An XML document is also profitably thought of as a family tree, a metaphor that
provides commonly used terminology. In our examples above, <TAN-T>
is the parent of <body>
,
and <body>
the parent of the four
<div>
elements. Likewise,
each <div>
is the child of <body>
, and <body>
is the child of <TAN-T>
. Distant parental relationships can be described with
the terms ancestor and descendant. <TAN-T>
is the ancestor of every element it encompasses, and
every element encompassed by <TAN-T>
is its descendant. Paratactic relationships are also
important. <head>
and <body>
are siblings to each other, and every <div>
is a sibling to every other <div>
.
Inside of the opening tags for the <TAN-T>
, <body>
, and <div>
elements are pairs of text joined by an equals sign,
collectively called an attribute. The left side of
the equals sign is the attribute name, and on the right side, within the quotation
marks, is the attribute value. <TAN-T>
has two attributes, @xmlns
and @id
(when we discuss an attribute outside
its original context, we often preface the name with @). We will skip
@xmlns
for now; this attribute (actually, a pseudo-attribute)
specifies the namespace of the XML file, an advanced
topic that need not be discussed now.
The @id
, however, is quite
important. Every TAN file has an @id
that uniquely and permanently identifies the file itself. It should not be changed,
even as we make edits. The name you save the file as can be changed, but keep in mind
that other people may be depending on it, and may be unable to find it.
The value of @id
is always what
is called a tag uniform resource name (tag URN). It always starts with
tag:
, followed by an email address or domain name that we own or
owned. (It is okay to use an obsolete address; this part is only for identification.)
After that email address or domain name comes a comma (no spaces) and a date on which
we owned it, in the international standard format of year, month, and date, joined by
hyphens, e.g., 2014-12-31. If we leave off a day value, it is assumed to be the first
of the month; if we leave off the month value it is assumed to be January. In the
examples above, parkj@textalign.net,2015
points to the person who owned
that particular email address on the stroke of midnight (Coordinated Universal Time)
January 1, 2015. (In this example, we are pretending to be that person.) After that
comes a colon, and then any name we wish to assign to the file.
We have anticipated a simple collection of texts, so we've called the files
ring01
and ring02
. (If we run out of names, or want to
restart, we can simply use a new email-date preface, e.g.,
parkj@textalign.net,2015-01-02
.)
The idea here is that hundreds of years from now, even when that email will be defunct or owned by someone else, someone might still be able to identify the person responsible for the file.
The element <body>
contains
our transcription. @xml:lang
,
required, specifies the principal language of the transcribed text. We use the
standard 3-letter abbreviation for English. (See later in the guide for more complex
language requirements.) By saying that @in-progress
is false
, we indicate that we have
finished our transcription and have no further plans to develop it. It doesn't mean
that the file is free of errors. We can make corrections later. It just means that we
have no more substantive revisions are planned, and any further changes will be
restricted to corrections of typographical errors. This attribute is optional. If it
is left off, our TAN file is assumed to be a work in progress, and it serves as a
kind of warning to anyone who might want to use it.
Our transcription has been divided into four <div>
elements. How we divide up the work is entirely up to
us. But we must make sure that every bit of text is enclosed by a leafmost
<div>
. That is, every
<div>
must be the parent of
only other <div>
s, or none at all.
We cannot have a <div>
that mixes
text with other elements (such as other <div>
s). The values of @type
and @n
indicate, respectively, the type of division and the name of the division. We have
used line
in the first example, but we could easily have also used
l
(as we did in the second) or ln
or any other phrase
that we think will make intuitive sense to other users. The choice is arbitrary (we
will see why below). We have used arabic numerals for the values of @n
, but the value, once again, could have
been anything. We could have used Roman numerals, or some other naming scheme that is
standard in the field.
Aside from the <head>
element
(discussed later), that's all we need in the transcription. We can now move to
alignment and annotation.
There are two different types of alignment, one emphasizing breadth, the other, depth. The broad type of alignment, called TAN-A-div, allows us to specify TAN transcriptions of as many versions of as many works as we wish, and to make claims about those texts. The other type of alignment, emphasizing depth, is called TAN-A-tok and allows us to take any two (and no more) TAN transcriptions, create word-to-word (or better put, token-to-token) relationships, and specify what type of relationship holds between each set of aligned words. TAN-A-div is suitable for work that focuses on the general alignment of multiple versions of one or more works at a single time. TAN-A-tok is for highly detailed, precise alignment of two text versions.
For our example, we start with a TAN-A-div file (once again suppressing
<head>
):
<?xml version="1.0" encoding="UTF-8"?> <?xml-model href="http://textalign.net/release/TAN-2018/schemas/TAN-A-div.rnc" type="application/relax-ng-compact-syntax"?> <?xml-model href="http://textalign.net/release/TAN-2018/schemas/TAN-A-div.sch" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?> <TAN-A-div xmlns="tag:textalign.net,2015:ns" id="tag:parkj@textalign.net,2015:ring-alignment"> <head> . . . . . . . </head> <body/> </TAN-A-div>
In the prolog, the first line is identical to the first line of our transcription
files. The second and third lines, the processing instructions, are identical, aside
from pointing to the validation files for alignment. Even the fourth line looks like
the transcription file, other than the new name for the root element, <TAN-A-div>
, and the new value for
@id
.
The penultimate line, <body/>
, is what is called an empty element,
and is equivalent to <body></body>
—a shorthand syntax for elements contains
nothing. It will become apparent, when we discuss <head>
below, why our <body>
can be empty.
The other kind of alignment, TAN-A-tok, takes a bit more work, because we must first identify words that correspond with each other. Even before we do that, we need to decide what kind of relationship holds between the two texts. Let us pretend, for the sake of example, that the 1987 version is a direct descendant (and therefore variation) of the 1881 one. So our task is to show exactly what parts of the the older version correspond to those of the newer one. We will simplify in this case, and assume an interest only in words, ignoring space and that punctuation. We will also adopt, tokens instead of words (word is notoriously difficult to define, and has connotations lacking from token).
We now create a TAN-A-tok file:
<?xml version="1.0" encoding="UTF-8"?> <?xml-model href="http://textalign.net/release/TAN-2018/schemas/TAN-A-tok.rnc" type="application/relax-ng-compact-syntax"?> <?xml-model href="http://textalign.net/release/TAN-2018/schemas/TAN-A-tok.sch" type="application/xml" schematypensrc="http://purl.oclc.org/dsdl/schematron"?> <TAN-A-tok xmlns="tag:textalign.net,2015:ns" id="tag:parkj@textalign.net,2015:TAN-A-tok,ring01+ring02"> <head> . . . . . . . </head> <body bitext-relation="B-descends-from-A" reuse-type="adaptation" in-progress="false"> <!-- Examples of picking tokens by number --> <align> <tok src="ring1881" ref="1" ord="1"/> <tok src="ring1987" ref="1" ord="1"/> </align> <align> <tok src="ring1881" ref="1" ord="2"/> <tok src="ring1987" ref="1" ord="2"/> </align> <align> <tok src="ring1881" ref="1" ord="3"/> <tok src="ring1987" ref="1" ord="3"/> </align> <align> <tok src="ring1881" ref="1" ord="4"/> <tok src="ring1987" ref="l" ord="4"/> </align> <align> <tok src="ring1881" ref="1" ord="5"/> <tok src="ring1987" ref="1" ord="5"/> </align> <!-- Examples of picking tokens by value --> <align> <tok src="ring1881" ref="2" val="A"/> <tok src="ring1987" ref="2" val="A"/> </align> <align> <tok src="ring1881" ref="2" val="pocket"/> <tok src="ring1987" ref="2" val="pocket"/> </align> <align> <tok src="ring1881" ref="2" val="full"/> <tok src="ring1987" ref="2" val="full"/> </align> <align> <tok src="ring1881" ref="2" val="of"/> <tok src="ring1987" ref="2" val="of"/> </align> <align> <tok src="ring1881" ref="2" val="posies"/> <tok src="ring1987" ref="2" val="posies"/> </align> <!-- Examples of picking ranges of tokens --> <align> <tok src="ring1881" ref="3" ord="1, 2"/> <tok src="ring1987" ref="3" ord="1"/> </align> <align> <tok src="ring1881" ref="3" ord="3 - 4"/> <tok src="ring1987" ref="3" ord="2"/> </align> <align> <tok src="ring1881" ref="4" ord="1"/> <tok src="ring1987" ref="4" ord="1"/> </align> <align> <tok src="ring1881" ref="4" ord="2"/> </align> <align> <tok src="ring1881" ref="4" ord="3"/> <tok src="ring1987" ref="4" ord="2"/> </align> <!-- examples of using "last" --> <align> <tok src="ring1881" ref="4" ord="last-1"/> <tok src="ring1987" ref="4" ord="last-1"/> </align> <align> <tok src="ring1881" ref="4" ord="last"/> <tok src="ring1987" ref="4" ord="last"/> </align> </body> </TAN-A-tok>
Once again, the first four lines, the prolog and root element, should look
familiar, with the only significant changes being the names of the validation files,
the name of the root element (<TAN-A-tok>
) and the value of @id
.
The heart of the data is <body>
, which has, in addition to @in-progress
, two more
attributes, @reuse-type
,
which specifies the default type of relationship between the two sources, and
@bitext-relation
,
which specifies how the versions relate to each other. Our two values,
B-descends-from-A
and adaptation
, are arbitrary names
that we define in the <head>
(discussed later).
You will also notice some lines that begin <!--
and end
-->
. These are comments, and can be
placed within or beside any element, and can be any number of lines. If you wish to
ignore, say temporarily, some elements, an XML editor can help you toggle them on and
off as comments.
<body>
is the parent of one or
more <align>
elements, each of
which correlates a set of tokens in the two texts through its <tok>
children. Each <tok>
has, in this example, three
attributes. @src
takes a nickname
(an @id
reference) that points to
one of the two transcriptions; we have used ring1881
and
ring1987
but we could have just as easily used anything else such as
uk
and us
. @ref
has a value that points to a specific <div>
in the source transcription; and
@pos
or @val
specify which token is intended,
either by word number (@pos
) or
text of the actual word (@val
).
Either technique is fine, and can be mixed, as in the example. You may also notice
that the comma and hyphen can be used in @pos
to point to multiple words within the same <div>
, and that last
and
last-X
(where X
is a digit) can be used to point to a
word token relative to the last one in a <div>
.
Each <align>
can establish
one-to-one, one-to-many, many-to-one, or many-to-many relationships between words
from the two texts. Words may feature in multiple <align>
elements (a kind of overlapping that doesn't offend
the XML rule against overlapping). And if an <align>
has <tok>
elements belonging to only one source, such as in the
fourth-to-last <align>
above, we
have what is called, in these guidelines, a half-null alignment.
This half-null alignment indicates that the second word of line four of the 1881
version is excluded from the act that we have called adaptation
(which
is, as we shall see, defined in the <head>
). If this were a translation, it would be as if we
were saying that this word was excluded from the translation. (A half-null alignment
containing only tokens of the later source might point to words that the translator
added.)
A half-null alignment should not be confused with our own silence. As creators of this file, we are under no obligation to indicate every word-for-word correspondence. If we fail to mention certain words, all that can be implied is that we opted not to say anything about them.
We could have aligned the two texts in different ways. Perhaps further study will reveal that we were in error to associate the second "ring" with "round" in line 1. We can make corrections, even after publication, and signal the change to users of our data. There are also ways to express doubt or alterative opinions. We can even correlate fragments of tokens (letters, prefixes, infixes, or suffixes). All these more advanced uses are discussed elsewhere in these guidelines.