inconsistent wording of descriptions of attr classes with only 1 attr

[sydb]

When describing (in classSpec/desc) a class that has only 1 attribute we are inconsistent as to whether we say the class “provides an attribute” or “provides attributes”.

class name	desc
att.global.analytic	provides additional global attributes for…
att.fragmentable	provides an attribute for…
att.namespaceable	provides an attribute indicating…
att.notated	provides an attribute to…
att.msClass	provides an attribute to…
att.written	provides an attribute to…
att.milestoneUnit	provides an attribute to…
att.breaking	provides an attribute to…
att.global.source	provides an attribute used by elements to…
att.entryLike	provides an attribute used to…
att.global.facs	provides an attribute used to…
att.enjamb	provides an attribute which may be used to…
att.cReferencing	provides an attribute which may be used to…
att.resourced	provides attributes by which…
att.formula	provides attributes for…
att.partials	provides attributes for…
att.placement	provides attributes for…
att.sortable	provides attributes for…
att.ascribed	provides attributes for to…
att.ascribed.directed	provides attributes for…
att.segLike	provides attributes for…
att.spanning	provides attributes for…
att.declaring	provides attributes for…
att.interpLike	provides attributes for…
att.predicate	provides attributes for…
att.duration.iso	provides attributes for…
att.duration.w3c	provides attributes for…
att.citeStructurePart	provides attributes for…
att.internetMedia	provides attributes for…
att.declarable	provides attributes for…
att.docStatus	provides attributes for…
att.deprecated	provides attributes indicating how…
att.combinable	provides attributes indicating how…
att.rdgPart	provides attributes to…
att.msExcerpt	provides attributes used to…
att.translatable	provides attributes used to…
att.witnessed	supplies the attribute used to…
att.global.change	supplies the change attribute…

[jamescummings]

I've been thinking about this and on a theoretical level I think that class descriptions should always be plural. This holds for model classes as well where appropriate. The reasons something is in a class is basically because it makes sense to semantically group it with related things or it will be used in lots of places alongside those things and specifying it by class is easier than specifying all the individual members. But also it is a class so that customisers may add something to the class and get the benefit of appearing wherever that class is referenced. If it is singular and I add a new element or attribute then I've got to go and change the class description or have my documentation look wrong. Whereas having it plural means that we're indicating it is for attributes or elements of that semantic concept or useful grouping that may or may not be included yet. It is a statement of intention that you can add pLike elements here or facsimile-related attributes there. It is a statement of potential, it is a statement of hope.

[sydb]

I’m convinced, @jamescummings. (That said, someone else could convince me otherwise, I suppose. But my hobgoblin mind probably cannot be convinced that the inconsistency is a good idea.)

[martinascholger]

I agree with both of you. I also prefer consistency and I think the class descriptions should be plural.

[sydb]

I re-thought this earlier today, without reading my previous comments, and was pleased to find that I pretty much agree with my former self: I mildly prefer plural, but don’t really care much, so long as they are consistent.

[JanelleJenstad]

I prefer this wording over the two options on which we are currently voting: "The class provides one or more attributes..." That wording is consistent and true in every case.

[sydb]

At first blush, that is an awfully good idea, @JanelleJenstad. Two (perhaps minor) concerns jump to mind:

1. Is it a bit silly to say “one or more” when we know darn well in any given case whether it is “one” or “more”?
2. But what if a class no longer provides any attributes (ostensibly because the customizer has removed them all)?

I think I can handle concern (2) pretty easily. If the customizer has removed the last attribute, she is responsible for either just deleting the class or changing the description. We can’t be responsible for extreme actions like that.

But (1) does give me a bit of reason for pause. I think the answer is “well, maybe a little, but no more silly than using the plural when we know there is only 1, and you’re perfectly OK with that, Syd”, but it would make me feel better if others think (1) is not a problem.

[ebeshero]

Hi all! Having just written up att.locatable , a class with just one attribute (for the moment), awaiting review and merge in a pull request near you, I find I prefer the plural for conveying potentiality. This attribute class, however many (or few or no) attribute(s) it has now, can perhaps one day contain more. There’s something hopeful about that.

[JanelleJenstad]

I like @ebeshero's optimism. The potentiality of the plural is indeed full of hope. (I don't object to plurals, even though I like my suggestion, so perhaps the strong consensus on plurals means we should go with them.)

[martindholmes]

I agree. Customizers may add new attributes to a class containing only one, or remove attributes so that a class ends up containing only one, so "one or more' is the most robust formulation.

[martinascholger]

Really good idea @JanelleJenstad, I didn't think of it when setting up the poll. I've now looked at the model classes and we use plurals there, even for classes with only one element (see https://tei-c.org/release/doc/tei-p5-doc/en/html/ref-model.applicationLike.html). One option would be to also change the description of the model classes to "one or more". Nevertheless, I lean towards plurals.

[jamescummings]

Just as I believe in a singular 'they', I also believe in a non-specific plural of potentiality. I've nothing against 'one or more' but saying a class 'provides attributes' in my mind doesn't actually specify whether there are zero, one, or more attributes. It is non-specific in that it just says the class 'provides attributes' which I take also to mean 'potentially provides attributes' without the word potentially there because any class could have zero, one, or more attributes because the TEI framework allows customisation. Having a plural 'provides attributes' says that the job of the class is to provide attributes regardless of whatever the reality may be. (Same with model classes)

But if you went with 'zero or more' I wouldn't complain.

[martinascholger]

In this context, the restrictive pronouns in the descriptions have been changed from "which" to "that", see #2176