Samba 3.0/3.2 ドキュメントの生成のソースを表示

Samba 3.0 系列のドキュメントは、XML ファイルから、さまざまな処理を経て manpage 形式や html 形式、PDF などのドキュメントを生成するようになっています。

PDF や html 形式用に、画像ファイルなども多数存在しており、ドキュメント自体の容量が非常に肥大化しています。

このため、Samba 3.0 系列の途中から、アーカイブの肥大化を防ぐ意味で、XML ファイルや XML ファイルからドキュメントを生成するための各種ファイル類は別の SVN ツリーに格納され、Samba のアーカイブには生成済の manpage 形式、html 形式、PDF ファイルのみが同梱されるようになりました。しかし、3.2.0からはドキュメントのソース(XMLファイル)の同梱が復活しています。

以下、Samba のドキュメントをオリジナルの XML ファイルからコンパイルする手順について記載します。

== ドキュメントの取得 ==

Samba のドキュメントアーカイブは、[Samba Team の SVN (Subversion) ツリー] から取得できます(注:gitの場合はh詳細不明)。

リリース版のドキュメント一式には、'''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''' に記載されていますが、いくつかのプロダクトが必要です。これらのプロダクトはバージョン依存性があり、現状SUSE Linux以外の環境では動作しません。

以下、README から引用します。

<pre>
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
</pre>

これらのパッケージを適宜インストールしておく必要があります。万が一make中にパッケージが足らなかった場合には、足らないパッケージをインストール後、docs-xmlディレクトリ配下でconfigure を再度実行する必要があります。

また、実行時にwww.samba.orgにアクセスしますので、ネットワークが繋がるようにしておく必要があります。ファイアウォールの内側の場合は、export http_proxy でプロキシの設定をしておいてください。

== configure と make ==

環境が整備できたら、configure を実行した上で、make を実行します。

make のオプションには以下のようなものがあり、生成するドキュメントの種類を限定できます。

<pre>
[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
</pre>

上記に記載がありませんが、 manpages3 を指定することでマニュアルページのみを生成可能です。

このほかにも tex や pdf など様々なオプションが指定可能です。指定可能なオプションについては、Makefile のターゲット欄を参照してください。

== 日本語ドキュメントを作成する ==

このドキュメント生成システムは、基本的に英語圏の環境しか考慮されていませんが、文字コードとして UTF-8 を用いることで、禁則処理の不備など問題があるものの、日本語ドキュメントを生成させることも可能です。

以下、方法を記載します。
なお、よりよい方法があれば、ぜひ加筆、訂正願います。

=== 現在の注意点 ===

*デフォルト値、設定例、といった文言は、xslt/expand-smbconfdoc.xsl を直接編集しています。
*Note や Warning といった文字列を日本語化する方法が確認できていません。
*デフォルトでは、日本語文字列が、すべて実体参照（&#xxx形式）になってしまいますので、HTML はまだしも、manpage 形式では使い物になりません。仕方ないので、以下のような PHP スクリプトで変換掛けてます。
*:ということでしたが、SuSEでやったところ、man形式はまともでした。htmlはだめでした。また、下記のスクリプトを実行すると、文字情報以外の情報が落ちるらしく、うまくないです。

<pre>
#!/usr/bin/php
<?php

    while (!feof(STDIN)) {
        echo foo(fgets(STDIN));
    }

function foo($s)
{
    $s = mb_convert_encoding($s, "UTF-16", "eucJP-win");
    $s = mb_decode_numericentity($s, array(0, 0xffff, 0, 0xffff), "UTF-16");
return mb_convert_encoding($s, "EUC-JP", "UTF-16");
}
?>
</pre>
*OpenSUSE 11.0でだいたい動きます。ただPDF作成はghostscriptがエラーになってしまいます。