feat: check fragment requirements on overlays links to text content

This commit checks the updated requirements on referencing document
fragments from media overlays.

- Warning `MED-017` (new) is reported for fragment references to XHTML
  content documents that do not indicate an element ID
- Warning `MED-018` (new) is reported for fragment references SVG
  content document that are not valid SVG fragment identifiers

Fixes #1248, fixes #1301

src/main/java/com/adobe/epubcheck/dtbook/DTBookHandler.java

@@ -51,7 +51,7 @@ public void startElement()
     if (ns.equals("http://www.daisy.org/z3986/2005/dtbook/"))
     {
       // Register IDs
-      xrefChecker.registerID(e.getAttribute("id"), XRefChecker.Type.HYPERLINK, location());
+      xrefChecker.registerID(e.getAttribute("id"), XRefChecker.Type.GENERIC, location());
 
       // Check cross-references (link@href | a@href | img@src)
       URL url = null;

src/main/java/com/adobe/epubcheck/messages/DefaultSeverities.java

@@ -160,6 +160,8 @@ private void initialize()
     severities.put(MessageId.MED_014, Severity.ERROR);
     severities.put(MessageId.MED_015, Severity.USAGE);
     severities.put(MessageId.MED_016, Severity.WARNING);
+    severities.put(MessageId.MED_017, Severity.WARNING);
+    severities.put(MessageId.MED_018, Severity.WARNING);
 
     // NAV
     severities.put(MessageId.NAV_001, Severity.ERROR);

src/main/java/com/adobe/epubcheck/messages/MessageId.java

@@ -154,6 +154,8 @@ public enum MessageId implements Comparable<MessageId>
   MED_014("MED_014"),
   MED_015("MED_015"),
   MED_016("MED_016"),
+  MED_017("MED_017"),
+  MED_018("MED_018"),
 
   // Epub3 based table of content errors
   NAV_001("NAV-001"),

src/main/java/com/adobe/epubcheck/opf/XRefChecker.java

@@ -407,6 +407,7 @@ public void checkReferences()
         break;
       case OVERLAY_TEXT_LINK:
         overlayLinks.add(reference);
+        checkReference(reference);
         break;
       default:
         checkReference(reference);
@@ -419,11 +420,7 @@ public void checkReferences()
 
   private void checkReference(URLReference reference)
   {
-    Resource hostResource = resources.get(reference.location.url);
-
-    // Retrieve the Resource instance representing the targeted document
-    // If the resource was not declared in the manifest,
-    // we build a new Resource object for the data URL.
+    // Retrieve the target resource
     Resource targetResource = resources.get(reference.targetDoc);
     String targetMimetype = (targetResource != null) ? targetResource.getMimeType() : "";
 
@@ -487,6 +484,7 @@ else if (!undeclared.contains(reference.targetDoc)
     switch (reference.type)
     {
     case HYPERLINK:
+
       if ("epubcfi".equals(fragment.getScheme()))
       {
         break; // EPUB CFI is not supported
@@ -536,6 +534,14 @@ else if (reference.type == Type.IMAGE && !targetResource.hasImageFallback())
         }
       }
       break;
+    case OVERLAY_TEXT_LINK:
+      if (!OPFChecker.isBlessedItemType(targetMimetype, version))
+      {
+        report.message(MessageId.RSC_010,
+            reference.location.context(container.relativize(reference.url)));
+        return;
+      }
+      break;
     case SEARCH_KEY:
       // TODO update when we support EPUB CFI
       if ((!fragment.exists() || !"epubcfi".equals(fragment.getScheme()))
@@ -584,31 +590,27 @@ else if (reference.type == Type.IMAGE && !targetResource.hasImageFallback())
     // Fragment integrity checks
     if (fragment.exists() && !fragment.isEmpty())
     {
-      // EPUB CFI
-      if ("epubcfi".equals(fragment.getScheme()))
-      {
-        // FIXME HOT should warn if in MO
-        // FIXME epubcfi currently not supported (see issue 150).
-        return;
-      }
-      // Media fragments in Data Navigation Documents
-      else if (fragment.isMediaFragment() && hostResource != null && hostResource.hasItem()
-          && hostResource.getItem().getProperties()
-              .contains(PackageVocabs.ITEM_VOCAB.get(PackageVocabs.ITEM_PROPERTIES.DATA_NAV)))
-      {
-        // Ignore,
-        return;
-      }
-      // Non-ID-based fragments are ignored
-      else if (fragment.getId().isEmpty())
+      // Check media overlays requirements
+      if (reference.type == Type.OVERLAY_TEXT_LINK)
       {
-        return;
+        // Check that references to XHTML indicate an element by ID
+        if (MIMEType.XHTML.is(targetMimetype) && fragment.getId().isEmpty())
+        {
+          report.message(MessageId.MED_017, reference.location, fragment.toString());
+        }
+        // Check that references to SVG use a SVG fragment identifier
+        else if (MIMEType.SVG.is(targetMimetype) && !fragment.isValid())
+        {
+          report.message(MessageId.MED_018, reference.location, fragment.toString());
+        }
       }
-      // Fragment Identifier (by default)
-      else if (!container.isRemote(reference.targetDoc))
+
+      // Check ID-based fragments
+      // Other fragment types (e.g. EPUB CFI) are not currently supported
+      if (!fragment.getId().isEmpty() && !container.isRemote(reference.targetDoc))
       {
-        ID anchor = targetResource.ids.get(fragment.getId());
-        if (anchor == null)
+        ID targetID = targetResource.ids.get(fragment.getId());
+        if (targetID == null)
         {
           report.message(MessageId.RSC_012, reference.location.context(reference.url.toString()));
           return;
@@ -617,15 +619,16 @@ else if (!container.isRemote(reference.targetDoc))
         {
         case SVG_PAINT:
         case SVG_CLIP_PATH:
-          if (anchor.type != reference.type)
+          if (targetID.type != reference.type)
           {
             report.message(MessageId.RSC_014, reference.location.context(reference.url.toString()));
             return;
           }
           break;
         case SVG_SYMBOL:
         case HYPERLINK:
-          if (anchor.type != reference.type && anchor.type != Type.GENERIC)
+        case OVERLAY_TEXT_LINK:
+          if (targetID.type != reference.type && targetID.type != Type.GENERIC)
           {
             report.message(MessageId.RSC_014, reference.location.context(reference.url.toString()));
             return;

src/main/java/com/adobe/epubcheck/ops/OPSHandler.java

@@ -290,8 +290,6 @@ else if (name.equals("script"))
           checkScript();
         }
 
-        resourceType = XRefChecker.Type.HYPERLINK;
-
         String style = e.getAttribute("style");
         if (style != null && style.length() > 0)
         {

src/main/java/com/adobe/epubcheck/overlay/OverlayHandler.java

@@ -12,6 +12,7 @@
 import com.adobe.epubcheck.opf.OPFChecker30;
 import com.adobe.epubcheck.opf.ValidationContext;
 import com.adobe.epubcheck.opf.XRefChecker;
+import com.adobe.epubcheck.opf.XRefChecker.Type;
 import com.adobe.epubcheck.util.EpubConstants;
 import com.adobe.epubcheck.vocab.AggregateVocab;
 import com.adobe.epubcheck.vocab.PackageVocabs;
@@ -22,7 +23,6 @@
 import com.adobe.epubcheck.vocab.VocabUtil;
 import com.adobe.epubcheck.xml.handlers.XMLHandler;
 import com.adobe.epubcheck.xml.model.XMLElement;
-import com.google.common.base.Strings;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 import com.google.common.collect.Sets;
@@ -54,6 +54,8 @@ public void startElement()
     XMLElement e = currentElement();
     String name = e.getName();
 
+    processGlobalAttrs();
+
     switch (name)
     {
     case "smil":
@@ -64,8 +66,7 @@ public void startElement()
 
     case "body":
     case "seq":
-    case "par":
-      processGlobalAttrs();
+      processTextRef();
       break;
 
     case "text":
@@ -140,79 +141,65 @@ private void checkType(String type)
 
   private void processTextSrc()
   {
-    URL srcURL = checkURL(currentElement().getAttribute("src"));
-    if (srcURL != null)
+    URL url = checkURL(currentElement().getAttribute("src"));
+    if (url != null && context.xrefChecker.isPresent())
     {
-      processRef(srcURL, XRefChecker.Type.HYPERLINK);
-
-      if (context.xrefChecker.isPresent())
-      {
-        context.xrefChecker.get().registerReference(srcURL, XRefChecker.Type.OVERLAY_TEXT_LINK,
-            location());
-      }
+      processContentDocumentLink(url);
     }
 
   }
 
+  private void processTextRef()
+  {
+    URL url = checkURL(
+        currentElement().getAttributeNS(EpubConstants.EpubTypeNamespaceUri, "textref"));
+    if (url != null && context.xrefChecker.isPresent())
+    {
+      processContentDocumentLink(url);
+    }
+  }
+
   private void processAudioSrc()
   {
 
-    URL srcURL = checkURL(currentElement().getAttribute("src"));
-    if (srcURL != null)
+    URL url = checkURL(currentElement().getAttribute("src"));
+    if (url != null && context.xrefChecker.isPresent())
     {
-      processRef(srcURL, XRefChecker.Type.AUDIO);
+      // check that the audio type is a core media type resource
+      String mimeType = context.xrefChecker.get().getMimeType(url);
+      if (mimeType != null && !OPFChecker30.isBlessedAudioType(mimeType))
+      {
+        report.message(MessageId.MED_005, location(), context.relativize(url), mimeType);
+      }
+
+      // register the URL for cross-reference checking
+      context.xrefChecker.get().registerReference(url, Type.AUDIO, location());
 
-      if (context.isRemote(srcURL))
+      // if needed, register we found a remote resource
+      if (context.isRemote(url))
       {
         requiredProperties.add(ITEM_PROPERTIES.REMOTE_RESOURCES);
       }
     }
   }
 
-  private void processRef(URL ref, XRefChecker.Type type)
+  private void processContentDocumentLink(URL url)
   {
-    assert ref != null;
-    if (context.xrefChecker.isPresent())
+    assert url != null;
+    assert context.xrefChecker.isPresent();
+    assert context.overlayTextChecker.isPresent();
+    URL documentURL = URLUtils.docURL(url);
+    if (!context.overlayTextChecker.get().registerOverlay(documentURL,
+        context.opfItem.get().getId()))
     {
-      if (type == XRefChecker.Type.AUDIO)
-      {
-        String mimeType = context.xrefChecker.get().getMimeType(ref);
-        if (mimeType != null && !OPFChecker30.isBlessedAudioType(mimeType))
-        {
-          report.message(MessageId.MED_005, location(), context.relativize(ref), mimeType);
-        }
-      }
-      else
-      {
-        checkFragment(ref);
-        URL resourceURL = URLUtils.docURL(ref);
-        // FIXME 2022 see if test case is needed
-        // if (!Strings.isNullOrEmpty(uniqueResource))
-        // {
-        // (uniqueResource was ref-minus-fragment string)
-        // OverlayTextChecker must be present if XRefChecker is also present
-        assert context.overlayTextChecker.isPresent();
-        if (!context.overlayTextChecker.get().registerOverlay(resourceURL, context.opfItem.get().getId()))
-        {
-          report.message(MessageId.MED_011, location(), context.relativize(ref));
-        }
-        // }
-      }
-      context.xrefChecker.get().registerReference(ref, type, location());
+      report.message(MessageId.MED_011, location(), context.relativize(url));
     }
+    context.xrefChecker.get().registerReference(url, Type.OVERLAY_TEXT_LINK, location());
   }
 
   private void processGlobalAttrs()
   {
     XMLElement e = currentElement();
-    if (!e.getName().equals("audio"))
-    {
-      URL textrefURL = checkURL(e.getAttributeNS(EpubConstants.EpubTypeNamespaceUri, "textref"));
-      if (textrefURL != null)
-      {
-        processRef(textrefURL, XRefChecker.Type.HYPERLINK);
-      }
-    }
     checkType(e.getAttributeNS(EpubConstants.EpubTypeNamespaceUri, "type"));
   }
 
@@ -238,17 +225,6 @@ private void checkItemReferences()
 
   }
 
-  private void checkFragment(URL url)
-  {
-    String fragment = url.fragment();
-
-    if (Strings.isNullOrEmpty(fragment))
-    {
-      // must include a non-empty fragid
-      report.message(MessageId.MED_014, location());
-    }
-  }
-
   protected void checkProperties()
   {
     if (!context.container.isPresent()) // single file validation

src/main/java/com/adobe/epubcheck/overlay/OverlayTextChecker.java

@@ -24,8 +24,7 @@ public boolean registerOverlay(URL contentDocURL, String overlayID)
     }
     else
     {
-      // TODO check if case must really be ignored
-      return overlayID.equalsIgnoreCase(docToOverlayMap.get(contentDocURL));
+      return overlayID.equals(docToOverlayMap.get(contentDocURL));
     }
   }
 
@@ -40,7 +39,6 @@ public boolean isReferencedByOverlay(URL contentDocURL)
 
   public boolean isCorrectOverlay(URL contentDocURL, String overlayID)
   {
-    // TODO check if case must really be ignored
-    return overlayID.equalsIgnoreCase(docToOverlayMap.get(contentDocURL));
+    return overlayID.equals(docToOverlayMap.get(contentDocURL));
   }
 }

src/main/resources/com/adobe/epubcheck/messages/MessageBundle.properties

@@ -144,7 +144,9 @@ MED_012=The "media-overlay" attribute does not match the ID of the Media Overlay
 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.
-MED_016=Media Overlays total duration should be the sum of the durations of all Media Overlays documents. 
+MED_016=Media Overlays total duration should be the sum of the durations of all Media Overlays documents.
+MED_017=URL fragment should indicate an element ID, but found '#%1$s'.
+MED_018=URL fragment should be an SVG fragment identifier, but found '#%1$s'.
 
 #NAV EPUB v3 Table of contents
 NAV_001=The nav file is not supported for EPUB v2.

src/test/resources/epub3/09-media-overlays/files/mediaoverlays-textref-fragment-schemebased-warning/EPUB/content_001.smil

@@ -0,0 +1,9 @@
+<?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#xpointer(id('c01'))"/>
+            <audio src="content_001.mp3"/>
+        </par>
+    </body>
+</smil>

src/test/resources/epub3/09-media-overlays/files/mediaoverlays-fragid-invalid-error/EPUB/content_001.smil → src/test/resources/epub3/09-media-overlays/files/mediaoverlays-textref-no-fragment-valid/EPUB/content_001.smil

@@ -1,8 +1,8 @@
 <?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 epub:textref="content_001.xhtml#">
+    <body epub:textref="content_001.xhtml">
     	<par id="par1">
-    		<text src="content_001.xhtml"/>
+    		<text src="content_001.xhtml#"/>
     		<audio src="content_001.mp3"/>
     	</par>
     </body>

src/test/resources/epub3/09-media-overlays/files/mediaoverlays-textref-no-fragment-valid/EPUB/content_001.xhtml

@@ -0,0 +1,11 @@
+<!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>
+		<p>Call me Ishmael.</p>
+	</body>
+</html>

src/test/resources/epub3/09-media-overlays/files/mediaoverlays-textref-no-fragment-valid/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>