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.

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 at GitHub for the Guidelines or Stylesheets.
 * 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 GitHub). If it is not a real issue, sometimes the ticket will just be closed. If you do not have developer access on GitHub you'll to ask to be added to the Council team there. 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 GitHub 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 GitHub 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 [mailto:tei-council-owner@lists.tei-c.org TEI Council mailing list owner], currently this is Kevin Hawkins (North Texas) and Nick Homenda (Indiana). There is also a joint Board/Council mailing list to which you should be added as well.

Why are some people on the Council email list or attending Council meetings even though they are not on the list of elected members?
In addition to the members of the Council, the chair of the TEI Technical Council may invite others not elected to the Council to meetings (e.g. to speak to a particular issue). Historically the Council often invited a representative of the Board to the Council mailing list and meetings. The TEI-C Webmaster (currently Kevin Hawkins) and Assistant Webmaster (Nick Homenda) are also on the mailing lists.

TEI Technical Council Member
A TEI Technical Council Member is expected to participate in all aspects of Council work. This means that they should learn how the TEI infrastructure is organised and how to edit the TEI Guidelines, asking on the Council list any questions they might have. They will be expected to come to face-to-face ("f2f") meetings (often two per year) and participate in a couple other teleconferences per year. They will be assigned (or take) feature requests/bugs on the TEI Consortium's GitHub site, for which they will be in charge of encouraging discussion, reporting on the issue to Council, and eventually implementing (or ensuring implementation) of the resulting decision. A TEI Technical Council Member is expected to participate in the maintenance and development of the TEI Guidelines and related outputs. Some elected TEI Council members focus more on particular aspects of the infrastructure or stylesheets as part of the contribution to the Council. Council members should always act to represent what they believe are the opinions and best interest of the community that has elected them.

TEI Technical Council Chair
The TEI Technical Council Chair's role is to administrate and facilitate the work of the TEI Technical Council. If all of the Council are the elected servants of the community, then the Council Chair is the servant of the servants of the TEI (Servus servorum TEI). The duties of the Technical Council Chair include (in no particular order):
 * ensuring the delivery and maintenance of the Guidelines
 * arranging for Council members to actively participate in Council activities
 * arranging and chairing the face-to-face meetings (in conjunction with the local organiser)
 * arranging and chairing the teleconferences
 * creating agendas for those meetings, and ensuring minutes are written and posted of them
 * assigning tickets in the SourceForge system
 * acting as SIG coordinator
 * liaising for and reporting on Council activities at all Board meetings
 * reflecting Council wishes in Board discussions
 * budgeting Council expenses,
 * acting as a public point of contact and responding to technical enquiries (messages to council@tei-c.org are forwarded to the Council Chair)
 * announcing new releases of the Guidelines on the TEI-L mailing list
 * ensuring the smooth running of the TEI Technical Council

The TEI Technical Council Chair is also a member of the Council, so has all the duties and obligations of being a council member as well.

Release Technician
The TEI Guidelines release process (see tcw22: Building a TEI Release) involves a single individual responsible for 'pushing the button' and completing the steps required to make a TEI Guidelines release live. This is not a standing position; instead, the responsibility rotates for every release in order to demystify the release process and spread the expertise beyond Oxford staff. Although we have documented the work in quite a detailed manner, it is a non-trivial process and involves a fair degree of work. A release technician is usually required to set aside a whole day for the release process since history teaches us that often the entire process needs to be re-run to correct last-minute errors.

TEI-C Webmaster and Assistant Webmaster
The TEI-C Webmaster and Assistant Webmaster are not officially part of the Council but may be added to the mailing lists at the discretion of the Council Chair. They are responsible for the smooth running of the TEI-C Website.

How is the TEI Technical Council Chair elected?
The Bylaws of the TEI-C say that: The Chair of the Technical Council shall be elected by the voting Members of the TEI-C Technical Council from its membership and shall serve as the chief technical officer of the Consortium. If no Technical Council Member is able or willing to assume the chair, the Technical Council may request the Board of Directors to second one of its elected members to the role, or it may nominate a non-elected individual. This leaves it intentionally vague as to the precise process the TEI Technical Council will follow. For now there is vague consensus that they will do something like the following. Note that timeframes below are not intended to be rigid or precise, but rather to be suggestive.
 * 1) The new Technical Council Members will be added to the tei-council (and tei-board-council) mailing lists shortly after the members' meeting. Up until around the last last Friday in November those who are Council members for next year will consider whether they want to run to be Chair of the TEI Technical Council. The current Chair will facilitate this process by answering any questions about the post. Before that date those intending to stand should send a statement of some sort to the Council mailing list detailing why they think the council members should vote for them.
 * 2) On or around the first weekday of December if only one person is running then the Chair will announce this to the tei-council mailing list as an acclamation (and after a short period for objections, to the Board and TEI-L). If multiple people are running, then the Council Chair will appoint a "returning officer" who is not a member of the incoming Council (i.e., not a voter and thus at least a somewhat disinterested party). The returning officer will set up an electronic voting system with the names of the candidates. This should be a private election with no one able to determine who has voted for whom. E.g. if using opavote.org this should have the following settings:
 * 3) Results only shown at end
 * 4) Method: "Plurality/FPTP/SNTV" for 2 candidates, "Instant Runoff Voting" for 3 or more
 * 5) a single winner
 * 6) Ballot type: "choose one" for 2 candidates, "ranked enhanced" for 3 or more
 * 7) candidate order shuffled
 * 8) The returning officer should ensure the election runs for at least 4 days, preferably in early December, after announcing it on the tei-council mailing list (and distributing ballots depending on the system).
 * 9) The results will be announced publicly on the tei-council mailing list, and Council members given a brief chance to raise any objections with the election before the current Chair informs the Board and announces it more publicly on TEI-L.
 * 10) The new Chair assumes the role on 1 January. The current chair steps down on 31 December. The outgoing and incoming chairs should co-ordinate activities between the election and 1 January so as to ensure a smooth transition. (Remembering that the current Chair might be departing off council at the end of that year.) These dates and timescales can of course shift and are not meant to be set in stone.

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. Our deprecation policy supersedes some of this.

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. Increasingly the work on Pure ODD elements for content models and datatypes has cut the gordian knot of this problem.

What does "no magic" mean?
'Magic' in the sense sometimes used in Council discussion refers to pre-existing or special knowledge required to process something. For example, it was only by 'magic' that a TEI ODD processor would know to add attributes from the att.global attribute class to elements until this was changed to make all element specifications have to explicitly claim membership in this class if they wanted the global attributes. Knowing to add them was 'magic', and in general it is better if any requirements or understood knowledge is explicitly documented. While some 'magic' of understood conventions or processing will always remain in complex technical systems, the Council strives to at very least enable the possibility of documenting the underlying rules when it discovers them. James Cummings has been a fervent proponent of the removal of any understood 'magic' rules from the TEI.

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 :

and you have a document with:

  

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 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.

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 can I get straight to certain tickets in SourceForge?
'(This is now out of date since we've moved to GitHub... leaving here for a bit for historical interest.)' 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

The new URLs are much more human readable and so those should now be used in preference. Some legacy documents may still use the old PURL URLs. Furthermore, if a legacy document references a ticket number from the old system, you can use one of these PURLs in order to be redirected to the new URL.

I have something to say about a GitHub 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 GitHub 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 GitHub. Council-specific issues should be raised on the council mailing list, after having reviewed any previous discussion on the topic in the tei-council mailing list archives.

How can I find out about every time a ticket is created or commented on?
FIX-ME: Needs update to github' Two options:


 * By RSS: Subscribe to an RSS feed that includes new tickets and comments on existing ones
 * By email:
 * Create a SourceForge user, or log in to an existing account.
 * Make sure you have joined the TEI project.
 * 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 are tickets assigned in GitHub?
All members of Council are made part of the Council 'Team on the GitHub TEIC Organisation and meant to take an active role in the development and maintenance of the TEI Guidelines. This means that they have write access to the TEI Guidelines Github Repository, and tickets can be assigned to them in the ticket trackers. They can also update and modify tickets. This means that Council members are free to 'take' tickets which they wish to oversee. Other Council members can also 'give' tickets to each other if they think someone particularly suited to overseeing a particular ticket. (However, usually they should have the Council member's permission to do so.) On a regular basis the Council Chair will assign tickets to Council members, if a ticket gets assigned to them that they don't want to do they should tell the Chair and/or ask other Council members to swap.

What does Red, Amber, and Green mean in classifying a ticket?

 * ' Red ' means that the ticket has not been discussed sufficiently and that the answer to it is not necessarily clear. There needs to be more discussion, more examples, use cases, and possibly a clearer proposal about what specifically needs to be done. Or possibly, the ticket does have these things but Council has not yet discussed it or enough Council members seen it for it to warrant an 'Amber' status.


 * ' Amber ' means that the ticket has been discussed and/or there may be some general consensus on what the correct thing to do is, but necessary components are missing. It may be some examples, use-cases, or prose are missing. Or there is a question of which of several possible solutions is the correct one.


 * ' Green ' means that the ticket has been discussed, there is general consensus on what the correct thing to do is, and it has been assigned for someone to ensure its implementation.

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

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 GitHub repository?

 * 1) Go to https://github.com/TEIC/
 * 2) Make sure you are logged in and
 * 3) go into each repository you are interested in and 'watch' them.

How do I use GitHub?
'FIX-ME: NEeds to be updated to github 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 GitHub commit message?
It is beneficial to all those looking at the TEI GitHub 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 GitHub issue numbers (or 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.

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 webmasters -- currently Kevin Hawkins and Nick Homenda -- 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.

Why do some elements have @type and others do not?
The TEI has avoided adding @type globally to elements because its availability is thought to invite tag or attribute abuse. In order for a request to add @type to an element to be considered for prolonged discussion and argument the TEI Technical Council has a standing principle that an element should be both repeatable and have obvious different classifications that apply to it. If such a request is approved then the preferred method is to make the element a member of the att.typed class (because if you can have @type, you can also have sub-types and thus need @subtype). If a closed or suggested value list, or different description is needed, this should then be provided as a local modification to the attributes inherited from att.typed.

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.