Best Practice Tagging: Table of contents example under Lists

[jrbowden]

Just wanted to note that the example for table of contents needs more work - this is why I did not attempt one when writing the Wiki examples.

1. There needs to be some kind of class to make sure the (braille) page number was tabbed to a particular position on the line, with appropriate leader dots.
   Current example would render for example as:
   ⠠⠉⠓⠁⠏⠞⠑⠗⠀⠼⠑⠀⠼⠉⠉

whereas we actually want, e.g.:
⠠⠉⠓⠁⠏⠞⠑⠗⠀⠼⠑⠀⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠐⠀⠼⠉⠉

2. It is likely that a user will want to be able to activate anywhere on the entry: the chapter name, leader line or page number) to jump to the content. The current example only shows the page number as the link).

3. Also, (certainly in the UK), the table header lines (such as "Chapter" and "Page" are repeated at the top of each braille page. This is analogous to thead, so we may need a mechanism to do this in combination with a list-like structure.

[wfree-aph]

The example given could actually deliver the output that we want. The CSS would know that we're dealing with a table of contents because of the class name applied to the list and then would know that there is a page number inside that list item. The expanded CSS could then add the appropriate symbols with spaces, based on the size of the line between the text and the page number link. I could definitely be wrong but I don't think the tags need any additional information to make this happen.

I'll also add that this example is just one example. We don't need an exhaustive list but if you wanted to propose the additional examples that you suggestion here in the issue, I think they would be most welcome.

Finally, we will benefit from tagging and examples for the repeated items use case that you mention. Would you or anyone else be willing to write that up? We could probably have a section just about the concept and how you would tag it. The CSS is more important in this instance but it would be good to know how to tag and if there is anything reserved for this kind of material.

[jrbowden]

Again, the class name in the content should be allowed to be anything; it is the CSS that determines behaviour.
Note also that, certainly in the UK, there are three possible types of contents page:

• General contents (which roughly speaking, corresponds to the Contents in the print book)
• Volume contents (which shows what is included in a single braille volume)
• Combined table of contents (a special case where there is only one braille volume for the entire book where both print and braille page numbers are shown - rarer)

In many books in the UK, you may get both a General Contents and a Volume Contents in Volume 1 of a book. They have different requirements, therefore different CSS to determine the behaviour. The class name is therefore cannot be fixed.

e.g.:

<!-- start a new page -->
<p class="CenteredHeading">General Contents</p>
<div class="GeneralContents">
<ul>
...
</ul></div>

Then similar for the Volume Contents.

The CSS would have to determine such things as:

• the column headings
• • whether column headings are repeated at the top of a new page
• the indentation scheme for the hierarchy
• what to do for runover lines
• the leader (if any) between entry and page number
• whether page numbers are shown at all
• whether print or braille page numbers are used
• whether entries are allowed to cross a page boundary or not
• etc, etc.

Note, though original print page numbers could be hard coded into the content, braille page numbers cannot, because the braille page size is variable, according to the reading system. So possibly there might have to be some mechanism that the reading system can calculate the braille page number given say, a link reference.

Again, speculating, an individual TOC entry might be tagged as:

...
<li><a href="#chapt_1_1"><dt>1.1 Basic requirements of the system</dt>
<dd><@brlpageref href="#chapt_1_1" /></dd></a></li>

Again, highly speculative and there may be better ways to do this.

CSS should then have a style called GeneralContents to determine the behaviour.

[bertfrees]

I want to add that the "A table of contents with links" example might also benefit from having span elements around the chapter names. The spans are needed to style the table of contents properly. See the "Table of contents" example in styling best practices. Note that the spans would not be needed if scripting would be allowed, however we want to avoid scripting if possible, hence the need for the additional markup.

Also, there has been the idea of omitting the TOC examples from the tagging and styling best practices, because eBraille publications are already required to have a navigation document, so additional TOCs within the content documents will only be confusing. Instead we could provide examples of lists that are formatted similar to TOCs, such as an index, a table of images, etc.

[jrbowden]

Just to note we can't eliminate tables of contents from the document, because of the need to emboss hardcopy.

[bertfrees]

Yes, you're right. I should correct myself: the idea was to omit TOC examples for now, because we're focused on consuming eBraille publications on electronic reading systems. Adding the TOC examples is part of the work for a future revision that better accounts for the use case of embossing publications on paper.