# ebappendix コマンド

この文書は EB ライブラリバージョン 4.4.3 に対応しています。

目次:

- appendix (付録) とは
- `ebappendix` コマンドとは
- appendix のソースデータの書き方
  - `catalog(s).app` とは
  - `catalog(s).app` の書き方
  - 副本`.app` とは
  - 副本`.app` の文法
  - 副本`.app` の単独指示子
  - 副本`.app` の複合指示子
- appendix の生成
  - `ebappendix` の実行
  - appendix と CD-ROM 書籍の重ね合わせ
  - `ebappendix` のオプション

Copyright (c) 2003-2006 Motoyuki Kasahara

## appendix (付録) とは

appendix (付録) とは CD-ROM 書籍の補助データのことです。 appendix は CD-ROM 書籍の出版社から提供されているものではなく、 EB ライブラリに固有のものです。

appendix は以下のデータを CD-ROM 書籍に対して提供します。

本文の区切りコード
  あなたが EB ライブラリを使って CD-ROM 辞書の中のある単語を引く際、その 単語の説明が終了する箇所で、EB ライブラリが本文の出力を止めることを あなたは期待するのではないでしょうか。 しかし、EB ライブラリはそのような動作を保証することができません。 なぜなら、CD-ROM 書籍の本文には、項目の終わりを示す印が存在しないから です。 幸いにも、多くの CD-ROM 書籍には、項目の終わりを示す印の代替として 使える、区切りコード (stop code) というものを持って います。 通常、EB ライブラリはこの区切りコードを自動的に推測するようになって いるのですが、時々誤った区切りコードを導き出すことがあります。 appendix の区切りコードは、その書籍の正しい区切りコードを EB ライブラリ に教えてやるために用います。
外字の代替文字列
  多くの CD-ROM 書籍は、外字 (独自に定義した文字) を持っており、本文中で その外字を使っています。 CD-ROM 書籍では外字のビットマップフォントを用意しており、 クライアントアプリケーションが外字を出力するには、そのフォントを描画 しなくてはなりません。 appendix では、外字の 代替文字列 (alternation text) を定義することができます。 アプリケーションは、ビットマップフォントを描画する代わりに、その 代替文字列を出力することにしても良いでしょう。

appendix のレイアウトは CD-ROM 書籍のものとよく似ています。 トップディレクトリには `catalog` もしくは `catalogs` ファイルが存在し、各副本のデータは対応するサブディレクトリに配置されて います。

## `ebappendix` コマンドとは

appendix はバイナリ形式のデータファイルで構成されますので、手で直接 編集するのは容易ではありません。 そこで、EB ライブラリでは `ebappendix` コマンドを用意しています。 `ebappendix` コマンドは、テキスト形式で書かれたデータを読み込み、 バイナリ形式の appendix を生成します。

EB ライブラリの公式な FTP サイト ftp://ftp.sra.co.jp/pub/misc/eb/appendix/ には、既にいくつかの書籍用の appendix が置いてあります。 ここに載っていない CD-ROM 書籍用の appendix を用意したい場合は、 `ebappendix` コマンドを使いましょう。

## appendix のソースデータの書き方

この章では、appendix のソースデータの書き方を説明します。 ここで、「ソースデータ」と言っているのは、`ebappendix` が読み込む テキスト形式で書かれたデータのことです。

appendix を生成するためには、次に挙げるソースデータファイルが必要です。 これらのファイルをすべて、同じディレクトリ上に用意するようにします。

`catalog.app` または `catalogs.app`
  appendix には必ず、`catalog` または `catalogs` という 名前のファイルが必要です。 `catalog.app`, `catalogs.app` はその生成元となる ファイルです。 appendix に収録されている 副本 (subbook) (詳しくは 「`catalog(s).app` の書き方」 を参照) の一覧を記します。
副本`.app`
  appendix が収録している副本それぞれに対して、一つずつ用意する必要が あります (副本 の部分は、実際は個々の副本の名前になります)。 appendix のメインデータである、本文の区切りコードや外字の代替文字列は、 このファイルに記します。

### `catalog(s).app` とは

CD-ROM 書籍と同様に、appendix パッケージにも必ず `catalog` もしくは `catalogs` という名前のファイルのどちらか一方が 必要です。 `catalog.app`, `catalogs.app` ファイルは、その 生成元となります。

`ebappendix` コマンドに appendix を生成させる際には、 `catalog.app` か `catalogs.app` のどちらかを必ず 用意しておく必要があります。

`ebappendix` の標準の動作では、`catalog.app` という ファイル名にしておくと、生成するファイル名も `catalog` に なります。 また、appendix 全体のディレクトリ構造が、電子ブックに似た形式になります。

反対に、`catalogs.app` というファイル名にしておくと、生成する ファイル名も `catalogs` になります。 また、appendix 全体のディレクトリ構造が、EPWING に似た形式になります。

ただし、EPWING の書籍に対して電子ブック形式の appendix を使用しても、 動作そのものには支障がありません。 逆も同様です。

### `catalog(s).app` の書き方

`catalog(s).app` には、書籍に収録されている副本のディレクトリ名を 1 行に 1 つずつ書き並べます。 副本のディレクトリ名は、`ebinfo` コマンドを使うと容易に分かります。

以下は、`ebinfo` の実行例です。

>     % ebinfo /mnt/cdrom
>     ディスクの形式: EB/EBG/EBXA/EBXA-C/S-EBXA
>     文字コード: JIS X 0208
>     副本の数: 2

>     副本  1:
>       題名: 新英和辞典（第三版）
>       ディレクトリ: ejdict
>       検索方式: 前方一致 後方一致 条件 メニュー
>       フォントの大きさ: 16 24 30 48
>       半角フォントの文字: 0xa121 -- 0xa24e
>       全角フォントの文字: 0xa321 -- 0xa27e

>     副本  2:
>       題名: この書籍の使い方
>       ディレクトリ: howto
>       検索方式: 前方一致 後方一致 条件 メニュー
>       フォントの大きさ: 16 24 30 48
>       半角フォントの文字:
>       全角フォントの文字: 0xa321 -- 0xa27e

この辞書用の appendix を作成する場合、`catalog(s).app` には次の ように記します。

>     ejdict
>     howto

(`ebinfo` コマンドに関しての詳細は、 ebinfo コマンドのマニュアル を参照のこと。)

ディレクトリ名の大文字、小文字は、同じものとして扱われます。 また、空行およびおよび空白以外の最初の文字がハッシュ記号 (`#`) である行は無視されます。

必ずもとの書籍の副本すべてを、同じ順序で `catalog(s).app` に 記すようにして下さい。

### 副本`.app` とは

appendix が収録している副本それぞれに対して、ソースデータファイル 副本`.app` を用意する必要があります。 副本 の部分は、実際には個々の副本の使用する ディレクトリ名になります。

たとえば、前節の例では、書籍が `ejdict` と `howto` というディレクトリ名を持った副本を持っていました。 この場合、用意するファイルは `ejdict.app` と `howto.app` になります。

副本`.app` ファイルは appendix のメインデータである、 本文の区切りコードや外字の代替文字列を収録した `appendix` や `furoku` といったファイルの生成元になります。 (appendix を電子ブック形式で生成すると `appendix`、EPWING 形式 で生成すると `furoku` というファイル名になります。)

### 副本`.app` の文法

各副本のソースデータを記したファイル「副本`.app`」 の中では、空行、および空白以外の最初の文字がハッシュ記号 (`#`) である行は無視されます。

他の行はすべて、単独指示子 (single directive) か 複合指示子 (group directive) のいずれかでなくてはなりません。 単独指示子と複合指示子は、どのような順序で定義しても差し支えありません。

単独指示子とは、1 行で完結する指示子です。 単独指示子の一般形は次の通りです。

>     指示子の名前    指示子の値

以下の例では、`stop-code` が指示子の名前、 `0x1f09 0x0001` がその値です。

>     stop-code          0x1f09 0x0001

指示子名の大文字と小文字は区別されますので、`stop-code` を `Stop-Code` と書くことはできません。 指示子の名前と値の区切りには、空白かタブを用います。 連続した空白とタブが、行頭および行末にあった場合、それらは無視されます。

複合指示子とは、記述が設定ファイル内の複数行に渡る指示子です。 複合指示子の一般形は次の通りです。

>     begin 複合指示子の名前
>         副指示子の名前    副指示子の値
>                  :
>                  : (繰り返し)
>                  :
>     end

キーワード `begin` が、複合指示子の開始を表します。 `begin` は後ろに 複合指示子の名前 を引数として 取ります。 `begin` と 複合指示子の名前 は空白かタブで区切り、 両方とも同じ行の中に置きます。 キーワード `end` は、複合指示子の終了を表します。 `end` は、単独で 1 行にして置きます。

今のところ 副本`.app` で使用できる複合指示子の名前は、 `narrow` と `wide` の 2 つだけです。 それぞれの 副指示子 は、`begin` と `end` の行の間に置きます。 副指示子に関する記述の一般的な規則は、単独指示子と変わりません (たとえば、副指示子の名前と 副指示子の値 は空白か タブで区切ることなど)。

以下は、 `narrow` 複合指示子の記述例です。

>     begin narrow
>         range-start     0xa121
>         range-end       0xa123
>         0xa121          [→参照]
>         0xa122          [→音声]
>         0xa123          [→図解]
>     end

### 副本`.app` の単独指示子

単独指示子には次のようなものがあります。

`character-code`
  appendix の文字コードを指定します。 文字コードは必ず、CD-ROM 書籍に合わせるようにします。 CD-ROM 書籍の文字コードは、`ebinfo` コマンドの出力を見れば確認 できます。 CD-ROM 書籍が ISO 8859-1 で書かれている場合は、指示子の値として `ISO8859-1` を指定します。 それ以外の場合は、`JISX0208` を指定して下さい。

  >     character-code          JISX0208

  この指示子は、副本`.app` ファイル内で必ず一回定義 されなければなりません。 定義しなかったり、二度以上定義するとエラーになります。
`stop-code`
  副本の本文の区切りコードを指定します。 指示子の値は、区切りコードの文字番号を 2 つ書き並べたものになります。

  >     stop-code          0x1f09 0x0001

  文字番号は、`0x` ないし `0X` に続けて 16進数 4 桁 で記します。 ただし、1つ目の文字番号は、`0x1f09` か `0x1f41` で なければなりません。 それ以外だとエラーになります。 `ebstopcode` コマンドを使うと、副本に適切な区切りコードを 特定することができます (詳しくは ebstopcode コマンドのマニュアル を参照の こと)。 この指示子は定義しなくても構いませんが、二度以上定義するとエラーになります。

### 副本`.app` の複合指示子

`narrow` および `wide` 複合指示子は、それぞれ副本に 対する半角外字および全角外字に対する代替文字列を定義するために用います。 ただし、副本が外字を定義していても、代替文字列を利用する必要がなければ、 `narrow`, `wide` 複合指示子を記述する必要はありません。

`narrow` と `wide` 複合指示子内で定義できる副指示子は、 まったく同じです。 副指示子には次のようなものがあります。

`range-start`
  外字の定義範囲を記します。 開始位置の文字番号を `range-start` で、終了位置の文字番号を `range-end` で指定します。 文字番号は、`0x` ないし `0X` に続けて 16進数 4 桁で 記します。 以下は記述例です。

  >         range-start     0xa121
  >         range-end       0xa123

  定義範囲は、`ebinfo` コマンドの出力結果の 「半角フォントの文字 (narrow font characters)」 「全角フォントの文字 (wide font characters)」 で記された範囲と一致させるようにして下さい。 `narrow` および `wide` 複合指示子内では、 必ず一回ずつ `range-start` および `range-end` を 定義しなければなりません。 定義しなかったり、二度以上定義したりするとエラーになります。
`0xhhhh`
  hhhh は、4 桁 の 16進数です。 文字番号 `0x` hhhh の全角外字ないし半角外字に対して、 代替文字列を定義します。

  >         0xa121          [名]

  appendix が ISO 8859-1 で書かれている場合は、代替文字列も ISO 8859-1 で定義します。 それ以外の場合は、代替文字列を日本語 EUC で定義します。 いずれも、代替文字列は最長で 31 バイトまでで、それを超えるとエラーに なります。 `range-start`, `range-end` で指定した定義範囲内の 外字すべてについて、代替文字列を設定する必要はありません。 ただし、同一の複合指示子内で、一つの文字番号の外字に対して代替文字列を 定義できるのは一回までです。 複数回設定しようとすると、エラーになります。 また、範囲外の文字番号の代替文字列を定義しようとしても、やはりエラーに なります。 CD-ROM 書籍がどのような外字を定義しているのかは、`ebfont` コマンド で調べることができます (詳しくは ebfont コマンドのマニュアル を参照のこと)。

## appendix の生成

appendix のソースデータが書けたら、`ebappendix` コマンドを用いて 実際の (バイナリ形式の) appendix を生成します。

以下、この章では `ebappendix` の実行方法について詳しく説明します。

### `ebappendix` の実行

`ebappendix` の一般的な起動方法は次の通りです。

>     % ebappendix 入力ディレクトリのパス

入力ディレクトリのパス には、読み込む appendix ソースデータの ディレクトリ、つまり `catalog.app` または `catalogs.app` ファイルが存在するディレクトリを指定します。 省略した場合は、カレントディレクトリを指定したとみなされます。

標準では、出力ファイルはカレントディレクトリに作成されます。

`--output-directory` オプションを指定することで、 `ebappendix` はカレントディレクトリ以外の場所に出力することが できます。

>     % ebappendix --output-directory 出力ディレクトリのパス \
>       入力ディレクトリのパス

もし出力ディレクトリが存在していなければ、自動的に `ebappendix` が生成します。

実行すると、`ebappendix` は出力ディレクトリの下にサブディレクトリ を作り、いくつかのファイルを生成します。

### appendix と CD-ROM 書籍の重ね合わせ

HDD 上にコピーした CD-ROM 書籍と同じディレクトリに、appendix を重ねて 置くことができます。

これには、`ebappendix` の `--output-directory` と `--no-catalog` オプションを使います。 `--output-directory` オプションには、CD-ROM 書籍の トップディレクトリを指定します。

>     % ebappendix --no-catalog --output-directory 出力ディレクトリのパス \
>       入力ディレクトリのパス

なお、appendix の形式 (電子ブックか EPWING か) は CD-ROM 書籍に合わせる ようにします (詳しくは 「`catalog(s).app` の書き方」 を参照)。

`ebappendix` の実行前後で CD-ROM 書籍のディレクトリ構成が どのように変化するのか、例を記してみます。 まず電子ブックの場合ですが、実行前のディレクトリ構成が次のように なっていたとします。

>     catalog
>     ejdict/start
>     howto/start

`ebappendix` で appendix を重ね合わせると、次のような構成に なります。

>     catalog
>     ejdict/start
>     ejdict/appendix  ← appendix のファイル
>     howto/start
>     howto/appendix   ← appendix のファイル

同様に、EPWING で実行前のディレクトリ構成が次のようになっていたと すると、

>     catalogs
>     ejdict/data/honmon
>     howto/data/honmon

実行後は、次のような構成になります。

>     catalogs
>     ejdict/data/honmon
>     ejdict/data/furoku  ← appendix のファイル
>     howto/data/honmon
>     howto/data/furoku   ← appendix のファイル

CD-ROM 書籍によっては、ディレクトリ名に大文字が混じっていることが ありますが、`ebappendix` はそれを検出しますので、名前を小文字に 変えたディレクトリを別途作ってしまうことはありません。

`--no-catalog` オプションを指定すると、`ebappendix` は カタログファイル `catalog` や `catalogs` ファイルを 生成しなくなります。 この appendix を EB ライブラリのアプリケーションから使う際は、 CD-ROM 書籍に最初から用意されている `catalog` や `catalogs` ファイルを CD-ROM 書籍、appendix 共用の カタログファイルとして流用することになります。

appendix のカタログファイルは、CD-ROM 書籍のカタログファイルの部分集合 となっているため、こうした事が可能となっています。 `--no-catalog` オプションを指定し忘れると、 `ebappendix` は CD-ROM 書籍のカタログファイルを上書き してしまいますので、注意して下さい。

### `ebappendix` のオプション

`ebappendix` コマンドは、伝統的な一文字オプション名と覚えやすい 長いオプション名の両方を扱うことができます。 長いオプション名を表すには、`-` ではなく `--` を 用います。 オプション名が一意に決まる範囲内で、名前の後方部分を省略することができま す。

`-b 書籍の形式`
`--booktype 書籍の形式`
  appendix を電子ブック、EPWING のどちらの形式のレイアウトに似せて作る のかを指定します。 電子ブック形式なら `eb`、EPWING 形式なら `epwing` と指定します。 このオプションを指定しなかった場合、次の要領でどちらの形式で生成する のかがが決定されます。 まず、入力ディレクトリに `catalog.app` ファイルが存在すれば それが読み込まれ、電子ブック形式の appendix が生成されます。 `catalog.app` がなく、代わりに `catalogs.app` が 存在すればそれが読み込まれ、EPWING 形式の appendix が生成されます。 (`catalogs.app` も `catalog.app` なければ、エラー になります。)
`-d`
`--debug`
`--verbose`
  デバッグ用のメッセージを、標準エラー出力に出力します。
`-h`
`--help`
  ヘルプメッセージを標準出力に出力して、終了します。
`-n`
`--no-catalog`
  カタログファイル (`catalog` および `catalogs`) を 生成しません。 このオプションは、書籍と appendix を同じディレクトリに重ね合わせる際に 有効です (詳しくは 「appendix と CD-ROM 書籍の重ね合わせ」 を参照のこと)。
`-o ディレクトリ`
`--output-directory ディレクトリ`
  出力先のディレクトリを指定します。 このオプションを省略すると、カレントディレクトリ (`.`) に 出力します。 ディレクトリが存在しなければ、自動的に生成されます。
`-t`
`--test`
  ファイルを出力しません。 入力ファイルを読み込んで、内容のチェックだけを行います。
`-v`
`--version`
  バージョン番号を標準出力に出力して、終了します。