feat: check reading order of Media Overlays text elements

rdeltour · rdeltour · commit e35bd050ba60 · 2020-12-28T15:32:12.000+01:00
Report new error MED-015 when the order of text elements in a Media Overlay does not match the DOM order of the referenced elements in the corresponding content document(s). Applies PR #1180
diff --git a/src/main/java/com/adobe/epubcheck/messages/DefaultSeverities.java b/src/main/java/com/adobe/epubcheck/messages/DefaultSeverities.java
@@ -151,6 +151,7 @@ private void initialize()
     severities.put(MessageId.MED_012, Severity.ERROR);
     severities.put(MessageId.MED_013, Severity.ERROR);
     severities.put(MessageId.MED_014, Severity.ERROR);
+    severities.put(MessageId.MED_015, Severity.ERROR);
 
     // NAV
     severities.put(MessageId.NAV_001, Severity.ERROR);
diff --git a/src/main/java/com/adobe/epubcheck/messages/MessageId.java b/src/main/java/com/adobe/epubcheck/messages/MessageId.java
@@ -145,6 +145,7 @@ public enum MessageId implements Comparable<MessageId>
   MED_012("MED_012"),
   MED_013("MED_013"),
   MED_014("MED_014"),
+  MED_015("MED_015"),
 
   // Epub3 based table of content errors
   NAV_001("NAV-001"),
diff --git a/src/main/java/com/adobe/epubcheck/opf/XRefChecker.java b/src/main/java/com/adobe/epubcheck/opf/XRefChecker.java
@@ -69,6 +69,7 @@ public static enum Type
     SEARCH_KEY,
     NAV_TOC_LINK,
     NAV_PAGELIST_LINK,
+    OVERLAY_TEXT_LINK,
     PICTURE_SOURCE,
     PICTURE_SOURCE_FOREIGN;
   }
@@ -286,6 +287,7 @@ public void checkReferences()
     // if (checkReference(reference)) checkReferenceSubtypes(reference);
     Queue<Reference> tocLinks = new LinkedList<>();
     Queue<Reference> pageListLinks = new LinkedList<>();
+    Queue<Reference> overlayLinks = new LinkedList<>();
     for (Reference reference : references)
     {
       switch (reference.type)
@@ -299,13 +301,17 @@ public void checkReferences()
       case NAV_PAGELIST_LINK:
         pageListLinks.add(reference);
         break;
+      case OVERLAY_TEXT_LINK:
+          overlayLinks.add(reference);
+          break;
       default:
         checkReference(reference);
         break;
       }
     }
     checkReadingOrder(tocLinks, -1, -1);
     checkReadingOrder(pageListLinks, -1, -1);
+    checkReadingOrder(overlayLinks, -1, -1);
   }
 
   private void checkReference(Reference ref)
@@ -533,7 +539,7 @@ private void checkReadingOrder(Queue<Reference> references, int lastSpinePositio
     if (ref == null) return;
 
     Preconditions
-        .checkArgument(ref.type == Type.NAV_PAGELIST_LINK || ref.type == Type.NAV_TOC_LINK);
+        .checkArgument(ref.type == Type.NAV_PAGELIST_LINK || ref.type == Type.NAV_TOC_LINK || ref.type == Type.OVERLAY_TEXT_LINK);
     Resource res = resources.get(ref.refResource);
 
     // abort early if the link target is not a spine item (checked elsewhere)
@@ -545,11 +551,18 @@ private void checkReadingOrder(Queue<Reference> references, int lastSpinePositio
     {
       String orderContext = LocalizedMessages.getInstance(locale).getSuggestion(MessageId.NAV_011,
           "spine");
-      report.message(MessageId.NAV_011,
-          EPUBLocation.create(ref.source, ref.lineNumber, ref.columnNumber),
-          (ref.type == Type.NAV_TOC_LINK) ? "toc" : "page-list", ref.value, orderContext);
-      report.message(MessageId.INF_001,
-          EPUBLocation.create(ref.source, ref.lineNumber, ref.columnNumber), "https://github.com/w3c/publ-epub-revision/issues/1283");
+      
+      if (ref.type == Type.OVERLAY_TEXT_LINK) {
+        report.message(MessageId.MED_015,
+                EPUBLocation.create(ref.source, ref.lineNumber, ref.columnNumber), ref.value, orderContext);
+      }
+      else {
+        report.message(MessageId.NAV_011,
+            EPUBLocation.create(ref.source, ref.lineNumber, ref.columnNumber),
+            (ref.type == Type.NAV_TOC_LINK) ? "toc" : "page-list", ref.value, orderContext);
+        report.message(MessageId.INF_001,
+            EPUBLocation.create(ref.source, ref.lineNumber, ref.columnNumber), "https://github.com/w3c/publ-epub-revision/issues/1283");
+      }
       lastSpinePosition = targetSpinePosition;
       lastAnchorPosition = -1;
     }
@@ -569,11 +582,17 @@ private void checkReadingOrder(Queue<Reference> references, int lastSpinePositio
       {
         String orderContext = LocalizedMessages.getInstance(locale).getSuggestion(MessageId.NAV_011,
             "document");
-        report.message(MessageId.NAV_011,
-            EPUBLocation.create(ref.source, ref.lineNumber, ref.columnNumber),
-            (ref.type == Type.NAV_TOC_LINK) ? "toc" : "page-list", ref.value, orderContext);
-        report.message(MessageId.INF_001,
-            EPUBLocation.create(ref.source, ref.lineNumber, ref.columnNumber), "https://github.com/w3c/publ-epub-revision/issues/1283");
+        if (ref.type == Type.OVERLAY_TEXT_LINK) {
+            report.message(MessageId.MED_015,
+                    EPUBLocation.create(ref.source, ref.lineNumber, ref.columnNumber), ref.value, orderContext);
+        }
+        else {
+          report.message(MessageId.NAV_011,
+              EPUBLocation.create(ref.source, ref.lineNumber, ref.columnNumber),
+              (ref.type == Type.NAV_TOC_LINK) ? "toc" : "page-list", ref.value, orderContext);
+          report.message(MessageId.INF_001,
+              EPUBLocation.create(ref.source, ref.lineNumber, ref.columnNumber), "https://github.com/w3c/publ-epub-revision/issues/1283");
+        }
       }
       lastAnchorPosition = targetAnchorPosition;
     }
diff --git a/src/main/java/com/adobe/epubcheck/overlay/OverlayHandler.java b/src/main/java/com/adobe/epubcheck/overlay/OverlayHandler.java
@@ -150,7 +150,17 @@ private void checkType(String type)
 
   private void processTextSrc(XMLElement e)
   {
-    processRef(e.getAttribute("src"), XRefChecker.Type.HYPERLINK);
+    String src = e.getAttribute("src");
+    
+    processRef(src, XRefChecker.Type.HYPERLINK);
+    
+    String resolvedSrc = PathUtil.resolveRelativeReference(path, src);
+    
+    if (context.xrefChecker.isPresent())
+    {
+      context.xrefChecker.get().registerReference(path, parser.getLineNumber(),
+          parser.getColumnNumber(), resolvedSrc, XRefChecker.Type.OVERLAY_TEXT_LINK);
+    }
   }
   
   private void processAudioSrc(XMLElement e) {
@@ -163,6 +173,7 @@ private void processAudioSrc(XMLElement e) {
     {
       requiredProperties.add(ITEM_PROPERTIES.REMOTE_RESOURCES);
     }
+
   }
 
   private void processRef(String ref, XRefChecker.Type type)
diff --git a/src/main/resources/com/adobe/epubcheck/messages/MessageBundle.properties b/src/main/resources/com/adobe/epubcheck/messages/MessageBundle.properties
@@ -138,6 +138,7 @@ MED_011=EPUB Content Document referenced from multiple Media Overlay Documents.
 MED_012=The "media-overlay" attribute does not match the ID of the Media Overlay that refers to this document.
 MED_013=Media Overlay Document referenced from the "media-overlay" attribute does not contain a reference to this Content Document.
 MED_014=A non-empty fragment identifier is required.
+MED_015=Media overlay text references must be in reading order. Text target "%1$s" is before the previous link target in %2$s order.
 
 #NAV EPUB v3 Table of contents
 NAV_001=The nav file is not supported for EPUB v2.
diff --git a/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/EPUB/content_001.mp3 b/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/EPUB/content_001.mp3
diff --git a/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/EPUB/content_001.smil b/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/EPUB/content_001.smil
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<smil xmlns="https://www.w3.org/ns/SMIL" xmlns:epub="https://www.idpf.org/2007/ops" version="3.0">
+	<body>
+		<par id="par1">
+			<text src="content_001.xhtml#c01"/>
+			<audio src="content_001.mp3"/>
+		</par>
+		<par id="par2">
+			<text src="content_001.xhtml#c03"/>
+			<audio src="content_001.mp3"/>
+		</par>
+		<par id="par3">
+			<text src="content_001.xhtml#c02"/>
+			<audio src="content_001.mp3"/>
+		</par>
+	</body>
+</smil>
diff --git a/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/EPUB/content_001.xhtml b/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/EPUB/content_001.xhtml
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html xmlns="https://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<title>Minimal EPUB</title>
+	</head>
+	<body>
+		<h1 id="c01">Loomings</h1>
+		<h2 id="c02">Roomings</h2>
+		<h2 id="c03">Zoomings</h2>
+	</body>
+</html>
diff --git a/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/EPUB/nav.xhtml b/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/EPUB/nav.xhtml
@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html xmlns="https://www.w3.org/1999/xhtml" xmlns:epub="https://www.idpf.org/2007/ops" xml:lang="en" lang="en">
+	<head>
+		<meta charset="utf-8"/>
+		<title>Minimal Nav</title>
+	</head>
+	<body>
+		<nav epub:type="toc">
+			<ol>
+				<li><a href="content_001.xhtml">content 001</a></li>
+			</ol>
+		</nav>
+	</body>
+</html>
diff --git a/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/EPUB/package.opf b/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/EPUB/package.opf
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="https://www.idpf.org/2007/opf" version="3.0" xml:lang="en" unique-identifier="q">
+<metadata xmlns:dc="https://purl.org/dc/elements/1.1/">
+  <dc:title id="title">Minimal EPUB 3.0</dc:title>
+  <dc:language>en</dc:language>
+  <dc:identifier id="q">NOID</dc:identifier>
+  <meta property="dcterms:modified">2017-06-14T00:00:01Z</meta>
+  <meta property="media:duration">2.5s</meta>
+  <meta property="media:duration" refines="#mo_001">2.5s</meta>
+</metadata>
+<manifest>
+  <item id="content_001"  href="content_001.xhtml" media-type="application/xhtml+xml" media-overlay="mo_001"/>
+  <item id="mo_001"  href="content_001.smil" media-type="application/smil+xml"/>
+  <item id="audio_001"  href="content_001.mp3" media-type="audio/mpeg"/>
+  <item id="nav"  href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>
+</manifest>
+<spine>
+  <itemref idref="content_001" />
+</spine>
+</package>
diff --git a/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/META-INF/container.xml b/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/META-INF/container.xml
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+	<rootfiles>
+		<rootfile full-path="EPUB/package.opf" media-type="application/oebps-package+xml"/>
+	</rootfiles>
+</container>
diff --git a/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/mimetype b/src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/mimetype
@@ -0,0 +1 @@
+application/epub+zip
diff --git a/src/test/resources/epub3/mediaoverlays-publication.feature b/src/test/resources/epub3/mediaoverlays-publication.feature
@@ -47,6 +47,13 @@ Feature: EPUB 3 ▸ Media Overlays ▸ Full Publication Checks
 
   ## 3. Creating Media Overlays
   
+  ### 3.2.1 Structure
+
+  Scenario: Report an overlay document whose text elements do not match the dom order of the corresponding content document
+    When checking EPUB 'mediaoverlays-text-reading-order-error'
+    Then error MED-015 is reported
+    And no other errors or warnings are reported
+
   ### 3.5.1 Including Media Overlays
 
   Scenario: Report an EPUB content document referenced from an overlay that is missing its media-overlay attribute
@@ -63,3 +70,4 @@ Feature: EPUB 3 ▸ Media Overlays ▸ Full Publication Checks
     When checking EPUB 'mediaoverlays-no-overlay-ref-error'
     Then error MED-013 is reported
     And no other errors or warnings are reported
+

Original file line number	Diff line number	Diff line change
`@@ -150,7 +150,17 @@ private void checkType(String type)`
`150`	`150`
`151`	`151`	`private void processTextSrc(XMLElement e)`
`152`	`152`	`{`
`153`		`- processRef(e.getAttribute("src"), XRefChecker.Type.HYPERLINK);`
	`153`	`+ String src = e.getAttribute("src");`
	`154`	`+`
	`155`	`+ processRef(src, XRefChecker.Type.HYPERLINK);`
	`156`	`+`
	`157`	`+ String resolvedSrc = PathUtil.resolveRelativeReference(path, src);`
	`158`	`+`
	`159`	`+ if (context.xrefChecker.isPresent())`
	`160`	`+ {`
	`161`	`+ context.xrefChecker.get().registerReference(path, parser.getLineNumber(),`
	`162`	`+ parser.getColumnNumber(), resolvedSrc, XRefChecker.Type.OVERLAY_TEXT_LINK);`
	`163`	`+ }`
`154`	`164`	`}`
`155`	`165`
`156`	`166`	`private void processAudioSrc(XMLElement e) {`
`@@ -163,6 +173,7 @@ private void processAudioSrc(XMLElement e) {`
`163`	`173`	`{`
`164`	`174`	`requiredProperties.add(ITEM_PROPERTIES.REMOTE_RESOURCES);`
`165`	`175`	`}`
	`176`	`+`
`166`	`177`	`}`
`167`	`178`
`168`	`179`	`private void processRef(String ref, XRefChecker.Type type)`