Samba 3.0/3.2 ドキュメントの生成
Samba 3.0 系列のドキュメントは、XML ファイルから、さまざまな処理を経て manpage 形式や html 形式、PDF などのドキュメントを生成するようになっています。
PDF や html 形式用に、画像ファイルなども多数存在しており、ドキュメント自体の容量が非常に肥大化しています。
このため、Samba 3.0 系列の途中から、アーカイブの肥大化を防ぐ意味で、XML ファイルや XML ファイルからドキュメントを生成するための各種ファイル類は別の SVN ツリーに格納され、Samba のアーカイブには生成済の manpage 形式、html 形式、PDF ファイルのみが同梱されるようになりました。
以下、Samba のドキュメントをオリジナルの XML ファイルからコンパイルする手順について記載します。
ドキュメントの取得
Samba のドキュメントアーカイブは、[Samba Team の SVN (Subversion) ツリー] から取得できます。
リリース版のドキュメント一式には、release-x-x-x というタグが振られているので、このタグを指定することで、任意のバージョンのドキュメント一式を取得することが可能です。
たとえば、Samba 3.0.23 のドキュメント一式を取得するには、 Subversion のクライアント環境 (svn コマンド) をインストールした上で、以下のようにします。
svn co svn://svnanon.samba.org/samba-docs/tags/release-3-0-23 samba-docs
これで、 samba-docs ディレクトリ以下に、Samba 3.0.23 のドキュメント一式が取得されます。
環境の整備
Samba のドキュメントをコンパイルする方法は、アーカイブに含まれる README に記載されていますが、いくつかのプロダクトが必要です。
以下、README から引用します。
To generate the docs, you need to have the following packages installed: * GNU Make * GNU autoconf * docbook-utils * xsltproc * pngtopnm and pnmtops (from the netpbm utilities) * dia For generating PDF (thru LaTeX): * db2latex (from http://db2latex.sf.net/). Make sure to get CVS version dated 20030622 -- it works best. Versions previous to 20030425 are known to have problems, as well as current (as of 20031210) snapshots. * pdflatex * thumbpdf For generating PDF (thru FO): * fop (http://xml.apache.org/fop/) For generating PostScript (thru LaTeX): * db2latex * latex * dvips For generating ASCII: * html2text For generating Palm-viewable docs: * plucker-build For generating texi files: * docbook2x-texi * makeinfo For validating: * xmllint
これらのパッケージを適宜インストールしておく必要があります。
configure と make
環境が整備できたら、configure を実行した上で、make を実行します。
make のオプションには以下のようなものがあり、生成するドキュメントの種類を限定できます。
[melrose:samba-docs-3.0.23d] make help Supported make targets: release - Build the docs needed for a Samba release all - Build all docs that can be build using the utilities found by configure everything - Build all of the above pdf,tex,dvi,ps,manpages3,txt,pearson,fo,htmlhelp - Build specific output format html - Build multi-file HTML versions html-single - Build single-file HTML versions htmlman3 - Build HTML version of manpages undocumented - Output list of undocumented smb.conf options samples - Extract examples
上記に記載がありませんが、 manpages3 を指定することでマニュアルページのみを生成可能です。
このほかにも tex や pdf など様々なオプションが指定可能です。指定可能なオプションについては、Makefile のターゲット欄を参照してください。
日本語ドキュメントを作成する
このドキュメント生成システムは、基本的に英語圏の環境しか考慮されていませんが、文字コードとして UTF-8 を用いることで、禁則処理の不備など問題があるものの、日本語ドキュメントを生成させることも可能です。
以下、方法を記載します。 なお、よりよい方法があれば、ぜひ加筆、訂正願います。
