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.

Navigation

 * 1) DONE 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) DONE 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.")
 * 3) DONE 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?)
 * 4) DONE html/head/link elements should be provided to navigate the guidelines (i.e. next and previous, toc, glossary, whatever).
 * 5) DONE 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. This is a problem

Code Examples Styling

 * 1) DONE Better styling of all Relax NG examples. Is this being taken care of with the RNG/RNC switch? (only partly... Yes that give better styling, but we want (better) syntax highlighting of both of them.  Also links in the RNG for model.foo etc.)
 * 2) DONE 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).

Appendix B

 * 1) DONE 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:  Description:     I'm not sure what is the issue here
 * 2) (JC:) Maybe a 'prev element'  'toc' 'next element' in the element reference pages?
 * 3) DONE Alphabetised grouping of elements in appB similar to: http://www.oucs.ox.ac.uk/atoz/ but show-all should have option of alphabetised grouping or by-module grouping.

Changes in Styles

 * 1) Better styling of XML examples which are given as CDATA since they aren't TEI elements
 * 2) DONE 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.   If I understand this correctly then I agree. What about italicizing them? There doesn't seem to be rhyme or reason for when attributes appear in the explanation and when they do not.
 * 3) DONE First line highlighted when moused over I don't understand. Is this a comment or a request? "First line" of what? (In some of the rendering the first line of text used to be rendered with an underline appearing when moused-over.  I believe this was an accidental CSS error and has been solved, but I've left it here to double-check later.)
 * 4) DONE 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.
 * 5) DONE Have a "print view" (In addition to the PDF, a most-formatting-stripped view without layout structure) (though only accessible through printing or print-preview)
 * 6) DONE Show possible children of elements in the reference chapter

Changes in Source
'''Many readers are mystified by the bits that say e.g. "include 69 : Specialized front matter for performance texts". No-one has yet proposed a sensible way of dealing with them however... if we had a clear idea of what was needed then we could deliver it! By the way, all chapters in the main body of the Guidelines now define exactly one module. (LB)'''
 * 1) DONE Tidying up of the way module descriptions are integrated into the body of the Guidelines. I'm not sure what this means. Is this a reference to the Reference Section that appears at the end of some module-centric chapters? Perhaps the confusion is that some chapters describe modules (msDescription) while others do not. How can we clarify the relationships between modules and chapters?
 * 1) DONE 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? // Seems indeed to be fixed now Spoke too soon: look at the code for the third paragraph in 15.2.3 (including examples).
 * 2) DONE 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 The image file is 540 px wide but the @width value on limits it to 480px. So the image is being squished. Either the value for image@width needs to be increased or the image file needs to be shrunk.
 * 3) Space is output before ptr e.g.   That is an extra space in the code (between > and E), not a problem with the styles.
 * 4) 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 what this is? I agree completely. The Index needs a good hard look. Those little lines are weird.
 * 5) DONE Sometimes chapter names not output as in note on http://tei.oucs.ox.ac.uk/Query/tag.xq?name=att.declaring I don't know if this is a problem with the styles or with the source

DONE
Done in this case means it has been done on the (unadvertised) guidelines-beta site, but may not have been merged into mainstream TEI.

rendered, but probably this doesn't need to be changed
 * 1) DONE  is not output as italics e.g. scriptio continua
 * 2) DONE (e.g." poem, title ) is not
 * 1) 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?
 * 2) 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.
 * 3) 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  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.
 * 4) 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.
 * 5) DONE Change the rendition of tei:ref; it's currently broken: 12  Feature Structures.
 * 6) DONE Target attribute should not be used (it currently has invalid data type anyway - it's not supposed to be a URI).
 * 7) 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. 61. (Poss. Problem: title tooltips cropped in some browsers if too long.)
 * 8) DONE Show possible parents of elements in the reference chapter
 * 9) DONE 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 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.
 * 10) DONE At the bottom of each page, we have a lower case "edited by..." it should be upper case.
 * 11) DONE 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: 14.1.1  Use of Core Tags for Transcriptional Work ...  You would have: 14.1.1  Use of Core Tags for Transcriptional Work <... 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?: 14.1.1  Use of Core Tags for Transcriptional Work ¶ <...
 * 12) DONE 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?)

Website Issues

 * 1) DONE What is the purpose of  "Skip links" (at to of the menu to the left)?   (Website Issue?)

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