[tei-council] some formatting thoughts -- reference documentation

[Syd Bauman]

* Most importantly (and Julia gets credit for convincing me of this),
  the reference documentation pages need a "how to read this page"
  guide. Just as when the utility company changes the look & feel of
  your bill, they send along a "how to read your new bill" leaflet, we
  need to give the perplexed guidance here. A more web-like way to
  accomplish this, I think, would be to do the following.

  - Give the page an intelligent header, e.g. "TEI P5 Reference
    Documentation for class model.choicePart".

  - Put back some sort of indication that the references produced by
    the <ptr> elements in <listRef> are of the "read more about it"
    flavor; if folks like the references being listed at the
    top with the description, perhaps just preceding by "See further:"
    would do.

  - Put a "(?)" icon link next to each row heading, and link them to a
    pop-up window with a *short* description of what the information
    means -- remember, lots of readers will not have read the
    Infrastructure chapter yet, and won't know what a module is, or
    will be confused by this "Members" business. These short
    descriptions
    + don't need to be part of the Guidelines per se
    + can (and perhaps should) be written by Christine, Julia, and the
      UVa web team
    + should include a link(s) to relevant section(s) of the Guidelines
    E.g.: "*Members*: This section lists each of the elements which is
    a member of the class being documented. If the class in question
    is an attribute class, then this means that each of the elements
    listed has the attributes defined by the class, which can be found
    in the *Attributes* section. If the class in question is a model
    class ..."

* The same stuff I said about navigating the main Guidelines applies
  here. There should be links to (among other things) the class,
  element, and macro catalogs from top & bottom navigation bars.

* If we're going to go with the javascript alphabet-box, we should do
  so for classes & macros too, no?

* Should we have an appendix that holds all the info that is
  generated by <moduleSpec> as a gray box mid-prose now? It would
  list the modules, and for each module all the classes, elements,
  datatypes, and other macros defined in that module.

* For the opening page to Appendix A, Classes, attribute and model
  classes have to be separated somehow. Here is one suggestion.

  - large alphabetical list gets divided between model classes and
    attribute classes;

  - javascript alphabet box has 26 letters, "show all attribute
    classes" and "show all model classes" (and perhaps "show by
    module", if we were to make that available);

  - for each class, it gets tucked into A-Z based on the 1st letter
    after 1st dot -- e.g. 

    S: model.segLike,  model.settingPart,  model.singleVal,
       model.sourceDescPart,  model.specDescLike,  model.stageLike;
       att.segLike,  att.spanning

    of course, if it's a whole lot easier to code, we could just
    consider breaking it into 2 appendices.

* The same is theoretically true of datatypes and macros, but there
  are so few macros it is not as important.

* For the opening pages, more is needed to visually separate one
  entry from the next in the lists of links -- perhaps more
  whitespace, perhaps separate with commas, perhaps both.

* The contents of the "Contained by" cell are confusing. (Already one
  smart experienced encoder has asked me whether the occurrence of a
  model class in that slot means that the element being described can
  be a child of each member of that class.) One suggested solution:
  
  - split out a "Member of" row for classes
  
  - for "May be contained by" list direct parentage first (as I think
    is done already -- the green ones), then, analogously to "May
    contain" by modules, list other possible parents by class.

  - E.g., <u>:

    Member of           | model.pPart.transcriptional model.choicePart
    May be              | as model.pPart.transcriptional: subst, bibl, 
    contained by        | byline castItem closer date dictScrap
                        | docImprint entryFree etym form gramGrp lem
                        | opener rdg re sense time u x ab add camera
                        | caption case cell colloc corr damage def del
                        | docEdition emph gen gram head hi hyph iType
                        | imprimatur l lang lbl mood number orig orth
                        | p per pos pron ref reg restore rhyme seg sic
                        | sound stress subc supplied syll tech title
                        | titlePart tns unclear usg writing abbr actor
                        | addName addrLine affiliation author
                        | biblScope birth bloc catchwords cl colophon
                        | country dateline death distinct distributor
                        | district docAuthor docDate edition editor
                        | education email expan explicit extent faith
                        | finalRubric floruit foreign forename fw
                        | genName geoDecl geogName gloss headItem
                        | headLabel heraldry incipit label material
                        | measure mentioned name nameLink nationality
                        | num occupation orgName persName phr
                        | placeName pubPlace publisher region
                        | residence role roleDesc roleName rs rubric s
                        | salute secFol settlement sex signatures
                        | signed soCalled socecStatus speaker stamp
                        | street summary surname term textLang trailer
                        | watermark wit witDetail accMat acquisition
                        | additions collation condition custEvent
                        | decoNote filiation foliation handNote item
                        | layout musicNotation note origin provenance
                        | q quote said source stage support surrogates
                        | view
                        | as model.choicePart: choice

    Yes, it's a long list, so it probably should be collapsible. (I'm
    not actually a big fan of these lists, at least not for the main
    documentation, but some users really seem to like them.)