Avoid reserving class names for specific styles

[bertfrees]

Refer to a quote from James Bowden about the reasons for using reserved class names:

From discussions at eBraille meeting 13 Feb 2024:

We agree the reasons for using reserved class names are:

• To define an object which doesn't have an HTML tag, e.g. a line number, transcriber note.
• If needed for navigation to such items, e.g. navigate directly to a transcriber note
• To show/hide such items - e.g. show/hide print page indicators.
• interoperability - so a different stylesheet can be swapped in to reformat a document (issue #90)
• To better facilitate consistency amongst authoring and software development

Classes may of course also be used just to attach CSS styles, but IMO it is questionable to reserve class names for this. What can authoring and reading software do with this information? How can a style sheet be swapped with another style to reformat the document, while continuing to make use of the class names specific to the original formatting?

Below are some examples of reserved class names that may be acceptable. Sometimes transcribers make very specific decisions when formatting a book. By using reserved class names, the information can be taken into account when reformatting the document for other locales. A condition is that the class names are generic enough. It is also acceptable when a class name describes the style of the print book.

• For ol, ul, dl: nomark
• For p: left-aligned, hanging
• For table: listed, linear, stairstep (see also https://github.com/daisy/ebraille/issues/139)

Sometimes proposed class names are not generic enough, or are even exact descriptions of the CSS styles. I think reserving class names for these cases should be reconsidered.

• For ol, ul, dl, and p: 1-3, 5-7, etc.

[wfree-aph]

@bertfrees Apologies but I am not understanding what changes are needed. My understanding of this issue is that 1-3, 5-7, etc for lists and paragraphs are not generic enough. Is that correct?

If my understanding of the problem is correct, I'll say that the reasoning behind these reserved class values was allow the transcriber to force specific cell positions. It hedges the problem of not always knowing what the transcriber specifically needs. Also, unfortunately, a lot of transcribers seem to rely on these numeric styles currently.

I can, however, see the issue with using them as it goes against the idea of using the same tags with different CSS to produce multiple kinds of formatting. I'm just not sure what the correct fix is.

One option is to remove these numeric class names entirely. This is a tidy solution as it would prevent transcribers from taking shortcuts and force them to apply proper markup. The downside is it would mean we have to plan for a lot of different scenarios and I can't pretend to know what all those scenarios will be. I don't know if anyone can. That's not necessarily a major problem though as we can just address these issues as they come up. They can even be handled by the transcription software locally and if a method becomes accepted, it can be added to a future revision of the spec.

What would you suggest? Should we remove these numeric class names entirely? Or, have I misunderstood the problem?

[wfree-aph]

@bertfrees One aspect of this issue that has occurred to me is that we can remove them from the spec because they are not really "best practices" and that would not prevent a transcription tool from utilizing them if they needed to do so. That solution makes sense to me. We can't really control the behavior of the different transcription programs anyway but we can recommend what is actually "best."

[bertfrees]

Yes, that's what I was thinking. Allowing the transcriber to force specific cell positions is something that will surely be needed, but it's something the authoring software can provide, without the need for reserved classes. The software can use whatever classes it likes.