developerWorks の XML テンプレートを使ったオーサリング

developerworks ディレクトリーはルート・ディレクトリーにある必要はなく、Windows の C:\ ドライブにある必要もありません。しかし一連のツールは、developerworks ディレクトリーとそのサブディレクトリーの中にファイルがあると想定しているため、developerworks のディレクトリー構造とファイル名は、変更せずそのままにしておいてください。

Linux をご使用の場合は、IBM Developer Kit for Java もダウンロードして (リンクについては参考文献を参照してください)、/opt/ibm にインストールしてください (tarball を使用している場合)。検証ツール (「developerWorks の XML 検証ツールを使う」で説明されています) は、Xalan を含む Java のバージョン (Xalan 2.7 を含む Java バージョン 5.0) でのみ動作します。

ファイルを解凍すると、下記のサブディレクトリーを含んだ developerworks ディレクトリー (またはフォルダー) が見えるはずです。

• readme -- readme.html ファイルを含んでいます。この readme ファイルによって、皆さんが今読んでいる、この記事にリンクされます。
• schema -- スキーマ・ファイルを含んでいます。メインのスキーマ・ファイルの名前は、dw-document-5.10.xsd です (5.10 は この記事の執筆時点での developerWorks スキーマのレベルです)。
• tools -- 2 つのテンプレート (template-dw-article-5.10.xml と template-dw-tutorial-5.10.xml) と、新しい記事を設定し、検証するための単純なツールをいくつか含んでいます。java サブディレクトリーは Linux の検証、変換ツールで使われる Java™ プログラムのソースを含んでおり、必要な場合には、これを利用してツールを修正したり再ビルドしたりすることができます。
• web -- 記事またはチュートリアルをプレビューするために必要な画像と JavaScript を含んでいます。
• xsl -- プライマリー・スタイルシート・ファイル dw-document-html-5.10.xsl と、いくつかのセカンダリー・スタイルシートを含んでいます。

執筆者パッケージに含まれるファイルやツールは、Linux または Windows で使うように作られています。Windows または Linux 以外のオペレーティング・システムを使ってテンプレートを編集するために補助が必要な場合には、developerWorks の担当編集者に連絡してください。

上に戻る

リリースに関する注意

ステップ 2 に進む前に、今回のリリースで何が変更されたのかを調べてみましょう。

2008年3月21日に、バージョン 5.10 のスキーマとスタイルシートがリリースされました。このスキーマとスタイルシートには、ソーシャル・タギングおよびデータ管理の最新 Web 技術を最大限に利用するための内部的な変更が含まれています。執筆者が気になるところの外部的な変更は最小限に抑えられていて、記事およびチュートリアルの最新のテンプレートには次の内容が反映されています。

• コードのリストで、不要な改行を入れなくても単一行内に強調表示 (太字、斜字体、および通常のテキスト) を混在させることができるようになりました。
• コードのリストで開始および終了タグをセットで使うことで、複数行の強調表示 (太字あるいは斜字体) もサポートします。
• 「Component」、「Grid」、「Systems」、「Unicode」、「Wireless」、および「Workplace」はコンテンツ・エリアとして選択できなくなりました。

author-package の zip ファイルと、この記事は、5.10 リリースに準拠しています。皆さんが記事またはチュートリアルを準備する際には、5.10 のスキーマとスタイルシートを使う必要があります。これ以前のリリースの developerWorks スキーマとスタイルシートを使っている場合には、下記の「ダウンロード」セクションから、5.10 の author-package.zip ファイルをダウンロードする必要があります。

記事もチュートリアルも、同じプライマリー・スキーマ (xsd ファイル) と同じプライマリー・スタイルシート (xsl ファイル) を使います。これらは次のとおりです。

• プライマリー・スキーマ: dw-document-5.10.xsd
• プライマリー・スタイルシート: dw-document-html-5.10.xsl

上に戻る

ステップ 2. 新しいテンプレートを作成する

このステップでは、記事またはチュートリアルのためのテンプレート・コピーを、執筆者パッケージのツールを使って自分専用に設定します。このステップで、index.xml という新しいファイルが別のディレクトリーに作成されます。また適切なパスが設定され、そしてさまざまなオペレーティング・システム環境で適切に動作するように、テンプレートの調整も行われます。

Microsoft Windows を使う場合

developerworks ディレクトリーの中で、記事を作成する場合は new-article.vbs を、チュートリアルを作成する場合は new-tutorial.vbs をクリックします。フォルダー名には、有効な名前であれば任意の名前を選ぶことができます。デフォルトは、my-article と my-tutorial です。

OK をクリックすると、developerworks フォルダーの中に新しいフォルダーが見えるはずです。場合によっては、(表示 > 最新の情報に更新を使って) 最新の情報に更新する必要があるかもしれません。この新しいフォルダーには、記事またはチュートリアルのテンプレート (index.xml) と、検証と変換のためのスクリプト (dw-transform.vbs) が含まれています。

Linux を使う場合

developerworks ディレクトリーの中にある、new-article.sh または new-tutorial.sh シェル・スクリプトを使います。(KDE または GNOME デスクトップを実行している場合には、これをグラフィカル・マネージャー (Nautilus や Konqueror など) から実行します。それ以外の場合は、ターミナル・ウィンドウの中でスクリプトを実行します。) 新しいプロジェクトの名前を入力するためのダイアログ・ボックスが表示されます。有効な名前であれば任意の名前を選ぶことができます。デフォルトは my-article と my-tutorial です。

OK をクリックすると (あるいは Enter を押すと)、developerworks フォルダーの中に新しいフォルダーが見つかるはずです。この新しいフォルダーには、記事またはチュートリアルのテンプレート (index.xml) と、検証と変換のためのスクリプト (dw-transform.sh) が含まれています。

グラフィカル環境を使用している場合は、ご使用の GNOME または KDE デスクトップに対応する zenity、gdialog、または kdialog パッケージが必要です。非グラフィカル環境を使用している場合は、dialog パッケージが必要です。

上に戻る

ステップ 3: XML を編集し、検証する

XML ソースを編集し、検証するための基本的な方法には 2 種類があり、どちらを使うこともできます。

検証用の XML エディターを使う

XML エディターを使って XML の編集と検証を行うと、編集しながらエラーを見つけることができます。Windows の場合も Linux の場合も、市場には商用の XML エディターが数多くあります。その中から 3 つ例をあげると、Rational® Web Developer for WebSphere® Software と <oXygen/>、そして Altova XMLSpy があります (ダウンロードやドキュメンテーションに関しては、「参考文献」のリンクを参照してください)。どれも試用版を無料でダウンロードできるので、これらの製品に付属の説明を読み、使い方を学んでみるようにお勧めします。これらの製品や、あるいは他の商用 XML エディターを使って記事またはチュートリアルを作成するために必要なファイルやサポート・ファイルは、すべて developerWorks の author-package.zip ファイルの中に含まれています。

無料で入手できる XML エディターもいくつかあります。Altova は、上にあげた商用版の XMLSpy の他に、XMLSpy の Home Edition を無料で提供しています。また、XML 文書を用意するために使用可能な Eclipse プラットフォーム用のプラグインも入手することができます。「参考文献」のリンクを参照してください。

検証用の XML エディターまたはワークベンチを使う場合には、次のことに注意してください。

• このテンプレートでは、スキーマ・ファイルやスタイルシート・ファイルへの参照は、チュートリアルまたは記事のディレクトリーに対する相対参照で行っています。そのため、参照 (..\schema\5.10\dw-document-5.10.xsd と ..\xsl\5.10\dw-document-html-5.10.xsl) を C:\developerworks\schema\5.10\dw-document-5.10.xsd のような絶対参照に変更する必要があります。一部のエディターでは、こうしたファイルの位置を、他の設定手段を使って指定する必要があるかもしれません。
• XML エディターの中でチュートリアルまたは記事を変換した場合、もし画像がまったく表示されないのであれば、そのエディターが、一時的な保存に使うディレクトリーの中に HTML ファイルを作成した可能性があります。その場合には、生成された HTML ファイルを本来の記事のディレクトリー (この例では my-article) に保存し、その XML エディターの GUI の中で、あるいはブラウザーでファイルを開く必要があります。

テキスト・エディターと検証ツールを使う

もし検証用の XML エディターに適当なものがなければ、あるいはその使い方を学ぶために時間を費やしたくないのであれは、任意のテキスト・エディターを使って XML テンプレートを編集することができます。そして、執筆者パッケージの中に用意されたツール (Windows の場合は dw-transform.vbs、Linux の場合は dw-transform.sh) を使ってその XML を検証し、HTML に変換します。そうすると、その HTML をブラウザーで見ることができます。こうした単純なツールの使い方の詳細は、この記事とセットになったもう一方の記事、「developerWorks の XML 検証ツールを使う」を参照してください。

上に戻る

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

記事またはチュートリアルのプレビューを見ると、最終的な出力がどのように見えるかの概略をつかむことができます。しかし、プレビューで見えるものと最終的な出力との間には少し違いがあります。記事またはチュートリアルをプレビューする際には、内容に注目し、プレゼンテーションやスタイルの問題は気にしないでください。私達が最終的な編集を行う際に、必要な変更を加えます。

検証用の XML エディターを使う場合には、そのエディターのドキュメンテーションの説明をよく調べてから XML から HTML ファイルに変換し、そしてそのファイルをブラウザーで見てみます。一部のエディターは、このステップを単純にするためにブラウザー・プレビュー・オプションを持っています。

テキスト・エディターと developerWorks のスクリプトを使う場合には、出力の HTML は、記事またはチュートリアルのフォルダーの中に作成されます。ブラウザーで index.html を開きます。こうしたスクリプトの使い方の詳細は、「developerWorks の XML 検証ツールを使う」を参照してください。

上に戻る

構成のヒント

XML のマークアップに慣れていない人は 他の XML 文書と同様、執筆者パッケージの中の XML テンプレートも以下のルールに従っています。 XML タグ ( < と > との間の文字列) は小文字です。 XML タグは、通常は開始タグと終了タグの対になっています。例えば、<title> タグと </title> タグは、記事またはチュートリアルのタイトルのための開始タグと終了タグです。 記事またはチュートリアルの内容は、タグとタグの間に入ります。例えば <title>Groovy の成長が加速</title> のようになります。 対とはならない例外的なタグとして、改行タグ (<br />) や画像タグ (<img />) など、1 つのタグで開始タグと終了タグの両方を兼ねるものがあります。この場合のタグは、/> で終了します。 コメント行は <!-- と --> とで囲まれています。

XML テンプレートは、記事またはチュートリアルを作成する上で最も頼りになる、包括的なヒントでもあります。テンプレートの中の詳細なコメント (tools ディレクトリーの中の template-dw-article-5.10.xml と template-dw-tutorial-5.10.xml) を読むと、記事またはチュートリアルをコーディングする際のすべての作業の参考になるはずです。その他のヒントとして、以下のことを知っておくと便利でしょう。

• Microsoft Word または OpenOffice Writer で作成する場合。

  XML テンプレートの代わりに Word または Writer のテンプレートを使用することができます。詳細については「Authoring with the developerWorks Word and Writer templates」を参照してください。

• 他のファイル・フォーマットから XML テンプレートにカット・アンド・ペーストすることもできます。Word ファイルや Writer ファイルなど、組み込みの書式を持つファイルからカット・アンド・ペーストする場合は、そのエディターの機能 (形式を選択して貼り付け) を使って、テキストとして貼り付けます。あるいは、カット・アンド・ペーストする前に、そのファイルを TXT ファイルとして保存します。書式設定されたファイルから、直接カット・アンド・ペーストしてはいけません。また、Word または Writer の文書に画像が組み込まれている場合、その画像を抽出する必要はありません。developerWorks の編集者にその文書をそのまま送ってください。ビジュアル・デザイナー・チームが画像を抽出して再加工します。そして最後に、文書で変更履歴を記録していた場合には、XML テンプレートにカット・アンド・ペーストする前に必ずすべての変更を反映してください。そうしなければ、削除した部分がすべて、コピーしたテキストの間に再び出現してしまいます。
  
  
• 終了タグについて。終了タグを使うことを忘れないでください。終了タグを使うことを忘れないこと。例えば、段落タグ (<p>) には必ず終了タグ (</p>) が必要です。また、改行タグ (<br />) や画像タグ (<img />) などの空要素は、終了スラッシュが必要です。
  
  
• 使用しないタグについて。span タグやフォントを変更するための code タグ、CDATA セクション、font タグは避けてください。
  
  
• コードのリストについて。記事またはチュートリアルの本文中にサンプル・コードのリストを含める場合には、以下の内容を守ってください。
  
  
  • 行の長さは、空白を含めて 90 文字以下にする。
    
    
  • リストの長さは、空行を含めて 100 行以下にする。
    
  • コードのリストが 100 行を超える場合は、複数のリストに分割するか、特に重要な部分だけを抜粋して、コードのリスト全体は記事またはチュートリアルの「ダウンロード」セクションからダウンロードできるサンプル・コードとして提供することを検討してください。
    
  • サンプル・コード行の最後に空白やタブをハードコーディングすることは避ける。
    
    
  • サンプル・コード行の最初にタブは使わない。インデントが必要な場合は空白を使ってください。
    
    
  • CDATA セクションは使わない。サンプル・コードで不等号括弧や XML タグを表示する必要がある場合は < および > を使用してください (そのほかの特殊記号については表 1 を参照してください)。
    
  • 色は使わない。サンプル・コードの一部を強調表示したい場合には、太字 (<b> と </b>) を使います。
    
    
• サンプル・コードをダウンロードできるようにする場合。記事またはチュートリアルの「ダウンロード」セクションからサンプル・コードをダウンロードできるようにしたい場合には、コードを zip で圧縮し、その ZIP ファイルを編集者宛に別途送ってください。
  
  
• アートワークについて。スクリーン・ショットを含め、すべてのアートワーク・ファイルは JPG または GIF ファイルとして作成し、画像の幅が、記事の場合は 572 ピクセル、チュートリアルの場合は 500 ピクセルを超えないようにします。アートワーク・ファイルは編集者に送ってください。効果的なグラフィックスを作成し、提供するための詳細については、「Illustrating your article or tutorial for developerWorks」を参照してください。
  
  
• 特殊文字について。特殊文字は CDATA セクションを使用せず、以下のようなコードにしてください。
  
  

  表 1. 特殊文字

  文字	XML コード
  アンパーサンド (&)	& (アンパーサンドは、URL の場合も必ず & としてください。)
  アポストロフィ (')	'
  より大記号 (>)	>
  より小記号 (<)	&lt;
  長いダッシュ (—)	<mdash />
  引用符 (")	&quot;
  登録商標 (®)	<reg/> (執筆者は登録商標記号を挿入しても構いませんが、その必要はありません。登録商標への対応は developerWorks の編集スタッフが行います。)
  商標 (™)	<trade/> (執筆者は登録商標記号を挿入しても構いませんが、その必要はありません。登録商標への対応は developerWorks の編集スタッフが行います。)

  
  
  

  例えば、コード・セクションに不等号括弧を含めるための

  <TABLE border="0" width="100%">

  
  

  は、XML テンプレートでは次のようにコーディングします。

  <TABLE border="0" width="100%">

• コメント行について。記事またはチュートリアルを作成しながら内容を正確に見るために、タグに慣れたら記事ファイルからコメント行を自由に削除して構いません。

上に戻る

強調表示する場合の原則

どんなものに <code type="inline"> タグが必要で、どんなものに必要ないのか。本の題名には斜字体を使うのか、引用符を使うのか。どんな時に太字を使うべきなのか。また、強調表示が必要ないのはどんな場合なのか。表 2 は、developerWorks の記事の中で強調表示を行う場合に推奨される原則の一覧です。

上に戻る

記事またはチュートリアルを developerWorks に送信する

皆さんの作品が完成すると、その作品を developerWorks の編集者に送る準備ができたことになります。記事またはチュートリアルの XML ファイルを (関連するグラフィックスやサンプル・コードと共に)、編集者に E メールで送ります。記事で使用するグラフィックスの作成や送信に関する詳細なガイドラインやヒントは、「Illustrating your article or tutorial for developerWorks: How to create effective graphics」を参照してください。

質問や問題がある場合には、担当の編集者に連絡し、相談してください。

上に戻る

ダウンロード

	ダウンロード形式について

参考文献

• 「developerWorks の XML 検証ツールを使う」(developerWorks、2008年3月): テキスト・エディターを使って XML テンプレートを編集したい場合には、執筆者パッケージに含まれているツールを使うことで XML を検証でき、内容をプレビューすることができます。
  
  
• 「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年1月): 記事またはチュートリアルのためのグラフィックスを作成し、送信するための詳細なガイドラインとヒントを手に入れてください。
  
  
• developerWorks 執筆者のガイドラインおよび編集方針: developerWorks の編集方針と、developerWorks の各編集者がどんな内容の記事やチュートリアルを望んでいるのかを知ってください。
  
  

• Microsoft's XML Parser (MSXML): 記事やチュートリアルの変換に dw-transform.vbs スクリプトを使うためには、最新バージョンの MSXML パーサーが必要です。必要なファイルは、msxml.msi です。
  
  
• IBM Developer Kit for Java: 記事やチュートリアルの変換に Linux で dw-transform.sh スクリプトを使うためには、IBM Developer Kit for Java, Version 5.0 以上が必要です。
  
  
• Rational® Web Developer for WebSphere® Software V6.0: 試用版は developerWorks から直接ダウンロードすることができます。
  
  
• IBM trial products for download: 皆さんの次期開発プロジェクトを、IBM の試用ソフトウェアを使って構築してください。developerWorks から直接ダウンロードすることができます。
  
  
• <oXygen/> XML エディター兼 XSLT デバッガー (複数プラットフォーム用) と、Altova XMLSpy (Windows 用): これらの商用 XML エディターの無料試用版について知り、またダウンロードしてみてください。
  
  
• 「EclipseによるXML開発」(developerWorks、2003年4月): Eclipse プラットフォームとプラグイン (Bocaloco Software の XMLBuddy など) を使って XML 文書を作成してください。
  
  

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

著者について

		この記事は developerWorks の編集スタッフが作成しました。

記事の評価

サイト改善のため、ご意見をお寄せください。こちらのフォームからお願いいたします。 この情報はお客様が目的を達成するうえで役に立ちましたか？ はい いいえ わからない   お気軽にご意見・ご感想をお寄せください。   この記事は役に立ちましたか？ 1 2 3 4 5 不充分・不完全である 大変素晴らしい

この記事を共有する はてなブックマーク livedoorクリップ del.icio.us Buzzurl（バザール） Choix！ Saafブックマーク FC2ブックマーク MM/memo ニフティクリップ Yahoo!ブックマーク CZブックマーク newsing

上に戻る