List of formatting requirements

[bertfrees]

This is a list of possible formatting requirements for the e-braille file format. It includes formatting that should be controllable by the author (with CSS), formatting that should be controllable by the reading system (RS), and formatting that should be controllable by the end user (with CSS or some other way). These categories may overlap of course. The list may also include some things that will be out of scope in the end. The purpose of the list is to provide a good representation of the kind of formatting that exists in various braille standards around the world.

In addition the list gives an overview of what can currently be achieved with standard CSS and what could possibly be done with extensions. CSS might not be a good fit for all the formatting requirements. For such cases the reading system will still be able to apply the correct formatting, provided the content is marked up correctly and the reading system knows the braille rules that apply for the locale in question.

Note that this is a work in progress! I will be updating the list along the way based on your comments.

1. Media

	Related issues	Author	RS	End user	CSS
apply style conditionally based on the target medium tactile tablet embosser refreshable braille display regular screen	#31, #32, #80				☑ CSS media queries

2. Units

	Related issues	Author	RS	End user	CSS
express length in terms of rows/columns Because of the fixed-grid layout that is typical for braille, the most obvious length unit is the dimension of one "cell": cell height for vertical measuring, cell width for horizontal measuring.	#81				☑ em, rem and ch are units that are relative to the font size. They are the perfect fit for measuring heights (`em` and `rem`) and widths (`ch`) in our use case, as long as there can only be one font and font size for the whole document, the font is monospaced, and line-height: 1em; letter-spacing: 0 yields the expected spacing between dots. Braille CSS uses unitless length values.
optionally also support other units					in, px, ...

3. Box model

	Related issues	Author	RS	End user	CSS
blank lines above/below a block of text Also includes suppression of blank lines by end user.	#34, #82				☑ margin-top, margin-bottom, padding-top, padding-bottom
"collapsing" of margins Adjoining margins are combined into a single margin.	#82				☑ margin-top, margin-bottom
left/right margins To set off a block of text from other text. To not let a block of text fill up the full width of the page, e.g. in case of a centered heading.	#83				☑ margin-left, margin-right, padding-left, padding-right
vertical alignment of block of text at/around a vertical position on the page Common thing to do on a title page for instance.					CSS allows for positioning to position an element anywhere you want on the screen (viewport) or relative to a containing element. It is unclear however whether the standard also allows for an element to be positioned relatively to the page box. Also it is questionable whether such positioning is even useful because it takes the elements out of the normal flow. Finally, it can only align the top or bottom boundary of an element to some vertical position, but it can not center the element around a position.
positioning of marker (bullet/number) relative to list item					☑ list-style-position
spatial layout of blocks of text Similar to spatial layout of a table (see below), but more flexible and without the semantics of a table.	#30
column layout	#49

3.1 Borders

	Related issues	Author	RS	End user	CSS
borders to box/outline content to create horizontal lines ('end marker', 'thematic break')	#50				☑ border
underlining of headings	#96				☑ This could be accomplished with a box with a bottom border (border-bottom) and a width that is automatically adapted to the contents (width: fit-content).
specify style of border as braille character					The border-style or border property could be extended to support a braille pattern as value, like is done in braille CSS. ☑ An alternative approach is to use a specific border-image to control the border patterns exactly, as illustrated here. A tool could be provided to generate the images, e.g. border-image-source: url('https://daisy.github.io/ebraille/border-image?pattern=⢐⠐⢐⢐⢐⠐⠐⠐&width=240&height=480').
top/bottom box lines in UK These appear to have a special pattern. (See @jrbowden's example.)

3.2. Tables

	Related issues	Author	RS	End user	CSS
spatial layout of table	#8				☑ display: table
layout a table as a list	#8
abbreviate table headings	#23

4. Text

	Related issues	Author	RS	End user	CSS
text indentation (of first line vs. next lines)	#83				☑ text-indent
hanging text indentation	#83				☑ This can either be achieved with a negative text-indent (combined with a margin-left or padding-left that is at least this value, or with the 'hanging' of the text-indent property.
specify line height E.g. double line spaced braille.					☑ line-height
specify inter-word spacing					☑ word-spacing
specify letter spacing					☑ letter-spacing
alignment of a block of text right aligned centered					☑ text-align
alignment of a text segment at/around a horizontal position This is useful for tabulation. The segment could e.g. be a page number in a table of contents. The space could optionally be filled by leader dots. The leader may start on one line and continue on the next if the alignment requires it.	#84				Braille CSS has the leader() function for this purpose.
indentation of right-aligned text segment In the case a block of text ends with a right aligned segment, e.g. a page number in a table of contents, it may be a requirement that the last line with the segment extends further to the right than the other lines.
it should be possible to collapse insignifcant white space characters and preserve significant white space characters					☑ CSS white space processing rules
line breaking of text should take into account line breaking properties of unicode characters	#51				☑ Matches CSS line breaking rules
specify hyphen character					☑ hyphenate-character
preformatted text					☑ white-space
control over formatting indicators	#17

5. Automatic numbering

	Related issues	Author	RS	End user	CSS
choose the bullet character for a list					☑ list-style-type
numbered lists					☑ counter-increment, counter-reset, counter-set, counter(), @counter-style, ::marker, list-style-type
braille page numbering	#92				☑ CSS allows counters to be defined and controlled (counter-increment) within a @page rule. See page-based counters.
prefix to indicate continuation of print page In BANA, the continuation of print page "1" is marked "a1", then "b1", etc.	#102				Should be accomplishable with counter-increment, counter-set, @page and @counter-style and counter(), complemented with the non-standard string-set and string(): ```css @page { counter-increment: continuation; @top-left { content: counter(continuation, abc) string(print-page); } } @counter-style abc { system: numeric; symbols: '' '⠁' '⠃' '⠉' '⠙' '⠑'; } pagenum { string-set: print-page content(); counter-set: continuation 0; } ```

6. Page box model, page layout

	Related issues	Author	RS	End user	CSS
placement of content in specific parts of page margin page numbers headers/footers					☑ CSS defines a number of page margin boxes. These areas can be filled using the content property and counter() and string() functions.
placement of footnotes in the lower area of the page					☑ float: footnote, ::footnote-call, ::footnote-marker, @footnote
differentiate between left and right hand pages e.g. place page numbers in the outer page margin (left on left hand page and right on right hand page)					☑ @page:left, @page:right
differentiate between left and right hand pages to create interlining Interlining means making lines of braille on front and back not overlap.					☑ CSS allows offseting the page area with some value by controlling the size of the top page margin (margin-top property of @page rule).
ability to change the page layout within the document e.g. to leave out page numbers from title page					☑ The page property can be used to specify a particular type of page on which an element must be displayed. The page can be styled by using a @page selector.

7. Page breaking

	Related issues	Author	RS	End user	CSS
force page breaks					☑ page-break-before, page-break-after
avoid page break within and element					☑ page-break-inside
avoid orphan/widow lines					☑ orphans, widows

8. Indication of original pagination

	Related issues	Author	RS	End user	CSS
print page number within text Possibly the number may be preceded by leader dots to form a page break indicator line. Possibly the number should be skipped when it would occur at the top of the page (e.g. because it would also appear in the top page margin, resulting in unneeded repetition)	#101				For the purpose of skipping the number at the top of the page, braille CSS has the :top-of-page pseudo-class.
print page at the beginning of current braille page rendered in top/bottom page margin	#102				string-set, string() (both non-standard), and page margin boxes
range of print pages within current braille page or spread rendered in top/bottom page margin					The (non-standard) string() function could be extended to support addition keywords to control which value of the named string should be used. This is how braille CSS approaches this requirement.
print page break marker within left page margin Common in Norway.					Absolute positioning could be used, but might be too primitive.

[wfree-aph]

@bertfrees Wanted to ask in the meeting but wasn't sure: are the blank table cells on the CSS side, like on "indentation of right-aligned text segment", places where css can't account for that example or is it blank for another reason?

[bertfrees]

Those cells are blank because I didn't immediately have a possible solution in mind for the requirement. These need more attention. The list is really still a work in progress. I didn't want it to take too long before I could share it.

By the way, you probably guessed, but the requirements that are covered by standard CSS start with a checkbox (Unicode U+2611) character.

[skntkacm]

Is unbreakable space possible to solve with some tag? We should include for sure a possibility of such an space within the documment - something like tag " ".

[bertfrees]

@skntkacm What do you mean with tag?

[skntkacm]

Well tag... I am sorry if not being precise technically. I just ment we should include it, that this possibility is for sure included in the code of e-braille. In BRF, if I am not mistaken, this unbreakable space is not possible. I though noticed an issue #51 which addresses it.

[jrbowden]

I believe no tag is needed for this: the no break space is a character and so we should allow the HTML character entity name   Would this work?

[bertfrees]

The affect of no-break spaces on line breaking is covered by the item "line breaking of text should take into account line breaking properties of Unicode characters" under "4. Text".

I'll add another item about processing (notably collapsing) of white space.

[bertfrees]

I have added the following item to the table:

it should be possible to collapse insignifcant white space characters and preserve significant white space characters

[mattgarrish]

em and rem are units that are relative to the font size (of the current and the root element respectively), both in vertical and horizontal directions.

Wouldn't ch be a good fit for unit length?

[bertfrees]

Thanks for pointing that out. I don't know why I said that that em could be used for both vertical and horizontal directions. It turns out we can only use em for measuring heights, and we should use ch to measure widths.