From the Open Siddur Project Development Wiki

Jump to: navigation, search

The Contributors to the Open Siddur Project, the copyright holder of this work, has published or hereby publishes it under the following licenses:

This work is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or any later version. This work is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See version 3 of the GNU General Public License for more details.

Deutsch | Deutsch (Sie-Form) | English | Français | +/−

This file is licensed under the Creative Commons Attribution ShareAlike 3.0 License. In short: you are free to share and make derivative works of the file under the conditions that you appropriately attribute it, and that you distribute it only under a license identical to this one. Official license

You may select the license of your choice.

A large portion of the text in the siddur is common between the different nuschaot. Perhaps an equally large section is conditioned on the particular rite in use. Some sections of the service are also dependent on the time of day, the time of year, the day of the week, holidays and a host of other factors. The conditional mechanism in JLPTEI is intended:

to give a human who is selecting texts a way to make an educated decision.
to allow a computer to correctly select an appropriate text for a given time and rite.

In JLPTEI, conditions are represented in a form of variable known as a "feature structure." They can be thought of either as computer code that tells a processor which parts of the text to include, dependent on the user's choices. They can also be conceptualized as an association of a property with a text. The feature structure also has a mechanism for documenting the purpose and possible values of the conditional, such that a user interface can present the user with its description and set of values.

Specifying conditional text

Special types

Some common types of conditionally included text that have their own semantic considerations are given their own elements. These include the kri/ktiv (read/written) pairs which are common in Tanach. Kri/ktiv pairs are represented inside a tei:choice element, with the children j:read (kri) and j:written (ktiv). These, in turn, contain tei:w, as normal. Kri/ktiv pairs will most often (always?) occur within a segment in the text repository. A processor must offer the options to make typographical distinctions between kri and ktiv when encountered in the text. A user-defined global processor setting may be used to determine the particular typographical difference that is applied.

Certain common kri/ktiv pairs are understood and need not be represented by markup. These are:

The word יְרוּשָׁלַֽ‌ִם (as written) = יְרוּשָׁלַֽיִם (as read). In the case of this ktiv, the combining grapheme joiner (Unicode 034F) is required between the meteg and the hiriq, to separate the two vowels and prevent Unicode normalization from reversing their positions.
The Tetragrammaton: when written as יְהוָה, it is understood to be read אֲדֹנָי, and when written יְהוִה, it is understood to be written as אֱלֹהִים. The sheva under the yod should be omitted when the hataf-vowel would be omitted from the alef.

Automated transliteration processors are required to transliterate the above correctly.

All other kri/ktiv pairs must have the tei:choice/j:read, j:written construct.

When, in a kri/ktiv pair, either the kri or the ktiv portion is empty, an empty j:read or j:written element must be included. Needless to say, both j:read and j:written cannot be blank in the same tei:choice construct.

Other conditional text

All conditional text not covered in the cases above, independent of the reason for the condition, is represented using a tei:choice element, with one or more j:option children. These elements may occur inside segments in the text repository, for small differences in wording, or they may appear inside a view.

Declaration of conditionals

Conditionals are declared in the resource section of the file, just after a the header, in the tei:TEI/tei:fsdDecl section. Each tei:fsdDecl section may include:

links to conditional types that are defined elsewhere
new definitions of conditional types.

Conditionals should not be duplicated. If a conditional is defined in one file that can appropriately control options in another, the same conditional declaration from the first file should be used in the second.

Each file that has any options defines one conditional type (feature structure). If there is a good semantic reason for there to be more than one type, more than one may be defined. Each conditional is represented by a feature, which should:

have its function, the values it can take, and the result of using those values documented
have a feature @name equal to the xml:id of the tei:choice or j:option it controls, if it only controls one option (by convention)
present a default value

Feature structures and features are declared using the TEI tei:fsDecl and tei:fDecl tags. Documentation of features is done using the tei:fsDescr and tei:fDescr tags. Where multilingual documentation is required, these tags may include one or more tei:desc elements, with the documentation language written using the @xml:lang attribute.

There are a number of standard feature values, represented using the tei:symbol atomic type. The value YES indicates that the feature is on, or that the text should be included; the value NO indicates that the feature is off, or that the text should not be included; the value MAYBE indicates that it is uncertain at processing time whether the text should be included or not. The user should be given an instruction indicating when to include the text.

A feature that may only have the values YES or NO is called a "two way switch." If it can accept YES, NO, or MAYBE, it is a "three way switch."

Mnemonics (special URIs) may be used for common sets of values and defaults.

Example

The following example shows a time conditional being declared:

<tei:fsdDecl xml:base="http://jewishliturgy.org/base/text/time_example.xml">
  <tei:fsDecl type="time" xml:id="fsdecl_time">
    <tei:fsDescr>
       <tei:desc xml:lang="en">Conditionals dependent on time</tei:desc>
    </tei:fsDescr>
    <tei:fDecl name="shabbat">
      <tei:fDescr>
        <tei:desc xml:lang="en">On Shabbat</tei:desc>
      </tei:fDescr>
      <xi:include href="TWOWAY"/>
      <xi:include href="DEFAULT_MAYBE"/>
    </tei:fDecl>
  </tei:fsDecl>
</tei:fsdDecl>

The following example shows what is required in the tei:fsdDecl section of a file, if the above time conditional is used within the file:

<tei:fsdDecl>
  <tei:fsdLink type="time" target="time_example.xml#fsdecl_time"/>
</tei:fsdDecl>

Associating conditionals

Text is put under conditional control by wrapping it in j:option or tei:choice/j:option tags, as indicated in Textual variations. Each j:option tag must be given an @xml:id attribute to identify it uniquely. This @xml:id must be file unique and persistent. Nontextual elements may also be put under conditional control. Using j:option merely indicates to the processor that the text is conditionally present. In order to specify what condition determines whether it is present, a condition needs to be associated with a conditional feature.

An associated conditional applies to the identified element, and all elements that are processed as its children. A processor may decide not to process the children of a conditional that evaluates to NO, even if it contains external pointers.

A newly-defined part of the resource section (between tei:teiHeader and tei:text) of the file, enclosed in a j:conditionGrp element, contains one or more tei:linkGrp or tei:link elements, in any order. It also may contain one or more tei:fvLib tags to hold the associating condition values as tei:fs feature structures.

Association of conditionals may also be put under conditional control by enclosing the tei:link or tei:linkGrp elements with tei:choice/j:option tags. A j:conditionGrp//tei:link or j:conditionGrp//tei:linkGrp that is a child of a j:option element should only be processed if the condition attached to the parent j:option evaluates to YES. In this way, conditional properties can be conditionally applied to text.

The forms of the links are as follows:

<j:conditionGrp>
  <tei:link type="association" targets="tag_uri conditional_property_uri"/>
  <tei:link type="association" targets="tag_uri conditional_property_uri instruction_uri"/>
  <tei:linkGrp type="association">
    <tei:link targets="tag_uri conditional_property_uri"/>
    <tei:link targets="tag_uri conditional_property_uri instruction_uri"/>
  </tei:linkGrp>
  <tei:fvLib>
    <tei:fs type="X">
       <tei:f name="Y" feats="#Z"/>
       <!-- and so on... -->
    </tei:fs>
  </tei:fvLib>
</j:conditionGrp>

The first form indicates that the tag with URI tag_uri is associated with the condition (which is a feature structure in a j:conditionGrp/tei:fvLib) with uri conditional_property_uri. If a third URI is given, it is interpreted as a pointer to the instruction(s) that should be generated if the selected value of the conditional is MAYBE.

For both two and three way switches, the conditional property as associated with the text may only have the values YES or NO. A value of YES indicates that the text should be included if the value of the conditional setting is YES or MAYBE. A value of NO indicates that the text should be included if the value of the conditional setting is NO or MAYBE, as shown in a table below.

Applying (setting) conditionals

In order to determine whether a text with an associated conditional will be included, the operating conditions must be applied to the text. Conditions are applied using j:conditionGrp/(tei:link|tei:linkGrp)[@type='set']. The application is valid through all nodes that are processed as children of the element to which they are applied.

If a conditional feature with the same name and type is set again, it is set to its new value. To set a conditional feature back to its default value, it should be set to the feature value tei:default.

Truth tables

	Set Conditional Value
Associated Conditional Value	YES	MAYBE	NO
YES	Included	Included with instructions	Excluded
NO	Excluded	Included with instructions	Included

More than one conditional value can be linked to the same text, via an intermediate tei:fs or an intermediate tei:ptr. If this is the case, then, any of the conditions being true will result in the text's inclusion, as shown below:

	Applied Conditional Value 1
Applied Conditional Value 2	YES	MAYBE	NO
YES	Included	Included with instructions	Included
MAYBE	Included with instructions	Included with instructions	Included with instructions
NO	Included	Included with instructions	Excluded

Automatically declared conditionals

Any time a j:option is declared, a conditional property of type name equivalent to the local name of the base URI (that is, substring-after(base-uri(.), '/') ) and name equivalent to the option's @xml:id is declared. The conditional is, by default, a two way switch, with default value YES. If the automatically declared conditional is cause by a j:option inside a tei:choice element, the first j:option listed has a default of YES, the others default to NO. This feature should not be relied upon for larger conditionals, because automatically declared conditionals are undocumented aside from the source code.

TODO: this section needs clarification

Special URIs

Certain special URIs are defined to help with the declaration and use of conditionals. These URIs may be included using XInclude, which should be processed before XML validation and before JLPTEI processing.

Feature values or conditions

http://jewishliturgy.org/base/text/YES (yes feature value) always points to:

<tei:symbol value="YES"/>

http://jewishliturgy.org/base/text/NO always points to:

<tei:symbol value="NO"/>

http://jewishliturgy.org/base/text/MAYBE always points to:

<tei:symbol value="MAYBE"/>

Conditions

http://jewishliturgy.org/base/text/YN (yes or no feature value) always points to:

<tei:vColl>
  <tei:symbol value="YES"/>
  <tei:symbol value="NO"/>
</tei:vColl>

http://jewishliturgy.org/base/text/YM (yes or maybe) always points to:

<tei:vColl>
  <tei:symbol value="YES"/>
  <tei:symbol value="MAYBE"/>
</tei:vColl>

http://jewishliturgy.org/base/text/NM (no or maybe) always points to:

<tei:vColl>
  <tei:symbol value="NO"/>
  <tei:symbol value="MAYBE"/>
</tei:vColl>

Declaration ranges

http://jewishliturgy.org/base/text/TWOWAY (two way switch range definition) always points to:

<tei:vRange>
  <tei:vAlt>
    <tei:symbol value="YES"/>
    <tei:symbol value="NO"/>
  </tei:vAlt>
</tei:vRange>

http://jewishliturgy.org/base/text/THREEWAY (three way switch range definition) always points to:

<tei:vRange>
  <tei:vAlt>
    <tei:symbol value="YES"/>
    <tei:symbol value="NO"/>
    <tei:symbol value="MAYBE"/>
  </tei:vAlt>
</tei:vRange>

Default values

http://jewishliturgy.org/base/text/DEFAULT_YES (default definition for YES) always points to:

<tei:vDefault>
  <tei:symbol value="YES"/>
</tei:vDefault>

http://jewishliturgy.org/base/text/DEFAULT_MAYBE (default definition for MAYBE) always points to:

<tei:vDefault>
  <tei:symbol value="MAYBE"/>
</tei:vDefault>

http://jewishliturgy.org/base/text/DEFAULT_NO (default definition for NO) always points to:

<tei:vDefault>
  <tei:symbol value="NO"/>
</tei:vDefault>

Conditionals

From the Open Siddur Project Development Wiki

Contents

Specifying conditional text

Special types

Other conditional text

Declaration of conditionals

Example

Associating conditionals

Applying (setting) conditionals

Truth tables

Automatically declared conditionals

Special URIs

Feature values or conditions

Conditions

Declaration ranges

Default values

Views

Personal tools

Search

NAVIGATION

DEVELOPMENT

HOWTO

DOCUMENTATION

PROJECT

COMMUNITY

META

Toolbox