bug fixes: what we are doing and how you can help

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

bug fixes: what we are doing and how you can help

Michael Sperberg-McQueen
We promised a report on what to do about bugs in the DTDs; here it is.
-CMSMcQ and LB



        TEI Maintenance:  What We Are Doing and How You Can Help

As reports on experience with the TEI encoding scheme come in, we are
finding, as expected in a scheme this large and complex, some problems,
slips, errors, typos, and just plain bugs in the TEI DTD files.  As
people start trying out the Guidelines in earnest, we are also starting
to receive reports of the "How am I supposed to do X" or "The Guidelines
don't support Y" variety.  In this note we'll call the first kind BUGS
and the second PROBLEMS.  This note describes how we're hoping to cope
with both kinds of activity, but chiefly the former.  It also says
something about how you can help us make the maintenance of the TEI DTDs
function smoothly for everyone, in one or more of the following ways:

       -- report bugs
       -- raise technical problems
       -- raise usability issues
       -- develop test files


---BUGS-----

Some bugs are just plain errors with obvious solutions.  Alas, these
will happen, even in the best regulated projects.  Some bugs do not have
obvious solutions, although they are clearly erroneous. And yet others
maybe are not bugs at all, but misunderstandings or well disguised
design features...

We are fondest of the first category (the ones with solutions).  When
these are reported, we will normally post a note to TEI-L defining the
bug and giving instructions on how to fix it.  Where possible these
instructions will suggest how you can avoid falling foul of the problem
concerned until such time as a revised version of the relevant DTD
fragment is available from the servers.  This may involve local
modifications to your copies of the TEI DTD, or it may simply involve
evasive action of some kind.

At unpredictable intervals, new versions of the DTD will be posted  on
the TEI file servers, in which all outstanding errors have been fixed:
a note will always be posted to TEI-L announcing when this has been
done. The Chicago and Exeter servers will be updated first; the shadow
servers in Oslo and Chiba may take a bit longer.

Bugs for which there is no obvious solution (or for which only one
editor believes there to be one) will normally be referred to TEI work
groups for further study and discussion.  The TEI Steering Committee is
considering ways of organizing a framework in which further technical
work of this nature can take place.


---  BUG REPORTS ---

If you suspect you've found a bug in the TEI DTD, PLEASE REPORT IT!
Don't assume that everyone knows about it (unless of course it's already
been reported on TEI-L) or that we're not interested.

You can send bug reports and is-this-a-bug queries to TEI-L, or you can
send private mail to the editors ([hidden email] and [hidden email]) if
it's too embarrassing a bug to reveal in public.

As with all bug reports for all kinds of systems, it is useful to
describe both what actually happens when you process a file, and what
you think ought to be happening.  Often a simple statement will suffice,
for example:

    The APP element does not seem to be legal within paragraphs,
    even when the tag set for text criticism is selected; surely
    it ought to be?

In other cases, more evidence is necessary. For example:

   Sometimes the APP element is legal when I expect it to be, and
   sometimes it isn't.  What gives?

is not very helpful unless it comes with some examples of when the
element is (or is not) accepted as legal, and when you think it ought
(or ought not) to be.


                * * * * * *  REWARD  * * * * * *

The first individual to report a given bug in the currently published
TEI DTD will be entitled to receive a check for ONE DOLLAR, if the bug
is reported during 1994.  During 1995, and each year thereafter, the
reward will double (two dollars in 1995; four dollars in 1996; eight
dollars in 1997 ...)  Some time fairly early in the next millenium we
expect to decide we can't afford it any more, and withdraw the offer,
but not before then.  Bugs must be current:  bugs in back versions of
the DTD will NOT be paid for.

Anyone who prefers a check for one ECU may request one (it is worth a
bit more, after all), but we will have to make arrangements for an ECU
account first.

The editors' decision on whether a bug report is new or is the same as
an already reported bug will be final, and may occasionally be tainted
by self-interest. The editors' decision as to whether or not something
is a bug at all is similarly non-negotiable.

Our thanks to the following people, who have already reported bugs, and
to whom we therefore already owe the one-dollar reward described below
-- in some cases, several dollars' worth:

        - Berend Dijk
        - John Price-Wilkin
        - Greg Murphy
        - Walter Handy

(If your name should be on this list and isn't, please accept our
apologies, and remind us of the bug in question -- it may be one we'd
prefer to forget.)


-- PROBLEMS --

As noted above, we are expecting discussion and technical development of
the TEI Guidelines to continue. We want to hear about problems of
encoding which the Guidelines do not address, as well as those which
they address unsuccessfully. We don't anticipate any immediate major
revisions in the published Guidelines, but neither do we anticipate
their being cast in stone as of this May.  Problems which have no simple
and obvious solution require study, analysis, and discussion.  The
proper forum for such discussion is the network.  If you have identified
such a problem, and you have relevant experience or opinions, please
don't hesitate to post them on TEI-L so that the community as a whole
can benefit from your experience.


-- USABILITY PROBLEMS --

Our current NEH funding is specifically intended to cover the production
of tutorial and introductory guides for a number of different
application areas. It's too early to say exactly what form these will
take, though those who have recently attended a TEI Workshop will have
some idea of our current thinking.  By reporting any difficulties you've
experienced in trying to use the Guidelines you can help a lot.  We want
to know about problem areas for which the TEI solution is not apparent,
even after a careful reading of P3.  (Problems which result from an
inability to read may however be given short shrift.) Again, TEI-L is
the appropriate place to report such things in the first instance.


-- TEST FILES --

A specific task for which those with the necessary time and expertise
may wish to volunteer is the construction of one or more TEI test files,
for checking to ensure the DTD defines a particular tag set properly.
Such test files are urgently needed to help ensure that revisions to the
DTD don't introduce new bugs.

Test files should preferably focus on testing a single tag set (though
if you are particularly interested in testing a tag set's combination
with others, you may), and should ideally include at least one example
of each element or construct declared in a tag set (normally several,
with different contents or in different contexts).  Test files may
either be realistic, plausible (but short) examples of the tag set (a
simple one might be created by combining the examples in the chapter
describing the tag set being tested), or artificially complex, difficult
files designed to test as much of the tag set as possible in as compact
a space.

Programmers will recognize the latter style as a variant of the one-page
'torture test' designed by Donald E. Knuth for testing new versions of
TeX.

Volunteers willing to help construct test files should contact the
editors; you may volunteer for a particular tag set, or we can assign
you a tag set which does not yet have a full test suite.  Experts in
regression testing who wish to advise on the proper construction of test
suites should also get in touch.  Thanks!

-C. M. Sperberg-McQueen ([hidden email])
 Lou Burnard ([hidden email])

[Please note changes of email address above -- the old addresses will go
on working for a while.]