なぜ機械で検査するか
MarkdownからEPUBを作るとき、変換が終わったことと、内容を確かめ終わったことは別です。ファイルが開けても、目次の飛び先が消えていたり、コードの一部が落ちていたりする可能性があります。見た目の確認だけでは、似た字形の別文字も見逃しやすくなります。
そこで、アップロード前に繰り返せる検査をPythonで用意します。この記事では、手元の材料にある verify_epub.py、check_chars.py、check_overflow.py を読み、何を根拠に判定しているかを説明します。実行結果は材料の記録を引用し、今回あらためてEPUBを実行検査した結果とは区別します。
コードは材料から要所を抜粋しています。利用時は、スクリプト内の固有の書名を持つEPUBパスを <本>.epub など、自分のファイルに合わせて読み替えてください。原稿の位置や OEBPS 内の構成も、このコードが想定する配置に合わせる必要があります。
検査1:ZIP構造とmimetype
verify_epub.py はEPUBを zipfile.ZipFile で開き、中の名前一覧を調べます。まず確かめるのは、mimetype の位置、圧縮方式、中身です。
check(names[0] == 'mimetype', 'mimetype が先頭 (実際: {0})'.format(names[0]))
check(z.getinfo('mimetype').compress_type == zipfile.ZIP_STORED, 'mimetype が無圧縮')
check(z.read('mimetype') == b'application/epub+zip', 'mimetype の中身')
拡張子だけで判断せず、ZIP内の実体を見ています。ZIP_STORED との比較で無圧縮を確かめ、内容はバイト列で一致を取っています。続いて META-INF/container.xml、OEBPS/content.opf、OEBPS/nav.xhtml、OEBPS/toc.ncx の存在も調べます。
ここでの判定は、このスクリプトが想定する生成物に対するものです。たとえば OEBPS/content.opf という固定パスを探しているので、別の配置を採用するEPUBへそのまま適用できるとは限りません。また、必須ファイルの欠落などで例外になる箇所もあり、どんな壊れ方でも最後までNG一覧を出す作りではありません。
検査2:XMLとして読めるか
次に、対象の拡張子を持つファイルをXMLパーサーへ渡します。
xmls = [n for n in names if n.endswith(('.xhtml', '.opf', '.ncx', '.xml'))]
bad = []
for n in xmls:
try:
ET.fromstring(z.read(n))
except Exception as e:
bad.append('{0}: {1}'.format(n, e))
読み込みに失敗したファイル名と例外を残すので、問題のある場所を絞れます。タグの閉じ忘れなど、XMLとして解析できない状態をここで拾う考え方です。
見出しは「XML妥当性」ですが、実装が行うのは ET.fromstring による解析です。EPUBに関する仕様全体や、パッケージ内の意味的な整合性まで検証しているとは読めません。XMLとして読めたことと、EPUBのあらゆる条件を満たすことは分けて扱います。
検査3:目次リンクの実在
目次は表示されるだけでなく、移動先が存在する必要があります。このコードは各XHTMLから id を集め、ファイル名ごとに集合として保存します。その後、nav.xhtml と toc-page.xhtml の href を調べます。
f, _, frag = href.partition('#')
if f not in ids:
missing.append('{0} -> ファイル無し {1}'.format(navfile, href))
elif frag and frag not in ids[f]:
missing.append('{0} -> id 無し {1}'.format(navfile, href))
# より前をファイル名、後ろを移動先のIDとして扱います。ファイル自体がない場合と、ファイルはあるがIDがない場合を区別できるのが便利です。toc.ncx の content src に対しても、同じ考え方で確認します。
ただし抽出は正規表現で、ダブルクォートの属性を想定しています。ファイルのキーもベース名です。任意の相対パスを解決する汎用リンク検査ではありません。また、移動先が存在しても、意図した章に飛ぶかどうかまでは判断しません。
検査4:原稿の文字が落ちていないか
文字の比較では、章のXHTMLからタグを取り除き、一部の実体参照を文字へ戻して本文をつなぎます。比較時は空白を除くため、改行や空白の違いで不一致になりにくい形です。
def norm(s):
s = re.sub(r'\s+', '', s)
return s
照合するのは、原稿の見出し、コードブロックの先頭の非空行、一定の長さを超える引用行の先頭部分、表の行の先頭セルです。見出しは本文だけでなく、扉と目次ページにも探します。移した見出しを欠落と誤認しないための処理です。
コードブロックについては、次の箇所が検査の粒度をよく表しています。
probe = norm(ls[0])
if probe and probe not in body_norm:
lost_b.append(ls[0][:50])
先頭行が見つかれば、そのブロックについては通過します。途中の行まで一致するかは調べません。表も全セルの比較ではなく先頭セルの存在確認なので、「文字がすべて同じ」と保証する検査にはなりません。同じ文字列が別の場所にあれば、存在確認を通過する点にも注意が必要です。
分量の確認では、空白を除いた原稿とEPUB本文の文字数を出し、Markdown記号や扉へ移した部分を概算して差分を表示します。これは欠落の手掛かりを得る補助です。差分の出力自体には check による合否判定がなく、概算値だけで欠落なしとは断言できません。
なお、元のスクリプトには図のファイル数、本文からの参照、代替テキスト、説明文、変換されずに残ったバッククォートの検査もあります。図の期待数などはその本向けの設定なので、自分の構成に合わせて扱います。
検査5:化け字と残留文字列
verify_epub.py は本文中のU+FFFDと、XHTML内の裸の & を確認します。さらに check_chars.py はXHTML・NCX・OPFの文字列を連結し、特定のコードポイントを数えます。
bad = [c for c in t if 0x2E80 <= ord(c) <= 0x2EFF or 0x2F00 <= ord(c) <= 0x2FDF or 0x2FF0 <= ord(c) <= 0x2FFF
or ord(c) in (0xFFFD, 0x2027, 0x2215, 0x336, 0xAD, 0x6236)]
esc = re.findall(r"\x5cu[0-9a-fA-F]{4}", t)
康熙部首などの範囲と、置換文字U+FFFDに加え、似た字形への置換としてメモに記録された文字も対象です。見た目だけに頼らず、ord で実際の文字を見ます。esc は、バックスラッシュと u に続く十六進表記が、そのまま残っていないかを探します。さらに localhost の文字列も数え、いずれかがあれば終了コードを失敗にします。
材料のメモでは、HTMLからPDFを出力する工程で、普通の漢字が見た目の似た康熙部首になる事例が記録されています。コピーすると別文字になるため、画面を眺めるだけでは気付きにくい問題です。ただし、これはPDF生成についての記録であり、このEPUBで同じ原因の化けが起きた証拠ではありません。
メモは途中の判断を訂正し、最終的にはフォント名だけで安全とは判定できないとしています。ここから得られるのは、フォント名を信頼するより、出力された文字を調べるという方針です。localhost の確認にもPDF出力時の記録がありますが、EPUBでは対象文字列の残留を探していると説明するのが正確です。
この検査は特定文字の検出であり、文字化け全般の自動判定ではありません。意図して該当文字やエスケープ表記を掲載する技術書なら、それも検出されます。検出箇所を見て原稿の意図と照合する必要があります。
検査6:横にはみ出していないか
check_overflow.py は文字数ではなく、ブラウザーが配置した要素の幅を測ります。EPUBを一時ディレクトリへ展開し、OEBPS 直下のXHTMLへ計測用スクリプトを差し込みます。変更するのは展開先で、元のEPUBは書き換えません。
展開したページはローカルHTTPで配信します。変数名は CHROME ですが、実装の実行ファイルはEdgeです。ヘッドレスで起動し、幅を620pxに設定してDOMを回収します。計測側の核心は次の部分です。
var r = e.getBoundingClientRect();
if (r.width < 1 && r.height < 1) continue;
var over = Math.round(r.right - vw);
var scrollOver = e.scrollWidth - e.clientWidth;
if (over > 1 || scrollOver > 1) {
vw は実際の表示領域の幅です。要素の右端がそこを越える量と、要素内部のスクロール幅が表示幅を越える量を調べます。前者は画面の右への突出、後者は要素内部で収まり切らない内容を拾うための値です。どちらかが条件を満たせば、タグ、クラス、幅に関する値、テキストの先頭を記録します。
結果はページのタイトルへJSONとして埋め込み、Pythonが --dump-dom の出力から読み戻します。計測不能は、はみ出しとは別に数えます。タイムアウト時は再試行し、それでも回収できなければ「計測できず」と表示します。
ここでいうページは列挙したXHTMLファイルであり、Kindleで分割表示されるページ数ではありません。また右方向と内部幅の検査で、左側への突出や縦方向の問題を網羅していません。末尾は集計を表示する処理で、はみ出し件数に応じた失敗終了コードの設定もありません。自動処理に組み込むなら、出力の読み取り方まで考える必要があります。
実行結果の例
材料の 実行結果_20261111.txt には、次の記録があります。数字は記録どおりです。
原稿.md:64698 字(コードブロックを除く本文 55141 字)・章 18
figures : 14
size : 997574 bytes
EPUB サイズ: 997,574 バイト
=== 結果: OK 21 / NG 0 ===
=== 21 ページ中 はみ出し 0 件 / 計測できず 1 ページ ===
化け字 0/localhost 0/エスケープ 0
記録には「総合判定:すべてOK」もありますが、はみ出し検査には計測できなかったページが残っています。したがって「全ページのはみ出しなしを確認済み」とは読めません。未計測の原因はこの記録だけでは分からず、再計測または個別確認が必要です。また、原稿の分量など、提示されたスクリプトの出力と直接対応を確定できない項目を、特定の検査の成果として説明しないようにします。
限界と使いどころ
機械検査は、同じ条件を繰り返し確認するのに向いています。一方で、抜き取り照合の通過は全文一致の証明ではなく、XML解析の成功もEPUB全体の完全な検証ではありません。対象ファイルや属性の書き方が変われば、検査側の前提も見直す必要があります。
ブラウザーでの幅の実測も、その環境で得た結果です。KDPのプレビューの代わりにはならず、文字の読みやすさ、図の見え方、目次から意図した箇所への移動などは実際の表示で確認します。機械で見つけられる問題を先に減らし、その後の表示確認に集中する使い方ができます。
おわりに
ZIPの構造、XMLの解析、リンク先の存在、原稿との照合、特定文字の検出、ブラウザーでの実測は、それぞれ違う問題を探しています。何を調べていないかも把握しておくと、OKの表示を過信せずに使えます。未計測を残さず確認し、最後はプレビューで仕上がりを確かめます。
原稿づくりから KDP の入力までを Claude Code に任せた手順は、Tips にまとめています:https://tips.jp/u/hina-mina/a/4WeiOt6J