Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add interleave element (and deprecate sequence/@preserveOrder) #2538

Open
wants to merge 11 commits into
base: dev
Choose a base branch
from
Open

Add interleave element (and deprecate sequence/@preserveOrder) #2538

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
a681495
Initial work on `tei:interleave` per #2154
joeytakeda Mar 17, 2024
c99fa45
Add the interleave spec file
joeytakeda Mar 17, 2024
4b2c180
Adding interleave to specGrp
joeytakeda Mar 17, 2024
e1b8e77
Fix duplicate constraintSpec ident
joeytakeda Mar 17, 2024
e556a8d
latest from dev
sydb Jul 10, 2024
0e86aac
Add interleave xmp
sydb Jul 10, 2024
b5f31ff
Minor wording tweaks
sydb Jul 20, 2024
1bc877a
Tweak xmp
sydb Jul 20, 2024
d651de7
First crack at health warning for DTD generation
sydb Jul 20, 2024
95f1613
Do not allow interleave in GLs:
sydb Aug 13, 2024
eae6597
merge in latest from dev
sydb Aug 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 66 additions & 9 deletions P5/Source/Guidelines/en/TD-DocumentationElements.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -634,18 +634,23 @@ to mark any technical term, thus:
<specDesc key="att.repeatable" atts="minOccurs maxOccurs"/>
</specList>
</p>
<p>Additionally, two wrapper elements are provided to indicate
whether the components listed as their children form a sequence
or an alternation:
<p>Additionally, three wrapper elements are provided to indicate
whether the components listed as their children form a sequence,
an alternation, or are interleaved:
<specList>
<specDesc key="sequence"/>
<specDesc key="alternate"/>
<specDesc key="interleave"/>
</specList>
These two wrapper elements are also members of <ident
Note, however, that current ODD processing software will
not be able to convert a content model that uses <gi>interleave</gi>
to a DTD.</p>
<p>These three wrapper elements are also members of <ident
type="class">att.repeatable</ident>. References listed as
children of <gi>sequence</gi> must appear in the order and
cardinality specified. Only one of the references listed as
children of <gi>alternate</gi> may appear, although the
cardinality specified whereas references listed as children
of <gi>interleave</gi> may appear in any order. Only one of the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can-of-worms department.

(Note to @joeytakeda — most of the problem here is not from your improvement, but has been here all along and is just foregrounded by your change.)

This sentence does not mention that cardinality of the stuff inside <interleave>. But on thinking of how to re-word it, I realize that these sentences discuss the cardinality of references, when what we are talking about is the cardinality of the thing referenced. I am not sure what, if anything, we should do about this.

references listed as children of <gi>alternate</gi> may appear, although the
cardinality of the <gi>alternate</gi> itself applies. Thus the
following fanciful content model permits either any number of
<gi>ptr</gi> elements (except zero) or any number of
Expand Down Expand Up @@ -673,13 +678,14 @@ to mark any technical term, thus:
</content>
</egXML>
</p>
<p>The <gi>sequence</gi> and <gi>alternate</gi> elements may be
used in combination with great expressive power. For example, in
<p>The <gi>sequence</gi>, <gi>alternate</gi>, and <gi>interleave</gi>
elements may be used in combination with great expressive power. For example, in
the following example, which might be imagined as a clean
replacement for the content of the <gi>choice</gi> element, one
and only one of the element pairs <gi>sic</gi> and
<gi>corr</gi>, <gi>orig</gi> and <gi>reg</gi>, or
<gi>abbr</gi> and <gi>expan</gi> is allowed.
<gi>abbr</gi> and <gi>expan</gi> is allowed, in each case only
in the order specified.
<egXML xmlns="http://www.tei-c.org/ns/Examples" xml:lang="und" source="#NONE">
<content>
<alternate>
Expand All @@ -698,6 +704,56 @@ to mark any technical term, thus:
</alternate>
</content>
</egXML>
In the above example, the alternation of element pairs must be
encoded in the order specified (for example, <gi>sic</gi> and then
<gi>corr</gi>). In the next example, which also might be
imagined as a clean replacement for the content of the
<gi>choice</gi> element, this restriction is removed. That is,
one and only one of the element pairs <gi>sic</gi> and
<gi>corr</gi>, <gi>orig</gi> and <gi>reg</gi>, or <gi>abbr</gi>
and <gi>expan</gi> is allowed, but in each case the members
of the pair may occur in either order.
<egXML xmlns="http://www.tei-c.org/ns/Examples" xml:lang="und" source="#NONE">
<content>
<alternate>
<interleave>
<elementRef key="sic"/>
<elementRef key="corr"/>
</interleave>
<interleave>
<elementRef key="orig"/>
<elementRef key="reg"/>
</interleave>
<interleave>
<elementRef key="abbr"/>
<elementRef key="expan"/>
</interleave>
</alternate>
</content>
</egXML>
</p>
<p>This next example, which might be imagined as a
clean replacement for the content of the <gi>person</gi>
element, declares that the element must contain one
<gi>persName</gi> element, either both <gi>birth</gi> and
<gi>death</gi> elements (in that order) or a single
<gi>floruit</gi> element, and one <gi>note</gi> element in any
order:
<egXML xmlns="http://www.tei-c.org/ns/Examples" xml:lang="und" source="#NONE">
<content>
<interleave>
<elementRef key="persName"/>
<alternate minOccurs="0" maxOccurs="1">
<sequence>
<elementRef key="birth"/>
<elementRef key="death"/>
</sequence>
<elementRef key="floruit"/>
</alternate>
<elementRef key="note"/>
</interleave>
</content>
</egXML>
In the following example, which might be imagined as a clean
replacement for the content of the <gi>address</gi> element, the
encoder is given a choice of either:
Expand Down Expand Up @@ -1837,6 +1893,7 @@ xmlns="http://www.tei-c.org/ns/Examples"><attList>
<include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/model.contentPart.xml"/>
<include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/sequence.xml"/>
<include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/alternate.xml"/>
<include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/interleave.xml"/>
<include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/constraint.xml"/>
<include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/constraintSpec.xml"/>
<include xmlns="http://www.w3.org/2001/XInclude" href="../../Specs/attList.xml"/>
Expand Down
61 changes: 61 additions & 0 deletions P5/Source/Specs/interleave.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
<?xml version="1.0" encoding="UTF-8"?>
<!-- © TEI Consortium. Dual-licensed under CC-by and BSD2 licenses; see the file COPYING.txt for details. -->
<?xml-model href="https://jenkins.tei-c.org/job/TEIP5-dev/lastSuccessfulBuild/artifact/P5/release/xml/tei/odd/p5.nvdl" type="application/xml" schematypens="http://purl.oclc.org/dsdl/nvdl/ns/structure/1.0"?>
<elementSpec xmlns="http://www.tei-c.org/ns/1.0" xmlns:sch="http://purl.oclc.org/dsdl/schematron" module="tagdocs" ident="interleave">
<desc versionDate="2024-03-16" xml:lang="en">indicates that the constructs referenced by its children occur in any order (i.e. are interleaved)</desc>
<classes>
<memberOf key="att.global"/>
<memberOf key="model.contentPart"/>
<memberOf key="att.repeatable"/>
</classes>
<content>
<classRef key="model.contentPart" maxOccurs="unbounded"/>
</content>
<constraintSpec ident="interleavechilden" scheme="schematron">
<constraint>
<sch:rule context="tei:interleave">
<sch:assert test="count(*) gt 1">The interleave element must have at least two child elements</sch:assert>
</sch:rule>
</constraint>
</constraintSpec>
<exemplum xml:lang="en">
<egXML xmlns="http://www.tei-c.org/ns/Examples" xml:lang="en" source="#UND">
<content>
<interleave>
<elementRef key="persName"/>
<alternate minOccurs="0">
<elementRef key="placeName"/>
<elementRef key="location"/>
</alternate>
<elementRef key="note" minOccurs="0"/>
</interleave>
</content>
</egXML>
<p>This example describes a content model that consists of a
mandatory <gi>persName</gi> element, zero or one of either
<gi>placeName</gi> or <gi>location</gi>, and an optional
<gi>note</gi> element, in any order.</p>
<!-- <p>To express this content model in the DTD language one might use
<eg xml:space="preserve"><![CDATA[ ( persName
| ( persName, note )
| ( persName, ( placeName | location ) )
| ( note, persName )
| ( ( placeName | location ), persName )
| ( persName, note, ( placeName | location ) )
| ( persName, ( placeName | location ), note )
| ( note, persName, ( placeName | location ) )
| ( note, ( placeName | location ), persName )
| ( ( placeName | location ), note, persName )
| ( ( placeName | location ), persName, note )
)]]></eg></p> -->
</exemplum>
<remarks xml:lang="en" versionDate="2024-07-20">
<p>If a TEI description of an XML markup language (often referred
to as an <q>ODD</q>) makes use of this element, current processing
software will not be able to generate a DTD from it. For this reason
TEI P5 itself does not make use of <gi>interleave</gi> internally.</p>
</remarks>
<listRef>
<ptr target="#DEFCON" type="div2"/>
</listRef>
</elementSpec>
3 changes: 2 additions & 1 deletion P5/Source/Specs/sequence.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@
</constraint>
</constraintSpec>
<attList>
<attDef ident="preserveOrder">
<attDef ident="preserveOrder" validUntil="2025-03-15">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given that a) <interleave> did not make it into the recent release, and b) use of @preserveOrder still works in the Stylesheets, I think the @validUntil date should be moved up to late 2025 or early 2026.

<desc type="deprecationInfo" versionDate="2024-03-15" xml:lang="en">The <att>preserveOrder</att> on <gi>sequence</gi> has been deprecated. The <gi>interleave</gi> element should be used to denote unordered constructs.</desc>
<desc versionDate="2023-03-21" xml:lang="en">if false, indicates that
component elements of a sequence may occur in any order.</desc>
<datatype><dataRef key="teidata.truthValue"/></datatype>
Expand Down
48 changes: 31 additions & 17 deletions P5/p5odds.odd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ $Id$
<!-- We attempted to enforce this with an abstract
pattern, but found that oNVDL does not support
abstract patterns. Thus, at least for now, just use
a bulky, straightfoward, ineligant, but easier to
a bulky, straightfoward, inelegant, but easier to
process pattern. -->
<sch:pattern id="en-gloss-if-any">
<sch:rule context=" tei:elementSpec[tei:gloss]
Expand Down Expand Up @@ -162,7 +162,7 @@ $Id$
<!--
This definition of <teix:egXML> overrides that of P5 which, for
some reason I don't grok, does not allow a <teix:egXML> descendant.
—Syd, 2018-06-13
—Syd, 2018-06-13
-->
<content>
<alternate minOccurs="1" maxOccurs="unbounded">
Expand All @@ -183,10 +183,10 @@ $Id$
if you really want a newline at the end, follow it with U+00A0.
</desc>
<constraint>
<sch:rule context="tei:eg">
<sch:report test="matches( .//text()[last()], '&#x0A;\s*$')">trailing newline not allowed</sch:report>
<sch:report test="matches( .//text()[1], '^\s*&#x0A;')">leading newline not allowed</sch:report>
</sch:rule>
<sch:rule context="tei:eg">
<sch:report test="matches( .//text()[last()], '&#x0A;\s*$')">trailing newline not allowed</sch:report>
<sch:report test="matches( .//text()[1], '^\s*&#x0A;')">leading newline not allowed</sch:report>
</sch:rule>
</constraint>
</constraintSpec>
</elementSpec>
Expand Down Expand Up @@ -627,7 +627,7 @@ $Id$
<attList>
<attDef ident="module" mode="replace">
<valList type="closed" mode="add">
<!-- I daresay this should be a generated list —Syd, 2022-04-24 -->
<!-- I daresay this should be a generated list —Syd, 2022-04-24 -->
<valItem ident="tei"/>
<valItem ident="core"/>
<valItem ident="analysis"/>
Expand Down Expand Up @@ -682,6 +682,20 @@ $Id$
</attList>
</elementSpec>

<!--
Use of <interleave> in a content model means that our
Stylesheets cannot generate a DTD from that ODD, and it
would be very difficult to impossible to do so. Thus
although vanilla P5 alows for <interleave> to occur inside
<alternatio>, <content>, or <sequence>, we are not
allowing ourselves to use it within P5 at all.
-->
<elementSpec module="tagdocs" ident="interleave" mode="change">
<classes>
<memberOf key="att.repeatable" mode="delete"/>
</classes>
</elementSpec>

<elementSpec ident="content" mode="change" module="tagdocs">
<content>
<choice xmlns="http://relaxng.org/ns/structure/1.0">
Expand Down Expand Up @@ -740,16 +754,16 @@ $Id$
</constraintSpec>
</elementSpec>

<!-- Per TEI ticket #2285, restrict where <altIdent> can go in GLs. -->
<elementSpec ident="altIdent" module="tagdocs" mode="change">
<constraintSpec scheme="schematron" ident="restricted-altIdent-placement">
<constraint>
<sch:rule context="tei:altIdent">
<sch:assert test="parent::tei:elementSpec|parent::tei:attDef|parent::tei:valItem">The &lt;altIdent> element should only be used as a child of &lt;elementSpec>, &lt;attDef>, or &lt;valItem>.</sch:assert>
</sch:rule>
</constraint>
</constraintSpec>
</elementSpec>
<!-- Per TEI ticket #2285, restrict where <altIdent> can go in GLs. -->
<elementSpec ident="altIdent" module="tagdocs" mode="change">
<constraintSpec scheme="schematron" ident="restricted-altIdent-placement">
<constraint>
<sch:rule context="tei:altIdent">
<sch:assert test="parent::tei:elementSpec|parent::tei:attDef|parent::tei:valItem">The &lt;altIdent> element should only be used as a child of &lt;elementSpec>, &lt;attDef>, or &lt;valItem>.</sch:assert>
</sch:rule>
</constraint>
</constraintSpec>
</elementSpec>

<dataSpec ident="teidata.temporal.working" mode="change">
<constraintSpec ident="not_in_future" scheme="schematron">
Expand Down