Skip to content

Instantly share code, notes, and snippets.

@raeq
Created September 16, 2026 19:35
Show Gist options
  • Select an option

  • Save raeq/d617a4777361f9f5c906445d19a5c66e to your computer and use it in GitHub Desktop.

Select an option

Save raeq/d617a4777361f9f5c906445d19a5c66e to your computer and use it in GitHub Desktop.
epubcheck message ids: 21 of 315 use an underscore (repro)

epubcheck message ids: 21 of 315 use an underscore

repro.sh builds a minimal fixed-layout EPUB with two faults and runs epubcheck 5.3.0 on it. Output:

ERROR    HTM_056    Viewport metadata has no "height" dimension (both "width" and "height"
ERROR    RSC-012    Fragment identifier is not defined.

One report, two spellings. HTM_056 takes an underscore, RSC-012 a hyphen.

The ids are defined in src/main/java/com/adobe/epubcheck/messages/MessageId.java, where each enum constant carries its public id as a string:

MED_005("MED-005"),
MED_006("MED_006"),

In 5.3.0, 21 of 315 ids are spelled with an underscore:

HTM_053 HTM_054 HTM_055 HTM_056 HTM_057 HTM_058 HTM_059 HTM_060a HTM_060b HTM_061
MED_006 MED_007 MED_010 MED_011 MED_012 MED_013 MED_014 MED_015 MED_016 MED_017 MED_018

In 5.4.0 there are 23 of 323, with HTM_062 and HTM_063 added.

To list them from a checkout:

grep -oE '^\s+[A-Z]{3}_[0-9]+[a-z]?\("[A-Z]{3}_[0-9]+[a-z]?"\)' \
  src/main/java/com/adobe/epubcheck/messages/MessageId.java

epubcheck's own feature files write the hyphen form for these ids, so the expectation and the output disagree:

src/test/resources/epub3/09-media-overlays/media-overlays.feature
  Then error MED-014 is reported

Found while replaying epubcheck's test corpus against two validators; a consumer matching [A-Z]{3}-[0-9]+ dropped all 21 silently.

#!/bin/sh
# Two findings from one EPUB: epubcheck reports one id with a hyphen and the
# other with an underscore. Needs epubcheck on PATH, plus zip and python3.
set -eu
work=$(mktemp -d "${TMPDIR:-/tmp}/epubcheck-msgid.XXXXXX")
trap 'rm -rf "$work"' EXIT
book="$work/book"
mkdir -p "$book/META-INF" "$book/OEBPS"
printf 'application/epub+zip' > "$book/mimetype"
cat > "$book/META-INF/container.xml" <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
<rootfiles><rootfile full-path="OEBPS/package.opf"
media-type="application/oebps-package+xml"/></rootfiles>
</container>
XML
cat > "$book/OEBPS/package.opf" <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="uid"
prefix="rendition: http://www.idpf.org/vocab/rendition/#">
<metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
<dc:identifier id="uid">urn:uuid:0d6d1a1e-4a1a-4f4e-9a3e-2b7c1d5e8f90</dc:identifier>
<dc:title>Message id spelling</dc:title>
<dc:language>en</dc:language>
<meta property="dcterms:modified">2026-09-16T00:00:00Z</meta>
<meta property="rendition:layout">pre-paginated</meta>
</metadata>
<manifest>
<item id="nav" href="nav.xhtml" media-type="application/xhtml+xml" properties="nav"/>
<item id="c1" href="chapter.xhtml" media-type="application/xhtml+xml"/>
</manifest>
<spine><itemref idref="c1"/></spine>
</package>
XML
cat > "$book/OEBPS/nav.xhtml" <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops"
lang="en" xml:lang="en">
<head><title>Contents</title><meta name="viewport" content="width=1200, height=1600"/></head>
<body><nav epub:type="toc"><ol><li><a href="chapter.xhtml">Chapter</a></li></ol></nav></body>
</html>
XML
# The viewport has no height, which is HTM_056. The link points at an id the
# document does not have, which is RSC-012.
cat > "$book/OEBPS/chapter.xhtml" <<'XML'
<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head><title>Chapter</title><meta name="viewport" content="width=1200"/></head>
<body><p><a href="#no-such-id">link</a></p></body>
</html>
XML
(cd "$book" && zip -q -X0 ../book.epub mimetype && zip -qrX ../book.epub . -x mimetype)
epubcheck "$work/book.epub" --json "$work/report.json" -q || true
python3 - "$work/report.json" <<'PY'
import json, sys
report = json.load(open(sys.argv[1]))
for message in report["messages"]:
print(f'{message["severity"]:8} {message["ID"]:10} {message["message"][:70]}')
PY
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment