developerWorks の XML 検証ツールを使う

developerWorks で公開する記事やチュートリアルを作成するためのオプション・ツール

Comments

はじめに

developerWorks で公開する記事またはチュートリアルを作成するためには、次の3 つのステップが必要です。

  1. 執筆者パッケージ (author package) をダウンロードし、ファイルを解凍する。
  2. 記事用の XML テンプレート、あるいはチュートリアル用のテンプレートをコピーする。
  3. XML テンプレートを編集し、記事またはチュートリアルの内容を追加した後、その XML をスキーマに対して検証し、間違いを修正する。
  4. 記事またはチュートリアルをブラウザーでプレビューし、developerWorks でどのように表示されるかを確認する。

まず、記事「developerWorks の XML テンプレートを使ったオーサリング」のステップ 1 とステップ 2 を読み、その 2 つのステップを終えてください。この記事は、必要なツールやすべてのファイルを含んだ執筆者パッケージのダウンロード方法を説明しています。また、記事やチュートリアルの内容を構成し、送信するための方法も説明しています。

そのステップ 1 とステップ 2 を終えたら、この記事に戻ってきてください。そうすると、執筆者パッケージがダウンロードされて自分のハードディスクに解凍されており、またテンプレートのコピーが、記事で述べられていた (新しいチュートリアルまたは新しい記事用の) ツールを使って作成されているはずです。これで、残ったステップを進める準備ができました。では下記に説明する手順に従って、記事またはチュートリアルの内容を編集し、検証し、そしてプレビューしましょう。

Microsoft Windows を使う場合

必要なものは以下のとおりです。

  • プレーンテキスト・フォーマットで保存できるテキスト・エディター、またはワード・プロセッサー。行番号の表示機能は必ずしも必要ではありませんが、あると便利です(検証フェーズで検出されるエラーは行番号でレポートされるため)。Windows XP のメモ帳は、メニュー・オプションで 表示 > ステータス バー を選択すれば行番号を表示します。ただし、このオプションは Windows XP 以前のバージョンの Windows のメモ帳では利用できないことに注意してください。
  • MSXML (Microsoft's XML Parser) のバージョン 4 またはバージョン 6 (このパーサーの入手方法は、「参考文献」のセクションにあげたリンクを参照してください)。Windows Vista ユーザーの場合、Vista に含まれている MSXML バージョン 6 を使用する必要があります。
  • Internet Explorer 6 または 7、あるいは Mozilla や Firefox、Opera などのWeb ブラウザー。

ステップ 1: XML ファイルを編集する

新しいフォルダーまでナビゲートし、適当なテキスト・エディターを使ってファイル(index.xml) を編集します。他に特別なエディターを持っていない場合には、Notepadでも十分です。index.xml テンプレート・ファイルの中にある詳細なコメントに従ってください。これらのコメントを読むと、何をすべきかがよく理解できるはずです。

ワード・プロセッサーを使っている場合には、必ずプレーンテキストとしてファイルを保存します。同様に、MicrosoftWord ファイルなど、組み込みのフォーマットを持つファイルからカット・アンド・ペーストする場合は、そのエディターの機能(形式を選択して貼り付け) を使って、テキストとして貼り付けます。あるいは、そのXML ファイルをプレーンテキストとして保存します。ファイルの名前を index.xmlから変更してはいけません。また、developerWorks の編集者は XML バージョンで作業するため、このツールで生成されるHTML ファイル (index.html) を編集してはいけません。写真やスクリーン・ショットなどの画像は、記事またはチュートリアル用に作成したディレクトリー(この例の場合では my-article) に保存します。

ステップ2: XML を検証する

記事またはチュートリアルを編集する際には、加えた変更をスキーマに対して検証する必要があります。XMLに慣れていない場合には、検証しながら編集を進めるようにお勧めします。そうした方が、間違いを容易に見つけることができます。

新しい記事またはチュートリアルを作成する際には、XML を検証するためのツールがプロジェクト・ディレクトリーにインストールされています。記事またはチュートリアル用のディレクトリーの中にあるdw-transform.vbs スクリプトをクリックします。Windows の設定によっては、単純にdw-transform として表示されるかもしれません。図 1 のようなウィンドウが表示されるはずです。

図 1. dw-transform スクリプトを使って記事を検証する
dw-transform スクリプトを使って記事を検証する
dw-transform スクリプトを使って記事を検証する

ステップ 3: 検証で見つかった問題を修正する

XML コーディング・エラーがあった場合には、エラー出力が表示されます。dw-transformスクリプトを使うと、図 2 に示すようなウィンドウが表示されるはずです。

図 2. 無効な記事 (VB スクリプト・チェッカー)
An invalid article (script checker)
An invalid article (script checker)

この場合は、<u>Underline error!</u> を含めることで意図的にエラーを起こしています。developerWorksの記事やチュートリアルではリンクに下線を付けているため、他の目的でテキストに下線を付けることはありません。従って、このスキーマでは <u> タグと </u> タグを許していません。ツールは最初のエラーの場所を特定し、エラーの理由を表示します。理由はMSXML パーサーによって生成されます。エラーの理由は多少わかりにくいですが、問題の特定に役立つことが多いものです。理由の中に、Expectinga, b, br, ... など、他のタグ名を延々とリストアップしたものが含まれている場合には、タグ名の入力を間違えたか、あるいは developerWorks スキーマがサポートしていないタグを使おうとしたことが考えられます。行番号を表示するエディターを使えば、エラーを素早く見つけることができます。図3 を見てください。

図 3. XML の中のエラーを、メモ帳を使って探す
XML の中のエラーを、メモ帳を使って探す
XML の中のエラーを、メモ帳を使って探す

エラーを発見し、修正したら、そのファイルを保存し、再度 dw-transform.vbsを実行してファイルを再チェックします。このプロセスを、エラーがなくなるまで繰り返します。

ステップ 4: 記事またはチュートリアルをプレビューする

エラーがなくなったら、その記事またはチュートリアルが developerWorks でどのように表示されるかをプレビューすることができます。ディレクトリーの中に、index.htmlというファイルがあるはずです。ブラウザーでこのファイルを開き、記事またはチュートリアルの内容をプレビューします。WindowsXP Service Pack 2 で Internet Explorer を使っている場合には、このファイルのアクティブ・コンテンツを表示しないようにInternet Explorer が制限していると警告するポップアップ・ウィンドウと情報バーが表示されるかもしれません。記事またはチュートリアルをプレビューするためには、その情報バーをクリックし、ブロックされているコンテンツを許可… を選択します。

図 4. 記事をプレビューする
記事をプレビューする
記事をプレビューする

注意:

  • スタイルシートの一部はサーバーに含まれているため、プレビューで見えるフォーマットは、developerWorksのスタッフが生成し、サーバー上で公開するフォーマットと完全に同じではありません。
  • チュートリアルは、最終的に公開される時には何ページかに分割されますが、Windows のプレビューでは1 つのページとして表示されます。この 1 つのページでも各セクションの開始位置を見ることができますが、左側のナビゲーション・エリアとチュートリアル本体とのクロス・リンクは、プレビューでは動作しません。ページの分割とリンクは、developerWorksのスタッフが行います。

次のステップ

おめでとうございます。これで記事またはチュートリアルの編集、検証、そしてプレビューが終わりました。今度は「developerWorks の XML テンプレートを使ったオーサリング」に戻り、記事やチュートリアルの内容を完成させて developerWorks 編集者に送信するためのヒントを学んでください。

Linux や、他のオペレーティング・システムを使う場合

必要なものは以下のとおりです。

  • プレーンテキスト・フォーマットで保存できるテキスト・エディター、またはワード・プロセッサー。行番号の表示機能は必ずしも必要ではありませんが、あると便利です(検証フェーズで検出されるエラーは行番号でレポートされるため)。Linux やUNIX® のエディターの大部分は (viemacs を含めて)、常に、あるいはユーザー・オプションとして行番号を表示します。
  • IBM Developer Kit for Java Version 5.0 またはそれ以降。RPM からではなく tarball からインストールする場合は、/opt/ibm に解凍してください。IBM JRE (Runtime Environment for Java 2) は必要な Xalan 機能や Xerces 機能を含んでいる上、他の Java 実装がインストールされていてもインストールすることができます。ダウンロード用のリンクは、この記事の「参考文献」セクションにあります。別の Java ランタイム・キットや開発キットを使っていて、その Java のバージョンに Apache Xalan Version 2.7 またはそれ以降のパッケージ (必要な Xerces を含んでいます) が含まれていない場合には、このパッケージも必要です。また、developerworks/tools/dwxmlxslt.shスクリプトを修正するか、あるいは CLASSPATH 環境変数を設定する必要もあるかもしれません。
  • グラフィカル環境を使用している場合は、ご使用の GNOME または KDE デスクトップに対応する zenity、gdialog、または kdialog パッケージが必要です。非グラフィカル環境を使用している場合は、dialog パッケージが必要です。
  • Mozilla や Firefox、Opera などのグラフィカル・ブラウザー

ステップ 1: XML ファイルを編集する

新しいフォルダーまでナビゲートし、適当なテキスト・エディターを使って XMLファイルを編集します。index.xml ファイルの中にある詳細なコメントに従ってください。ワード・プロセッサーを使っている場合には、必ずプレーンテキストとしてファイルを保存します。ファイル名をindex.xml から変更してはいけません。写真やスクリーン・ショットなどの画像を、記事またはチュートリアル用に作成したディレクトリー(この例の場合では my-tutorial) に保存します。

ステップ 2: XML を検証する

記事またはチュートリアルを編集する際には、加えた変更をスキーマに対して検証する必要があります。XMLに慣れていない場合には、検証しながら編集を進めるようにお勧めします。そうした方が、間違いを容易に見つけることができます。

新しい記事またはチュートリアルを作成する際には、その記事またはチュートリアルを検証するためのツールがディレクトリーにインストールされています。そのディレクトリーの中にあるdw-transform.sh スクリプトを実行します。KDE または GNOME デスクトップを実行している場合には、これをグラフィカル・マネージャー(Nautilus や Konqueror など) から実行します。それ以外の場合は、ターミナル・ウィンドウの中でスクリプトを実行します。

初めて検証スクリプトを実行するときには、適合するバージョンの Java が検索されます。これには少しだけ時間がかかるかもしれません。適切な Java 実行環境が見つかると、tools ディレクトリーにある dwjava.txt というファイルにそのパスが保存されます。これ以降は、処理を高速にするためにこのパスが最初に確認されます。このファイルが削除されたり、あるいはこのファイルに記述されているパスが無効になったりした場合には、新たに検索が実行されます。

すべてがうまくいっていれば、しばらくすると図 5 のようなメッセージ・ボックスが表示されるはずです。

図 5. dw-transform シェル・スクリプトを使ってチュートリアルを検証する
dw-transform シェル・スクリプトを使ってチュートリアルを検証する
dw-transform シェル・スクリプトを使ってチュートリアルを検証する

ステップ 3. 検証で見つかった問題を修正する

XML コーディング・エラーがあった場合には、メッセージ・ボックスに図 6 のようなエラーが表示されるはずです。

図 6. 無効なチュートリアル (シェル・スクリプト・チェッカー)
無効なチュートリアル (シェル・スクリプト・チェッカー)
無効なチュートリアル (シェル・スクリプト・チェッカー)

この場合は、<u>Underline error!</u>を含めることで意図的にエラーを起こしています。developerWorksの記事やチュートリアルではリンクに下線を付けているため、他の目的でテキストに下線を付けることはありません。従って、このスキーマでは<u> タグと </u> タグを許していません。ツールは最初のエラーの場所を特定し、その理由を表示します。理由はJava パーサーによって生成されます。エラーの理由は多少わかりにくいですが、問題の特定に役立つことが多いものです。もし理由の中に、One of '{" など、他のタグ名を延々とリストアップしたものが含まれている場合には、タグ名の入力を間違えたか、あるいは (この例の場合のように) developerWorks スキーマがサポートしていないタグを使おうとしたことが考えられます。行番号を表示するエディターを使えば、エラーを素早く見つけることができます。図 7 を見てください。

図 7. チュートリアルのエラーを gedit エディターを使って探す
チュートリアルのエラーを gedit エディターを使って探す
チュートリアルのエラーを gedit エディターを使って探す

エラーを発見し、修正したら、そのファイルを保存し、再度 dw-transform.shスクリプトを実行してファイルを再チェックします。このプロセスを、エラーがなくなるまで繰り返します。

注意:

  • 適切な開始タグが使われていて、それに対応する終了タグがない、などの一部のエラーでは、エラー表示に行番号が付きませんので、検証は頻繁に行う必要があります。
  • 記事またはチュートリアルをインデントするためにタブを使っていると、エディターに表示される列番号とエラー・メッセージの中でレポートされる列番号とが一致しないことがあります。

ステップ 4. 記事またはチュートリアルをプレビューする

エラーがなくなったら、その記事またはチュートリアルが developerWorks でどのように表示されるかをプレビューすることができます。ディレクトリーの中に、index.htmlというファイルがあるはずです。ブラウザーでこのファイルを開き、記事またはチュートリアルをプレビューします。

図 8. チュートリアルをプレビューする
チュートリアルをプレビューする
チュートリアルをプレビューする

注意:

  • スタイルシートの一部はサーバーに含まれているため、プレビューで見えるフォーマットは、developerWorksのスタッフが生成し、サーバー上で公開するフォーマットと完全に同じではありません。
  • Linux 変換ツールは、最終的に公開されるページと似た何ページかの html ページを生成するため、左側のナビゲーション・エリアを使うと、そのチュートリアルのセクション間、あるいはセクション内をナビゲートすることができます。

次のステップ

おめでとうございます。これで記事またはチュートリアルの編集、検証、そしてプレビューが終わりました。今度は「developerWorks の XML テンプレートを使ったオーサリング」に戻り、記事やチュートリアルの内容を完成させて developerWorks 編集者に送信するためのヒントを学んでください。


ダウンロード可能なリソース


関連トピック

  • Authoring with the developerWorks Word and Writer templates」(developerWorks、2008年3月): XML テンプレートの代わりに Microsoft Word または OpenOffice.org Writer で記事を書きたい方のために、Word および Writer 用のテンプレートも用意してあります。
  • 「Illustrating your article or tutorial for developerWorks: How to create effective graphics」(developerWorks、2008年7月): 記事やチュートリアルのためのグラフィックスを作成し、送信するための詳細なガイドラインとヒントを手に入れてください。
  • developerWorks 執筆者のガイドラインおよび編集方針: developerWorks の編集方針と、developerWorks の各編集者がどんな内容の記事やチュートリアルを望んでいるのかを知ってください。
  • Microsoft's XML Parser (MSXML) バージョン 4 またはバージョン 6: 記事やチュートリアルの変換に dw-transform.vbs スクリプトを使うためには、MSXML パーサーのバージョン 4 またはバージョン 6 のいずれかが必要です。必要なファイルは、バージョン 4 の場合は msxml.msi、バージョン 6 の場合は msxml6.msi です。
  • IBM Developer Kit for Java, Version 5.0: 記事やチュートリアルの変換に Linux で dw-transform.sh スクリプトを使うためには、IBM Developer Kit for Java, Version 5.0 以上が必要です。
  • Apache Xalan: IBM Developer Kit for Java を使わず、Linux ツール (dw-transform.sh) を使っている場合には、Apache Xalan が必要かもしれません。
  • XML Copy Editor は、XML の妥当性検証と XML ファイルの変換ができる、無料の高速な XMLエディターです。

コメント

コメントを登録するにはサインインあるいは登録してください。

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=XML
ArticleID=239921
ArticleTitle=developerWorks の XML 検証ツールを使う
publish-date=12042008