Disallow obsolete attributes/values

[rmzelle]

Since CSL 1.0, the schema has been rewritten to include separate definitions for dependent and independent styles. As a result, we can be more specific with regard to the attributes and attributes values allowed for each type. We should probably make this change in CSL 1.1 to prevent style from becoming invalid. The attributes/values affected:

• for cs:link, "independent-parent" (independent styles) and "template" (dependent styles)
• for cs:style, "class", and any of the style options (dependent styles)

These can all just be stripped from styles with the next XSLT upgrade script, and removed from the schema.

[bdarcus]

I was just trying to go through and remove pieces we flagged as deprecated for 1.1. Is this the correct patch for these two attribute values @rmzelle? As in, I can simply remove them? PR linked below. You can just click "approved" on the review if good.

diff --git a/schemas/styles/csl.rnc b/schemas/styles/csl.rnc
index 3947925..f9f18c9 100644
--- a/schemas/styles/csl.rnc
+++ b/schemas/styles/csl.rnc
@@ -164,10 +164,6 @@ div {
         |
           ## URI of style documentation.
           "documentation"
-        |
-          ## Obsolete for independent styles. Will be disallowed with
-          ## CSL 1.1.
-          "independent-parent"
       },
       info-text
     }
@@ -187,10 +183,6 @@ div {
         |
           ## URI of style documentation.
           "documentation"
-        |
-          ## Obsolete for dependent styles. Will be disallowed with CSL
-          ## 1.1.
-          "template"
       },
       info-text
     }

[rmzelle]

Is this the correct patch for these two attribute values @rmzelle? As in, I can simply remove them?

If we're okay with the schema being more strict in 1.1 (and have some 1.0/1.0.1 styles in the wild stop validating against the 1.1 schema unless upgraded), then sure.

Note that there are the separate obsolete attribute values on cs:style:

schema/schemas/styles/csl.rnc

Line 53 in 964179d

dependent-style.style.legacy-attributes

schema/schemas/styles/csl.rnc

Lines 60 to 63 in 964179d

	## Obsolete for dependent styles. Will be disallowed with CSL 1.1.
	dependent-style.style.legacy-attributes =
	attribute class { "in-text" | "note" }?,
	style.options

And in the past the CSL project provided a XSLT schema to upgrade 0.8.1 styles to 1.0 (https://docs.citationstyles.org/en/1.0/release-notes.html#updating-csl-0-8-styles). I don't know if we should offer that for 1.1 as well? (e.g. Zotero still ships with it to upgrade 0.8.1 styles on-the-fly: https://github.com/zotero/zotero/blob/bb220ad0f2d6bf0eca6df6d225d3d358cb50a27b/chrome/content/zotero/updateCSL.xsl and https://github.com/zotero/zotero/blob/617564982c81962a9ddf819f7e09385ddd91ec51/chrome/content/zotero/xpcom/style.js#L724)

[rmzelle]

CSL 1.0.1 also introduced new legacy attributes:

schema/schemas/styles/csl.rnc

Lines 521 to 525 in 964179d

	names.et-al.legacy-attributes
	}
	## Ignored in CSL 1.0.1. Will be disallowed with CSL 1.1.
	names.et-al.legacy-attributes = affixes

https://docs.citationstyles.org/en/1.0.1/release-notes.html#affixes-on-cs-et-al

P.S. Never mind, I see you covered these in a separate PR: #221

[bdarcus]

Is this the correct patch for these two attribute values @rmzelle? As in, I can simply remove them?

If we're okay with the schema being more strict in 1.1 (and have some 1.0/1.0.1 styles in the wild stop validating against the 1.1 schema unless upgraded), then sure.

In general, idea of 1.1 is to fix bugs ("sub verbo") and problems (including places where we're being too loose), and add new features (like intext).

Currently, the 1.1 branch schema will not validate 1.0 styles at all. It will require:

<style version="1.1">

The upshot is one would have to choose to target a particular version, and to validate against two independent versions of the schema file.

Reason is two-fold:

1. I concluded it was too complicated to make an already complex schema validate multiple versions. To satisfy this alone does not require a version change on styles though. But ...
2. it is necessary to allow processors to clearly understand processing expectations of the styles they're consuming; for sake of argument, for example, for a new project in 2021 to decide they will only target 1.1. I'm also thinking about Norm's comments here.

Beyond that, I have no opinion on these specific issues. So if you are rethinking whether we should deprecate these, let me know.

Note that there are the separate obsolete attribute values on cs:style:

schema/schemas/styles/csl.rnc

Lines 60 to 63 in 964179d

	## Obsolete for dependent styles. Will be disallowed with CSL 1.1.
	dependent-style.style.legacy-attributes =
	attribute class { "in-text" | "note" }?,
	style.options

Not sure how I missed that; thanks!

And in the past the CSL project provided a XSLT schema to upgrade 0.8.1 styles to 1.0 (https://docs.citationstyles.org/en/1.0/release-notes.html#updating-csl-0-8-styles). I don't know if we should offer that for 1.1 as well? (e.g. Zotero still ships with it to upgrade 0.8.1 styles on-the-fly: https://github.com/zotero/zotero/blob/bb220ad0f2d6bf0eca6df6d225d3d358cb50a27b/chrome/content/zotero/updateCSL.xsl and https://github.com/zotero/zotero/blob/617564982c81962a9ddf819f7e09385ddd91ec51/chrome/content/zotero/xpcom/style.js#L724)

We could; sure.

[rmzelle]

Beyond that, I have no opinion on these specific issues. So if you are rethinking whether we should deprecate these, let me know.

I'm definitely for cleaning up the schema. Just stressing the implications. Having to upgrade styles once-a-decade doesn't seem like too much to ask.

[bdarcus]

OK, merged.

Since I'm maintaining 1.1. on a separate branch, it will be easy for us to review it as a complete release. We can always further tweak things as we move along.

[rmzelle]

And in the past the CSL project provided a XSLT schema to upgrade 0.8.1 styles to 1.0 (https://docs.citationstyles.org/en/1.0/release-notes.html#updating-csl-0-8-styles). I don't know if we should offer that for 1.1 as well? ...

We could; sure.

Maybe we can tag PRs that involve changes where styles/locales can/should be upgraded as such with a GitHub label? (just dropping attributes would be easy to do in XSLT)

(that might be handier than having to update an XSLT for each relevant PR that is merged)

[bdarcus]

I did add a deprecate tag, which I used on these two PRs.

[bdarcus]

And I just added a commit with the XSLT file. It currently only strips link elements with those two values, and updates the version number.

As you can see, it's trivial.

https://github.com/citation-style-language/schema/blob/v1.1/tools/csl-update.xsl

[bdarcus]

Maybe we can tag PRs that involve changes where styles/locales can/should be upgraded as such with a GitHub label? (just dropping attributes would be easy to do in XSLT)

(that might be handier than having to update an XSLT for each relevant PR that is merged)

Wait, not sure I'm understanding your distinction here.

In any case, so far, there aren't many changes for 1.1.

[rmzelle]

I meant, if keeping an XSLT file up to date as PRs are being merged is inconvenient, we could just label PRs that require XSLT work (or another CSL upgrade path) and tackle them all at the end before release of the CSL version in question.

[bdarcus]

Gotcha. We can tag to give us that option.

But there's value in updating the XSLT as we go too, because it helps ensure the changes aren't too onerous.

[bdarcus]

Pretty sure this should be closed now.