Guidelines Appendices should include a list of pending deprecations

[jamescummings]

We should have an appendix (or something else?) in the Guidelines which lists all the elements/attributes/etc that will be deprecated and the dates-after-which the deprecation will happen.

[duncdrum]

I like the idea, how about making one table for depreciation, and one with links to GH issues discussing specific elements? It could help increase the traffic between GH and tei-c.org?

[jamescummings]

Hi @duncdrum. I'm not sure about the second idea... there can be many issues on one particular element which we would want on separate issues in github. (e.g. one discussing its definition, another one wondering about its content model, another one proposing new sample values for one of its attributes....etc.)

What might be better is a generic 'Raise an issue about this element on GitHub' button which copied in the reference page url and gave a template for submitting a good issue. Like the kinds of things you get with bug submission systems...

[sydb]

Whether just an appendix listing deprecations (which, BTW, needs to include auto-generated items that are deprecated with @validUntil and hand-written items that could not be deprecated w/ that mechanism), or also a “raise issue on GitHub” button (which idea I worry would be opening a floodgate), seems to me this ticket belongs — or at least also belongs — in the Stylesheets repo.

[martinascholger]

I think it is a good idea to have an appendix listing the deprecations. I think it would fit after Appendix E, Appendix F Deprications? Or is it bad style to restructure the appendices?

I'm a bit worried too about the "raise an issue on GitHub" button, but maybe we should discuss this in the context of the ongoing internationalization process and our idea to possibly introduce a "suggest a translation" button?

[jamescummings]

@sydb In my envisioning of it I'm picturing a stub file with the start of a list of deprecated objects. In building the Guidelines this is then added to for all those using validUntil or similar. I.e. we manually add those for which we don't have a mechanism.

@martinascholger Other than people having cited the letters of the appendices or something I don't think it is too much of a problem to insert an appendix. Another option is to have it just as an additional page produced alongside the Guidelines but not in the Guidelines. i.e. It might sit in the Guidelines release directory but be listed on the index page on the right under TEI Sourcecode, or similar.

The feedback mechanism of a generic 'Create an issue' say on all ref-*.html pages is really a separate issue in itself I guess. We currently have a 'Feedback' link on the footer of every page, which goes to http://www.tei-c.org/About/contact.xml which has a 'Submit an issue in GitHub' link that just goes to the issues page for the TEIC/TEI repository. The problem with that, of course, is we have several repositories. It would be nifty to have it go to something that directed your query a bit.

[raffazizzi]

F2F subgroup suggests to mark this green and @martinascholger to proceed coordinating the creation of the appendix. Connections to GitHub and internationalization are deferred to later / separate issue.

[martindholmes]

Added P5/Utilities/listDeprecations.xsl in commit 12736aa to generate a P5 document containing a table of all the current deprecations in p5subset.xml. The next stage is to incorporate that process into the GL build process, and then to integrate that table as (e.g.) REF-DEPRECATIONS.html, and then decide what Appendix letter it should have.

[martindholmes]

I've done a few more things in subsequent commits that get us closer to making this work. I think the last thing is to figure out how the appendix generation bits (divGens) trigger processes, and hook in a new process for the new appendix.

[martindholmes]

Made a commit to the Stylesheets in common/common_tagdocs.xsl which I think should enable processing of divGen[@type='deprecationcat'].

[martindholmes]

This is basically done:

https://jenkins.tei-c.org/job/TEIP5-dev/lastSuccessfulBuild/artifact/P5/release/doc/tei-p5-doc/en/html/DEPRECATIONS.html

But the results are not (yet) pretty. It's Appendix G -- that seemed the most logical place to put it -- and it's tabular. But @jamescummings @martinascholger @hcayless please have a look and make some suggestions as to what it should look like (pointing at other Guidelines tables that exist for examples) and whether you think any additional info is required. The other thing each item should obviously do is link to somewhere in the Guidelines pages, but I haven't figured out the approved method of making that happen.

[sydb]

@martindholmes — your description of what you did doesn’t entirely match @jamescummings “envisioning”. Where do things that are deprecated manually (as opposed to with @validUtil) get put?

[martindholmes]

Sorry @sydb, I didn't properly understand what was being asked for. I thought it was just a list of deprecations. I don't really know what a manual (as opposed to @validUntil) deprecation is; I guess I wasn't around for those discussions. Should I back out my changes to the two repos?

[martindholmes]

@sydb there is now a deprecation XML file in the repo, though, so it would be easy to add textual explanations of anything you like in there, above the <divGen>.

[sydb]

For an example, see P5/Source/Specs/content.xml (search for “deprecated”).

I’ll take a look at the DEPRECATION file soon.

[sydb]

Well, when I build the Guidelines, the DEPPRECATION.html file looks like that <divGen> was not processed.

But if & when it is working, seems to me it might do fine depending on formatting, separation, etc.

[martindholmes]

Would it be sufficient to harvest the constraintSpecs whose idents end in "-deprecated" and echo out their error messages? That would be easy.

[martindholmes]

@sydb Did you update your stylesheets before doing the build? This is one of those cases where the Stylesheets and the TEI repos both required changes.

[sydb]

Right! Probably not. On it …
(I see that it works in the latest build.)

[sydb]

OK. Got it working. Looks good.
A first crack at dividing DEPRECATIONS into two sections (manual & auto): 364b150

[martindholmes]

@sydb the latest incarnation shows correctly-linked items for most cases:

https://teijenkins.hcmc.uvic.ca/job/TEIP5-dev/lastSuccessfulBuild/artifact/P5/release/doc/tei-p5-doc/en/html/DEPRECATIONS.html

but a couple which didn't end up linked; I need to investigate that. And it looks like constraint-based "manual" deprecations are also being pulled into the main table, so perhaps we only need one table after all?

[sydb]

Well, it’s not clear to me that there will always be a constraint specification (or @validUntil) if there is a deprecation. Is it not the case it might be expressed only in prose? Idunno. (E.g., if we were to remove the expectation that a <title> child of <monogr> has an @level of "m" or no @level at all — why we would ever remove that, and why there is no <constraintSpec> for it are a different matter.)

One way we could handle this is to say that when something is deprecated we always put in a @validUntil, even if we have to put in an empty <constraintSpec> to get it. (Well, one with only a <desc> child.)

I don’t see how the manual deprecations got pulled into the table: I only see a for-each //attribute::validUntil … did those constraint specifications already have @validUntil?

So I’m trying to think through how this should work. I.e., how do we get a useful, human-readable description into the table? (Probably should be a 4th column.) The elements that can have @validUntil are: <attDef>, <classSpec>, <constraintSpec>, <dataSpec>, <elementSpec>, <macroSpec>, <moduleSpec>, <paramSpec>, <schemaSpec>, <valDesc>, <valItem>, <valList>, and <defaultVal>. All of those except <constraintSpec>, <paramSpec>, <schemaSpec>, <valDesc>, <valList>, and <defaultVal> have a child <remarks>; and of those 6 that do not use <remarks>, only the last 3 are also missing <desc>.

So putting a special @type on <desc> would work for all but <valDesc>, <valList>, and <defaultVal>; but that does mean finding every other place where <desc> is processed, and adding a predicate. Hmm …

[martindholmes]

There's now only a single table, and links are working there. Now I think all that remains is cosmetic work. @jamescummings @martinascholger @sydb could you take a look at the results:

https://jenkins.tei-c.org/job/TEIP5-dev/lastSuccessfulBuild/artifact/P5/release/doc/tei-p5-doc/en/html/DEPRECATIONS.html

and suggest what things should look like and what needs fixing.

[martindholmes]

I've now added some basic styling to the table, added i18n keys in Stylesheets/i18n.xsl for the headers, and integrated the translation call into the XSLT in common_tagdocs.xsl. Translations are still needed, of course. The description column will be populated once @sydb has completed his work adding the required desc elements in the TEI source.

[martindholmes]

To clarify what @sydb and I are doing to make this work: all items which are deprecated will have @validUntil, and they will also be required to have descendant::tei:desc[@type='deprecationInfo'], which will hold the human-readable explanation of the deprecation, along with hints for working around it if you need to. These descs need to be added, but requiring them is a good thing anyway.

[sydb]

To further explicate @martindholmes’ previous post …

We had to make some decisions when implementing this ticket which Council may wish to weigh in on:

1. Every deprecation, even if it would currently be dealt with only in prose, will require an @validUntil. Thus if we really have a “prose-only” deprecation in the future, we would need to add a <constraintSpec> (even if it had no <constraint>, which, after all, is optional) in order to hang the @validUntil on.
2. Every deprecation of an element that has <desc> in its content model (as a child) will need to have a <desc type="deprecationInfo">. (It is the contents of this that shows up in the table in the appendix to explain the deprecation to users.)
3. When a <constraintSpec> is used to express or warn about a deprecation, it should bear a type="deprecationWarning" attribute. (This allows us to differentiate when @validUntil is on a <constraintSpec> because it (the <constraintSpec>) is being deprecated itself, rather than it is enforcing some other deprecation.)
4. This all means we will need to go through the Stylesheets to ensure that <desc type="deprecationInfo"> elements are not processed along with regular <desc>s.

I don’t want to check in the changes to the specs (that add these @type attr values and constraints thereon) until I have the <desc type="deprecationWarming">s in place, as doing so would break the build. It will take a few days to get that done. (Good plane fodder!)

Yes, we should have done this in a separate branch. But a) we started before we realized we should have, and b) Martin is deathly afraid of the Stylesheets-TEI repo anti-feedback loop that would occur if we used a different branch. (I don’t care as much, because I build the Stylesheets locally, instead of on Jenkins.)

[martindholmes]

@sydb I'm not deathly afraid. It's just not practical to have two branches in two separate repos dependent on each other, with parallel pull requests, and Jenkins can't build such a mess of stuff without multiple new Jenkins jobs. The two repos should never have been separated.

[jamescummings]

On the prose before the table is

which are deprecated in this revision of the TEI Guidelines
The right thing to say?
Maybe:
which are currently listed as deprecated in this revision of the TEI Guidelines
Or something?

(i.e. it isn't necessarily this revision that has deprecated it.)

Also, why not include a count of deprecated things (similar to other appendices like elements)?

[martindholmes]

@jamescummings you can edit DEPRECATIONS.xml to make the change. I'm not sure what the value of a count is, but if you want to add it, it would be another of the processing-instruction things we've added before.

[sydb]

I think the change @jamescummings recommends is fine, but I hold that the current wording asserts the list is the list of things that are deprecated in this revision, not that they were first deprecated in this revision.

And as for a count, I have nothing against it, but seems like a waste of time to me. Most of the time there are fewer than 1/2 dozen dozen deprecations. (We happen to have a lot due to the datatypes now, but those all go away next month.)

[lb42]

While warmly applauding the decision to provide some explanation for deprecations and guidance on what to do if you're affected by one, I wonder whether this is an over-engineered solution. So I propose to engineer it further: shirley there should be a constraintSpec on the attribute @validUntil to enforce the requirements syd sets out above? Also, as regards the data.* deprecations, this is a fairly special case, which probably should be addressed explicitly by a (series of?) postings to tei-l etc

[sydb]

Yes, there should be constraints, and there already are in some sense — but I have not checked them in yet as they break the build until the conditions are satisfied. I’m planning to check both in in roughly 24 hours.

As for the data->teidata, the old ones already get the red warning boxes, but I think @lb42 is right, a posting to TEI-L is in order, too. I’ll plan to post a 2-week warning on or about Mon 17 Sep.

[sydb]

Checked in at c0e061a

[martindholmes]

Done and working.