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

Table of Contents

1. 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?)
2. 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.")

1. Tidying up of the way module descriptions are integrated into the body of the Guidelines.
2. 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?)
3. At the bottom of each page, we have a lower case "edited by..." it should be upper case.
4. DONE With styles off, the presentation of paragraphs is bad, because they are these odd <div class="p"> constructions. Why aren't they html:p? The tei <--> html p conversion problem was more or less solved, I thought? // Seems indeed to be fixed now Spoke too soon: look at the code for the third paragraph in 15.2.3 (including examples).
5. 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?)
6. First line highlighted when moused over
7. 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
8. Space is output before <gi>prt</gi> e.g. <ptr target="#SG17"/>
9. Better styling of XML examples which are given as CDATA since they aren't TEI elements
10. Better styling of all Relax NG examples.
11. 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"/>
12. Sometimes chapter names not output as in note on http://tei.oucs.ox.ac.uk/Query/tag.xq?name=att.declaring
13. 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?
14. What is the purpose of "Skip links" (at to of the menu to the left)? (Website Issue?)
15. 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.
16. 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.
17. html/head/link elements should be provided to navigate the guidelines (i.e. next and previous, toc, glossary, whatever).
18. 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>
19. Have a "print view" (In addition to the PDF, a most-formatting-stripped view without layout structure)
20. Show possible children of elements in the reference chapter
21. 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.") (Appears to be browser dependent, needs more thought).
22. The rnc rng toggle works great, but I wonder if we shouldn't indicate which version you are looking at when you are looking at the actual code: an <h3> or something at the beginning of the fragment saying "RNG:" or "RNC:" as appropriate would be enough. Currently the button shows the other schema name (because of course it is what you are supposed to click on to get to it). Perhaps that button could be clarified to: "Switch to RNC" etc.
23. The element description in the Element appendix is not part of the table showing the other information about the element. I think this might cause people to miss it. I'd recommend adding it as a first row: <td>Description:</td><td><!-- actual description --></td>

DONE

1. DONE <foreign xml:lang="LA"> is not output as italics e.g.<foreign xml:lang="LA">scriptio continua</foreign>
2. DONE <mentioned> (e.g."<mentioned>poem</mentioned>, <mentioned>title</mentioned">) is not rendered, but probably this doesn't need to be changed
3. DONE 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?
4. DONE 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.
5. DONE 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.
6. DONE 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.
7. DONE 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. DONE Target attribute should not be used (it currently has invalid data type anyway - it's not supposed to be a URI).
   2. DONE 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.)
8. DONE Show possible parents of elements in the reference chapter

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.)