doc/ja_JP.eucJP/books/fdp-primer/writing-style/chapter.sgml

<!-- Copyright (c) 1998 Nik Clayton, All rights reserved.

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1. Redistributions of source code (SGML DocBook) must retain the above
         copyright notice, this list of conditions and the following
         disclaimer as the first lines of this file unmodified.

      2. Redistributions in compiled form (transformed to other DTDs,
         converted to PDF, PostScript, RTF and other formats) must reproduce
         the above copyright notice, this list of conditions and the
         following disclaimer in the documentation and/or other materials
         provided with the distribution.

     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
     POSSIBILITY OF SUCH DAMAGE.


     The FreeBSD Japanese Documentation Project

     Original revision: 1.7
     $FreeBSD$
-->

<chapter id="writing-style">
  <title>文体について</title>

  <para>FreeBSD の文書はたくさんの人々によって書かれています.  
    そのため, 文書の一貫性を保てるよう, 作者向けにガイドラインがつくられています.  
  </para>
  
  <variablelist>
    <varlistentry>
      <term>短縮形は使わない</term>
      
      <listitem>
	<para>短縮形は使わないでください.  
          スペルは常に完全な形で書き, 
	  &ldquo;Don't use contractions&rdquo;
          というような表現は使ってはいけません.  
        </para>

	<para>短縮形を使わないことで文の調子が引き締まり, かたい感じになります.  
          また, 多少ですが翻訳者の負担を軽減できます.  
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term>並記の際にはカンマを使う</term>

      <listitem>
	<para>
          段落のなかで項目を並べる場合には, 
          それぞれの項目をカンマを使って分けてください.  
          最後の項目では, カンマと &ldquo;and&rdquo; を使います.  
        </para>

	<para>たとえば, 次の例を見てください.  </para>
	
	<blockquote>
	  <para>This is a list of one, two and three items.</para>
	</blockquote>

        <para>さて, これは三つの項目, &ldquo;one&rdquo;,
	  &ldquo;two&rdquo; および &ldquo;three&rdquo;
          を並べたものでしょうか?
          それとも, 二つの項目, &ldquo;one&rdquo; と &ldquo;two and three&rdquo;
          を並べたものなのでしょうか?
        </para>

	<para>これは, 
          並記の際にカンマを使うことではっきりさせることができます.  </para>
	
	<blockquote>
	  <para>This is a list of one, two, and three items.</para>
	</blockquote>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term>冗長な表現を避ける</term>
      
      <listitem>
        <para>冗長な表現を使わないよう配慮してください.  具体的に言うと, 
          &ldquo;the command&rdquo;,
          &ldquo;the file&rdquo;,
          そして &ldquo;man command&rdquo;
          というような表現は, いずれも余計なものです.  
        </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>
	
	<informalexample>
	  <para>&hellip; in the filename
	    <filename>/etc/rc.local</filename>&hellip;</para>
	</informalexample>
	
	<informalexample>
	  <para>&hellip; in
	    <filename>/etc/rc.local</filename>&hellip;</para>
	</informalexample>
	
	<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>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>文の最後には二個分の空白を入れる</term>

      <listitem>
	<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.columbia.edu/acis/bartleby/strunk/">Elements of
      Style</ulink> が参考になります.  </para>

  <sect1>
    <title>スタイルガイド</title>

    <para>ハンドブックはたくさんの人々によって編集されます.  
      ソースファイルにおける一貫性を維持するため, 
      以下にあげるようなスタイルを守るようにお願いします.  
    </para>

    <sect2>
      <title>大文字と小文字</title>

      <para>タグは小文字で入力します.  
        <literal>&lt;PARA&gt;</literal>
        <emphasis>ではなく</emphasis>, 
        <literal>&lt;para&gt;</literal> です.  
      </para>

      <para>SGML コンテキスト(訳注: DTD などの部分)では通常,
        大文字で書かれます.  
        たとえば <literal>&lt;!entity&hellip;&gt;</literal> や
	<literal>&lt;!doctype&hellip;&gt;</literal>
        <emphasis>ではなく</emphasis>, 
        <literal>&lt!ENTITY&hellip;&gt;</literal> や
	<literal>&lt;!DOCTYPE&hellip;&gt;</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>開始タグでは必ず二個分の空白で字下げ幅を増やし, 
        同様に終了タグでは二個分の空白で字下げ幅を減らします.  
        エレメント中の内容が一行以上にわたる場合は, 
        さらに二個分の空白で字下げされていなければなりません.  
      </para>

      <para>たとえば, このセクションのソースはつぎのようになっています.  </para>

      <programlisting>
<![ CDATA [+--- This is column 0
V
<chapter>
  <title>...</title>

  <sect1>
    <title>...</title>

    <sect2>
      <title>Indentation</title>

      <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>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>
    </sect2>

    <sect2>
      <title>タグのスタイル</title>

      <sect3>
	<title>タグ間のスペース</title>

	<para>
          タグはその前にあるタグと同じ字下げ幅ではじめ, 
          タグとの間は一行空けてください.  
          ただしその前のタグが同じ字下げ幅でなければ行を空けてはいけません.  
        </para>

	<informalexample>
	  <programlisting><![ CDATA [<article>
  <artheader>
    <title>NIS</title>

    <pubdate>October 1999</pubdata>

    <abstract>
      <para>...
	...
	...</para>
    </abstract>
  </artheader>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>
</article>]]></programlisting>
	</informalexample>
      </sect3>

      <sect3>
	<title>特殊なタグ</title>

	<para>
          いくつかのタグには前節であげた字下げルールにを適用しません.  
          <sgmltag>screen</sgmltag> タグと
          <sgmltag>programlisting</sgmltag> タグは, 
          常に左詰めにしてください.  
        </para>

	<informalexample>
	  <programlisting><![ RCDATA [<informalexample>
<programlisting>
&hellip;
</programlisting>
</informalexample>]]></programlisting>
	</informalexample>

	<para>
          <sgmltag>informalexample</sgmltag> タグも
          <sgmltag>screen</sgmltag> や
	  <sgmltag>programlisting</sgmltag>
          が含まれる場合には左詰めにします.  </para>

	<para>
          これらの例の場合は前後に空白行を入れ, 
          残りのテキストと分離してください.  
        </para>
      </sect3>

      <sect3>
	<title>タグの分離</title>

	<para>
          <sgmltag>itemizedlist</sgmltag>
          のようなタグは常に内部に別のタグが入り, 
          実際の文字データは入りません.  
          そのため, 常にタグだけで一行になります.  
        </para>

	<para><sgmltag>para</sgmltag> と <sgmltag>term</sgmltag> は, 
          通常の文字データを他のタグを使わずにそのまま入れることができます.  
          そのため, 内容は開始タグの直後, 
          すなわち<emphasis>同じ行から</emphasis>はじまります.  
        </para>

	<para>これは, 二種類のタグが閉じるときも同様です.  </para>
        
	<para>このルールは, この種のタグが混ぜて使われる際に問題となります.  </para>

	<para>直接文字データを含むことができない開始タグに続くタグがこの種のタグ, 
          すなわち文字データを入れるために他のタグを使わなければならないものであった場合, 
          それらはそれぞれ独立した行になります.  
          二番目のタグは, 適切に字下げされていなければなりません.  
        </para>

	<para>文字データを直接含むことのできるタグが
          データを直接含むことのできないタグの直後に現われる場合は, 
          それらは同一の行に共存することになります.  
        </para>
      </sect3>
    </sect2>

    <sect2>
      <title>空白の変更</title>

      <para>変更を commit する際には, 
        <emphasis>内容の変更と体裁の変更を同時に
          commit してはいけません</emphasis>.  
      </para>

      <para>これは, ハンドブックを他の言語に翻訳している翻訳チームがあなたの
        commit で実際の内容が変更されたことをすぐに判別できるようにするためです.  
        commit が分けてあれば, その変更が内容的なものか, 
        それとも単に整形のためなのかを確認する必要がなくなります.  
      </para>

      <para>たとえば, ある段落に二つの文を追加する場合を考えてみましょう.  
        文を追加したことにより, 段落の長さが 80 カラムを超えたとします.  
        そういう場合には, 最初の commit で整形せずに長いまま commit してください.  
        そして次に行の折り返しを行ない, 二回目としてその結果を commit します.  
        また, 二回目の commit ログには「これは空白の変更だけであり, 
        翻訳チームは無視しても大丈夫です」ということを示すようにしてください.  
      </para>
    </sect2>
  </sect1>
</chapter>

<!--
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->