<!doctype linuxdoc system>
<article>
<title>JF リポジトリについて
<author>CVS committers of The JF Project &lt;<tt/JF@linux.or.jp/&gt;
<date>$Revision: 1.2 $ $Date: 2004/01/31 16:06:11 $
<abstract>
    これは JF Project の CVS リポジトリに関して解説する文書です。
    (JF 文書ではありません。CVS の操作方法に関する解説でもありません。)

    JF では Web ページの再構築にあたり、JF 文書を含めたコンテンツ
    すべてをバージョン管理システム CVS で維持することになりました。
    この文書は CVS を使ってどのようにコンテンツを維持しようとしているのか、
    また、実際にリポジトリのファイルを更新し、Web コンテンツなどに反映させる
    にはどうすればよいか、など、基本的な情報を提供するものです。
    committer になって JF の資源管理を手伝おうとお考えの方の足掛かりと
    なれば幸いです。
</abstract>

<toc><!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect>予備知識(1) …… コンテンツ生成の実際<label id="intro1">
<p>
    JF の Web 公開にあたっては、JLA の提供するリソースを
    利用しています。以下出てくるサーバ群に対するリクエストは、
    JLA-admin@linux.or.jp までお願いします。
    この ML には、JF からは やまだ、馬場、森本、中野、福島の
    各氏が参加しています。

<p>
    JF の Web コンテンツはすべて JF の CVS リポジトリに納められています。
    CVS リポジトリの維持は <tt/cvs.linux.or.jp/ で行われています。
<!--    リポジトリの内容は以下の URL で確認できます。

    <quote><tt>
    <url url="http://cvs.linux.or.jp/JF/">
    </tt></quote>

-->
<p>
    リポジトリの更新履歴を参照したい場合は cvsweb (リポジトリのファイルと
    履歴を視覚的にわかりやすく表示する CGI アプリケーション) も利用できます。

    <quote><tt>
    <url url="http://cvs.linux.or.jp/cgi-bin/cvsweb/JF/?cvsroot=JF">
    </tt></quote>

<p>
    <tt/master.linux.or.jp/ では、
    リポジトリの中身を定期的に取り出しています。
    そしてこのホスト上で Build が行われ、
    コンテンツが生成されます。
    Namazu インデックスの生成もここで行われます。

<p>
    ここで生成されたコンテンツそのものは一般に公開されませんが、
    JF メンバは以下の URL で確認することができます。

    <quote><tt>
    <url url="http://master.linux.or.jp/JF/">
     Auth ID: jf / Password: lisachan
    </tt></quote>

<p>
    生成された Web コンテンツは、6 時間おきに
    ホスト <tt>www.linux.or.jp</tt> へと <tt>rsync</tt> で転送され、
    実際に公開されることになります。

    <quote><tt>
    <url url="http://www.linux.or.jp/JF/">
    </tt></quote>

    ここからさらに、各地のミラーサーバへと伝播していきます。

<p>
    これらの <tt/crontab/ は以下の通りです。

<verb>
   build:           55 * * * *
   namazu:          30 5 * * *
   rsync:           45 4,10,16,22 * * *
</verb>
<p>

<p>
    FTP コンテンツも <tt/minori.linux.or.jp/ で生成された後、
    JF のプライマリ FTP サイトへと転送されます。

    <quote><tt>
    <url url="ftp://ftp.linet.gr.jp/pub/JF/">
    (JF ディレクトリ)
    </tt></quote>
    <quote><tt>
    <url url="ftp://ftp.linet.gr.jp/pub/howto-translations/">
    (LDP の翻訳だけを集めたディレクトリ)
    </tt></quote>

<p>
    ここから <tt><url url="ftp://metalab.unc.edu/"></tt>
    をはじめ、各地のミラーサイトへ伝播していきます。

<!-- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -->
<sect>予備知識(2) …… CVS で管理するメリット<label id="intro2">
<p>
    CVS を使ってコンテンツソースを管理することで、複数のメンバーが
    作業を同時に並行してできるようになります。
    各メンバーは自分の ``作業コピー'' を CVS サーバから入手し、それを編集し、
    また CVS サーバの管理するリポジトリに反映させることができます。
    これによって、これまで小野さん個人に委ねられていた JF の資源管理を、
    複数のメンバーによって分担することができます。

<p>
    資源管理をする特定のホスト上に編集作業のためのログインユーザアカウントを
    設置する必要がないので、セキュリティの面からも好ましいといえます。

<p>
    将来的には、翻訳・執筆など、文書自体の作成作業を複数の人間が
    共同して行う場合に、バージョン管理や作業分担などが容易になるという
    メリットも見込めます。
    &lsqb;<ref id="sec-cvs" name="→ CVS を利用した執筆作業">&rsqb;

<p>
    一方 CVS に依存することは、CVS の利用方法を知らないメンバーの
    作業への参加を阻害してしまうというデメリットも考えられます。
    また、CVS は作業者間の意思疏通を図るための手段とはなりえません。
    これらのデメリットは、JF-ML でのコミュニケーションを密に行い、
    意見交換をきちんとすることである程度解消できるものと思われます。
    CVS と ML をうまく使いわけて、それぞれのメリットを生かせる形で
    資源管理を進めていきたいと思います。

<p>
    なお、この Web や FTP などの資源管理一般については JF-ML から
    派生した JF-gofer-ML で議論されています。JF-gofer-ML に関しては、

    <quote><tt>JF-gofer-ctl@linux.or.jp</tt></quote>

    に <tt/# guide/ とだけ書いたメールを送ると折り返しガイドが
    返信されますので、そちらを参照してください。

<!-- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -->
<sect>JF コンテンツ生成 (Build)
<sect1>Build の概略<label id="build-overview">
<p>
    JF リポジトリをすべて checkout すると、FTP 配布パッケージや Web コンテンツ
    などを生成 (Build) することができます。

<p>
    Build にあたってはリポジトリのコピーの他に、
    LinuxDoc-Tools, jade, w3m, nkf, GNU m4, Perl 5.003 などの
    ツールが必要です。
    これらのツールのあるディレクトリにはすべて PATH を通しておいてください。
    また、JF コンテンツのすべてを Build するには 100MB 以上のディスクスペースが
    必要になります。

<p>
    JF リポジトリに納められている <tt/Makefile/ は実際の Build マシンの
    環境にあわせて準備されています。
    おそらくディレクトリ配置に関しては、
    必ず変更をせまられることになるでしょう。
    このディレクトリ配置の初期値は <tt/JF.conf/ の冒頭に書かれていますので、
    この部分を直接書き換えるか、
    Build 時に make のコマンドラインオプションで指定することになります。

<sect1>Build の例
<p>
    以下のサブセクションでは幾つかの Build の例をあげます。
    <tt/JF.conf/ を直接書き換える場合はディレクトリの指定は省略できます。

<sect2>JF パッケージを作るとき (Full Build & install)
<p>
<tscreen><verb>
 % make PROJROOT=/home/user/jfwork/JF WORKDIR=/var/tmp
  (文書ソースから各種フォーマットの閲覧用文書を作成します)
 % make PROJROOT=/home/user/jfwork/JF WORKDIR=/var/tmp \
        DESTROOT=/home/www install
  (配布パッケージを作成し /home/www 以下に全てのコンテンツを
   install します)
</verb></tscreen>

<sect2>LDP ミラー用ファイル群を作るとき
<p>
<tscreen><verb>
  (これ以降の例では PROJROOT, DESTROOT, WORKDIR などの指定は
   省略しています。)
 % make INSTALL_LDP=yes install
</verb></tscreen>

<sect2>商用配布用パッケージをつくるとき
<p>
<tscreen><verb>
 % make RESTRICT_COMMERCIAL=yes install
</verb></tscreen>

<sect2>ゴミ掃除
<p>
<tscreen><verb>
 % make clean
</verb></tscreen>

<sect1>make に絡むファイルの説明
<p>
    <itemize>
    <item>JF.conf …… ディレクトリの配置などを記述したファイル
    <item>JF.rules …… コンパイル用のルールファイル
    <item>Makefile …… コンパイル用 Makefile
    </itemize>

<!-- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -->
<sect>リポジトリの中で文書はどのように管理されているのか?
<sect1>全体の構成
<p>
    JF リポジトリは、大きくわけて以下のような構成になっています。
    <descrip>
     <tag>JF/docs</tag>
          文書そのものが個別に置かれるディレクトリが配置されています。
     <tag>JF/www</tag>
	  Web 用コンテンツのツリーです。一部は make install の過程で
          自動生成されます。
     <tag>JF/ftp</tag>
	  FTP 用コンテンツと共に配置される
	  文書以外のメッセージファイルなどが置かれています。
     <tag>JF/lists</tag>
	JF パッケージ作成に必要な各種データが置かれています
     <tag>JF/bin</tag>
	JF パッケージ作成に必要な各種ツールが置かれています
     <tag>JF/admin</tag>
	その他の管理用データファイルが置かれています。
    </descrip>

<sect1>各文書の構成<label id="document-structure">
<p>
    各文書ディレクトリ <tt>JF/docs/*</tt> とその中に置かれるファイルは、
    一部の例外を除き以下のような規則で名前付けされ、配置されます。

<quote>
「一部の例外」の代表的な例としては、Linux カーネルの付属文書
(<tt>Documentation/</tt> ディレクトリ以下の各ファイル) の翻訳が
挙げられます。これについては <ref id="Kernel-Docs" name="→カーネル文書">
をご覧ください。
</quote>

    <descrip>

     <tag>ディレクトリ名</tag>
     文書の名称。文書のタイトルではありません。
     この名前は文書を識別する際の固有名称 (BASENAME) として、
     パッケージ生成の際に利用されます。
     日本語翻訳であることを示唆する文字列 (ja など) は付けない慣習に
     なっています。

     <tag>SGML ファイル</tag>
     $(BASENAME).sgml という名前の、SGML フォーマットで
     記述された文書ファイルです。
     日本語翻訳であることを示唆する文字列 (ja など) は付けない慣習に
     なっています。文字コードは日本語 EUC です。

     <tag>info ファイル</tag>
     info という名前のテキストファイルです。info の記述法については、
     JF Web Page の中の
     <htmlurl url="http://www.linux.or.jp/JF/workshop/guidance-infofile.html"
     name="JF Workshop Guidance: 文書情報管理ファイル(info)について">
     を参照してください。
     info ファイルの文字コードは日本語 EUC です。

     <tag>Makefile</tag><label id="makefile-for-release">
     LinuxDoc 形式の SGML ファイルの場合、通常は以下の内容を記述します。
     <tscreen><verb>
     include ../../JF.conf
     include ../../JF.rules
     </verb></tscreen>
    </descrip>

<!-- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -->
<sect>一般文書の管理(1)<label id="General-Docs">
<sect1>文書の新規登録<label id="add-doc">
<p>
    <ref id="document-structure" name="[各文書の構成]"> にしたがって、
    必要なファイルを用意し、CVS リポジトリに commit または import します。
    基本的には、オリジナルが sgml ファイル 1 個だけなら，ディレクトリを作って
    sgml ファイルと <tt/Makefile/ と <tt/info/ を入れるだけです。
<p>
    この <tt/Makefile/ と <tt/info/ のテンプレートは
    <tt>JF/admin/template/</tt> に用意されていますので参考にしてください。
<p>
    ただし、追加登録しようとする文書のステータスによって、
    <tt/Makefile/ と <tt/info/ にどのような内容を登録するかが
    変ってきます。もし文書がまだドラフト段階であり、正式に公開するのではなく、
    共同作業を行うためにリポジトリに登録する場合は、
    <ref id="starting-work" name="CVSの上で執筆作業をはじめるには">
    の章をご覧になってください。
<p>
    なお、特殊な場合は、それに見合った Makefile をあつらえてもかまいません。
<p>
    <tt>JF/www/news.m4</tt> は、
    文書の新規追加・更新をお知らせする JF Web ページの
    ための M4 ソースファイルです。
    ファイルの冒頭にコメントで書かれているように、
    簡単なルールで新規文書・更新文書が記述できますので、
    ぜひこのファイルも更新して commit してください。
    詳しくは
    <ref id="news_m4" name="news.m4 への登録">
    に関する説明を参照してください。

<sect2>CHECKLIST for committers
<p>
<enum>
<item>文書の BASENAME となるディレクトリを作成する.
 <tscreen><verb>
 % mkdir FOO-HOWTO
 </verb></tscreen>
<item>ディレクトリの中に、必要なファイルを用意する.
     <enum>
       <item>info
       <item>FOO-HOWTO.sgml 
       <item>Makefile
     </enum>
<item>各ファイルの漢字コードがすべて日本語 EUC になっていることを確認する.
<item>CVS リポジトリに入れる.
 <tscreen><verb>
 % cd FOO-HOWTO
 % ls -F
 Makefile    FOO-HOWTO.sgml  info

 % setenv CVSROOT :pserver:yourname@cvs.linux.or.jp:/JF
    or
 $ export CVSROOT=:pserver:yourname@cvs.linux.or.jp:/JF

 % cvs import -m "Import of FOO-HOWTO" \
       JF/docs/FOO-HOWTO JF FOO-HOWTO-Initial
 </verb></tscreen>

<item>ChangeLog に記入する.
 <tscreen><verb>
 % cvs checkout JF/ChangeLog
   (編集)
 % cvs commit -m "added FOO-HOWTO" JF/ChangeLog
 </verb></tscreen>

<item>JF/www/news.m4 で告知する.
 <tscreen><verb>
 % cvs checkout JF/www/news.m4
   (編集)
 % cvs commit -m "added FOO-HOWTO" JF/www/news.m4
 </verb></tscreen>

</enum>


<sect1>文書の更新登録<label id="Update-Docs">
<p>
    <ref id="document-structure" name="[各文書の構成]"> にしたがって、
    更新されたファイルを CVS リポジトリに commit します。
    通常は SGML 文書ファイルそのものと、<tt/info/ ファイルが更新の
    対象になります。
<p>
    <tt>JF/www/news.m4</tt> は、
    文書の新規追加・更新をお知らせする JF Web ページの
    ための M4 ソースファイルです。
    ファイルの冒頭にコメントで書かれているように、
    簡単なルールで新規文書・更新文書が記述できますので、
    ぜひこのファイルも更新して commit してください。
    詳しくは
    <ref id="news_m4" name="news.m4 への登録">
    に関する説明を参照してください。

<sect2>CHECKLIST for committers
<p>
<enum>
<item>文書をリポジトリから取り出す
 <tscreen><verb>
 % cvs checkout JF/docs/FOO-HOWTO
 </verb></tscreen>
<item>ファイルを更新する
<item>各ファイルの文字コードがすべて日本語 EUC になっていることを確認する.
<item>CVS リポジトリに入れる.
 <tscreen><verb>
 % cd FOO-HOWTO
 % ls -F
 CVS/    Makefile    FOO-HOWTO.sgml  info
 % cvs commit -m "updated: FOO-HOWTO" .
 </verb></tscreen>

<item>ChangeLog に記入する.
 <tscreen><verb>
 % cvs checkout JF/ChangeLog
   (編集)
 % cvs commit -m "updated: FOO-HOWTO" JF/ChangeLog
 </verb></tscreen>

<item>JF/www/news.m4 で告知する.
 <tscreen><verb>
 % cvs checkout JF/www/news.m4
   (編集)
 % cvs commit -m "updated: FOO-HOWTO" JF/www/news.m4
 </verb></tscreen>

</enum>


<sect1>無効になった文書の削除
<p>
     <enum>
     <item>オリジナルが SGML ファイル 1 個だけなら，
           それを <tt>docs/obsolete</tt> に移動し、そちらで保管します。
     <item>同様に <tt>info</tt> は識別可能な名前
           (<tt>BASENAME.info</tt>) に rename して
           <tt>docs/obsolete</tt> に移動します。
     <item><tt/Makefile/ は削除します。
     <item><tt>docs/obsolete/obsoleted.list</tt> に <tt>BASENAME</tt> を
           書いておきます。
	   ここに書かれた文書については、すでに ftp と Web コンテンツに
	   行ってしまったファイルも追っかけて削除できるはずです。
     </enum>
    以上 4 つの変更点を CVS に commit します。

<sect1>Windows 環境での注意点
<p>
Windows 環境下での commit 作業をする際はファイルの case(大文字・小文字)に注意してください。Windows は case の違うファイルも同一の物として扱いますが、cvs では両者は区別されます。リポジトリに登録される際のファイル名は、cvs コマンドに渡した引数がまったくそのまま引き継がれます。

例えば foo.sgml ファイルが存在する時に <tt>cvs add FOO.SGML</tt> と実行すると、Windows ではファイル名の case は区別されないためリポジトリへの追加作業は正常終了しますが、登録されたファイル名は引数で指定された <tt>FOO.SGML</tt> という大文字のファイル名になってしまいます。


<sect>一般文書の管理(2):info ファイル
<p>
    info ファイルは各文書の管理情報を記録するファイルです。
    これは JF 文書の戸籍謄本のようなもので、
    すべての公開文書はこの info ファイルの記載にしたがって、
    分類・管理されています。
    ひとつの文書につき、必ずひとつの info ファイルを用意します。
    原則として、文書を作成した本人が
    この info ファイルを作成することになっています。
<p>
    info ファイルのフォーマットは JF Web Page の中の
    <htmlurl 
    url="http://www.linux.or.jp/JF/workshop/guidance-infofile.html#kdoc-info-format" name="JF Workshop Guidance: 文書情報管理ファイル(info)について">
    を参照してください。
    この文書では info ファイルのフォーマットに関する解説は省略します。

<p>
    以下のセクションでは、目的に応じた info ファイルの更新の例をとりあげます。

<sect1>文書の所属ジャンルを変更する
<p>
    <enum>
    <item>JF リポジトリから目的の文書の info ファイルを checkout します。
    公開されている JF の cvsweb 
    (&lsqb;<ref id="intro1" 
    name="→ 予備知識(1) …… コンテンツ生成の実際">&rsqb; を参照)
    や、cvs サーバから http 経由で入手することもできます。
    <item>info ファイルをエディタで編集します。
    例えば、現在 'その他' に分類されているものを 'ツールの解説' に
    変更したい場合は、ITEM: etc となっている行を ITEM: tool に
    編集します。
    <item>編集の終わった info ファイルを JF リポジトリに commit します。
    cvsweb など http 経由で元のファイルを入手した場合は、
    info ファイルの変更を JF-ML に流して commit できる人に
    お願いすることになります。
    </enum>
<p>
    既存のジャンルではなく、新たにジャンルを作成する場合は、
    info ファイルの更新だけでは無理なので、
    JF-ML などで相談してください。
    実際には複数のファイルの更新が必要になりますが、
    新設する作業自体は難しくありません。

<sect1>文書の商用再配布を禁止する
<p>
    基本的なプロセスは前項と同じです。今度は info ファイルの COPY の
    行を編集します。COPY: NO-COM とすると、その後は商用配布パッケージに
    含まれないことになります。

<sect1>文書の更新日時など、その他の変更
<p>
    基本的なプロセスは前項と同じです。
    JF Web Page の中の
    <htmlurl url="http://www.linux.or.jp/JF/workshop/guidance-infofile.html#kdoc-info-format" name="JF Workshop Guidance: 文書情報管理ファイル(info)について">
    を確認した上で、必要な項目を修正し、commit します。

<sect>一般文書の管理(3):予約リスト等

<sect1>なぜ info 以外のデータファイルが必要か?
<p>
    JF では作業状況進行リストなど、常に最新に保つ必要のある文書を
    メンテナンスしなければなりません。
    また、複数のリスト間で食い違いが生じることのないように、
    情報源を統一する必要があります。
    先の章で述べた info ファイルもそれにあたりますが、実際には
    翻訳の予約など、info ファイルだけでは処理できない情報もあります。
<p>
    以下で説明するファイルは、いずれも管理情報の源となるものです。
    それぞれに適合する情報は、これらのファイルで一括して管理するように
    したいと思います。いずれのファイルも、情報を記入するためにあるのであって、
    直接閲覧することは意図されていないことに注意してください。

<sect1>翻訳作業の予約リスト<label id="reserve">
<p>
    翻訳作業の予約リスト は <tt>JF/lists/reserved.list</tt> に
    記述します。フォーマットは info とほぼ同じですが、必要な項目は
    ずっと少なくなっています。
    <itemize>
    <item><bf>NAME:</bf> <it>BASENAME</it> …… 翻訳元文書ファイルの BASENAME
    <item><bf>TRNS:</bf> <it>email@address</it> …… 予約した人の email address
    <item><bf>PDAT:</bf> <it>YYYY/MM/DD</it> …… 予約宣言をした日
    <item><bf>STAT:</bf> <it>VALUE</it> …… 現在の状況。<it/VALUE/ は
    以下の中から選択
       <itemize>
         <item><it>Reserved</it> ... 予約がなされている状況
         <item><it>Draft</it>    ... ドラフト(草稿)が出ている状況
         <item><it>Release</it>  ... リリース版が出ている状況
       </itemize>
    <item><bf>NOTE:</bf>            …… その他の特記事項を記入。
    LDP 文書以外の場合、文書が存在する URL などを記入してください。
    </itemize>

<p>
    以下に、予約リストへの記入例を示します。
    <code>
    NAME: Hard-Disk-Upgrade
    TRNS: nagaoka@jttk.zaq.ne.jp
    PDAT: 2001/01/14
    STAT: Reserved
    NOTE: [JF:12949]
    </code>
<p>
    このファイルに記述した予約は、 JF-in-Progress などの作業状況
    進行リストに反映されます。
    リストに反映されるルールは:
<enum>
<item>現在公開されている翻訳が原著の最新版に
      完全に追従している場合は、
      予約リストの内容は作業状況進行リストには表示されません
<item>
      未翻訳のものを対象としている場合は、
      予約者のメールアドレスが作業状況進行リストに
      表示されます
</enum>
    いうまでもないことですが、原文が更新されると同時に翻訳は古くなります。
    このことと、上記ルールを考えあわせると、
    作業終了後に <tt>reserved.list</tt> の取り扱いをどうしたらよいかが
    わかると思います。
<p>
    作業終了後<tt>reserved.list</tt> から予約を削除すると、
    当然ですが原文が更新されても作業進行リストに名前は出現しません。
<p>
    一方、<tt>reserved.list</tt> が更新されなかった場合は、
    原文が更新されると自動的に作業進行リストに予約者のメールアドレスが
    再掲載されます。
<p>

<sect1>LDP でメンテナンスされなくなった文書のリスト
<p>
    <tt>JF/lists/obsoleted.LDP</tt> は LDP でメンテナンス
    されなくなった文書のリストです。
    ここには、すでにメンテナンスされていない文書の $(BASENAME) が記述されます。
<p>
    このファイルに記述した情報は、JF-in-Progress などの作業状況
    進行リストに反映されます。


<!-- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -->
<sect>カーネル文書の管理<label id="Kernel-Docs">
<p>
Linux カーネルの配布アーカイヴには、<tt>Documentation/</tt>
ディレクトリ以下に大量の文書が含まれています。これらはカーネルを
ハックする人たちのみならず、カーネルを利用するだけの人たちに
とっても有益な情報を含んでいます。
<p>
カーネル文書は他の文書に比べて以下のような特徴をもっています。

<itemize>
<item>Copyright がはっきりしている (GPL2)
<item>プレインテキストで供給されているものが多い
<item>数が多い(^^;
<item>日付よりもどのバージョンのカーネルに含まれていたものかが重要
</itemize>

<p>
したがって現時点では、カーネル文書は CVS リポジトリの
<tt>docs/kernel-docs-2.2</tt> と <tt>docs/kernel-docs-2.4</tt>
以下にまとめ、他とは異なった管理方法を取っています。
本章では、それらについてまとめます。

<sect1>文書の追加・更新の手順
<p>
カーネル文書を追加する際には、以下のようにしてください。
<enum>
<item>文書が完成したら、
カーネル 2.2 の翻訳なら <tt>docs/kernel-docs-2.2</tt>,
カーネル 2.4 の翻訳なら <tt>docs/kernel-docs-2.4</tt> 以下に追加する。
基本的にオリジナルと同じファイル名にしてください。文字コードは日本語
EUC にしてください。
<item>info ファイルを準備する。ファイル名は (文書名).info と
してください。例えば <tt/md.txt/ 用の info ファイルなら
<tt/md.txt.info/ という名前にします。
カーネル文書用 info ファイルのフォーマットは
JF Web Page の中の
<htmlurl 
url="http://www.linux.or.jp/JF/workshop/guidance-infofile.html#kdoc-info-format" 
name="JF Workshop Guidance: 文書情報管理ファイル(info)について">
を参照してください。
<item>以上を commit する。その後必要に応じて <tt>www/news.m4</tt> に
アナウンス用のエントリを追加しておきましょう。
<tt>www/news.m4</tt> については
<ref id="news_m4" name="news.m4 への登録">
に関する説明を参照してください。
</enum>

<p>
更新も基本的に上記の各ファイルを更新・ commit すれば OK のはずです。

<sect1>翻訳作業の予約リスト<label id="kdoc-reserve">
<p>

<p>
翻訳作業の予約は,
カーネル 2.2 なら <tt>JF/lists/kdoc-reserved.list</tt>,
カーネル 2.4 なら <tt>JF/lists/kdoc-2.4-reserved.list</tt> に
記述します。書式やエントリの意味などは <tt>JF/lists/reserved.list</tt>
と全く同じですので, <ref id="reserve" name="LDP 文書の予約リストの説明">
を見てください。ただし <tt/STAT:/ ディレクティブのエントリとしては
<tt/Reserved/ と <tt/Draft/ のみが有効です。
<p>
上記のリストは, www/workshop/KDoc-in-Progress.m4,
www/workshop/KDoc-2.4-in-Progress.m4 から呼ばれる
<tt>JF/www/bin/kdoc-in-progress.pl</tt> によって利用されます。
このスクリプトが用いるファイルには、他に
JF/lists/kdoc-version.list, JF/lists/kdoc-2.4-version.list があります。
これは各文書が最後に更新されたカーネルのバージョンを保持するものです。
カーネルが更新され、差分パッチ (patch-2.[24].?.bz2) が配布されたら、
それに対して <tt>JF/bin/upd-kdoc-list.pl</tt> を用いれば、
最新の状態に追随することができます。
<p>

<sect1>カーネル文書の import<label id="kdoc-import">
<p>
   JF のリポジトリには ORIGINAL というモジュールがあり、
   現在はここにはカーネル文書の原文が納められています。
   import するにはカーネルアーカイブを取得してほどき、
   ディレクトリ Documentation に移動します。
   その後以下のコマンドラインを実行します (2.4.20 の場合)。

<tscreen><verb>
 % setenv CVSROOT :pserver:yourname@cvs.linux.or.jp:/JF
    or
 $ export CVSROOT=:pserver:yourname@cvs.linux.or.jp:/JF
 % cvs import -m 'import of 2.4.20' ORIGINAL/kernel-docs/Documentation-2.4 KDOC KDOC-2_4_20
</verb></tscreen>

<!-- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -->
<sect>Configure.help の管理
<p>
カーネル文書のなかでも Conigure.help (以下、CH) だけは
ちょっとシステムが異なります。
翻訳に関する作業手順は、

<url url="http://www.linux.or.jp/JF/workshop/guidance-procedure.html#CH-trans">

に公開されていますので、まずそちらをお読みになってください。

以下、committer に関係する登録作業手順だけを記します。

<enum>
<item>JF-ML に翻訳の予約が投稿されてきます。
 Subject は次の通り (例: CONFIG_SMP の 2.2.10 の場合)
 <tscreen><verb>
[CH:RESERVE] CONFIG_SMP 2.2.10
 </verb></tscreen>
 予約があったら、<tt>JF/docs/Configure.help/Reserved.list</tt>に記入します。
<item>JF-ML に翻訳文が投稿されてきます。
 ドラフトの場合の Subject は次の通り (例: CONFIG_SMP の 2.2.10 の場合)
 <tscreen><verb>
[CH:DRAFT] CONFIG_SMP 2.2.10
 </verb></tscreen>
 これはまだリポジトリには入れません。リポジトリに入れるのは、
 次のような Subject があった場合です。
 <tscreen><verb>
[CH:FINAL] CONFIG_SMP 2.2.10
 </verb></tscreen>
 これは最終原稿ですので、リポジトリに格納します。
 <item>リポジトリ格納の際に注意すべき点としては:
 <itemize>
  <item> 原文をすべて削る。
  <item> 翻訳文の行頭には 1Byte Space がふたつ入るように必要であれば整形する
  <item> 行の長さが 60カラムを越えないように必要であれば整形する
  <item> 最後の行に
 <tscreen><verb>
<名前>
 </verb></tscreen>
  のような形式で翻訳者氏名が付いていることを確認する。なければ付ける
  <item>文字コードが日本語 EUC (UNIX 改行) になっていることを確認する.
  <item>格納すべきディレクトリは項目によってまちまちである。
	翻訳者が version を明記していない場合は、
	<htmlurl url="http://www.linux.or.jp/JF/JFdocs/Configure.help/Configure-Status-text.html" name="CH 翻訳作業進行状況">
	で "<tt>N"</tt> または "<tt>*</tt>" のマークのある
	バージョンと仮定して類推するしかない。必要であれば翻訳者に確認する。
	バージョンが判明したら

         docs/Configure.help/TRANS-Configure.help-$(VERSION)/CONFIG_$(ITEM)

        のように格納する

  <item>同じディレクトリに translators というファイルがある。ここに、
        翻訳者名が記録されていなければ付加する
 </itemize>
</enum>

<sect1>新カーネルが公開された際の Configure.help 作業の準備
<p>
(2001/06/06 現在では) 2.2 系に限っての翻訳下準備作業をまとめました。

<enum>
 <item><url url="http://cvs.linux.or.jp/cgi-bin/cvsweb/ORIGINAL/kernel-docs/Documentation/?cvsroot=JF">
に 最新バージョンの Configure.help 原文がありますので wget などで手元にもらってきます。ここでは  2.2.18 バージョンのものを ~/tmp に置いたとしましょう。

 <item>
<tscreen><verb>
cp ~/tmp/Configure.help JFのCVSリポジトリ/docs/Configure.help/Configure.help-2.2.18
</verb></tscreen>
    して、Configure.help を手元リポジトリにコピー。
    ここで、「Configure.help-2.2.18」のことを今回のCHと呼ぶことにする

<item> JFのCVSリポジトリ/docs/Configure.help/Makefile を変更する。具体的
    には、以下の変更となる。
    <itemize>
     <item>CONFIGURE_NEW の末尾に今回のCHのファイル名を追記。
    </itemize>

<item> cd JFのCVSリポジトリdocs/Configure.help/ する。
    ORIG-Configure.help.diffs ディレクトリに今回のCHとその直前のCHとの
    差異を示したファイルを追加する。
    具体的には、
<tscreen><verb>
    $ diff -U0 Configure.help-2.2.17 Configure.help-2.2.18 \
      > ORIG-Configure.help.diffs/2.2.17-2.2.18.diff
</verb></tscreen>
   と実行する。
   diff の option は -U0 とし、差異のある部分だけを出力することに注意。 

<item>
<tscreen><verb>
echo "patch -o Configure.help-2.2.18 < ORIG-Configure.help.diffs/2.2.17-2.2.18.diff" \
    >> ORIG-Configure.help.diffs/mkall.sh
</verb></tscreen>
    する。

<item>
    さきほど変更した Makefile がある。データベース
    (Mod_Configure.help-2.2.18.db)と予約リスト(Reserved.list)を今回の
    バージョンに対応させるために、
<tscreen><verb>
    $ make db ; make reserve
</verb></tscreen>
    を実行。

<item>mkdir ./TRANS-Configure.help-2.2.18 する。このディレクトリには翻訳
    されたファイルが入ることになる。
<tscreen><verb>
    cp ./TRANS-Configure.help-2.2.17/translators ./TRANS-Configure.help-2.2.18/
</verb></tscreen>
    して、以前の翻訳者の氏名をコピーする。

    header.txt も追加することになるが、今回のCHの冒頭と直前のCHの冒頭
    が変化していないことをまず調べなくてはならない。
<tscreen><verb>
    $ diff -u ../Configure.help-2.2.17 ../Configure.help-2.2.18 | less
</verb></tscreen>
    して、違いのないことを確認する(違いがあれば header.txt も追従する)。
<tscreen><verb>
    cp ../TRANS-Configure.help-2.2.17/header.txt  .
</verb></tscreen>
    する。

<item> cd .. する。今度は index.m4 を今回のCH用に修正する。80行目付近の作
    業状況、「(カーネルバージョン) の翻訳を作業中です.」
    のカーネルバージョン部分を変更する。

<item> Reserved.list の「# Based on: Configure.help-2.2.17」の行を、今回
    のCHに合わせるため、「# Based on: Configure.help-2.2.18」に変更する。

<item> さて、JFのCVSリポジトリにディレクトリやファイルを add, commit する。
<newline>
     $ cvs add docs/Configure.help/TRANS-Configure.help-2.2.18/ <newline>
     $ cvs add docs/Configure.help/TRANS-Configure.help-2.2.18/header.txt \ <newline>
               docs/Configure.help/TRANS-Configure.help-2.2.18/translators \ <newline>
               docs/Configure.help/ORIG-Configure.help.diffs/2.2.17-2.2.18.diff
     $ cvs commit docs/Configure.help/TRANS-Configure.help-2.2.18/header.txt \ <newline>
                  docs/Configure.help/TRANS-Configure.help-2.2.18/translators \ <newline>
                  docs/Configure.help/Configure.help-2.2.18 \ <newline>
                  docs/Configure.help/index.m4 \ <newline>
                  docs/Configure.help/Makefile \ <newline>
                  docs/Configure.help/ORIG-Configure.help.diffs/mkall.sh \ <newline>
                  docs/Configure.help/ORIG-Configure.help.diffs/2.2.17-2.2.18.diff \ <newline>
                  docs/Configure.help/Reserved.list \ <newline>
                  docs/Configure.help/ChangeLog
</enum>

<p>
   docs/Configure.help/ChangeLog は周辺の記述を参考にして記述すること
   になる。注意として、今回のCH は cvs add しないことが挙げられる(
   ORIG-Configure.help.diffs/ 以下の diff をもとに JF のリポジトリマシ
   ンで make Makefile されて自動生成されるからである)。



<!-- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -->
<sect>Web コンテンツの管理
<p>
    この章では、リポジトリに格納されている JF Project の Web ページを
    更新する際の注意事項などをとりあげます。

<sect1>HTML ファイルの編集
<p>
    Web ページの土台はリポジトリの <tt>JF/www</tt> 以下に入っています。
    リポジトリに HTML フォーマットで格納されているファイルは、
    あまり更新頻度の高くない、比較的スタティックなページです。
    これらのファイルは直接編集して構いません。
    ただし、文字コードを UTF-8 で保存することを忘れないでください 
    JF のリポジトリに入っているファイルの中で、
    文字コードが UTF-8 なのは HTML 文書だけです。
    これ以外はすべて日本語 EUC で記述します。
    この後に述べる M4 ファイルも 日本語 EUC です。
<sect1>M4 ファイルの編集
<p>
    新たにページを追加する場合は、できれば GNU m4 のソース形式で
    記述することをおすすめします。この方式を採るメリットは:
    <itemize>
     <item>ヘッダやフッタなど JF の基本形式のマクロがあらかじめ
     用意されているので、それを利用するだけで形式を合わせることができる。
     単語などもマクロ化して使えるので、用語の統一、変更が楽になる。
     <item>Build 時に外部コマンドを起動して、
     その出力をファイル中に埋め込むことができる
     (http サーバ上で実行される SSI とは意味も方法もまったく違います)。
     <item>共通ライブラリを更新することで、
     関係するページすべてに反映させることができる。
    </itemize>
    などです。
<p>
    リポジトリ中にある、<tt>.m4</tt> の拡張子のついているファイルが、
    GNU m4 を通して処理するためのソースファイルです。
    <tt>jf_www.m4</tt> だけは特別で、原則としてすべての m4 のソースの
    冒頭付近で include することになる、基本ライブラリと考えてください。
<p>
    例として「JF Project 奇人伝」というページを新たに追加する場合ですが:
    <enum>
    <item>以下のようなファイル <tt>foo.m4</tt> を作成します。
    (文字コードは日本語 EUC)
    <code>
    m4_include(jf_www.m4)
    _HEADER(JF Project 奇人伝)
    _MIRROR_LIST
    &lt;P&gt;酔うと変な行動をするのなら普通ですが...(略)&lt;/P&gt;
    _BACK_TO_HOME
    _CREDITS
    &lt;/BODY&gt;
    &lt;/HTML&gt;
    </code>
    <item><tt>m4 -P foo.m4</tt> の出力を確認してください。
    他の JF のページと同等のヘッダ、
    TOP ページへのリンク、Mirror Site へのリンク、連絡先アドレスフッタなどが
    きちんと埋め込まれているはずです。
    <item>内容が全部 OK なら、<tt>Makefile</tt> に <tt>foo.m4</tt> の
    処理を追加します。
    <item><tt>foo.m4</tt> と <tt>Makefile</tt> を
    リポジトリに add & commit します。
    </enum>
    これで新しいページのソースの出来上がりです。
<p>
    なお、GNU m4 のソースから生成される HTML ファイルは、
    直接編集しても意味がありませんので注意が必要です。
    また、m4 から生成された HTML ファイルは、リポジトリに格納する必要は
    ありません。
<p>
    TOP ディレクトリよりも深いディレクトリに置かれるファイルを
    作成するときは、別の呪文が必要になります。これをふくめて、
    その他細かいことについては、すでにある実際のファイルを眺めて
    参考にしてください。特に、<tt>jf_www.m4</tt> には
    あらかじめ定義されたマクロが書かれています。
    便利に使えばページの記述や更新が楽に行えます。
    GNU m4 と M4 マクロの詳細については m4(1) や GNU m4 の texinfo ファイルを
    参照してください。

<sect1>画像ファイルを追加する
<p>
    アイコンなどに使用する画像ファイルは、
    原則としてリポジトリの <tt>JF/www/images</tt> ディレクトリに
    格納してください。
    また、add する際に <tt>-kb</tt> オプションをつけて、
    バイナリファイルであることを明示するのを忘れないでください。
    これをしないと、ファイルの中身がおかしくなります。

<!-- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -->
<sect>CVS を利用した執筆作業<label id="sec-cvs">
<sect1>概略
<p>
    せっかく JF の CVS リポジトリが用意されているのですから、
    文書の執筆や翻訳などにも活用できたら、と思いませんか?
<p>
    すでに 
    &lsqb;<ref id="intro2" name="→ 予備知識(2) …… CVS で管理するメリット">
    &rsqb;
    で説明した通り、CVS を上手に使うと複数のメンバーが作業を同時に
    並行してできるようになります。
    たとえば、翻訳文書の章毎に担当を決めて分業するような場合でも、
    他の人の作業を参照しながら作業できるので、
    用語や文体の統一が容易になるというメリットがあります。
<p>
    あるいは、翻訳者と校正者が同時に作業を行うことも可能になります。
    翻訳者が書いた原稿はメイントランク (幹) に格納し、
    校正者は枝と呼ばれるブランチを作成して、そのブランチの原稿に
    直接修正を入れていきます。
    校正が入った部分は cvs の diff コマンドで簡単に確認できますし、
    その間にさらに翻訳が進んでも、
    後で校正された内容をメイントランクにマージすることができます。
<p>
    単独で作業を行う場合は、もっと自由です。
    ドラフトに対して ML で寄せられたコメントをブランチの原稿に格納して、
    それを横目で見ながらメイントランクの原稿に手を入れていく、
    という使い方もできるでしょう。
    正式リリースの直前まで、原稿の中に執筆メモを残しておいて、
    最後に削除するということも可能です。
    そのメモは履歴の中には残っていますから、
    あとで必要になったときにもすぐに参照できます。
    あるいはもっとリアリスティックに考えれば、
    作業途中の履歴つきバックアップを JF リポジトリに保存してもらうのだ、
    という考え方さえできるのです。これだけでも充分意味があるでしょう?
<p>
    CVS のメリットを生かした作業を行うには、CVS に関する知識が不可欠です。
    しかし、その労力をかけてもおつりが来るほどの成果を
    もたらしてくれるはずです。
    本文書では CVS の操作方法に関してはすべて省略しますが、
    CVS の texinfo ファイルの日本語訳が
    <htmlurl url="http://www-vox.dj.kit.ac.jp/nishi/cvs/cvs.html" 
    name="http://www-vox.dj.kit.ac.jp/nishi/cvs/cvs.html">
    で公開されていますので、ぜひ参考にしてください。
    JF での具体的な作業にかかわる情報は、
    <htmlurl url="JF-committers.html"
    name="JF committers mini-HOWTO"> もごらんください。

<sect1>CVS の上で執筆作業をはじめるには(1)<label id="starting-work">
<p>
    基本的には &lsqb;<ref id="add-doc" name="→新しい文書の追加">&rsqb; で
    述べた手順にしたがって、
    文書の格納されるディレクトリを CVS リポジトリ上に用意します。

<p>
    <label id="makefile-for-draft">
    <tt>Makefile</tt> は作業が終わるまでは、
    install ターゲットを空にしておいてください。作業に必要な項目のみを
    用意して、<tt>JF.conf</tt> や <tt>JF.rules</tt> も include しないままにしておきましょう。
<p>
<tscreen><verb>
 # Makefile for OUR-HOWTO.sgml
 #
 BASENAME   = OUR-HOWTO
 SGML2HTML  = sgml2html -c nippon -l ja
 SGML2TEXT  = sgml2txt  -c nippon -f -l ja
 .SUFFIXES: .sgml .html
 .SUFFIXES: .sgml .txt
 .sgml.html:
            $(SGML2HTML) $&lt;
 .sgml.txt:
            $(SGML2TEXT) $&lt;
 default: $(BASENAME).txt $(BASENAME).html
 install:
 clean:
	rm -f $(BASENAME).txt $(BASENAME)*.html
</verb></tscreen>
<p>
    この他、作業ディレクトリに <tt>ChangeLog</tt> という
    変更履歴ファイルを用意して、
    更新の過程を記録することをおすすめします。
    執筆作業が続いている間は、JF リポジトリの TOP に
    ある <tt>ChangeLog</tt> ファイルには細かい報告を書く必要はありません。
    逆に個々の報告が TOP の <tt>ChangeLog</tt> に書かれると
    煩わしいことも考えられます。
<p>
    注意が必要なのは info ファイルです。
    <em>文書が正式にリリースされるまで info ファイルは作成しないでください</em>
    (info ファイルの作成は文書リリースの宣言だと思ってください)。

<p>
    どうしても info ファイルを置きたい場合は、
    info の最初の行に ``<tt>DRAFT-NOINDEX</tt>''という行を挿入します。
    これによって INDEXING の対象から強制的に外すことができます。
    これは、未公開文書の info を作成する際には <em>必須</em> です。
    また、Makefile は必ず上記で述べたように DRAFT 用のものになっている必要が
    あります。

<p>
    以上であげたファイル以外はリポジトリの文書ディレクトリに入れてはいけない、
    という決まりはありません。
    作業に必要であれば、リポジトリに格納しても構いません。
    ただし、拡張子が <tt>.html</tt> のファイルは、
    作業が終わって公開を始める前に、事前に削除する必要があります
    (現在の Build プロセスの仕様です)。
    これは混乱を招く要因になりかねませんので、
    始めからこの拡張子をもったファイルを
    文書ディレクトリに入れないことをお勧めします。
<p>
    なお、CVS を利用した執筆作業全般に言えることですが、
    作業を始める際に JF のリポジトリすべてを checkout する必要はありません。
    また、作業過程で CVS タグをつける場合も、
    文書ディレクトリのファイルに対してだけ行うようにしましょう。

<sect1>CVS の上で執筆作業をはじめるには(2)<label id="import">
<sect2>ベンダーブランチを使う
<p>
    &lsqb;<ref id="starting-work"
    name="CVS の上で執筆作業をはじめるには(1)">&rsqb; で解説した内容は、
    リポジトリの上で文書ファイルを管理する際の基本事項です。
    この章では応用編として、執筆作業を始める際に、
    あえてちょっと複雑なリビジョン管理方法をとるケースについて説明します。
    CVS の操作方法に不馴れな方は、この章は読み飛ばしてしまってかまいません。
    (なお、ここで取り扱う方法に関するより詳細な情報は、
    CVS 附属の texinfo ファイル中の ``Tracking sources'' の項目を
    参照してください。)
<p>
    ここで述べる方法は、主に翻訳文書の作成・更新に向いています。
    通常翻訳文書の作成は、原文を SGML コメントとして残しながら、
    本文に翻訳文を挿入していきます。
    見方を変えれば、原文にローカルな変更を加えているようなものです。

<p>
    この点に注目すると、まず最初のリビジョンとして原文自体が存在していると
    見ることができます。
    この原文をリポジトリの出発点にしようと考えるのは、
    決して不自然な思い付きではありません。

<p>
    ただし、単に最初に原文を commit するだけなら、
    あまりうれしくありません。面倒な手間がひとつ増えるだけで、
    ほとんどなんの得もありません。

<p>
    ところで、CVS には ``ベンダーブランチ'' という
    特別なブランチの概念があります。
    主たる目的は、
    別の開発元(ベンダー)によって作業が進行しているファイルを
    自分たちのリポジトリに輸入しつつ、ローカルな変更を施すためのものです。
    ローカルな変更がメイントランク(幹)で行われている間に、
    開発元のファイルが更新されたとしても、
    重ねて輸入 (import) することによって、
    その間の変更を幹に反映させることができるような仕組みが用意されています。
    
<sect2>Import and Track 方式<label id="import_and_track">
<p>
    これを利用して、翻訳文書を作成する際には
    まず最初に原文をそのまま ``ベンダーブランチ'' に入れてしまう、
    という手段が採れます。
    この方式を <em>``Import and Track 方式''</em> と呼ぶことにします。
    これによるメリットは:
    <enum>
    <item>原文の更新個所を cvs diff で簡単にとれるようになる.
    <item>原文が更新されたとき、翻訳文に SGML コメントとして残している
          原文部分も自動更新できる.
    </enum>
    という点です。
<p>
    ``Import and Track 方式'' では、翻訳が途中でも、あるいは終了していても、
    原文が更新された際には、常にベンダーブランチに入れます。
    この作業は CVS では import というコマンドになっており、
    通常の add &amp; commit とは区別されています。
    そして、このベンダーブランチに納められたファイルには、
    <em>決して手を入れない</em>ようにします。
<p>
    では、具体的に作業の手順を追ってみましょう。
    まず最初に用意するのは、
    原文のファイルです。どこかに適当な空のディレクトリを作成して、
    このファイルを import します。

 <tscreen><verb>
 % mkdir FOO-HOWTO; cd FOO-HOWTO
 % cp FOO-HOWTO-Original.sgml FOO-HOWTO.sgml
 % ls -a
 FOO-HOWTO.sgml
 % cvs import -m "Import of FOO-HOWTO original v1.1" \
       JF/docs/FOO-HOWTO LDP_DIST FOO-HOWTO-1_1
 </verb></tscreen>
<p>
    これで最初の import が完了しました。
    LDP_DIST ベンダーブランチが作成されていますが、
    それ以前には何もなかったので、
    メイントランクの HEAD リビジョンでもあります。これを取り出すには、
    単に checkout するだけです。

 <tscreen><verb>
 % cvs checkout JF/docs/FOO-HOWTO
 </verb></tscreen>

    翻訳作業はこの HEAD ブランチに対して直接行います。
    ここで作業ブランチを起こす方法もありますが、一番最初のケースでは
    その必要はないでしょう。
    翻訳作業は適当にきりのいいところでリポジトリに commit します。
    この時点でのリポジトリの様子をツリーにしてみると:
 <tscreen><verb>
     Main Trunck                          Vendor Branch (LDP_DIST)
         1.1   ------------------------------ 1.1.1 (FOO-HOWTO-1_1)
          |
         1.2
          |
         1.3
          |
      1.4 (HEAD)
 </verb></tscreen><!-- fig -->

    となっています。


<sect2>原文が更新されたら
<p>
    ある程度翻訳が進んだところで、また原文が更新されました。
    これもすぐにベンダーブランチに入れてしまいます。
    やり方は、最初の import の時とまったく一緒です。
    違うのは <tt>-m</tt> で付加する commit メッセージと、
    リビジョンタグの番号くらいでしょう。

 <tscreen><verb>
 % mkdir /tmp/FOO-HOWTO; cd /tmp/FOO-HOWTO
 % cp FOO-HOWTO-Original.sgml FOO-HOWTO.sgml
 % ls -a
 FOO-HOWTO.sgml
 % cvs import -m "Import of FOO-HOWTO original v1.2" \
       JF/docs/FOO-HOWTO LDP_DIST FOO-HOWTO-1_2
 </verb></tscreen>
    ここで import コマンドで輸入されたリビジョンは、メインブランチではなく、
    ベンダーブランチにスタックされます。
 <tscreen><verb>
     Main Trunck                          Vendor Branch (LDP_DIST)
         1.1   ------------------------------ 1.1.1 (FOO-HOWTO-1_1)
          |                                     |
         1.2                                  1.1.2 (FOO-HOWTO-1_2)
          |
         1.3
          |
      1.4 (HEAD)
 </verb></tscreen>
<p>
    この時点では、翻訳文が入っているメイントランクには
    原文の変更が反映されていません。CVS もその旨を警告してくれると思います。
<p>
    もし、この時翻訳を進めているワークコピーが手元にないならば、
 <tscreen><verb>
 % cvs checkout -j FOO-HOWTO-1_1 -j FOO-HOWTO-1_2 JF/docs/FOO-HOWTO
 </verb></tscreen>
    とすると、
    リビジョン FOO-HOWTO-1_1 と リビジョン FOO-HOWTO-1_2 の間の変更個所を
    翻訳作業の入ったメイントランクの内容にマージして、その結果のワークコピーを
    取り出してくれます。
<p>
    すでに翻訳作業を行っているワークコピーが手元にある場合は、
    その作業ディレクトリで
 <tscreen><verb>
 % cvs update -j FOO-HOWTO-1_1 -j FOO-HOWTO-1_2 .
 </verb></tscreen>
    とすることで、同じ結果を得られます。

<sect2>衝突(conflict)の解決
<p>
    どちらの場合もマージは自動的に行われますが、完全にマージし切れない個所が
    残ってしまうこともあります。
    これは変更個所が衝突 (conflict) しているからです。
    CVS は変更個所の衝突を検出すると、
    その部分には人間の目に分かりやすいマーキングを残します。
<tscreen><verb>
&lt;&lt;&lt;&lt;&lt;&lt;&lt;  FOO-HOWTO.sgml
Java holds promise as a portable language.
=======
Java does not hold promise as a portable language.
&gt;&gt;&gt;&gt;&gt;&gt;&gt;  FOO-HOWTO.sgml
</verb></tscreen>
    これらの衝突は人間の手で解決する必要があります。
    多くの場合、衝突個所を修正するのはそれほど難しくありません。
<p>
    無事にマージが完了した時点でのツリーを図にしてみます。
 <tscreen><verb>
     Main Trunck                          Vendor Branch (LDP_DIST)
         1.1   ------------------------------ 1.1.1 (FOO-HOWTO-1_1)
          |                                     |
         1.2       +------------------------- 1.1.2 (FOO-HOWTO-1_2)
          |        |
         1.3       |
          |        |
      1.4 (HEAD) &lt;-+ merge
 </verb></tscreen><!-- fig -->

<sect2>原文の更新内容を翻訳に反映させる
<p>
    衝突が解決できたら、原文のどの部分が更新されたのが、
    diff をとって確認してみましょう。
<tscreen><verb>
 % cvs diff -u -r FOO-HOWTO-1_1 -r FOO-HOWTO-1_2 FOO-HOWTO.sgml | less
</verb></tscreen>
    これを横目に見ながら、翻訳文にも更新内容を反映させればいいわけです。
 <tscreen><verb>
     Main Trunck                          Vendor Branch (LDP_DIST)
         1.1   ------------------------------ 1.1.1 (FOO-HOWTO-1_1)
          |                                     |
         1.2       +------------------------- 1.1.2 (FOO-HOWTO-1_2)
          |        |
         1.3       |
          |        |
         1.4  &lt;----+ merge
          |
      1.5 (HEAD) &lt;---- 更新作業終了後 commit したリビジョン
 </verb></tscreen><!-- fig -->

<p>
    後は原文の更新にあわせて作業を繰り返すだけです。
<enum>
<item>(作業ブランチを作成する : 任意)
<item>ベンダーブランチに原文を import する
<item>原文の変更内容をマージする
<item>翻訳の更新を行う
<item>(メイントランクへ作業ブランチでの更新内容をマージする : 任意)
<item>公開
</enum>
<p>
    この流れの全体図を以下に示します。
 <tscreen><verb>
     Main Trunck                          Vendor Branch (LDP_DIST)
         1.1   ------------------------------ 1.1.1 (FOO-HOWTO-1_1)
          |                                     |
         1.2       +------------------------- 1.1.2 (FOO-HOWTO-1_2)
          |        |                            |
         1.3       |                            |
          |        |                            |
         1.4  &lt;----+ merge                      |
          |                                     |
         1.5                                    |
          |   &lt;-- merge --------------------- 1.1.3 (FOO-HOWTO-1_3)
         1.6                                    |
          |   &lt;-- merge --------------------- 1.1.4 (FOO-HOWTO-1_4)
         1.7                                    |
          |   &lt;-- merge --------------------- 1.1.5 (FOO-HOWTO-1_5)
          |
      1.8 (HEAD: FOO-HOWTO v1.5 の翻訳)
 </verb></tscreen><!-- fig -->


<sect1>作業が終わったら
<sect2>info ファイルの用意
<p>
    まだ用意していなかった  info ファイルを準備します。
    フォーマットは JF Web Page の中の 
    <htmlurl url="http://www.linux.or.jp/JF/workshop/guidance-infofile.html#kdoc-info-format" name="JF Workshop Guidance: 文書情報管理ファイル(info)について">
    を参照してください。

<sect2>Makefile の用意
<p>
    <tt>Makefile</tt> も全体の Build の形式にあったものを用意します。
    この二つのファイルを commit すると、
    文書は自動的に公開されることになります。

<sect2><tt>news.m4</tt> への登録<label id="news_m4">
<p>
    <tt>JF/www/news.m4</tt> は、
    文書の新規追加・更新をお知らせする JF Web ページの
    ための M4 ソースファイルです。
    ファイルの冒頭にコメントで書かれているように、
    簡単なルールで新規文書・更新文書が記述できますので、
    ぜひこのファイルも更新して commit してください。
<p>
    新規文書の場合は マクロ <tt>_NEW_DOC</tt> を使います。
    更新文書の場合は マクロ <tt>_UPD_DOC</tt> を使います。
    どちらも引数の数、内容は同じです。引数はカンマ (<tt>,</tt>) で区切ります。
    引数をクオートする必要があるときは <tt>`</tt> と <tt>'</tt> でくくります。

    <enum>
      <item>参照先文書名 (JFdocs/ ディレクトリからの相対パスで記述)
      <item>更新日時 (YYYY/MM/DD)
      <item>文書のタイトル
    </enum>
<p>
    以下に記述例を示します。

    <verb>
  _NEW_DOC(Coffee.html,1999/12/05,
           Coffee HOWTO の日本語訳)

  _UPD_DOC(kernel-docs-2.2/networking/soundmodem.txt.html,1999/08/12,
           `kernel-2.2.11 附属の soundmodem.txt の日本語訳')
    </verb>

<sect2>予約ファイルの変更
<p>
    翻訳作業で
    <tt>JF/lists/reserved.list</tt>
    に予約を書いていた場合は、自分のエントリをコメントアウトします。
    <ref id="reserve" name="[ →reserved.list ]"> 
<p>
    これで正式公開の手続きはすべて終わりました。
    JF-ML で報告するとともに、
    関係する Newsgroup や Mailing List でアナウンスしましょう。

<sect1>リリース後の文書更新
<p>
    &lsqb;<ref id="intro1" 
    name="予備知識(1) …… コンテンツ生成の実際">&rsqb;
    で触れたように、JF コンテンツの Build は毎日行われており、
    メイントランクの内容は常にリリースされたものである、と見なされます。
<p>
    したがって、正式リリース後はリリースタグを打つと同時にブランチを起こして、
    文書に対する細かな修正はブランチに施すことをお勧めします。
    そして、ある程度キリがついたところで所で
    メイントランクにマージして再リリース、という方法を取りましょう。
    さもなくば、更新過程の (あまり見られたくない) 姿の文書が
    一時的にせよ公開されてしまうことになります。

<!-- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -->
<sect>特殊な生成ルールを利用したい場合には
<sect1>ソースが html/txt の文書を登録したい
<P>
 <ref id="document-structure" name="[→各文書の構成]">
 に述べたように、
 LinuxDoc 形式の sgml が一次ソースとなっている文書では、
 Makefile に

    <quote><tt>
    include = ../../JF.rules
    </tt></quote>

 を記述します。
 html が一次ソースの文書の場合は、この部分に
 <tt/Exception_2.rules/ を、
 txt が一次ソースの文書なら
 <tt/Exception_4.rules/ をそれぞれ指定すれば OK です。

<sect1>html をひとつにまとめたい
<p>
    それほど長くない文書では、セクションごとに別ファイルを作ってしまう
    stml2html の仕様がうっとうしくなるかもしれません。その場合には加藤さん
    が作成された sgml2onehtml、または佐野さんの sgml21html を試してみま
    しょう。それぞれ

    <quote><tt>
    <htmlurl
    url="http://www.linux.or.jp/JF/workshop/guidance-sgml.html"
    name="http://www.linux.or.jp/JF/workshop/guidance-sgml.html">
    </tt></quote>

    から入手できます。これらのルールを用いるようにするには、
    <tt>Makefile</tt> の <tt>SGML2HTML</tt> マクロを

    <quote><tt>
    SGML2HTML = sgml2onehtml
    </tt></quote>

    もしくは

    <quote><tt>
    SGML2HTML = sgml21html 
    </tt></quote>

     のように指定しましょう。これらを汎用の <tt>Makefile</tt> にある

    <quote><tt>
    include = ../../JF.rules
    </tt></quote>

     の「後に」書けば、 html はひとつだけで生成されるはずです。
     いずれのコマンドもビルドを行うホストには入っています。

<sect1>dvi などのバイナリファイルを追加したい
<p>
     (考え中です(^^; なかの)

</P>
<sect1>HTML 文書中にインライン画像を挿入したい
<P>
   Linuxdoc SGML ではインライン画像のタグはサポートされていません。
   したがって、正規の方法ではインライン画像を挿入することはできません。
<P>
   しかし、文書の性格によってはどうしても画像を挿入したい場合もあるでしょう。
   以下に示す方法によって HTML 文書中に画像を挿入することができます。
<enum>
<item>SGML 文書中の画像を挿入したい部分を以下のように label タグで
      くくります。
    <verb>
      &lt;label id="START-FIGURE:fig1.gif"&gt;
                   :
                   :
      &lt;label id="END-FIGURE:fig1.gif"&gt;
    </verb>
     この START - END で挟まれた部分は、HTML 文書中では画像に置き換えられます。
     プレインテキスト形式の出力には、通常通りSTART - END で挟まれた部分の
     文章も出力されます。コロンの後ろは、挿入したい画像のファイル名です。
<item>Makefile の通常 <tt>../../JF.rules</tt> を include している部分を、
      <tt>../../Exception_3.rules</tt> に変更します。
<item>文書ディレクトリに、BASENAME-images というサブディレクトリを作成し、
      その中に画像ファイルを格納します。リポジトリに add する際には
      <tt>-kb</tt> とバイナリモードにするのを忘れないようにしてください。
</enum>
<P>
    <tt>dump-restore-mini-HOWTO</tt> でこの方法がとられていますので
    参考にしてください。この文書の Makefile は
    <verb>
    include ../../JF.conf

    BASENAME     = dump-restore-mini-HOWTO
    SGML2HTML    = sgml21html

    include ../../Exception_3.rules
    </verb>
    となっています。文書ディレクトリには
    <tt>dump-restore-mini-HOWTO-images</tt> という
    サブディレクトリが作成され、
    その中に fig1.gif 〜 fig7.gif が納められています。
<P>
    このディレクトリで make すると、プレインテキスト版にはアスキー文字
    による図版が、HTML 版には Inline Gif 画像が埋め込まれていることが
    確認できるでしょう。

<sect1>寄贈文書の格納について<label id="contribution">
<P>
    他のプロジェクト等から寄贈された文書を登録する場合、
    通常の JF 文書とは異なった取り扱いが必要になる場合があります。
    現時点では LILO-doc から寄贈された文書群がこれに相当します。

<P>
    基本的には、通常の JF 文書の登録作業と同じですが、
    唯一違うのは、Makefile で include されるルールセットと、
    info の KIND の項目です。
<P>
<enum>
    <item><P> まず Makefile では、
    JF.rules のかわりに contrib.rules を include します。
    <verb>
    include ../../JF.conf
    include ../../contrib.rules
    </verb>


    <item><P> 次に info ファイルですが、KIND の項目以外は
    通常のオリジナル文書と同じです。
    ただし、KIND には寄贈元の Project 名を記入します。
    これは管理の都合上、一意のキー文字として取り扱います
    (現在は ``LILO-doc'' 以外のProject keyword は機能していませんが、
    必要に応じて追加することにします)。

<P>
    例としては:

    <verb>
       TITL: Linux の起動および終了、ユーザー設定説明
       KIND: LILO-doc
       ATRB: HOWTO
       NAME: userconf
       DSRC: SGML
       JDAT: 2000/05/02
       ITEM: guide
       AUTH: たなかとしひさ <toshihisa@netfort.gr.jp>
       COPY: GPL2
       CONT: Linux の起動および終了方法とユーザー設定の方法の簡単な説明。
       KEY1: userconf
       KEY2: lilo
       STAT: OK
    </verb>

    のようになります。
</enum>
<P>
     以上の二点がほどこされた文書に関しては、
     最終的には以下のような形で処理が行われます。

   <enum>
     <ITEM><P>Web では <tt>JFdocs/contrib/&dollar;{PROJ_NAME}/</tt> の下に
          置かれます。先ほどの例では
        <verb>
         JFdocs/contrib/LILO-doc/userconf.txt
         JFdocs/contrib/LILO-doc/userconf*.html
         JFdocs/contrib/LILO-doc/userconf.sgml
        </verb>
         となります。

     <ITEM><P>Web での目録は JFdocs/contrib/index.html で管理されます。

     <ITEM><P>FTP は <tt>JF/contrib/&dollar;{PROJ_NAME}/(text|sgml|html)/</tt>
       以下に置かれます。先ほどの例では
         <verb>
         JF/contrib/LILO-doc/text/userconf.txt.gz
         JF/contrib/LILO-doc/html/userconf.tar.gz
         JF/contrib/LILO-doc/sgml/userconf.sgml.gz
         </verb>
     となります。

     <ITEM><P>JF 文書のアーカイブファイル内では、
     Web に準拠した位置で格納されます。先ほどの例では
         <verb>
         JF/JFtxt.tar.gz   -> JFdocs/contrib/LILO-doc/userconf.txt
         JF/JFhtml.tar.gz  -> JFdocs/contrib/LILO-doc/userconf*.html
         JF/JFsgml.tar.gz  -> JFdocs/contrib/LILO-doc/userconf.sgml
         </verb>
     となります。
     </enum>
<!-- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -->
<sect>F A Q
<sect1>JF の執筆作業をするには、CVS committer になる必要がありますか?
<P>
   必ずしも CVS committerになる必要はありません。
   もし翻訳作業の方をメインで行われるのであれば、
   基本的には ML ベースでのやりとりだけで OK ですし、
   リポジトリの内容の閲覧だけなら web ベースでも行うことができます。

   しかし、CVS のリポジトリにアクセスできるようになっておくと、
   いろいろと便利です。自分の執筆した文書も校正してもらいやすくなりますし、
   執筆の履歴も残せます。これはファイルのバックアップがあるようなものです。
   CVS の操作方法はやってみると意外と簡単ですから、
   ぜひ committer になることをお勧めします。

<sect1>CVS committer になって作業に協力したいのですが?
<P>
    ありがとうございます。
    アカウント登録、CVS プログラムの設定などに関しては
    <htmlurl url="JF-committers.html"
    name="JF committers mini-HOWTO"> をごらんください。

<sect1>CVS committer になったら管理作業を手伝わなければいけないのですよね?
<p>
    いいえ、そういう義務はまったくないので安心してください。
    単に自分のかかわっている文書のメンテナンスのためだけに
    committer になることは全く問題がありません。

<sect1>committer になって自分で文書を更新するなら、JF-ML にドラフトを流す必要はないのですか?
<p>
    いいえ、JF-ML にも適宜ドラフトを流しましょう。
    リポジトリの中身を見ていない JF のメンバはたくさんいます。
    JF のメンバの意見を反映させるための唯一の方法は、
    JF-ML にドラフトを投稿することです。
    この手続きは文書のクオリティを維持するために絶対に必要な過程であり、
    この段階を経ないまま公開された文書は、JF プロジェクトの文書とはいえません。
<p>
    最終的なリリース版は JF の Web ページなどで公開されますので、
    必ずしも全文を JF-ML に流す必要はありません。
    ただし、その場合でも最低限リリースの宣言は JF-ML で行うべきです。

<sect1>committer は JF のコンテンツ全てを持つ必要がありますか?
<p>
   コンテンツ全てを checkout する必要はありません。
   <quote><tt>
        cvs checkout -d dokka JF/docs/HOGE-HOWTO/
   </tt></quote>
   のようにすれば HOGE-HOWTO だけを dokka の下に checkout してくることが
   できますし、 commit すればそれはメインのツリーに
   ちゃんと反映されます。

<sect1>CVS の使い方がわかりません。
<p>
    この文書は CVS の使い方を解説するものではありません。
    基本的な CVS の操作がすでにわかっていることを前提に書かれています。
<P>
    基本的な CVS の操作に関しては
    <htmlurl url="JF-committers.html"
    name="JF committers mini-HOWTO"> をごらんください。
<P>
    もし、CVS に関するもっと詳細な情報を得たいのでしたら、
    以下に示す情報を参照してください。

    <descrip>
    <tag><htmlurl url="http://www.cvshome.org/"
	         name="CVShome.org"></tag>
         CVS 配布元による情報 &amp; ドキュメントです。

    <tag><htmlurl url="http://www-vox.dj.kit.ac.jp/nishi/cvs/cvs.html"
	         name="バージョン管理システム CVS を使う"></tag>
        "CVS-1.11 texinfo の日本語訳","入門 CVS" など、
         CVS に関する日本語の情報源としてもっとも充実しています。
  
    <tag><htmlurl url="http://www.sra.co.jp/people/katsu/cvs/"
	         name="CVS 1.8.1 の解説 OHP"></tag>
        CVS の使い方解説セミナーで実際に使われた OHP が公開されています。
        CVS の基本概念を理解する上で貴重な情報源となっています。

    <tag><htmlurl url="http://kahori.com/j-cvsbook/"
	         name="Open Source Development with CVS 日本語訳"></tag>
        Karl Fogel 氏著 ``Open Source Development with CVS'' の
        GPL 条件下公開部分、2, 4, 6, 8, 9, 10章の日本語訳です。 
    </descrip>

<sect1>CVS の操作を失敗するとなにかマズいことが起こるのでしょうか?
<p>
    まずいこととしては、<tt><htmlurl
    url="http://www.linux.or.jp/JF/"
    name="http://www.linux.or.jp/JF/">
    </tt> 以下のページに作業ミスが反映されてしまうくらいでしょうか。
    でも、翌日には気付いた人がなおしてくれるでしょうけど。
<p>
    極端なことを言えば、すべての文書を消してしまうことも出来ます。
    しかし、リポジトリの Work copy を複数の人間が持っているので、
    何重かのバックアップが存在しているとも言えます。現在の状況なら、
    先の例のような極端な事故が起きた場合でもかなりの確率で復旧可能でしょう。

<sect1>Committing の際のミス・トラブルの事例にはどんなものがありましたか?
<p>
    以下に、特におかしやすい間違いを列挙します。
  <enum>
    <item><p>もっとも多いのは文字コードのミスです。
          JF のリポジトリに入っているファイルのうち、
	  拡張子が <tt>.html</tt> のものは UTF-8 で記述します。
	  それ以外は全て日本語 EUC で記述します。
	  拡張子が <tt>.sgml</tt> のファイルを
	  まちがって Shift-JIS や ISO-2022-JP で記述すると
	  コンテンツ生成の際にエラーを引き起こしますので注意してください。
          <P>ただし、例外として Plain text file を直接公開するような
          構成になっている場合 (例: PostgreSQL-FAQ) は、その text file は
          Shift-JIS で記述します。非常に紛らわしいのですが、注意して下さい。

    <item><p>info ファイルの NAME フィールドと文書を格納したディレクトリ名、
          文書の BASENAME はすべて一致していなければなりません。
          これが食い違っていると目録(インデックス)の生成に失敗します。
	  (注記: この仕様はあまりよくないので、将来的には
	  解決しなければならないかもしれません)

    <item><p><tt>JF/www/news.m4</tt>の記載ミス。
          マクロ <tt>_UPD_DOC</tt> と <tt>_NEW_DOC</tt>は、
	  三つの引数をとります。詳しくは
	  <ref id="news_m4" name="news.m4 への登録">
	  に関する説明を参照してください。
  </enum>

<sect1>文書を commit したのに、JF の Web ページに登録されないのですが?
<p>
    CVS リポジトリの内容が JF の Web ページに反映されるのは
    一日四回です。
    commit した時刻によっては数時間のタイムラグが生じることもあります。
    このあたりの仕組みは、この文書の
    <ref id="intro1" name="予備知識(1)コンテンツ生成の実際">
    を参照してください。
<p>
    もし、数日たっても Web ページに登録されない場合は、
    この文書を見直して何か間違ったことをしていないか、
    (文書を add しただけで実際には commit していないとか)
    もう一度確認してみてください。
    もっとも、コンテンツを生成しているホストの問題という場合もあるので、
    そういうときは JF-gofer ML で問い合わせてしまった方が早いかも知れません。

<sect1>ドラフト段階の未公開文書なのに Web/FTP コンテンツに出てしまったのですけど?
<p>
    この事故は、メイントランクに格納した <tt>info</tt> と <tt/Makefile/
    がドラフト用になってなかったことが原因となって発生します。
<p>
    一度流れ出してしまったものを完全になかったことにするのは困難です。
    現在、JF のコンテンツは多数のサイトによってミラーリングされています。
    それらのミラーサイトに流れ着いてしまったものを、
    確実に消す保証のある手段はないです。
<p>
    ただし、以下の対策を施せばほとんどの場合は消えてくれます。
     <enum>
     <item><tt>info</tt> の最初の行に ``<tt>DRAFT-NOINDEX</tt>''
           という行を挿入します。
     <item><tt/Makefile/ は削除するか、
           <ref id="makefile-for-draft" name="ドラフト用のもの">
           に差し換えます。
     <item><tt>docs/obsolete/obsoleted.list</tt> に <tt>BASENAME</tt> を
           書いておきます。
     </enum>
    以上 3 つの変更点を CVS に commit します。
<p>
    あらためて正式にリリースする際には、上記の変更点を元に戻します。
    すなわち、<tt/Makefile/ を
    <ref id="makefile-for-release" name="公開用のもの"> にし、
    <tt>docs/obsolete/obsoleted.list</tt> から <tt>BASENAME</tt> を削って
    おきます。<tt>info</tt> の先頭に挿入した行も削除します。

<sect1>文書を更新して最新版にしたのですが、過去の文書はどうしたらいいですか?
<p>
    別の人が担当していた文書を引き継いで更新した場合など、
    ちょっとためらってしまうかもしれませんが、
    普通は新しい文書があれば古い文書は不要ですから、
    通常の文書と同様にバージョンを重ねる形で commit してかまいません。

<sect1>タグを付けるのはどのような時ですか?
<p>
    タグにはリリースタグとブランチタグがあります。
    メイントランクだけで直線的な流れで作業を行う場合は、
    リリースタグを付ける理由はほとんどありません。
    ただし、作業ブランチを作成するときには、
    分岐点となるメイントランクに
    目印としてリリースタグをつけるのがよいでしょう。
    この場合は必然的に枝分かれしたブランチには、
    ブランチタグも付けることになります。

<sect1>タグの名称にルールはありますか?
<p>
    特にルールはありません。
    作業にかかわる人の間で誤解の生じないようにわかりやすいものであれば、
    支障はないでしょう。
    (将来新たにルールが出来る可能性がないとはいえませんが)
<p>
    一般的にはブランチタグには、分岐点となったリリースタグの一部を含ませて、
    出所を分かりやすくすることが多いようです。
    また、リリースタグには日付を入れたり、
    対応する原文のバージョンを入れたりすることも多いようです。
<p>
    ついでにいうと、
    タグ名称は文書名より Release なのか Work なのか Dist なのか、
    等の性格を反映していることの方が、
    実作業には役立つ場合が多いような気がします。
<p>
    参考として、いくつかのタグの例をあげておきます。
<itemize>
<item> <tt>FOO-HOWTO-Release-1-1</tt> (FOO-HOWTO の リビジョン 1.1 のリリースタグ)
<item> <tt>FOO-HOWTO-Draft-1-1</tt>   (<tt>FOO-HOWTO-Release-1-1</tt> から枝分かれしたブランチタグ)
<item> <tt>FOO-HOWTO-Release-19990214</tt> (FOO-HOWTO の日付 19990214 のリリースタグ)
</itemize>
<p>
    タグが増えてくるとかえって混乱することもあります。
    リリース後、作業が落ち着いたら、不要になったタグを消去するとよいでしょう。

<sect1>ブランチを起こすのはどのような時ですか?
<p>
    意図的にブランチを起こすのは、
<itemize>
<item>現在、すでに文書が公開中である。
<item>今の作業が終わるまで何度か commit する必要があるが、
      その過程は公開したくない。
</itemize>
     という場合です。これまで一度もその文書を公開していないならば、
     ブランチを起こす必然性はあまりないでしょう。
<p>
    複数の人によって同時に作業が進行し、それぞれの履歴を保存しつつ
    最終的にマージする、という方針で執筆作業を進める場合は、
    最初から各個人の作業ブランチを用意することもあります。
    このあたりになるとケース・バイ・ケースなります。

<sect1>ベンダーブランチの名称は決まっていますか?
<p>
    import する際につけるベンダーブランチの名称は、
    LDP の翻訳文書の場合は ``LDP_DIST'' を使います。
    LDP 以外の文書の場合は、プロジェクト名、
    著者名などからわかりやすい名称を導き出して、それを利用することにします。
    以上の名称ルールはあくまで目安で、
    間違って LDP のものに特殊な名称を使ってしまったからといって
    最初からやり直す必要はありません。

<sect1>Import and Track 方式を後から採り入れることはできますか?
<p>
    多少トリッキーな方法になりますが、後から
    <ref id="import" name="Import and Track 方式">
    を採り入れることもできます。
<p>
    今現在リポジトリに入っている JF の翻訳が LDP のオリジナルに対する変更、
    という形になっているならいいのですが、
    そうでないなら LDP --> JF の対応を一旦整理してメイントランクに格納する、
    という作業が必要です。
    以下、すでにリポジトリに入っている翻訳文書のリビジョンが 1.1 になっていると
    仮定します。
<p>
    まず、ベンダーブランチに、
    現在の翻訳文書の元になっている原文を import します。
    import された文書は 1.1.1.1 というリビジョンになります。
    その後、この 1.1.1.1 の内容をメイントランクにマージします。
    ここではきっと衝突が発生します。
    衝突を解決する際に 1.1 の翻訳が 1.1.1.1 に手を加えたものに
    見えるようにすることがポイントです。
    根気よくこの衝突を解決し、
    なんとか 1.1.1.1 と 1.1 の間の対応をきれいにします。
    これが終わったら、一旦 commit します。
<tscreen><verb>
   [Ventor Branch]                    [Main]
      LDP_DIST
                                       1.1
      1.1.1.1    ------------------->   |  (checkout -j LDP_DIST)
                                       1.2
</verb></tscreen>

    結果としては 1.1 -> 1.2 では文書内容には手を加えず、
    ファイルの見た目だけに手を入れて、見掛けの対応をとったわけです。
    (文章の内容が変ってないわけですから、
    理屈のうえでは JF として公開される内容に変化はない、
    と見なすことにします。)
<p>
    その上で、作業ブランチを起こします。この結果は

<tscreen><verb>
   [Ventor Branch]    [Work]          [Main]
      LDP_DIST
                                       1.1
      1.1.1.1    ------------------->   |
                                       1.2 (HEAD)
                                      /
                      1.2.1.1     <- +
</verb></tscreen>

この作業が終わったら、改めて最新の LDP 版を import します。結果は:

<tscreen><verb>
   [Ventor Branch]    [Work]          [Main]
      LDP_DIST
                                       1.1
      1.1.1.1    ------------------->   |
         |                             1.2 (HEAD)
         |                            /
         |            1.2.1.1     -- +
      1.1.1.2
</verb></tscreen>

<p>
これで、1.1.1.2 に対して作業する準備が整いました。
あとは通常の作業と同じで、1.1.1.1 と 1.1.1.2 の間の原文の更新内容を
1.2.1.1 の作業コピーに反映させます。
当然ですが更新内容にしたがって、翻訳文にも手を入れます。
作業が終わったら、作業ブランチに commit し、
今度はメイントランクへこれをマージします。

<tscreen><verb>
   [Ventor Branch]    [Work]          [Main]
      LDP_DIST
                                       1.1
      1.1.1.1    ------------------->   |
         |                             1.2
         |                            /
         |            1.2.1.1     -- +  |
      1.1.1.2 --------->|               |
                      1.2.1.x     ----> |
                                       1.3 (HEAD)
</verb></tscreen>
<p>
    後は
<enum>
<item>作業ブランチを作成する
<item>ベンダーブランチに原文を import する
<item>作業ブランチに原文の変更内容をマージする
<item>翻訳の更新を行う
<item>メイントランクへ作業ブランチでの更新内容をマージする
<item>公開
</enum>
の繰り返しです。

<tscreen><verb>
   [Ventor Branch]    [Work]          [Main]
      LDP_DIST
                                       1.1
      1.1.1.1    ------------------->   |
         |                             1.2
         |                            /
         |            1.2.1.1     -- +  |
      1.1.1.2 --------->|               |
         |            1.2.1.x     ----> |
         |                             1.3
         |                            /
         |            1.3.1.1     -- +  |
      1.1.1.3 --------->|               |
         |            1.3.1.x     ----> |
         |                             1.4
         |                            /
         |            1.4.1.1     -- +  |
      1.1.1.4 --------->|               |
                      1.4.1.x     ----> |
                                       1.5
</verb></tscreen>

<sect1>LILO-doc の文書はどのように登録しますか?
<P>
    この文書の <ref id="contribution" name="寄贈文書の格納について">
    を参照してください。

<!-- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -->
<appendix>
<!-- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= -->
<sect>この文書について
<sect1>この文書に手を入れた人一覧
<p>
<itemize>
<item>福島於修 &lt;<tt/fuku@amorph.rim.or.jp/&gt;
<item>藤原輝嘉 &lt;<tt/fujiwara@linux.or.jp/&gt;
<item>中野武雄 &lt;<tt/nakano@apm.seikei.ac.jp/&gt;
<item>小林雅典 &lt;<tt/zap03216@nifty.ne.jp/&gt;
<item>武井伸光 &lt;<tt/takei@webmasters.gr.jp/&gt;
</itemize>
<sect1>この文書の最新版
<p>
最新版は以下から入手することができます。
<itemize>
<item><url url="http://www.linet.gr.jp/~fuku/"> JF Greenroom
</itemize>
<sect1>COPYRIGHT
<p>
    変更個所が JF の CVS リポジトリに commit されるかぎり、どなたでも
    自由に改変することができます。
<p>
    <htmlurl url="http://www.linux.or.jp/JF/" name="JF Project">
    以外への再配布に関しては JF@linux.or.jp
    までお問い合わせ下さい。
</article>
