From 2040ef2fa29f5360b2caaa313461644fd7460a7a Mon Sep 17 00:00:00 2001 From: Matt Garrish Date: Wed, 10 Sep 2025 10:03:31 -0400 Subject: [PATCH 01/19] updated access mode definitions --- js/lang/en/topics.json | 12 ++++ .../docs/metadata/schema.org/accessMode.html | 63 ++++++------------- .../schema.org/accessibilityFeature/ARIA.html | 2 +- .../accessibilityFeature/ChemML.html | 2 +- .../MathML-chemistry.html | 2 +- .../accessibilityFeature/MathML.html | 2 +- .../accessibilityFeature/alternativeText.html | 2 +- .../audioDescription.html | 2 +- .../accessibilityFeature/braille.html | 2 +- .../accessibilityFeature/closedCaptions.html | 2 +- .../accessibilityFeature/describedMath.html | 2 +- .../displayTransformability.html | 2 +- .../fullRubyAnnotations.html | 2 +- .../highContrastDisplay.html | 2 +- .../horizontalWriting.html | 2 +- .../accessibilityFeature/index.html | 2 +- .../accessibilityFeature/largePrint.html | 2 +- .../accessibilityFeature/latex-chemistry.html | 2 +- .../accessibilityFeature/latex.html | 2 +- .../accessibilityFeature/longDescription.html | 2 +- .../accessibilityFeature/openCaptions.html | 2 +- .../pageBreakMarkers.html | 2 +- .../accessibilityFeature/rubyAnnotations.html | 2 +- .../accessibilityFeature/signLanguage.html | 2 +- .../structuralNavigation.html | 2 +- .../synchronizedAudioText.html | 2 +- .../accessibilityFeature/tactileGraphic.html | 2 +- .../accessibilityFeature/tactileObject.html | 2 +- .../accessibilityFeature/taggedPDF.html | 2 +- .../accessibilityFeature/timingControl.html | 2 +- .../accessibilityFeature/transcript.html | 2 +- .../accessibilityFeature/ttsMarkup.html | 2 +- .../accessibilityFeature/verticalWriting.html | 2 +- .../withAdditionalWordSegmentation.html | 2 +- .../withoutAdditionalWordSegmentation.html | 2 +- .../accessibilityHazard/flashing.html | 2 +- .../accessibilityHazard/motionSimulation.html | 2 +- .../schema.org/accessibilityHazard/sound.html | 2 +- .../unknownFlashingHazard.html | 2 +- .../unknownMotionSimulationHazard.html | 2 +- 40 files changed, 69 insertions(+), 82 deletions(-) diff --git a/js/lang/en/topics.json b/js/lang/en/topics.json index 1b111cd9..90c51e44 100644 --- a/js/lang/en/topics.json +++ b/js/lang/en/topics.json @@ -955,6 +955,18 @@ "id": "schema.org", "showInRootIndex": false, "categories": [ + { + "title": "accessMode", + "id": "accessmode", + "indexPage": "../accessMode.html", + "showInRootIndex": false + }, + { + "title": "accessModeSufficient", + "id": "accessmodesufficient", + "indexPage": "../accessModeSufficient.html", + "showInRootIndex": false + }, { "title": "accessibilityFeature", "id": "accessibilityfeature", diff --git a/publishing/docs/metadata/schema.org/accessMode.html b/publishing/docs/metadata/schema.org/accessMode.html index ac03d4d1..db7da43f 100644 --- a/publishing/docs/metadata/schema.org/accessMode.html +++ b/publishing/docs/metadata/schema.org/accessMode.html @@ -87,54 +87,29 @@

Values

The following values are recommended for this property:

- -
-

auditory

-

The auditory value is used to indicate that there is an auditory component to - the content (e.g., audio tracks on their own or as part of a video, or an audiobook).

- -

The auditory value does not have to be set if the audio does not include - information necessary to understand the content (e.g., background noises in an interactive - game or mood music).

-
- -
-

tactile

+ -

The tactile value is used to indicate that a publication contains tactile - content (e.g., braille-formatted text or tactile images or objects).

- -

This value is typically not applicable outside of accessible republishing.

- -

The value is not used to indicate that text content can be converted to - tactile (e.g., using a refreshable braille display).

-
- -
-

textual

+

The following values are also often paired with a visual access mode to provide additional + information about the type of content in visual form:

-

The textual value is used to indicate that a publication contains text - content.

- -

This value is the most commonly used for digital publications, as most pubications contain at - least some text content.

- -

If a publication contains images of text, the visual - access mode is also set (or set instead, if the publication only contains images of text). - If, however, an image format allows the text content to be retained in text form (e.g., - SVG), the textual value is also specified.

-
- -
-

visual

+ -

The visual value is used to indicate that a publication contains visual content - such as images, grapics and video.

- -

This value is not set if the visual content does not contain any information necessary to - understanding the content (e.g., decorative images).

-
+

In addition the colorDependent value can be + paired with either visual or textual access modes to indicate that color perception is + necessary to understand part or all of the content.

diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/ARIA.html b/publishing/docs/metadata/schema.org/accessibilityFeature/ARIA.html index 121c97aa..89db7e6b 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/ARIA.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/ARIA.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/ChemML.html b/publishing/docs/metadata/schema.org/accessibilityFeature/ChemML.html index f1131dfc..6486f1b1 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/ChemML.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/ChemML.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/MathML-chemistry.html b/publishing/docs/metadata/schema.org/accessibilityFeature/MathML-chemistry.html index fd1541c3..a4aed56b 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/MathML-chemistry.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/MathML-chemistry.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/MathML.html b/publishing/docs/metadata/schema.org/accessibilityFeature/MathML.html index 32d10ee3..db8e89c5 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/MathML.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/MathML.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/alternativeText.html b/publishing/docs/metadata/schema.org/accessibilityFeature/alternativeText.html index 3b0362e4..d89ae445 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/alternativeText.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/alternativeText.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/audioDescription.html b/publishing/docs/metadata/schema.org/accessibilityFeature/audioDescription.html index a483f8a0..cf3b66d3 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/audioDescription.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/audioDescription.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/braille.html b/publishing/docs/metadata/schema.org/accessibilityFeature/braille.html index 196c42b0..ec4c878f 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/braille.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/braille.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/closedCaptions.html b/publishing/docs/metadata/schema.org/accessibilityFeature/closedCaptions.html index 1e80dbd7..561c6672 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/closedCaptions.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/closedCaptions.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/describedMath.html b/publishing/docs/metadata/schema.org/accessibilityFeature/describedMath.html index 213dc781..d64c2d7c 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/describedMath.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/describedMath.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/displayTransformability.html b/publishing/docs/metadata/schema.org/accessibilityFeature/displayTransformability.html index b0216ec6..24699cdd 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/displayTransformability.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/displayTransformability.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/fullRubyAnnotations.html b/publishing/docs/metadata/schema.org/accessibilityFeature/fullRubyAnnotations.html index 14419387..e7214036 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/fullRubyAnnotations.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/fullRubyAnnotations.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/highContrastDisplay.html b/publishing/docs/metadata/schema.org/accessibilityFeature/highContrastDisplay.html index 8394d016..15094d42 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/highContrastDisplay.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/highContrastDisplay.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/horizontalWriting.html b/publishing/docs/metadata/schema.org/accessibilityFeature/horizontalWriting.html index fd17d808..6222ba73 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/horizontalWriting.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/horizontalWriting.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/index.html b/publishing/docs/metadata/schema.org/accessibilityFeature/index.html index 98ddd5d5..3d4ff12a 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/index.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/index.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/largePrint.html b/publishing/docs/metadata/schema.org/accessibilityFeature/largePrint.html index 96563805..e32b66e0 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/largePrint.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/largePrint.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/latex-chemistry.html b/publishing/docs/metadata/schema.org/accessibilityFeature/latex-chemistry.html index ed62a53f..8d7db509 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/latex-chemistry.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/latex-chemistry.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/latex.html b/publishing/docs/metadata/schema.org/accessibilityFeature/latex.html index 22509bac..cf7fcd51 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/latex.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/latex.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/longDescription.html b/publishing/docs/metadata/schema.org/accessibilityFeature/longDescription.html index e0e53c47..e244b9b4 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/longDescription.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/longDescription.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/openCaptions.html b/publishing/docs/metadata/schema.org/accessibilityFeature/openCaptions.html index 4c4ad2e8..6b95e826 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/openCaptions.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/openCaptions.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/pageBreakMarkers.html b/publishing/docs/metadata/schema.org/accessibilityFeature/pageBreakMarkers.html index b1568e70..575996a5 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/pageBreakMarkers.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/pageBreakMarkers.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/rubyAnnotations.html b/publishing/docs/metadata/schema.org/accessibilityFeature/rubyAnnotations.html index 79004e1c..8d6752c4 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/rubyAnnotations.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/rubyAnnotations.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/signLanguage.html b/publishing/docs/metadata/schema.org/accessibilityFeature/signLanguage.html index 02a3ea30..fe63a4f4 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/signLanguage.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/signLanguage.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/structuralNavigation.html b/publishing/docs/metadata/schema.org/accessibilityFeature/structuralNavigation.html index 486ebad3..75ddbe1f 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/structuralNavigation.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/structuralNavigation.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/synchronizedAudioText.html b/publishing/docs/metadata/schema.org/accessibilityFeature/synchronizedAudioText.html index 07b7b5f5..023efac2 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/synchronizedAudioText.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/synchronizedAudioText.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/tactileGraphic.html b/publishing/docs/metadata/schema.org/accessibilityFeature/tactileGraphic.html index 4af4a531..5323ce55 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/tactileGraphic.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/tactileGraphic.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/tactileObject.html b/publishing/docs/metadata/schema.org/accessibilityFeature/tactileObject.html index 02c0a15e..3d7a7199 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/tactileObject.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/tactileObject.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/taggedPDF.html b/publishing/docs/metadata/schema.org/accessibilityFeature/taggedPDF.html index dde0e0f0..3ac93cce 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/taggedPDF.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/taggedPDF.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/timingControl.html b/publishing/docs/metadata/schema.org/accessibilityFeature/timingControl.html index 5b9bfc8f..ecde94d7 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/timingControl.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/timingControl.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/transcript.html b/publishing/docs/metadata/schema.org/accessibilityFeature/transcript.html index 4fe3e9b2..0a436c1d 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/transcript.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/transcript.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/ttsMarkup.html b/publishing/docs/metadata/schema.org/accessibilityFeature/ttsMarkup.html index 94f852ce..363588dc 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/ttsMarkup.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/ttsMarkup.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/verticalWriting.html b/publishing/docs/metadata/schema.org/accessibilityFeature/verticalWriting.html index 36cdbe8f..f8a8ac6a 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/verticalWriting.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/verticalWriting.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/withAdditionalWordSegmentation.html b/publishing/docs/metadata/schema.org/accessibilityFeature/withAdditionalWordSegmentation.html index eacfed1d..71e801c3 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/withAdditionalWordSegmentation.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/withAdditionalWordSegmentation.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityFeature/withoutAdditionalWordSegmentation.html b/publishing/docs/metadata/schema.org/accessibilityFeature/withoutAdditionalWordSegmentation.html index 34132efd..d1349c1c 100644 --- a/publishing/docs/metadata/schema.org/accessibilityFeature/withoutAdditionalWordSegmentation.html +++ b/publishing/docs/metadata/schema.org/accessibilityFeature/withoutAdditionalWordSegmentation.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityHazard/flashing.html b/publishing/docs/metadata/schema.org/accessibilityHazard/flashing.html index f2f6f22d..8e093cd6 100644 --- a/publishing/docs/metadata/schema.org/accessibilityHazard/flashing.html +++ b/publishing/docs/metadata/schema.org/accessibilityHazard/flashing.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityHazard/motionSimulation.html b/publishing/docs/metadata/schema.org/accessibilityHazard/motionSimulation.html index 98c0d3da..8c3b10ed 100644 --- a/publishing/docs/metadata/schema.org/accessibilityHazard/motionSimulation.html +++ b/publishing/docs/metadata/schema.org/accessibilityHazard/motionSimulation.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityHazard/sound.html b/publishing/docs/metadata/schema.org/accessibilityHazard/sound.html index c42feaea..aedb55cd 100644 --- a/publishing/docs/metadata/schema.org/accessibilityHazard/sound.html +++ b/publishing/docs/metadata/schema.org/accessibilityHazard/sound.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityHazard/unknownFlashingHazard.html b/publishing/docs/metadata/schema.org/accessibilityHazard/unknownFlashingHazard.html index a6c59c8b..04359fc6 100644 --- a/publishing/docs/metadata/schema.org/accessibilityHazard/unknownFlashingHazard.html +++ b/publishing/docs/metadata/schema.org/accessibilityHazard/unknownFlashingHazard.html @@ -8,7 +8,7 @@ diff --git a/publishing/docs/metadata/schema.org/accessibilityHazard/unknownMotionSimulationHazard.html b/publishing/docs/metadata/schema.org/accessibilityHazard/unknownMotionSimulationHazard.html index c06f2ae7..cf7d0bd6 100644 --- a/publishing/docs/metadata/schema.org/accessibilityHazard/unknownMotionSimulationHazard.html +++ b/publishing/docs/metadata/schema.org/accessibilityHazard/unknownMotionSimulationHazard.html @@ -8,7 +8,7 @@ From a4e7fb092d73f701f88731d5adeb17a68cb0be60 Mon Sep 17 00:00:00 2001 From: Matt Garrish Date: Wed, 10 Sep 2025 10:22:14 -0400 Subject: [PATCH 02/19] access modes --- publishing/docs/html/new.html | 72 ++++++ publishing/docs/html/word-breaks.html | 72 ++++++ .../schema.org/accessMode/auditory.html | 77 +++++++ .../schema.org/accessMode/chartOnVisual.html | 99 +++++++++ .../schema.org/accessMode/chemOnVisual.html | 88 ++++++++ .../schema.org/accessMode/colorDependent.html | 97 ++++++++ .../accessMode/diagramOnVisual.html | 102 +++++++++ .../schema.org/accessMode/mathOnVisual.html | 88 ++++++++ .../schema.org/accessMode/musicOnVisual.html | 86 +++++++ .../schema.org/accessMode/tactile.html | 84 +++++++ .../schema.org/accessMode/textOnVisual.html | 91 ++++++++ .../schema.org/accessMode/textual.html | 116 ++++++++++ .../schema.org/accessMode/visual.html | 93 ++++++++ .../accessModeSufficient/auditory.html | 106 +++++++++ .../accessModeSufficient/tactile.html | 106 +++++++++ .../accessModeSufficient/textual.html | 106 +++++++++ .../accessModeSufficient/visual.html | 106 +++++++++ publishing/docs/tutorials.html | 52 +++++ publishing/docs/tutorials/index.html | 32 +++ publishing/docs/tutorials/language.html | 210 ++++++++++++++++++ 20 files changed, 1883 insertions(+) create mode 100644 publishing/docs/html/new.html create mode 100644 publishing/docs/html/word-breaks.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/auditory.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/chartOnVisual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/chemOnVisual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/colorDependent.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/diagramOnVisual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/mathOnVisual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/musicOnVisual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/tactile.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/textOnVisual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/textual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/visual.html create mode 100644 publishing/docs/metadata/schema.org/accessModeSufficient/auditory.html create mode 100644 publishing/docs/metadata/schema.org/accessModeSufficient/tactile.html create mode 100644 publishing/docs/metadata/schema.org/accessModeSufficient/textual.html create mode 100644 publishing/docs/metadata/schema.org/accessModeSufficient/visual.html create mode 100644 publishing/docs/tutorials.html create mode 100644 publishing/docs/tutorials/index.html create mode 100644 publishing/docs/tutorials/language.html diff --git a/publishing/docs/html/new.html b/publishing/docs/html/new.html new file mode 100644 index 00000000..bf867f79 --- /dev/null +++ b/publishing/docs/html/new.html @@ -0,0 +1,72 @@ + + + + + What's New + + + + + + + +
+
+

Overview

+ +

Tracking changes to the HTML standard has become more difficult complicated since it changed to a + "living standard". The standard does not have a change log listing major changes; it instead refers + readers to the entire list of changes made in the standard's issue tracker. Although there is a + twitter account that tweets changes to the standard, even this is difficult to track now that + tweets appear out of order — plus not every change is relevant to publishers of digital + publications.

+ +

This page will try to bring to fill this information void by drawing attention to any major changes + to the standard that are likely to impact publishers.

+ +

Due to the ever-changing nature of the HTML standard, this page may not always be perfectly in sync. + If you are aware of a recent change that should be noted, please open an issue to have it + highlighted.

+
+
+

Changes

+ +
+
March 23, 2023 — The search element added
+
+

The new search element is a dedicated container for a search box. It fills a + semantic gap that the nav, section, article, and + aside elements missed.

+

Although the element is unlikely to be used inside publications, it may be beneficial for + identifying search interfaces in web-based reading systems.

+
+ +
July 1, 2022 — Outline algorithm removed; hgroup redefined
+
+

The outline algorithm has been fully removed from the HTML standard. The notion of the + sectioning of a document defining its outline, regardless of the headings used, has now + been put to rest.

+ +

This change should only re-affirm best practices for structuring documents, as the outline + algorithm has never worked in practice.

+ +

In removing the outline algorithm, the hgroup element has undergone a major + transformation. It is now designed to group a heading with its subheadings in a + semantically improved manner. The hgroup tag now allows only one heading tag + for the heading and can include subheadings in p tags. (This change will make + the DPUB-ARIA doc-subtitle role unnecessary moving forward.)

+ +

For more information about using hgroup, please refer to the Knowledge Base's + headings page.

+
+
+
+
+ + diff --git a/publishing/docs/html/word-breaks.html b/publishing/docs/html/word-breaks.html new file mode 100644 index 00000000..2a4d0c95 --- /dev/null +++ b/publishing/docs/html/word-breaks.html @@ -0,0 +1,72 @@ + + + + + Word Breaks + + + + + + +
+
+

Summary

+ +

Identify word break possibilities to ensure long words will fit the screen as the content is + zoomed.

+
+ +
+

Techniques

+
    +
  • ... [[WCAG-#]]
    • +
+
+ +
+

Examples

+ +
+
+
Example 1 —
+

...

+
+ 
...
+
+
+ +
+

Frequently Asked Questions

+ +
+
Question
+
+

Answer

+
+
+
+ +
+

Explanation

+ +

...

+
+ +
+

Related Links

+ +
    +
  • HTML — The wbr element
    • +
  • MDN — Hyphens
    • +
  • CSS —
    • +
+
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/auditory.html b/publishing/docs/metadata/schema.org/accessMode/auditory.html new file mode 100644 index 00000000..9bf42880 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/auditory.html @@ -0,0 +1,77 @@ + + + + + auditory + + + + + + + +
+
+

Explanation

+ +

The auditory value is used to indicate that there is an auditory component to + the content (e.g., audio tracks on their own or as part of a video, or an audiobook).

+ +

The auditory value does not have to be set if the audio does not include + information necessary to understand the content (e.g., background noises in an interactive + game or mood music).

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">auditory</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="auditory"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory"]
+
+
+ +
+

ONIX Mapping

+ +

The auditory value maps to multiple codes in list 81. Some common examples include + code 01 for audiobooks, + code 28 for video, and + code 44 for comics and manga.

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/chartOnVisual.html b/publishing/docs/metadata/schema.org/accessMode/chartOnVisual.html new file mode 100644 index 00000000..c8fc27c5 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/chartOnVisual.html @@ -0,0 +1,99 @@ + + + + + chartOnVisual + + + + + + + +
+
+
+

Caution

+

The application of this value and diagramOnVisual + is currently under discussion. One or both terms may be deprecated and/or replaced in the + future.

+
+ +

Explanation

+ +

The chartOnVisual value is used to indicate that a publication contains images of + charts. This value is always paired with a visual + acces mode as it is a modifier.

+ +

Charts are graphics that represent data. Common examples include pie charts, bar charts, line graphs, + scatter plots, bubble charts, graphs, etc. For graphics that represent concepts, see diagramOnVisual.

+ +

The chartOnVisual value is also commonly paired with textOnVisual if the chart also contains text + content necessary to its understanding. (If the chart is encoded in a format like SVG + where the text character data is retained in the markup, however, textOnVisual + would not apply.)

+ +

It is also not uncommon for chartOnVisual to be paired with + colorDependent if color perception is the + only way to differentiate information (e.g., a pie chart without a secondary indicator + to differentiate each slice).

+ +

The chartOnVisual access mode is common in publications produced using the EPUB format, + but is less common for audiobooks. It is only potentially relevant when an audiobook also contains + supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">chartOnVisual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="chartOnVisual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual", "chartOnVisual"]
+
+
+ +
+

ONIX Mapping

+ +

The chartsOnVisual value maps to list 81 + code 19 ("Figures, Diagrams, Charts").

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/chemOnVisual.html b/publishing/docs/metadata/schema.org/accessMode/chemOnVisual.html new file mode 100644 index 00000000..56130fc0 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/chemOnVisual.html @@ -0,0 +1,88 @@ + + + + + chemOnVisual + + + + + + + +
+
+

Explanation

+ +

The chemOnVisual value is used to indicate that a publication contains images of chemical + equations and formulas. This value is always paired with a visual + acces mode as it is a modifier.

+ +

It is not uncommon for chemOnVisual to be paired with + colorDependent if color perception is the + only way to differentiate information (e.g., if relationships are color coded).

+ +

It is sometimes also paired with textOnVisual + if text content beyond the equation or forumla data itself is also encoded in the image (e.g., + if relationships or descriptions are drawn as text in the image canvas).

+ +

Note that chemistry represented using a text-based markup language like MathML, or a formatting + language like LaTeX, is considered a textual access mode.

+ +

The chemOnVisual access mode is common in publications produced using the EPUB format + as there is no support for rendering chemical markup languages like ChemML. It is only potentially + relevant to audiobooks if there is supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">chemOnVisual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="chemOnVisual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual", "chemOnVisual"]
+
+
+ +
+

ONIX Mapping

+ +

The chemOnVisual value maps to list 81 + code 47 ("Chemical content").

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/colorDependent.html b/publishing/docs/metadata/schema.org/accessMode/colorDependent.html new file mode 100644 index 00000000..0a2b792c --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/colorDependent.html @@ -0,0 +1,97 @@ + + + + + colorDependent + + + + + + + +
+
+

Explanation

+ +

The colorDependent value is used to indicate that color is the sole means of + conveying some visual information. This value is typically paired with either a textual or visual acces mode as it is a modifier.

+ +

A common example of the need to perceive color occurs with graphs and charts. If the bars in + a graph, or the slices in a pie chart, are differentiated by color alone, then users may + not be able understand the data unless they can perceive those color differences.

+ +

Color dependence can also manifest itself in other ways, such as when learning assignments + are color coded to age or difficulty level, or when hyperlinks are colored to indicate + their purpose (e.g., to open external web sites).

+ +

The colorDependence value is not set if a secondary means of differentiating the + information is available. If, for example, graphs and charts include distinct patterns in their + data representations, such as lines going in different directions, then a user can use those + patterns to differentiate the data. Similarly, hyperlinks can use different types of underline + to gives a visual cue to their existence and purpose.

+ +

Note, however, that any secondary means of differentiating the information must also be visual + before this label can be omitted. Affordances provided for non-visual readers, such as through + hidden ARIA attributes, are not generally accessible to visual readers so do not improve the + accessibility for them. This value is meant to help individuals with, for example, color + blindness and cognitive disabilities determine if the content will be accessible to them.

+ +

The colorDependent access mode is common in publications produced using the EPUB format, + but is less common for audiobooks. It is only potentially relevant when an audiobook also contains + supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">colorDependent</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="colorDependent"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "textual", "colorDependent"]
+
+
+ +
+

ONIX Mapping

+ +

The colorDependent value does not currently have an ONIX equivalent.

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/diagramOnVisual.html b/publishing/docs/metadata/schema.org/accessMode/diagramOnVisual.html new file mode 100644 index 00000000..d0ce8e5f --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/diagramOnVisual.html @@ -0,0 +1,102 @@ + + + + + diagramOnVisual + + + + + + + +
+
+
+

Caution

+

The application of this value and chartOnVisual + is currently under discussion. One or both terms may be deprecated and/or replaced in the + future.

+
+ +

Explanation

+ +

The diagramOnVisual value is used to indicate that a publication contains images + of diagrams. This value is always paired with a visual + acces mode as it is a modifier.

+ +

Diagrams are graphics that represent concepts, flow and relationships. Common examples include + mind maps, anatomical diagrams, flowcharts, instructions to complete tasks, etc. For graphics + that represent concepts, see chartOnVisual.

+ +

The diagramOnVisual value is also commonly paired with textOnVisual if the diagram also contains text + content necessary to its understanding. (If the diagram is encoded in a format like SVG where + the text character data is retained in the markup, however, textOnVisual would + not apply.)

+ +

It is also not uncommon for diagramOnVisual to be paired with + colorDependent if color perception is the + only way to differentiate information (e.g., a flow chart that uses colors to represent + different organizational groups).

+ +

A diagamOnVisual access mode would not be specified if the graphic does not carry + information necessary to understand the publication, although such cases are rare for diagrams.

+ +

The diagramOnVisual access mode is common in publications produced using the EPUB format, + but is less common for audiobooks. It is only potentially relevant when an audiobook also contains + supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">diagramOnVisual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="diagramOnVisual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual", "diagramOnVisual"]
+
+
+ +
+

ONIX Mapping

+ +

The diagramOnVisual value maps to list 81 + code 19 ("Figures, Diagrams, Charts").

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/mathOnVisual.html b/publishing/docs/metadata/schema.org/accessMode/mathOnVisual.html new file mode 100644 index 00000000..d6ba889c --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/mathOnVisual.html @@ -0,0 +1,88 @@ + + + + + mathOnVisual + + + + + + + +
+
+

Explanation

+ +

The mathOnVisual value is used to indicate that a publication contains images of + mathematical equations and formulas. This value is always paired with a visual acces mode as it is a modifier.

+ +

It is not uncommon for mathOnVisual to be paired with + colorDependent if color perception is the + only way to differentiate information (e.g., if relationships are color coded).

+ +

It is sometimes also paired with textOnVisual + if text content beyond the equation or forumla data itself is also encoded in the image (e.g., + if relationships or descriptions are drawn as text in the image canvas).

+ +

Note that math represented using a text-based markup language like MathML, or a formatting + language like LaTeX, is considered a textual access mode.

+ +

The mathOnVisual access mode is common in publications produced using the EPUB format, + but is less common for audiobooks. It is only potentially relevant when an audiobook also contains + supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">mathOnVisual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="mathOnVisual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual", "mathOnVisual"]
+
+
+ +
+

ONIX Mapping

+ +

The mathOnVisual value maps to list 81 + code 48 ("Mathematical content").

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/musicOnVisual.html b/publishing/docs/metadata/schema.org/accessMode/musicOnVisual.html new file mode 100644 index 00000000..609e33e6 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/musicOnVisual.html @@ -0,0 +1,86 @@ + + + + + musicOnVisual + + + + + + + +
+
+

Explanation

+ +

The musicOnVisual value is used to indicate that a publication contains images of + musical scores. This value is always paired with a visual + acces mode as it is a modifier.

+ +

The value is also commonly paired with textOnVisual + if, for example, the lyrics for a musical score also drawn in the image canvas. + +

It is also possible for musicOnVisual to be paired with + colorDependent if color perception is the + only way to differentiate information (e.g., color coding to help learners read music).

+ +

As support for rendering markup languages that represent musical scores is not generally available, + using images for music compositions is common. Consequently, a musicOnVisual access + mode would be typical for any publications produced using the EPUB format that contains music + scores. It is only relevant to an audiobook if it also contains supplementary material + beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">musicOnVisual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="musicOnVisual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual", "musicOnVisual"]
+
+
+ +
+

ONIX Mapping

+ +

The musicOnVisual value maps to list 81 + code 11 ("Musical notation").

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/tactile.html b/publishing/docs/metadata/schema.org/accessMode/tactile.html new file mode 100644 index 00000000..eabb8b56 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/tactile.html @@ -0,0 +1,84 @@ + + + + + tactile + + + + + + + +
+
+

Explanation

+ +

The tactile value is used to indicate that a publication contains tactile + content (e.g., braille-formatted text, tactile images, or tactile objects).

+ +

This value is typically not applicable to publications outside of accessible republishing.

+ +

Although digital publications will not contain physical tactile objects, if a publication + provides links to such items (e.g., for download and printing on a 3d printer), the value + should be set.

+ +

The value is not used to indicate that text content can be converted to + tactile (e.g., using a refreshable braille display). A fully textual + access mode, or a sufficient access mode + of textual, is used to indicate that content can be converted to braille or read aloud + using text-to-speech synthesizers.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">tactile</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="tactile"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "tactile"]
+
+
+ +
+

ONIX Mapping

+ +

The tactile value maps to list 21 + code BRL for a braille edition or list 175 code E146 + for a BRF (braille ready format) file.

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/textOnVisual.html b/publishing/docs/metadata/schema.org/accessMode/textOnVisual.html new file mode 100644 index 00000000..cbb6d97b --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/textOnVisual.html @@ -0,0 +1,91 @@ + + + + + textOnVisual + + + + + + + +
+
+

Explanation

+ +

The textOnVisual value is used to indicate that a publication contains images of text. + This value is always paired with a visual acces mode + as it is a modifier.

+ +

Images of text are where the text is part of the image data so can only be read visually. + JPEG and PNG are two common image formats that cannot preserve text separate from the visual + canvas it is drawn on. SVG, on the other hand, has markup elements to contain and present + text content, which allow reading systems and assistive technologies to access the character + data indepenent from its rendering.

+ +

A textOnVisual access mode is not specified where the text does not carry information + necessary to understand the publication. Corporate logos and the title on a cover page are a + couple of examples of image text that is considered decorative.

+ +

The value is also sometimes paired with colorDependent + if color perception is the only way to differentiate information (e.g., colored text to differentiate + different learning levels or related topics).

+ +

The textOnVisual access mode is common in publications produced using the EPUB format, + particularly for comics and manga, but is less common for audiobooks. It is only potentially relevant + when an audiobook also contains supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">textOnVisual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="textOnVisual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual", "textOnVisual"]
+
+
+ +
+

ONIX Mapping

+ +

The textOnVisual value maps to list 81 + code 49 ("Images of text").

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/textual.html b/publishing/docs/metadata/schema.org/accessMode/textual.html new file mode 100644 index 00000000..cc69dcb0 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/textual.html @@ -0,0 +1,116 @@ + + + + + textual + + + + + + + +
+
+

Explanation

+ +

The textual access mode value is used to indicate that a publication contains information + encoded as text character data. Consequently, the value only applies to digital publications (e.g., + even though a print book has text content it is considered to have a visual access mode because you + have to be able to see the ink on the page).

+ +

Text character data can be rendered and manipulated in a variety of ways to accommodate different user + needs — visually for sighted readers and readers with low vision, as synthetic speech for readers + who are blind, etc. This characteristic makes it the most flexible mode of access.

+ +

Note that not all text content necessitates setting a textual access mode. Publishers often include + text content that is not directly related to the content (i.e., is not part of the work created by + the author) or that is not considered essential for reading the work.

+ +

Examples of non-essential text content include:

+ +
    +
  • the title page, if the title and author are available through the publication + metadata.
    • +
  • the title page verso information about the publisher, copyright dates, etc. are + not critical to reading the text.
    • +
  • author bios
    • +
  • lists of additional or future works by the author or by other authors
    • +
  • marketing blurbs
    • +
  • endorsements
    • +
+ +

If a publication also contains images of text (i.e., where the text is part of the image data), set the + textOnVisual and visual + access modes. If a publication only consists of images of text (e.g., comics and manga) a + textual access mode is not set.

+ +

If an image format allows the text content to be retained in text form (e.g., SVG), a + textual access mode is specified in addition to visual (assuming there + is more to the image to understand it than just the text). The textOnVisual value is + not set because it is possible for reading systems and assistive technologies to access and read + aloud the text content for users.

+ +

The textual value is also sometimes paired with colorDependent if color perception is the only way + to differentiate information (e.g., colored text to differentiate different learning levels or + related topics).

+ +

A textual access mode is common in publications produced using the EPUB format, + but is less common for audiobooks. It is only potentially relevent when an audiobook also contains + supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">textual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="textual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "textual"]
+
+
+ +
+

ONIX Mapping

+ +

The textual value most commonly maps to list 81 + code 10. It can map to other values + such as code 16 for text that is not part + of the main content

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/visual.html b/publishing/docs/metadata/schema.org/accessMode/visual.html new file mode 100644 index 00000000..b46a0c19 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/visual.html @@ -0,0 +1,93 @@ + + + + + visual + + + + + + + +
+
+

Explanation

+ +

The visual access mode value is used to indicate that a publication contains visual + content such as images, grapics and video, or that it requires visual perception to fully + access information (e.g., the ability to perceive background or border colors, or to read + text that is encoded in images).

+ +

This value is not set if the visual content does not contain any information necessary to + understanding the content (e.g., logos, cover artwork, and visual flair at the start of + chapters).

+ +

A visual access mode is common in publications produced using the EPUB format, + but is less common for audiobooks. It is only potentially relevant when an audiobook also contains + supplementary material beyond the audio.

+ +

The visual value should always be set when using any of the visual content + indicators — chartOnVisual, + chemOnVisual, + diagramOnVisual, + mathOnVisual, + musicOnVisual, and + textOnVisual. It is also set with + colorDependent when the color requirement + is in the visual content (as opposed to, say, colored textual content).

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual"]
+
+
+ +
+

ONIX Mapping

+ +

The visual value maps to multiple codes in list 81. Some common examples include + code 07 for still images and graphics, + code 28 for video, and + code 44 for comics and manga.

+
+ +
+

Related Links

+ +
    +
  • Schema.org — accessMode
    • +
  • Schema.org Accessibility Vocabulary — visual
    • +
+
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/auditory.html b/publishing/docs/metadata/schema.org/accessModeSufficient/auditory.html new file mode 100644 index 00000000..b03c34e1 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessModeSufficient/auditory.html @@ -0,0 +1,106 @@ + + + + + accessModeSufficient + + + + + + + +
+
+

Definition

+ +

A list of single or combined access modes that are sufficient to understand all the + intellectual content of a resource.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessModeSufficient">textual,visual</meta>
+<meta property="schema:accessModeSufficient">textual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessModeSufficient" content="textual,visual"/>
+<meta name="schema:accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 3 — HTML with RDFa
+
+ 
<meta property="accessModeSufficient" content="textual,visual"/>
+<meta property="accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 4 — HTML with microdata
+
+ 
<meta itemprop="accessModeSufficient" content="textual,visual"/>
+<meta itemprop="accessModeSufficient" content="textual"/>
+
+
+ +
+

Values

+ +

The property takes one or more of the following values:

+ +
    +
  • auditory
    • +
  • tactile
    • +
  • textual
    • +
  • visual
    • +
+ +

The meaning of these values is the same as their definitions for access + modes, but sufficient access modes identify the different combinations of senses that can be + used to sufficiently consume the content, not just the raw access modes of the content itself.

+ +

A publication with images and text, for example, will require both visual and textual modes to be + consumed. If the images are also adequately described (alt text and extended descriptions, as + appropriate) a single textual mode would also be sufficient, indicating someone who is blind can + consume the content.

+ +
+

Note

+

Unless the metadata format used supports lists of lists (e.g., JSON-LD), use a separate property + declaration for each list of sufficient access modes. Separate the values with commas.

+
+
+ +
+

Related Links

+ +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/tactile.html b/publishing/docs/metadata/schema.org/accessModeSufficient/tactile.html new file mode 100644 index 00000000..b03c34e1 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessModeSufficient/tactile.html @@ -0,0 +1,106 @@ + + + + + accessModeSufficient + + + + + + + +
+
+

Definition

+ +

A list of single or combined access modes that are sufficient to understand all the + intellectual content of a resource.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessModeSufficient">textual,visual</meta>
+<meta property="schema:accessModeSufficient">textual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessModeSufficient" content="textual,visual"/>
+<meta name="schema:accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 3 — HTML with RDFa
+
+ 
<meta property="accessModeSufficient" content="textual,visual"/>
+<meta property="accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 4 — HTML with microdata
+
+ 
<meta itemprop="accessModeSufficient" content="textual,visual"/>
+<meta itemprop="accessModeSufficient" content="textual"/>
+
+
+ +
+

Values

+ +

The property takes one or more of the following values:

+ +
    +
  • auditory
    • +
  • tactile
    • +
  • textual
    • +
  • visual
    • +
+ +

The meaning of these values is the same as their definitions for access + modes, but sufficient access modes identify the different combinations of senses that can be + used to sufficiently consume the content, not just the raw access modes of the content itself.

+ +

A publication with images and text, for example, will require both visual and textual modes to be + consumed. If the images are also adequately described (alt text and extended descriptions, as + appropriate) a single textual mode would also be sufficient, indicating someone who is blind can + consume the content.

+ +
+

Note

+

Unless the metadata format used supports lists of lists (e.g., JSON-LD), use a separate property + declaration for each list of sufficient access modes. Separate the values with commas.

+
+
+ +
+

Related Links

+ +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html b/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html new file mode 100644 index 00000000..b03c34e1 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html @@ -0,0 +1,106 @@ + + + + + accessModeSufficient + + + + + + + +
+
+

Definition

+ +

A list of single or combined access modes that are sufficient to understand all the + intellectual content of a resource.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessModeSufficient">textual,visual</meta>
+<meta property="schema:accessModeSufficient">textual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessModeSufficient" content="textual,visual"/>
+<meta name="schema:accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 3 — HTML with RDFa
+
+ 
<meta property="accessModeSufficient" content="textual,visual"/>
+<meta property="accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 4 — HTML with microdata
+
+ 
<meta itemprop="accessModeSufficient" content="textual,visual"/>
+<meta itemprop="accessModeSufficient" content="textual"/>
+
+
+ +
+

Values

+ +

The property takes one or more of the following values:

+ +
    +
  • auditory
    • +
  • tactile
    • +
  • textual
    • +
  • visual
    • +
+ +

The meaning of these values is the same as their definitions for access + modes, but sufficient access modes identify the different combinations of senses that can be + used to sufficiently consume the content, not just the raw access modes of the content itself.

+ +

A publication with images and text, for example, will require both visual and textual modes to be + consumed. If the images are also adequately described (alt text and extended descriptions, as + appropriate) a single textual mode would also be sufficient, indicating someone who is blind can + consume the content.

+ +
+

Note

+

Unless the metadata format used supports lists of lists (e.g., JSON-LD), use a separate property + declaration for each list of sufficient access modes. Separate the values with commas.

+
+
+ +
+

Related Links

+ +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/visual.html b/publishing/docs/metadata/schema.org/accessModeSufficient/visual.html new file mode 100644 index 00000000..b03c34e1 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessModeSufficient/visual.html @@ -0,0 +1,106 @@ + + + + + accessModeSufficient + + + + + + + +
+
+

Definition

+ +

A list of single or combined access modes that are sufficient to understand all the + intellectual content of a resource.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessModeSufficient">textual,visual</meta>
+<meta property="schema:accessModeSufficient">textual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessModeSufficient" content="textual,visual"/>
+<meta name="schema:accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 3 — HTML with RDFa
+
+ 
<meta property="accessModeSufficient" content="textual,visual"/>
+<meta property="accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 4 — HTML with microdata
+
+ 
<meta itemprop="accessModeSufficient" content="textual,visual"/>
+<meta itemprop="accessModeSufficient" content="textual"/>
+
+
+ +
+

Values

+ +

The property takes one or more of the following values:

+ +
    +
  • auditory
    • +
  • tactile
    • +
  • textual
    • +
  • visual
    • +
+ +

The meaning of these values is the same as their definitions for access + modes, but sufficient access modes identify the different combinations of senses that can be + used to sufficiently consume the content, not just the raw access modes of the content itself.

+ +

A publication with images and text, for example, will require both visual and textual modes to be + consumed. If the images are also adequately described (alt text and extended descriptions, as + appropriate) a single textual mode would also be sufficient, indicating someone who is blind can + consume the content.

+ +
+

Note

+

Unless the metadata format used supports lists of lists (e.g., JSON-LD), use a separate property + declaration for each list of sufficient access modes. Separate the values with commas.

+
+
+ +
+

Related Links

+ +
+
+ + diff --git a/publishing/docs/tutorials.html b/publishing/docs/tutorials.html new file mode 100644 index 00000000..89957cce --- /dev/null +++ b/publishing/docs/tutorials.html @@ -0,0 +1,52 @@ + + + + + Tutorials + + + + + + + + +
+ +
+ + diff --git a/publishing/docs/tutorials/index.html b/publishing/docs/tutorials/index.html new file mode 100644 index 00000000..3e4b747f --- /dev/null +++ b/publishing/docs/tutorials/index.html @@ -0,0 +1,32 @@ + + + + + Tutorials + + + + + + + + +
+
+ + diff --git a/publishing/docs/tutorials/language.html b/publishing/docs/tutorials/language.html new file mode 100644 index 00000000..82b50d5c --- /dev/null +++ b/publishing/docs/tutorials/language.html @@ -0,0 +1,210 @@ + + + + + Setting the language in EPUB publications + + + + + + + +
+
+

Introduction

+ +

Setting the language of a publication is an important step in ensuring its accessibility as it helps + assistive technologies pronounce the text correctly. Without language declarations, assistive + technologies will read the text in the default language of the user. This can lead to the entire + text being mispronounced (when reading a publication in another language) or individual phrases + being mangled (for inline foreign phrases).

+ +

This tutorial covers how to set the language in the EPUB package document as well as + in XHTML content documents so that the information is available to assistive technologies + and reading systems.

+
+ +
+

What are language tags

+ +

Before we can get into the mechanisms for setting the language, it is important to first understand + what you are setting. Languages are declared using language tags, which are hyphen-separated + codes that identify the language, region, script, etc.

+ +

At a minimum, each language tag consists of a primary language, which is a two- or three-character code + that identifies the language.

+ +

The following table lists some common language codes:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeLanguage
deGerman
enEnglish
heHebrew
hiHindi
koKorean
+ +

For the complete list of language codes, refer to the IANA + language registry (search for the language's name to find its code).

+ +

For many languages, all that you have to specify is the primary language code. For others with + regional dialects, however, you can add an additional region subtag for more precision.

+ +

American and British pronounciations, for example, can differ significantly, but a code of + "en" will not inform an assistive technology which to apply when it matters (e.g., + when reading an American or British novel where the characters talk in regional dialects). Adding + the region solves this problem as it allows the assistive technology to pick a more appropriate + voice for playback.

+ +

The region subtag is added to the language using a hypen. For example, "en-US" indicates that + the text is in English as spoken in the US.

+ +

The following table lists some common language tags with their region subtags:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeLanguage
en-GBBritish English
en-USUS English
fr-CAFrench as spoken in Canada
en-FRFrench as spoken in France
+ +

Note that although it is common convention to capitalize region tags, this is not a requirement. + Language tags are processed case-insensitively.

+ +

It is not necessary to use region codes for metadata such as that found in the EPUB package document. This information is rarely region-specific + and users will typically expect to hear it announced in their preferred regional dialect.

+ +

You can also specify the script the text is written in using a script subtag. Simplified and + traditional Chinese, for example, can be differentiated using the "zh-Hans" and "zh-Hant" script + tags. You should only use script subtags when a language is commonly written in more than one + script.

+ +

For a more in-depth explanation of language tags, refer to the W3C article Language tags in HTML and + XML.

+
+ +
+

Language declaration mechanisms

+ +

With an understanding now of what language tags are, it is time to turn to how to express those tags + in markup languages. + +

In XML-based markup languages, like XHTML, SVG and the EPUB package document, the standard mechanism + for declaring the language of the text is the xml:lang attribute, where the value of + this attribute is a language tag.

+ +

Best practice is to always declare a language on the root element (i.e., the element that contains + all the other markup). For example, the language of an XHTML document can be specified as follows:

+ + 
<html … xml:lang="en-US">
+   …
+</html>
+ +

Language information is inherited, so by setting the attribute on the root element you automatically + declare language information for all the elements and text in the document.

+ +
+

Note on HTML

+ +

Although it is only required to use the xml:lang attribute with XHTML documents, it + is best practice to also add a lang attribute. When doing so, the language tag + expressed in the xml:lang and lang attributes must match. For + example:

+ + 
<html … xml:lang="en-US" lang="en-US">
+ +

The reason why it is recommended to add both attributes is that the XHTML documents in EPUB + publications may not always be processed as XML, despite the requirements of the standard. A + browser-based reading system might, for example, default to processing all the XHTML documents + as regular HTML. In this case, the xml:lang attribute is ignored, as HTML + processors only recognize the lang attribute. By always adding both attributes, + you help ensure that the correct language information is available to users regardless of how + the document is processed.

+
+
+ +
+

Overriding the language

+
+ +
+

Setting the publication language

+ +

The language of an EPUB publication is set in a dc:language element in the package + document.

+
+ +
+

Setting the package document language

+ +

Setting the language of an EPUB publication does not set the language of the + metadata in the package document. It is also required to specify the language of the metadata + using xml:lang attributes.

+
+ +
+

Setting the content language

+
+ +
+

Related Links

+ +
+
+ + From c79086b841a3f0b2fa5e2de134472d9e204c1c7f Mon Sep 17 00:00:00 2001 From: Matt Garrish Date: Wed, 10 Sep 2025 10:28:54 -0400 Subject: [PATCH 03/19] fix issues --- .../schema.org/accessMode/auditory.html | 77 ++++++++++++ .../schema.org/accessMode/chartOnVisual.html | 99 +++++++++++++++ .../schema.org/accessMode/chemOnVisual.html | 88 +++++++++++++ .../schema.org/accessMode/colorDependent.html | 97 +++++++++++++++ .../accessMode/diagramOnVisual.html | 102 +++++++++++++++ .../schema.org/accessMode/mathOnVisual.html | 88 +++++++++++++ .../schema.org/accessMode/musicOnVisual.html | 86 +++++++++++++ .../schema.org/accessMode/tactile.html | 84 +++++++++++++ .../schema.org/accessMode/textOnVisual.html | 91 ++++++++++++++ .../schema.org/accessMode/textual.html | 116 ++++++++++++++++++ .../schema.org/accessMode/visual.html | 93 ++++++++++++++ .../accessModeSufficient/auditory.html | 106 ++++++++++++++++ .../accessModeSufficient/tactile.html | 106 ++++++++++++++++ .../accessModeSufficient/textual.html | 106 ++++++++++++++++ .../accessModeSufficient/visual.html | 106 ++++++++++++++++ 15 files changed, 1445 insertions(+) create mode 100644 publishing/docs/metadata/schema.org/accessMode/auditory.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/chartOnVisual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/chemOnVisual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/colorDependent.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/diagramOnVisual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/mathOnVisual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/musicOnVisual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/tactile.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/textOnVisual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/textual.html create mode 100644 publishing/docs/metadata/schema.org/accessMode/visual.html create mode 100644 publishing/docs/metadata/schema.org/accessModeSufficient/auditory.html create mode 100644 publishing/docs/metadata/schema.org/accessModeSufficient/tactile.html create mode 100644 publishing/docs/metadata/schema.org/accessModeSufficient/textual.html create mode 100644 publishing/docs/metadata/schema.org/accessModeSufficient/visual.html diff --git a/publishing/docs/metadata/schema.org/accessMode/auditory.html b/publishing/docs/metadata/schema.org/accessMode/auditory.html new file mode 100644 index 00000000..9bf42880 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/auditory.html @@ -0,0 +1,77 @@ + + + + + auditory + + + + + + + +
+
+

Explanation

+ +

The auditory value is used to indicate that there is an auditory component to + the content (e.g., audio tracks on their own or as part of a video, or an audiobook).

+ +

The auditory value does not have to be set if the audio does not include + information necessary to understand the content (e.g., background noises in an interactive + game or mood music).

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">auditory</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="auditory"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory"]
+
+
+ +
+

ONIX Mapping

+ +

The auditory value maps to multiple codes in list 81. Some common examples include + code 01 for audiobooks, + code 28 for video, and + code 44 for comics and manga.

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/chartOnVisual.html b/publishing/docs/metadata/schema.org/accessMode/chartOnVisual.html new file mode 100644 index 00000000..c8fc27c5 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/chartOnVisual.html @@ -0,0 +1,99 @@ + + + + + chartOnVisual + + + + + + + +
+
+
+

Caution

+

The application of this value and diagramOnVisual + is currently under discussion. One or both terms may be deprecated and/or replaced in the + future.

+
+ +

Explanation

+ +

The chartOnVisual value is used to indicate that a publication contains images of + charts. This value is always paired with a visual + acces mode as it is a modifier.

+ +

Charts are graphics that represent data. Common examples include pie charts, bar charts, line graphs, + scatter plots, bubble charts, graphs, etc. For graphics that represent concepts, see diagramOnVisual.

+ +

The chartOnVisual value is also commonly paired with textOnVisual if the chart also contains text + content necessary to its understanding. (If the chart is encoded in a format like SVG + where the text character data is retained in the markup, however, textOnVisual + would not apply.)

+ +

It is also not uncommon for chartOnVisual to be paired with + colorDependent if color perception is the + only way to differentiate information (e.g., a pie chart without a secondary indicator + to differentiate each slice).

+ +

The chartOnVisual access mode is common in publications produced using the EPUB format, + but is less common for audiobooks. It is only potentially relevant when an audiobook also contains + supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">chartOnVisual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="chartOnVisual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual", "chartOnVisual"]
+
+
+ +
+

ONIX Mapping

+ +

The chartsOnVisual value maps to list 81 + code 19 ("Figures, Diagrams, Charts").

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/chemOnVisual.html b/publishing/docs/metadata/schema.org/accessMode/chemOnVisual.html new file mode 100644 index 00000000..56130fc0 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/chemOnVisual.html @@ -0,0 +1,88 @@ + + + + + chemOnVisual + + + + + + + +
+
+

Explanation

+ +

The chemOnVisual value is used to indicate that a publication contains images of chemical + equations and formulas. This value is always paired with a visual + acces mode as it is a modifier.

+ +

It is not uncommon for chemOnVisual to be paired with + colorDependent if color perception is the + only way to differentiate information (e.g., if relationships are color coded).

+ +

It is sometimes also paired with textOnVisual + if text content beyond the equation or forumla data itself is also encoded in the image (e.g., + if relationships or descriptions are drawn as text in the image canvas).

+ +

Note that chemistry represented using a text-based markup language like MathML, or a formatting + language like LaTeX, is considered a textual access mode.

+ +

The chemOnVisual access mode is common in publications produced using the EPUB format + as there is no support for rendering chemical markup languages like ChemML. It is only potentially + relevant to audiobooks if there is supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">chemOnVisual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="chemOnVisual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual", "chemOnVisual"]
+
+
+ +
+

ONIX Mapping

+ +

The chemOnVisual value maps to list 81 + code 47 ("Chemical content").

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/colorDependent.html b/publishing/docs/metadata/schema.org/accessMode/colorDependent.html new file mode 100644 index 00000000..0a2b792c --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/colorDependent.html @@ -0,0 +1,97 @@ + + + + + colorDependent + + + + + + + +
+
+

Explanation

+ +

The colorDependent value is used to indicate that color is the sole means of + conveying some visual information. This value is typically paired with either a textual or visual acces mode as it is a modifier.

+ +

A common example of the need to perceive color occurs with graphs and charts. If the bars in + a graph, or the slices in a pie chart, are differentiated by color alone, then users may + not be able understand the data unless they can perceive those color differences.

+ +

Color dependence can also manifest itself in other ways, such as when learning assignments + are color coded to age or difficulty level, or when hyperlinks are colored to indicate + their purpose (e.g., to open external web sites).

+ +

The colorDependence value is not set if a secondary means of differentiating the + information is available. If, for example, graphs and charts include distinct patterns in their + data representations, such as lines going in different directions, then a user can use those + patterns to differentiate the data. Similarly, hyperlinks can use different types of underline + to gives a visual cue to their existence and purpose.

+ +

Note, however, that any secondary means of differentiating the information must also be visual + before this label can be omitted. Affordances provided for non-visual readers, such as through + hidden ARIA attributes, are not generally accessible to visual readers so do not improve the + accessibility for them. This value is meant to help individuals with, for example, color + blindness and cognitive disabilities determine if the content will be accessible to them.

+ +

The colorDependent access mode is common in publications produced using the EPUB format, + but is less common for audiobooks. It is only potentially relevant when an audiobook also contains + supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">colorDependent</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="colorDependent"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "textual", "colorDependent"]
+
+
+ +
+

ONIX Mapping

+ +

The colorDependent value does not currently have an ONIX equivalent.

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/diagramOnVisual.html b/publishing/docs/metadata/schema.org/accessMode/diagramOnVisual.html new file mode 100644 index 00000000..d0ce8e5f --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/diagramOnVisual.html @@ -0,0 +1,102 @@ + + + + + diagramOnVisual + + + + + + + +
+
+
+

Caution

+

The application of this value and chartOnVisual + is currently under discussion. One or both terms may be deprecated and/or replaced in the + future.

+
+ +

Explanation

+ +

The diagramOnVisual value is used to indicate that a publication contains images + of diagrams. This value is always paired with a visual + acces mode as it is a modifier.

+ +

Diagrams are graphics that represent concepts, flow and relationships. Common examples include + mind maps, anatomical diagrams, flowcharts, instructions to complete tasks, etc. For graphics + that represent concepts, see chartOnVisual.

+ +

The diagramOnVisual value is also commonly paired with textOnVisual if the diagram also contains text + content necessary to its understanding. (If the diagram is encoded in a format like SVG where + the text character data is retained in the markup, however, textOnVisual would + not apply.)

+ +

It is also not uncommon for diagramOnVisual to be paired with + colorDependent if color perception is the + only way to differentiate information (e.g., a flow chart that uses colors to represent + different organizational groups).

+ +

A diagamOnVisual access mode would not be specified if the graphic does not carry + information necessary to understand the publication, although such cases are rare for diagrams.

+ +

The diagramOnVisual access mode is common in publications produced using the EPUB format, + but is less common for audiobooks. It is only potentially relevant when an audiobook also contains + supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">diagramOnVisual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="diagramOnVisual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual", "diagramOnVisual"]
+
+
+ +
+

ONIX Mapping

+ +

The diagramOnVisual value maps to list 81 + code 19 ("Figures, Diagrams, Charts").

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/mathOnVisual.html b/publishing/docs/metadata/schema.org/accessMode/mathOnVisual.html new file mode 100644 index 00000000..d6ba889c --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/mathOnVisual.html @@ -0,0 +1,88 @@ + + + + + mathOnVisual + + + + + + + +
+
+

Explanation

+ +

The mathOnVisual value is used to indicate that a publication contains images of + mathematical equations and formulas. This value is always paired with a visual acces mode as it is a modifier.

+ +

It is not uncommon for mathOnVisual to be paired with + colorDependent if color perception is the + only way to differentiate information (e.g., if relationships are color coded).

+ +

It is sometimes also paired with textOnVisual + if text content beyond the equation or forumla data itself is also encoded in the image (e.g., + if relationships or descriptions are drawn as text in the image canvas).

+ +

Note that math represented using a text-based markup language like MathML, or a formatting + language like LaTeX, is considered a textual access mode.

+ +

The mathOnVisual access mode is common in publications produced using the EPUB format, + but is less common for audiobooks. It is only potentially relevant when an audiobook also contains + supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">mathOnVisual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="mathOnVisual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual", "mathOnVisual"]
+
+
+ +
+

ONIX Mapping

+ +

The mathOnVisual value maps to list 81 + code 48 ("Mathematical content").

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/musicOnVisual.html b/publishing/docs/metadata/schema.org/accessMode/musicOnVisual.html new file mode 100644 index 00000000..609e33e6 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/musicOnVisual.html @@ -0,0 +1,86 @@ + + + + + musicOnVisual + + + + + + + +
+
+

Explanation

+ +

The musicOnVisual value is used to indicate that a publication contains images of + musical scores. This value is always paired with a visual + acces mode as it is a modifier.

+ +

The value is also commonly paired with textOnVisual + if, for example, the lyrics for a musical score also drawn in the image canvas. + +

It is also possible for musicOnVisual to be paired with + colorDependent if color perception is the + only way to differentiate information (e.g., color coding to help learners read music).

+ +

As support for rendering markup languages that represent musical scores is not generally available, + using images for music compositions is common. Consequently, a musicOnVisual access + mode would be typical for any publications produced using the EPUB format that contains music + scores. It is only relevant to an audiobook if it also contains supplementary material + beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">musicOnVisual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="musicOnVisual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual", "musicOnVisual"]
+
+
+ +
+

ONIX Mapping

+ +

The musicOnVisual value maps to list 81 + code 11 ("Musical notation").

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/tactile.html b/publishing/docs/metadata/schema.org/accessMode/tactile.html new file mode 100644 index 00000000..eabb8b56 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/tactile.html @@ -0,0 +1,84 @@ + + + + + tactile + + + + + + + +
+
+

Explanation

+ +

The tactile value is used to indicate that a publication contains tactile + content (e.g., braille-formatted text, tactile images, or tactile objects).

+ +

This value is typically not applicable to publications outside of accessible republishing.

+ +

Although digital publications will not contain physical tactile objects, if a publication + provides links to such items (e.g., for download and printing on a 3d printer), the value + should be set.

+ +

The value is not used to indicate that text content can be converted to + tactile (e.g., using a refreshable braille display). A fully textual + access mode, or a sufficient access mode + of textual, is used to indicate that content can be converted to braille or read aloud + using text-to-speech synthesizers.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">tactile</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="tactile"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "tactile"]
+
+
+ +
+

ONIX Mapping

+ +

The tactile value maps to list 21 + code BRL for a braille edition or list 175 code E146 + for a BRF (braille ready format) file.

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/textOnVisual.html b/publishing/docs/metadata/schema.org/accessMode/textOnVisual.html new file mode 100644 index 00000000..cbb6d97b --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/textOnVisual.html @@ -0,0 +1,91 @@ + + + + + textOnVisual + + + + + + + +
+
+

Explanation

+ +

The textOnVisual value is used to indicate that a publication contains images of text. + This value is always paired with a visual acces mode + as it is a modifier.

+ +

Images of text are where the text is part of the image data so can only be read visually. + JPEG and PNG are two common image formats that cannot preserve text separate from the visual + canvas it is drawn on. SVG, on the other hand, has markup elements to contain and present + text content, which allow reading systems and assistive technologies to access the character + data indepenent from its rendering.

+ +

A textOnVisual access mode is not specified where the text does not carry information + necessary to understand the publication. Corporate logos and the title on a cover page are a + couple of examples of image text that is considered decorative.

+ +

The value is also sometimes paired with colorDependent + if color perception is the only way to differentiate information (e.g., colored text to differentiate + different learning levels or related topics).

+ +

The textOnVisual access mode is common in publications produced using the EPUB format, + particularly for comics and manga, but is less common for audiobooks. It is only potentially relevant + when an audiobook also contains supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+<meta property="schema:accessMode">textOnVisual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+<meta name="schema:accessMode" content="textOnVisual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual", "textOnVisual"]
+
+
+ +
+

ONIX Mapping

+ +

The textOnVisual value maps to list 81 + code 49 ("Images of text").

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/textual.html b/publishing/docs/metadata/schema.org/accessMode/textual.html new file mode 100644 index 00000000..cc69dcb0 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/textual.html @@ -0,0 +1,116 @@ + + + + + textual + + + + + + + +
+
+

Explanation

+ +

The textual access mode value is used to indicate that a publication contains information + encoded as text character data. Consequently, the value only applies to digital publications (e.g., + even though a print book has text content it is considered to have a visual access mode because you + have to be able to see the ink on the page).

+ +

Text character data can be rendered and manipulated in a variety of ways to accommodate different user + needs — visually for sighted readers and readers with low vision, as synthetic speech for readers + who are blind, etc. This characteristic makes it the most flexible mode of access.

+ +

Note that not all text content necessitates setting a textual access mode. Publishers often include + text content that is not directly related to the content (i.e., is not part of the work created by + the author) or that is not considered essential for reading the work.

+ +

Examples of non-essential text content include:

+ +
    +
  • the title page, if the title and author are available through the publication + metadata.
    • +
  • the title page verso information about the publisher, copyright dates, etc. are + not critical to reading the text.
    • +
  • author bios
    • +
  • lists of additional or future works by the author or by other authors
    • +
  • marketing blurbs
    • +
  • endorsements
    • +
+ +

If a publication also contains images of text (i.e., where the text is part of the image data), set the + textOnVisual and visual + access modes. If a publication only consists of images of text (e.g., comics and manga) a + textual access mode is not set.

+ +

If an image format allows the text content to be retained in text form (e.g., SVG), a + textual access mode is specified in addition to visual (assuming there + is more to the image to understand it than just the text). The textOnVisual value is + not set because it is possible for reading systems and assistive technologies to access and read + aloud the text content for users.

+ +

The textual value is also sometimes paired with colorDependent if color perception is the only way + to differentiate information (e.g., colored text to differentiate different learning levels or + related topics).

+ +

A textual access mode is common in publications produced using the EPUB format, + but is less common for audiobooks. It is only potentially relevent when an audiobook also contains + supplementary material beyond the audio.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">textual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="textual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "textual"]
+
+
+ +
+

ONIX Mapping

+ +

The textual value most commonly maps to list 81 + code 10. It can map to other values + such as code 16 for text that is not part + of the main content

+
+ +
+

Related Links

+ + +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessMode/visual.html b/publishing/docs/metadata/schema.org/accessMode/visual.html new file mode 100644 index 00000000..b46a0c19 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessMode/visual.html @@ -0,0 +1,93 @@ + + + + + visual + + + + + + + +
+
+

Explanation

+ +

The visual access mode value is used to indicate that a publication contains visual + content such as images, grapics and video, or that it requires visual perception to fully + access information (e.g., the ability to perceive background or border colors, or to read + text that is encoded in images).

+ +

This value is not set if the visual content does not contain any information necessary to + understanding the content (e.g., logos, cover artwork, and visual flair at the start of + chapters).

+ +

A visual access mode is common in publications produced using the EPUB format, + but is less common for audiobooks. It is only potentially relevant when an audiobook also contains + supplementary material beyond the audio.

+ +

The visual value should always be set when using any of the visual content + indicators — chartOnVisual, + chemOnVisual, + diagramOnVisual, + mathOnVisual, + musicOnVisual, and + textOnVisual. It is also set with + colorDependent when the color requirement + is in the visual content (as opposed to, say, colored textual content).

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessMode">visual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessMode" content="visual"/>
+
+ +
+
+
Example 3 — Audiobooks
+
+ 
"accessMode": ["auditory", "visual"]
+
+
+ +
+

ONIX Mapping

+ +

The visual value maps to multiple codes in list 81. Some common examples include + code 07 for still images and graphics, + code 28 for video, and + code 44 for comics and manga.

+
+ +
+

Related Links

+ +
    +
  • Schema.org — accessMode
    • +
  • Schema.org Accessibility Vocabulary — visual
    • +
+
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/auditory.html b/publishing/docs/metadata/schema.org/accessModeSufficient/auditory.html new file mode 100644 index 00000000..b03c34e1 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessModeSufficient/auditory.html @@ -0,0 +1,106 @@ + + + + + accessModeSufficient + + + + + + + +
+
+

Definition

+ +

A list of single or combined access modes that are sufficient to understand all the + intellectual content of a resource.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessModeSufficient">textual,visual</meta>
+<meta property="schema:accessModeSufficient">textual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessModeSufficient" content="textual,visual"/>
+<meta name="schema:accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 3 — HTML with RDFa
+
+ 
<meta property="accessModeSufficient" content="textual,visual"/>
+<meta property="accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 4 — HTML with microdata
+
+ 
<meta itemprop="accessModeSufficient" content="textual,visual"/>
+<meta itemprop="accessModeSufficient" content="textual"/>
+
+
+ +
+

Values

+ +

The property takes one or more of the following values:

+ +
    +
  • auditory
    • +
  • tactile
    • +
  • textual
    • +
  • visual
    • +
+ +

The meaning of these values is the same as their definitions for access + modes, but sufficient access modes identify the different combinations of senses that can be + used to sufficiently consume the content, not just the raw access modes of the content itself.

+ +

A publication with images and text, for example, will require both visual and textual modes to be + consumed. If the images are also adequately described (alt text and extended descriptions, as + appropriate) a single textual mode would also be sufficient, indicating someone who is blind can + consume the content.

+ +
+

Note

+

Unless the metadata format used supports lists of lists (e.g., JSON-LD), use a separate property + declaration for each list of sufficient access modes. Separate the values with commas.

+
+
+ +
+

Related Links

+ +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/tactile.html b/publishing/docs/metadata/schema.org/accessModeSufficient/tactile.html new file mode 100644 index 00000000..b03c34e1 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessModeSufficient/tactile.html @@ -0,0 +1,106 @@ + + + + + accessModeSufficient + + + + + + + +
+
+

Definition

+ +

A list of single or combined access modes that are sufficient to understand all the + intellectual content of a resource.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessModeSufficient">textual,visual</meta>
+<meta property="schema:accessModeSufficient">textual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessModeSufficient" content="textual,visual"/>
+<meta name="schema:accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 3 — HTML with RDFa
+
+ 
<meta property="accessModeSufficient" content="textual,visual"/>
+<meta property="accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 4 — HTML with microdata
+
+ 
<meta itemprop="accessModeSufficient" content="textual,visual"/>
+<meta itemprop="accessModeSufficient" content="textual"/>
+
+
+ +
+

Values

+ +

The property takes one or more of the following values:

+ +
    +
  • auditory
    • +
  • tactile
    • +
  • textual
    • +
  • visual
    • +
+ +

The meaning of these values is the same as their definitions for access + modes, but sufficient access modes identify the different combinations of senses that can be + used to sufficiently consume the content, not just the raw access modes of the content itself.

+ +

A publication with images and text, for example, will require both visual and textual modes to be + consumed. If the images are also adequately described (alt text and extended descriptions, as + appropriate) a single textual mode would also be sufficient, indicating someone who is blind can + consume the content.

+ +
+

Note

+

Unless the metadata format used supports lists of lists (e.g., JSON-LD), use a separate property + declaration for each list of sufficient access modes. Separate the values with commas.

+
+
+ +
+

Related Links

+ +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html b/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html new file mode 100644 index 00000000..b03c34e1 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html @@ -0,0 +1,106 @@ + + + + + accessModeSufficient + + + + + + + +
+
+

Definition

+ +

A list of single or combined access modes that are sufficient to understand all the + intellectual content of a resource.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessModeSufficient">textual,visual</meta>
+<meta property="schema:accessModeSufficient">textual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessModeSufficient" content="textual,visual"/>
+<meta name="schema:accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 3 — HTML with RDFa
+
+ 
<meta property="accessModeSufficient" content="textual,visual"/>
+<meta property="accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 4 — HTML with microdata
+
+ 
<meta itemprop="accessModeSufficient" content="textual,visual"/>
+<meta itemprop="accessModeSufficient" content="textual"/>
+
+
+ +
+

Values

+ +

The property takes one or more of the following values:

+ +
    +
  • auditory
    • +
  • tactile
    • +
  • textual
    • +
  • visual
    • +
+ +

The meaning of these values is the same as their definitions for access + modes, but sufficient access modes identify the different combinations of senses that can be + used to sufficiently consume the content, not just the raw access modes of the content itself.

+ +

A publication with images and text, for example, will require both visual and textual modes to be + consumed. If the images are also adequately described (alt text and extended descriptions, as + appropriate) a single textual mode would also be sufficient, indicating someone who is blind can + consume the content.

+ +
+

Note

+

Unless the metadata format used supports lists of lists (e.g., JSON-LD), use a separate property + declaration for each list of sufficient access modes. Separate the values with commas.

+
+
+ +
+

Related Links

+ +
+
+ + diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/visual.html b/publishing/docs/metadata/schema.org/accessModeSufficient/visual.html new file mode 100644 index 00000000..b03c34e1 --- /dev/null +++ b/publishing/docs/metadata/schema.org/accessModeSufficient/visual.html @@ -0,0 +1,106 @@ + + + + + accessModeSufficient + + + + + + + +
+
+

Definition

+ +

A list of single or combined access modes that are sufficient to understand all the + intellectual content of a resource.

+
+ +
+

Examples

+ +
+
+
Example 1 — EPUB 3
+
+ 
<meta property="schema:accessModeSufficient">textual,visual</meta>
+<meta property="schema:accessModeSufficient">textual</meta>
+
+ +
+
+
Example 2 — EPUB 2
+
+ 
<meta name="schema:accessModeSufficient" content="textual,visual"/>
+<meta name="schema:accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 3 — HTML with RDFa
+
+ 
<meta property="accessModeSufficient" content="textual,visual"/>
+<meta property="accessModeSufficient" content="textual"/>
+
+ +
+
+
Example 4 — HTML with microdata
+
+ 
<meta itemprop="accessModeSufficient" content="textual,visual"/>
+<meta itemprop="accessModeSufficient" content="textual"/>
+
+
+ +
+

Values

+ +

The property takes one or more of the following values:

+ +
    +
  • auditory
    • +
  • tactile
    • +
  • textual
    • +
  • visual
    • +
+ +

The meaning of these values is the same as their definitions for access + modes, but sufficient access modes identify the different combinations of senses that can be + used to sufficiently consume the content, not just the raw access modes of the content itself.

+ +

A publication with images and text, for example, will require both visual and textual modes to be + consumed. If the images are also adequately described (alt text and extended descriptions, as + appropriate) a single textual mode would also be sufficient, indicating someone who is blind can + consume the content.

+ +
+

Note

+

Unless the metadata format used supports lists of lists (e.g., JSON-LD), use a separate property + declaration for each list of sufficient access modes. Separate the values with commas.

+
+
+ +
+

Related Links

+ +
+
+ + From 4791e1955b81c5724f58bb924901aa0b6dfac27f Mon Sep 17 00:00:00 2001 From: Matt Garrish Date: Wed, 10 Sep 2025 10:34:37 -0400 Subject: [PATCH 04/19] fix mis-merge --- publishing/docs/tutorials.html | 52 ------ publishing/docs/tutorials/index.html | 32 ---- publishing/docs/tutorials/language.html | 210 ------------------------ 3 files changed, 294 deletions(-) delete mode 100644 publishing/docs/tutorials.html delete mode 100644 publishing/docs/tutorials/index.html delete mode 100644 publishing/docs/tutorials/language.html diff --git a/publishing/docs/tutorials.html b/publishing/docs/tutorials.html deleted file mode 100644 index 89957cce..00000000 --- a/publishing/docs/tutorials.html +++ /dev/null @@ -1,52 +0,0 @@ - - - - - Tutorials - - - - - - - - -
- -
- - diff --git a/publishing/docs/tutorials/index.html b/publishing/docs/tutorials/index.html deleted file mode 100644 index 3e4b747f..00000000 --- a/publishing/docs/tutorials/index.html +++ /dev/null @@ -1,32 +0,0 @@ - - - - - Tutorials - - - - - - - - -
-
- - diff --git a/publishing/docs/tutorials/language.html b/publishing/docs/tutorials/language.html deleted file mode 100644 index 82b50d5c..00000000 --- a/publishing/docs/tutorials/language.html +++ /dev/null @@ -1,210 +0,0 @@ - - - - - Setting the language in EPUB publications - - - - - - - -
-
-

Introduction

- -

Setting the language of a publication is an important step in ensuring its accessibility as it helps - assistive technologies pronounce the text correctly. Without language declarations, assistive - technologies will read the text in the default language of the user. This can lead to the entire - text being mispronounced (when reading a publication in another language) or individual phrases - being mangled (for inline foreign phrases).

- -

This tutorial covers how to set the language in the EPUB package document as well as - in XHTML content documents so that the information is available to assistive technologies - and reading systems.

-
- -
-

What are language tags

- -

Before we can get into the mechanisms for setting the language, it is important to first understand - what you are setting. Languages are declared using language tags, which are hyphen-separated - codes that identify the language, region, script, etc.

- -

At a minimum, each language tag consists of a primary language, which is a two- or three-character code - that identifies the language.

- -

The following table lists some common language codes:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CodeLanguage
deGerman
enEnglish
heHebrew
hiHindi
koKorean
- -

For the complete list of language codes, refer to the IANA - language registry (search for the language's name to find its code).

- -

For many languages, all that you have to specify is the primary language code. For others with - regional dialects, however, you can add an additional region subtag for more precision.

- -

American and British pronounciations, for example, can differ significantly, but a code of - "en" will not inform an assistive technology which to apply when it matters (e.g., - when reading an American or British novel where the characters talk in regional dialects). Adding - the region solves this problem as it allows the assistive technology to pick a more appropriate - voice for playback.

- -

The region subtag is added to the language using a hypen. For example, "en-US" indicates that - the text is in English as spoken in the US.

- -

The following table lists some common language tags with their region subtags:

- - - - - - - - - - - - - - - - - - - - - - - - - - -
CodeLanguage
en-GBBritish English
en-USUS English
fr-CAFrench as spoken in Canada
en-FRFrench as spoken in France
- -

Note that although it is common convention to capitalize region tags, this is not a requirement. - Language tags are processed case-insensitively.

- -

It is not necessary to use region codes for metadata such as that found in the EPUB package document. This information is rarely region-specific - and users will typically expect to hear it announced in their preferred regional dialect.

- -

You can also specify the script the text is written in using a script subtag. Simplified and - traditional Chinese, for example, can be differentiated using the "zh-Hans" and "zh-Hant" script - tags. You should only use script subtags when a language is commonly written in more than one - script.

- -

For a more in-depth explanation of language tags, refer to the W3C article Language tags in HTML and - XML.

-
- -
-

Language declaration mechanisms

- -

With an understanding now of what language tags are, it is time to turn to how to express those tags - in markup languages. - -

In XML-based markup languages, like XHTML, SVG and the EPUB package document, the standard mechanism - for declaring the language of the text is the xml:lang attribute, where the value of - this attribute is a language tag.

- -

Best practice is to always declare a language on the root element (i.e., the element that contains - all the other markup). For example, the language of an XHTML document can be specified as follows:

- - 
<html … xml:lang="en-US">
-   …
-</html>
- -

Language information is inherited, so by setting the attribute on the root element you automatically - declare language information for all the elements and text in the document.

- -
-

Note on HTML

- -

Although it is only required to use the xml:lang attribute with XHTML documents, it - is best practice to also add a lang attribute. When doing so, the language tag - expressed in the xml:lang and lang attributes must match. For - example:

- - 
<html … xml:lang="en-US" lang="en-US">
- -

The reason why it is recommended to add both attributes is that the XHTML documents in EPUB - publications may not always be processed as XML, despite the requirements of the standard. A - browser-based reading system might, for example, default to processing all the XHTML documents - as regular HTML. In this case, the xml:lang attribute is ignored, as HTML - processors only recognize the lang attribute. By always adding both attributes, - you help ensure that the correct language information is available to users regardless of how - the document is processed.

-
-
- -
-

Overriding the language

-
- -
-

Setting the publication language

- -

The language of an EPUB publication is set in a dc:language element in the package - document.

-
- -
-

Setting the package document language

- -

Setting the language of an EPUB publication does not set the language of the - metadata in the package document. It is also required to specify the language of the metadata - using xml:lang attributes.

-
- -
-

Setting the content language

-
- -
-

Related Links

- -
-
- - From 9d72eb10d236d96804a37259adf039fd4cb2f42a Mon Sep 17 00:00:00 2001 From: Matt Garrish Date: Tue, 16 Sep 2025 21:15:54 -0400 Subject: [PATCH 05/19] access modes and sufficient --- .../docs/metadata/schema.org/accessMode.html | 4 +- .../schema.org/accessMode/colorDependent.html | 20 +-- .../schema.org/accessMode/textual.html | 17 --- .../schema.org/accessModeSufficient.html | 8 +- .../accessModeSufficient/auditory.html | 79 ++++------- .../accessModeSufficient/tactile.html | 73 +++------- .../accessModeSufficient/textual.html | 127 ++++++++++-------- .../accessModeSufficient/visual.html | 122 +++++++++-------- 8 files changed, 206 insertions(+), 244 deletions(-) diff --git a/publishing/docs/metadata/schema.org/accessMode.html b/publishing/docs/metadata/schema.org/accessMode.html index db7da43f..6e47a604 100644 --- a/publishing/docs/metadata/schema.org/accessMode.html +++ b/publishing/docs/metadata/schema.org/accessMode.html @@ -95,8 +95,8 @@

Values

  • visual
    • -

    The following values are also often paired with a visual access mode to provide additional - information about the type of content in visual form:

    +

    The following values are also often paired with a visual access mode + to provide additional information about the type of content in visual form:

    - -
    -

    Values

    - -

    The property takes one or more of the following values:

    - -
      -
    • auditory
      • -
    • tactile
      • -
    • textual
      • -
    • visual
      • -
    - -

    The meaning of these values is the same as their definitions for access - modes, but sufficient access modes identify the different combinations of senses that can be - used to sufficiently consume the content, not just the raw access modes of the content itself.

    - -

    A publication with images and text, for example, will require both visual and textual modes to be - consumed. If the images are also adequately described (alt text and extended descriptions, as - appropriate) a single textual mode would also be sufficient, indicating someone who is blind can - consume the content.

    + +
    +

    ONIX Mapping

    -
    -

    Note

    -

    Unless the metadata format used supports lists of lists (e.g., JSON-LD), use a separate property - declaration for each list of sufficient access modes. Separate the values with commas.

    -
    +

    The tactile value most commonly maps to list 81 + code 10. It can map to other values + such as code 16 for text that is not part + of the main content

    - +

    Related Links

    diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html b/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html index b03c34e1..4973af91 100644 --- a/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html +++ b/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html @@ -2,13 +2,13 @@ - accessModeSufficient + textual - + @@ -16,13 +16,56 @@
    -
    -

    Definition

    - -

    A list of single or combined access modes that are sufficient to understand all the - intellectual content of a resource.

    +
    +

    Explanation

    + +

    The textual sufficient access mode value is used to indicate that a publication can be + read, in whole or in part, if the user has a device that can present text character data in a form + they can read. This could be as visual text for sighted readers, or as text-to-speech playback or + refreshable braille for non-visual readers.

    + +

    Any accessibility affordances provided by the author are considered when determining when to specify + a single textual sufficient access is available. For example, a publication might have + textual and visual + access modes if it contains a combination of text and images, but the publisher can state that + there is a single sufficient textual means of reading the content if the images all have + alternative text and/or extended descriptions that fully convey their meaning.

    + + + +

    Although a single textual sufficient access mode is generally the most important for users to + be aware of, because it allows the content to be read in a variety of different ways, always include + any other combinations of sufficient access modes that include textual content, especially if the + access modes are not listed.

    + +

    For example, an EPUB 3 publication with both textual and visual content that also has a single + textual access mode would list the following possibilities:

    + + 
    <meta property="schema:accessModeSufficient">textual, visual</meta>
+<meta property="schema:accessModeSufficient">textual</meta>
+
    + +

    A single textual sufficient access mode is common in accessible publications produced + using the EPUB format, but would never apply to an audiobook.

    - +

    Examples

    @@ -42,63 +85,37 @@

    Examples

    <meta name="schema:accessModeSufficient" content="textual"/> -
    +
    -
    Example 3 — HTML with RDFa
    +
    Example 3 — Audiobooks
    - 
    <meta property="accessModeSufficient" content="textual,visual"/>
-<meta property="accessModeSufficient" content="textual"/>
    -
    - -
    -
    -
    Example 4 — HTML with microdata
    -
    - 
    <meta itemprop="accessModeSufficient" content="textual,visual"/>
-<meta itemprop="accessModeSufficient" content="textual"/>
    + 
    "accessModeSufficient": [
+   {
+      "type": "ItemList",
+      "itemListElement": ["auditory", "textual"],
+      "description": "Audio and text"
+   }
+]
    - -
    -

    Values

    - -

    The property takes one or more of the following values:

    - -
      -
    • auditory
      • -
    • tactile
      • -
    • textual
      • -
    • visual
      • -
    - -

    The meaning of these values is the same as their definitions for access - modes, but sufficient access modes identify the different combinations of senses that can be - used to sufficiently consume the content, not just the raw access modes of the content itself.

    - -

    A publication with images and text, for example, will require both visual and textual modes to be - consumed. If the images are also adequately described (alt text and extended descriptions, as - appropriate) a single textual mode would also be sufficient, indicating someone who is blind can - consume the content.

    + +
    +

    ONIX Mapping

    -
    -

    Note

    -

    Unless the metadata format used supports lists of lists (e.g., JSON-LD), use a separate property - declaration for each list of sufficient access modes. Separate the values with commas.

    -
    +

    The textual value most commonly maps to list 81 + code 10. It can map to other values + such as code 16 for text that is not part + of the main content

    - +

    Related Links

    diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/visual.html b/publishing/docs/metadata/schema.org/accessModeSufficient/visual.html index b03c34e1..1b83f086 100644 --- a/publishing/docs/metadata/schema.org/accessModeSufficient/visual.html +++ b/publishing/docs/metadata/schema.org/accessModeSufficient/visual.html @@ -2,13 +2,13 @@ - accessModeSufficient + visual - + @@ -16,11 +16,53 @@
    -
    -

    Definition

    +
    +

    Explanation

    -

    A list of single or combined access modes that are sufficient to understand all the - intellectual content of a resource.

    +

    The visual sufficient access mode value is used to indicate that a publication can be + read, in whole or in part, if the user is able to visually perceive the content. It mostly commonly + indicates that a publication contains images and/or videos.

    + +

    If only a single visual sufficient access mode is set, it indicates that only sighted readers will + be able to read the content (i.e., the content is not universally accessible). Examples of publications + with only a single visual sufficient access mode include comics, manga, and photo books.

    + +

    When combined with other values, a visual sufficient access mode indicates that some essential + content is only readable in visual form. It is most common to find the visual value + paired with textual as one means of reading the content, + with a single textual value to indicate that there are affordances that allow all + the visual content to also be read textually. Any book that is predominantly text-based but + includes images, video, interactive games, or other visual content will have both these values + set.

    + +

    For example, an EPUB 3 publication with both textual and visual content that also has a single + textual access mode would list the following possibilities:

    + + 
    <meta property="schema:accessModeSufficient">textual, visual</meta>
+<meta property="schema:accessModeSufficient">textual</meta>
+
    + +

    A single visual sufficient access mode is common in accessible publications produced + using the EPUB format, but would never apply to an audiobook.

    + +

    Note that the visual content indicators + that can be specified as access modes are never listed as sufficient access modes. Only the + visual value is specified, as this value should always be paired with the content + indicators.

    + +
    +

    Note

    +

    An edge case can arise with the colorDependent indicator when it is + used to specify that textual styling may not be accessible only to users who are color blind (e.g., + hyperlinks may not be perceivable). Such publications are not accessible as they will fail WCAG + success criterion 1.4.1, but they typically + still provide a sufficient textual access mode for non-visual readers.

    + +

    When the color perception issue is limited only to visual reading, indicate the problem in an accessibility summary and specify that there is single + textual sufficient access mode in addition to a visual and textual one.

    +
    @@ -42,63 +84,37 @@

    Examples

    <meta name="schema:accessModeSufficient" content="textual"/> -
    +
    -
    Example 3 — HTML with RDFa
    +
    Example 3 — Audiobooks
    - 
    <meta property="accessModeSufficient" content="textual,visual"/>
-<meta property="accessModeSufficient" content="textual"/>
    -
    - -
    -
    -
    Example 4 — HTML with microdata
    -
    - 
    <meta itemprop="accessModeSufficient" content="textual,visual"/>
-<meta itemprop="accessModeSufficient" content="textual"/>
    + 
    "accessModeSufficient": [
+   {
+      "type": "ItemList",
+      "itemListElement": ["auditory", "visual"],
+      "description": "Audio and images"
+   }
+]
    - -
    -

    Values

    - -

    The property takes one or more of the following values:

    - -
      -
    • auditory
      • -
    • tactile
      • -
    • textual
      • -
    • visual
      • -
    - -

    The meaning of these values is the same as their definitions for access - modes, but sufficient access modes identify the different combinations of senses that can be - used to sufficiently consume the content, not just the raw access modes of the content itself.

    - -

    A publication with images and text, for example, will require both visual and textual modes to be - consumed. If the images are also adequately described (alt text and extended descriptions, as - appropriate) a single textual mode would also be sufficient, indicating someone who is blind can - consume the content.

    + +
    +

    ONIX Mapping

    -
    -

    Note

    -

    Unless the metadata format used supports lists of lists (e.g., JSON-LD), use a separate property - declaration for each list of sufficient access modes. Separate the values with commas.

    -
    +

    The textual value most commonly maps to list 81 + code 10. It can map to other values + such as code 16 for text that is not part + of the main content

    - +

    Related Links

    From 487869a27f5c292b44ddd4d6d5da57bacd30dbcc Mon Sep 17 00:00:00 2001 From: Matt Garrish Date: Fri, 19 Sep 2025 08:31:23 -0400 Subject: [PATCH 06/19] fix ja feed path --- publishing/ja/new/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/publishing/ja/new/index.html b/publishing/ja/new/index.html index 29e3dad0..150d5cfe 100644 --- a/publishing/ja/new/index.html +++ b/publishing/ja/new/index.html @@ -43,7 +43,7 @@ req.addEventListener("load", loadUpdates); req.addEventListener("error", showError); req.addEventListener("abort", showError); - req.open("GET", "/publishing/docs/new/feed.xml"); + req.open("GET", "/publishing/ja/new/feed.xml"); req.send(); req.onloadend = function() { From 50972b3a53d044fc50defb1e0f47270ff2a95997 Mon Sep 17 00:00:00 2001 From: Matt Garrish Date: Fri, 19 Sep 2025 11:05:03 -0400 Subject: [PATCH 07/19] finish ams section --- .../schema.org/accessMode/auditory.html | 20 ++++++---- .../schema.org/accessModeSufficient.html | 4 +- .../accessModeSufficient/auditory.html | 37 +++++++++++-------- .../accessModeSufficient/tactile.html | 25 +++++++------ .../accessModeSufficient/textual.html | 9 ++--- .../accessModeSufficient/visual.html | 6 +-- 6 files changed, 55 insertions(+), 46 deletions(-) diff --git a/publishing/docs/metadata/schema.org/accessMode/auditory.html b/publishing/docs/metadata/schema.org/accessMode/auditory.html index 9bf42880..12b9bc90 100644 --- a/publishing/docs/metadata/schema.org/accessMode/auditory.html +++ b/publishing/docs/metadata/schema.org/accessMode/auditory.html @@ -26,6 +26,19 @@

    Explanation

    The auditory value does not have to be set if the audio does not include information necessary to understand the content (e.g., background noises in an interactive game or mood music).

    + +

    Auditory content added using EPUB 3's media overlays feature is not considered an auditory + access mode unless the auditory content is the only way to read the entire publication.

    + +

    For example, a mainstream publisher will typically add a media overlay to the full text of a + novel. In this case, the work would only have a textual access mode. + An accessible content republisher, on the other hand, might publish the same work with only + the chapter headings as text and all the content of the book synchronized to those headings + as audio (to allow users who are blind to move through the audio by heading). In this case, + the work would only have an auditory access mode.

    + +

    Note that it is not possible for EPUB 2 publications to have an auditory access mode as the format + does not support embedding audio or have an equivalent to EPUB 3's media overlays.

    @@ -38,13 +51,6 @@

    Examples

    <meta property="schema:accessMode">auditory</meta>
    -
    -
    -
    Example 2 — EPUB 2
    -
    - 
    <meta name="schema:accessMode" content="auditory"/>
    -
    -
    Example 3 — Audiobooks
    diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient.html b/publishing/docs/metadata/schema.org/accessModeSufficient.html index 6e8b7926..de019c57 100644 --- a/publishing/docs/metadata/schema.org/accessModeSufficient.html +++ b/publishing/docs/metadata/schema.org/accessModeSufficient.html @@ -73,7 +73,9 @@

    Values

    The meaning of these values is the same as their definitions for access modes, but sufficient access modes identify the different combinations of senses that can be - used to sufficiently consume the content, not just the raw access modes of the content itself.

    + used to sufficiently consume the content, not just the raw access modes of the content itself. + They also take into consideration any accessibility affordances, such alternative text and + extended descriptions, provided by the publisher.

    A publication with images and text, for example, will require both visual and textual modes to be consumed. If the images are also adequately described (alt text and extended descriptions, as diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/auditory.html b/publishing/docs/metadata/schema.org/accessModeSufficient/auditory.html index 0fb44428..870036eb 100644 --- a/publishing/docs/metadata/schema.org/accessModeSufficient/auditory.html +++ b/publishing/docs/metadata/schema.org/accessModeSufficient/auditory.html @@ -19,7 +19,24 @@

    Explanation

    -

    +

    The auditory sufficient access mode value is used to indicate that a publication can be + read, in whole or in part, if a user is able to perceive sound.

    + +

    A single auditory sufficient access mode is, by design, most commonly associated with + audiobooks, but it is also possible for formats like EPUB 3 that provide text and audio + synchronization for an entire work to have a solitary auditory sufficient access mode. + This is because sufficient access modes take into account any accessibility affordances + provided by the publisher.

    + +

    Note, however, that unlike an auditory access mode, + an auditory sufficient access mode is always specified when media overlays are used in an EPUB 3 + file to include the full audio of the publication.

    + +

    The auditory value is more commonly found in combination with textual + for works that include auditory clips, whether standalone or when the audio is part of a video.

    + +

    Note that it is not possible for EPUB 2 publications to have an auditory access mode as the format + does not support embedding audio or have an equivalent to EPUB 3's media overlays.

    @@ -29,18 +46,10 @@

    Examples

    Example 1 — EPUB 3
    - 
    <meta property="schema:accessModeSufficient">textual,visual</meta>
-<meta property="schema:accessModeSufficient">textual</meta>
    + 
    <meta property="schema:accessModeSufficient">textual</meta>
+<meta property="schema:accessModeSufficient">auditory</meta>
    -
    -
    -
    Example 2 — EPUB 2
    -
    - 
    <meta name="schema:accessModeSufficient" content="textual,visual"/>
-<meta name="schema:accessModeSufficient" content="textual"/>
    -
    -
    Example 3 — Audiobooks
    @@ -58,11 +67,7 @@

    Examples

    ONIX Mapping

    -

    The textual value most commonly maps to list 81 - code 10. It can map to other values - such as code 16 for text that is not part - of the main content

    +

    ONIX currently does not include a means of expressing sufficient access modes.

    diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/tactile.html b/publishing/docs/metadata/schema.org/accessModeSufficient/tactile.html index 53f4fa3b..d4a3aec1 100644 --- a/publishing/docs/metadata/schema.org/accessModeSufficient/tactile.html +++ b/publishing/docs/metadata/schema.org/accessModeSufficient/tactile.html @@ -17,10 +17,17 @@
    -

    Definition

    +

    Explanation

    -

    A list of single or combined access modes that are sufficient to understand all the - intellectual content of a resource.

    +

    The tactile sufficient access mode value is used to indicate that a publication can be + read, in whole or in part, if a user is able to perceive content through touch.

    + +

    A single tactile sufficient access mode is most commonly associated with braille publications, + such as can be produced using the eBraille format (an specialization of EPUB 3 for braille). + EPUB publications can also entirely consist of braille content although this is not common.

    + +

    A tactile sufficient access mode is sometimes found paired with another access mode. For example, + an audiobook for blind users might also include tactile graphics.

    @@ -30,16 +37,14 @@

    Examples

    Example 1 — EPUB 3
    - 
    <meta property="schema:accessModeSufficient">textual,visual</meta>
-<meta property="schema:accessModeSufficient">textual</meta>
    + 
    <meta property="schema:accessModeSufficient">tactile</meta>
    Example 2 — EPUB 2
    - 
    <meta name="schema:accessModeSufficient" content="textual,visual"/>
-<meta name="schema:accessModeSufficient" content="textual"/>
    + 
    <meta name="schema:accessModeSufficient" content="tactile"/>
    "accessModeSufficient": [
@@ -54,11 +59,7 @@ 
    Examples
    
 			
    
 				
    ONIX Mapping
    
 				
-				
    The tactile value most commonly maps to list 81
-					code 10. It can map to other values
-					such as code 16 for text that is not part
-					of the main content
    
+				
    ONIX currently does not include a means of expressing sufficient access modes.
    
 			
    
 			
 			
    
diff --git a/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html b/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html
index 4973af91..e8969324 100644
--- a/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html
+++ b/publishing/docs/metadata/schema.org/accessModeSufficient/textual.html
@@ -31,6 +31,9 @@ 
    Explanation
    
 					there is a single sufficient textual means of reading the content if the images all have
 					alternative text and/or extended descriptions that fully convey their meaning.
    
 				
+				
    Similarly, text equivalents, like transcripts, provided for auditory content are considered when
+					determining if a publication can be read in full using only text character data.
    
+