本家XMLドキュメントのHTML変換ガイド

1.はじめに

ドキュメントを翻訳した後、実際に表示される内容で確認したいと思ったことはありませんか? また、査読中にXMLタグがちょっと邪魔だなと思ったことは? それとも、翻訳した時にXMLタグを消してしまって文法エラーがあるかも…とちょっと不安になりませんか?

このドキュメントは本家のXMLドキュメントを実際にHTMLへ変換する実例を示しながらわかりやすく説明しますので、そんなあなたに打って付けのものになるはずです。なお、このドキュメントはDocumentation Development Tips & Tricksを参考に作成されています。

2.必要なファイルの準備

ファイルを保存するディレクトリ(フォルダ)を作成する 

まず、変換したいXMLドキュメントを置くディレクトリを作成します。このドキュメントでは、このディレクトリをGentoo Linuxの場合は~/jadoc、Windowsの場合はC:\jadocに作成したものとして説明していきます。

次に、作成したディレクトリにサブディレクトリを作成します。以下に挙げるディレクトリを作成してください。

必要なファイルをダウンロードして準備する 

ちょっと大変ですが、HTMLに変換するために必要なファイルを準備しましょう。

以下に挙げるファイルを先ほど作成したディレクトリに保存してください。その際、書かれているディレクトリと同じ場所にファイルを置くようにしてください。つまり、guide.dtdならば~/jadoc/dtd(C:\jadoc\dtd)に、main.cssならば~/jadoc/css(C:\jadoc\css)というように保存してください。

• dtd/guide.dtd
• dtd/book.dtd
• css/main.css
• images/gbot-s.gif
• images/gridtest.gif
• images/gtop-s.jpg
• images/line.gif
• images/netraverse-gentoo.gif

そして、SwifTさんのウェブスペースからローカルで変換できるようにした特別なguide.xslをxslディレクトリにダウンロードします。Windows環境やブラウザを使った場合、guide.xslの拡張子がxmlに変わってしまったり、xslの後にxmlが付いてしまうことがありますので気を付けてください。

実際に変換を行うために準備をする必要があります。Gentooをお使いの場合は、実行準備 - Gentoo編に、Windowsをお使いの場合は実行準備 - Windows編に進んでください。

3.実行準備 - Gentoo編

変換と文法チェックに必要なパッケージをインストールする 

Gentooですので、インストールはemergeするだけですね。

emerge libxml2 libxslt

そして、/etc/xml/catalogに以下の内容を追加します。hogeの部分はユーザー名を入れてください。

<rewriteURI uriStartString="/dtd" rewritePrefix="/home/hoge/jadoc/dtd"/>

さあ、実行する準備ができました。実行へ進んで実際に試してみてください。

4.実行準備 - Windows編

変換と文法チェックに必要なパッケージをインストールする 

まず、http://xmlsoft.org/sources/win32/から次のファイルをダウンロードします。

• iconv-1.9.1.win32.zip
• libxml2-2.6.15.win32.zip
• libxslt-1.1.12.win32.zip
• zlib-1.2.1.win32.zip

次に、それらを適当なフォルダに解凍します。拡張子(.zip)を除いた部分のフォルダが自動的に作成されますが、必要なのはそのフォルダに入っているbin、lib、include、utilフォルダだけです。C:\xsltprocというフォルダを作成し、その中に前述のフォルダを移動してください。(上書きの確認ダイアログではすべて上書きを選んでください)

さらに、環境変数のPATHに2つのディレクトリを追加し、新しい環境変数SGML_CATALOG_FILESを作成します。

環境変数PATHは次のように設定します。ただし、既にユーザーの環境変数でPATHを設定している場合は、新規ボタンを押すかわりに変数PATHの部分を選択して編集ボタンをクリックします。そして、既に設定されている変数値の最後に;C:\xsltproc\bin;C:\xsltproc\libを追加してください。

1. コントロールパネルでシステムを開き、詳細設定タブをクリックします。
2. 環境変数ボタンをクリックします。
3. ユーザーの環境変数の所の新規ボタンをクリックします。
4. 変数名にPATHと入力し、変数値にC:\xsltproc\bin;C:\xsltproc\libと入力してOKをクリックします。

続いて、環境変数SGML_CATALOG_FILESを設定します。

1. ユーザーの環境変数の所の新規ボタンをクリックします。
2. 変数名にSGML_CATALOG_FILESと入力し、変数値にC:\xsltproc\catalog.txtと入力してOKをクリックします。
3. 後は、OKを何度かクリックしてシステムのプロパティを閉じます。

最後に、以下の内容を記述したテキストファイルを作り、C:\xsltproc\catalog.txtとして保存します。

<?xml version="1.0"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN"
 "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
<rewriteURI uriStartString="/dtd" rewritePrefix="C:/jadoc/dtd"/>
</catalog>

さあ、実行する準備ができました。実行へ進んで実際に試してみてください。

5.実行

一般的なドキュメントをHTMLに変換する 

変換したいXMLドキュメントをjadocディレクトリに入れましたか? それでは実行してみましょう。(ここでは変換したいXMLドキュメントのファイル名をhoge.htmlとして説明しています)

Gentooの場合は、コンソールや端末エミュレータで次のコマンドを入力してください。

cd ~/jadoc
xmllint --valid --noout hoge.html
xsltproc --novalid xsl/guide.xsl hoge.html > hoge.html

Windowsの場合は、コマンド プロンプトを実行して次のコマンドを入力してください。

C:
cd \jadoc
xmllint --catalogs --valid --noout hoge.html
xsltproc --catalogs xsl\guide.xsl hoge.html > hoge.html

エラーが出なかったら、jadocディレクトリを見てみましょう。hoge.htmlができているはずです!

ハンドブックをHTMLに変換する 

まず、変換したいハンドブックのアーキテクチャのトップにあたるXMLドキュメントをViewCVS経由で入手し、最初に作成したXMLドキュメントを置くディレクトリに保存します(例えばhandbook-x86.html)。また、変換したいハンドブックのXMLドキュメントも同様にします。

次に、変換したいXMLドキュメントがどのパートのどの章なのかを調べます。Gentoo.orgのハンドブックを見て確認してください。例えば、「Gentoo Linuxのインストールについて」(hb-install-about.html)はパート1の1章です。

最後に、xsltprocのオプションとしてパート番号(part)と章番号(chap)を与えてHTMLへ変換します。変換したい章に合わせて設定してください。この例ではパート1の1章、hb-install-about.htmlを変換しています。

xmllint --valid --noout handbook-x86.html
xmllint --valid --noout hb-install-about.html
xsltproc --stringparam part 1 --stringparam chap 1 xsl/guide.xsl handbook-x86.html > hb-install-about.html

xmllint --catalogs --valid --noout handbook-x86.html
xmllint --catalogs --valid --noout hb-install-about.html
xsltproc --catalogs --stringparam part 1 --stringparam chap 1 xsl/guide.xsl handbook-x86.html > hb-install-about.html

エラーが出なかったら、jadocディレクトリを見てみましょう。hb-install-about.htmlができているはずです!

xmllint実行時に警告・エラーが出ます... 

xmllintはXMLの文法をチェックするコマンドです。ここでエラーが表示された場合、XMLドキュメントに文法的なエラーがある可能性があります。行番号も一緒に表示されますのでそのあたりを重点的に見直してみてください。

タグの閉じ忘れなどのエラーの場合、一つ閉じ忘れただけでいくつもエラーが表示されてしまう事があります。この場合、一番最初に表示されたエラーを修正するだけで解決することがほとんどですので、安心してください。

6.うまくいかない時は?

気軽にdocs MLにメールを出してください。:-)