文体について
FreeBSD の文書はたくさんの人々によって書かれています。
そのため、文書の一貫性を保てるよう、作者向けにガイドラインがつくられています。
米国式の英語のつづりを用いる
英語には同じ単語に対して異なるつづりをする変種があります。
いろいろなつづりがある場合には、米国式を用いてください。
colour
ではなく color
,
rationalise
ではなく rationalize
などです。
短縮形は使わない
短縮形は使わないでください。
スペルは常に完全な形で書き、
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
Style が参考になります。
スタイルガイド
ハンドブックはたくさんの人々によって編集されます。
ソースファイルにおける一貫性を維持するため、
以下にあげるようなスタイルを守るようにお願いします。
大文字と小文字
タグは小文字で入力します。
<PARA>
ではなく、
<para> です。
SGML コンテキスト(訳注: DTD などの部分)では通常、
大文字で書かれます。
たとえば <!entity…> や
<!doctype…>
ではなく、
<!ENTITY…> や
<!DOCTYPE…>
というように書きます。
頭字語
一般的に、頭字語が文書中に最初に表れた時は "Network Time Protocol
(NTP)"
のように略さずに書くべきです。頭字語が定義されたら、以後は一般的には
(文脈上完全な表現を用いることに意義がなければ、完全な表現ではなく)
その頭字語のみを使用すべきです。通常は頭字語は文書全体で
1 回だけ定義します。ただし、好みに応じて各章で最初に現れる時に
定義してもよいでしょう。
頭字語を使う最初の 3 回は、role 属性に
完全な表現を定義した <acronym> タグで括ってください。
こうすると用語解説へのリンクが作成され、マウスポインタを上に
もってくると完全な表現が表示されます。
字下げ
それぞれのファイルの字下げは 0 桁目から始まります。
他のファイルに読み込まれる場合でも、
読み込む側のファイルの字下げの深さにはよりません。
開始タグでは 2 個の空白で字下げ幅を増やし、
終了タグでは 2 個の空白で字下げ幅を減らします。
行頭の 8 つの空白のかたまりはタブへ置き換えられるべきです。
タブの前に空白を用いず、行末に余分な空白を加えないでください。
要素の中身が一行以上に渡るならば 2 個の空白で字下げしてください。
たとえば、このセクションのソースはつぎのようになっています。
...
...
Indentation
Each file starts with indentation set at column 0,
regardless of the indentation level of the file
which might contain this one.
...
]]>
ファイルの編集に Emacs か
XEmacs を使っている場合には
sgml-mode が自動的にロードされますので、
各ファイルの最後に書かれた Emacs
のローカル変数によってこのスタイルが維持されます。
Vim
ユーザは以下のようにエディタを設定すると良いでしょう。
augroup sgmledit
autocmd FileType sgml set formatoptions=cq2l " Special formatting options
autocmd FileType sgml set textwidth=70 " Wrap lines at 70 columns
autocmd FileType sgml set shiftwidth=2 " Automatically indent
autocmd FileType sgml set softtabstop=2 " Tab key indents 2 spaces
autocmd FileType sgml set tabstop=8 " Replace 8 spaces with a tab
autocmd FileType sgml set autoindent " Automatic indentation
saugroup END
タグのスタイル
タグ間のスペース
タグはその前にあるタグと同じ字下げ幅ではじめ、
タグとの間は一行空けてください。
ただしその前のタグが同じ字下げ幅でなければ行を空けてはいけません。
NIS
October 1999
...
...
...
...
...
...
...
]]>
タグの分離
itemizedlist
のようなタグは常に内部に別のタグが入り、
実際の文字データは入りません。
そのため、常にタグだけで一行になります。
para と term は、
通常の文字データを他のタグを使わずにそのまま入れることができます。
そのため、内容は開始タグの直後、
すなわち同じ行からはじまります。
これは、二種類のタグが閉じるときも同様です。
このルールは、この種のタグが混ぜて使われる際に問題となります。
直接文字データを含むことができない開始タグに続くタグがこの種のタグ、
すなわち文字データを入れるために他のタグを使わなければならないものであった場合、
それらはそれぞれ独立した行になります。
二番目のタグは、適切に字下げされていなければなりません。
文字データを直接含むことのできるタグが
データを直接含むことのできないタグの直後に現われる場合は、
それらは同一の行に共存することになります。
空白の変更
変更を commit する際には、
内容の変更と体裁の変更を同時に
commit してはいけません。
これは、ハンドブックを他の言語に翻訳している翻訳チームがあなたの
commit で実際の内容が変更されたことをすぐに判別できるようにするためです。
commit が分けてあれば、その変更が内容的なものか、
それとも単に整形のためなのかを確認する必要がなくなります。
たとえば、ある段落に二つの文を追加する場合を考えてみましょう。
文を追加したことにより、段落の長さが 80 カラムを超えたとします。
そういう場合には、最初の commit で整形せずに長いまま commit してください。
そして次に行の折り返しを行ない、二回目としてその結果を commit します。
また、二回目の commit ログには「これは空白の変更だけであり、
翻訳チームは無視しても大丈夫です」ということを示すようにしてください。
非改行空白
改行により醜くなったり、
読みづらくなるような場所では改行を避けてください。
改行は選択した出力媒体の幅に依存します。
特に、HTML 文書をテキストブラウザで閲覧すると
次の段落のように汚くフォーマットされることがあります。
Data capacity ranges from 40 MB to 15
GB. Hardware compression …
一般実体 は、
これを挟む場所での改行を禁止します。
非改行空白は次の場所で使用してください。
数値と単位の間:
プログラム名とバージョン番号の間:
複数の単語から成る名前の間 (The FreeBSD Brazilian
Portuguese Documentation Project
のような
3, 4 語以上の名前へ適用する場合には注意してください):
語句リスト
次は FreeBSD ドキュメンテーションプロジェクトで用いるべき
つづりを示した小さな語句リストです。
探している語句がこのリストに見つからなかったら、
O'Reilly
word list を参照してください。
2.2.X
4.X-STABLE
CDROM
DoS (Denial of Service)
FreeBSD Ports Collection
IPsec
Internet
MHz
Soft Updates
Unix
disk label
email
file system
manual page
mail server
name server
ports collection
web server