feat: check reading order of Media Overlays text elements

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

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);

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"),

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;
     }

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)

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.

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="http://www.w3.org/ns/SMIL" xmlns:epub="http://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>

src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/EPUB/content_001.xhtml

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html xmlns="http://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>

src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/EPUB/nav.xhtml

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://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>

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="http://www.idpf.org/2007/opf" version="3.0" xml:lang="en" unique-identifier="q">
+<metadata xmlns:dc="http://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>

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>

src/test/resources/epub3/files/epub/mediaoverlays-text-reading-order-error/mimetype

@@ -0,0 +1 @@
+application/epub+zip

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
+