Conditionals

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:

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:

=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:

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=

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:

=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:


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


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

Conditions

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


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


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

Declaration ranges

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


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

Default values

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


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


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