翻訳とオリジナルドキュメント作成環境の構築ガイド

 このガイドでは、GentooJPの翻訳・オリジナルドキュメント作成の際に必要となる環境の構築方法について説明します。
このドキュメントの著作権はAuthorの方に帰属します。

詳しくはオリジナルドキュメントプロジェクトを参照してください。




Contents:

1. GentooJP のドキュメント

2. ドキュメントの構成

3. ドキュメント作成準備

4. ドキュメントの確認方法(HTML)

5. ドキュメントの確認方法(AxKit)

6. ドキュメントの送付方法

著者 : Takashi Ota
改訂者 : 飴谷 茂寛


Updated 14 Nov 2004




1.GentooJP のドキュメント

概要 

gentoo.org と GentooJP では、Webコンテンツ、技術文書などにXML関連技術を活用しています。XML関連技術の活用は、次の点でcoolです。

  • Webデザインを、コンテンツを変えることなく短期間に変更できる。
  • 10個程度の要素タグを覚えることで、誰もが統一化された文書を容易に作成できる。
  • 翻訳ドキュメント、オリジナルドキュメントの反映が即座に可能である。
  • xml文書は、htmlなどに比べて非常に見通しが良い。

Gentoo Linuxは、比較的新しいディストリビューションです。即応性を考え、GentooJPではXML関連技術を通して、さまざまなドキュメントの作成と提供を行います。

ドキュメント作成上の注意点 

ドキュメントの作成を行う場合には以下の点に注意してください。

  • エンコーディング UTF-8、改行コード LFで文書を作成します。
  • 翻訳ドキュメントでは、オリジナルの要素タグを変更しないでください。原則的として変更できるのは、翻訳者の追加のみです。
  • 作成者、作成者メールアドレスが必要になります。個人名、所有メールアドレスを推奨しますが、作成者名にGentooJP、メールアドレスに docs@gentoo.gr.jpを選択することも可能です。

ドキュメント作成の手順 

ドキュメントの作成は次の手順で行ってください。なお、次章以降ではその詳細な手順を説明します。

2.ドキュメントの構成

ここでは、ドキュメントの最低限必要となる項目について解説します。
文書の作成にとてもよいガイド、Gentoo Linux ドキュメンテーションガイドがありますので、参照してください。 GentooJPのドキュメントで、必ず必要となる初期化部及び終了部などは次のとおりです。 また、ドキュメントのファイル名、文書のタイトル、作成者のメールアドレス、作成者名、文書の摘要、作成年月日、文書のバージョンは適宜変更する必要があります。
ドキュメントのファイル名は、簡潔にその文書の内容が理解できるものが良いでしょう。なお、翻訳ドキュメントの場合は、バージョン番号を変更しないで下さい。オリジナルドキュメントの場合は、バージョンを1.0としてください。
これ以外の項目については、変更の必要はありません。青文字の部分が、変更を必要とする箇所です。実際のドキュメントは次のような構成となります。

Code listing 2.1: ドキュメント 基本構成
<?xml version='1.0' encoding="UTF-8"?>
<?xml-stylesheet href="/xsl/guide.xsl" type="text/xsl"?> 
<!--上の行は最終的な翻訳ドキュメントでは必要ありません。AxKit以外で確認する場合の文法チェックで必要となります-->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<!--ドキュメントのファイル名-->
<guide link="/jpdoc/test-xml.html">

<!--ドキュメントのタイトル-->
<title>ドキュメントサンプル文書</title>

<!--作成者名、作成者のメールアドレス-->
<author title="Author"><mail link="docs@gentoo.gr.jp">GentooJP</mail>
</author>

<!--翻訳ドキュメントの場合は、以下を追加します-->
<author title="翻訳"><mail link="翻訳者メールアドレス">翻訳者名</mail>
</author>

<!--Original revision: 1.49--><!--// 翻訳ドキュメントでオリジナルリビジョンを確認するために記入してください-->


<!--文書の摘要-->
<abstract>
このガイドは、GentooJPの翻訳・オリジナルドキュメントの基本構成について、サンプルを提供します。 
</abstract>

<!--ドキュメントのバージョン-->
<version>1.0</version>

<!--作成年月日-->
<date>8 November 2002</date>


<!-- ここから本文です。-->
<chapter>
<title>これは第1章のタイトルです</title>
<section>

<title>これは第1章第1節のタイトルです</title>

<body>

<p>第1章の第1節の本文です。</p>

<pre>コード領域です。実際に入力する操作を記載します。</pre>

<note>これは注記です。</note>
<warn>これは警告です。</warn>
<impo>これは重要項目です。</impo>

</body>
</section>
</chapter>
<!-- ここまでが本文です。-->

</guide>

Note: このサンプル文書の名前はjpdoc/test-xml.xmlです。実際の表示を確認してみてください。

3.ドキュメント作成準備

概要 

gentoo.orgやGentooJPのXMLドキュメントは、すべてcvsで公開されています 回線状況やディスクスペースの問題なども考慮して、必要最小限のファイルで準備する方法、 www.tar.gzを取得し展開する方法、cvs利用による方法を紹介します。
(翻訳ドキュメントでは作業の開始宣言、gentoo.orgの原文取得など追加作業が必要になりますが、この章の最後に説明します。)
どの方法でも、次の点は守ってください。

  • ドキュメント作成は、必ずjpdoc/以下で行うこと。(翻訳ドキュメントでは、doc/ja/以下での作業を推奨)
  • オリジナルドキュメントで画像イメージを使用する場合は、/images/(ドキュメント名)/画像ファイル名とすること。
  • 画像フォーマットは、PNGを推奨します。

必要最小限のファイルで準備する方法 

オリジナルドキュメントを作成するには、まずディレクトリを適切なユーザーの /home 領域などに、dtd、xsl、css、jpdoc、imagesの5つを作成します。 次に、dtd/guide.dtd、xsl/guide.xsl、css/main.css を配置します。作成しようとするドキュメントは、jpdocディレクトリで作業を行って下さい。
作業領域としてwww以下に各ディレクトリとファイルを展開します。

Code listing 3.1: ディレクトリの作成とファイルの配置
$ mkdir www 
$ mkdir www/{dtd,xsl,css,jpdoc,images}
$ wget http://cvs.sourceforge.jp/cgi-bin/viewcvs.cgi/*checkout*/gentoojp/www/dtd/guide.dtd? -P www/dtd
$ wget http://cvs.sourceforge.jp/cgi-bin/viewcvs.cgi/*checkout*/gentoojp/www/xsl/guide.xsl? -P www/xsl
$ wget http://cvs.sourceforge.jp/cgi-bin/viewcvs.cgi/*checkout*/gentoojp/www/css/main.css? -P www/css

www.tar.gzを取得して展開する方法 

GentooJPのwebコンテンツ全体を取得することのできるwww.tar.gzは、こちらから取得できます。
www.tar.gzを取得して展開する方法は、他のドキュメントを参考にしながら作業できるのが利点です。コマンドラインから取得して展開する方法は次のとおりです。
展開が終われば、GentooJPのwebコンテンツと同様のディレクトリ構成とファイルがwww/以下に配置されます。

Code listing 3.2: www.tar.gzの取得と展開
$ cd ~/
$ wget http://cvs.sourceforge.jp/cgi-bin/viewcvs.cgi/gentoojp/www/www.tar.gz?tarball=1
$ tar -zxvf www.tar.gz

cvsを利用する方法 

cvsを利用する方法は、いくつかのコマンドを覚えることでファイルのバージョンを常に最新版にしておけるなど大変便利です。
以下に基本的な内容を書きますが、詳細は CVSチュートリアルsourceforge.jpなどを参照してください。
あなたのホームディレクトリを/home/username、リポジトリは、gentoojpとして説明します。

Code listing 3.3: cvsのインストールとリポジトリの作成
// cvsのインストール
# emerge cvs

// リポジトリの作成
$ cvs -d /home/username/gentoojp init

GentooJPのWebコンテンツ(www.tar.gzと同内容)をチェックアウト(作業コピー取り出し)し、/home/username/gentoojp/www/以下に必要ファイルを取得します。

Code listing 3.4: checkout
$ cd /home/username/gentoojp
$ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.jp:/cvsroot/gentoojp co www

次のコマンドは、取得した作業コピーをアップデートする場合に使用します。

Code listing 3.5
$ cd /home/username/gentoojp
$ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.jp:/cvsroot/gentoojp update -dP

Important: このガイドでは、作業ディレクトリをwww/として解説していますが、 cvsを利用した場合には作業ディレクトリが gentoojp/www/となります

翻訳ドキュメント作成の際に必要となる追加手順 

翻訳ドキュメント作成の際には、翻訳状況の確認と翻訳手順を確認してください。 GentooJPでは、GentooJP翻訳プロジェクト - 進捗状況GentooJP翻訳プロジェクトの2つの詳細なドキュメントを用意しています。 なお、この手順はオリジナルドキュメント作成では必要ありません。

4.ドキュメントの確認方法(HTML)

HTML変換による確認 

HTML変換による確認方法は、コンソールから内容、記述上の間違いなどを検証する方法です。まず文法チェック・変換ツールのインストールを行います。一度インストールを行ってしまえば、次回からは必要ありません。

Code listing 4.1: HTML変換に必要なパッケージのインストール
wget http://cvs.sourceforge.jp/cgi-bin/viewcvs.cgi/*checkout*/gentoojp/www/dtd/guide.dtd? -P www/dtd
// xmllint(文法チェック)
# emerge libxml2

// xsltproc(HTML変換)
# emerge libxslt

完成したオリジナルドキュメントをHTMLに変換して確認するには、まず、xmllintで文法チェックを行います。次にHTMLに変換するのですが、 jpdoc/test-xml.xml(あなたが作成した文書名)とxsl/guide.xslに、dtdとcssが絶対パス指定として記述されている部分があるため、変更してから確認する必要があります。

Code listing 4.2: jpdoc/test-xml.xml
3行目変更前
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3行目変更後
<!DOCTYPE guide SYSTEM "../dtd/guide.dtd">
Code listing 4.3: xsl/guide.xsl の変更
11行目変更前
href="/css/main.css"
11行目変更後
href="../css/main.css"

Warning: この変更は、AxKitで確認をする場合には必要ありません。

Code listing 4.4: HTMLへの変換
$ cd ~/www/jpdoc

$ xmllint --valid --noout test-xml.xml
// ここでエラーが表示されるかも知れません。チェックしてください。

$ xsltproc  ../xsl/guide.xsl test-xml.xml > test-xml.html


// UTF-8コードをeucJPコードに変換します。ここで次のようなメッセージが表示されることがありますが、無視してください。
$ iconv -f utf-8 -t eucjp -c -o test-xml-euc.html < test-xml.html 
iconv: 位置 3859 で不正な入力シーケンスがありました

Note: xmllintでの文法チェックは、AxKitでの確認方法を使用する場合でも、とても便利です。

ドキュメントの確認 

作成したドキュメントは、w3mなどから確認を行います。

Code listing 4.5
//  w3mがインストールされていない場合には、次のコマンドでw3mをインストールします。
# emerge w3m

//  HTMLの確認をします。
$ w3m file:///home/username/www/jpdoc/test-xml-euc.html

Note: net-www/w3mmeeを使って、UTF-8エンコーディングのまま、HTMLを参照することもできます。

5.ドキュメントの確認方法(AxKit)

AxKitのインストールとApacheの設定 

AxKitを使えば、GentooJPでドキュメントがが公開されるときとほぼ同じ状態で文法のチェック、レイアウトのチェックなどが可能になりますし、印刷用のXSLスタイルシートを使って紙上でも確認ができます。
このガイドでは、ローカル環境で、Apache Virtual Hostを使った設定方法を紹介します。 ユーザー名username、グループ名users、ドキュメントディレクトリを/home/username/wwwとして説明します。 まず、AxKitをインストールします。

Code listing 5.1: AxKitのインストール
# emerge -p AxKit
[ebuild  N   ] dev-perl/AxKit-1.6-r1 
// AxKitに必要なパッケージの一覧が表示されます。お使いの環境によってはたくさんのパッケージがインストールされます。

# emerge AxKit

/etc/conf.d/apache にmod_perlモジュールが有効となるオプションを加えます。

Code listing 5.2: /etc/conf.d/apacheの設定
APACHE_OPTS="-D PERL"

mod_perlの設定をします。次のコマンドを実行することで、/etc/apache/conf/appache.conf に設定が追加されます。

Code listing 5.3: /etc/apache/conf/apache.confへの設定追加
# ebuild /var/db/pkg/dev-perl/mod_perl-1.27-r1/mod_perl-1.27-r1.ebuild config
Code listing 5.4: apache.confに追加される内容
<IfDefine PERL>
  LoadModule perl_module        extramodules/libperl.so
</IfDefine>

<IfDefine PERL>
  AddModule mod_perl.c
</IfDefine>

vhosts.conf を有効にするために、/etc/apache/conf/appache.conf を次のとおり設定します。

Code listing 5.5: /etc/apache/conf/apache.confの設定
# Include conf/vhosts/Vhosts.conf
コメントアウトを取り除いて有効化します
Include conf/vhosts/Vhosts.conf

/etc/apache/conf/vhosts/Vhosts.confは次のように設定します。 ローカルエリア内の環境を想定していますので、追加的に必要となるApache、DNSその他の設定は、適切なドキュメントを参照してください。 なお、IPアドレスは、192.168.1.1を想定しています。

Code listing 5.6: /etc/apache/conf/vhosts/Vhosts.conf の設定
Port 8080
Listen 8080

<VirtualHost 192.168.1.1:8080>
User username
Group users
DocumentRoot /home/username/www
ErrorLog /home/username/www-error_log
<IfModule mod_alias.c>
 Alias /doc /home/username/www/doc
</IfModule>
<Directory /home/username/www>
Options Indexes FollowSymLinks Multiviews ExecCGI
 AllowOverride All
 Order allow,deny
 Allow from all
<IfModule mod_perl.c>
 PerlModule AxKit
  SetHandler perl-script
  PerlHandler AxKit
  // 次の1行は表示用と印刷用のXSLを使い分ける場合に必要です
  AxAddPlugin Apache::AxKit::StyleChooser::QueryString
  AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT
</IfModule>
</Directory>
</VirtualHost>

Note: エラーログが /home/username/www-error_log に作成されます。

Warning: ここで説明したApacheの設定は、あくまでGentooJPドキュメントチェック用であり、外部への公開、セキュリティなどは考慮していません。

印刷用表示をする場合の追加設定 

表示用と印刷用を使い分け確認作業を行う場合は、まず表示用と印刷用のxslファイルを取得する必要があります。また、翻訳ドキュメントは最終的にgentoo.orgのディレクトリ下におかれるので、なるべくgentoo.orgの最新版xslファイルを取得してください。 xslファイルのダウンロードはこちらからできます。最低限、印刷用のguide-print.xslを取得して、www/xsl/以下に保存して下さい。

Important: xsl取得用のアドレスは将来変更になる可能性があります。

次に表示用と印刷用を使い分けるために作業ディレクトリjpdoc/以下に.httaccessファイルを作成します。

Code listing 5.7: .htaccessファイルの例
<AxMediaType screen>
    <AxStyleName "#default">
      AxAddProcessor text/xsl /xsl/guide.xsl
    </AxStyleName>
    <AxStyleName printable>
      AxAddProcessor text/xsl /xsl/guide-print.xsl
    </AxStyleName>
</AxMediaType>

Note: .htaccessファイルには適切なパーミションを設定して下さい。

Important: 印刷用で表示されない場合、<?xml-stylesheet href=”/xsl/guide.xsl” type=”text/xsl”?>を削除しているか確認して下さい。

Apacheの起動 

各confファイルの準備が整ったら、apachectl で 各ファイルの変更点にミスがないかチェックし、問題がなければApacheを起動します。

Code listing 5.8: configtest
# apachectl configtest

// Apacheが起動していない場合
# /etc/init.d/apache start

// すでにApacheが起動している場合
# /etc/init.d/apache stop start

ドキュメントの確認 

作成したドキュメントは、mozillaなどから、http://192.168.1.1:8080/jpdoc/test-xml.xmlを開いて確認します。 印刷用のxslで確認するには同じくhttp://192.168.1.1:8080/jpdoc/test-xml.xml?style=printableとします。

6.ドキュメントの送付方法

翻訳・オリジナルドキュメントの作成が終わったら、翻訳ドキュメントは、GentooJP翻訳プロジェクトを、オリジナルドキュメントは、GentooJP オリジナルドキュメントプロジェクトを参照して、 あなたが作成したすばらしい文書を送信して下さい。
なお、ドキュメントの確認を“ドキュメントの確認方法(HTML)”で、行った場合には、jpdoc/test-xml.xmlの変更を忘れずに元に戻してから、送付してください。
送信する前に、文字コードはutf-8、改行コードはLF、xmllintのチェックはもう一度してくださいね。:)

Copyright© 2002-2014 Gentoo Linux Users Group Japan. All rights reserved.

このサイトはGentooJPが運営するGentoo.org非公式コミュニティサイトです。ご質問、ご意見などはこちらまで。 Email: www@gentoo.gr.jp