Remove or rewrite TEI-Minimal

[lb42]

The exemplars include an ODD called tei_minimal which should be removed, or substantially revised. When it was created, I believe, the purpose of this was to act as a template for people trying to build their own ODDs by providing what was regarded as the "minimal" set of modules any ODD shouldt choose to select. The result is something misleadingly titled which does not even satisfy the original goal since a minimal ODD does not need anything except the TEI module and a bunch of elementRefs. This would matter less if it were not the case that oXygen releases always include all the "exemplars" (they are supposed to be exemplary, after all), which means that this relic of days gone by will continue to haunt us until we either remove it, or change it to something better.

[martindholmes]

The effect of the Oxygen plugin inclusion of Minimal is to provide a set of templates from which people can start a TEI file (Minimal; Minimal with XInclude; Minimal with MathML; etc.). I think this might actually be quite useful, but perhaps it belongs in the TEI P5 ODD set instead of the TEI P5 set, and should provide minimal customizations to get people started with ODD files, rather than TEI files pointing to minimal schemas.

That said, there might be a lot of people out there who have used these things to get started with a project, and now have a file pointing to a schema like this:

<?xml-model href="http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_minimal.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>

If we remove those schemas, such files will not validate properly.

Cheers, Martin

[jamescummings]

Isn't Minimal used for the 'Build Up' starting point in Roma? (I know that we can keep it for that but not have it in the framework.) If that is the case, then it is a reason for keeping it, no?

[lb42]

@martindholmes ANY of the ODD files provided by the Exemplars could be used as the starting point for a customization. That's what they are for! I am not sure what distinction you're making between "TEI files pointing to minimal schemas" and "ODD files". ODD files are TEI files. And while yes, there MIGHT be some people who still have document instances which point to RNG files derived from one of the ODD files we supply. I'd like to see some evidence for that before committing to continue support for this thing though. @jamescummings : yes, if you ask Roma to "Build Up" you get (all of) the three modules which "Minimal" thinks you need in addition to tei. So your first step in "building up" is likely to be removing a bunch of elements you don't want from the core. So I am unconvinced about its usefulness. But in any case whatever Roma does, this is no reason for retaining Minimal as a starting point in the Oxyygen framework

[martindholmes]

@lb42 The point is not that ODD files are not TEI files; it's that in the TEI plugin there are two distinct sets of templates, one of which is for creating ODD files and one of which is for creating TEI P5 files. The former only has one thing in it right now, and it gives you a minimal TEI file with an empty schemaSpec and nothing much else. What I'm suggesting is that this option could perhaps be enhanced with some more helpful options such as those provided by Minimal in the other ("TEI P5") set. You're right, though, that if we put out a call to the community and no-one admits to having any TEI file whose schemas is defined as being from the Minimal set, we could easily remove them. We should also check the stats on the TEI webserver to see if there are many calls to get these files -- that would presumably only happen for the purpose of validation.

[lb42]

Thanks for the clarification martin. I entirely agree. The current minimal odd should be transformed into a template file.

[ebeshero]

F2F subgroup finds that @jamescummings should try to make a more minimal Minimal, to achieve the smallest possible minimalist TEI.

[jamescummings]

I think I'm confused on what I'm supposed to be doing. Am I supposed to be trying to: 1) write an ODD the customises the TEI so that only the absolutely necessary elements are included? (In which case, isn't this basically what tei_bare does? It does include things like front/back which I would exclude but still...) If we want a starting point for Roma or something, why not just use that? 2) write a new ODD-writing template file to improve on the tei_odds.template to instead have samples of how one might do the standard things people like to do in the ODD language?

Of these number 2 seems the most useful.

I propose that I:

• Remove TEI Minimal as an exemplar at all, or at very least from the oXygen TEI Framework
• Create a new 'Example ODD' or something starting point for ODD customizations and that this replace the tei_odds.template

[martinascholger]

Sounds good to me, I support your proposal.

[sydb]

I agree with the proposal with a caveat: unless we ascertain that no one seems to be using "minimal", it should suffer a deprecation period, no? (@martindholmes is right, people might be using it.) I don't know how we do that, but some thoughts are to a) announce it on TEI-L b) have "(deprecated)" appear next to it in the oXygen list of exemplar schemas c) have a large comment at the top of the oXygen template that uses it d) issue warnings in release notes, maybe?

I don’t think you need to write a new example ODD, do you? Why not just (drastically) improve tei_odds.template?

[jamescummings]

Have you looked at the TEI Minimal ODD? It is just:

    <schemaSpec ident="tei_minimal" start="TEI">
        <moduleRef key="header"/>
        <moduleRef key="core"/>
        <moduleRef key="tei"/>
        <moduleRef key="textstructure"/>
        <elementSpec ident="teiCorpus" mode="delete" module="core"/>
      </schemaSpec>

(https://github.com/TEIC/TEI/blob/dev/P5/Exemplars/tei_minimal.odd#L61-L67)

I don't think anyone is using this except in Roma. The oXygen template (https://github.com/TEIC/TEI/blob/dev/P5/Exemplars/tei_minimal.template) just gives you the standard TEI starting point that you get with any of them. e.g. https://github.com/TEIC/TEI/blob/dev/P5/Exemplars/tei_all.template i.e. if anyone is using it they aren't getting anything special by doing so.

I agree that the example ODD really should just be tei_odds.template (https://github.com/TEIC/TEI/blob/dev/P5/Exemplars/tei_odds.template) but as you note *drastically improved since all this does is give you a schema spec.

So I don't think it needs a deprecation period. I'd remove TEI Minimal from the oXygen framework (and if anyone really wants it they can still download it from release. And then I'd create a new tei_odds.template which gives examples of the top 10 things people want to do, etc. (And I'd even happily have it point are your odd for odds schema if we adopt that? Can't remember what happened about that decision?)

[sydb]

@jamescummings : I don't think anyone is using it, either, but @martindholmes 's point still stands: people may be relying on the existence of http://www.tei-c.org/release/xml/tei/custom/schema/relaxng/tei_minimal.rng. So I'd like a little more assurance that no one is before we zoom ahead (w/o deprecation). If not, at least a warning on TEI-L months in advance.

[raffazizzi]

I agree with @sydb especially re: the use of the derived RNG. A TEI-L message should do it, but I don't think it needs months. "Until the next release" may be enough

[martindholmes]

For the record: I posted a message to TEI-L asking if anyone was using it over a year ago, and got no positive responses, so I think we could get rid of it. I'll wait till after the upcoming release.

[martindholmes]

Just coming back to this ticket to see where we're at. The tei_minimal template options are all still there in Oxygen, and if you choose the basic "Minimal [TEIP5]", you still get a TEI file pointing at the minimal schema on tei-c.org. @jamescummings, did you have a clear idea of what we need to do?

Note that the other "Minimal" options (Math,SVG etc.) give you files pointing at tei_math.rng or tei_svg.rng. Those don't appear to be "minimal" ODDs at all; the SVG one includes not only SVG but also linking and figures, for example.

[lb42]

I say nuke it forthwith. Produce a decent tei_odd template instead. As james noted above, anyone who is actually using tei_minimal.rng can get the same effect in any number of ways.

[martindholmes]

@sydb's TEI ODD Customization template is now in the Oxygen framework; should we now revisit removing these?

I'd like to see a simple taxonomy of all the types of files we want Oxygen users to be able to create from a template, and how they should be distributed across the three plugin groups (TEI P5, TEI JTEI, TEI ODD).

[martindholmes]

Calling Council: This was given status go two years ago, but it's not clear what's supposed to happen. It's easy to remove all the Minimal items from the Oxygen plugin, but lb42 suggests it should be replaced by something, and I don't understand what.

[jamescummings]

@martindholmes In case we need a real tei_minimal ODD, I propose this as a new one: https://gist.github.com/jamescummings/8d44333a86daf5f8be4c24b98f85d30b It is much more minimal than the previous one since we can do moduleRef includes now and just has the 10 elements that tei_minimal.tei exemplar file produces (that are required for the most minimal instance document).

We can replace tei_minimal with my proposed one (much more minimal, moreso than absolutely bare which includes all sorts of things) in the repo and thus if people are pointing to it, still have something there, while not offering it as an option for editing in Oxygen. The other 'TEI minimal' types in the oxygen package I think should definitely be nuked.

While we are at it my oxygen offers me: TEI ODD -> ODD Customization (template points to tei_odds.rng) TEI P5 -> ODD Customization (same thing) TEI P5 -> TEI for writing TEI Customizations (points to tei_customization.rng)

What is the difference now between tei_odds and tei_customization?

[martindholmes]

@jamescummings If I understand correctly, the tei_customization.rng file is @sydb 's schema for tightly constraining ODD files which are intended to be pure TEI customizations (as opposed to ODD files that weird folks like me create to build XHTML5 schemas etc.). I believe the ODD Customization option should not be in the TEI P5 list, just in the TEI ODD list, and I really think the tei_customization one belongs there too, not in TEI P5. But we definitely have a problem explaining this complexity for ordinary users. We have an ODD file for creating a schema for creating ODD files for creating schemas. Makes yore brane hurt.

[sydb]

To elaborate on what @martindholmes just said: Yes, tei_odds is the generic schema for writing ODD files. I.e., it is a pretty simple ODD that produces a schema which allows the user to encode pretty much any sort of ODD file. (All it does is include a bunch of modules including tagdocs, nuke <teiCorpus>, allow <div> and <*Spec> elements to be the root (in addition to <TEI>, and include the RELAX NG schema.) tei_customization on the other hand is an ODD file built from P5 that is intended not so much as a go/no-go gauge for validating various kinds of ODD files, but rather as an assistant for writing one specific kind of ODD file, the TEI customization ODD. I don’t have any strong thoughts on which templates/schemas go where, as I do not understand the difference between being in the TEI ODD pile or the TEI P5 pile. Thus I’ll just trust @martindholmes’s instincts on that for now. (In my oXygen, there is only 1 template in TEI ODD, the “ODD customization” that is repeated in TEI P5.)

[martindholmes]

@jamescummings is it your intention that we should overwrite the current Exemplars/tei_minimal.odd with your new one? I would be in favour of that, and I see no reason not to do it.

[martindholmes]

@jamescummings and I determined that the word "minimal" in the ITS, SVG and MathML templates in Oxygen was unrelated to the "minimal" schema itself; it was just a descriptor in the TEI/@n value of the template files. We've now got rid of that; next is to determine exactly what the so-called "minimal" file should contain, starting from James's excellent proposal.

[martindholmes]

@jamescummings What we did does not appear to have had the desired effect; I still see those options in the File / New / TEI P5 list (Minimal with Internationalization etc.). Could you confirm this (assuming you're also subscribed to the bleeding edge version of the plugin)?

[jamescummings]

@martindholmes Darn. Not tested on my copy since computer I'm at is not subscribed to bleeding edge version. I'll try to do so in the next few days.

[rvdb]

@martindholmes I see them too, version 3.7.20 of the bleeding edge add-on.

[martindholmes]

Thanks @rvdb. Back to the drawing board... Anybody have any idea how those things get in there, or get labelled with the Minimal label? What we want to do is convert those TEI Minimal + something-or-other templates into just TEI + something-or-other, then rewrite the remaining Minimal schema/template.

[martindholmes]

I've replaced the old tei_minimal.odd file with @jamescummings's proposed new one; I'll deal with the inevitable fallout from that, and then we'll try to address the appearance of the word "minimal" in other exemplars.

[martindholmes]

With @sydb figured out that the old templates were hanging around in the plugin because the clean task was not deleting them. Fixed in commit #fa5bf1b. If all is well with bleeding-edge plugin, this ticket can be closed.

[martindholmes]

I think we're done here. There is one more "Minimal with XInclude" still in the exemplars, but I presume that's because people wanted to keep that one.

[rvdb]

Just an afterthought: I see the minimal ODD exemplar file at https://github.com/TEIC/TEI/blob/dev/P5/Exemplars/tei_minimal.odd has been updated.

Is it the intention that Roma will be using that updated version, too, in the future? Right now, it's still offering:

• the TEI Absolutely Bare template
• the old version of TEI Minimal, when choosing the "Build up" option

Hence, I'm wondering if this ticket has consequences for Roma:

• Is this old TEI Minimal in Roma a remnant of the past, and will it be updated to the version I referred to above?
• If answer to the previous question is positive, will this updated TEI Minimal replace the current TEI Absolutely Bare template (since they seem to be fulfilling the same purpose now)?

[raffazizzi]

@rvdb Roma takes the Exemplars from the latest release, so I would expect these new files to become available in both Romas after next release (sometime in summer, unless we are forced to make a smaller release sooner).

[rvdb]

@raffazizzi Ok, thanks for clarifying. So I can safely start using the current TEI Minimal for didactic purposes already.

Still, am I missing anything, or are tei_bare and tei_minimal now nearly equivalent?

[martindholmes]

It does look like tei_bare and tei_minimal have converged to a large degree, although they're structured somewhat differently and explain themselves in slightly different terms. Perhaps they should be merged.