TEI-Council-FAQ

So you have some questions about how the TEI Technical Council works? This page has been set up to answer questions that new council members (or other curious parties) may have.

Overview

How does the Council do its work?

By every means possible. These include regular telephone conferences, endless streams of email, widely circulated discussion documents, private caucussing, public debate in other contexts such as TEI-L, and private gossip. Formally speaking, the Council meets face to face once a year (at least), and many more times than that virtually.

And what work does it do?

You should probably review the recent official work of the Council by reading the last few sets of minutes: http://www.tei-c.org/Council/ has an index page which links to them all (when we remember to update it). The minutes record topics discussed and responsibilities allocated at the Council level. Of course many Council members are also active in subgroups (formal or informal) of the Council or SIGs, which may be documented elsewhere as well.

Generally, things in Council work like this:

1. A bug report or feature request is reported by anyone in SourceForge.
2. Sometimes others notice the ticket and comment on it.
3. Sometimes a Council member may make an executive decision on the ticket. If it's a corrigible error or bug, we can just fix it in the appropriate ODD file(s) (also in SourceForge Subversion). If it is not a real issue, sometimes the ticket will just be closed. If you do not have developer access on sourceforge you'll need to ask someone who does to re-open the ticket if you want to raise it again. Otherwise, it's discussed either by email on the Council mailing list or at a Council meeting (conference call or in-person meeting). Comments are recorded in the ticket reflecting the decision reached, and changes are made in SourceForge by a member of the Council sometime thereafter.
4. The change shows up on tei-c.org after the next TEI "release", which happens about two or three times a year.

However, Council does sometimes consider lengthy proposals circulated to Council outside of SourceForge and vote on them as packages, with the changes grouped together in a sensible way so they can be considered in smaller packages, or with the changes listed individually.

And what is its scope?

The Council's primary responsibility is to act as technical watchdog for the intellectual content of the TEI Guidelines. That is to say: it has the final say in just about every aspect of the TEI encoding scheme -- what elements exist in it, what they are called, how they should be used.

How do I join the TEI Council mailing list?

We have had the practice on the Council so far that elected members get added immediately to the list (and to the telecon, if there is one), with every right to participate, while outgoing members stay on until the end of their term. To join or discuss any problems using the list contact the TEI Council mailing list owner, currently this is David Sewell in Virginia.

Why are some people on the Council email list or attending Council meetings even though they are not on the list of elected members?

The chair of the TEI Consortium is a member of the Council ex officio, and the TEI Board also nominates another representative in addition to the Council Chair. Other people, at the discretion of the Chair of the TEI Technical Council, may be allowed on to the TEI Council Mailing list or allowed to attend Council meetings. As of March 2012, Lou Burnard (board representative) and David Sewell (TEI-C Webmaster) are invited to attend.

Terminology

What was the War on Free-text-bearing Attribute Values?

The War on Free-text-bearing Attribute Values, also known as the War on Free-text-bearing Attributes and the War on Attributes for short, happened because some have felt that if attribute values don't have a datatype, they are more prone to abuse than if they did. So there has been an effort to give datatypes to as many attributes as possible. Some discussion of this with respect to @rend is available here: http://blogs.oucs.ox.ac.uk/jamesc/2011/12/01/rend-and-the-war-on-text-bearing-attributes/

What is the "Birnbaum doctrine"?

As expressed in TCW09: Backward Compatibility and the Maintenance of the Text Encoding Initiative Guidelines, we should avoid breaking backward compatibility and only do so after serious consideration. It does not mean that we cannot break backwards compatibility, just that we've agreed a set of steps to take when we do so.

In what ways will Council break backwards compatibility?

For an egregious error, we might actually change a content model immediately. More often, we will survey the community on TEI-L before doing so, and we might deprecate.

What is the "Durand Conundrum"?

The "Durand Conundrum" was suggested by David G. Durand concerning the TEI's decision to use the TEI ODD meta-schema language rather than just one of the existing schema languages. Given that we decided to use our own language, why use RelaxNG as part of that language for describing content models? Generally, the consensus is that TEI ODD gives us greater power and flexibility than any individual schema language can do in that we can model things that those schema languages are currently unable to cope with. TEI ODD gives the ability for a single document to produce both documentation and schema since these are inherently interlinked. It also keeps the TEI honest, in requiring it to use its own system to document schemas. TEI ODD does currently have some problems, a few of which are detailed at ODD-dev and successive revisions of TEI ODD are intended to solve some of these.

What is a "magic token"?

This is an value, usually an attribute value, such as that of @key or @rend, which does not follow a standard outside vocabulary but instead is understood in some undocumented way and often used for local processing. It should usually be explained in the teiHeader if possible. Having any processing rely on undocumented magic tokens is generally considered a bad idea. See also Magic Cookie.

What is a non-deterministic content model?

If you have a content model for <a>:

b*, c?, b*

and you have a document with:

<a>
  <b/>
</a>

then a parser can't tell whether the matches the first b* or the second b* in the content model. Thus, the content model itself is called “non-determinstic”. DTDs and W3C XML Schemas reject non-deterministic content models. Thus, if we were to create one in the TEI, validation with DTD and XSD would fail due to errors in the schema, regardless of whether the instance document has an occurence that is non-deterministic or not.

What are Janus elements?

These are pairs of elements that are in a sense two sides of the same coin, such as orig and reg, corr and sic, abbr and expan.

What does "no magic" mean?

(answer to be added here)

= What does it mean to say that elements tessellate?

This means that all textual content is included in exactly one instance of an element. For example, once you start using divs (numbered or unnumbered), all text thereafter must be inside of one of the divs: you can't start using p elements that are not wrapped in a div.

In the Guidelines this is sometimes referred to as end-to-end segmentation.

Meetings

Where are the minutes of previous meetings?

Minutes are archived on the TEI website. Interim states of minutes may at times live in this wiki, Google Docs, or elsewhere.

How are the teleconferences held?

Currently the TEI Council uses the teleconferencing facilities provided by commercial provider since this has proved most cost effective with less problems than other VOIP-based solutions. This has 800/free call numbers for most countries, and low-cost for some. This will be set up by the Council Chair in advance and details posted to the list.

The specific details of what number to dial and what access code is needed will be circulated on the council list shortly before the meeting.

What funding is available for Council Activities? And how do I get reimbursed?

The TEI funds the participation of the council members in the meetings. Though I don't know of anyone claiming back telephone conferencing costs, I suppose that is possible as well, in most cases the council members' institutions probably swallow that.

If the council has a meeting, then the council members' travel, hotel, etc. will be reimbursed with proper receipts. The TEI reimburses all reasonable expenses in keeping with standard practice at most universities and granting agencies. We cover meals, travel, lodging, and other common daily travel expenses. Airfare should be economy class and direct return, unless otherwise arranged with the Treasurer prior to your trip. (See draft reimbursement policies and procedures.) If you have questions about reimbursement procedures, including what is reimbursable, please email John Unsworth, the TEI treasurer, at unsworth AT brandeis.edu.

Use the TEI Travel expense form available here: http://www.tei-c.org/Admin/TEI_travel_form.pdf Expense forms should be submitted within 10 days of the end of the meeting.

Council members are not funded to attend the TEI Members' Meeting, however, there has been discussion concerning whether the council should also officially meet here as well.

How we get work done

How can I get straight to certain tickets in SourceForge?

SourceForge divides all tickets into "bugs" and "feature requests". You must browse them separately. You can browse all in a given category from the links at http://tei.sourceforge.net/ .

Before we upgraded to the new Allura system on SourceForge for our tickets, tickets had old, ugly URLs. To get around using these, we set up short URLs maintained by James Cummings and others, which which you could append the attribute ID to the end of the appropriate one of the two URLs where it says 'NUMBER' in order to reach the right ticket:

http://purl.org/TEI/bug/NUMBER
http://purl.org/TEI/FR/NUMBER
 

I have something to say about a SourceForge Feature Request or Bug: Should I comment on the ticket or the TEI Council mailing list?

There is no hard-and-fast policy on this. The mailing list is a better place for ongoing discussions where people are arguing back and forth during decision making. The SourceForge tracker is the appropriate place to record opinions, positions, and decisions for posterity, especially if such would help a) whoever is implementing the decisions recorded in the ticket, b) anyone revisiting this decision later to retrace the thinking. The TEI Council mailing list archives are public, so if substantial discussion has taken place there (or indeed on TEI-L), this can also be linked to from the ticket.

When is discussion on an element or topic "closed" and how do I know?

Any topic can be revisited at any point, even in the published guidelines, through posting a feature request on sourceforge. Council-specific issues should be raised on the council mailing list, after having reviewed any previous discussion on the topic in the council mailing list archives.

How can I find out about every time a ticket is created or commented on?

Two options:

• By RSS: Subscribe to an RSS feed that includes new tickets and comments on existing ones
• By email:
  1. Create a SourceForge user, or log in to an existing account.
  2. Make sure you have joined the TEI project.
  3. Click the "monitor" button at https://sourceforge.net/tracker/?group_id=106328&source=navbar to receive an email for each change (but what exactly does this include?)

How does a TEI release happen?

The process of making a release is documented at http://www.tei-c.org/Activities/Council/Working/tcw22.xml

Working in SourceForge

How do I edit the TEI Guidelines?

Editing the TEI Guidelines is a complex process and the Council has produced a document http://www.tei-c.org/Activities/Council/Working/tcw20.xml covering the logical and physical layout of the Guidelines, stylistic notes, how to make a change to the Guidelines (it requires using subversion, building a release, and a reference section of useful information. If any information you need isn't in this document, ask on the Council list and get someone to update it!

How can I find out about every time a change is made in the TEI subversion repository?

1. Go to https://lists.sourceforge.net/lists/listinfo/tei-notify .
2. Subscribe under your SourceForge email address (which you can find at http://sourceforge.net/project/memberlist.php?group_id=106328 ).

How do I use Subversion?

The TEI stores its working files in the TEI Sourceforge Subversion Repositories, with read access to anyone who wishes. See the instructions. Write access is reserved for those who are developers on the SourceForge project. To request developer status, contact one of the project admins, whose usernames are given in bold on the SourceForge list of users.

Note that you will have to enter your password each time you access Subversion. A way around this (which causes a security risk) is to create a public/private key pair based on no passphrase and upload your public key to SF. There is a description of how this process works in general, and some hard-to-follow instructions specific to SourceForge.

What should I put in a Subversion commit message?

It is beneficial to all those looking at the TEI Subversion repository if commit messages are clear and detailed. This is especially true when trying to revert changes made by yourself or others to solve problems. A good commit message will include:

• an explanation to a useful level of detail about what you did
• a mention of why this is being done
• the SourceForge ticket numbers (or shortened urls) that relate to the change if applicable
• an explanation of whether this change is completing the work described or one step towards doing so.

TEI website

I want to add a document to add meeting minutes, reports, or working papers to the TEI-C website. How do I do that?

The TEI webmaster(s) -- currently David Sewell, with assistance from Kevin Hawkins -- have access to the CMS behind the TEI website. The site uses a stylesheet to render TEI Lite documents in XHTML, though the CMS can also deliver non-TEI documents. However, for long-term preservation and consistency, use of TEI Lite is encouraged.

You can author a document from scratch or take an existing document as a starting point. To get the XML source of an existing document, simply click "XML View" in the footer of a page on the TEI-C website and choose "save as" in your browser.

The TEI has a longstanding naming convention for files that consists of:

1. a short alphabetical abbreviation for a committee (such as "tc" for "Technical Council")
2. a one-letter abbreviation for minutes ("m"), reports ("r"), or working papers ("w")
3. a two-digit number for the document with a committee series, numbered sequentially (e.g., "tcw01" is the first working paper from the Technical Council, "tcm05" is the fifth minutes from the Technical Council, etc.)

There is no registry of documents, so when creating a new one, you simply name the file appropriately.

Send the file to a webmaster for putting online. If you are hesitant to have the page go live until you have previewed it, you can ask the webmaster to send you a derived HTML version using the stylesheets without publishing that document.

How do I get access to the Google Analytics Data for www.tei-c.org?

Email the TEI-C webmaster: web@tei-c.org.

Miscellaneous

Why do some elements have @type and others do not?

The TEI has avoided adding @type to elements because its availability is thought to invite tag abuse. One principle used by the Technical Council is that if an element is repeatable and is something for which there can be different classifications, it should have @type.

I have a question!

Then add it just above this one or email someone on the council or the council list reminding them of the existence of this wiki page when you ask your question.