TEI-Council-FAQ - Revision history

Syd: add new Pending status

2024-10-18T17:49:12Z

add new Pending status

← Older revision		Revision as of 17:49, 18 October 2024
Line 177:		Line 177:

	* '<span style="color:orange; font-weight:bold;">Status: Needs Discussion</span>' 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.		* '<span style="color:orange; font-weight:bold;">Status: Needs Discussion</span>' 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.

			* '<span style="color: #5319E7; font-weight:bold;">Status: Pending</span>' 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..

	* '<span style="color:green; font-weight:bold;">Status: Go</span>' 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.		* '<span style="color:green; font-weight:bold;">Status: Go</span>' 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.

Syd: entirely re-write, as my recollection of the War on Attributes does not involve concerns of abuse mitigated by datatypes at all.

2024-10-18T17:27:43Z

entirely re-write, as my recollection of the War on Attributes does not involve concerns of abuse mitigated by datatypes at all.

← Older revision		Revision as of 17:27, 18 October 2024
Line 87:		Line 87:
	=== What was the War on Free-text-bearing Attribute Values? ===		=== 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~~/		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 <tt><g></tt> 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 <tt>textNode</tt> in TEI content models.)

			Secondly, it was observed, XML’s internal mechanism to specify language (<tt>@xml:lang</tt>) 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 <tt>@xml:lang</tt> 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 <tt>@xml:lang</tt>. TEI chose the latter.

	=== What is the "Birnbaum doctrine"? ===		=== What is the "Birnbaum doctrine"? ===

Hcayless: /* What funding is available for Council Activities? And how do I get reimbursed? */

2023-09-19T14:20:28Z

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

← Older revision		Revision as of 14:20, 19 September 2023
Line 149:		Line 149:
	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.		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://~~www.~~tei-c.org/~~wp-content/uploads/2017~~/~~10/TEI_travel_form.pdf~~ '''Expense forms should be submitted within 1 month of the end of the meeting.'''		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 ==		== How we get work done ==

Seifert: /* How do I edit the TEI Guidelines? */

2023-08-10T14:51:09Z

How do I edit the TEI Guidelines?

← Older revision		Revision as of 14:51, 10 August 2023
Line 186:		Line 186:
	=== How do I edit the TEI Guidelines? ===		=== 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 [[TEI-Council-FAQ#How_do_I_use_GitHub.3F\|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!		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 [[TEI-Council-FAQ#How_do_I_use_GitHub.3F\|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? ===		=== How can I find out about every time a change is made in the TEI GitHub repository? ===

Seifert: /* And what work does it do? */

2023-08-10T14:49:17Z

And what work does it do?

← Older revision		Revision as of 14:49, 10 August 2023
Line 15:		Line 15:
	# A bug report or feature request is reported by anyone at [https://github.com/TEIC/ GitHub] for the [https://github.com/TEIC/TEI/issues Guidelines] or [https://github.com/TEIC/Stylesheets/issues Stylesheets].		# A bug report or feature request is reported by anyone at [https://github.com/TEIC/ GitHub] for the [https://github.com/TEIC/TEI/issues Guidelines] or [https://github.com/TEIC/Stylesheets/issues Stylesheets].
	# Sometimes others notice the ticket and comment on it.		# Sometimes others notice the ticket and comment on it.
	# 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.		# 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.
	# The change shows up on tei-c.org after the next TEI "release", which happens about two or three times a year.		# The change shows up on tei-c.org after the next TEI "release", which happens about two or three times a year.

Hcayless: /* Terminology */

2019-10-08T15:47:16Z

Terminology

← Older revision		Revision as of 15:47, 8 October 2019
Line 80:		Line 80:

	== Terminology ==		== 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? ===		=== What was the War on Free-text-bearing Attribute Values? ===
Line 96:		Line 100:

	The "Durand Conundrum" was suggested by David G. Durand concerning the TEI's decision to use the [[ODD \| 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 [[ODD \| 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. [[ODD \| 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 [[ODD#Future_plans:_.22Pure_ODD.22\|the work on Pure ODD elements for content models and datatypes]] has cut the gordian knot of this problem.		The "Durand Conundrum" was suggested by David G. Durand concerning the TEI's decision to use the [[ODD \| 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 [[ODD \| 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. [[ODD \| 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 [[ODD#Future_plans:_.22Pure_ODD.22\|the work on Pure ODD elements for content models and datatypes]] has cut the gordian knot of this problem.


	=== What does "no magic" mean? ===		=== 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.		'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 [http://en.wikipedia.org/wiki/Magic_cookie Magic Cookie].



	=== What is a non-deterministic content model? ===		=== What is a non-deterministic content model? ===
Line 130:		Line 126:

	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.		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? ===		=== What does it mean to say that elements tessellate? ===

Hcayless: /* What funding is available for Council Activities? And how do I get reimbursed? */

2019-10-08T15:30:02Z

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

← Older revision		Revision as of 15:30, 8 October 2019
Line 150:		Line 150:
	=== What funding is available for Council Activities? And how do I get reimbursed? ===		=== 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.~~		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. ~~(See [http://www.tei-c.org/Board/procedures.xml#body.1_div.8 draft reimbursement policies and procedures].)~~ If you have questions about reimbursement procedures, including what is reimbursable, please email ~~John Unsworth~~, the TEI treasurer, at ~~john.m.unsworth~~ AT gmail.com.		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://www.tei-c.org/wp-content/uploads/2017/10/TEI_travel_form.pdf '''Expense forms should be submitted within ~~10 days~~ of the end of the meeting.'''		Use the TEI Travel expense form available here: https://www.tei-c.org/wp-content/uploads/2017/10/TEI_travel_form.pdf '''Expense forms should be submitted within 1 month 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 we get work done ==

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

2019-10-08T14:56:28Z

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

← Older revision		Revision as of 14:56, 8 October 2019
Line 215:		Line 215:

	=== I want to add a document to add meeting minutes, reports, or working papers to the TEI-C website. How do I do that? ===		=== 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:		The TEI has a longstanding naming convention for files that consists of:
Line 226:		Line 222:
	# 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.)		# 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~~.		These documents currently reside in the [https://github.com/TEIC/Documentation Documentation] repo on GitHub.

	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? ===		=== How do I get access to the Google Analytics Data for www.tei-c.org? ===

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

2019-10-08T14:53:59Z

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

← Older revision		Revision as of 14:53, 8 October 2019
Line 30:		Line 30:
	=== Why are some people on the Council email list or attending Council meetings even though they are not on the list of elected members? ===		=== 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.		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? ===		=== What are the various job roles on the TEI Council? ===

Hcayless: /* How does the Council do its work? */

2019-10-08T14:53:21Z

How does the Council do its work?

← Older revision		Revision as of 14:53, 8 October 2019
Line 5:		Line 5:
	=== How does the Council do its work? ===		=== 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.		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? ===		=== And what work does it do? ===