Lists of members for classes/macros are confusing

[joeytakeda]

Following the reconfiguring of attribute lists in #592 ("Attribute lists are confusing"), I think model class spec pages should also have a more expanded view to be less confusing:

E.g. The table for model.paraPart is very difficult to parse to figure out how elements are enrolled into the class:

Members: model.gLike [g] model.global [model.global.edit [addSpan app damageSpan delSpan ellipsis gap space witDetail] model.global.meta [alt altGrp certainty fLib fs fvLib index interp interpGrp join joinGrp link linkGrp listTranspose precision respons span spanGrp substJoin timeline] model.global.spoken [incident kinesic pause shift vocal writing] model.milestoneLike [anchor cb fw gb lb milestone pb] model.noteLike [note noteGrp] figure metamark notatedMusic] model.inter [model.attributable [model.quoteLike [cit quote] floatingText said] model.biblLike [bibl biblFull biblStruct listBibl msDesc] model.egLike [eg egXML] model.labelLike [desc label] model.listLike [list listApp listEvent listNym listObject listOrg listPerson listPlace listRelation listWit table] model.oddDecl [classSpec constraintSpec dataSpec elementSpec macroSpec moduleSpec outputRendition specGrp specGrpRef] model.stageLike [camera caption move sound stage tech view] castList] model.lLike [l] model.phrase [model.graphicLike [binaryObject formula graphic media] model.highlighted [model.emphLike [code distinct emph foreign gloss ident mentioned soCalled term title] model.hiLike [hi q] ] model.lPart [caesura rhyme] model.pPart.data [model.addressLike [address affiliation email] model.dateLike [date time] model.measureLike [depth dim geo height measure measureGrp num unit width] model.nameLike [model.nameLike.agent [name orgName persName] model.offsetLike [geogFeat offset] model.persNamePart [addName forename genName nameLink persPronouns roleName surname] model.placeStateLike [model.placeNamePart [bloc country district geogName placeName region settlement] climate location population state terrain trait] eventName idno lang objectName rs] ] model.pPart.edit [model.pPart.editorial [abbr am choice ex expan subst] model.pPart.transcriptional [add corr damage del handShift mod orig redo reg restore retrace secl sic supplied surplus unclear undo] ] model.pPart.msdesc [catchwords dimensions heraldry locus locusGrp material objectType origDate origPlace secFol signatures stamp watermark] model.phrase.xml [att gi tag val] model.ptrLike [listRef ptr ref] model.ptrLike.form [oRef pRef] model.segLike [c cl m pc phr s seg w] model.specDescLike [specDesc specList] ruby] lg

I think it would be much better to have a similar system as the attributes that goes:

• CLASS: ELEMENT ELEMENT
  • CLASS: ELEMENT ELEMENT

For example:

• model.gLike: g
• model.global: figure metamark notatedMusic
  • model.global.edit: addSpan app damageSpan delSpan ellipsis gap space witDetail
  • model.global.meta: alt altGrp certainty fLib fs fvLib index interp interpGrp join joinGrp link linkGrp listTranspose precision respons span spanGrp substJoin timeline
  • model.global.spoken: incident kinesic pause shift vocal writing
  • model.milestoneLike: anchor cb fw gb lb milestone pb
  • model.noteLike: note noteGrp
• model.inter: castList
  • model.attributable: floatingText said
  • model.quoteLike: cit quote
  • model.biblLike: bibl biblFull biblStruct listBibl msDesc
  • model.egLike: eg egXML
  • model.labelLike: desc label
  • model.listLike: list listApp listEvent listNym listObject listOrg listPerson listPlace listRelation listWit table
  • model.oddDecl: classSpec constraintSpec dataSpec elementSpec macroSpec moduleSpec outputRendition specGrp specGrpRef
  • model.stageLike: camera caption move sound stage tech view

[martindholmes]

+1 from me. Shouldn't be too hard to do. My only concern is that this is a part of the page that many users will never look at, and in the case of listings like this, they will take up a lot of space, obscuring what people want to get to. Maybe when they're beyond a certain size, make them into an expandable details element?

[sydb]

+1 from me, too. Although I do not share @martindholmes’ concern that it be expandable, I do not object, either. I do want the class names to be renditionally distinct from the element names. (Visually being separated by a colon is insufficient, IMHO.)

[joeytakeda]

Okay I've had a first pass at this in branch iss769_classes. Processing was updated to group class members and split into separate lists; this makes the structure basically the same as the attLists (and thus the same CSS could be repurposed).

Note that running the build from that branch does not do the compressed list nicely since the CSS in the TEI repo — I've made a sub-issue for that in TEIC/TEI#2757 and corresponding branch. Also I haven't updated the tests yet, so the branch is currently broken—if we decide that we like this, then I'll go ahead and update the expected results accordingly.

Sample image:

[jamescummings]

I share @martindholmes' concerns about it pushing the examples even further down the page. That is what most users are looking for. If it were expandable with the first X characters shown on the screen and then a very visible [see more] link to click, then that would work? (In non-web environments, obviously it all shows)

[martindholmes]

@jamescummings I think it would be slightly more awkward to arrange a "show the first x characters setup without javascript, but the xslt could just check the length of the result and wrap it in a details element if it exceeds a specific threshold. @joeytakeda what do you think?

[joeytakeda]

This is just for the model class pages (eg https://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-model.paraPart.html), so I don’t share the concerns above about the length of the page, personally. Unless I’m missing something here, as far I understand it, there are no examples on those pages or any other content below the list of Members. Plus these pages are ones that few users look at anyway, so the ones who do come to it probably would like to see everything anyway, no?

[martindholmes]

Ah, I was assuming something similar would be done for all lists of elements in their modules and classes wherever they appear. In that case, I have no objection at all. Definitely an improvement.