[tei-council] the constraint element (long)
Sebastian Rahtz
sebastian.rahtz at oucs.ox.ac.uk
Wed Mar 25 22:44:46 EDT 2009
I have spent the last few hours trying to come up with
a concrete proposal here, and checking that it can be implemented.
To do this requires a fair bit of surgery on P5 itself, before I
even start on stylesheets and Roma, so I'd like some feedback
first.
The files affected, if you wonder, are (at least)
M Source/Guidelines/en/guidelines-en.xml
M Source/Guidelines/en/TD-DocumentationElements.xml
? Source/Specs/constraint.xml
M Source/Specs/delSpan.xml
M Source/Specs/gi.xml
M Source/Specs/attDef.xml
M Source/Specs/classSpec.xml
M Source/Specs/TEI.xml
M Source/Specs/damageSpan.xml
M Source/Specs/moduleRef.xml
M Source/Specs/addSpan.xml
M Source/Specs/elementSpec.xml
M Source/Specs/schemaSpec.xml
M Source/Specs/content.xml
I have made all the changes in my local copy but not
committed it.
The two main things to look at the elementSpec and the prose
for TD. I list these below. Could some of you scan this and
check that I am getting the point of what is needed?
The work left to do, if you don't disagre with what I say so far,
is
* check all this is valid and works
* find more examples in the Guidelines which can be expressed this way
* decide whether to support auto-constraints expressed in a classSpec
* fix the stylesheets to take account of it (essential it all be in sync)
* fix Roma (may take longer)
Any good examples you can suggest would be much appreciated!
ELEMENT SPEC:
<elementSpec
xmlns:s="http://www.ascc.net/xml/schematron"
xmlns="http://www.tei-c.org/ns/1.0"
xmlns:rng="http://relaxng.org/ns/structure/1.0" module="tagdocs"
ident="constraint">
<gloss>constraints on schema</gloss>
<desc>contains constraints, expressed in an XML syntax,
which cannot be expressed in the structural content model</desc>
<content>
<rng:group>
<rng:ref name="model.headLike"/>
<rng:zeroOrMore>
<rng:ref name="macro.anyXML"/>
</rng:zeroOrMore>
</rng:group>
</content>
<exemplum>
<p>This constraint uses Schematron to enforce the presence of the
<att>spanTo</att> attribute (which comes from an attribute class)
on the <gi>addSpan</gi> element: </p>
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<constraint>
<s:assert test="@spanTo">The spanTo= attribute of <s:name/>
is required.</s:assert>
</constraint>
</egXML>
</exemplum>
<exemplum>
<p>This constraint uses Schematron to check whether a
<gi>figure</gi> element has either a title or a description,
implementing an accessibility rule which says that pictures should
have textual explanations: </p>
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<constraint>
<head>Alt tags for figures</head>
<s:report test="not(tei:figDesc or tei:head)"> You should
provide information in a figure from which
we can construct an alt attribute in HTML </s:report>
</constraint>
</egXML>
</exemplum>
<listRef>
<ptr target="#TDTAG"/>
</listRef>
</elementSpec>
ADDITION TO TD:
<p>In addition to the <gi>content</gi> element, a second
container, <gi>constraint</gi>, is provided where rules about the
validity of an element can
be expressed. This follows the <gi>content</gi> element, and is also
permitted as a sibling of <gi>datatype</gi> in <gi>attDef</gi>,
and as a child of <gi>schemaSpec</gi>. The constraints can be
expressed in any XML notation may be found useful. The TEI recommends,
however, the use of ISO Schematron for this purpose.</p>
<p>A complete Schematron document consists of a <gi
scheme="Schematron">schema</gi> element containing <gi
scheme="Schematron">ns</gi> and <gi>scheme="Schematron">pattern</gi>
elements; each pattern specifies a rule and a context. In a normal a
TEI specification it is expected that <gi scheme="Schematron">ns</gi>
and <gi scheme="Schematron">pattern</gi> elements will be placed
wherever suitable for documentation, and extracted into a single
Schematron schema, or embedded in another schema language. As a
convenience for readers, however, TEI processors should also support
the direct placement of Schematron <gi scheme="Schematron">report</gi>
and <gi scheme="Schematron">assert</gi> elements inside the
<gi>constraint</gi> component of an <gi>elementSpec</gi>; the <gi
scheme="Schematron">pattern</gi> and <gi scheme="Schematron">rule</gi>
containers should then be generated automatically.
</p>
<p>Constraints are generally used to model local rules which are outside
the scope of
conventional schema languages. For example, if we know that
a TEI document must be rendered into accessible HTML, we can check
that some sort of content is available from which the <att>alt</att>
attribute of an HTML <gi scheme="HTML">img</gi> can be created:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<constraint>
<s:pattern name="Alt tags">
<s:rule context="figure">
<s:report test="not(figDesc or head)"> You should
provide information in a figure from which
we can construct an alt attribute in HTML </s:report>
</s:rule>
</s:pattern>
</constraint>
</egXML>
or we might enforce other HTML accessibility rules about tables:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<constraint>
<s:pattern name="Tables">
<s:rule context="tei:table">
<s:report test="not(tei:head)">A table should have a
caption, using a head element</s:report>
<s:assert test="not(parent::tei:body)">Do not use tables to lay
out the document body</s:assert>
</s:rule>
</s:pattern>
</constraint>
</egXML>
We can also model contextual constraints in Schematron:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<constraint>
<s:rule context="tei:div">
<s:assert
test="not(tei:div) or count(tei:div)>1">a clause must contain
at least two subclauses</s:assert>
</s:rule>
</constraint>
</egXML>
and base requirements on attribute values:
<egXML xmlns="http://www.tei-c.org/ns/Examples">
<constraint>
<s:rule context="tei:teiHeader">
<s:assert
test="tei:fileDesc/tei:titleStmt/tei:title[@type='introductory']">
An introductory component of the title is expected
</s:assert>
<s:assert
test="tei:fileDesc/tei:titleStmt/tei:title[@type='main']">
An main component of the title is expected
</s:assert>
</s:rule>
</constraint>
</egXML>
</p>
--
Sebastian Rahtz
Information Manager, Oxford University Computing Services
13 Banbury Road, Oxford OX2 6NN. Phone +44 1865 283431
Sólo le pido a Dios
que el futuro no me sea indiferente
More information about the tei-council
mailing list