<!-- Copyright (c) 1998, 1999 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.19
     $FreeBSD$

-->

<chapter id="overview">
  <title>概要</title>

  <para>FreeBSD ドキュメンテーションプロジェクトへようこそ.  
    質の高い文書は, FreeBSD
    を成功させるために欠かすことができない重要なものです.   FreeBSD
    ドキュメンテーションプロジェクト(FreeBSD Documentation Project;
    FDP)は, そのような文書を数多く作成するためのプロジェクトです.  
    あなたの貢献は, 非常に貴重です.  
  </para>

  <para>この文書は主に <emphasis>FDP の構成</emphasis>, 
    <emphasis>文書の作成と FDP への提出方法</emphasis>および, 
    <emphasis>文書作成のために利用できるツールの効果的な利用法</emphasis>
    について解説することを目的としています.  
  </para>

  <para><indexterm>
      <primary>参加資格</primary>
    </indexterm>
    FDP は, どなたでも参加できます.  参加資格はありませんし, 
    毎月, 文書の作成が義務づけられているわけでもありません.  
    あなたがしなければならないのは, ただ
    &a.doc;
    メーリングリストに参加することだけです.  
  </para>

  <para>この文書を読み終えた後, 
    あなたは次のようになっていなければなりません.  </para>
  
  <itemizedlist>
    <listitem> 
      <para>どれが FDP が管理する文書はなのか理解して下さい.  </para>
    </listitem>
    
    <listitem>
      <para>FDP の管理する文書の SGML のソースコードを読み, 
        意味が理解できるようになってください.  
      </para>
    </listitem>
    
    <listitem> 
      <para>文書へ変更を加える操作ができるようになってください.  </para>
    </listitem>
    
    <listitem>
      <para>あなたの変更が査読を受け, FreeBSD
        の文書として採用にまわせるよう, 変更の提出ができるようになってください.  
      </para>
    </listitem> 
  </itemizedlist>

  <sect1 id="overview-doc">
    <title>FreeBSD 文書セット</title>

    <para>FDP では FreeBSD 関連文書のうち, 次の
      4 つのカテゴリを担当しています.  
    </para>
    
    <variablelist>
      <varlistentry>
        <term>マニュアルページ</term>

        <listitem>
          <para>システムの英語版マニュアルページは基本システムの一部であり, 
            FDP がその作成を担当しているわけではありません.  
            しかし FDP は, マニュアルページをよりわかりやすくしたり, 
            不正確な記述を修正するため, 既存のマニュアルページの改編を行なうことが
            できます.  
          </para>

          <para>翻訳チームは, システムのマニュアルページを他言語に翻訳する
            作業を担当しています.  この翻訳作業は, FDP の担当範囲内です.  
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>FAQ</term>
	
        <listitem>
          <para>FAQ は, FreeBSD
            に関連するさまざまなメーリングリストやニュースグループで
            よく尋ねられる質問, あるいは質問されるべきものについて, 
            (短い質疑応答形式で)取り扱ったものです.  
            この形式では, 必要以上に長く細かい回答は許されません.  
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ハンドブック</term>

        <listitem>
          <para>ハンドブックは広範囲の話題を扱った FreeBSD のユーザのための
            オンライン情報源, およびリファレンスとなることを意図したものです.  
          </para>
        </listitem>
      </varlistentry>
 
      <varlistentry>
         <term>ウェブサイト</term>
	
         <listitem>
          <para>これは, World Wide Web において中心的な FreeBSD のサイトであり, 
            <ulink url="../../../../index.html">http://www.FreeBSD.org/</ulink>
            と, 世界中に存在するたくさんのミラーサイトから見ることができます.  
            このウェブサイトは, 多くの人々が FreeBSD
            を初めて目にする場所でもあります.  
          </para>
	</listitem>
      </varlistentry>
    </variablelist>
    
    <para>この 4 種類の文書は, いずれも FreeBSD CVS ツリーから入手することができます.  
      そのため, ファイルへの変更履歴は一般に公開されていて, 
      <application>CVSup</application> や
      <application>CTM</application> といったプログラムを使い
      誰でも文書のローカルコピーを最新のものに保つことができます.  
    </para>
    
    <para>さらに, たくさんの人々がチュートリアルや FreeBSD
      関連のウェブサイトをつくっています.  それらのなかには, 
      他の文書と同じように CVS リポジトリ(の原作者が同意した場所)に
      含まれているものもある一方, FreeBSD のリポジトリからは分離して, 
      原作者の手によって直接保守されているものもあります.  
      FDP では, そのような文書に対して可能な限り, 
      リンクを提供するように努力しています.  
    </para>
  </sect1>

  <sect1 id="overview-before">
    <title>はじめる前に</title>
    
    <para>この文書は, 次にあげる内容について
      あなたがすでに理解していることを前提として書かれています.  
    </para>
    
    <itemizedlist>                                                             
      <listitem>
	<para>FreeBSD CVS リポジトリのローカルコピーを
          (<application>CVS</application>, もしくは
	  <application>CVSup</application> か
	  <application>CTM</application> を使って) 入手したり,
          <application>CVSup</application> を使って
	  <emphasis>チェックアウトした(checked-out)</emphasis>コピーを
          ダウンロードすることで,
          FreeBSD の文書のローカルコピーを最新に維持する方法について.  
        </para>
      </listitem>
      
      <listitem>
	<para>FreeBSD Ports システム, もしくは &man.pkg.add.1
          を利用して新しいソフトウェアをダウンロードし, インストールする方法について.  
        </para>
      </listitem>                                                              
    </itemizedlist>                                                            
  </sect1>

  <sect1 id="overview-quick-start">
    <title>まずははじめてみる</title>

    <para>もし何かやってみたくなって, 継続してやっていく自信があるなら,
      以下の手順を追ってみてください.</para>

    <procedure>
      <step>
	<para><filename role="package">textproc/docproj</filename> メタ port を
	  インストールします.</para>

	<screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
      </step>

      <step>
	<para>FreeBSD <filename>doc</filename> ツリーのローカルコピー
	  を入手します.
	  CVSup を <literal>checkout</literal> モードで使うか,
	  CVS リポジトリの完全なコピーをローカルに取り寄せるかします.
	</para>

	<para>CVS リポジトリをローカルに持つようにした場合,
	  少なくとも <filename>doc/share</filename> と
	  <filename>doc/en_US.ISO8859-1/share</filename> ディレクトリ
	  をチェックアウトする必要があります.</para>

	<screen>&prompt.user; <userinput>cvs checkout doc/share</userinput>
&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/share</userinput></screen>

	<para>ディスクスペースに余裕があるようでしたら, 全てをチェックアウト
	  してしまうこともできます.</para>

	<screen>&prompt.user; <userinput>cvs checkout doc</userinput></screen>
      </step>

      <step>
	<para>既存の book もしくは article に変更を加えようと
	  している場合には, リポジトリのその部分をチェックアウトします.
	  新規に book や article を寄稿しようとしている場合には,
	  既存のものをテンプレートとして使ってください.</para>

	<para>例えば, FreeBSD と Windows 2000 の間に VPN を設定するような
	  新しい article を寄稿しようとしている場合, 以下のようにします.
	</para>

	<procedure>
	  <step>
	    <para><filename>articles</filename> ディレクトリを
	      チェックアウトします.</para>

	    <screen>&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/articles</userinput></screen>
	  </step>

	  <step>
	    <para>既存の article をテンプレートとして使うために
	      コピーします.
	      今回は, 新しい article は <filename>vpn-w2k</filename>
	      というディレクトリに入れることにしましょう.</para>

	    <screen>&prompt.user; <userinput>cd doc/en_US.ISO8859-1/articles</userinput>
&prompt.user; <userinput>cp -r committers-guide vpn-w2k</userinput></screen>
	  </step>
	</procedure>

	<para>もし <filename>doc/en_US.ISO8859-1/books/faq</filename>
	  にある FAQ のような既存の文書に手を加える場合,
	  リポジトリから以下のようにチェックアウトします.</para>

	<screen>&prompt.user; <userinput>cvs checkout doc/en_US.ISO8859-1/books/faq</userinput></screen>
      </step>

      <step>
	<para><filename>.sgml</filename> ファイルをあなたの好きな
	  エディタで編集します.</para>
      </step>

      <step>
	<para><maketarget>lint</maketarget> ターゲットでマークアップ
	  をテストします.
	  これにより, 時間のかかる変換を実際に行なうこと無く,
	  文書中の間違いをすばやく見つけることができます.</para>

	<screen>&prompt.user; <userinput>make lint</userinput></screen>

	<para>文書を実際に構築する準備ができたら,
	  <varname>FORMATS</varname> 変数で単一のフォーマット,
	  もしくはフォーマットの一覧を指定することができます.
	  今のところ,
  	  <literal>html</literal>, <literal>html-split</literal>,
  	  <literal>txt</literal>, <literal>ps</literal>,
  	  <literal>pdf</literal>, <literal>rtf</literal>
	  が指定できます.
	  サポートされているフォーマットの最新のリストは
	  <filename>doc/share/mk/doc.docbook.mk</filename> ファイルの
	  先頭を見てください.
	  単一のコマンドで複数のフォーマットを構築しようとする際
	  には, フォーマットの一覧を引用符で括ることを忘れないでください.
	</para>

        <para>例えば, 文書を <literal>html</literal> に変換する
	  だけなら以下のようになります:</para>

	<screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen>

        <para>文書を <literal>html</literal> と <literal>txt</literal>
	  の両方のフォーマットに変換したい場合は, 以下のように
	  &man.make.1; を二回にわけて実行することでできます:</para>

	<screen>&prompt.user; <userinput>make FORMATS=html</userinput>
&prompt.user; <userinput>make FORMATS=txt</userinput></screen>

        <para>一回のコマンドで実行するには, 以下のようになります:</para>

	<screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>
      </step>

      <step>
	<para>変更点を &man.send-pr.1; を使って提出します.</para>
      </step>
    </procedure>
  </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:
-->
