GuidelinesFormattingSuggestions

This is just a page to collect suggestions for changes to the formatting of the TEI Guidelines.

Note: These should be suggestions for formatting the TEI Guidelines themselves, not the TEI Website.

Suggestions for HTML Version of TEI Guidelines

1. Tidying up of the way module descriptions are integrated into the body of the Guidelines.
2. Given how many chapters there are, would it be a good idea to have a drop-down menu for the Table of Contents? Or could we fit however many chapter numbers it is in tabs across the top? (Website Issue?)
3. Sometimes (like right now) Appendix B: Elements, shows the full content of the element description rather than just a list of element names linked to the discussion. I prefer the list of names with links approach. (Agreed, Website Issue?)
4. At the bottom of each page, we have a lower case "edited by..." it should be upper case.
5. With styles off, the presentation of paragraphs is bad, because they are these odd
   constructions. Why aren't they html:p? The tei <--> html p conversion problem was more or less solved, I thought?
6. The navbar if it stays should go on the other side: it should also be relatively width'ed, since you can break it if you crank the text size up. (Website Issue?)
7. First line highlighted when moused over
8. <foreign xml:lang="LA"> is not output as italics e.g.<foreign xml:lang="LA">scriptio continua</foreign>
9. <mentioned> (e.g."<mentioned>poem</mentioned>, <mentioned>title</mentioned">) is not rendered, but probably this doesn't need to be changed
10. The image at http://www.tei-c.org/release/doc/tei-p5-doc/html/SG.html#SG152 is not really well visible even if it comes out nicely once printed
11. Space is output before <gi>prt</gi> e.g. <ptr target="#SG17"/>
12. Better styling of XML examples which are given as CDATA since they aren't TEI elements
13. Better styling of all Relax NG examples.
14. It would be good if attributes could be not only indented as they are now, visualised better or rendered differently from the main text when inserted in the explanation e.g. <specDesc key="head" atts="type"/>
15. Sometimes chapter names not output as in note on http://tei.oucs.ox.ac.uk/Query/tag.xq?name=att.declaring
16. The Appendix E Index: There are an extra line between each entry with an underline which looks odd. And the links does not work here. And I do not quite get by which criteria these index words are selected. And is a one column list the best way to present this? Should there be a paragraph at the top to say that this is?
17. Why are all the notes shown at the front page http://www.tei-c.org/release/doc/tei-p5-doc/html/index.html ? And should it be possible to click on a note to go to the text where the note belongs?
18. What is the purpose of "Skip links" (at to of the menu to the left)? (Website Issue?)
19. The layout of the the entry for each element, macro or classes are different from the rest of the guidelines. Should it be more of the same? For instance is the menu to the left not available. On the other hand I think there should be a distinction between these two parts.
20. The "Up: Contents" at the bottom of the pages, brings you the index page of the guidelines, so maybe it should be called "Up: Front page" of something in that direction. Or should it just go to the top of the page? Need a new name in that case as well. The middle option in the read text at the bottom "TEI Consortium | TEI P5 | Feedback" also brings you to the index page, which is an other argument to make the "Up: Contents" into "Up: Top" or something.
21. Documentation for elements should show the allowed parents for each element (i.e. contexts in which the element can appear). This used to be in the P4 docs but isn't in the P5.
22. egXML markup should be styled such that angle brackets, element and attribute names, attribute values, namespace prefixes, etc, are all distinctly coloured. Lots of browsers have something like for providing a default rendition of XML documents which don't have their own <?xml-stylesheet?> processing instruction. Some of these have + and - things so you can open and collapse elements, which I think we should do without, and I also know Firefox's one omits namespace prefixes on elements, which is just crazy. I have some XSLT code to do XML syntax highlighting hanging around somewhere as part of a Schematron report, I think; I will track it down if you like.
23. Footnotes should be hyperlinked in both directions - i.e. from the reference marker to the note, and from the note back to the reference marker.
24. Change the rendition of tei:ref; it's currently broken: <a target="#FS" class="link_ptr" href="FS.html" title="16">12 Feature Structures</a>.
    1. Target attribute should not be used (it currently has invalid data type anyway - it's not supposed to be a URI).
    2. Title attribute should be meaningful - "16" is hopeless as a title. Hyperlinks from footnote references could usefully include a truncated version of the note body as the title attribute. I've done this at www.nzetc.org (e.g. at http://www.nzetc.org/tm/scholarly/tei-WarEarl-t1-body-d5.html#reference-to-fn1-54 - hover your mouse over the asterisk reference mark ). I've found this is quite useful - sometimes it's not necessary to actually click the footnote reference at all but just hover over it. e.g. <a href="#Note61" title="The BibTeX scheme is intentionally compatible with that of Scribe, although it omits some fields used by Scribe. Hence only one list of fields is given here.">61</a>. (Poss. Problem: title tooltips cropped in some browsers if too long.)
25. html/head/link elements should be provided to navigate the guidelines (i.e. next and previous, toc, glossary, whatever).
26. Headings should have bookmarkable self-referential hyperlinks attached, like you sometimes see on blogs. This is convenient for bookmarking a point in the guidelines. e.g. instead of: <div class="div3" id="PHCO"><h4>14.1.1 Use of Core Tags for Transcriptional Work</h4>...</div> You would have: <div class="div3" id="PHCO"><h4><a href="#PHCO" class="permalink">14.1.1 Use of Core Tags for Transcriptional Work</a></h4><...</div> I've also seen (though I don't know the best HTML/CSS source for it) a technique where a very faint ¶ appears after the heading, which gets darker when you hover over it, and works as a link to the current section. Maybe something like this?:<div class="div3" id="PHCO"><h4>14.1.1 Use of Core Tags for Transcriptional Work <a href="#PHCO" class="permalink">¶</a></h4><...</div>
27. Get rid of the sidebar or make it configurable (But: "where would you put the table of contents?")(Answer:"I would think you could use breadcrumbs for the uplink back to a full toc and have only the toc for the chapter itself at the beginning of the text.")
28. Have a "print view" (In addition to the PDF, a most-formatting-stripped view without layout structure)
29. Show possible parents of elements in the reference chapter
30. Show possible children of elements in the reference chapter
31. Tidy up the display of rng fragments and make the display (and print!) of these passages optional (i.e. When printing, they seem to run occasionally over the edge of the page. Thinking of it, the same also happens to the examples here and there.) (Answer: "both the schema fragments and examples are pretty-printing. and the algorithm obviously needs more tweaking.")

Suggestions for PDF Version of TEI Guidelines

1. No suggestions specifically received so far, except some which carry over from HTML formatting (i.e. that element references should show possible children, etc.)