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

[Martin Holmes]

Hi Kevin,

I've made some changes based on your input, for which many thanks. One 
thing I have discovered is that the profusion of xmlns:sch definitions 
in the examples is actually the fault of the transformation in the CMS; 
they're not there in the source code. I wonder if we could get that 
fixed? For instance, this in the source:

         <exemplum xml:lang="en">
           <egXML xmlns="http://www.tei-c.org/ns/Examples" valid="true">
<date calendar="#julian">January, 1622</date>
           </egXML>
         </exemplum>

gives rise to this in the rendered output:

  <date calendar="#julian" 
xmlns:sch="http://purl.oclc.org/dsdl/schematron">January, 1622</date>

which is actually misleading. The Schematron namespace is declared in 
the root TEI element of the TCW20 XML doc, which might be the reason for 
its being copied into every example. Perhaps David can tell us if it 
would be an easy tweak to fix that?

Cheers,
Martin

On 12-09-12 09:00 PM, Martin Holmes wrote:
> Hi Kevin,
>
> On 12-09-12 07:43 PM, Kevin Hawkins wrote:
>> 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.
>
> I have nothing against including it in the Guidelines, but I think if we
> do start explaining how to use Schematron in the Glines we'll have to
> start from the assumption that readers know less and are much less
> familiar that Council members are with the TEI infrastructure. That
> wasn't my brief. I'm trying to write specifically for people with enough
> understanding of the system that they've made some edits in trunk
> already, seen Jenkins build, and are ready to move on to something
> slightly more challenging.
>
>> 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?
>
> As far as I know. I don't think you can express Schematron constraints
> any other way.
>
>> b) I don't care for use of "to fire" and "to be fired" in reference to a
>> test condition.
>
> I think it's pretty much exactly what happens. We could use "triggered"
> too. What else do you suggest?
>
>> c) Is <report> (fires when true) being contrasted with <assert> (fires
>> when false)?  This is implied but not stated explicitly.
>
> Yes. I should have made that clearer. I guess I was starting from the
> assumption that people would know a little bit about Schematron already,
> but you're probably right that I shouldn't make that assumption.
>
>> 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).
>
> You're right; each Schematron constraint constitutes its own little
> test, and runs only when its exact context conditions are met. It
> doesn't interact with the other validation processes.
>
>> e) You write, "We'll go through the process of adding a constraint like
>> this."
>>
>> Like what?
>
> I guess I meant "like the one above". I'll make it so.
>
>> 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.
>
> Good point. I think I was declaring it on the root because I had a vague
> expectation of adding more constraints to the same file, but perhaps we
> should come up with a standard way that we intend to do this, for the
> sake of clarity.
>
>> g) Why do the pampelmousse and later code snippets have @xmlns:sch at
>> all?  I would remove them for clarity.
>
> They were in the code already, so I left them as they were. If we make a
> decision to do this one particular way (e.g. always declare the
> namespace on the root element of the file, and use the sch prefix
> everywhere else) then we can normalize all existing practice. But
> Sebastian may know of a reason why not -- perhaps there's a non-XML
> process somewhere that lifts out the Schematron snippets and needs them
> to be internally coherent.
>
> Cheers,
> Martin
>
>> --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
>>>>>
>>>>
>>>

-- 
Martin Holmes
University of Victoria Humanities Computing and Media Centre
(mholmes at uvic.ca)