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

Wed Mar 4 22:55:55 JST 2015
Contents:

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

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

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 から選択します。

ATRB: VALUE

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

NAME: BASENAME

[必須] LDP 文書の翻訳の場合、 http://linuxjf.sourceforge.jp/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

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

AUTH: 著者名 <email-address>

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

TRNS: 翻訳者 <email-address>

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

COPY: VALUE

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

CPNT: NOTE

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

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

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

その後 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 の順番は特にきまっていませんが、 以下の例のように TITLNAME が上の方にくる方が 読みやすいでしょう。

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


    #
    # XFree86-HOWTO の info
    # 書き方は http://linuxjf.sourceforge.jp/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 カーネルのソースアーカイヴに含まれる文書に関しては、

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

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

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

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 コンテンツ生成の場合に...
  2. INDEX-JF 生成の場合に...
  3. 作業進行状況リスト生成の場合に...

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