はじめに

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 のようなウィンドウが表示されるはずです。

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

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

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

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

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

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

注意:

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

次のステップ

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

上に戻る

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

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

• プレーンテキスト・フォーマットで保存できるテキスト・エディター、またはワード・プロセッサー。行番号の表示機能は必ずしも必要ではありませんが、あると便利です(検証フェーズで検出されるエラーは行番号でレポートされるため)。Linux やUNIX® のエディターの大部分は (vi や emacs を含めて)、常に、あるいはユーザー・オプションとして行番号を表示します。
• 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 のようなメッセージ・ボックスが表示されるはずです。

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

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

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

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

注意:

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

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

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

注意:

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

次のステップ

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

参考文献

学ぶために

• 「developerWorks の XML テンプレートを使ったオーサリング」(developerWorks、2008年12月): 私達が用意した完璧な指示書と、ダウンロード可能なオーサリング・パッケージを使って、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エディターです。
  
  
• IBM trial products for download: 皆さんの次期開発プロジェクトを、IBM の試用ソフトウェアを使って構築してください。developerWorks から直接ダウンロードすることができます。
  
  

議論するために

• Content submission form: 記事やチュートリアルの案を developerWorks に送り、developerWorks の編集者と話を始めてください。content wish list を見ると、どんな内容の記事やチュートリアルが求められているかを知ることができます。
  
  
• developerWorks editor contact info: 質問がある場合には、皆さんが関心を持った技術ゾーンや製品ゾーンの編集者に連絡してください。
  
  

著者について

Ian Shields は、developerWorks Linux ゾーンの様々な Linux プロジェクトに関わっています。彼はノースキャロライナ州 Research Triangle Park にある IBM のシニア・プログラマーです。1973年にオーストラリアのキャンベラでシステム・エンジニアとして IBM に入社して以来、カナダのモントリオールやノースキャロライナ州 Research Triangle Park で、コミュニケーション・システムやパーベイシブ・コンピューティングに携わってきました。彼はいくつかの特許を保持しています。Australian National University にて純粋数学および哲学で学位を取得し、また North Carolina State University にてコンピューター・サイエンスで修士と博士を取得しています。

この記事を評価する

コメント

上に戻る

目次

• はじめに
• Microsoft Windows を使う場合
• Linux や、他のオペレーティング・システムを使う場合
• 参考文献
• 著者について
• コメント