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