cryolite
cryol****@bb*****
2004年 11月 23日 (火) 08:29:41 JST
はじめまして．Cryoliteと申します． このMLには初めて投稿させていただきます．よろしくお願いします． 実は今年の7月に本プロジェクトの一員として参加させていただいたのですが 今の今まで何一つ貢献できずにおりました．すいません． さて，このメールの本題についてです． （以下ではBoostのローカルツリーのルートをBOOST_ROOTと書きます） BoostでBoost.BookというXMLによるドキュメント形式の 統一を試みるプロジェクトがあることはご存知の方も多いかと思います． http://www.boost.org/doc/html/boostbook.html このBoost.Bookによるドキュメント生成の大まかな流れは以下のようになります． 1. Boost.Book形式でドキュメントを提供している各ライブラリ (BOOST_ROOT/libs/(ライブラリの名前)/docにxmlファイルかどうかが 目安になります)のXMLドキュメントをかき集めて，DocBook (http://www.docbook.org/)形式のXMLドキュメントに一旦変換する． 2. 生成したDocBook形式のXMLドキュメントから，XSLTプロセッサで 各種ドキュメント形式（chunking HTML, single HTML, man, ps, pdf）を ビルドする． Boostのwebサイト，及びリリースとして配布されているドキュメントのうち BOOST_ROOT/doc/html以下のドキュメントは2.でビルドされる形式のうちの 1形式（chunking HTML形式）です． 今後これらのドキュメントを訳す際には，やはりビルドの成果物である HTMLファイルを訳すよりは，大本のXMLファイルを翻訳した方が良いかと思います． 本MLのアーカイブを一瞥したところ，これらBoost.Book形式のXMLファイルの ビルド手順，特に日本語への翻訳とそのビルドの手順についての詳細な情報が まだないようでしたので，僭越ながら自分が調べた範囲内での情報を お知らせしておこうと思い，このメールを投稿させていただきました． もしMLのアーカイブを見落としていて，情報が重複しているようなら何卒ご容赦くだ さい． 以下がビルド手順となります． 1. 翻訳 ドキュメントを翻訳します．対象となるファイルは BOOST_ROOT/libs/(ライブラリ名)/doc にあるXMLファイルです． Boost.Bookで用いられている各タグの定義については http://www.boost.org/doc/html/boostbook.html 以下のドキュメントを参照してください． 基本的にBoost.Book形式のXMLは非常に読みやすく，タグも名前を見れば 意味が一目瞭然で，慣れればHTMLより読み書きしやすいかと思います． 後はXMLについての基本的な知識さえあれば 特に問題なく翻訳を進められるかと思います． XMLファイルのエンコードについては，基本的にXMLタグのencoding属性と ファイルのエンコードが一致していれば良いとは思いますが， XMLの標準であるutf-8を指定するのが無難かと思います． （とはいえ自分はXMLについてほとんど無知なので，この点については どなたか適切な訂正をいただけるとありがたいです） 2. bjamを用意する bjamのバイナリを用意してパスを通します． もしくはBOOST_ROOT/docで作業するのでそこから直接呼ぶのでも構いません． 1.32.0をビルドできるbjamのバイナリならそのまま使えると思いますが， 出来るならBOOT_ROOT/tools/build/jam_srcからbjamをビルドしたほうが 無難かと思います．bjamをソースからビルドする手順については http://www.boost.org/tools/build/jam_src/index.html#building_bjam を参照してください． 3. DocBook XSLとDocBook DTDを用意する DocBook XSLとDocBook DTDをローカルに落としてきます．各々最新版が http://docbook.sourceforge.net/ (DocBook XSL) と http://www.oasis-open.org/docbook/ (DocBook DTD) から入手可能です． これらがローカルになくてもドキュメントのビルドが可能なのですが， これらがローカルに無いとドキュメントのビルドの際に 逐一ネット上のリソースにアクセスしてビルドがえげつなく遅くなるので ローカルに落としておくことを強くお勧めします． 落としたら適当なディレクトリに展開しておきます． UNIX環境では/usr/shareあたりにすでにあるかも知れません． （自分の場合cygwinをフルインストールしたら，すでに各々 /usr/share/docbook-xsl, /usr/share/docbook-xml42に入ってました） 以下ではDocBook XSLとDcoBook DTDを展開したディレクトリを， 各々XSL_DIR，DTD_DIRと書くことにします．（7. で使います） 4. XSLTプロセッサを用意する XSLTプロセッサ(xsltproc)を用意してパスを通します． Windows環境では以下のバイナリを適当なディレクトリに展開してパスを通しま す． http://www.meta-comm.com/engineering/boost/xsltproc-win32.zip （上のバイナリが入手できなくてもxsltprocのwindowsバイナリは 探せばそこら辺に落ちています） UNIX環境ではlibxml2 (http://xmlsoft.org/)をビルド&インストールしてから 次にlibxslt (http://xmlsoft.org/XSLT/)をビルド&インストールしてください． お使いの環境によっては/usr/binあたりにすでに入っているかも知れません． （自分の場合cygwinをフルインスコしたら/usr/binにすでに入ってました） 5. doxygenを用意する doxygen (http://www.doxygen.org/)を用意してバイナリへのパスを通してくださ い． （未確認ですがchunking HTML吐かせるだけならdoxygenは不要かも知れません） 6. 環境変数HOMEを設定する Windows環境で環境変数HOMEを設定していない場合は設定してください． 7. user-config.jamの作成と設定 BOOST_ROOT/tools/build/v2にあるuser-config.jamというファイルを HOMEにコピーして，以下に示す箇所をコメントインします． "using boostbook"の箇所は3.で用意したDocBook XSLとDocBook DTDの ディレクトリへのパス（XSL_DIRとDTD_DIR）に書き換えます． ..... # xsltproc (from libxslt) configuration using xsltproc ; # コメントインする行 # BoostBook configuration. Please see BoostBook for documentation # on this. # using boostbook ; using boostbook : XSL_DIR # コメントインする行（XSL_DIRの部分は書き換 えます） : DTD_DIR # コメントインする行（DTD_DIRの部分は 書き換えます） ; # コメントインする行 user-config.jamはBoost.Build V2で必要とされる設定ファイルです． より詳細な情報は http://www.boost.org/doc/html/bbv2.html を参照してください． 8. DocBookのエンコードの設定 中間フォーマットであるDocBook形式のXMLのエンコードを設定します． BOOST_ROOT/tools/boostbook/xsl/docbook.xslの以下の部分 <xsl:output method="xml" doctype-public="-//OASIS//DTD DocBook XML V4.2//EN" doctype-system="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"/> を，次のように書き換えます． <xsl:output method="xml" doctype-public="-//OASIS//DTD DocBook XML V4.2//EN" doctype-system="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" encoding="utf-8"/> この設定が無いとデフォルトであるISO-8859-1で中間ファイルが吐かれ， 日本語がすべからく数値文字参照になります．実はこの状態でも ビルド・表示等には問題はないようなのですが1.と同じ理由で utf-8を設定しておくのが無難だと思います． 9. 出力されるHTMLのエンコードの設定 出力されるchunking HTMLのencodingを設定します． BOOST_ROOT/tools/boostbook/xsl/html.xslの以下の場所に 出力するHTMLのエンコードを設定する行を追加します． ..... <xsl:import href="chunk-common.xsl"/> <xsl:import href="docbook-layout.xsl"/> <xsl:import href="navbar.xsl"/> <xsl:import href="admon.xsl"/> <xsl:import href="relative-href.xsl"/> <!--以下の1行を追加する--> <xsl:param name="chunker.output.encoding" select="'utf-8'" /> <xsl:param name="html.stylesheet" select="'boostbook.css'"/> <xsl:param name="navig.graphics" select="1"/> ..... 上の設定が無くても生成されるHTMLファイルは日本語をきちんと表示しますが， 8. 同様ISO-8859-1 & 数値文字参照な状態になります． 逆に言うと，ここの設定次第で吐かれるHTMLファイルのエンコードが変わります． ここの設定についてはutf-8以外にも選択肢があると思います． どれが最適かについては自分は判断しかねます．（何でも良いとは思いますが） 10. 既存のHTMLファイルの属性変更 BOOST_ROOT/doc/html以下にある全てのHTMLファイルを 書き込み可能な状態にします． 11. ビルド BOOST_ROOT/docへ移動して，以下をシェル（プロンプト）から入力します． bjam --v2 以上でBOOST_ROOT/doc/html以下にドキュメントが生成されます． そこそこ時間がかかりますので気長に待ちましょう． その他，ビルドしてて気付いた点. ビルドが異常に遅い（普通はCeleron 1Gのマシーンでも30分あれば終わります）， プロセス(xsltproc)がフルに回ってない，ネットワークにつなげているようだ， などの兆候がある場合は7.で指定したXSL_DIRやDTD_DIRの設定が正しくなく， ネットワークからこれらのリソースを取得しようとしている可能性が高いです． この場合でも気長に待てばビルドは進みます （ただし「夜寝る前に仕掛けて朝起きたら終わってた」ぐらいのレベル）． もし，一度この状態になってから再度ビルドする際には user-config.jam中のXSL_DIRとDTD_DIRの部分(7.を参照)を 適切に設定した上， 「BOOST_ROOT/doc/catalog.xmlを削除してから」 ビルドしてください． その他，参考にしたドキュメント. -Windows環境でのBoost.Bookのビルドについて http://lists.boost.org/MailArchives/boost/msg73025.php -chunk.xslの出力エンコードの設定について http://www.sagehill.net/docbookxsl/Chunking.html ビルド手順は以上です． 本家のCVSリポジトリはBoost.Bookのドキュメントをビルドしていない 状態ですので，これをcheck outして上の手順を実行してみれば BOOST_ROOT/doc/html以下にHTMLファイルが生成されるかと思います． テストとして，本家の1.32.0のstring_algoのXMLドキュメントの 一部を訳して上の手順に沿ってビルドしてみましたが， （cygwin環境及びwindows環境双方で試してみました） 見た限りでは適切に翻訳・ビルドされているようでした． 余談ですがBOOST_ROOT/bin.v2/doc/debugに生成されるboost.docbookで bookタグにlang="ja"付けて再ビルドするなりすると遊べるかも知れません． （すぐに飽きる遊びですが・・・） <book lang="ja"> 後，上記とは関係ない要望・質問になりますが対訳表などを切に欲しています． http://www.shibu.jp/Boost/FixedWordBrowseReport 等がそれだとは思うのですが現在アクセスできないようです． 厚かましいお願いとは思いますが， これらを閲覧できるようにしていただけますでしょうか？ 以上です．長文・駄文，本当に失礼しました．
