diff --git a/ja_JP.eucJP/books/fdp-primer/overview/chapter.sgml b/ja_JP.eucJP/books/fdp-primer/overview/chapter.sgml index 42e6c75da8..43cc3c93fd 100644 --- a/ja_JP.eucJP/books/fdp-primer/overview/chapter.sgml +++ b/ja_JP.eucJP/books/fdp-primer/overview/chapter.sgml @@ -1,204 +1,204 @@ 概要 FreeBSD ドキュメンテーションプロジェクトへようこそ. 質の高い文書は, FreeBSD を成功させるために欠かすことができない重要なものです. FreeBSD ドキュメンテーションプロジェクト(FreeBSD Documentation Project; FDP)は, そのような文書を数多く作成するためのプロジェクトです. あなたの貢献は, 非常に貴重です. この文書は主に FDP の構成, 文書の作成と FDP への提出方法および, 文書作成のために利用できるツールの効果的な利用法 について解説することを目的としています. FDP は, どなたでも参加できます. 参加資格はありませんし, 毎月, 文書の作成が義務づけられているわけでもありません. あなたがしなければならないのは, ただ freebsd-doc@FreeBSD.org メーリングリストに参加することだけです. この文書を読み終えた後, あなたは次のようになっていなければなりません. どれが FDP が管理する文書はなのか理解して下さい. FDP の管理する文書の SGML のソースコードを読み, 意味が理解できるようになってください. 文書へ変更を加える操作ができるようになってください. あなたの変更が査読を受け, FreeBSD の文書として採用にまわせるよう, 変更の提出ができるようになってください. FreeBSD 文書セット FDP では FreeBSD 関連文書のうち, 次の 4 つのカテゴリを担当しています. マニュアルページ システムの英語版マニュアルページは基本システムの一部であり, FDP がその作成を担当しているわけではありません. しかし FDP は, マニュアルページをよりわかりやすくしたり, 不正確な記述を修正するため, 既存のマニュアルページの改編を行なうことが できます. 翻訳チームは, システムのマニュアルページを他言語に翻訳する 作業を担当しています. この翻訳作業は, FDP の担当範囲内です. FAQ FAQ は, FreeBSD に関連するさまざまなメーリングリストやニュースグループで よく尋ねられる質問, あるいは質問されるべきものについて, (短い質疑応答形式で)取り扱ったものです. この形式では, 必要以上に長く細かい回答は許されません. ハンドブック ハンドブックは広範囲の話題を扱った FreeBSD のユーザのための オンライン情報源, およびリファレンスとなることを意図したものです. ウェブサイト これは, World Wide Web において中心的な FreeBSD のサイトであり, http://www.FreeBSD.org/ と, 世界中に存在するたくさんのミラーサイトから見ることができます. このウェブサイトは, 多くの人々が FreeBSD を初めて目にする場所でもあります. この 4 種類の文書は, いずれも FreeBSD CVS ツリーから入手することができます. - そのため, ログとファイルへの変更は一般に公開されていて, + そのため, ファイルへの変更履歴は一般に公開されていて, CVSupCTM といったプログラムを使い 誰でも文書のローカルコピーを最新のものに保つことができます. さらに, たくさんの人々がチュートリアルや FreeBSD 関連のウェブサイトをつくっています. それらのなかには, 他の文書と同じように CVS リポジトリ(の原作者が同意した場所)に 含まれているものもある一方, FreeBSD のリポジトリからは分離して, 原作者の手によって直接保守されているものもあります. FDP では, そのような文書に対して可能な限り, リンクを提供するように努力しています. はじめる前に この文書は, 次にあげる内容について あなたがすでに理解していることを前提として書かれています. - FreeBSD の文書のローカルコピーを入手し, 最新に維持する方法について. - これには, FreeBSD CVS リポジトリのローカルコピーを + FreeBSD CVS リポジトリのローカルコピーを (CVS, もしくは CVSup か - CTM を使って)維持するか, もしくは + CTM を使って) 入手したり, CVSup を使って チェックアウトした(checked-out)コピーを - ダウンロードするという方法があります. + ダウンロードすることで, + FreeBSD の文書のローカルコピーを最新に維持する方法について. FreeBSD Ports システム, もしくは &man.pkg.add.1 を利用して新しいソフトウェアをダウンロードし, インストールする方法について. diff --git a/ja_JP.eucJP/books/fdp-primer/psgml-mode/chapter.sgml b/ja_JP.eucJP/books/fdp-primer/psgml-mode/chapter.sgml index 7a542726f1..c3aaff7c48 100644 --- a/ja_JP.eucJP/books/fdp-primer/psgml-mode/chapter.sgml +++ b/ja_JP.eucJP/books/fdp-primer/psgml-mode/chapter.sgml @@ -1,166 +1,166 @@ <application>Emacs</application> で <literal>sgml-mode</literal> を利用する 新しいバージョンの Emacs や Xemacs(Ports Collection にあります)には, PSGML と呼ばれる非常に便利なパッケージが附属しています. - これは拡張子が .sgml のファイルが読み込まれるか, + これは拡張子がとなっている .sgml のファイルが読み込まれるか, M-x sgml-mode と入力することで呼び出されます. PSGML は, SGML ファイルやエレメント, 属性を扱うためのメジャーモードです. このモードで提供されているいくつかのコマンドを知っていれば, ハンドブックなどの SGML 文書をより簡単に扱うことができるようになります. C-c C-e sgml-insert-element を実行します. 実行すると, 現在のカーソル位置に挿入すべきエレメント名が聞かれ, TAB キーを使うことでエレメント名の補完ができます. また, カーソル位置に挿入できないエレメント名は入力できないようになっています. 挿入は, 指定したエレメントのスタートタグとエンドタグが両方行なわれます. もし, そのエレメントが他の必須エレメントを含む場合は, その必須エレメントも同じように挿入されます. C-c = sgml-change-element-name を実行します. カーソルをエレメントの内側に移動させてこのコマンドを実行して下さい. 変更するエレメント名が聞かれ, 現在のエレメントのスタートタグとエンドタグが 入力した新しいエレメントのものに変更されます. C-c C-r sgml-tag-region を実行します. テキストを指定(テキストの開始点に移動して C-Space を押し, 終了点に移動して C-Space を押す)してから, このコマンドを実行して下さい. 利用するエレメント名が聞かれ, マークが付けられた範囲(リージョン)のすぐ前後に指定したエレメントが挿入されます. C-c - sgml-untag-element を実行します. カーソルを削除したいエレメントのスタートタグか, エンドタグの上において このコマンドを実行して下さい. すると, エレメントのスタートタグ, エンドタグが両方とも削除されます. C-c C-q sgml-fill-element を実行します. 実行すると, カーソル位置のエレメントの内容に対して, (整形する時のように)再帰的な文章の詰めが行なわれます. この詰め作業は, 含まれている空白文字が重要なもの, たとえば programlisting エレメントの中などでも効果がありますので, 利用の際は注意して下さい. C-c C-a sgml-edit-attributes を実行します. 実行するともう一つバッファを開き, 最も近い閉じたエレメントのすべての属性のリストと, 現在の値を表示します. TAB を使って属性間を移動することができ, C-k を 押すことで, 既存の値を新しいものに置き換えることができます. また, C-c を押すことで, バッファを閉じて 元の文書に戻ることができます. C-c C-v sgml-validate を実行します. 実行すると(必要に応じて)現在編集中の文書をセーブするかどうか聞かれ, 次に SGML の正当性検査が行なわれます. 検査の出力は新しいバッファに表示されますので, 誤りのある部分へひとつひとつ移動してマークアップのミスを修正することができます. もちろん, このモードには他にも有用な機能があります. ここにあげたのは, その中でもわたしが非常に頻繁に利用しているものです. diff --git a/ja_JP.eucJP/books/fdp-primer/see-also/chapter.sgml b/ja_JP.eucJP/books/fdp-primer/see-also/chapter.sgml index 509e0df519..2b39002538 100644 --- a/ja_JP.eucJP/books/fdp-primer/see-also/chapter.sgml +++ b/ja_JP.eucJP/books/fdp-primer/see-also/chapter.sgml @@ -1,123 +1,124 @@ 参考サイト この文書は, SGML や DTD, FreeBSD ドキュメンテーションプロジェクトに関して, すべてを網羅したものではありません. さらに詳しい内容については, 以下のウェブサイトをご覧になることをおすすめします. FreeBSD ドキュメンテーションプロジェクト FreeBSD ドキュメンテーションプロジェクトのウェブページ FreeBSD ハンドブック(英語版) SGML SGML/XML ウェブページ. これは広範囲にわたる網羅的な SGML の情報源です. やさしい SGML 入門 HTML World Wide Web コンソーシアム HTML 4.0 規格書 DocBook - The Davenport - Group. ここは DocBook DTD の保守を行なっているところです. + The DocBook + Technical Committee. + ここは DocBook DTD の保守を行なっているところです. Linux ドキュメンテーションプロジェクト - Linux + Linux ドキュメンテーションプロジェクトのウェブページ diff --git a/ja_JP.eucJP/books/fdp-primer/tools/chapter.sgml b/ja_JP.eucJP/books/fdp-primer/tools/chapter.sgml index 8fd4d1dde3..deec842422 100644 --- a/ja_JP.eucJP/books/fdp-primer/tools/chapter.sgml +++ b/ja_JP.eucJP/books/fdp-primer/tools/chapter.sgml @@ -1,306 +1,305 @@ ツール FDP では FreeBSD の文書を管理したり, 他の出力形式にに整形したりするため, さまざまなソフトウェアツールを利用します. FreeBSD の文書で作業するには, あなた自身がそれらのツールを使う必要があります. これらのツールはすべて FreeBSD の port や package として入手可能で, インストール作業は非常に簡単です. 以下の章に書かれた例を試すには, あらかじめ これらのツールがインストールされていなければなりません. 各ツールの実際の利用方法は, その例が書かれた章で説明されています. できるだけ <filename>textproc/docproj</filename> を利用してください textproc/docproj の port を使うとインストールする手間を大きく省くことができます. これは メタ(meta) port と呼ばれる port で, その中にソフトウェアが含むかわりに, 他のさまざまな port が正しくインストールされるように依存関係がつくられているものです. この port をインストールすると, - この章であげられているソフトウェアのうち, - あなたのシステムにインストールされていないものが + この章であげられているソフトウェアが 自動的にすべてダウンロードされ, インストールされます. 必要となるパッケージの一つに, JadeTeX マクロセットというものがあります. このマクロセットは, インストール時に TeX がインストールされていることを必要とします. TeX は非常に大きなパッケージですが, Postscript や PDF 形式の出力を行なわないならばインストールの必要はありません. 時間とディスクスペースの節約のため, この port をインストールする際に, JadeTeX(すなわち TeX を含む) を必要とするかどうかを指定する必要があります. 次のいずれかを, 場合に応じて実行して下さい. &prompt.root; make JADETEX=yes install &prompt.root; make JADETEX=no install 必須のツール ソフトウェア 以下のプログラムは, FreeBSD の文書で快適に作業するために必要なものです. これらはすべて, textproc/docproj に含まれています. SP (textproc/sp) 正当性検査のための SGML パーサや SGML 正規化ツールを含むアプリケーションのセットです. Jade (textproc/jade) DSSSL の実装です. これはマークアップされた文書を HTML や TeX といった他の形式に変換するために使われます. Tidy (www/tidy) HTML 整形ツールです. これは自動生成された HTML 文書を整形し, より利用しやすいものにするために使われます. - Lynx - (www/lynx-current) + W3M + (www/w3m) - テキストモードの WWW ブラウザです. &man.lynx.1; + テキストモードの WWW ブラウザです. &man.w3m.1; は, HTML ファイルをプレインテキストに変換することができます. 文書型定義(DTD)と実体宣言(entity) 以下にあげるのは, FDP で使われている DTD と実体宣言集合(entity set)です. これらはいずれも, 文書を取り扱う前に必要となります. HTML DTD (textproc/html) HTML は, World Wide Web で採用されているマークアップ言語です. これは FreeBSD ウェブサイト全体でも利用されます. LinuxDoc DTD (textproc/linuxdoc) FreeBSD の文書には, LinuxDoc でマークアップされたものがあります. FDP では, LinuxDoc から DocBook への移行を積極的にすすめています. DocBook DTD (textproc/docbook) DocBook は, 技術文書のマークアップのために設計された DTD であり, FDP では LinuxDoc から DocBook への移行をすすめています. この原稿を執筆している時点で, FreeBSD ハンドブックが DockBook によってマークアップされています. ISO 8879 公開実体宣言 (textproc/iso8879) ISO 8879:1986 に規定された 19 種類の 文字実体集合です. これはたくさんの DTD で利用されるもので, 数学記号や latin 文字集合の追加文字(アクセント記号, 発音記号など), ギリシャ文字などが含まれます. スタイルシート スタイルシートは, 文書を画面表示や印刷などに利用される形式に変換, 整形するために使われます. Modular DocBook Stylesheets (textproc/dsssl-docbook-modular) Modular DocBook Stylesheets は, DocBook DTD でマークアップされた文書を HTML や RTF 形式に変換するのに使われます. 必須でない(optional)ツール もし必要性を感じないなら, 以下にあげるソフトウェアはインストールしなくともかまいません. しかしインストールしていれば, 文書の取り扱いに便利だと感じるでしょうし, これらを使うことで, より多様な出力形式で文書を出力することが可能となります. ソフトウェア JadeTeX および teTeX (print/jadetex および - print/teTeX-beta) + print/teTeX) JadeteTeX は, DocBook 文書を DVI, Postscript, PDF の各形式に変換するのに使われます. また, このとき JadeTeX マクロも必要となります. 文書をそのような形式に変換しなくて良い (たとえば HTML, プレインテキスト, RTF で十分であるような)場合には, JadeTeX および teTeX をインストールする必要はありません. これらのインストールには大きなディスクスペースと時間を必要とします. teTeX は, 30MB を超える大きなものです. JadeTeXteTeX をインストールする場合には, JadeTeX がインストールされた後, teTeX の設定を行なわなければなりません. 必要な手順の詳細は, print/jadetex/pkg/MESSAGE に説明されています. Emacs もしくは xemacs (editors/emacs もしくは editors/xemacs) このエディタは両方とも, SGML DTD でマークアップされた文書を編集するための特別なモードを備えています. このモードには, 必要なタイプ量や誤りをを低減するためのコマンドがあります. どのようなテキストエディタでもマークアップされた文書を編集することは可能ですので, これらを使う必要があるというわけではありません. しかしおそらく, これらは便利なものだと感じると思います. もし, この他に SGML 文書を扱うために有用なソフトウェアをご存知でしたら, Nik Clayton(nik@FreeBSD.org) までお知らせ下さい. このリストに加えさせていただきます. diff --git a/ja_JP.eucJP/books/fdp-primer/writing-style/chapter.sgml b/ja_JP.eucJP/books/fdp-primer/writing-style/chapter.sgml index 511e0c8849..eda093e5da 100644 --- a/ja_JP.eucJP/books/fdp-primer/writing-style/chapter.sgml +++ b/ja_JP.eucJP/books/fdp-primer/writing-style/chapter.sgml @@ -1,387 +1,357 @@ 文体について FreeBSD の文書はたくさんの人々によって書かれています. そのため, 文書の一貫性を保てるよう, 作者向けにガイドラインがつくられています. 短縮形は使わない 短縮形は使わないでください. スペルは常に完全な形で書き, “Don't use contractions” というような表現は使ってはいけません. 短縮形を使わないことで文の調子が引き締まり, かたい感じになります. また, 多少ですが翻訳者の負担を軽減できます. 並記の際にはカンマを使う 段落のなかで項目を並べる場合には, それぞれの項目をカンマを使って分けてください. 最後の項目では, カンマと “and” を使います. たとえば, 次の例を見てください.
This is a list of one, two and three items.
さて, これは三つの項目, “one”, “two” および “three” を並べたものでしょうか? それとも, 二つの項目, “one” と “two and three” を並べたものなのでしょうか? これは, 並記の際にカンマを使うことではっきりさせることができます.
This is a list of one, two, and three items.
冗長な表現を避ける 冗長な表現を使わないよう配慮してください. 具体的に言うと, “the command”, “the file”, そして “man command” というような表現は, いずれも余計なものです. ここに, コマンドに関する二つの例を示します. 好ましいのは二番目の例です. Use the command cvsup to update your sources Use cvsup to update your sources 次に, ファイル名に関する二つの例を示します. こちらも, 好ましいのは二番目の例です. … in the filename /etc/rc.local … in /etc/rc.local マニュアルページ参照に関する二つの例を示します. こちらも, 好ましいのは二番目の例です (二番目の例では, citerefentry が使われています). See man csh for more information. See &man.csh.1; 文の最後には二個分の空白を入れる 文の最後には, 常に二個分の空白を入れてください. これは読みやすさを向上させるためと, emacs のようなツールで扱いやすくするためです. 文の最後のピリオドに続く文字は大文字だから, - スペースの数が 一つでも文の最後と分かるじゃないか, + スペースの数が一つでも文の最後と分かるじゃないか, と思われた方がいらっしゃるかも知れませんが, これは特に, 名前にピリオドが使われるときには当てはまりません. 適当な例として, たとえば Jordan K. Hubbard があげられます. この場合, ピリオドと一つのスペースの後ろに大文字の H が来ていますが, 明らかに新しい文のはじまりではありません.
文体についての詳細は, William Strunk 氏による Elements of + url="http://www.bartleby.com/141/index.html">Elements of Style が参考になります. スタイルガイド ハンドブックはたくさんの人々によって編集されます. ソースファイルにおける一貫性を維持するため, 以下にあげるようなスタイルを守るようにお願いします. 大文字と小文字 タグは小文字で入力します. <PARA> ではなく, <para> です. SGML コンテキスト(訳注: DTD などの部分)では通常, 大文字で書かれます. たとえば <!entity…><!doctype…> ではなく, <!ENTITY…><!DOCTYPE…> というように書きます. 字下げ Each file starts with indentation set at column 0, regardless of the indentation level of the file which might contain this one. 開始タグでは必ず二個分の空白で字下げ幅を増やし, 同様に終了タグでは二個分の空白で字下げ幅を減らします. エレメント中の内容が一行以上にわたる場合は, さらに二個分の空白で字下げされていなければなりません. たとえば, このセクションのソースはつぎのようになっています. ... ... Indentation Each file starts with indentation set at column 0, regardless of the indentation level of the file which might contain this one. Every start tag increases the indentation level by 2 spaces, and every end tag decreases the indentation level by 2 spaces. Content within elements should be indented by two spaces if the content runs over more than one line. ...
]]> ファイルの編集に EmacsXemacs を使っている場合には sgml-mode が自動的にロードされますので, 各ファイルの最後に書かれた Emacs のローカル変数によってこのスタイルが維持されます. タグのスタイル タグ間のスペース タグはその前にあるタグと同じ字下げ幅ではじめ, タグとの間は一行空けてください. ただしその前のタグが同じ字下げ幅でなければ行を空けてはいけません. NIS October 1999 ... ... ... ... ... ... ... ]]> - - 特殊なタグ - - - いくつかのタグには前節であげた字下げルールにを適用しません. - screen タグと - programlisting タグは, - 常に左詰めにしてください. - - - - - -… - -]]> - - - - informalexample タグも - screen や - programlisting - が含まれる場合には左詰めにします. - - - これらの例の場合は前後に空白行を入れ, - 残りのテキストと分離してください. - - - タグの分離 itemizedlist のようなタグは常に内部に別のタグが入り, 実際の文字データは入りません. そのため, 常にタグだけで一行になります. paraterm は, 通常の文字データを他のタグを使わずにそのまま入れることができます. そのため, 内容は開始タグの直後, すなわち同じ行からはじまります. これは, 二種類のタグが閉じるときも同様です. このルールは, この種のタグが混ぜて使われる際に問題となります. 直接文字データを含むことができない開始タグに続くタグがこの種のタグ, すなわち文字データを入れるために他のタグを使わなければならないものであった場合, それらはそれぞれ独立した行になります. 二番目のタグは, 適切に字下げされていなければなりません. 文字データを直接含むことのできるタグが データを直接含むことのできないタグの直後に現われる場合は, それらは同一の行に共存することになります. 空白の変更 変更を commit する際には, 内容の変更と体裁の変更を同時に commit してはいけません. これは, ハンドブックを他の言語に翻訳している翻訳チームがあなたの commit で実際の内容が変更されたことをすぐに判別できるようにするためです. commit が分けてあれば, その変更が内容的なものか, それとも単に整形のためなのかを確認する必要がなくなります. たとえば, ある段落に二つの文を追加する場合を考えてみましょう. 文を追加したことにより, 段落の長さが 80 カラムを超えたとします. そういう場合には, 最初の commit で整形せずに長いまま commit してください. そして次に行の折り返しを行ない, 二回目としてその結果を commit します. また, 二回目の commit ログには「これは空白の変更だけであり, 翻訳チームは無視しても大丈夫です」ということを示すようにしてください.