-
Notifications
You must be signed in to change notification settings - Fork 5
/
index.html
3290 lines (2764 loc) · 137 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US" xml:lang="en-US">
<head>
<meta charset="utf-8" />
<title>eBraille 1.0</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
<script src="common/js/status.js" class="remove"></script>
<script src="common/js/copyright.js" class="remove"></script>
<script src="common/js/examples.js" class="remove"></script>
<script src="common/js/css-inline.js" class="remove"></script>
<script class="remove">
//<![CDATA[
var respecConfig = {
shortName: null,
daisyWG: 'eBraille Working Group',
specStatus: 'base',
daisyStatus: 'ED',
latestVersion: 'https://daisy.org/s/ebraille/',
thisVersion: 'https://daisy.org/s/ebraille/1.0/WD-ebraille-20241017/',
previousVersion: 'https://daisy.org/s/ebraille/1.0/WD-ebraille-20241017/',
edDraftURI: 'https://daisy.github.io/ebraille/',
editors: [
{
name: 'Willow Free',
company: 'American Printing House for the Blind',
url: 'https://www.aph.org/'
},
{
name: 'Bert Frees',
company: 'DAISY Consortium',
url: 'https://daisy.org/'
},
{
name: 'Matt Garrish',
company: 'DAISY Consortium',
url: 'https://daisy.org/'
},
{
name: 'George Kerscher',
company: 'DAISY Consortium',
url: 'https://daisy.org/'
},
{
name: 'Charles LaPierre',
company: 'Benetech',
url: 'https://benetech.org/'
},
{
name: 'Avneesh Singh',
company: 'DAISY Consortium',
url: 'https://daisy.org/'
}
],
logos: [
{
src: 'https://daisy.github.io/ebraille/common/images/daisy_high.jpg',
width: 112,
height: 100,
alt: 'DAISY Consortium logo',
url: 'https://daisy.org'
}
],
github: 'daisy/ebraille',
preProcess:[inlineCustomCSS],
postProcess: [addDAISYStatus,addCopyrightYear,fixExampleHeaders],
xref: ["epub-33"],
localBiblio: {
"code-registry" : {
"title": "eBraille Braille Code Registry",
"href": "https://daisy.org/s/ebraille/registries/codes",
"publisher": "DAISY"
},
"dpub-aria" : {
"title": "Digital Publishing WAI-ARIA Module",
"href": "https://www.w3.org/TR/dpub-aria/",
"publisher": "W3C"
},
"css-page": {
"aliasOf": "css-page-3"
},
"css-fonts": {
"aliasOf": "css-fonts-3"
},
"css-color": {
"aliasOf": "css-color-3"
},
"css-text-decor": {
"aliasOf": "css-text-decor-3"
},
"css-values": {
"aliasOf": "css-values-3"
},
"mediaqueries": {
"aliasOf": "mediaqueries-4"
},
"css-conditional": {
"aliasOf": "css-conditional-3"
},
"css-cascade": {
"aliasOf": "css-cascade-5"
}
}
};
// ]]>
</script>
</head>
<body>
<p class="copyright">Copyright © DAISY Consortium <span id="copyYear">2023</span></p>
<section id="abstract">
<p>This specification defines eBraille, a digital reading format for braille publications.</p>
<p>eBraille uses an EPUB 3-compatible file set based on the Open Web Platform — using technologies
such as XHTML and CSS — to encode braille in semantically enhanced markup and allow it to adapt to
the different capabilities of braille reading devices. The file set is designed for both packaged
distribution to end users and deployment to the web for online and downloadable reading.</p>
</section>
<section id="sotd">
<div data-include="common/status.html" data-include-replace="true"></div>
<p>The eBraille Working Group is seeking input on all aspects of this document. It is particularly
interested in implementation experience both creating eBraille publication and creating reading systems
in which to read them.</p>
</section>
<section id="intro">
<h2>Introduction</h2>
<section id="overview">
<h3>Overview</h3>
<p>Unlike braille formats that focus on interchanging embosser-ready braille, eBraille focuses on
adapting braille for reading in refreshable braille displays with different line lengths.</p>
<p>In order to maintain close alignment with mainstream publishing formats, and simplify transcription
of these works, the eBraille format is built on an EPUB 3-compatible file set — it
incorporates XHTML documents, CSS, images, audio, and video. This means that an [=eBraille
publication=] shares its technology with the web, making it compatible for reading in standard web
browsers.</p>
<p>An [=eBraille publication=] differs from reading a typical web site in that the braille is not
transformed on the fly but comes formatted according to the rules of the regional braille code where
the publication was produced. Users are not locked into this default display, however. With the
display flexibility of CSS, and standardized markup practices, they can apply styles for another
region or even modify the display to their own preferences (e.g., by changing the maximum line
length).</p>
<p>eBraille publications are also designed to be flexible for deployment. An eBraille publication can be
placed on the web, unzipped on a user's local file system, or distributed in EPUB 3-compatible
packaging. And as web-compatible file sets, they are adaptable to future changes to publishing
formats.</p>
</section>
<section id="relationship-epub3" class="informative">
<h3>Relationship to EPUB 3</h3>
<p>The [=eBraille file set=] is designed to be compatible with EPUB 3 [[epub-33]] and adapt to changes
to that standard. Distribution and consumption on mainstream [=EPUB reading systems=], however, is
not a primary goal of this format. This specification introduces some additional requirements and
features beyond those defined in EPUB 3, and it is not expected that mainstream reading systems will
adapt to these modifications. Consequently, an eBraille publication may not render exactly as
intended outside of eBraille reading systems.</p>
<p>The primary difference between the eBraille format and EPUB 3 is [=eBraille publications=] do not
have to be packaged and distributed in an [=EPUB container=] [[epub-33]] — they can be
deployed on the web as an unpackaged set of files. An eBraille publication is packagable in an EPUB
container when that is the preferred distribution method, but eBraille uses the file extension
<code>.ebrl</code> not <code>.epub</code>.</p>
<p>Compatibility with EPUB 3 also means that eBraille relies on the same <a
data-cite="epub-33#sec-intro-relations">underlying technologies</a> [[epub-33]]. Many of these
technologies, like [[html]], are referred to as "evergreen" or "living" standards as they are
updated often and do not have version numbers. Others, like [[svg]], are referred to without a
specific version number so that the latest recommendation is always the recommended one to use.</p>
<p>The practical effect of this approach is predominantly beneficial for [=eBraille creators=]. New
features become available for use as soon as they are standardized; it is not required to wait for a
new revision of the eBraille standard to allow them. The approach does come with some drawbacks,
however. eBraille creators also have to keep themselves apprised of changes to the underlying
technologies, and use their best judgement in some cases as to whether a new feature is supported
well enough in [=eBraille reading systems=] to begin deploying. In some rare cases, it may also mean
that content that was previously valid may no longer be, but breaking changes like this usually only
happen when features are unsupported or are found to have serious security or privacy flaws.</p>
</section>
<section id="future-dir" class="informative">
<h3>Future directions</h3>
<p>The first version of the eBraille format is focused on creating a reading experience that is
minimally feature complete for the majority of braille publications. It is not expected that this
version will handle every unique formatting requirement of every publication type, but future drafts
and versions of this specification will focus on making the format more feature complete.</p>
<p>In particular, the working group expects to review the current support decisions for the following
features:</p>
<ul>
<li>scripting — the use of JavaScript in [=eBraille content documents=] is currently
prohibited. The working group is seeking further input on the need for dynamic braille before
allowing scripting as the ability to script documents increases the security and privacy risks
of the format.</li>
<li>CSS extensions — the first version of eBraille uses standard CSS properties to format
braille content. There may be a need to extend CSS in the future to handle more complex
formatting cases, which will also require defining reading system implementations.</li>
<li>embossing — this version of eBraille is focused on consuming [=eBraille publications=] on
electronic reading systems, more specifically refreshable braille displays. It is expected that
a revision is needed to better account for the use case of embossing publications on paper.</li>
</ul>
</section>
<section id="terminology">
<h3>Terminology</h3>
<p>This specification defines the following terms specific to eBraille.</p>
<div class="note">
<p>Only the first instance of a term in a section links to its definition.</p>
</div>
<dl>
<dt>
<dfn data-lt="content document|content documents">eBraille content document</dfn>
</dt>
<dd>
<p data-cite="html">eBraille content documents contain all or part of the content of a braille
publication. They use a restrictive set of [[html]] tags and define processing requirements
through the use of [^global/class^] and [^/role^] attributes.</p>
<p>For more information, refer to <a href="#ebrl-content-docs"></a>.</p>
</dd>
<dt>
<dfn>eBraille creator</dfn>
</dt>
<dd>
<p>An individual, organization, or process that produces an [=eBraille publication=].</p>
</dd>
<dt>
<dfn>eBraille file set</dfn>
</dt>
<dd>
<p>The set of files that comprise an [=eBraille publication=]. The eBraille file set is
contained within the [=publication root=].</p>
<p>For more information, refer to <a href="#fileset-structure"></a>.</p>
</dd>
<dt>
<dfn>eBraille publication</dfn>
</dt>
<dd>
<p>A logical document entity consisting of a set of interrelated resources.</p>
<p>An eBraille publication typically represents a single intellectual or artistic work, but this
specification does not restrict the nature of the content.</p>
</dd>
<dt><dfn data-lt="reading system|reading systems">eBraille reading system</dfn> (or reading
system)</dt>
<dd>
<p>A system that processes [=eBraille publications=] for presentation to a user in a manner
conformant with this specification.</p>
</dd>
<dt>
<dfn>primary entry page</dfn>
</dt>
<dd>
<p>The default [=eBraille content document=] that users reading an [=eBraille publication=] in a
browser are expected to encounter. It is located in the [=publication root=] and specially
named to open by default when users browse to a folder containing an eBraille
publication.</p>
<p>The primary entry page is an implementation of the [=EPUB navigation document=] [[epub-33]].
It contains the table of contents for the publication.</p>
<p>For more information, refer to <a href="#ebrl-nav"></a></p>
</dd>
<dt>
<dfn>publication root</dfn>
</dt>
<dd>The root directory is the base of the [=eBraille file set=]. All the resources of an eBraille
publication are located at or below this directory.</dd>
</dl>
</section>
<section id="conformance"></section>
<section id="auth-shorthands" class="informative">
<h3>Authoring shorthands</h3>
<p>In <a href="#metadata">package document metadata</a>, <a
data-cite="epub-33#sec-metadata-reserved-prefixes">reserved prefixes</a> [[epub-33]] are used
without declaration.</p>
<p>The following namespace prefixes [[xml-names]] are also sometimes used without an explicit
declaration, but the listed declaration is required for their use to be valid:</p>
<table class="zebra">
<thead>
<tr>
<th>Prefix</th>
<th>Required declaration</th>
<th>Used with</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<code>dc:</code>
</td>
<td>
<code>xmlns:dc="http://purl.org/dc/elements/1.1/"</code>
</td>
<td>Dublin Core elements [[dcterms]]</td>
</tr>
<tr>
<td>
<code>epub:</code>
</td>
<td>
<code>xmlns:epub="http://www.idpf.org/2007/ops"</code>
</td>
<td>EPUB 3-defined attributes [[epub-33]]</td>
</tr>
</tbody>
</table>
</section>
</section>
<section id="ebrl-pub">
<h2>eBraille publication conformance</h2>
<p>A conforming [=eBraille publication=]:</p>
<ul>
<li>
<p>MUST define at least one rendering of its content as follows:</p>
<ul>
<li>It MUST contain a package document that conforms to <a href="#ebrl-package-doc"></a> and
meet all publication resource requirements for the package document.</li>
<li>It MUST contain a primary entry page that conforms to <a href="#ebrl-nav"></a>.</li>
</ul>
</li>
<li>SHOULD conform to the accessibility requirements defined in <a href="#ebrl-a11y"></a>.</li>
</ul>
<p>In addition, all publication resources MUST adhere to the requirements in <a href="#ebrl-resources"
></a>.</p>
<p>If an eBraille publication is packaged for distribution, it MUST adhere to the packaging requirements in
<a href="#ebrl-packaging"></a>.</p>
<p>The rest of this specification covers specific conformance details.</p>
</section>
<section id="ebrl-resources">
<h2>Publication resources</h2>
<section id="res-intro" class="informative">
<h3>Introduction</h3>
<p>An [=eBraille publication=] is typically composed of many resources — XHTML documents, CSS
files, tactile graphics, audio, video, etc.</p>
<p>As an eBraille publication is intended to be easily packaged as a conforming [=EPUB publication=],
the requirements for publication resources are inherited from EPUB, specifically as defined in <a
data-cite="epub-33#sec-publication-resources"></a> [[epub-33]].</p>
<p>This section represents a subsetting of the EPUB requirements, as certain features, such as manifest
fallbacks, are disallowed in eBraille publications.</p>
</section>
<section id="cmt">
<h3>Core media types</h3>
<p>To ensure that [=eBraille reading systems=] are capable of rendering the content of [=eBraille
publications=], only certain widely supported resource types are allowed to be included without
fallbacks. These are called core media types and are designated by their MIME media type [[rfc2046]]
(e.g., XHTML documents have the MIME media type <code>application/xhtml+xml</code>).</p>
<p>Being designated a core media type does not mean that all reading systems are required to support the
type of resource, however. A reading system without audio capabilities will not be able to render
audio core media types, for example.</p>
<p>The list of core media types allowed in eBraille publications is the same as those designated for
EPUB 3. Some of the key core media types for eBraille include:</p>
<ul>
<li><code>application/xhtml+xml</code> — HTML documents that use the XML syntax [[html]].</li>
<li><code>text/css</code> — CSS Style Sheets [[css2]].</li>
<li><code>image/jpeg</code> — JPEG Images [[jpeg]]</li>
<li><code>image/png</code> — PNG Images [[png]]</li>
<li><code>image/svg+xml</code> — SVG images [[svg]]</li>
</ul>
<p>The complete list is available in the <a data-cite="epub-33#sec-core-media-types">core media types
section</a> of [[epub-33]].</p>
<p>All other media types are considered <a href="#foreign-res">foreign resources</a>.</p>
</section>
<section id="foreign-res">
<h3>Foreign resources</h3>
<p>Foreign resources, unlike <a href="#cmt">core media types</a>, have no guarantee of support in
reading systems.</p>
<p>To avoid users not being able to access the content of the [=eBraille publication=], foreign
resources can only be used if a fallback to a core media type is provided. Fallbacks are provided
using <a data-cite="epub-33#sec-intrinsic-fallbacks">intrinsic fallback methods</a> [[epub-33]].</p>
<div class="note">
<p><a href="#fallbacks">Manifest fallbacks</a> are not supported in eBraille. This means they cannot
be used to include foreign resources in the <a href="#spine">spine</a> or as a means of
providing fallbacks for foreign image formats (in the latter case, fallbacks can be provided
instead using the [[html]] [^img^] and [^picture^] elements' intrinsic fallback
capabilities).</p>
</div>
<p>It is generally best to avoid foreign resources unless absolutely necessary. PDF tactile graphics are
an example of a foreign resource that may not be avoidable for some [=eBraille creators=], but using
the [[html]] [^object^] element's intrinsic fallback capabilities can avoid having to duplicate the
image in a core media type format.</p>
<aside class="example" title="PDF tactile image with fallback">
<pre><object
data="ebraille/images/clouds.pdf"
type="application/pdf"
height="250"
width="100"
aria-label="alternative text">
<p><!-- description --></p>
</object></pre>
</aside>
<aside class="ednote">
<p>The accessibility of using an <code>object</code> element is still to be determined. Guidance on
how to embed PDFs may change in a future update.</p>
</aside>
</section>
<section id="fallbacks">
<h3>Resource fallbacks</h3>
<p>eBraille does not support the use of <a data-cite="epub-33#sec-manifest-fallbacks">manifest
fallbacks</a> [[epub-33]].</p>
<p>The intrinsic fallback methods provided by [[html]] elements are supported.</p>
</section>
<section id="res-location">
<h3>Resource location</h3>
<p>[=eBraille publications=] do not support [=remote resources=] [[epub-33]]. All publication resources
MUST be located in or below the [=root directory=], as defined in <a href="#fileset-structure"
></a>.</p>
<p>eBraille does not support the <code>file:</code> URL scheme [[rfc8089]] for referencing resources in
an eBraille publication. Accessing files on the user's local file system presents too great a
security risk.</p>
<p>The <code>data:</code> URL scheme MAY be used to embed resources within [=eBraille content
documents=] per the restrictions outlined in <a data-cite="epub-33#sec-data-urls">Data URLs</a>
[[epub-33]].</p>
</section>
<section id="res-exemptions" class="informative">
<h3>Exempt resources</h3>
<p>It is possible to include additional resources in an [=eBraille publication=] that are not part of
the rendering of the content. EPUB 3 defines resources that are not used in the [=spine=] or
embedded in [=xhtml content documents=] as exempt from the normal [=core media type resource=]
restrictions [[epub-33]].</p>
<p>This means, for example, that [=eBraille creators=] can embed pre-formatted braille in their
publication in a format such as PDF or BRF. The resource would still be listed in the [=manifest=],
but it would not be flagged as needing a fallback.</p>
<p>It would not be possible to link to these resources from the eBraille publication, but the
publication could note the presence of the resources and include instructions on how to access them
(e.g., to open the publication with a ZIP tool and navigate to a specific directory).</p>
</section>
<section id="res-extensions" class="informative">
<h3>File extensions</h3>
<p>Reading systems typically do not rely on file extensions for rendering, so, with a couple of notable
exceptions for the <a href="#ebrl-package-doc">package document</a> and <a href="#ebrl-nav">primary
entry page</a>, eBraille does not require specific extensions for the resources in an [=eBraille
publication=]. The media type declared in the manifest is used as a hint to the nature of each
resource, but even that declaration is not reliable. Instead, reading systems typically leave
inspection of resources and their rendering to their underlying browser core.</p>
<p>The use of standard file extensions for resources should still be considered a best practice,
however, as it avoids authoring confusion over the nature of resources.</p>
<p>Some formats have more than one common extension. For example, XHTML documents can use either the
extension <code>.html</code> or <code>.xhtml</code> and JPEG images can use either <code>.jpg</code>
or <code>.jpeg</code>. In these cases, either extension is acceptable.</p>
<div class="note">
<p>This specification uses the <code>.html</code> extension in examples for [=eBraille content
documents=] as it is more widely used and recognized than <code>.xhtml</code>, particularly for
opening the primary entry page.</p>
<p>The <code>.xhtml</code> extension may be useful if eBraille content documents are opened in a
browser on a local file system (e.g., for testing), as this triggers some browsers to render the
content using the correct XML parser. The extension has no effect on documents served over the
web, however.</p>
</div>
</section>
<section id="xml-conformance">
<h3>XML conformance</h3>
<p>The requirements for XML-based media types [[rfc2046]] defined in <a
data-cite="epub-33#sec-xml-constraints">XML conformance</a> [[epub-33]] also apply to [=eBraille
publications=].</p>
<p>The only difference is that eBraille publications only support UTF-8 [[unicode]]. UTF-16 MUST NOT be
used to encode XML resources.</p>
</section>
</section>
<section id="ebrl-fileset">
<h2>eBraille file set</h2>
<section id="fileset-intro" class="informative">
<h3>Introduction</h3>
<p>The [=eBraille file set=] is like a physical manifestation of the <a
data-cite="epub-33#sec-container-abstract">OCF abstract container</a> [[epub-33]]. EPUB 3 only
defines its file set in the abstract because those files are expected to be zipped in the [=EPUB
container=] [[epub-33]]; the standard is not concerned with the physical files before they are
zipped or after they are unzipped. As a ZIP file does not have a true file system within it, the
rules for file naming and placement can only be defined virtually.</p>
<p>eBraille moves the rules for the OCF abstract container to the physical file set that exists before
and after packaging in the EPUB container. This allows an [=eBraille publication=] to be independent
of packaging, making it a format that can flexibly move between web deployment and end-user
distribution.</p>
<p>eBraille defines additional rules on the file structure in order to make it easier to read an
eBraille publication on the web or from a local file system. In particular, it requires the [=EPUB
navigation document=] [[epub-33]] be in the root of the file set and named <code>index.html</code>.
These requirements do not conflict with being able to package an eBraille publication as a valid
[=EPUB publication=] [[epub-33]], however.</p>
</section>
<section id="fileset-structure">
<h3>File and directory structure</h3>
<p>The [=eBraille file set=] MUST have a single common root directory — the [=publication root=]
— for all the contents of the [=eBraille publication=].</p>
<p>Unlike EPUB 3, the eBraille file set MUST NOT reference resources outside the publication root (i.e.,
[=remote resources=] [[epub-33]] are not supported).</p>
<p>The eBraille file set MUST contain the following files in the publication root:</p>
<ul>
<li>The <a data-cite="epub-33#sec-nav">EPUB navigation document</a> [[epub-33]]. This file MUST be
named <code>index.html</code></li>
<li>The <a data-cite="epub-33#sec-package-doc">EPUB package document</a> [[epub-33]]. This file MUST
be named <code>package.opf</code></li>
</ul>
<p>There are no restrictions on where the rest of the eBraille publication content goes beyond the
requirement in EPUB 3 that <a data-cite="epub-33#sec-container-file-and-dir-structure">publication
resources are not allowed in a <code>META-INF</code> directory</a> [[epub-33]].</p>
<div class="note">
<p>For simplicity of unzipping and accessing a publication on a user's local file system, [=eBraille
creators=] are encouraged to place the rest of the publication in a subfolder (e.g., named
"<code>ebraille</code>"). This will make the navigation document the first HTML file users
encounter.</p>
</div>
</section>
<section id="fileset-naming">
<h3>File paths and file names</h3>
<p>To avoid potential naming issues when opening [=eBraille publications=] on common operating systems,
eBraille file paths and file names MUST adhere to the EPUB 3 file naming restrictions specified in
<a data-cite="epub-33#sec-container-filenames">File paths and file names</a> [[epub-33]].</p>
</section>
<section id="fileset-urls">
<h3>URLs in the file set</h3>
<p>Although the [=publication root=] establishes a common directory for all files in an [=eBraille
publication=], depending on how the eBraille publication is deployed it could allow references to
resolve outside of the publication root. For example, if an eBraille publication is deployed on the
web, unless it assigned its own domain, a [=path-absolute-URL string=] [[url]] (i.e., a path that
begins with a slash) could allow the publication to reach other resources on the server.</p>
<p>For this reason, the eBraille file set MUST NOT include file references that use path-absolute-URL
strings.</p>
</section>
<section id="multiple-renditions">
<h3>Multiple renditions</h3>
<p>An [=eBraille publication=] MAY contain multiple renditions of the content. The specifics of how this
is done are defined in <a href="https://www.w3.org/TR/epub-multi-rend-11/">EPUB 3 Multiple-Rendition
Publications 1.1</a> [[epub-multi-rend-11]].</p>
<p>When including multiple renditions, the <a data-cite="epub-multi-rend-11#container">default
rendition</a> [[epub-multi-rend-11]] — the one listed first in the <a
data-cite="epub-33#sec-container-metainf-container.xml"><code>container.xml</code> file</a>
[[epub-33]] — MUST be a braille rendition. The default rendition has a default <a
data-cite="epub-multi-rend-11#accessMode-attr"><code>rendition:accessMode</code> selection
attribute</a> [[epub-multi-rend-11]] equivalent to the value <code>tactile</code>. No other
value is allowed if the attribute is set explicitly.</p>
<p>Subsequent renditions are exempt from the following requirements:</p>
<ul>
<li>The <a href="#fileset-structure">file naming and location requirements</a> for the package
document and primary entry page, as this would cause conflicts.</li>
<li>The <a href="#xhtml-char-encoding">recommendation to use only 6- and 8-dot Unicode
characters</a> if the rendition is not in braille.</li>
<li>The <a href="#dc:language">publication language</a> requirement to use the <code>Brai</code>
script designator if the rendition is not in braille.</li>
</ul>
<div class="note">
<p>[[epub-multi-rend-11]] is only a W3C Working Group Note. The technology is not currently
considered stable and should be used with appropriate caution.</p>
<p>The eBraille working group may consider a replacement technology for multiple renditions in a
future version if there is significant need for them and implementation of the EPUB technology
proves too difficult.</p>
</div>
</section>
</section>
<section id="ebrl-package-doc">
<h2>Package Document</h2>
<section id="package-doc-intro" class="informative">
<h3>Introduction</h3>
<p>eBraille uses the EPUB 3 <a data-cite="epub-33#sec-package-doc">package document</a> [[epub-33]] to
express information about an [=eBraille publication=].</p>
<p>The package document is an XML document that contains three primary sections that encapsulate
information about the content and how to render it:</p>
<ul>
<li><a href="#metadata">Metadata</a> — the <code>metadata</code> element contains
bibliographic and rendering information about an eBraille publication.</li>
<li><a href="#manifest">Manifest</a> — the <code>manifest</code> element contains a list of
all the <a href="#ebrl-resources">publication resources</a>.</li>
<li><a href="#spine">Spine</a> — the <code>spine</code> element contains the default ordering
of [=eBraille content documents=].</li>
</ul>
<p>These sections are all contained within the <a href="#package-elem">root <code>package</code>
element</a>.</p>
<p>The primary difference of the eBraille package document is only in the metadata that is required and
recommended. The eBraille implementation of the package document is also more limited in the
features it allows — EPUB 3's <a data-cite="epub-33#sec-manifest-fallbacks">manifest
fallbacks</a> and <a data-cite="epub-33#sec-pkg-legacy">legacy elements</a> [[epub-33]] are not
allowed, for example.</p>
</section>
<section id="package-elem">
<h3>The <code>package</code> element</h3>
<p>At the root of the eBraille package document is the <code>package</code> element. This element MUST
conform to the <a data-cite="epub-33#sec-package-elem">requirements for the <code>package</code>
element</a> in [[epub-33]].</p>
<p>For example, EPUB 3 requires the <code>package</code> element's <a
data-cite="epub-33#attrdef-package-version"><code>version</code> attribute</a> [[epub-33]] have
the value "<code>3.0</code>". This identifies that the package document conforms to the EPUB 3
definition. (The identifier that the content conforms to this specification is contained in the
required <a href="#dc:format"><code>dc:format</code> element</a>.)</p>
<p>It is also required that the <code>unique-identifier</code> attribute [[epub-33]] be specified. This
attribute references the ID of the <a href="#dc:identifier"><code>dc:identifier</code> element</a>
that contains the unique identifier for the publication.</p>
<p>Although setting the default language of the package document text on the <code>package</code>
element is not required, it is best practice to set it here in an <a
data-cite="epub-33#attrdef-xml-lang"><code>xml:lang</code> attribute</a> [[epub-33]] so that
language information is available for every element that requires it.</p>
<aside class="example" title="Typical package element attributes">
<p>In this example, a <code>dc:identifier</code> element with the <code>id</code> attribute value
<code>uid</code> (not shown) is specified in the metadata.</p>
<pre><package xmlns="http://www.idpf.org/2007/opf"
version="3.0"
unique-identifier="uid"
xml:lang="en">
…
</package></pre>
</aside>
</section>
<section id="metadata">
<h3>Metadata</h3>
<section id="meta-about" class="informative">
<h4>About package document metadata</h4>
<section id="meta-elements">
<h4>Metadata elements</h4>
<p>Metadata about an [=eBraille publication=] is expressed in the package document's <a
data-cite="epub-33#sec-metadata-elem"><code>metadata</code> element</a> [[epub-33]].
This element is the first child of the root <a href="#package-elem"><code>package</code>
element</a>.</p>
<p>The following elements are allowed as children of the <code>metadata</code> element:</p>
<dl>
<dt id="dc-elem">Dublin Core elements</dt>
<dd>
<p>Dublin Core defines <a
href="https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#section-3"
>15 elements</a> in the <code>/elements/1.1/</code> namespace [[dcterms]]. Any
of these element can be used in the <code>metadata</code> element — elements
not listed in the <a href="#meta-req">required</a> or <a href="#meta-rec"
>recommended</a> metadata sections are considered <a href="#meta-additional"
>optional elements</a>.</p>
</dd>
<dt id="meta-elem">The <code>meta</code> element</dt>
<dd>
<p>The <a data-cite="epub-33#sec-meta-elem"><code>meta</code> element</a> [[epub-33]] is
used to express properties from metadata vocabularies, where its
<code>property</code> attribute defines the property name.</p>
<p>Metadata properties defined in this element typically require a <a
href="#meta-prefixes">prefix</a> (many prefixes are reserved and do not have to
be declared).</p>
</dd>
<dt id="link-elem">The <code>link</code> element</dt>
<dd>
<p>The <a data-cite="epub-33#sec-link-elem"><code>link</code> element</a> [[epub-33]] is
used to associate resources with an [=eBraille publication=], such as metadata
records.</p>
<p>Linked resources are typically not publication resources so are not listed in the <a
href="#manifest">manifest</a>.</p>
<p>Metadata properties defined in this element also typically require a <a
href="#meta-prefixes">prefix</a>.</p>
</dd>
</dl>
<div class="note">
<p>For more information about the attributes allowed on these elements, refer to their
definitions in [[epub-33]].</p>
</div>
</section>
<section id="meta-values">
<h4>Metadata values</h4>
<p>EPUB 3 requires that all Dublin Core [[dcterms]] and <a href="#meta-elem"><code>meta</code>
elements</a> have <a data-cite="epub-33#sec-metadata-values">child text content</a>
[[epub-33]] (i.e., they have to have at least one non-whitespace character after <a
data-cite="infra#strip-leading-and-trailing-ascii-whitespace">leading and trailing ASCII
whitespace</a> [[?infra]] is stripped). In the descriptions for these elements, this
specification refers to this content as the element's <dfn>value</dfn>.</p>
<p>Whitespace within these element values is not significant. Sequences of one or more
whitespace characters are <a data-cite="infra#strip-and-collapse-ascii-whitespace">collapsed
to a single space</a> [[infra]] during processing.</p>
</section>
<section id="meta-prefixes">
<h4>Using prefixes</h4>
<p>The <a href="#meta-elem"><code>meta</code> element</a> and <a href="#link-elem"
><code>link</code> element</a> are meant for use with properties defined in existing
metadata vocabularies, such as those in the Dublin Core <code>/terms/</code> namespace
[[dcterms]].</p>
<p>EPUB 3 defines a set of <a data-cite="epub-33#sec-reserved-prefixes">reserved prefixes</a>
[[epub-33]] for common metadata vocabularies. Properties from these vocabularies can be used
without having to declare their prefix.</p>
<div class="note">
<p>The prefixes <code>a11y:</code> and <code>dcterms:</code> are reserved prefixes in EPUB
3. They do not have to be declared to use the associated required and recommended
metadata properties in this specification.</p>
</div>
<p>If properties from other vocabularies are needed, a prefix needs to be declared before they
can be used. Prefixes are defined in the <code>prefix</code> attribute on the <a
href="#package-elem">root <code>package</code> element</a>. Both the prefix and a URL to
associate with the prefix have to be specified. These values are separated by
whitespace.</p>
<aside class="example" title="Declaring a new prefix">
<pre><package … prefix="ex: https://example.com/metadata/">
<metadata>
…
<meta property="ex:revisionDate">2024-01-01</meta>
…
</metadata>
…
</package></pre>
</aside>
<div class="note">
<p>For more information about using prefixes in the package document, refer to <a
data-cite="epub-33#sec-vocab-assoc">Vocabulary association mechanisms</a>
[[epub-33]].</p>
</div>
</section>
</section>
<section id="meta-req-general">
<h4>General requirements</h4>
<p>The eBraille package document metadata:</p>
<ul>
<li>MUST meet all the requirements for <a data-cite="epub-33#sec-pkg-metadata">EPUB 3
metadata</a> [[epub-33]].</li>
<li>MUST include all metadata defined in <a href="#meta-req"></a>.</li>
<li>SHOULD include all metadata defined in <a href="#meta-rec"></a>.</li>
</ul>
</section>
<section id="meta-req">
<h4>Required metadata</h4>
<section id="dc:creator">
<h5>dc:creator</h5>
<p>The REQUIRED <code>dc:creator</code> element [[dcterms]] identifies the name(s) of the
primary author, editor, etc. Follow regional conventions for name layout.</p>
<aside class="example" title="A single author with an English name">
<pre><dc:creator>
Mark Twain
</dc:creator></pre>
</aside>
<aside class="example" title="A single Japanese author with first name followed by last">
<pre><dc:creator>
Akiko AKAZOME
</dc:creator></pre>
</aside>
<p>The element MAY include the following attributes: <a data-cite="epub-33#attrdef-dir"
><code>dir</code></a>, <a data-cite="epub-33#attrdef-id"><code>id</code></a>, <a
data-cite="epub-33#attrdef-xml-lang"><code>xml:lang</code></a> [[epub-33]].</p>
<p>Repeat the element for each creator name.</p>
<p>To identify the role the creator played in the creation of the content, <a
data-cite="epub-33#subexpression">associate</a> a <a data-cite="epub-33#role"
><code>role</code> property</a> [[epub-33]] with the element.</p>
<aside class="example" title="Multiple authors with roles identified">
<pre><dc:creator id="aut01">
Charlotte Brontë
</dc:creator>
<meta property="role" refines="#aut01">aut</meta>
<dc:creator id="aut02">
Herman Melville
</dc:creator>
<meta property="role" refines="#aut02">aut</meta></pre>
</aside>
<p>To provide the creator's name for sorting purposes, associate a <a
data-cite="epub-33#file-as"><code>file-as</code> property</a> [[epub-33]] with the
element.</p>
<aside class="example" title="Author's name with sortable equivalent">
<pre><dc:creator id="aut01">
Charlotte Brontë
</dc:creator>
<meta property="file-as" refines="#aut01">Brontë, Charlotte</meta></pre>
</aside>
<div class="note">
<p>For more information, refer to the <a data-cite="epub-33#sec-opf-dccreator">definition of
the <code>dc:creator</code> element</a> in [[epub-33]].</p>
</div>
</section>
<section id="dc:date">
<h5>dc:date</h5>
<p>The REQUIRED <code>dc:date</code> element [[dcterms]] defines the publication date of the
[=eBraille publication=].</p>
<p>It is RECOMMENDED that the date string conform to [[iso8601]], particularly the subset
expressed in W3C Date and Time Formats [[datetime]].</p>
<aside class="example" title="Expressing the publication date">
<pre><dc:date>
2024-08-20
</dc:date></pre>
</aside>
<p>The element MAY include the following attributes: <a data-cite="epub-33#attrdef-dir">dir</a>,
<a data-cite="epub-33#attrdef-id">id</a>, <a data-cite="epub-33#attrdef-xml-lang"
>xml:lang</a> [[epub-33]].</p>
<p>Only one <code>dc:date</code> element is allowed in the package document metadata.</p>
<div class="note">
<p>The publication date is not the same as the <a href="#dcterms:modified">last modification
date</a>, which is the last time the publication was changed. </p>
</div>
</section>
<section id="dc:format">
<h5>dc:format</h5>
<p>The REQUIRED <code>dc:format</code> element [[dcterms]] identifies version of the eBraille
standard an publication conforms to. The [=value=] MUST contain both the name "eBraille" and
the version number.</p>
<p>For example, for this version of the specification, the value would be "<code>eBraille
1.0</code>".</p>
<aside class="example" title="eBraille version number">
<pre><dc:format>
eBraille 1.0
</dc:format></pre>
</aside>
<p>The element MAY include an <a data-cite="epub-33#attrdef-id"><code>id</code></a> attribute
[[epub-33]].</p>
</section>
<section id="dc:identifier">
<h5>dc:identifier</h5>
<p>The REQUIRED <code>dc:identifier</code> element [[epub-33]] contains an identifier for an
[=eBraille publication=], such as a UUID, DOI, or ISBN.</p>
<p>These identifiers SHOULD be formatted using a Uniform Resource Name.</p>
<aside class="example" title="Different types of identifiers">
<pre><dc:identifier>
urn:uuid:550e8400-e29b-41d4-a716-446655440000
</dc:identifier>
<dc:identifier>
urn:doi:10.1080/10509585.2015.1092083
</dc:identifier>
<dc:identifier>
https://en.wikipedia.org/wiki/Braille
</dc:identifier></pre>
</aside>
<div class="note">
<p>The <code>dc:identifier</code> element is not used to identify the source work being
transcribed. Use the <a href="#dc:source"><code>dc:source</code> element</a> for the
source work's identifier(s).</p>
</div>
<p>The element MAY include an <a data-cite="epub-33#attrdef-id"><code>id</code></a> attribute
[[epub-33]].</p>
<p>One identifier MUST be identified as the unique identifier for the publication using the
<code>package</code> element's <a data-cite="epub-33#attrdef-package-unique-identifier"
><code>unique-identifier</code> attribute</a> [[epub-33]]. This identifier MUST be
unique to the publication.</p>
<aside class="example" title="Unique identifier as ISBN">
<pre><package … unique-identifier="uid">
<metadata>
<dc:identifier id="uid">
urn:isbn:978-3-16-148410-0
</dc:identifier>
…
</metadata>
…
</package></pre>
</aside>
<div class="note">
<p>For more information, refer to the <a data-cite="epub-33#sec-opf-dcidentifier">definition
of the <code>dc:identifier</code> element</a> in [[epub-33]].</p>
</div>
</section>
<section id="dc:language">
<h5>dc:language</h5>
<p>The REQUIRED <a data-cite="epub-33#sec-opf-dclanguage"><code>dc:language</code> element</a>
[[epub-33]] identifies the language(s) of the [=eBraille publication=].</p>
<p>The [=value=] MUST be a <a href="https://www.rfc-editor.org/rfc/rfc5646#section-2.2.9"
>well-formed language tag</a> [[bcp47]]. The language code MUST include the script
subtag <code>Brai</code> to indicate the text is encoded in braille.</p>
<aside class="example" title="Language identifier for Italian braille">
<pre class="html"><dc:language>
it-Brai
</dc:language></pre>
</aside>
<p>When specified, a country code subtag MUST refer to the language of the work being
transcribed.</p>