注記

EPUBCheckを実行するための、入手方法とシステム設定については、 EPUBCheckの使用方法 wikiを参照してください。このページではインストールについては説明しません。

はじめに

EPUBCheckは、EPUB出版物が規格に準拠しているかどうかを自動的にチェックする無料のコマンドライン検証ツールです。規格の要件に違反している問題や、出版物がリーディングシステムで開かなかったりレンダリングされなかったりする可能性のある問題を報告します。

EPUBCheckプログラムはJavaライブラリとして記述されているため、実行するには、コマンドライン インターフェイスから命令を入力するための基本的な知識が必要です。使用するインターフェイスは、オペレーティング システムによって異なります。Windowsでは、コマンドプロンプト ( cmd.exe ) と PowerShell ( powershell.exe ) の両方を使用して EPUBCheckを実行できます。Macでは、ターミナルアプリを使用できます。

新しいコマンドライン インターフェイスを起動すると、通常、入力プロンプトの前に開始ディレクトリが表示されます。

C:\users\default>_

EPUBCheckはほぼどのディレクトリからでも実行できますが、長いファイルパスを入力しなくて済むように、検証する出版物があるディレクトリに変更する方が簡単な場合がよくあります。ディレクトリを変更するには、 cdコマンドを使用します。

次のコマンドは、コマンド ライン インターフェイスをc:\epubsディレクトリに変更します。

> cd c:\epubs

EPUBCheckを実行するコマンドはオペレーティング システムに関係なく同じです。javaコマンドとそれに続く2つの引数で構成されます。

  1. -jar path\to\epubcheck.jar — 最初の引数は、EPUBCheckプログラムを含む Java jar ファイル ( epubcheck.jar ) への参照です。このファイルを参照するために使用される正確なパスは、EPUBCheckがインストールされている場所と、EPUBCheckが実行されるディレクトリによって異なります。
  2. publication.epub — 2番目の引数は、チェックするパッケージ化されたEPUB出版物の名前です。EPUBCheckが実行されるディレクトリと同じディレクトリにない場合は、ファイルへのフルパスを指定する必要があります。

以下は、コマンドラインからEPUBCheckを呼び出してaccessible_epub_3.epubファイルを検証する方法の例です。

> java -jar epubcheck.jar -mode exp -s accessible_epub_3

情報（Info）

読みやすさを考慮して、このページの残りの例では、 epubcheck.jarファイルとチェック対象の出版物への完全なパスは省略されています。

EPUBCheckで問題が検出されない場合は、次のような一連のメッセージが表示されます。

Validating using EPUB version 3.2 rules.
No errors or warnings detected.
Messages: 0 fatals / 0 errors / 0 warnings / 0 infos

EPUBCheck completed

最初の行は、検証するEPUBのバージョンを指定します。前の例の場合、プログラムはEPUB 3.2の要件に照らしてチェックしています。

次の2行は問題が見つからなかったことを示していますが、問題がある場合はここに報告されます。

最後のステートメントは、プログラムが正常に終了したことを確認するだけです。

出版物のアクセシビリティのチェックに進む前に、クリーンな検証結果を得ることが望ましいです。ただし、実際には、EPUBCheckでは、最初に修正が必要な警告やエラーが見つかることがよくあります。

以下はマークアップエラーを含むレポートの例です。

Validating using EPUB version 3.2 rules.
ERROR(RSC-005): accessible_epub_3.epub/EPUB/ch01.xhtml(98,5): Error while
parsing file: element "p" not allowed here; expected the element end-tag

Check finished with errors
Messages: 0 fatals / 1 error / 0 warnings / 0 infos

EPUBCheck completed

EPUBCheckのエラーメッセージは、エラーを含むファイル ( accessible_epub_3.epub/EPUB/ch01.xhtml ) と、エラーが発生した行番号 ( 98 ) および文字オフセット ( 5 ) の両方を示します。また、問題を説明する簡単なメッセージも提供します。この場合、次のファイルのスクリーンショットに示すように、 pタグが許可されていない場所で使用されています。

pタグが、body終了タグの後に含まれる

残念ながら、すべてのメッセージがこのように簡単に理解できるわけではなく、EPUBCheckが有用な行番号や文字オフセットを提供しない場合もあります (たとえば、問題が特定の場所に追跡できない場合、 (-1,-1)が報告されることがよくあります)。その結果、エラーを修正するには、多くの場合、ある程度の調査作業が必要になります。

EPUBCheckが出力するメッセージ数は、報告される数値が誤解を招くことが多いですが、実行間で問題が解決されているかどうかを追跡するのに便利です。

たとえば、1つのマークアップエラーが他の多くのエラーの原因となる可能性があるため、1 つの問題を修正すると、他の多くの問題またはすべて解消される可能性があります。すでに解決されている問題を探すのに時間を費やさないように、バグを修正するときは、頻繁に出版物を再検証することをお勧めします。

また、EPUBCheckが提起するすべての問題を修正しなければならないわけではありません。これについては、次のメッセージの深刻度に関するセクションで説明します。

メッセージの深刻度

EPUBCheckは5つの異なるカテゴリのメッセージを報告します。4つはデフォルトで出力され、1つのタイプ（使用方法（usage）メッセージ）は引数でオンにする必要があります。これらのカテゴリは、報告されている問題の深刻度を反映しており、最も深刻度が高いのは致命的（fatal）、最も低いのは情報（info）です。

EPUBCheckによって報告される各問題は、次のいずれかのラベルで始まります。

WARNING(OPF-053): 30/accessible_epub_3.epub/EPUB/package.opf(9,29): Date value 'Tuesday' does not follow recommended syntax ...
ERROR(RSC-005): 30/accessible_epub_3.epub/EPUB/ch01.xhtml(91,19): Error while parsing file: attribute "border" not allowed here ...

深刻度の後には括弧で囲んだエラーコードが続きますが、これらのコードは通常無視できます。これらはプログラムが使用する内部分類システムであり、EPUBCheck自体の問題のデバッグ以外では役に立ちません。

EPUBCheckの検証が終了すると、それぞれの合計数の概要が提供されます。

Messages: 2 fatals / 4 error / 18 warnings / 1 infos / 147 usages

各カテゴリーの意味は以下のリストで説明されています。

致命的（Fatal）

致命的なエラーは、最も深刻な問題に対して発行されます。致命的なエラーとは、リーディングシステムが出版物を開けなくなるエラー（パッケージの問題など）、またはコンテンツが読み取れなくなるエラー（コンテンツ内の致命的ななXMLエラーなど）です。

出版物の使いやすさを確保するには、致命的なエラーを修正する必要があります。

エラー（Error）

エラーは、２番目の深刻度レベルを表します。エラーは、出版物がEPUB規格の要件から逸脱している個所を識別します。通常、エラーによってEPUB出版物が開けなくなることはありませんが、意図しない結果（コンテンツが期待どおりにレンダリングされないなど）につながることがよくあります。

通常、出版物の使いやすさを確保するにはエラーを修正する必要がありますが、一部のフォーマット固有のエラーはアクセシビリティに影響を与えません ( WCAGに関連するエラーの理解に関する注記を参照)。

警告（Warning）

警告はエラーの1つ下のレベルです。警告は、EPUB規格の推奨される方法からの逸脱を識別します。警告のある出版物は規格に準拠しないわけではなく、意図しないレンダリングの問題もない可能性がありますが、推奨される方法に従わないと相互運用性の問題が発生する可能性があります。

警告を修正することは必須ではありませんが、一般的には推奨される方法に従うことをお勧めします。多くのベンダーは警告のある出版物を受け入れません。

情報（Info）

情報メッセージは、EPUBCheckによってデフォルトで出力される最も低レベルのメッセージです。これらのメッセージは通常、EPUBCheck自体の問題に関する警告を提供します（たとえば、ファイルを解読してチェックできない可能性がある、または潜在的な問題が検討中であるなど）。これらは一般的ではありません。

情報メッセージは必ずしも何らかのアクションを必要とするわけではありませんが、EPUBCheckにどのような問題があったかを確認するために確認することが重要です。

使用方法（Usage）

使用方法メッセージはベストプラクティスに似ています。推奨される使用方法を示しますが、必ずしもガイドラインに従う必要はありません。出版物によっては、EPUBCheckが大量の使用方法メッセージを発行することがあるため、デフォルトではオフになっています。

使用方法メッセージのリストを取得するには、EPUBCheckを起動するときに使用方法フラグ ( -u ) を設定する必要があります。

すべての使用方法メッセージを修正する必要はありませんが、強調されているベストプラクティスに従うことを検討する必要があります。

WCAG解析要件

一般的に、EPUB出版物のエラーを修正することがベストプラクティスですが、WCAGは厳密な準拠を強制しません。すべてのエラーがコンテンツのアクセシブルな読み取りに重大な影響を与えるわけではありません。

WCAGでは、エラーや警告がアクセシビリティの問題を引き起こすものである場合にのみ、準拠しないコンテンツを修正することが求められます。次に例を示します。

  • ARIA属性参照が使えなくなる重複ID（例: カスタム コントロールまたは説明リンク内）
  • コントロール ラベルまたは表見出しが使えなくなる重複ID。
  • 要素に複数のrole属性が指定されている。

過去には、達成基準 4.1.1は、支援技術による文書処理能力に影響を与える可能性のあるHTML解析エラー（整形エラーなど）の包括的な基準として使用されていました。最新のHTML解析では、これらの整形エラーの処理方法が標準化されているため、4.1.1 は常に適合性評価に合格します。上記のような出版物のアクセシビリティに影響を与える解析エラーは、他の達成基準でカバーされており、より適切な達成基準に基づいて報告する必要があります。

詳細については、達成基準 4.1.1 の説明を参照してください。

引数

引数は、EPUBCheckの実行時に指定できる追加オプションです。引数は通常、EPUBCheck jar ファイルを呼び出した後、検証する出版物またはファイルを指定する前に含められます。

次の例は、 -u引数を使用して、EPUBCheckの出力に使用方法（usage）メッセージを含めるように要求する方法を示しています。

> java -jar epubcheck.jar -u accessible_epub_3.epub

EPUBCheckの引数の多くには、詳細形式と簡潔形式の両方があります。詳細形式では名前の前に2つのダッシュが付きますが、簡潔形式では1つのダッシュの後に文字が続きます。EPUBCheckに使用方法のメッセージを出力させるには、最後の例のように簡潔な-u引数を使用するか、詳細--usage引数を使用します。

EPUBCheckには、さまざまな方法や目的で実行できるようにする多くの引数が含まれていますが、このセクションでは、最も有用な引数の一部のみを説明します。

注記

EPUBCheckで使用できるすべての引数の完全なリストを表示するには、ヘルプ ( -h ) 引数のみを指定してプログラムを実行します: java -jar epubcheck.jar -h

バージョン ( -v )

バージョン引数は、検証するEPUBのバージョンを指定するために使用されます。コンテンツがEPUB2に準拠しているかEPUB3に準拠しているかを示すために、値「 2.0 」または「 3.0 」のいずれかを使用します。

> java -jar epubcheck.jar -v 2.0 ...

EPUBCheckはパッケージドキュメントから正しいバージョンを自動的に判別するため、完全な出版物を検証するときにこの引数を指定する必要はありません。通常、この引数はモード引数と組み合わせて、出版物内の個々のファイルを検証するのに使います。

バージョン引数には詳細な形式はありません。 --versionの使用は、インストールされている EPUBCheckのバージョンを検出するために予約されています。

モード ( --modeまたは-m )

EPUBCheckは、パッケージ化されたEPUBファイル以外でも実行できます。これらの場合、モード引数は、プログラムが実行する正しいタイプの検証をガイドするために使用されます。

モード引数は通常、EPUB2パッケージドキュメントを検証するために次の例のように、バージョン引数とペアになります。

> java -jar epubcheck.jar -mode opf -v 2.0 package.xml

さまざまなモード値については、次のリストで説明します。

opf

opf値は、EPUB 2 または 3 パッケージ ドキュメントが検証されることを示します。

> java -jar epubcheck.jar -mode opf -v 3.0 package.xml
xhtml

xhtml値は、EPUB 2 または 3 XHTML コンテンツ ドキュメントが検証されることを示します。

> java -jar epubcheck.jar -mode xhtml -v 3.0 chapter01.xhtml
svg

svg値は、EPUB 2 または 3 SVG コンテンツ ドキュメントが検証されることを示します。

> java -jar epubcheck.jar -mode svg -v 2.0 heart.svg
nav

nav値は、EPUB 3 ナビゲーション ドキュメントが検証されることを示します。

> java -jar epubcheck.jar -mode nav nav.xhtml

EPUBCheckは個々の EPUB 2 NCX ドキュメントを検証しません。

mo

mo値は、EPUB 3 メディア オーバーレイが検証されることを示します。EPUB 2 には同等の機能はありません。

> java -jar epubcheck.jar -mode mo chapter01.smil
exp

exp値は、パッケージ化されていない EPUB 2 または 3 の出版物が検証されることを示すために使用されます (つまり、コンテンツは独自のディレクトリに「展開」されます)。このモードでは、ファイル名の代わりに、解凍されたファイルを含むディレクトリが使用されます。

> java -jar epubcheck.jar -mode exp accessible_epub_3

EPUBCheck はパッケージ ドキュメントからバージョンを自動的に判別するため、拡張 EPUB 検証ではバージョン引数を指定する必要はありません。

使用方法メッセージ ( --usageまたは-u )

メッセージの深刻度に関するセクションで説明したように、使用方法（usage）メッセージはデフォルトではオンになっていません。有効にするには、使用方法（usage）引数を指定する必要があります。

> java -jar epubcheck.jar -u accessible_epub_3.epub
保存 ( --saveまたは-s )

save 引数は、展開されたディレクトリからパッケージ化された EPUB ファイルを作成するための便利なオプションを提供し、手動で EPUB を圧縮する際に発生する可能性のある問題を回避します。これは、展開モード引数が指定されている場合にのみ機能します。

> java -jar epubcheck.jar -mode exp -s accessible_epub_3

EPUBCheck が致命的なエラーやエラーメッセージなしで完了すると、圧縮された EPUB ファイルのコピーが、出版物のフォルダーと同じディレクトリに保存されます（たとえば、フォルダーc:\epubs\accessible_epub_3で実行した場合、保存されたファイルはc:\epubs\accessible_epub_3.epubに保存されます）。

出力のリダイレクト

EPUBCheck からの出力をコマンドライン ウィンドウで読み取るのは、特に処理するメッセージが大量にある場合は難しい場合があります。幸い、すべてのコマンドライン インターフェイスには、プログラムからの出力をキャプチャしてファイルにリダイレクトできる機能があります。テキスト エディターで EPUBCheck メッセージを読み取るのははるかに簡単です。行の折り返しをオフにでき、テキストのスクロールや検索がより簡単になります。

EPUBCheck の出力をリダイレクトするには、コマンドの最後に大なり記号 ( > ) を使用し、その後に出力をリダイレクトするファイルを指定します。

次のコマンドは、出力をファイルoutput.txtにリダイレクトします。

> java -jar epubcheck.jar accessible_epub_3.epub > output.txt

書き込み可能なディレクトリに出力する以外 (たとえば、オペレーティング システムでは特別なシステム ディレクトリへのファイルの書き込みは許可されません)、出力ファイルの名前やパスに制限はありません。

この方法でEPUBCheckを実行するたびに、以前のファイルが新しい結果で上書きされるため、毎回新しいファイル名を指定する必要はありません。多くのテキストエディターでは、EPUBCheckが終了すると新しい出力が自動的に再ロードされるため、プロセスがさらに簡素化されます。

制限事項

EPUBCheckは、EPUB出版物で発生する可能性のある最も深刻なユーザビリティの問題を検出できますが、効果的にチェックできる内容にはいくつかの制限があります。これには次のものが含まれます。

そのため、リーディングシステムでEPUBのユーザービリティを手動でチェックすることが常に推奨されます。

さらに重要なのは、出版物のアクセシビリティを確保するには、 AceツールとSMARTツールも実行する必要があることです。アクセシビリティのテストの詳細については、ナレッジベースのそれぞれのページを参照してください。

その他の方法

EPUBCheckをコマンドラインから実行するのが面倒な場合は、より簡単なオプションがあります。次に、よく使用されるその他の方法をいくつか紹介します。

追加の代替手段のリストは、 EPUBCheck wikiで確認できます。

関連リンク