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 monthly remote meetings, email, widely circulated discussion documents, and public debate in other contexts such as TEI-L and GitHub issues. The Council meets face to face twice a year (usually one of those meetings concurrent with the TEI Annual Meeting), and many more times than that virtually. Sub-groups of Council will often form around particularly large or complex issues and may meet separately to deal with them.

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 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 TEI Council mailing list owner, currently this is Luis Meneses (Victoria). 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 Luis Meneses) are also on the mailing lists.

What are the various job roles on the TEI Council?

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 TEIC Github organization
• acting as SIG coordinator
• liaising for and reporting on Council activities at all Board meetings
• reflecting Council wishes in Board discussions
• 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:
   1. Results only shown at end
   2. Method: "Plurality/FPTP/SNTV" for 2 candidates, "Instant Runoff Voting" for 3 or more
   3. a single winner
   4. Ballot type: "choose one" for 2 candidates, "ranked enhanced" for 3 or more
   5. candidate order shuffled
3. 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).
4. 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.
5. 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.

Terminology

What is a "corrigible error"?

This is a term that comes up in Council discussions and refers to an error or inconsistency in the Guidelines that can be fixed without requiring a deprecation period.

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

The move from SGML to XML included (some would say necessitated) The War on Free-text-bearing Attribute Values, also known as the War on Free-text-bearing Attributes or the War on Attributes for short. This war was an effort to disallow free text in the value of any attribute recommended by the Guidelines. There were two main reasons for this.

First, XML does not have SDATA entities, and thus has no built-in mechanism for representing a character that is not available in Unicode. The obvious mechanism to represent a character outside of Unicode in XML is to use an element. In TEI, this is the <g> element. However, an element cannot be inside an attribute value. Thus any free text which might include a character outside of Unicode could not be properly expressed in an attribute value — it would have to be element content so it could include an element itself. (This was also the reason behind macro.xtext, which in general should be used instead of textNode in TEI content models.)

Secondly, it was observed, XML’s internal mechanism to specify language (@xml:lang) does not differentiate between an element’s attributes and its content. However, it is quite reasonable to believe (at least, in DH) that an encoding would need to specify the natural language of any free text. One way around this problem would have been to avoid @xml:lang and instead develop a TEI-specific system for specification of language that did not have this limitation. Another was to avoid allowing free text in an attribute value, such that all free text would be in element content, which element could bear an @xml:lang. TEI chose the latter.

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 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 <b/> matches the first b* or the second b* in the content model. Thus, the content model itself is called “non-deterministic”. 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.

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 Council meetings held?

The Council usually makes use of Google Meet/Hangouts for their meetings. The meeting link will be in the agenda and/or sent out on the Council list 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.

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. If you have questions about reimbursement procedures, including what is reimbursable, please email Hugh Cayless, the TEI treasurer, at philomousos AT gmail.com.

Use the TEI Travel expense form available here: https://tei-c.org/tei_travel_form/ Expense forms should be submitted within 1 month of the end of the meeting.

How we get work done

I have something to say about a GitHub Feature Request or Bug: Should I comment on the issue 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?

Each repository has a "watch" control, which is to be found on the top right or the repo's GitHub page, below the navigation bar. This control lets you manage notifications in various ways.

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 do the issue labels mean?

• 'Status: Blocked' means that the issue cannot be progressed because it requires either that another issue be completed first or that more information is needed from the reporter or a third party.

• 'Status: Needs Discussion' means that the issue has not been talked about enough yet to resolve it. New issues nearly always go into this status first. When Council has face-to-face meetings, these are usually the issues we target first.

• 'Status: Pending' means that the issue is pending some work. Often this means that some work is to be done (typically in a branch named after the issue) and then discussed by Council..

• 'Status: Go' 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.

• Other labels should be self-explanatory, and are sometimes created as needed to group tickets for various purposes.

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 GitHub

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?

The TEI stores its working files in repositories in the TEIC GitHub Organization. See the instructions. Write access is reserved for those who are on the TEI Council or TEI Contributors teams. Any Council member should be able to add you to the Council team.

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:

• a subject line less than 72 characters long (which may be the whole message if no more is needed)
• 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.

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

These documents currently reside in the Documentation repo on GitHub.

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