18.3. ドキュメントのアップデート

ドキュメントは、FreeBSD オペレーティングシステムの必須要素です。 FreeBSD ドキュメントセットの最新バージョンは、 FreeBSD ウェブサイト から入手できますが、 ネットワーク接続が遅い、もしくはまったく接続できないユーザもいます。 ローカルのドキュメントを最新の FreeBSD ドキュメントセットにアップデートする方法がいくつも用意されています。

18.3.1. Subversion を用いたドキュメントのアップデート方法

FreeBSD のドキュメントのソースは、 svn を用いて入手できます。 この節では以下について説明します。

  • ドキュメントツールチェインのインストール方法。 このツールは、FreeBSD のドキュメントをソースから再構築するのに必要です。

  • svn を用いて、 ドキュメントのソースを /usr/doc 以下にダウンロードする方法。

  • FreeBSD ドキュメントをソースから再構築し、 /usr/share/doc 以下にインストールする方法。

  • ドキュメントのビルドシステムにおいてサポートされているビルドオプションの説明。 たとえば、翻訳されたドキュメンテーションのみを構築するオプションや、 ある特定の出力フォーマットを指定するようなオプションについて説明します。

18.3.2. svn およびドキュメントツールチェインのインストール

FreeBSD のドキュメントをソースから再構築するには、 ツールのコレクションが必要です。 これらのツールは多くのディスク容量を使用するため、 FreeBSD ベースシステムの一部ではありません。 また、すべての FreeBSD ユーザにとって有用というわけではなく、FreeBSD のために新しいドキュメントを活発に執筆している方や、 頻繁にドキュメントをソースからアップデートする方に向けたものです。

svn を含め必要なツールは、 textproc/docproj メタ port からインストールできます。この port は、 FreeBSD ドキュメンテーションプロジェクトにより開発されています。

注記:

ドキュメントの PostScript® や PDF 版が必要なければ、かわりに textproc/docproj-nojadetex をインストールすることも考えてよいでしょう。 このドキュメンテーションのツールチェインは、 teTeX と呼ばれる組版エンジンを除いたすべてをインストールします。 teTeX は大きなツールのコレクションです。 そのため、もし PDF 出力を本当に必要としなければ、 このツールをインストールしないことはとても賢明です。

18.3.3. ドキュメントのソースをアップデートする

以下の例では、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

18.3.4. ドキュメントのソースの調整可能なオプション

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 ドキュメンテーションプロジェクト入門 を参照してください。

18.3.5. ソースから 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 ドキュメンテーションプロジェクト入門 をご覧ください。

18.3.6. ドキュメンテーション ports

ベースとなった作業:Fonvieille Marc [FAMILY Given].

これまでのセクションでは、ソースコードを用いた FreeBSD ドキュメントのアップデート方法について説明してきました。 すべての FreeBSD システムで、 ソースからドキュメントをアップデートすることは難しいかも知れませんし、 できたとしても現実的ではないこともあります。 ドキュメントをソースから構築するには、 かなり大きなツールとユーティリティから構成される ドキュメンテーションツールチェイン が必要なためです。 また、svn リポジトリからソースをチェックアウトし、 チェックアウトしたソースからドキュメントを手動で構築する方法について、 それなりに熟知している必要もあります。 この節では、インストールされている FreeBSD のドキュメントをアップデートするもう一つの方法である、 Ports Collection を用いた方法について説明し、 以下について説明します。

  • 構築済のドキュメントのスナップショットをダウンロードしてインストールする方法。 ローカルでの構築作業やドキュメンテーションツールチェインをインストールする必要はありません。

  • ドキュメントのソースをダウンロードし、ports フレームワークを使って構築する方法です。 チェックアウトおよび構築作業が簡単になります。

FreeBSD のドキュメントをアップデートするこれらの方法は、 ドキュメンテーションエンジニアリングチーム が毎月アップデートしている ドキュメンテーション ports によりサポートされています。 これらの ports は、FreeBSD Ports Collection の docs カテゴリにまとめられています。

18.3.6.1. ドキュメンテーション ports の構築とインストール

ドキュメンテーション 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
18.3.6.1.1. 共通のオプション

ドキュメンテーション ports にはたくさんのオプションが用意されており、 以下のように ports の振る舞いをデフォルトの設定から変更できます。

WITH_HTML

HTML 形式を構築します。 各ドキュメントに対し、単一版の HTML ファイルが構築されます。 整形されたドキュメントは、 article.htmlbook.html といった名前で、 必要に応じて画像とともにインストールされます。

WITH_PDF

Adobe® Portable Document Format (PDF) を構築します。 整形されたドキュメントは、 article.pdfbook.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

18.3.6.2. ドキュメンテーション package の利用

前節で説明した、 ソースからドキュメンテーション port を構築する方法では、 ドキュメンテーションツールチェインをローカルにインストールする必要があり、 また、ports の構築のためにディスク容量を必要とします。 ドキュメンテーションツールチェインをインストールするリソースがない場合や、 ソースから構築する場合には多くのディスク容量を必要とするため、 構築済みのドキュメンテーション ports のスナップショットが用意されています。

ドキュメンテーションエンジニアリングチーム は、毎月 FreeBSD ドキュメンテーション package のスナップショットをアップデートしています。 これらのバイナリ package は、システムに用意されている pkg_add(1), pkg_delete(1) などの package 管理ツールを用いて扱うことができます。

注記:

バイナリ package を使うと、 インストールする言語に用意されている すべて の形式の FreeBSD ドキュメントがインストールされます。

たとえば、以下のコマンドを実行すると、 ハンガリー語のドキュメントの最新 package がインストールされます。

# pkg install hu-freebsd-doc

注記:

ドキュメントの package は、対応する port 名とは異なり、 lang-freebsd-doc の形式で名前がつけられています。 ここで、lang は言語コードの短縮形です。 ハンガリー語の場合は hu、簡体字の場合には zh_cn です。

18.3.6.3. ドキュメンテーション ports のアップデート

他の port と同様に、ドキュメンテーション port をアップデートできます。 たとえば、以下のコマンドを実行すると、ports-mgmt/portupgrade から、package だけを使ってインストールされているハンガリー語のドキュメントをアップデートします。

# portmaster -PP hu-freebsd-doc

本文書、および他の文書は ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/ からダウンロードできます。

FreeBSD に関する質問がある場合には、 ドキュメント を読んだ上で <questions@FreeBSD.org> まで (英語で) 連絡してください。

本文書に関する質問については、 <doc@FreeBSD.org> まで電子メールを (英語で) 送ってください。