P5: TEIガイドライン

TEI: Phrase Level Terms¶22.1.1 Phrase Level Terms

In any kind of technical documentation, the following phrase-level elements may be found useful for marking up strings of text which need to be distinguished from the running text because they come from some formal language:

• code プログラミング言語のような形式言語のコードを示す．

  lang	(formal language) 当該コードの形式言語名を示す．

• ident (identifier) 形式言語にあるオブジェクトの識別子または名前を示す．

Like other phrase-level elements used to indicate the semantics of a typographically distinct string, these are members of the model.emphLike class. They are available anywhere that running prose is permitted when the module defined by this chapter is included in a schema.

If the cited phrase is a mathematical or chemical formula, the more specific formula element defined by the figures module (14.2 Formulæ and Mathematical Expressions) may be more appropriate.

A further group of similar phrase-level elements is also defined for the special case of representing parts of an XML document:

• att (attribute) 属性の名前を示す．
• gi (element name) 要素の名前(共通識別子)を含む．
• tag 完全な開始タグ，終了タグのテキストを示す．属性規定はとることも可能だ が，タグ開始区切子，タグ終了区切子は含まない．
• val (value) 属性値をひとつ示す．

These elements constitute the model.phrase.xml class, which is also a subclass of model.phrase. They are also available anywhere that running prose is permitted when the module defined by this chapter is included in a schema.

Within technical documentation, it is also often necessary to provide more extended examples of usage or to present passages of markup for discussion. The following special elements are provided for these purposes:

• eg (example) 例を示す．
• egXML (example of XML) 要素や属性の使用例を示す，整形式XMLデータによる用例をひとつ含む．要 素egXMLが当該用例の根要素になる．

Like the code element, the egXML element is used to mark strings of formal code, or passages of XML markup. The eg element may be used to enclose any kind of example, which will typically be rendered as a distinct block, possibly using particular formatting conventions, when the document is processed. It is a specialized form of the more general q element provided by the TEI core module. In documents containing examples of XML markup, the egXML element should be used for preference, as further discussed below in 22.4.2 Exemplification of Components, since the content of this element can be checked for well-formedness.

These elements are added to the class model.egLike when this module is included in a schema. That class is a part of the general model.inter class, thus permitting eg or egXML elements to appear either within or between paragraph-like elements.

TEI: Element and Attribute Descriptions¶22.1.2 Element and Attribute Descriptions

Within the body of a document using this module, the following elements may be used to reference parts of the specification elements discussed in section 22.3 Specification Elements, in particular the brief prose descriptions these provide for elements and attributes.

• specList (specification list) 解説のリストが，散文形式の解説文中に挿入される場所を示す．
• specDesc/ (specification description) 特定された要素またはクラスの解説は，文書中のこの場所にあるべきである ことを示す．

  atts	(attributes) 解説が付加的に表される属性名を示す．

When formatting the ptr element in this example, an ODD processor might simply generate the section number and title of the section referred to, perhaps additionally inserting a link to the section. In a similar way, when processing the specDesc elements, an ODD processor may recover relevant details of the elements being specified (specList and specDesc in this case) from their associated declaration elements: typically, the details recovered will include a brief description of the element and its attributes. These, and other data, will be stored in a specification element elsewhere within the current document, or they may be supplied by the ODD processor in some other way, for example from a database. For this reason, the link to the required specification element is always made using a TEI-defined key rather than an XML IDREF value. The ODD processor uses this key as a means of accessing the specification element required. There is no requirement that this be performed using the XML ID/IDREF mechanism, but there is an assumption that the identifier be unique.

A specDesc generates in the documentation the identifier, and also the contents of the desc child of whatever specification element is indicated by its key attribute, as in the example above. Documentation for any attributes specified by the atts attribute will also be generated as an associated attribute list.

TEI: Description of Components¶22.4.1 Description of Components

• gloss 語句の説明や定義を示す．
• desc 当該要素，属性，属性値を採用した目的の簡単な解説を示す．
• equiv/ (equivalent) 親要素と同等とされる構成要素を，相互参照または外部リンクで示す．

  uri	(uniform resource identifier) 外部識別子によって親要素の意義を表す．
  filter	当該要素を標準的XMLデータに変形する外部スクリプトへの参照を示す．
  name	親要素の意義を表す．

• altIdent (alternate identifier) 特定言語において，XMLの要素，クラス，属性などで推奨される名前を示す．
• listRef (list of references) 場所への参照のリストを示す．当該文書中でも外部文書でもよい．
• remarks 要素，属性，クラス，エンティティに関する，まだ文書化されていない解説 や論議を示す．

Note that the gloss element is needed to explain the significance of the identifier for an item only when this is not apparent, for example because it is abbreviated, as in the above example. It should not be used to provide a full description of the intended meaning (this is the function of the desc element), nor to comment on equivalent values in other schemes (this is the purpose of the equiv element), nor to provide alternative versions of the ident attribute value in other languages (this is the purpose of the altIdent element).

Where specifications are supplied in multiple languages, the elements gloss and desc may be repeated as often as needed. Each such description or gloss should carry both an xml:lang and a versionDate attribute to indicate the language used and the date on which the translated text was last checked against its source.

By default, the altIdent of a component is identical to the value of its ident attribute.

TEI: Exemplification of Components¶22.4.2 Exemplification of Components

• exemplum 要素の使用例をひとつ示す．段落単位の解説を伴うかもしれない．
• eg (example) 例を示す．
• egXML (example of XML) 要素や属性の使用例を示す，整形式XMLデータによる用例をひとつ含む．要 素egXMLが当該用例の根要素になる．

  valid	indicates the intended validity of the example with respect to a schema.
  source [att.source]	provides a pointer to the bibliographical source from which a quotation or citation is drawn.

The exemplum element is used to combine a single illustrative example with an optional paragraph of commentary following or preceding it. The illustrative example itself may be marked up using either the eg or the egXML element.

When, as here, an example contains valid XML markup, the egXML element should be used. In such a case, it will clearly be necessary to distinguish the markup within the example from the markup of the document itself. In an XML environment, this is easily done by using a different name space for the content of the egXML element. For example:

<p>The <gi>term</gi> element may be used 
to mark any technical term, thus:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
  This <term>recursion</term> is 
  giving me a headache.</egXML></p>

Alternatively, the XML tagging within an example may be ‘escaped’, either by using entity references to represent the opening angle bracket, or by wrapping the whole example in a CDATA marked section:

<p>The <gi>term</gi> element may be used 
to mark any technical term, thus:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
  This &lt;term&gt;recursion&lt;/term&gt; is 
  giving me a headache.</egXML></p>

or, equivalently:

<p>The <gi>term</gi> element may be used 
to mark any technical term, thus:
<egXML xmlns="http://www.tei-c.org/ns/Examples"><![CDATA[
  This <term>recursion</term> is 
  giving me a headache.]]></egXML></p>

However, escaping the markup in this way will make it impossible to validate, and should therefore generally be avoided.

If the XML contained in an example is not well-formed then it must either be enclosed in a CDATA marked section, or ‘escaped’ as above: this applies whether the eg or egXML is used. The valid attribute on egXML may be used to indicate the XML validity of the example with respect to some schema, as being valid, invalid, or feasibly valid.

The egXML element should not be used to tag non-XML examples: the general purpose eg or q elements should be used for such purposes.

TEI: Classification of Components¶22.4.3 Classification of Components

In the TEI scheme elements are assigned to one or more classes, which may themselves have subclasses. The following elements are used to indicate class membership:

• classes 当該文書化されている要素やクラスの構成要素や下位クラスを示す．
• memberOf 親要素や親クラスを示す．

  key	当該要素またはクラスが下位要素・下位クラスとなっているクラスの識 別子を示す．

The classes element appears within either the elementSpec or classSpec element. It specifies the classes of which the element or class concerned is a member by means of one or more memberOf child elements. Each such element references a class by means of its key attribute. Classes themselves are defined by the classSpec element described in section 22.4.6 Element Classes below.

TEI: Element Specifications¶22.4.4 Element Specifications

The elementSpec element is used to document an element type, together with its associated attributes. In addition to the elements listed above, it may contain the following subcomponents:

• content (content model) 当該スキーマの宣言を示す．

  autoPrefix

  controls whether or not pattern names generated in the corresponding Relax NG schema source are automatically prefixed to avoid potential nameclashes.

• constraintSpec (constraint on schema) contains a constraint, expressed in some formal syntax, which cannot be expressed in the structural content model

  scheme

  supplies the name of the language in which the constraints are defined

• attList 当該要素に関する全ての属性に関する文書を，一連の要素attDef で示す．

  org	(organization) リスト中の属性が全て使用できるか(org="group")，またはその1つだけ が使用できるか(org="choice")を示す．

TEI: Attribute List Specification¶22.4.5 Attribute List Specification

The attList element is used to document information about a collection of attributes, either within an elementSpec, or within a classSpec. An attribute list can be organized either as a group of attribute definitions, all of which are understood to be available, or as a choice of attribute definitions, of which only one is understood to be available. An attribute list may thus contain nested attribute lists.

The attDef element is used to document a single attribute, using an appropriate selection from the common elements already mentioned and the following which are specific to attributes:

• attDef (attribute definition) 1つの属性の定義を示す．

  usage

  属性または要素の選択性を示す．

• datatype 属性値の型を，当該スキーマ中のデータ型を参照して示す．

  minOccurs	(minimum number of occurences) 属性値としてとる当該データ型の値が出現する最小回数を示す．
  maxOccurs	(maximum number of occurences) 当該データ型が属性値として出現する最大回数を示す．

• defaultVal (default value) 属性の既定値を示す．
• valDesc (value description) 要素datatypeにある情報に加えて，属性値の意味的・統語的制約 を示す．
• valList (value list) 可能な属性値を表すひとつ以上の要素valItemを示す．
• valItem 属性値のひとつを解説する．

The attList within an elementSpec is used to specify only the attributes which are specific to that particular element. Instances of the element may carry other attributes which are declared by the classes of which the element is a member. These extra attributes, which are shared by other elements, or by all elements, are specified by an attList contained within a classSpec element, as described in section 22.4.6 Element Classes below.

TEI: Element Classes¶22.4.6 Element Classes

The element classSpec is used to document either an attribute class or a ‘model class’, as defined in section 1.3 The TEI Class System. A corresponding classRef element may be used to select a specific named class from those available.

• classSpec (class specification) TEI要素クラスにおける参照情報を示す．内容モデルに出現する要素のまと まり，共通する属性のまとまり，またはその両方．

  type	当該クラスがモデルクラスか属性クラスかを示す．

• classRef/ points to the specification for an attribute or model class which is to be included in a schema
• attList 当該要素に関する全ての属性に関する文書を，一連の要素attDef で示す．

  org	(organization) リスト中の属性が全て使用できるか(org="group")，またはその1つだけ が使用できるか(org="choice")を示す．

The function of a model class declaration is to provide another way of referring to a group of elements. It does not confer any other properties on the elements which constitute its membership.

The attribute type is used to distinguish between ‘model’ and ‘attribute’ classes. In the case of attribute classes, the attributes provided by membership in the class are documented by an attList element contained within the classSpec. In the case of model classes, no further information is needed to define the class beyond its description, its identifier, and optionally any classes of which it is a member.

When a model class is referenced in the content model of an element (i.e. in the content of an elementSpec), its meaning will depend on the name used to reference the class.

The following suffixes, appended with an underscore, can be given to a class name when it is referenced in a content model:

alternation

members of the class are alternatives

sequence

members of the class are to be provided in sequence

sequenceOptional

members of the class may be provided, in sequence, but are optional

sequenceOptionalRepeatable

members of the class may be provided one or more times, in sequence, but are optional

sequenceRepeatable

members of the class must be provided one or more times, in sequence

The ‘sequence’ in which members of a class appear in a content model when one of the sequence options is used is that in which the elements are declared.

In principle, all these possibilities are available to any element making reference to any class. The classSpec element defining the class may however limit the possibilities by means of its generate attribute, which can be used to say that this particular model may only be referenced in a content model with the suffixes it specifies. For example, if the classSpec for model.hiLike took the form <classSpec ident="model.hiLike" generate="sequence sequenceOptional"> then a content model referring to (say) model.hiLike_sequenceRepeatable would be regarded as invalid by an ODD processor.

An attribute class (a classSpec of type atts) contains an attList element which lists the attributes that all the members of that class inherit from it. For example, the class att.interpLike defines a small set of attributes common to all elements which are members of that class: those attributes are listed by the attList element contained by the classSpec for att.interpLike. When processing the documentation elements for elements which are members of that class, an ODD processor is required to extend the attList (or equivalent) for such elements to include any attributes defined by the classSpec elements concerned. There is a single global attribute class, att.global, to which some modules contribute additional attributes when they are included in a schema.

TEI: Pattern Documentation¶22.4.7 Pattern Documentation

The macroSpec element is used to declare and document predefined strings or patterns not otherwise documented by the elements described in this chapter. A corresponding macroRef element may be used to select a specific named pattern from those available. Patterns are used as a shorthand chiefly to describe common content models and datatypes, but may be used for any purpose. The following elements are used to represent patterns:

• macroSpec (macro specification) パタンの機能や実装を解説する．

  type	ODDソフトウェアがXML DTDによるモジュールを生成する際，どの種類の エンティティが生成されるかを示す．

• macroRef/ points to the specification for some pattern which is to be included in a schema

  key	the identifier used for the required pattern within the source indicated.

• remarks 要素，属性，クラス，エンティティに関する，まだ文書化されていない解説 や論議を示す．