From 6a9213e580dd904b9d34259bc5a00a7e8c58175c Mon Sep 17 00:00:00 2001 From: Norman Walsh Date: Sun, 26 Jul 2020 16:09:52 +0100 Subject: [PATCH 1/7] Rework annotations to improve accessibility, close #41 --- src/guide/xml/ref-functions.xml | 27 ------ src/guide/xml/ref-params.xml | 83 +++++++------------ .../web/css/docbook-annotations-inline.css | 43 ---------- ...javascript.css => docbook-annotations.css} | 58 +++++++++---- src/main/web/js/annotations.js | 43 ++++++++++ src/main/xslt/main.xsl | 3 +- src/main/xslt/modules/annotations.xsl | 16 ---- src/main/xslt/modules/chunk-cleanup.xsl | 9 +- src/main/xslt/modules/head.xsl | 10 +-- src/main/xslt/param.xsl | 8 +- .../resources/expected/annotations.001.html | 6 +- .../resources/expected/annotations.002.html | 4 +- .../resources/expected/annotations.003.html | 4 +- .../resources/expected/annotations.004.html | 4 +- src/test/resources/expected/book.007.html | 4 +- src/test/resources/expected/fit.001.html | 4 +- 16 files changed, 141 insertions(+), 185 deletions(-) delete mode 100644 src/main/web/css/docbook-annotations-inline.css rename src/main/web/css/{docbook-annotations-javascript.css => docbook-annotations.css} (57%) diff --git a/src/guide/xml/ref-functions.xml b/src/guide/xml/ref-functions.xml index 5eb2e2506..58606f755 100644 --- a/src/guide/xml/ref-functions.xml +++ b/src/guide/xml/ref-functions.xml @@ -31,33 +31,6 @@ of pixels. For a discussion of units, see . - - - -f:annotation-style -{http://docbook.org/ns/docbook/functions}annotation-style#1 - - -f:annotation-style -Returns the annotation style for this document -function - - -Description -The default annotation style is defined by the -annotations parameter. An individual document may -override that style by specifying a -dbdb processing instruction - processing instruction with a -annotations -db processing instruction -annotations pseudo-attribute - pseudo-attribute in the info element at the -beginning of the document. -Annotation styles cannot vary across a single document. - - - diff --git a/src/guide/xml/ref-params.xml b/src/guide/xml/ref-params.xml index 576093734..5921e4e89 100644 --- a/src/guide/xml/ref-params.xml +++ b/src/guide/xml/ref-params.xml @@ -255,82 +255,63 @@ be ignored. When annotations are rendered, the annotation-mark is inserted at each location where an annotation occurs. -If JavaScript is used for annotations (see annotations), +If JavaScript is used for annotations (see annotation-style), clicking on the mark will bring up the annotation; if JavaScript is not used, the marks are numbered and the annotations appear as a form of footnote. - - + + -$annotations -{}annotations +$annotation-style +{}annotation-style -$annotations +$annotation-style Selects the annotation style param Description -An annotation can be used to add annotations -to arbitrary elements. When formatted, these can be presented in one -of two ways: - -javascript - -If “javascript” is selected, markers are introduced -at each point where an annotation occurs. Clicking on the marker will reveal -the annotation. Obviously, this requires a user-agent with JavaScript. +An annotation can be used to add annotations to +arbitrary elements. Annotations are formatted something like +footnotes, they appear at the bottom of the page and are linked from +the point of the annotation. There are two annotation styles, +“javascript” and “inline”. -The roles “wide” and “tall” can be used -to increase the size of a particular annotation when it’s popped up. - - -inline - -The “inline” rendering places the annotation text -near each reference and numbers them, something like footnotes. - - - - - - - - -$annotations-inline-css -{}annotations-inline-css - - -$annotations-inline-css -Inline annotation CSS -param - - -Description -If inline annotations appear in the document, a link to this -CSS file will be added to the HTML HEAD. +If the annotation style is “javascript”, a +script reference will be added. The script hides the annotations at the +bottom of the page and instead renders them as modal dialogs when the +marks are clicked. The presentation is accessible in the absence of +JavaScript. + +If the annotation style is “inline”, then the +script is not included and the default presentation is used. No other values +are supported at this time. - - + + -$annotations-javascript-css -{}annotations-javascript-css +$annotations-css +{}annotations-css -$annotations-javascript-css -Javascript annotation CSS +$annotations-css +Annotation CSS param Description -If popup (JavaScript) annotations appear in the document, a link to this -CSS file will be added to the HTML HEAD. +This CSS stylesheet is added to documents that contain annotations. +The selectors that match “popup-” classes are enabled by the annotation JavaScript +if that style of annotation is selected. +The CSS file will be added to the HTML +head. + diff --git a/src/main/web/css/docbook-annotations-inline.css b/src/main/web/css/docbook-annotations-inline.css deleted file mode 100644 index 21b5a7a4e..000000000 --- a/src/main/web/css/docbook-annotations-inline.css +++ /dev/null @@ -1,43 +0,0 @@ -/* ============================================================ */ -/* Inline annotations */ - -.annotations { - border-top: 2px dashed #afafaf; - padding-top: 1em; - margin-top: 6em; -} - -a.annomark, -a.annomark:visited { - text-decoration: none; - color: inherit; -} - -.annotation-wrapper { - margin-bottom: 1em; -} - -.annotation-body { - border: 1px solid black; - border-bottom-left-radius: 0.25em; - border-bottom-right-radius: 0.25em;; -} - -.annotation-header { - height: 2em; - background-color: #cfcfcf; - padding-left: 1em; - padding-right: 0.5em; - border-bottom: 1px solid black; -} - -.annotation-header .annotation-close { - float: right; -} - -.annotation-content { - padding-left: 1em; - padding-right: 1em; - padding-top: 0.5em; - padding-bottom: 0.5em; -} diff --git a/src/main/web/css/docbook-annotations-javascript.css b/src/main/web/css/docbook-annotations.css similarity index 57% rename from src/main/web/css/docbook-annotations-javascript.css rename to src/main/web/css/docbook-annotations.css index 8fa95242f..f1833461e 100644 --- a/src/main/web/css/docbook-annotations-javascript.css +++ b/src/main/web/css/docbook-annotations.css @@ -1,21 +1,51 @@ /* ============================================================ */ -/* JavaScript annotations */ +/* Inline annotations */ -.annomark { - cursor: pointer; +.annotations { + border-top: 2px dashed #afafaf; + padding-top: 1em; + margin-top: 6em; } a.annomark, a.annomark:visited { - color: inherit; text-decoration: none; + color: inherit; } -.annomark .num { - display: none; +.annotation-wrapper { + margin-bottom: 1em; } -.annotation-wrapper { +.annotation-body { + border: 1px solid black; + border-bottom-left-radius: 0.25em; + border-bottom-right-radius: 0.25em;; +} + +.annotation-header { + height: 2em; + background-color: #cfcfcf; + padding-left: 1em; + padding-right: 0.5em; + border-bottom: 1px solid black; +} + +.annotation-header .annotation-close { + float: right; +} + +.annotation-content { + padding-left: 1em; + padding-right: 1em; + padding-top: 0.5em; + padding-bottom: 0.5em; +} + +/* ============================================================ */ +/* Javascript annotations */ + +.popup-annotation-wrapper { display: none; position: fixed; left: 0; @@ -25,7 +55,7 @@ a.annomark:visited { background-color: rgb(128, 128, 128, 0.85); } -.annotation-body { +.popup-annotation-body { border: 1px solid black; width: 50%; background-color: white; @@ -40,15 +70,15 @@ a.annomark:visited { grid-template-columns: 100%; } -.wide .annotation-body { +.wide .popup-annotation-body { width: 80%; } -.tall .annotation-body { +.tall .popup-annotation-body { max-height: 80%; } -.annotation-header { +.popup-annotation-header { height: 2em; background-color: #cfcfcf; padding-left: 1em; @@ -56,17 +86,17 @@ a.annomark:visited { border-bottom: 1px solid black; } -.annotation-header .annotation-close { +.popup-annotation-header .annotation-close { float: right; cursor: pointer; font-size: 125%; } -.annotation-header .annotation-title { +.popup-annotation-header .annotation-title { padding-top: 0.1em; } -.annotation-content { +.popup-annotation-content { padding-left: 1em; padding-right: 1em; padding-top: 0.5em; diff --git a/src/main/web/js/annotations.js b/src/main/web/js/annotations.js index 8f796436b..4d1127591 100644 --- a/src/main/web/js/annotations.js +++ b/src/main/web/js/annotations.js @@ -10,6 +10,7 @@ const showAnnotation = function(event, id) { let div = document.querySelector(id); div.style.display = "block"; + enablePopup(div); event.preventDefault(); @@ -27,6 +28,7 @@ const hideAnnotation = function(event, id, curpress) { let div = document.querySelector(id); div.style.display = "none"; + disablePopup(div); if (curpress) { document.onkeyup = curpress; @@ -35,6 +37,40 @@ return true; }; + const enablePopup = function(div) { + togglePopup(div, 'popup-', ''); + }; + + const disablePopup = function(div) { + togglePopup(div, '', 'popup-'); + }; + + const togglePopup = function(div, on, off) { + div.classList.remove(`${off}annotation-wrapper`); + div.classList.add(`${on}annotation-wrapper`); + ["body", "header", "content"].forEach(function(token) { + const find = `.${off}annotation-${token}`; + const addClass = `${on}annotation-${token}`; + const removeClass = `${off}annotation-${token}`; + div.querySelectorAll(find).forEach(function (div) { + div.classList.add(addClass); + div.classList.remove(removeClass); + }); + }); + }; + + // Turn off the display of the individual annotations + document.querySelectorAll("footer .annotations > div").forEach(function(div) { + div.style.display = "none"; + }); + + // Change the class on the annotations block to remove its styling + document.querySelectorAll("footer .annotations").forEach(function(div) { + // Turn off the annotation styling + div.classList.add("popup-annotations"); + div.classList.remove("annotations"); + }); + // The annotation close markup is hidden in a script. This prevents // it from showing up spuriously all over screen readers and other // user agents that don't support JavaScript. Find it and copy it @@ -49,6 +85,7 @@ div.innerHTML = annoClose.innerHTML; }); + // Setup the onclick event for the annotation marks document.querySelectorAll("a.annomark").forEach(function(mark) { let id = mark.getAttribute("href"); // Escape characters that confuse querySelector @@ -58,6 +95,12 @@ }; }); + // Take out the annotation numbers (in the text and the popup titles) + document.querySelectorAll(".annomark sup.num").forEach(function(sup) { + sup.style.display = "none"; + }); + + // If an annotation is displayed, make clicking on the page hide it document.querySelectorAll(".annotation-wrapper").forEach(function(anno) { let id = anno.getAttribute("id"); if (id) { diff --git a/src/main/xslt/main.xsl b/src/main/xslt/main.xsl index a2551e559..992ef5eb2 100644 --- a/src/main/xslt/main.xsl +++ b/src/main/xslt/main.xsl @@ -75,8 +75,7 @@
+ db-xlink="{f:xlink-style(/)}">
diff --git a/src/main/xslt/modules/annotations.xsl b/src/main/xslt/modules/annotations.xsl index 0bcaa041b..eb407db71 100644 --- a/src/main/xslt/modules/annotations.xsl +++ b/src/main/xslt/modules/annotations.xsl @@ -11,18 +11,10 @@ exclude-result-prefixes="db f ghost m v xs" version="3.0"> - - - - - - @@ -36,7 +28,6 @@ @@ -58,13 +49,6 @@ - diff --git a/src/main/xslt/modules/chunk-cleanup.xsl b/src/main/xslt/modules/chunk-cleanup.xsl index ccb93e8bb..f9a51c817 100644 --- a/src/main/xslt/modules/chunk-cleanup.xsl +++ b/src/main/xslt/modules/chunk-cleanup.xsl @@ -152,10 +152,8 @@
- -
The following are annotations used elsewhere.
- +
Annotations
@@ -182,8 +180,7 @@ - + diff --git a/src/main/xslt/modules/head.xsl b/src/main/xslt/modules/head.xsl index b15fe3d43..e7aa0590b 100644 --- a/src/main/xslt/modules/head.xsl +++ b/src/main/xslt/modules/head.xsl @@ -120,14 +120,8 @@ - - - - - - + - + ⌖ @@ -209,10 +209,8 @@ - - + diff --git a/src/test/resources/expected/annotations.001.html b/src/test/resources/expected/annotations.001.html index bad7408e1..cf0955eb0 100644 --- a/src/test/resources/expected/annotations.001.html +++ b/src/test/resources/expected/annotations.001.html @@ -1,10 +1,10 @@ -Article wrapper

Article wrapper

This article tests annotations⌖2. +Article wrapper

Article wrapper

This article tests annotations⌖2. Annotations⌖2 can point in either direction. This paragraph contains annotation⌖2 targets.

This paragraph asserts that it is annotated by the annotation “there”. The annotation “there” contains a great big slab of text to test the behavior of the annotation mechanism when…the annotation -is a great big slab of text.⌖1

⌖2

This annotation pointlessly annotates every occurrence of the word “annotation” +is a great big slab of text.⌖1

Annotations
⌖2

This annotation pointlessly annotates every occurrence of the word “annotation” in the first paragraph of the article.

⌖1 This is an annotation title

Lorem ipsum dolor sit amet, consectetaur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut @@ -69,4 +69,4 @@ apoply tyu cak UCU sisulutiun munityuw uw cak UCU-TGU jot scannow. Trens roxas eis ti Plokeing quert loppe eis yop prexs. Piy opher hawers, eit yaggles orn ti sumbloat alohe plok. Su havo loasor cakso -tgu pwuructs tyu.

\ No newline at end of file +tgu pwuructs tyu.

\ No newline at end of file diff --git a/src/test/resources/expected/annotations.002.html b/src/test/resources/expected/annotations.002.html index 044a7cf72..55888c16c 100644 --- a/src/test/resources/expected/annotations.002.html +++ b/src/test/resources/expected/annotations.002.html @@ -1,10 +1,10 @@ -Article wrapper

Article wrapper

This article tests annotations⌖2. +Article wrapper

Article wrapper

This article tests annotations⌖2. Annotations⌖2 can point in either direction. This paragraph contains annotation⌖2 targets.

This paragraph asserts that it is annotated by the annotation “there”. The annotation “there” contains a great big slab of text to test the behavior of the annotation mechanism when…the annotation -is a great big slab of text.⌖1

The following are annotations used elsewhere.
⌖2

This annotation pointlessly annotates every occurrence of the word “annotation” +is a great big slab of text.⌖1