I've been passing my happy whitsun reading and scribbling increasingly irritated notes on a copy of the current state of the TEI Simple documentation, currently located in the P5/Exemplars branch of the TEI-simple branch. It contains the following discrete chunks of verbiage: 1. Some polemic about why TEI Simple is a good thing, and its design goals 2. A simple introduction to XML 3. A presentation of the elements used by Simple along with examples, almost entirely copied from the equivalent part of the TEI Lite document we all know and love (but extended with some ruminations on e.g. hyphenation) 4. A table showing frequency of Simple elements in various corpora/collections 5. A discussion of the processing model elements, and how they are used in Simple (and indeed how some of them are not used in Simple) 6. A schemaSpec which actually defines the TEI Simple schema. Here's the thing. How much of this do we think should be maintained by the Council as an Exemplar? How much of it should be regarded as of historical interest? How much should be published/archived/maintained elsewhere? The part of this which matters is of course the schemaSpec and (probably) the associated prose describing and instantiating the elements. So my first step was to make that valid (the spec had not been updated to reflect our decision that <param> should be an empty element). At the same time I did my best to make the document as a whole follow our usual praxis as regards depiction of XML constructs (i.e. use of <gi>, <tag>, <att>, <ident>, <code> etc. (Regrettably, this led to my reading (2) above more closely than I would have liked) Next, I checked to see whether the doc contained a <specDesc> for each <elementRef> in the ODD. This is a good way of ensuring that the schema contents match the documentation -- that everything the schema makes available is actually discussed or instantiated somewhere. There are 166 elements in Simple, all but 33 of which have a <specDesc>. Which is definitely not bad, but could be improved. In addition, it occurred to me that since the ODD has to provide specs for all the elements that specify a PM, these could also be enhanced to provide examples better tailored to Simple. I still have some reservations about the way Simple treats the Header -- it really doesn't provide much help to beginners to say "oh there's the header you can put anything you like in there. Good luck." But I can see I'll have to wait for the next release to see those addressed. I found DOZENS of examples of verbiage that needs straightening out -- whether to conform to what I consider a sensible consistent style for this kind of writing, or to address errors of fact, or to remove redundant waffle or to make hand-waving generalities more precise. So what's the way forward? As James said at the FTF, Martin Mueller wants to see Simple "replace" or "merge with" TEI Lite in some vague way, We discussed that, and I don't recall any agreement that this would on the face of it be advisable, and certainly in its current state I would vote against doing so on the basis of this document. On the other hand, we really ought to be putting some effort into making Simple a bit more visible and accessible for its target audience. So I propose the following: -- we work on a slimmed down non-polemical straightforward version of the Simple ODD -- revise the discussion of TEI customisations on the website so that it makes clear which ones are in the Council's remit (I make that Lite, Simple, Tite, Enrich, and possibly -- if they ever get their dung collected -- the ISO spoken one) I'll volunteer for a first cut at the former task. Unless of course you all say, no we like the document as it is just fine thanks.
On 16/05/16 17:05, Lou Burnard wrote:
1. Some polemic about why TEI Simple is a good thing, and its design goals 2. A simple introduction to XML 3. A presentation of the elements used by Simple along with examples, almost entirely copied from the equivalent part of the TEI Lite document we all know and love (but extended with some ruminations on e.g. hyphenation) 4. A table showing frequency of Simple elements in various corpora/collections 5. A discussion of the processing model elements, and how they are used in Simple (and indeed how some of them are not used in Simple) 6. A schemaSpec which actually defines the TEI Simple schema.
I think that 4. could just be removed. I think it served its purpose in creation of the schema. 5. could potentially be highly abbreviated now that processing model is in TEI Guidelines.
I still have some reservations about the way Simple treats the Header -- it really doesn't provide much help to beginners to say "oh there's the header you can put anything you like in there. Good luck." But I can see I'll have to wait for the next release to see those addressed.
We could make recommendations for a simple header, but I am still with Sebastian here... part of the point of simple was to create consistent textual content, not mandate how it should be documented in the header.
So what's the way forward? As James said at the FTF, Martin Mueller wants to see Simple "replace" or "merge with" TEI Lite in some vague way, We discussed that, and I don't recall any agreement that this would on the face of it be advisable, and certainly in its current state I would vote against doing so on the basis of this document. On the other hand, we really ought to be putting some effort into making Simple a bit more visible and accessible for its target audience.
I draw Council's attention to the polemic MartinM just posted on the simple list. His believe, if I'm not misrepresenting it, is that Simple should merge with Lite and become the thing that new users are directed towards.
-- we work on a slimmed down non-polemical straightforward version of the Simple ODD -- revise the discussion of TEI customisations on the website so that it makes clear which ones are in the Council's remit (I make that Lite, Simple, Tite, Enrich, and possibly -- if they ever get their dung collected -- the ISO spoken one)
I'll volunteer for a first cut at the former task. Unless of course you all say, no we like the document as it is just fine thanks.
I agree with you in this, it sounds like a reasonable way forward. -James -- Dr James Cummings, James.Cummings@it.ox.ac.uk Academic IT Services, University of Oxford
James (copied below) seems to be the only person to have expressed an opinion on what we should do about TEI Simple in reaction to my comments of the 16th. My reactions to his reactions are as follows: (1) re the header. Yes, if Sebastian were still with us, I would be arguing with him about the way Simple fails to simplify the Header. The point is that if we want TEi Simple to be a useful entry point to the TEI it cannot just do hand waving about the Header. In practice or de iure, beginners need to be told how to write a useful header, and the Simple schema has to enforce that. Faced with the same problem, Tite tries to duck the issue by not requiring a header at all, which is not what I would recommend, even though maybe it would be more honest. But no, you need a header in your TEI Simple document, just as you do in your TEI Lite one. (2) Martin's polemics are always fun to read but sometimes a bit less clear about what he actually wants. It's not unlike someone saying "we must build a wall to keep out the mexicans" -- you can see why they might want to do that, but it's not clear that they've really thought through the implications, or what the exact process for achieving the goal might be. (3) I stand by my earlier offer to produce a shorter sharper document, as a candidate for the TEI branded version of the TEI Simple ODD and have started work on same. On 16/05/16 19:14, James Cummings wrote:
On 16/05/16 17:05, Lou Burnard wrote:
1. Some polemic about why TEI Simple is a good thing, and its design goals 2. A simple introduction to XML 3. A presentation of the elements used by Simple along with examples, almost entirely copied from the equivalent part of the TEI Lite document we all know and love (but extended with some ruminations on e.g. hyphenation) 4. A table showing frequency of Simple elements in various corpora/collections 5. A discussion of the processing model elements, and how they are used in Simple (and indeed how some of them are not used in Simple) 6. A schemaSpec which actually defines the TEI Simple schema.
I think that 4. could just be removed. I think it served its purpose in creation of the schema. 5. could potentially be highly abbreviated now that processing model is in TEI Guidelines.
I still have some reservations about the way Simple treats the Header -- it really doesn't provide much help to beginners to say "oh there's the header you can put anything you like in there. Good luck." But I can see I'll have to wait for the next release to see those addressed.
We could make recommendations for a simple header, but I am still with Sebastian here... part of the point of simple was to create consistent textual content, not mandate how it should be documented in the header.
So what's the way forward? As James said at the FTF, Martin Mueller wants to see Simple "replace" or "merge with" TEI Lite in some vague way, We discussed that, and I don't recall any agreement that this would on the face of it be advisable, and certainly in its current state I would vote against doing so on the basis of this document. On the other hand, we really ought to be putting some effort into making Simple a bit more visible and accessible for its target audience.
I draw Council's attention to the polemic MartinM just posted on the simple list. His believe, if I'm not misrepresenting it, is that Simple should merge with Lite and become the thing that new users are directed towards.
-- we work on a slimmed down non-polemical straightforward version of the Simple ODD -- revise the discussion of TEI customisations on the website so that it makes clear which ones are in the Council's remit (I make that Lite, Simple, Tite, Enrich, and possibly -- if they ever get their dung collected -- the ISO spoken one)
I'll volunteer for a first cut at the former task. Unless of course you all say, no we like the document as it is just fine thanks.
I agree with you in this, it sounds like a reasonable way forward.
-James
On 25/05/16 15:48, Lou Burnard wrote:
James (copied below) seems to be the only person to have expressed an opinion on what we should do about TEI Simple in reaction to my comments of the 16th. My reactions to his reactions are as follows:
(1) re the header. Yes, if Sebastian were still with us, I would be arguing with him about the way Simple fails to simplify the Header. The point is that if we want TEi Simple to be a useful entry point to the TEI it cannot just do hand waving about the Header. In practice or de iure, beginners need to be told how to write a useful header, and the Simple schema has to enforce that. Faced with the same problem, Tite tries to duck the issue by not requiring a header at all, which is not what I would recommend, even though maybe it would be more honest. But no, you need a header in your TEI Simple document, just as you do in your TEI Lite one.
I would still be in favour of providing exemplars for best practice in use of the header and recommend basic ways to do things, but still not constraining it in any significant manner. (Other than the prose/structurd alternative content models I'd be willing to vote for decisions on single ways to do things.) We can use schematron (as I believe the ODD already does) to disallow certain metadata elements under text.
(2) Martin's polemics are always fun to read but sometimes a bit less clear about what he actually wants. It's not unlike someone saying "we must build a wall to keep out the mexicans" -- you can see why they might want to do that, but it's not clear that they've really thought through the implications, or what the exact process for achieving the goal might be.
I'm sure he'd be glad to discuss this in-depth with you. I'd rather we concentrate on getting at least a minimally-agreed TEI Simple into the TEI Exemplars, so that he can report that it is done, with the understanding that details of TEI Simple will of course change as we get bug and feature requests for at least the first few releases.
(3) I stand by my earlier offer to produce a shorter sharper document, as a candidate for the TEI branded version of the TEI Simple ODD and have started work on same.
I would be happy with that (as long as all existing TEI Simple documents still validate).... I'm not wedded to the prose at all. -James -- Dr James Cummings, James.Cummings@it.ox.ac.uk Academic IT Services, University of Oxford
I agree with James. At the same time, though, I worry about how much the
further development and promotion of Simple is going to impact the work of
Council. There's actually a lot more work to be done here if MM's vision is
to come to fruition, I suspect.
On Wed, May 25, 2016 at 11:09 AM, James Cummings wrote: On 25/05/16 15:48, Lou Burnard wrote: James (copied below) seems to be the only person to have expressed an
opinion on what we should do about TEI Simple in reaction to my comments of
the 16th. My reactions to his reactions are as follows: (1) re the header. Yes, if Sebastian were still with us, I would be
arguing with him about the way Simple fails to simplify the Header. The
point is that if we want TEi Simple to be a useful entry point to the TEI
it cannot just do hand waving about the Header. In practice or de iure,
beginners need to be told how to write a useful header, and the Simple
schema has to enforce that. Faced with the same problem, Tite tries to duck
the issue by not requiring a header at all, which is not what I would
recommend, even though maybe it would be more honest. But no, you need a
header in your TEI Simple document, just as you do in your TEI Lite one. I would still be in favour of providing exemplars for best practice in use
of the header and recommend basic ways to do things, but still not
constraining it in any significant manner. (Other than the prose/structurd
alternative content models I'd be willing to vote for decisions on single
ways to do things.) We can use schematron (as I believe the ODD already
does) to disallow certain metadata elements under text. (2) Martin's polemics are always fun to read but sometimes a bit less clear about what he actually wants. It's not unlike someone saying "we must
build a wall to keep out the mexicans" -- you can see why they might want
to do that, but it's not clear that they've really thought through the
implications, or what the exact process for achieving the goal might be. I'm sure he'd be glad to discuss this in-depth with you. I'd rather we
concentrate on getting at least a minimally-agreed TEI Simple into the TEI
Exemplars, so that he can report that it is done, with the understanding
that details of TEI Simple will of course change as we get bug and feature
requests for at least the first few releases. (3) I stand by my earlier offer to produce a shorter sharper document, as a candidate for the TEI branded version of the TEI Simple ODD and have
started work on same. I would be happy with that (as long as all existing TEI Simple documents
still validate).... I'm not wedded to the prose at all. -James --
Dr James Cummings, James.Cummings@it.ox.ac.uk
Academic IT Services, University of Oxford --
tei-council mailing list
tei-council@lists.tei-c.org
http://lists.lists.tei-c.org/mailman/listinfo/tei-council PLEASE NOTE: postings to this list are publicly archived
On 25/05/16 16:58, Hugh Cayless wrote:
I agree with James. At the same time, though, I worry about how much the further development and promotion of Simple is going to impact the work of Council. There's actually a lot more work to be done here if MM's vision is to come to fruition, I suspect.
I think we have a responsibility to integrate TEI Simple into the TEI infrastructure and make it available as an exemplar. I think undertaking it make it the novice's view of TEI or the first TEI people see or merging it, Lite, or other exemplars, etc. are all very different bits of work. I would suggest that we do what we are required to do in the first instance and build on that as requested. -James -- Dr James Cummings, James.Cummings@it.ox.ac.uk Academic IT Services, University of Oxford
So, question for you and Lou: is there anything the rest of Council can do to expedite the completion of the Simple exemplar? Is there more work than Lou slaving over the prose?
On May 25, 2016, at 12:10 , James Cummings
wrote: On 25/05/16 16:58, Hugh Cayless wrote:
I agree with James. At the same time, though, I worry about how much the further development and promotion of Simple is going to impact the work of Council. There's actually a lot more work to be done here if MM's vision is to come to fruition, I suspect.
I think we have a responsibility to integrate TEI Simple into the TEI infrastructure and make it available as an exemplar. I think undertaking it make it the novice's view of TEI or the first TEI people see or merging it, Lite, or other exemplars, etc. are all very different bits of work. I would suggest that we do what we are required to do in the first instance and build on that as requested.
-James
-- Dr James Cummings, James.Cummings@it.ox.ac.uk Academic IT Services, University of Oxford
Well, for one thing the stylesheets need some tweaking in order to display processing model stuff in the reference doc. Or so it seems to me. Sent from my Honor Mobile -------- Original Message -------- Subject: Re: [tei-council] tei not so simple From: Hugh Cayless To: TEI Council CC: So, question for you and Lou: is there anything the rest of Council can do to expedite the completion of the Simple exemplar? Is there more work than Lou slaving over the prose?
On May 25, 2016, at 12:10 , James Cummings
wrote: On 25/05/16 16:58, Hugh Cayless wrote:
I agree with James. At the same time, though, I worry about how much the further development and promotion of Simple is going to impact the work of Council. There's actually a lot more work to be done here if MM's vision is to come to fruition, I suspect.
I think we have a responsibility to integrate TEI Simple into the TEI infrastructure and make it available as an exemplar. I think undertaking it make it the novice's view of TEI or the first TEI people see or merging it, Lite, or other exemplars, etc. are all very different bits of work. I would suggest that we do what we are required to do in the first instance and build on that as requested.
-James
-- Dr James Cummings, James.Cummings@it.ox.ac.uk Academic IT Services, University of Oxford
-- tei-council mailing list tei-council@lists.tei-c.org http://lists.lists.tei-c.org/mailman/listinfo/tei-council PLEASE NOTE: postings to this list are publicly archived
participants (3)
-
Hugh Cayless
-
James Cummings
-
Lou Burnard