eBraille Tagging Best Practices

…

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

Asides are used for material that is indirectly related to the document's main content. Examples would include sidebars or call-out boxes.

Element(s):

aside

Reserved class values:

• none

Boxes may be created by lines of braille characters, above, below, to the left or right of a block of text. The characters used, the size and which sides to show, are controlled by CSS.

Element(s):

div

Reserved class values:

• box, nemeth

How to use class values:

• box is used to signify a standard box.
• Put box inside box when a box contains a box.
• nemeth is used for a box that has begin and end Nemeth symbols in its box lines.
• Various strings can be used for boxes with specific text needs. Examples could include boxes with color. There is no way to define all possible strings that could be used in such a scenario. The writing software will need to define the limitations and allow the user to input the string, which is then used as the class to allow the CSS to input that string into the box line.

Braille grade refers to whether contractions are used in the braille transcription. In Unified English Braille, for example, grade 1 braille uses no contractions, while grade 2 uses any applicable contractions. Documents can be in one grade but with sections that appear in a different grade.

Element(s):

span

Reserved class values:

• grade-0, grade-1, grade-2

Note that terms for braille grade vary throughout the world and that grade-related class values do not directly correlate to how a local region may understand the terms. Hence, in a region where uncontracted braille is called Grade 1, grade-0 is preferred for the class name so that these terms may be better understood internationally. Basically, one should use the least value class for the least contracted grade of braille and move up in value from there.

Additionally, braille grade should only be specified when it changes within the document. Otherwise, metadata is sufficient.

Captions refer to any text in print that is associated with an image, table, or chart. The text is not added by the transcriber, like a description or alt text, but instead is transcribed from the print.

Element(s):

figcaption

Reserved class values:

• None

In contrast to print, braille uses characters placed before or sometimes after text to indicate various types of text emphasis. The following elements will not add the braille characters themselves but will instead just track where emphasis is placed so that reading systems can potentially offer features that utilize this information.

Element(s):

em, strong

Note that b, i, mark, and u are not recommended and that em with a class should be used for emphasis other than italics and bold.

Reserved class values:

• script, underline, custom-1, custom-2, custom-3, custom-4, custom-5
• script— used to denote text that is meant to mimic handwriting.
• underline— used to denote text that is underlined.
• custom-#— used in UEB to denote text that is emphasized in a way not covered by a planned type of emphasis. For example, you could use it for green highlighting since UEB has no means to denote that kind of emphasis. Other kinds of emphasis that could be represented are text with a different color or a significant font change. It could similarly be applied to other braille codes that have emphasis types not covered by the types available.

figure specifies self-contained content, like illustrations, diagrams, photos, code listings, etc.

Element(s):

figure

Reserved class values:

• None

Element(s):

a, div, p, section

Supported role values:

• doc-noteref— used to identify the actual symbol of the footnote or endnote. This symbol will typically appear as a superscripted number or symbol in the main body of text.
• doc-footnote— used to identify the entirety of a single footnote, so symbol and text.
• doc-endnotes— used to identify the entirety of a single endnote, so symbol and text.

Element(s):

h1 - h6, title, header

Reserved class values:

• running-heading

Element(s):

img, a

Note that img is used for jpg, png, and svg, while a is used for pdf.

Reserved class values:

• TBD

Element Name:

span, div

Note that span is used to denote the specific line number, with an ID, class, and aria-label, while div is used to denote the section that contains line numbers.

Reserved class values:

• linenum, prose, poetry
• linenum— applied to the div and span to identify each as involving line numbers.
• prose— applied to the div to identify the section as involving prose text with line numbers (some braille regions have different rules for prose line numbers vs poetry line numbers).
• poetry— applied to the div to identify the section as involving poetic text with line numbers.

Element Name:

a

Note that links can be either external or internal. An internal link could point to a location within the same xHTML file or to a different file within the same package. An external link points to a location outside of the package, such as a webpage.

Supported role values:

• doc-backlink— A link that allows the user to return to a related location in the content.
• doc-biblioref— A link referencing a bibliographic entry.
• doc-glossref— A link to a glossary definition.

Element(s):

ol, ul, dl, li

Note that dl is preferred for glossary and index.

Reserved class values:

The reserved class values in this section are only applied to ol, ul, and dl.

• nomark, exercise, glossary, index, toc, poetry
• nomark— used to prevent the automatic inclusion of list prefixes, like bullets or numbers.
• exercise— used to denote an exercise question, typically one in a list format like a multiple-choice question.
• glossary— used to denote a glossary entry.
• index— used to denote an indices entry.
• toc— used to denote a table of contents entry.
• poetry— used to denote a line in a work of poetry that is meant to be formatted in stanzas or a way that is similar to a list.

Element(s):

div, span

Editor's note: Use [span] for all page numbers?

It's possible to treat a span as a div (and vice versa), so it may be simpler to treat all page numbers as either span or div regardless of whether they interrupt another element.-WF

Supported role values:

• doc-pagebreak— A separator denoting the position before which a break occurs between two contiguous pages in a statically paginated version of the content.

Element(s):

p

Reserved class values:

• left-aligned, directions, hanging
• left-aligned— used to denote a paragraph that should be left justified.
• directions— used to denote directions that will typically accompany tests, quizzes, or multiple choice questions.
• hanging— used to denote a paragraph in which the first line is set to the left margin, but all subsequent lines are indented.

Element(s):

pre

Note that pre should be avoided unless otherwise necessary. When pre is used, the formatting will be hardcoded and not reflowable for different page sizes. In future revisions, additional terms will be defined to reduce instances where pre is needed.

Reserved class values:

• None

Element(s):

table, tr, th, td, thead, tbody, tfoot

Attributes

Either the attributes scope or headers with id must be used to properly identify the relationship between the cells of the table. headers with id is preferred for complex tables.

abbr should be used with any long row or column headings.

Reserved class values:

The reserved class values in this section are only applied to table.

• listed, linear, stairstep
• listed— presents the same information as the original table but in a listed format that repeats column headings for each entry.
• linear— presents the same information as the original table but in a listed format that rearranges the row entries according to their column headings. Column headings are not repeated but are presented in a transcriber's note that precedes the table and informs the reader of the layout of each row's entries.
• stairstep— presents the same information as the original table but in a specialized format that puts each row in its own section with each column entry in a list format where each column of that row begins two-cells to the right of the previous column. So the first column is in 1-1, the second in 3-3, and so on. The column headings appear in a transcriber's note and are used to inform the reader of the layout of the table.

Element(s):

wbr, ­

Reserved class values:

• None.

Element(s):

span, div

Reserved class values:

• transcriber-note— used to identify a span or div as a transcriber's note, which is text that is added by a transcriber and not part of the original text.