[tei-council] tcw20.xml (Editing the TEI Guidelines)

[Kevin Hawkins]

While this is very helpful, it seems that the first half of it needs to 
be adapted for inclusion in chapter 23 of the Guidelines.  That is, we 
would not refer to specific files like att.datable.xml and not refer to 
something that has already been added into the Guidelines.  After all, 
if anyone not on Council wants to use Schematron, they would never think 
to look at tcw20 (or even know it exists)!  What you would leave here is 
the explanation of how trunk/P5/Text works and what follows.

Still, here are a few comments for now:

a) You write, "Inside <constraintSpec> , <constraints> s have <assert> 
elements, which have @test attributes, which are XPath".

Are @test attributes always expressed in XPath, or is that just the case 
in this example?

b) I don't care for use of "to fire" and "to be fired" in reference to a 
test condition.

c) Is <report> (fires when true) being contrasted with <assert> (fires 
when false)?  This is implied but not stated explicitly.

d) For clarity, you might explain that a Schematron schema checks only 
the Schematron constraints but nothing else typically expressed in a 
DTD, RELAX NG, or XML Schema (or maybe I'm wrong about that).

e) You write, "We'll go through the process of adding a constraint like 
this."

Like what?

f) You have an example with @xmlns:sch on <constraintSpec> but in the 
following paragraph say that the user needs to add the Schematron 
namespace "to the <classSpec> root element".  Regardless of which way 
you meant it, strictly speaking the namespace isn't required to be in 
just one place or the other: you can do it different ways.  So you might 
want to say something about making sure the namespace is declared.  This 
unfortunately relies on the user to understand how namespaces work and 
your various options for declaring them.

g) Why do the pampelmousse and later code snippets have @xmlns:sch at 
all?  I would remove them for clarity.

--K.

On 9/12/12 11:23 AM, Martin Holmes wrote:
> Thanks indeed for debugging this. I've tweaked the whitespace a bit and
> I think it looks fine now.
>
> Any comments from Council on the actual content would be welcome --
> imagine yourself in the position of having to add a Schematron
> constraint to a classSpec or an elementSpec -- would my instructions be
> clear and helpful enough?
>
> <http://www.tei-c.org/Activities/Council/Working/tcw20.xml#schematron>
>
> Cheers,
> Martin
>
> On 12-09-11 08:08 PM, David Sewell wrote:
>> Martin et al.,
>>
>> The added code in tcw20.html was throwing a server error because
>> something in the XSLT stylesheets is triggering a bug when <ref> is a
>> child of <q>. The workaround was to transform the one instance of that
>> construct to replace <q>...</q> with “...”. (Googling, I find Michael
>> Kay referring to a bug involving tunnel parameters and an older version
>> of Saxon; not sure if that's what is biting our OpenCMS as I don't know
>> if it's using Saxon for a parser.)
>>
>> The XSLT stylesheet within OpenCMS does in fact have a template rule for
>> <egXML> but it is not very robust.
>>
>> I hate to say it, but for purposes of the ordinary web pages (as opposed
>> to the Guidelines) I think you'd be better off using <ab> with CDATA
>> content formatted as desired.
>>
>> Anyway, if you go into OpenCMS now and take a look at tcw20.xml you'll
>> see your section appear; you can steal the lock and edit/publish if you
>> wish.
>>
>> It might be time to try a wholesale replacement of the version of
>> tei2.xsl used to format the OpenCMS pages, only I'm not sure there's a
>> current one using XSLT 1.0? And the other problem affecting changes to
>> the XSLT is that I believe the stylesheet must be "published" to take
>> effect even within the offline context of OpenCMS, meaning if it is
>> buggy it affects the world-viewable site as well.
>>
>> David
>>
>> On Thu, 6 Sep 2012, Martin Holmes wrote:
>>
>>> Hi all,
>>>
>>> I've just completed one of my Ann Arbor obligations by documenting the
>>> process of adding a Schematron constraint along with tests for that
>>> constraint. I've written quite a long section, and you can see the
>>> results here:
>>>
>>> <http://hcmc.uvic.ca/people/martin/tcw20.html#schematron>
>>>
>>> All comments appreciated.
>>>
>>> However, writing it required the use of <exemplum>, <egXML> and friends.
>>> Unfortunately, the TCW documents (and I assume their associated
>>> transformation) are TEI Lite documents, so when I add my code to the
>>> tcw20.xml file on the TEI site (in CMS), the transform fails and the
>>> page does not show up. So I've had to comment out my new section for the
>>> moment.
>>>
>>> What should we do about this? Could we transition the tcw files to full
>>> TEI, and use the default P5 XHTML conversion to render them on the CMS?
>>> It's going to be a bit difficult to provide good documentation for
>>> ourselves if we're prevented from using documentation elements.
>>>
>>> Cheers,
>>> Martin
>>>
>>
>