[tei-council] some formatting thoughts -- main Guidelines

Thu Sep 27 14:46:49 EDT 2007

* I don't think I'm a fan of the right-hand navigation box. I'm not
  100% on this, but I think I'd prefer to see

  - horizontal line of links at the top to things like TEI home, P5
    home, P5 TOC, element catalog, etc.; also perhaps previous and
    next chapters

  - same line repeated at the bottom (not where the current contents,
    previous, next are, but after the notes)

  - link to previous & next section (I would not bother with "top" or
    beginning of chapter) at each section heading. I am not sure what
    I think about level jumping on back navigation, but I think
    forward navigation should drill down. I.e., "next" for section
    5.1.4 is section 5.2, and "previous" for 5.1.1 is 5.1, but I'm
    not sure if "previous" for 5.2 is 5.1 or 5.1.4.

  - I'm still not thrilled about the near-invisible pilcrows, but
    perhaps I'll warm up to them

* I think that references to elements in running prose should not be
  links to the reference documentation

* I think, pretty strongly, that references to elements should not
  attempt to indicate whether the element is declared as empty or not

* I'm glad <specGrp> and <specGrpRef> are no longer poking their
  noses into the prose. Now let's see if we can tone down the
  intrusion of <moduleSpec>. I think it is a good idea for a chapter
  to name the module that it declares, but I'm not sure that the list
  of stuff defined in the module is necessary. I guess I wouldn't
  object if it were always the very last section of a chapter.
  (Sometimes we have it earlier, e.g. in TS-TranscriptionsofSpeech.

With respect to whitespace inside <egXML> examples
---- ------- -- ---------- ------ ------- --------
Sebastian's stylesheets ignore the whitespace the editors put into
examples and instead auto-generate the indentation. This is generally
a good thing, for a variety of reasons including not having editors
spend hours tweaking whitespace and permitting wrapping. However ...

* comments are not indented

* at the root level an end-tag gets indented one too many

* examples become more convoluted than necessary; see, e.g., the
  example with the string "#B49r" in
  http://tei.oucs.ox.ac.uk/P5/Guidelines-web-beta/en/html/PH.html.
  It would be far more readable if the <lb> elements were aligned:[1,2]

    <pb facs="#B49r"/>
    <fw>De Geometrie 49</fw>
    <head facs="#B49rHead">
      DU SON ET ACCORD DES CLOCHES ET 
      <lb/>des alleures des chevaulx, chariotz &
      charges, des fontaines:& 
      <lb/>encyclie du monde, &
      de la dimension du corps humain.</head>
    <head>Chapitre septiesme</head>
    <div n="1">
      <p>Le son & accord des cloches pendans en ung mesme 
        <lb/>axe, est faict en contraires parties.</p>
      <p rend="it" facs="#B49rPara2">LEs cloches ont quasi fi
        <lb/>gures de rondes pyra
        <lb/>mides imperfaictes & 
        <lb/>irregulieres: & leur accord se 
        <lb/>fait par reigle geometrique. Com
        <lb/>me si les deux cloches C & D 
        <lb/>sont <w facs="#B49rW457">pendans</w> a ung mesme axe 
        <lb/>ou essieu A B: je dis que leur ac
        <lb/>cord se fera en co<expan>n</expan>traires parties
        <lb/>co<expan>m</expan>me voyez icy figure. Car qua<expan>n</expan>d 
        <lb/>lune sera en hault, laultre declinera embas. Aultrement si elles decli
        <lb/>nent toutes deux ensembles en une mesme partie, elles seront discord, 
        <lb/>& sera leur sonnerie mal plaisante a oyr.
        <figure facs="#B49rFig1">
          <graphic url="Bovelles49r-detail.png"/>
        </figure>
      </p>
    </div>

Note: I see a "whitespace before a link" problem on the beta site,
but not when I build it locally.

Notes
-----
[1] I have removed accents for e-mail transmission. I have also
    deleted blanks that occured between an <lb> and the next
    non-whitespace character.
[2] I don't read French, so there may be nothing wrong here at all,
    but just in case I thought I'd ask:
    * Do both those <head>s belong outside the <div>?
    * Should the 'E' of "LEs cloches ont ..." be uppercase?