diff options
Diffstat (limited to 'ja_JP.eucJP/books/fdp-primer/writing-style/chapter.sgml')
| -rw-r--r-- | ja_JP.eucJP/books/fdp-primer/writing-style/chapter.sgml | 449 |
1 files changed, 296 insertions, 153 deletions
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 eda093e5da..367fe858d8 100644 --- a/ja_JP.eucJP/books/fdp-primer/writing-style/chapter.sgml +++ b/ja_JP.eucJP/books/fdp-primer/writing-style/chapter.sgml @@ -30,111 +30,123 @@ The FreeBSD Japanese Documentation Project - Original revision: 1.9 - $FreeBSD: doc/ja_JP.eucJP/books/fdp-primer/writing-style/chapter.sgml,v 1.1 2001/03/07 19:40:56 hrs Exp $ + Original revision: 1.38 + $FreeBSD$ --> <chapter id="writing-style"> <title>文体について</title> - <para>FreeBSD の文書はたくさんの人々によって書かれています. - そのため, 文書の一貫性を保てるよう, 作者向けにガイドラインがつくられています. + <para>FreeBSD の文書はたくさんの人々によって書かれています。 + そのため、文書の一貫性を保てるよう、作者向けにガイドラインがつくられています。 </para> - + <variablelist> <varlistentry> + <term>米国式の英語のつづりを用いる</term> + + <listitem> + <para>英語には同じ単語に対して異なるつづりをする変種があります。 + いろいろなつづりがある場合には、米国式を用いてください。 + <quote>colour</quote> ではなく <quote>color</quote>, + <quote>rationalise</quote> ではなく <quote>rationalize</quote> + などです。</para> + </listitem> + </varlistentry> + + <varlistentry> <term>短縮形は使わない</term> - + <listitem> - <para>短縮形は使わないでください. - スペルは常に完全な形で書き, - “Don't use contractions” - というような表現は使ってはいけません. - </para> - - <para>短縮形を使わないことで文の調子が引き締まり, かたい感じになります. - また, 多少ですが翻訳者の負担を軽減できます. - </para> + <para>短縮形は使わないでください。 + スペルは常に完全な形で書き、 + <quote>Don't use contractions</quote> + というような表現は使ってはいけません。 + </para> + + <para>短縮形を使わないことで文の調子が引き締まり、かたい感じになります。 + また、多少ですが翻訳者の負担を軽減できます。 + </para> </listitem> </varlistentry> - + <varlistentry> <term>並記の際にはカンマを使う</term> <listitem> <para> - 段落のなかで項目を並べる場合には, - それぞれの項目をカンマを使って分けてください. - 最後の項目では, カンマと “and” を使います. - </para> + 段落のなかで項目を並べる場合には、 + それぞれの項目をカンマを使って分けてください。 + 最後の項目では、カンマと <quote>and</quote> を使います。 + </para> + + <para>たとえば、次の例を見てください。</para> - <para>たとえば, 次の例を見てください. </para> - <blockquote> <para>This is a list of one, two and three items.</para> </blockquote> - <para>さて, これは三つの項目, “one”, - “two” および “three” - を並べたものでしょうか? - それとも, 二つの項目, “one” と “two and three” - を並べたものなのでしょうか? - </para> + <para>さて、これは三つの項目、<quote>one</quote>, + <quote>two</quote> および <quote>three</quote> + を並べたものでしょうか? + それとも、二つの項目、<quote>one</quote> と <quote>two and three</quote> + を並べたものなのでしょうか? + </para> + + <para>これは、 + 並記の際にカンマを使うことではっきりさせることができます。</para> - <para>これは, - 並記の際にカンマを使うことではっきりさせることができます. </para> - <blockquote> <para>This is a list of one, two, and three items.</para> </blockquote> </listitem> </varlistentry> - + <varlistentry> <term>冗長な表現を避ける</term> - + <listitem> - <para>冗長な表現を使わないよう配慮してください. 具体的に言うと, - “the command”, - “the file”, - そして “man command” - というような表現は, いずれも余計なものです. - </para> - - <para>ここに, コマンドに関する二つの例を示します. - 好ましいのは二番目の例です. </para> - + <para>冗長な表現を使わないよう配慮してください。具体的に言うと、 + <quote>the command</quote>, + <quote>the file</quote>, + そして <quote>man command</quote> + というような表現は、いずれも余計なものです。 + </para> + + <para>ここに、コマンドに関する二つの例を示します。 + 好ましいのは二番目の例です。</para> + <informalexample> <para>Use the command <command>cvsup</command> to update your sources</para> </informalexample> - + <informalexample> <para>Use <command>cvsup</command> to update your sources</para> </informalexample> - - <para>次に, ファイル名に関する二つの例を示します. - こちらも, 好ましいのは二番目の例です. </para> - + + <para>次に、ファイル名に関する二つの例を示します。 + こちらも、好ましいのは二番目の例です。</para> + <informalexample> <para>… in the filename <filename>/etc/rc.local</filename>…</para> </informalexample> - + <informalexample> <para>… in <filename>/etc/rc.local</filename>…</para> </informalexample> - - <para>マニュアルページ参照に関する二つの例を示します. - こちらも, 好ましいのは二番目の例です (二番目の例では, - <sgmltag>citerefentry</sgmltag> が使われています). </para> + + <para>マニュアルページ参照に関する二つの例を示します。 + こちらも、好ましいのは二番目の例です (二番目の例では、 + <sgmltag>citerefentry</sgmltag> が使われています)。</para> <informalexample> <para>See <command>man csh</command> for more information.</para> </informalexample> - + <informalexample> <para>See &man.csh.1;</para> </informalexample> @@ -145,75 +157,75 @@ <term>文の最後には二個分の空白を入れる</term> <listitem> - <para>文の最後には, 常に二個分の空白を入れてください. - これは読みやすさを向上させるためと, - <application>emacs</application> - のようなツールで扱いやすくするためです. - </para> - - <para>文の最後のピリオドに続く文字は大文字だから, - スペースの数が一つでも文の最後と分かるじゃないか, - と思われた方がいらっしゃるかも知れませんが, - これは特に, 名前にピリオドが使われるときには当てはまりません. - 適当な例として, たとえば <quote>Jordan K. Hubbard</quote> - があげられます. この場合, ピリオドと一つのスペースの後ろに大文字の - <literal>H</literal> が来ていますが, - 明らかに新しい文のはじまりではありません. - </para> + <para>文の最後には、常に二個分の空白を入れてください。 + これは読みやすさを向上させるためと、 + <application>Emacs</application> + のようなツールで扱いやすくするためです。 + </para> + + <para>文の最後のピリオドに続く文字は大文字だから、 + スペースの数が一つでも文の最後と分かるじゃないか、 + と思われた方がいらっしゃるかも知れませんが、 + これは特に、名前にピリオドが使われるときには当てはまりません。 + 適当な例として、たとえば <quote>Jordan K. Hubbard</quote> + があげられます。この場合、ピリオドと一つのスペースの後ろに大文字の + <literal>H</literal> が来ていますが、 + 明らかに新しい文のはじまりではありません。 + </para> </listitem> </varlistentry> </variablelist> - <para>文体についての詳細は, William Strunk 氏による <ulink - url="http://www.bartleby.com/141/index.html">Elements of - Style</ulink> が参考になります. </para> + <para>文体についての詳細は、William Strunk 氏による <ulink + url="http://www.bartleby.com/141/">Elements of + Style</ulink> が参考になります。</para> - <sect1> + <sect1 id="writing-style-guide"> <title>スタイルガイド</title> - <para>ハンドブックはたくさんの人々によって編集されます. - ソースファイルにおける一貫性を維持するため, - 以下にあげるようなスタイルを守るようにお願いします. + <para>ハンドブックはたくさんの人々によって編集されます。 + ソースファイルにおける一貫性を維持するため、 + 以下にあげるようなスタイルを守るようにお願いします。 </para> <sect2> <title>大文字と小文字</title> - <para>タグは小文字で入力します. - <literal><PARA></literal> - <emphasis>ではなく</emphasis>, - <literal><para></literal> です. + <para>タグは小文字で入力します。 + <literal><PARA></literal> + <emphasis>ではなく</emphasis>、 + <literal><para></literal> です。 </para> - <para>SGML コンテキスト(訳注: DTD などの部分)では通常, - 大文字で書かれます. - たとえば <literal><!entity…></literal> や + <para>SGML コンテキスト(訳注: DTD などの部分)では通常、 + 大文字で書かれます。 + たとえば <literal><!entity…></literal> や <literal><!doctype…></literal> - <emphasis>ではなく</emphasis>, - <literal><!ENTITY…></literal> や + <emphasis>ではなく</emphasis>、 + <literal><!ENTITY…></literal> や <literal><!DOCTYPE…></literal> - というように書きます. + というように書きます。 </para> </sect2> <sect2> <title>字下げ</title> - <!-- hrs:2000/03/25 - what's "this one?" --> - <para>Each file starts with indentation set at column 0, - <emphasis>regardless</emphasis> of the indentation level of the file - which might contain this one.</para> + <para>それぞれのファイルの字下げは 0 桁目から始まります。 + 他のファイルに読み込まれる場合でも、 + 読み込む側のファイルの字下げの深さには<emphasis>よりません</emphasis>。 + </para> - <para>開始タグでは必ず二個分の空白で字下げ幅を増やし, - 同様に終了タグでは二個分の空白で字下げ幅を減らします. - エレメント中の内容が一行以上にわたる場合は, - さらに二個分の空白で字下げされていなければなりません. + <para>開始タグでは 2 個の空白で字下げ幅を増やし、 + 終了タグでは 2 個の空白で字下げ幅を減らします。 + 行頭の 8 つの空白のかたまりはタブへ置き換えられるべきです。 + タブの前に空白を用いず、行末に余分な空白を加えないでください。 + 要素の中身が一行以上に渡るならば 2 個の空白で字下げしてください。 </para> - <para>たとえば, このセクションのソースはつぎのようになっています. </para> + <para>たとえば、このセクションのソースはつぎのようになっています。</para> - <programlisting> -<![ CDATA [+--- This is column 0 + <programlisting><![ CDATA [+--- This is column 0 V <chapter> <title>...</title> @@ -228,21 +240,29 @@ V <emphasis>regardless</emphasis> of the indentation level of the file which might contain this one.</para> - <para>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.</para> - - ... + ... </sect2> </sect1> </chapter>]]></programlisting> <para>ファイルの編集に <application>Emacs</application> か - <application>Xemacs</application> を使っている場合には - <literal>sgml-mode</literal> が自動的にロードされますので, - 各ファイルの最後に書かれた Emacs - のローカル変数によってこのスタイルが維持されます. </para> + <application>XEmacs</application> を使っている場合には + <literal>sgml-mode</literal> が自動的にロードされますので、 + 各ファイルの最後に書かれた <application>Emacs</application> + のローカル変数によってこのスタイルが維持されます。</para> + + <para><application>Vim</application> + ユーザは以下のようにエディタを設定すると良いでしょう。</para> + + <programlisting>augroup sgmledit + autocmd FileType sgml set formatoptions=cq2l " Special formatting options + autocmd FileType sgml set textwidth=70 " Wrap lines at 70 spaces + 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</programlisting> + </sect2> <sect2> @@ -252,24 +272,24 @@ V <title>タグ間のスペース</title> <para> - タグはその前にあるタグと同じ字下げ幅ではじめ, - タグとの間は一行空けてください. - ただしその前のタグが同じ字下げ幅でなければ行を空けてはいけません. - </para> + タグはその前にあるタグと同じ字下げ幅ではじめ、 + タグとの間は一行空けてください。 + ただしその前のタグが同じ字下げ幅でなければ行を空けてはいけません。 + </para> <informalexample> <programlisting><![ CDATA [<article> - <artheader> + <articleinfo> <title>NIS</title> - <pubdate>October 1999</pubdata> + <pubdate>October 1999</pubdate> <abstract> <para>... - ... - ...</para> + ... + ...</para> </abstract> - </artheader> + </articleinfo> <sect1> <title>...</title> @@ -290,57 +310,180 @@ V <title>タグの分離</title> <para> - <sgmltag>itemizedlist</sgmltag> - のようなタグは常に内部に別のタグが入り, - 実際の文字データは入りません. - そのため, 常にタグだけで一行になります. - </para> - - <para><sgmltag>para</sgmltag> と <sgmltag>term</sgmltag> は, - 通常の文字データを他のタグを使わずにそのまま入れることができます. - そのため, 内容は開始タグの直後, - すなわち<emphasis>同じ行から</emphasis>はじまります. - </para> - - <para>これは, 二種類のタグが閉じるときも同様です. </para> - - <para>このルールは, この種のタグが混ぜて使われる際に問題となります. </para> - - <para>直接文字データを含むことができない開始タグに続くタグがこの種のタグ, - すなわち文字データを入れるために他のタグを使わなければならないものであった場合, - それらはそれぞれ独立した行になります. - 二番目のタグは, 適切に字下げされていなければなりません. - </para> + <sgmltag>itemizedlist</sgmltag> + のようなタグは常に内部に別のタグが入り、 + 実際の文字データは入りません。 + そのため、常にタグだけで一行になります。 + </para> + + <para><sgmltag>para</sgmltag> と <sgmltag>term</sgmltag> は、 + 通常の文字データを他のタグを使わずにそのまま入れることができます。 + そのため、内容は開始タグの直後、 + すなわち<emphasis>同じ行から</emphasis>はじまります。 + </para> + + <para>これは、二種類のタグが閉じるときも同様です。</para> + + <para>このルールは、この種のタグが混ぜて使われる際に問題となります。</para> + + <para>直接文字データを含むことができない開始タグに続くタグがこの種のタグ、 + すなわち文字データを入れるために他のタグを使わなければならないものであった場合、 + それらはそれぞれ独立した行になります。 + 二番目のタグは、適切に字下げされていなければなりません。 + </para> <para>文字データを直接含むことのできるタグが - データを直接含むことのできないタグの直後に現われる場合は, - それらは同一の行に共存することになります. - </para> + データを直接含むことのできないタグの直後に現われる場合は、 + それらは同一の行に共存することになります。 + </para> </sect3> </sect2> <sect2> <title>空白の変更</title> - <para>変更を commit する際には, - <emphasis>内容の変更と体裁の変更を同時に - commit してはいけません</emphasis>. + <para>変更を commit する際には、 + <emphasis>内容の変更と体裁の変更を同時に + commit してはいけません</emphasis>。 </para> - <para>これは, ハンドブックを他の言語に翻訳している翻訳チームがあなたの - commit で実際の内容が変更されたことをすぐに判別できるようにするためです. - commit が分けてあれば, その変更が内容的なものか, - それとも単に整形のためなのかを確認する必要がなくなります. + <para>これは、ハンドブックを他の言語に翻訳している翻訳チームがあなたの + commit で実際の内容が変更されたことをすぐに判別できるようにするためです。 + commit が分けてあれば、その変更が内容的なものか、 + それとも単に整形のためなのかを確認する必要がなくなります。 </para> - <para>たとえば, ある段落に二つの文を追加する場合を考えてみましょう. - 文を追加したことにより, 段落の長さが 80 カラムを超えたとします. - そういう場合には, 最初の commit で整形せずに長いまま commit してください. - そして次に行の折り返しを行ない, 二回目としてその結果を commit します. - また, 二回目の commit ログには「これは空白の変更だけであり, - 翻訳チームは無視しても大丈夫です」ということを示すようにしてください. + <para>たとえば、ある段落に二つの文を追加する場合を考えてみましょう。 + 文を追加したことにより、段落の長さが 80 カラムを超えたとします。 + そういう場合には、最初の commit で整形せずに長いまま commit してください。 + そして次に行の折り返しを行ない、二回目としてその結果を commit します。 + また、二回目の commit ログには「これは空白の変更だけであり、 + 翻訳チームは無視しても大丈夫です」ということを示すようにしてください。 </para> </sect2> + + <sect2> + <title>非改行空白</title> + + <para>改行により醜くなったり、 + 読みづらくなるような場所では改行を避けてください。 + 改行は選択した出力媒体の幅に依存します。 + 特に、HTML 文書をテキストブラウザで閲覧すると + 次の段落のように汚くフォーマットされることがあります。</para> + + <literallayout class="monospaced">Data capacity ranges from 40 MB to 15 +GB. Hardware compression …</literallayout> + + <para>一般実体 <literal>&nbsp;</literal> は、 + これを挟む場所での改行を禁止します。 + 非改行空白は次の場所で使用してください。</para> + + <itemizedlist> + <listitem> + <para>数値と単位の間:</para> + <programlisting><![ CDATA [57600 bps]]></programlisting> + </listitem> + + <listitem> + <para>プログラム名とバージョン番号の間:</para> + <programlisting><![ CDATA [FreeBSD 4.7]]></programlisting> + </listitem> + + <listitem> + <para>複数の単語から成る名前の間 (<quote>The FreeBSD Brazilian + Portuguese Documentation Project</quote> のような + 3, 4 語以上の名前へ適用する場合には注意してください):</para> + + <programlisting><![ CDATA [Sun Microsystems]]></programlisting> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 id="writing-style-word-list"> + <title>語句リスト</title> + + <para>次は FreeBSD ドキュメンテーションプロジェクトで用いるべき + つづりを示した小さな語句リストです。 + 探している語句がこのリストに見つからなかったら、 + <ulink + url="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly + word list</ulink> を参照してください。</para> + + <itemizedlist> + <listitem> + <para>2.2.X</para> + </listitem> + + <listitem> + <para>4.X-STABLE</para> + </listitem> + + <listitem> + <para>CDROM</para> + </listitem> + + <listitem> + <para>DoS <emphasis>(Denial of Service)</emphasis> </para> + </listitem> + + <listitem> + <para>FreeBSD Ports Collection</para> + </listitem> + + <listitem> + <para>IPsec</para> + </listitem> + + <listitem> + <para>Internet</para> + </listitem> + + <listitem> + <para>MHz</para> + </listitem> + + <listitem> + <para>Soft Updates</para> + </listitem> + + <listitem> + <para>Unix</para> + </listitem> + + <listitem> + <para>disk label</para> + </listitem> + + <listitem> + <para>email</para> + </listitem> + + <listitem> + <para>file system</para> + </listitem> + + <listitem> + <para>manual page(s)</para> + </listitem> + + <listitem> + <para>mail server</para> + </listitem> + + <listitem> + <para>name server</para> + </listitem> + + <listitem> + <para>ports collection</para> + </listitem> + + <listitem> + <para>web server</para> + </listitem> + </itemizedlist> + </sect1> </chapter> |