ベースシステム、Ports Collection に加え、 ドキュメントも FreeBSD オペレーティングシステムの構成要素です。 FreeBSD ドキュメントセットの最新バージョンは、FreeBSD ウェブサイト から入手できますが、 ネットワーク接続が遅い、もしくはまったく接続できないユーザもいます。 幸運にも、各リリースで提供されるドキュメントをアップデートして、 最新の FreeBSD ドキュメントセットをローカルで維持する方法が用意されています。
FreeBSD のドキュメントのソースは、 Subversion を用いて入手できます。 この節では以下について説明します。
ドキュメントツールチェインのインストール方法。 このツールは、FreeBSD のドキュメントをソースから再構築するのに必要です。
Subversion を用いて、 ドキュメントのソースを /usr/doc 以下にダウンロードする方法。
FreeBSD ドキュメントをソースから再構築し、 /usr/share/doc 以下にインストールする方法。
ドキュメントのビルドシステムにおいてサポートされているビルドオプションの説明。 たとえば、翻訳されたドキュメンテーションのみを構築するオプションや、 ある特定の出力フォーマットを指定するようなオプションについて説明します。
FreeBSD のドキュメントをソースから再構築するには、 かなり大きなツールのコレクションが必要です。 これらのツールは多くのディスク容量を必要とし、また、 すべての FreeBSD ユーザにとって有用というわけではないので、 FreeBSD ベースシステムの一部ではありません。 これらのツールは、FreeBSD のために新しいドキュメントを活発に執筆している方や、 頻繁にドキュメントをソースからアップデートする方に向けたものです。
必要なツールは、すべて Ports Collection で入手できます。textproc/docproj は、 FreeBSD ドキュメンテーションプロジェクトにより開発されているマスター port で、 これらのツールのインストールやアップデートを容易にします。
注意: ドキュメントの PostScript® や PDF 版が必要なければ、かわりに textproc/docproj-nojadetex をインストールすることも考えてよいでしょう。 このドキュメンテーションのツールチェインは、 teTeX と呼ばれる組版エンジンを除いたすべてをインストールします。 teTeX は大きなツールのコレクションです。 そのため、もし PDF 出力を本当に必要としなければ、 このツールをインストールしないことはとても賢明です。
textproc/docproj をインストールすると、Subversion もインストールされます。
ドキュメントのソースは、 Subversion プログラムを使ってダウンロードできます。 ダウンロードするには以下のように入力してください。
# svn checkout svn://svn.FreeBSD.org/doc/head /usr/doc
最初にドキュメントのソースをダウンロードするには少し時間がかかります。 ダウンロードが終わるまでお待ちください。
ダウンロードしたドキュメントのソースをアップデートするには、 以下のコマンドを実行してください。
# svn update /usr/doc
ソースを入手したら、/usr/doc ディレクトリの Makefile を使い、 以下のようにドキュメントをアップデートすることもできます。
# cd /usr/doc # make update
FreeBSD のドキュメントのアップデートとビルドシステムは、 ドキュメンテーションの一部のアップデートを簡単にするオプションや、 特定の翻訳のビルドに対応しています。 これらのオプションは、システム全般のオプションである /etc/make.conf ファイルや、make(1) ユーティリティに与えるコマンドラインオプションで設定できます。
以下がこれらのオプションの一部です。
ビルドおよびインストールの言語およびエンコーディングの一覧。 たとえば、英語のドキュメントのみを指定するには en_US.ISO8859-1 を設定します。
ビルドを行うフォーマット、または出力フォーマットの一覧。 現在は html, html-split, txt, ps, pdf, そして rtf に対応しています。
ドキュメントをインストールする場所。デフォルトは /usr/share/doc です。
FreeBSD のシステム全般のオプションに関連するもっと多くの make 変数については、 make.conf(5) をご覧ください。
FreeBSD ドキュメントのビルドシステムで対応しているさらなる make の変数に関しては、 新しい貢献者のための FreeBSD ドキュメンテーションプロジェクト入門 を参照してください。
ドキュメントのソースの最新スナップショットを /usr/doc にダウンロードし終わったら、 インストールされているドキュメントをアップデートする準備がすべて整いました。
makefile の DOC_LANG オプションで定義されているすべての言語を完全にアップデートするには、 以下のように入力してください。
# cd /usr/doc # make install clean
もし、ある特定の言語のみをアップデートしたいのであれば、 /usr/doc サブディレクトリで以下のように make(1) を実行してください。
# cd /usr/doc/en_US.ISO8859-1 # make update install clean
make の FORMATS 変数を設定して、 以下のようにインストールする出力形式を指定できます。
# cd /usr/doc # make FORMATS='html html-split' install clean
これまでのセクションでは、ソースコードを用いた FreeBSD ドキュメントのアップデート方法について説明してきました。 しかしながら、すべてのシステムにおいて、 ソースからドキュメントをアップデートすることは難しいかも知れませんし、 できたとしても現実的ではないこともあります。 ドキュメントをソースから構築するには、 かなり大きなツールとユーティリティから構成される ドキュメンテーションツールチェイン が必要です。 また、Subversion リポジトリからソースをチェックアウトし、 チェックアウトしたソースからドキュメントを手動で構築する方法について、 それなりに熟知している必要もあります。 この節では、インストールされている FreeBSD のドキュメントをアップデートするもう一つの方法である、 Ports�Collection を用いた以下の方法について説明します。
構築済のドキュメントのスナップショットをダウンロードしてインストールする方法。 ローカルでの構築作業は必要ありません (ドキュメンテーションツールチェインをインストールする必要はありません)。
ドキュメントのソースをダウンロードし、ports フレームワークを使って構築する方法 (チェックアウトおよび構築作業が簡単になります)。
FreeBSD のドキュメントをアップデートするこれらの方法は、
ドキュメンテーションエンジニアリングチーム <[email protected]>
が毎月アップデートしている ドキュメンテーション ports によりサポートされています。
これらの ports は、FreeBSD Ports�Collection の docs
仮想カテゴリにまとめられています。
ドキュメンテーション ports では、 ports の構築フレームワークが用いられるので、 ドキュメントを簡単に構築できます。 この ports は、ドキュメントのソースを自動的にチェックアウトし、 環境変数やコマンドラインオプションを適切に設定して make(1) を実行します。 また、他の FreeBSD port, package のインストールと同様に簡単な方法で、 ドキュメントのインストールやアンインストールを行うことができます。
注意: 追加の機能として、この ports は ドキュメンテーションツールチェイン ports への依存を理解しているので、 構築時にはドキュメンテーションツールチェインも自動的にインストールされます。
ドキュメンテーション ports の構成は以下の通りです。
“マスタ port”, misc/freebsd-doc-en。 ドキュメンテーション port のファイルはここにあります。 この port は、すべてのドキュメンテーション ports のベースです。 デフォルトでは、英語の文書のみを構築します。
“すべてのドキュメントの port”, misc/freebsd-doc-all。 これは、すべての利用可能な言語のすべてのドキュメントを構築します。
最後に、各言語のために “スレーブ port” が用意されています。たとえば、misc/freebsd-doc-hu はハンガリー語のドキュメンテーション port です。 この port は、すべてマスタ port に依存し、 各言語の翻訳されたドキュメントをインストールします。
ソースからドキュメンテーション port をインストールするには、 以下のコマンドを (root 権限で) 実行してください。
# cd /usr/ports/misc/freebsd-doc-en # make install clean
英語版の分割された HTML 形式 (http://www.FreeBSD.org と同じ形式) のドキュメントが構築され、/usr/local/share/doc/freebsd ディレクトリにインストールされます。
ドキュメンテーション ports にはたくさんのオプションが用意されており、 ports の振る舞いをデフォルトの設定から変更できます。 以下はその中からいくつかをリストアップしたものです。
HTML 形式を構築します。 それぞれのドキュメントごとに単一版の HTML ファイルが構築されます。 整形されたドキュメントは、 article.html や book.html といった名前で、 画像とともにインストールされます。
Adobe® Portable Document Format を構築します。 Adobe Acrobat�Reader®, Ghostscript、 または、他の PDF リーダで読むためのものです。 整形されたドキュメントは、 article.pdf や book.pdf といった名前でインストールされます。
ドキュメントのインストール先を設定します。 デフォルトのインストール先は /usr/local/share/doc/freebsd です。
注意: デフォルトのターゲットディレクトリは、 Subversion を用いる方法とは異なります。 なぜならば、この節で説明をしている方法では port を用いてインストールしており、 ports は通常 /usr/local ディレクトリ以下にインストールされるためです。 PREFIX 変数を使うことで、 このディレクトリ以外にもインストールできます。
以下は、上記の変数を用いてハンガリー語のドキュメントを PDF 形式でインストールする方法を示す、簡単な例です。
# cd /usr/ports/misc/freebsd-doc-hu # make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean
前節で説明した、 ソースからドキュメンテーション port を構築する方法では、 ドキュメンテーションツールチェインをローカルにインストールする必要があり、 また、ports の構築のためにディスク容量を必要とします。 ドキュメンテーションツールチェインをインストールするリソースがない場合や、 ソースから構築する場合には多くのディスク容量を必要とするため、 構築済みのドキュメンテーション ports のスナップショットが用意されています。
ドキュメンテーションエンジニアリングチーム <[email protected]> は、毎月 FreeBSD
ドキュメンテーション package のスナップショットをアップデートしています。
これらのバイナリ package は、システムに用意されている pkg_add(1), pkg_delete(1) などの
package 管理ツールを用いて扱うことができます。
注意: バイナリ package を使うと、 インストールする言語に用意されている すべて の形式の FreeBSD ドキュメントがインストールされます。
たとえば、以下のコマンドを実行すると、 ハンガリー語のドキュメントの最新 package がインストールされます。
# pkg_add -r hu-freebsd-doc
注意: ドキュメントの package は、言語ごとに対応する port に lang-freebsd-doc の形式で名前がつけられています。 ここで、lang は言語コードの短縮形です。 ハンガリー語の場合は hu、簡体字の場合には zh_cn です。
インストール済みのドキュメンテーション port をアップデートするには、 ports のアップデートツールが用意されていれば十分です。 たとえば、以下のコマンドを実行すると、 ports-mgmt/portupgrade ツールで、package だけを使ってハンガリー語のドキュメントをアップデートします。
# portupgrade -PP hu-freebsd-doc
本文書、および他の文書は ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/ からダウンロードできます。
FreeBSD に関する質問がある場合には、ドキュメント を読んだ上で <[email protected]> まで (英語で)
連絡してください。
本文書に関する質問については、<[email protected]> まで電子メールを (英語で)
送ってください。