JF: JF Workshop Guidance: 文書情報管理ファイル(info)について

• SGML 文書作成
  • LinuxDoc DTD
  • LinuxDoc-Tools のダウンロード
  • LinuxDoc-Tools のインストール
  • DocBook DTD
  • SGML 文書作成を支援するツール
  • SGML 文書作成の実際
  • 資料「日本語版 Linuxdoc-SGML ガイド」
  • SGML 参考リンク集
• JF Project における文書作成の手順
  
  • LDP 文書の翻訳手順
  • Configure.help 翻訳手順
  • JF 文書文体ガイド
• 文書情報管理ファイル(info)について [ 現在閲覧中のページです ]
  • info ファイルのフォーマット
  • カーネル付属文書の info ファイル
  • info ファイルはいつ参照されるのか?
• バージョン管理システム CVS
  
  • CVS に関する情報へのリンク

文書情報管理ファイル(info ファイル)

JF Project では 文書を JF の CVS リポジトリに格納する際に、 文書についての付帯情報を一緒に納めることになっています。 この文書情報管理ファイルは info ファイルと呼ばれています。 この info ファイルの記述によって、JF の Web/FTP の資源管理の中で、 各文書がどのように取り扱われるべきかを指定することができます。

info ファイルのフォーマット

info ファイルは各文書の管理情報を記録するファイルです。 ひとつの文書につき、必ずひとつの info ファイルを用意します。 ファイル名も info に固定です。

ファイルは UNIX 改行形式の日本語 EUC テキストファイルで記述します。 空行、空白文字のみの行は無視されます。 また、# 以降は行末まで無視されます。 なお、jf-info-check.el を使えば、記述した info ファイルが適正であるかをチェックしてくれます。 ただし、この elisp がチェックするのは フィールドの内容が下記の VALUE に含まれるかだけですので、 COPYRIGHT や著者名などは間違いのないようにしてください。

すべての情報は

KEYWORD: VALUE

という形式で記入します。以下にフォーマットの詳細を記します。

TITL: タイトル

[必須] 文書のタイトルです。 実際の文書に記されたタイトルをそのまま記します。

例) TITL: The Linux XFree86 HOWTO

KIND: VALUE

[必須] 文書の出所を示します。以下の VALUE から選択します。

• LDP-TRANS …… (LDP の翻訳)
• OTHER-TRANS …… (その他の文書の翻訳)
• ORIGINAL …… (オリジナル文書)

ATRB: VALUE

[必須] 文書のタイプを指定します。以下の VALUE から選択します。

• HOWTO …… (いわゆる HOWTO 文書)
• MINI …… (いわゆる mini-HOWTO 文書)
• BOOK …… (書籍原稿)
• FAQ …… (FAQ List)
• MISC …… (その他)

NAME: BASENAME

[必須] LDP 文書の翻訳の場合、 http://www.linux.or.jp/JF/workshop/JF-in-Progress.html にある元文書へのリンク文字列をそのまま入れてください。たとえば、 Winmodems-and-Linux-HOWTO (SGML) というリンクになっていたら、 NAME: Winmodems-and-Linux-HOWTO となります。

例) NAME: XFree86-HOWTO

DSRC: VALUE

[必須] 一次ソースのファイル形式 (SGML, ,XML, TXT, HTML, TEX, DVI, ROFF) を記述します。

JDAT: YYYY/MM/DD

[必須] 文書の最終更新日付

BDAT: YYYY/MM/DD

翻訳の場合、日本語版が元にしている原版の日付

ODAT: YYYY/MM/DD

原版の最新の日付: この項目は更新の手間が大変ですし、 LDP に関する最新版の日付は自動的に取得できる仕組みになっていますので、 今後は非必須の項目とします。

ITEM: VALUE

[必須] 文書の内容にあった、おおまかなジャンルです。 以下のジャンルからひとつを選択します。

• install …… (Linuxの紹介とインストール)
• faq …… (FAQ)
• guide …… (ガイドとチュートリアル)
• hardware …… (ハードウェアとドライバー)
• diskmanage …… (ブートとディスク管理)
• filesystem …… (ファイルシステム)
• dtp …… (文書作成)
• network …… (ネットワーク)
• database …… (データベース)
• xfree …… (X Window System の設定)
• tool …… (ツールの解説)
• kernel …… (カーネル関連)
• programming …… (プログラミング)
• etc …… (その他)
• archived …… (古い文書)

AUTH: 著者名 <email-address>

[必須] 複数の著者がいるときは、AUT2:, AUT3: .... の KEY が使えます。

TRNS: 翻訳者 <email-address>

複数の翻訳者がいるときは、TRN2:, TRN3: .... の KEY が使えます。

COPY: VALUE

[必須] COPYRIGHT に関して、一番近いものを下記から選んで記入します。

• GPL2 …… GPL2 と明記してあるもの。
• GPL2-like …… 原文の Copyright notice を保存していれば自由に再配布可能
• GFDL …… GFDL と明記してあるもの。
• LDP …… LDP 文書に良く見られる例の形式。
• NO-COM …… 商用再配布を認めない。
• COM-PERM …… 商用再配布には、著者の許可が必要。
• OTHER …… その他（CPNT フィールドに記載して下さい）
• NOTHING …… 配布制限無し、あるいは配布制限に関する記述無し。

CPNT: NOTE

COPY によるカテゴリ分けでは不充分だった場合のメモ書き。

STAT: Doc-CD 初版発行時に調査した結果

ステータスは以下のどれかを選択します。

• Sent …… メールを送ったけど返事が来てない。
• Unreachable …… メールアドレスが無効だった。
• OK …… OK との返事をもらった
• Prohibited …… ダメとの返事をもらった
• Suspend …… 何らかの理由でメールを出さなかった。

その後 Doc-CD と関連しての調査は行われていませんので、 通常は Suspend でかまいません。

CONT: NOTE

[必須] 文書の概要。 JF のトップページの「新着情報」 にリストされる際に、文書の説明文として使われます。

KEY1...KEY5: キーワード

5個まで。 推奨されるキーワードは以下のものです。

Install, INDEX, FAQ, CDROM, Ethernet, Ftape, IDE, Keyboard, Mouse, PCI, PCMCIA, SCSI, Serial, Sound, UPS, Video, XFree86, Network, Mail, News, UUCP, BBS, Compile, Print, Kernel, Boot, DOSEMU, Game, Music, Diskspace, Backup, general, guide, misc

HREF: URI

関連文書がある場合のWWWのリンク先(HOWTOs以外の文書など)

HNAM: HREF のキー文字列

<A HREF='..'>ここの文字列</A>

NOTE:

その他文書のステータスに関するコメント。

以下に 実際の info ファイルの例をあげます。 KEYWORD の順番は特にきまっていませんが、 以下の例のように TITL や NAME が上の方にくる方が 読みやすいでしょう。

また、適宜 # を使ってコメントを入れておくのもよいでしょう。

    #
    # XFree86-HOWTO の info
    # 書き方は http://www.linux.or.jp/JF/workshop/guidance-infofile.html 参照
    #
    TITL: The Linux XFree86 HOWTO
    KIND: LDP-TRANS
    ATRB: HOWTO
    NAME: XFree86-HOWTO
    DSRC: SGML
    AUTH: Eric S. Raymond <esr@thyrsus.com>
    TRNS: 森本 淳 <morimoto@cup.com>
    JDAT: 1999/01/12
    BDAT: 1998/10/27
    CONT: XFree86-3.3 に関するHOWTO
    ITEM: xfree
    COPY: OTHER
    CPNT: 商用配布許可。連絡希望
    STAT: Sent

カーネル付属文書の info ファイル

Linux カーネルのソースアーカイヴに含まれる文書に関しては、

• Copyright がはっきりしている (GPL2)
• プレインテキストで供給されているものが多い
• 数が多い(^^;
• 日付のないものが多いので、 カーネルアーカイヴのバージョンの方が オリジナルのバージョンの版を特定しやすい

など、通常の文書とは異なった性格があります。 このため、ひとまとめにして別の管理を行っています。 これにより info ファイルの扱いも少々異なります。

まず info ファイルのファイル名は (文書のファイル名).info という名前にします (foo.txt の info ファイルなら foo.txt.info)。 これは複数の文書ソースが CVS リポジトリの同じディレクトリに まとめて置かれるためです。

フォーマットも通常の文書とは異なります。 以下にまとめました。通常の文書と同じ内容を書くエントリについては、 説明を省略しています。

TITL: タイトル

NAME: FILENAME

文書ファイルのファイル名です。カーネル文書の場合は BASENAME ではなくディレクトリ名を含んだファイル名をそのまま記述します。

例) NAME: kbuild/commands.txt

JDAT: YYYY/MM/DD (日本語版日付)

BVER: x.y.z (日本語版が元にしている版)

オリジナルの文書が含まれていたカーネルアーカイヴのバージョンを 記述します。

AUTH: 著者名 <email-address>

著者がふたりのときは、AUT2: の KEY が使えます。

TRNS: 翻訳者 <email-address>

翻訳者がふたりのときは、TRN2: の KEY が使えます。

CONT: [必須] 文書の概要(38コラムまで)

KEY1...KEY5: キーワード

NOTE: その他文書のステータスに関するコメント。

info ファイルはいつ参照されるのか?

info ファイルは、JF パッケージや Web コンテンツ、作業進行状況リスト などを自動生成する際に参照されます。具体的には:

1. FTP コンテンツ生成の場合に...
   • 商用配布 が OK かどうかを判断します。
   • 以下の分類によって FTP コンテンツのどこに配置されるかを判断します。
     • LDP-TRANS: LDP 文書の翻訳
     • OTHER-TRANS: その他の文書の翻訳
     • ORIGINAL: JF オリジナル文書
2. INDEX-JF 生成の場合に...
   • タイトル(TITL)、著者名(AUT*)、翻訳者名(TRN*)、更新日時(JDAT)、 概要(CONT) が参照され、INDEX 生成されます。
   • ジャンル(ITEM) にしたがって分類され、分野別 INDEX が生成されます。
3. 作業進行状況リスト生成の場合に...
   • 更新日時(JDAT)、翻訳の原本の日時(BDAT) が参照されます。

以上のように、info ファイルは JF 文書の様々なインフォメーションを提供する上で 重要な役割を果たします。逆に言えば、info ファイルを更新すれば、 INDEX や FTP での公開形態も変更することができます。