注記
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つの引数で構成されます。
-
-jar path\to\epubcheck.jar
— 最初の引数は、EPUBCheckプログラムを含む Java jar ファイル (epubcheck.jar
) への参照です。このファイルを参照するために使用される正確なパスは、EPUBCheckがインストールされている場所と、EPUBCheckが実行されるディレクトリによって異なります。 -
publication.epub
— 2番目の引数は、チェック対象のパッケージ化されたEPUB出版物の名前です。EPUBCheckが実行されるディレクトリと同じディレクトリにない場合は、ファイルへのフルパスを指定してください。
以下は、コマンドラインからEPUBCheckを呼び出しaccessible_epub_3.epub
のファイルを検証する例です。
> java -jar c:\epubcheck\epubcheck.jar c:\epubs\accessible_epub_3.epub
注記
このページの残りの例では、 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
タグが許可されていない場所で使用されています。
残念ながら、すべてのメッセージがこのように簡単に理解できるわけではありません。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)
-
エラーは、2番目の深刻度レベルを表します。エラーは、出版物が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
値は、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
) -
メッセージの深刻度
に関するセクションで説明したように、使用方法メッセージはデフォルトでは有効化されていません。有効にするには、使用方法メッセージの引数を指定しなければなりません。> java -jar epubcheck.jar -u accessible_epub_3.epub
- 保存 (
--save
または-s
) -
保存引数は、展開されたディレクトリよりパッケージ化した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出版物で発生する可能性のある最も深刻なユーザビリティの問題を検出できますが、効果的にチェックできる内容にはいくつかの制限があります。これには次のものが含まれます。
- 一部の技術、特にCSSについては限定的な検証しか提供されないため、表示に問題が生じる可能性があります。
- スクリプトが出版物の構造や使いやすさに悪影響を及ぼすかどうかは検証できません。
- アクセシビリティ関連のチェックの多くは含まれていません。ARIAのrole、states、propertyの正しい使用など、チェックに使用されるコードの複雑さにより、完全ではない可能性があります。
そのため、リーディングシステムでEPUBのユーザービリティを手動でチェックすることが常に推奨されます。
さらに重要なのは、出版物のアクセシビリティを確保するには、 AceツールとSMARTツールも実行する必要がある点です。アクセシビリティのテストの詳細については、ナレッジベースのそれぞれのページを参照してください。
その他の方法
EPUBCheckをコマンドラインから実行するのが面倒な場合には、より簡単な方法があります。以下に、よく利用されているいくつかの代わりの方法を紹介します。
- EPUB Validator — DAISYコンソーシアムが管理する無料のオンライン検証ツール。アップロードされたファイルはEPUBCheckで検証され、その結果が新しいWebページに返されます。(商業出版には使用できません。)
- FlightDeck — ベンダー固有のコンテンツルールにも重点を置いた、Webベースの商用検証ツールです。EPUBCheckエラーの解決方法に関する役立つ追加情報も含まれています。
- Oxygen Editor — パッケージ化されたEPUB出版物をチェックするためのEPUBCheckの組み込みバージョンを含む商用ファイルエディター。このプログラムは、パッケージドキュメントやコンテナーファイルなどの EPUB固有のファイルに対して、リアルタイム検証とコード補完も提供します。
- Pagina EPUB-Checker — EPUBCheckを実行するための無料のグラフィカルインターフェイス。ドイツ語、フランス語、スペイン語、日本語を含む多数の異なる言語で利用できます。
追加の代替手段については、 EPUBCheck wikiで確認できます。