This is eb-ja.info, produced by makeinfo version 4.0 from eb-ja.texi.

INFO-DIR-SECTION CD-ROM Book Utilities
START-INFO-DIR-ENTRY
* eb-ja: (eb-ja).               C library for accessing CD-ROM book.
END-INFO-DIR-ENTRY

   EB Library: CD-ROM 書籍にアクセスするための C ライブラリ, 笠原基之

   Copyright (C) 1998, 99  Motoyuki Kasahara

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by Free Software Foundation, Inc.


File: eb-ja.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)

   この文書は第 3.2.1 版です。

* Menu:

* Introduction::                はじめに
* Features::                    EB ライブラリの特徴
* Compilation::                 プログラムのコンパイル方法
* Init and Exit::               ライブラリの初期化と後始末
* EB_Book::                     CD-ROM 書籍と `EB_Book' オブジェクト
* Error Handling::              エラー処理
* Subbook::                     副本
* Search::                      検索
* Text Data::                   テキストデータ
* Local Character::             外字
* Index::                       索引

 --- The Detailed Node Listing ---

はじめに

* Electronic Book and EPWING::  電子ブックと EPWING について
* Construction of This Book::   本書の構成について

EB ライブラリの特徴

* Header Files::                ヘッダファイル
* Character Code::              文字コード
* Compressed Book::             圧縮された書籍
* Traditional System::          古いシステムへの対応

プログラムのコンパイル方法

* Compilation Simple Way::      てっとり早いコンパイル方法
* Compilation with Autoconf::   Autoconf を併用したコンパイル方法

ライブラリの初期化と後始末

* Init and Exit Sample::        サンプルプログラム
* Init and Exit Functions::     関数の詳細

CD-ROM 書籍と `EB_Book' オブジェクト

* EB_Book Explanation::         `EB_Book' オブジェクト
* EB_Book Sample::              サンプルプログラム
* EB_Book Data Types::          データ型の詳細
* EB_Book Functions::           関数の詳細

エラー処理

* Error Code and Message::      エラーコードとエラーメッセージ
* Tolerance to Error::          エラーに対する寛容さ
* Error Data Types::            データ型の詳細
* Error Code List::             エラーコードの一覧
* Error Functions::             関数の詳細

副本

* Subbook Code::                副本コード
* Current Subbook::             選択中の副本
* Subbook Sample::              サンプルプログラム
* Subbook Data Types::          データ型の詳細
* Subbook Functions::           関数の詳細

検索

* Word Search::                 前方一致、後方一致、完全一致検索
* Keyword Search::              条件検索
* Multi Search::                複合検索
* EB_Hit::                      一致エントリの情報
* Get Remained Entries::        残っているエントリの取得
* Search Data Types::           データ型の詳細
* Search Functions::            関数の詳細

テキストデータ

* Seek and Read Text Data::     テキストデータのシークと読み込み
* Text Data Format::            テキストデータの内部形式
* Hook::                        フック
* Hook and Character Code::     フックと文字コードの関係
* Copyright Notice::            著作権表示
* Menu::                        メニュー
* Multi Candidates::            複合検索の候補一覧
* Stop Code Issue::             区切りコードの問題
* Text Data Sample::            サンプルプログラム
* Text Data Types::             データ型の詳細
* Hook Function Details::       フック関数の詳細
* Hook Code List::              フックコードの一覧
* Hookset Access Functions::    フックセット操作関数の詳細
* Builtin Hook Functions::      組み込みフック関数の詳細
* Text Data Functions::         テキストデータ操作関数の詳細

外字

* Narrow & Wide Font::          半角外字と全角外字
* Font Size and Font Code::     外字の大きさと外字コード
* Current Font Height::         選択中の外字フォントの高さ
* Get Font::                    外字フォントの取り出し
* Convert Font::                外字フォントの変換
* Local Character in Text::     テキスト中の外字
* Font Data Types::             データ型の詳細
* Font Constants::              定数の詳細
* Font Data Functions::         関数の詳細

索引

* Data Type Index::             データ型の索引
* Function Index::              関数の索引
* Variable Index::              変数と定数の索引


File: eb-ja.info,  Node: Introduction,  Next: Features,  Prev: Top,  Up: Top

はじめに
********

   EB ライブラリは、CD-ROM 書籍にアクセスするための C 言語のライブラリ
です。 主に UNIX 系 OS のシステム上で動作させることができます。 EB ライ
ブラリは、電子ブック (EB, EBG, EBXA, EBXA-C, S-EBXA) および EPWING 形式
の CD-ROM 書籍に対応しています。

このライブラリは、書籍内部のデータ形式についての理解はなるべく必要とせ
ずに、アプリケーションプログラムを開発できることを目標に開発されていま
す。

   本書は、EB ライブラリを使ってアプリケーションプログラムを作成する開
発者向けに、ライブラリの仕様を解説した文書です。 そして、ライブラリの公
式な参照マニュアルでもあります。 読み進めるにあたって、読者は EB ライブ
ラリおよび CD-ROM 書籍の内部構造について知っている必要はありませんが、
電子ブックか EPWING を利用して、 実際に CD-ROM 書籍がどのようなものかを
理解しておくことをお薦めします。 また、C 言語によるプログラミングについ
ては、十分に理解していることを前提とします。

   この文書は、EB ライブラリバージョン 3.2.1 に対応しています。 本書の
内容に沿って EB ライブラリを使ったアプリケーションプログラムを作成する
には、お使用いのシステムに EB ライブラリバージョン 3.2.1 と C コンパイ
ラをインストールしておいて下さい。

   EB ライブラリはフリーソフトウェアです。 あなたは、 Free Software
Foundation が公表した GNU General Public License (GNU 一般公有使用許諾)
バージョン 2 あるいはそれ以降の各バージョンの中からいずれかを選択し、
そのバージョンが定める条項に従って本プログラムを再頒布または変更するこ
とができます。

   EB ライブラリは有用とは思いますが、頒布にあたっては、市場性及び特定
目的適合性についての暗黙の保証を含めて、いかなる保証も行ないません。 詳
細については GNU General Public License をお読み下さい。

* Menu:

* Electronic Book and EPWING::  電子ブックと EPWING について
* Construction of This Book::   本書の構成について


File: eb-ja.info,  Node: Electronic Book and EPWING,  Next: Construction of This Book,  Prev: Introduction,  Up: Introduction

電子ブックと EPWING について
============================

   電子ブックと EPWING は、いずれも主に日本で使われている電子書籍のデ
ータ形式の名称で、 CD-ROM に収めた形で数々の書籍が市販されています。
CD-ROM は ISO 9660 形式なので、 CD-ROM
ドライブが扱えるシステムであれば、 容易にアクセスすることができます。
電子書籍のデータ形式とはいっても、実際は辞書向けに特化した構造となって
おり、市販されている書籍も辞書の類が圧倒的に多いようです。

   EPWING、電子ブックともに、データ形式に関する規格の全容は一般公開され
ていませんが、EPWING ついては規格の一部が日本工業規格 JIS X 4081 「電
子出版検索データ構造」として公開されています。 さらに、EPWING と電子ブ
ックのデータ形式は、酷似していることが知られています。

   EB ライブラリの開発者も、 EPWING、電子ブック規格の全容は知りません。
EB ライブラリでは JIS X 4081 の記述をもとに、
EPWING、電子ブックを読めるようにしてあります。 しかしながら、規格の全容
が分からない状態で開発しているため、残念ながら一部に正しく読めない書籍
が存在します。


File: eb-ja.info,  Node: Construction of This Book,  Prev: Electronic Book and EPWING,  Up: Introduction

本書の構成について
==================

   次章「EB ライブラリの特徴」では、EB ライブラリが対応している機能、対
応していない機能について、簡単に説明します。 また、ライブラリの概略に
関して、最初に知っておいたほうが良いと思われる事柄をいくつか説明してい
ます。

   さらに次の章「プログラムのコンパイル方法」では、EB ライブラリを利用
したプログラムのコンパイル方法を説明します。 本書のサンプルプログラム
をコンパイルするために必要な情報も、この章に記してあります。

   そして、その次の章「ライブラリの初期化と後始末」からが、実際の EB ラ
イブラリのプログラミングの解説となります。 それぞれの章は、次のような節
から構成されています。
ただし、章によっては一部の節がない場合もあります。

解説
     その章で解説する機能や概念についての基礎知識、EB ライブラリの仕様
     の概要について解説しています。

サンプルプログラム
     「解説」ではプログラムの断片だけを示すことが多いので、動作可能な
     プログラムのサンプルをここで示します。

データ型の詳細
関数の詳細
定数値の一覧
     データ型や関数、定数値などについての参照マニュアルです。


File: eb-ja.info,  Node: Features,  Next: Compilation,  Prev: Introduction,  Up: Top

EB ライブラリの特徴
*******************

   前に述べたように、 EB ライブラリは、電子ブック (EB, EBG, EBXA,
EBXA-C, S-EBXA) と EPWING 形式の CD-ROM 書籍に対応しています。

   EB ライブラリは、これらの CD-ROM 書籍に対して、次の処理を行うことが
できます。

   * 前方一致検索

   * 後方一致検索

   * 完全一致検索

   * 条件検索

   * 複合検索

   * 見出しデータの取得

   * 本文データの取得

   * メニューの取得

   * 著作権表示の取得

   * カラー画像データの取得 (ただし EPWING のみ)

   * モノクロ画像データの取得

   * 外字データの取得

   * 動画データの取得

   この章では、EB ライブラリの概要に関して、あらかじめ知っておいて頂い
たほうが良いと思われるその他の事柄について、何点か説明します。

* Menu:

* Header Files::                ヘッダファイル
* Character Code::              文字コード
* Compressed Book::             圧縮された書籍
* Traditional System::          古いシステムへの対応


File: eb-ja.info,  Node: Header Files,  Next: Character Code,  Prev: Features,  Up: Features

ヘッダファイル
==============

   EB ライブラリには、いくつかのヘッダファイルが用意されています。

`appendix.h'
     付録 (appendix) に関連した宣言、定義を行う。

`binary.h'
     バイナリデータに関連した宣言、定義を行う。

`eb.h'
     EB ライブラリの基本ヘッダファイル。

`error.h'
     エラーコードに関連した宣言、定義を行う。

`font.h'
     外字に関連した宣言、定義を行う。

`text.h'
     テキストデータ (本文、見出しなど) に関連した宣言、定義を行う。

これ以外にもいくつかのファイルがインストールされますが、上に挙げたヘッ
ダファイルから読み込まれるもので、アプリケーションプログラムが直接読み
込む必要はありません。

   アプリケーションプログラムは、EB ライブラリを使う際にこのヘッダファ
イルをファイルの先頭付近で読み込みます。

     #include <eb/eb.h>
     #include <eb/error.h>

`eb.h' ではなく、`eb/eb.h' を読み込むようにして下さい。


File: eb-ja.info,  Node: Character Code,  Next: Compressed Book,  Prev: Header Files,  Up: Features

文字コード
==========

   EB ライブラリでは、CD-ROM 書籍内のデータを文字列にしてアプリケーショ
ンに渡す際の文字コードを規定しています。

   EBG (海外の電子ブック) については、データが ISO 8859-1 (ラテン文字 1、
 ただし制御文字を除く) で書かれているため、データのやり取りも ISO
8859-1 で行います。 ただし、外字だけは 2 バイトで表現し、 0x0101 〜
0x1efe の領域を使用します。 (外字領域の下位 16 ビットは 0x01 〜 0xfe の
範囲を使用します。)

   EPWING および EGG, EBXA-C を除いた電子ブックについては、データが JIS
X 0208 (日本語のかな漢字) で書かれており、 JIS X 0208 を 0x2121 〜
0x7e7e にマッピングし、0xa121 〜 0xfe7e を外字領域にしています (下図)。

     　　　　　　　　　　　　　　　　上位８ビット
     
     　　　　　　　　　００　２１　　　　７ｅ　ａ１　　　　ｆｅ
     　　　　　　　００┌──┬─────┬──┬─────┬┐
     　　　　　　　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　２１├──┼─────┼──┼─────┼┤
     　　　　　　　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　　　│　　│ＪＩＳ　Ｘ│　　│　外字　　││
     　　　　　　　　　│　　│０２０８　│　　│　　　　　││
     　　　　　　　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　７ｅ├──┼─────┼──┼─────┼┤
     下位８ビット　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　ａ１├──┼─────┼──┼─────┼┤
     　　　　　　　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　ｆｅ└──┴─────┴──┴─────┴┘

EB ライブラリでは JIS X 0208 部分を日本語 EUC (EUC-JP) にエンコードし
て、アプリケーションとのやり取りも日本語 EUC で行います。 したがって、
JIS X 0208 部分は 0xa1a1 〜 0xfefe にマッピングされます。

   EBXA-C (中日・日中辞書の電子ブック) については、データが JIS X 0208
(日本語のかな漢字) と GB 2312 (中国語の簡体字) で書かれており、 JIS X
0208 を 0x2121 〜 0x7e7e にマッピング、 GB 2312 を 0x21a1 〜 0x7efe に
マッピングし、 0xa121 〜 0xfe7e を外字領域にしています (下図)。

     　　　　　　　　　　　　　　　　上位８ビット
     
     　　　　　　　　　００　２１　　　　７ｅ　ａ１　　　　ｆｅ
     　　　　　　　００┌──┬─────┬──┬─────┬┐
     　　　　　　　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　２１├──┼─────┼──┼─────┼┤
     　　　　　　　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　　　│　　│ＪＩＳ　Ｘ│　　│　外字　　││
     　　　　　　　　　│　　│０２０８　│　　│　　　　　││
     　　　　　　　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　７ｅ├──┼─────┼──┼─────┼┤
     下位８ビット　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　ａ１├──┼─────┼──┼─────┼┤
     　　　　　　　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　　　│　　│ＧＢ　　　│　　│　　　　　││
     　　　　　　　　　│　　│２３１２　│　　│　　　　　││
     　　　　　　　　　│　　│　　　　　│　　│　　　　　││
     　　　　　　　ｆｅ└──┴─────┴──┴─────┴┘

EB ライブラリでは、アプリケーションとのやり取りに使う文字コードは、 日
本語 EUC および中国語 EUC (EUC-ZH) です。 したがって、そのままでは JIS
X 0208 と GB 2312 が 0xa1a1 〜 0xfefe にマッピングされ、衝突してしまい
ます。 この問題をどう回避するのかは、アプリケーション側で決める必要があ
ります (詳しくは、*note フックと文字コードの関係 : Hook and Character
Code.)。

   電子ブック、EPWING ともに、外字については、アプリケーション側でどう
扱うかを決める必要があります。 外字について詳しくは *note 外字 : Local
Character.。


File: eb-ja.info,  Node: Compressed Book,  Next: Traditional System,  Prev: Character Code,  Up: Features

圧縮された書籍について
======================

   EB ライブラは、データを圧縮して収録した書籍を扱うことができます。 今
のところ、次の 4 種類の圧縮方法に対応しています。

`ebzip' 圧縮形式
     EB ライブラリ独自の圧縮形式です。 付属の `ebzip'
     コマンドを使うと、この形式で圧縮した書籍を作れます。

EPWING V4, V5 形式
     市販の EPWING V4, V5 の書籍の一部に、この形式で圧縮したものがあり
     ます。

EPWING V6 形式
     市販の EPWING V6
     の書籍の一部に、この形式で圧縮したものがあります。 EPWING V4, V5
     形式の改良型です。

S-EBXA 形式
     市販の S-EBXA の書籍の一部に、この形式で圧縮したものがあります。

   データの伸長は EB ライブラリ側で自動的に行われるため、 アプリケーシ
ョンプログラムからは、アクセスしている書籍が圧縮されているかどうか分か
りません。 アプリケーションプログラムは、書籍が圧縮されているかどうかで
処理を変える必要はありません。


File: eb-ja.info,  Node: Traditional System,  Prev: Compressed Book,  Up: Features

古いシステムへの対応
====================

   アプリケーションプログラムのコンパイルに用いるコンパイラには、 ANSI
(ANSI X3.159-1989, ISO/IEC 9899-1990) 対応のものを対象としています。 ま
た、システムには POSIX.1 (IEEE Std. 1003.2-1990, ISO/IEC 9945-1:1990)
準拠ないし互換のものを対象としています。

   また、EB ライブラリでは、古いコンパイラや UNIX 系システムへの対応も
それなりに行われています。 ここでは、古いコンパイラや UNIX
系システムで、アプリケーションプログラムをコンパイルする際の注意点を挙
げておきます。

`const'
     `const' 修飾子が使えないコンパイラでは、本書の中の `const' と書か
     れた部分はすべて無視して下さい。

`void *'
     EB ライブラリには、`void *' を引数にとる関数がありますが、 CPP マ
     クロ `__STDC__' が定義されていないコンパイラでは、 `void *' の代わ
     りに `char *' を使います。

本書の以降の節ではこれらのことを明記しませんので、`const' や `void *'
と書かれている箇所は、適宜読み替えて下さい。


File: eb-ja.info,  Node: Compilation,  Next: Init and Exit,  Prev: Features,  Up: Top

プログラムのコンパイル方法
**************************

   本章では、EB ライブラリを利用したプログラムのコンパイル方法を説明し
ます。

   EB ライブラリを `/usr/local' にインストールし、個々のファイルのイン
ストール先を変更していなければ、ヘッダファイルは
`/usr/local/include/eb' にインストールされ、ライブラリファイルは
`/usr/local/lib' にインストールされます。 EB ライブラリを利用したアプリ
ケーションプログラムを作成する際は、 これらのファイルを使用することにな
ります。

   EB ライブラリのヘッダファイルの一部には、GNU Autoconf の使用を前提
とした記述が含まれており、Autoconf を併用しないとプログラムが正しくコ
ンパイルできません。

   しかし、 EB ライブラリの概要を理解するためのプログラムに、わざわざ
Autoconf を使用するのは大変です。 そこでまず、Autoconf を使わずにてっと
り早くコンパイルする方法を紹介します。

   その後で、Autoconf を併用する方法についても説明します。 フリーソフト
ウェアとしてアプリケーションを公開するなら、こちらの方法をとることをお
薦めします。 Autoconf を単体で使用してもヘッダファイルの問題は解決でき
ますが、 本書では GNU Automake, および GNU Libtool も一緒に併用した方法
について説明しています。

* Menu:

* Compilation Simple Way::      てっとり早いコンパイル方法
* Compilation with Autoconf::   Autoconf を併用したコンパイル方法


File: eb-ja.info,  Node: Compilation Simple Way,  Next: Compilation with Autoconf,  Prev: Compilation,  Up: Compilation

てっとり早いコンパイル方法
==========================

   アプリケーションプログラムをコンパイルする際は、ヘッダファイルのデ
ィレクトリ位置を C コンパイラに教えてやる必要があるかも知れません。 一
般に UNIX の C コンパイラでは、`-I' オプションで位置を指定します。

     cc -I/usr/local/include -c sample.c

`/usr/local/include/eb' ではなく、その一つ上を指定します (*note ヘッダ
ファイル: Header Files.)。

   ただし、 EB ライブラリは Autoconf
を併用することを前提としているため、 そのままではコンパイルエラーが発生
してしまいます。 そこで、この節では Autoconf を併用する代わりに、次の手
順で回避します。

  1. EB ライブラリ 3.2.1 のソースードを展開します。

  2. ソースコードに付属している `configure' スクリプトを実行します。
     `configure' のコマンド行引数は、インストール時と同じものを指定し
     ます。

  3. `config.h' というファイルが生成されるので、アプリケーションプログ
     ラムのディレクトリにコピーします。

アプリケーションプログラムのソースファイルでは、この `config.h' を読み
込むようにします。 必ずファイルの一番先頭で読み込んで下さい。

     #include "config.h"

またこれに伴い、`config.h' のディレクトリ位置を指定するために、 C コン
パイラのオプションをさらに追加する必要があるかも知れません。

     cc -I. -I/usr/local/include -c sample.c

   次に、リンクして実行バイナリを生成する工程ですが、 以下に記したライ
ブラリの一部、もしくは全部をリンクします。 括弧内は、ライブラリのファイ
ル名です (ただし、`.a' や `.so' といった接尾子は省略)。

EB ライブラリ (libeb)
     EB ライブラリの本体です。このライブラリは必須です。

zlib (libz)
     圧縮と伸長を行うライブラリです (詳しくは
     <http://www.gzip.org/zlib/>)。 `ebzip' コマンドで圧縮した辞書を扱
     うために使います。 このライブラリは必須です。 EB ライブラリのソー
     スコードには zlib も収録されています。 システムに zlib がインスト
     ールされていなければ、EB ライブラリをインストールする際に、zlib
     も自動的にインストールされます。

gettext ライブラリ (libintl)
     メッセージの国際化機能 (NLS) を提供するライブラリですメッセージの
     国際化機能を有効にして EB ライブラリをコンパイルしている場合は、
     必要になるかも知れません。 gettext の実装は何種類かありますが、EB
     ライブラリで使用できるのはメッセージカタログの形式が GNU gettext
     互換のものだけです。

     メッセージの国際化機能を有効にしている場合でも、OS の標準 C ライブ
     ラリとして glibc を採用しているシステムでは、指定する必要はありま
     せん。

iconv ライブラリ
     文字コード変換のライブラリです。 gettext ライブラリをリンクする場
     合、一緒に必要となるかも知れません。 iconv の実装も何種類かあり、
     OS によっては最初から添付されています。

必要なライブラリファイルの名称を、C コンパイラに指定してやります。 加え
て、ファイルの置かれているディレクトリ位置を、C コンパイラに教える必要
があるかも知れません。 一般に UNIX の C コンパイラでは、`-L' オプション
でディレクトリ位置を指定し、`-l' オプションでライブラリのファイル名を
指定します。

     cc sample.o -L/usr/local/lib -leb -lz -lintl -liconv

ただし、共有ライブラリをリンクする場合は、実行時におけるライブラリの検
索パスも合わせて指定する必要があるかも知れません。

     cc sample.o -R/usr/local/lib -L/usr/local/lib -leb -lz -lintl -liconv

   C コンパイラの使い方に関しての詳細は、 C
コンパイラのマニュアルを参照して下さい。


File: eb-ja.info,  Node: Compilation with Autoconf,  Prev: Compilation Simple Way,  Up: Compilation

Autoconf を併用したコンパイル方法
=================================

   作業の前に、Autoconf, Automake, Libtool は、あらかじめインストールし
ておいて下さい。 Autoconf はバージョン 2.50 以降が必要です。

   まず、アプリケーションプログラムの `configure.ac' (もしくは
`configure.in') に、次の行を加えます。

     eb_LIB_EB3

マクロ `eb_LIB_EB3' は、EB ライブラリの使用に必要な一切のチェックを行
い、さらに `configure' に次のオプションを追加します。

       --with-eb-conf=FILE     eb.conf file is FILE [SYSCONFDIR/eb.conf]

`eb.conf' は、EB ライブラリをインストールしたときの情報を記録したファ
イルで、ライブラリと一緒にインストールされます。 `eb_LIB_EB3' はこのフ
ァイルを読み込んで、C コンパイラに渡さなければいけないオプションなどの
情報を得ます。 `--eb-conf-file' は、`eb.conf' のファイル名を明示的に指
定するオプションです。

   マクロ `eb_LIB_EB3' は、 `eb3.m4' というファイルで提供されています。
EB ライブラリを `/usr/local' にインストールし、個々のファイルのインス
トール先を変更していなければ、`/usr/local/share/eb' にインストールされ
ます。 この `eb3.m4' をソースコードの適当なディレクトリの下 (たとえば
`m4') にコピーして下さい。

   `aclocal' コマンドで `aclocal.m4' を再生成する際は、 `-I' オプション
でマクロファイルのディレクトリを指定します。

     aclocal -I m4

加えて、トップディレクトリの `Makefile.am' の中にも `aclocal' へ渡すオ
プションを書いておきます。

     ACLOCAL_AMFLAGS = -I m4

   また、ソースコードのディレクトリに Libtool パッケージがまだ用意され
ていなければ、用意します。 `libtoolize' コマンドを実行して下さい。
Libtool パッケージが、ソースコードのディレクトリにコピーされます。

     libtoolize

   最後に、コンパイルを行うディレクトリの `Makefile.am' ファイルの
`_LDFLAGS' と `INCLUDES' に、次のような値を追加します。

     program_LDFLAGS = $(EBCONF_EBLIBS) $(EBCONF_ZLIBLIBS) $(EBCONF_INTLLIBS)
     INCLUDES = $(EBCONF_EBINCS)

(`program_LDFLAGS' の `program' のところは、 アプリケーションプログラム
の実際のコマンド名にします。)


File: eb-ja.info,  Node: Init and Exit,  Next: EB_Book,  Prev: Compilation,  Up: Top

ライブラリの初期化と後始末
**************************

   この章からは、 EB
ライブラリのプログラミングについての解説になります。

   まず、アプリケーションプログラムから EB ライブラリを利用するには、
最初にライブラリを初期化する必要があります。

   ライブラリの初期化を行うには、`eb_initialize_library()' という関数
を呼び出します。

     if (eb_initialize_library() != EB_SUCCESS) {
         printf("eb_initialize_library() failed\n");
         exit(1);
     }

   同様に、ライブラリを使い終わったら、`eb_finalize_library()' という
関数を呼び出して後始末をします。

     eb_finalize_library();

* Menu:

* Init and Exit Sample::        サンプルプログラム
* Init and Exit Functions::     関数の詳細


File: eb-ja.info,  Node: Init and Exit Sample,  Next: Init and Exit Functions,  Prev: Init and Exit,  Up: Init and Exit

サンプルプログラム
==================

     /*
      * 使用方法:
      *     initexit
      * 例:
      *     initexit
      * 説明:
      *     EB ライブラリの初期化、後始末をしてみます。
      *     プログラムの外側から見れば、これは何の意味もない動作です。
      */
     #include "config.h"
     
     #include <stdio.h>
     #include <stdlib.h>
     
     #include <eb/eb.h>
     #include <eb/error.h>
     
     int
     main(argc, argv)
         int argc;
         char *argv[];
     {
         EB_Error_Code error_code;
     
         /* EB ライブラリを初期化。*/
         error_code = eb_initialize_library();
         if (error_code != EB_SUCCESS) {
     	fprintf(stderr, "%s: failed to initialize EB Library, %s: %s\n",
     	    argv[0], eb_error_message(error_code), argv[1]);
     	exit(1);
         }
     
         /* EB ライブラリの利用を終了。*/
         eb_finalize_library();
         exit(0);
     }


File: eb-ja.info,  Node: Init and Exit Functions,  Prev: Init and Exit Sample,  Up: Init and Exit

関数の詳細
==========

   この項で説明している関数を使うには、`eb/eb.h' を読み込んで下さい。

     #include <eb/eb.h>

 - Function: EB_Error_Code eb_initialize_library ()
     関数 `eb_initialize_library()' は、EB ライブラリを初期化します。
     アプリケーションプログラムは、EB ライブラリの他の関数を呼ぶ前に、
     必ず一回だけこの関数を呼ぶ必要があります。

     メッセージの国際化機能 (NLS) を有効にして EB ライブラリをコンパイ
     ルした場合、`eb_initialize_library()' は `bindtextdomain()' を呼
     び出します。 したがって、アプリケーションプログラムが
     `setlocale()' を呼び出すのは、この関数を呼び出す前である必要があ
     ります。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、原因を示
     すエラーコードを返します。

     ライブラリを初期化せずに、EB ライブラリの他の関数を呼んだ場合の動
     作は未定義です。 また、すでに初期化を済ませた状態で、再度
     `eb_initialize_library()' を呼んでもいけません。 呼んだ場合の動作
     は未定義です。

 - Function: void eb_finalize_library ()
     関数 `eb_finalize_library()' は、EB ライブラリを使い終わった際の
     後始末を行います。 ただし、アプリケーションプログラム側で使用した
     `EB_Book'、`EB_Hookset'、`EB_Appendix' オブジェクトの後始末は行い
     ません。 オブジェクトを後始末するには、それぞれ専用の関数
     `eb_finalize_book()'、 `eb_finalize_hookset()'、
     `eb_finalize_appendix()' を各オブジェクトに対して別途呼んでやる必
     要があります。

     ライブラリの後始末をした後は、EB ライブラリのいかなる関数も呼んで
     はいけません。 呼んだ場合の動作は未定義です。


File: eb-ja.info,  Node: EB_Book,  Next: Error Handling,  Prev: Init and Exit,  Up: Top

CD-ROM 書籍と `EB_Book' オブジェクト
************************************

   EB ライブラリでは、CD-ROM 書籍へのアクセスは、すべて `EB_Book' 型の
オブジェクトを介して行います。 したがって、ほとんどのアプリケーションプ
ログラムは、本章で記述している処理を必要とするはずです。

   本章では `EB_Book' オブジェクトの初期化、後始末といった基本的な取り
扱い方について説明します。

* Menu:

* EB_Book Explanation::         `EB_Book' オブジェクト
* EB_Book Sample::              サンプルプログラム
* EB_Book Data Types::          データ型の詳細
* EB_Book Functions::           関数の詳細


File: eb-ja.info,  Node: EB_Book Explanation,  Next: EB_Book Sample,  Prev: EB_Book,  Up: EB_Book

`EB_Book' オブジェクト
======================

   CD-ROM 書籍へアクセスするには、まず `EB_Book' 型のオブジェクトを用
意します。 同時に複数の CD-ROM 書籍にアクセスするなら、書籍一冊毎にオブ
ジェクトを作る必要があります。

     EB_Book book;

もちろん、オブジェクトの領域は、`malloc()' で確保しても構いません。

     EB_Book *book_pointer;
     
     book_pointer = (EB_Book *) malloc(sizeof(EB_Book));

   `EB_Book' オブジェクトの中身 (変数 `book' の中身および
`book_pointer' の指す領域) はまだ初期化されていませんので、次の要領で
オブジェクトを初期化します。

     eb_initialize_book(&book);
     eb_initialize_book(book_pointer);

`eb_initialize()' へ渡す引数は `EB_Book' オブジェクトへのポインタであ
って、 `EB_Book' オブジェクトそのものではないことに注意して下さい。 (EB
ライブラリの他の関数も、すべてオブジェクトをポインタで渡します。)

   CD-ROM 書籍を使うには、続いて `EB_Book' オブジェクトを CD-ROM 書籍
の実体に結び付けます。 これは、関数 `eb_bind()' によって行います。

     ＥＢ＿Ｂｏｏｋ　　　　　　　　　　　　ＣＤ−ＲＯＭ書籍
     オブジェクト　　　　　　　　　　┌────────────┐
     ┌───┐　　　　　　　　　　　│　　　　　　　　　　　　│
     │　　　┝━━━━━━━━━━━┥　／ｍｎｔ／ｃｄｒｏｍ　│
     └───┘　ｅｂ＿ｂｉｎｄ（）　│　　　　　　　　　　　　│
     　　　　　　　　　　　　　　　　└────────────┘

実際のプログラムでは、次のようにします。

     if (eb_bind(&book, "/mnt/cdrom") != EB_SUCCESS) {
         printf("eb_bind() failed\n");
         return;
     }

`eb_bind()' に渡す書籍のパス (この例では `/mnt/cdrom') は書籍のトップ
ディレクトリ、つまり `CATALOG' または `CATALOGS' ファイルのあるディレク
トリを指定します。

   `EB_Book' オブジェクトを使い終わったら、 `eb_finalize_book()' を呼ん
で後始末をします。 オブジェクトは書籍との結び付きを解かれた状態に戻り、
内部で割り当てられたメモリは解放され、開いていたファイルもすべて閉じら
れます。

     eb_finalize_book(&book);
     eb_finalize_book(book_pointer);

オブジェクトの領域を `malloc()' で確保した場合は、 `eb_finalize_bokk()'
を呼んだ後ならば、オブジェクトの領域を安全に解放することができます。

     free(book_pointer);


File: eb-ja.info,  Node: EB_Book Sample,  Next: EB_Book Data Types,  Prev: EB_Book Explanation,  Up: EB_Book

サンプルプログラム
==================

   このサンプルプログラムでは、 CD-ROM 書籍の種類を調べるために、
`eb_disc_code()' という関数を使用しています。 この関数については、 *note
関数の詳細: EB_Book Functions.。

     /*
      * 使用方法:
      *     disctype <book-path>
      * 例:
      *     disctype /cdrom
      * 説明:
      *     <book-path> で指定された CD-ROM 書籍の種類が、EB か EPWING か
      *     を調べて表示します。
      */
     #include "config.h"
     
     #include <stdio.h>
     #include <stdlib.h>
     
     #include <eb/eb.h>
     #include <eb/error.h>
     
     int
     main(argc, argv)
         int argc;
         char *argv[];
     {
         EB_Error_Code error_code;
         EB_Book book;
         EB_Disc_Code disc_code;
     
         /* コマンド行引数をチェック。*/
         if (argc != 2) {
     	fprintf(stderr, "Usage: %s book-path\n", argv[0]);
     	exit(1);
         }
     
         /* EB ライブラリと `book' を初期化。*/
         error_code = eb_initialize_library();
         if (error_code != EB_SUCCESS) {
     	fprintf(stderr, "%s: failed to initialize EB Library, %s: %s\n",
     	    argv[0], eb_error_message(error_code), argv[1]);
     	goto die;
         }
         eb_initialize_book(&book);
     
         /* `book' を書籍に結び付ける。失敗したら終了。*/
         error_code = eb_bind(&book, argv[1]);
         if (error_code != EB_SUCCESS) {
     	fprintf(stderr, "%s: failed to bind the book, %s: %s\n",
     	    argv[0], eb_error_message(error_code), argv[1]);
     	goto die;
         }
     
         /* 書籍の種類を調べて表示。*/
         error_code = eb_disc_type(&book, &disc_code);
         if (error_code != EB_SUCCESS) {
     	fprintf(stderr, "%s: failed to get disc type, %s: %s\n",
     	    argv[0], eb_error_message(error_code), argv[1]);
     	goto die;
         }
     
         if (disc_code == EB_DISC_EB) {
     	fputs("EB\n", stdout);
         } else if (disc_code == EB_DISC_EPWING) {
     	fputs("EPWING\n", stdout);
         } else {
     	fputs("unknown\n", stdout);
         }
     
         /* 書籍と EB ライブラリの利用を終了。*/
         eb_finalize_book(&book);
         eb_finalize_library();
         exit(0);
     
         /* エラー発生で終了するときの処理。*/
       die:
         eb_finalize_book(&book);
         eb_finalize_library();
         exit(1);
     }


File: eb-ja.info,  Node: EB_Book Data Types,  Next: EB_Book Functions,  Prev: EB_Book Sample,  Up: EB_Book

データ型の詳細
==============

   この節で説明しているデータ型を使うには、次のようにヘッダファイルを
読み込んで下さい。

     #include <eb/eb.h>

 - Data type: EB_Book
     `EB_Book' 型は、一冊の CD-ROM 書籍を表します。 CD-ROM 書籍へのアク
     セスは、すべてこの型のオブジェクトを介して行います。 同時に複数の
     CD-ROM 書籍にアクセスする際は、書籍一冊毎にオブジェクトを作る必要
     があります。

     `EB_Book' オブジェクトの操作は、すべて EB
     ライブラリが用意している関数で行います。 アプリケーションプログラ
     ムは、直接 `EB_Book' オブジェクトのメンバを参照したり、セットした
     りすべきではありません。

     `EB_Book' オブジェクトを使用する際は、まずそのオブジェクトに対して
     `eb_initialize_book()' を呼んで初期化しなくてはなりません。

 - Data type: EB_Disc_Code
     データ型 `EB_Disc_Code' は、CD-ROM 書籍の形式コードを表します。 現
     在のところ、次の値が定義されています。

    `EB_DISC_EB'
          電子ブック (EB, EBG, EBXA, EBXA-C, S-EBXA) であることを表しま
          す。

    `EB_DISC_EPWING'
          EPWING であることを表します。

    `EB_DISC_INVALID'
          不正な形式コード値を表します。

     この型は符合付き整数型の別名として定義されていますので、2 つのコー
     ドを 2 項演算子 `==' と `!=' で一致比較することができます。

 - Data type: EB_Character_Code
     データ型 `EB_Character_Code' は、 CD-ROM
     書籍で使用される文字コードを表します。 現在のところ、次の値が定義
     されています。

    `EB_CHARCODE_ISO8859_1'
          ISO 8859-1 (ラテン文字 1) を使用していることを表します。 電子
          ブックの EBG はこれです。

    `EB_CHARCODE_JISX0208'
          JIS X 0208 (日本語のかな漢字) を使用していることを表します。
          EBG, EBXA-C 以外の電子ブック、および EPWING
          はすべてこれです。

    `EB_CHARCODE_JISX0208_GB2312'
          JIS X 0208 (日本語のかな漢字) と GB 2312 (中国語の簡体字) を
          併用していることを表します。 電子ブックの EBXA-C
          はこれです。

    `EB_CHARCODE_INVALID'
          不正な文字コード値を表します。

     この型は符合付き整数型の別名として定義されていますので、2 つのコー
     ドを 2 項演算子 `==' と `!=' で一致比較することができます。


File: eb-ja.info,  Node: EB_Book Functions,  Prev: EB_Book Data Types,  Up: EB_Book

関数の詳細
==========

   この節で説明している関数を使うには、次のようにヘッダファイルを読み込
んで下さい。

     #include <eb/eb.h>

 - Function: void eb_initialize_book (EB_Book *BOOK)
     関数 `eb_initialize_book()' は、BOOK の指す `EB_Book' オブジェクト
     を初期化します。 `EB_Book' オブジェクトに対して EB ライブラリの他
     の関数を呼ぶ前に、 必ずそのオブジェクトを初期化しなくてはなりませ
     ん。 初期化していないオブジェクトに対して、EB ライブラリの他の関数
     を呼んだ場合の動作は未定義です。 また、すでに初期化したオブジェク
     トに対して、再度 `eb_initialize_book()' を呼んではいけません。 呼
     んだ場合の動作は未定義です。

 - Function: EB_Error_Code eb_bind (EB_Book *BOOK, const char *PATH)
     関数 `eb_bind()' は、 BOOK の指す `EB_Book' オブジェクトを、パス
     PATH にある CD-ROM 書籍に結び付けます。 パスは書籍のトップディレク
     トリ、つまり `CATALOG' あるいは `CATALOGS' ファイルの存在するディ
     レクトリでなくてはなりません。 オブジェクトがすでに書籍に結び付い
     ていた場合、その書籍との結び付きを解いてから、PATH にある書籍に結
     び付けます。

     成功すると、関数は `EB_SUCCESS' を返します。 このとき、副本は未選
     択の状態になります。 失敗すると、オブジェクトを書籍との結び付きを
     解かれた状態にして、原因を示すエラーコードを返します。

     PATH は、 `EB_MAX_PATH_LENGTH'
     バイトに収まていなくてはなりません。 さらに、PATH が相対パスのとき
     は、絶対パスに変換した結果がこの長さに収まっていなくてはなりませ
     ん。 これを超えると、`EB_ERR_TOO_LONG_FILE_NAME' を返します。

 - Function: void eb_finalize_book (EB_Book *BOOK)
     関数 `eb_finalize_book()' は、BOOK が指す `EB_Book' オブジェクトの
     後始末を行います。

     オブジェクトが割り当てて管理していたメモリはすべて解放され、 ファ
     イルディスクリプタもすべて閉じられます。 オブジェクトが書籍と結び
     付いていた場合は、結び付きが解かれます。

     後始末をしたオブジェクトに対して `eb_bind()' を呼ぶことで、 オブジ
     ェクトを再利用することができます。

 - Function: int eb_is_bound (EB_Book *BOOK)
     関数 `eb_is_bound()' は、BOOK が書籍に結び付いているかどうかを調
     べます。 結び付いていれば 1 を返し、そうでなければ 0 を返します。

 - Function: EB_Error_Code eb_path (EB_Book *BOOK const char *PATH)
     関数 `eb_path()' は、BOOK に結び付いている書籍のパスを、 PATH の指
     す領域に書き込みます。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、PATH の指
     す領域に空文字列を書き込み、原因を示すエラーコードを返します。

     BOOK は、あらかじめ書籍に結び付いている必要があります。 結びついて
     いない場合は、`EB_ERR_UNBOUND_BOOK' を返します。

     PATH に書き込むパス名のバイト数は、最長で `EB_MAX_PATH_LENGTH' に
     なります。 この長さは、末尾のナル文字を含みません。 関数が返すパス
     は正規化された形になっているので、`eb_bind()' に渡したときのもの
     と同じとは限りません。 たとえば、相対パスだった場合は、絶対パスに
     変換されます。

 - Function: EB_Error_Code eb_disc_type (EB_Book *BOOK, EB_Disc_Code
          *DISC_CODE)
     関数 `eb_disc_type()' は、BOOK のディスクの形式を DISC_CODE の指す
     領域に書き込みます。 書き込むディスクの形式の値は、`EB_Disc_Code'
     型 (*note [CD-ROM 書籍と `EB_Book' オブジェクト] データ型の詳細 :
     EB_Book Data Types.)  のいずれかの定数値です。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、 DISC_CODE
     の指す領域に `EB_DISC_INVALID' を書き込み、原因を示すエラーコード
     を返します。

     BOOK は、あらかじめ書籍に結び付いていなければなりません。 結びつい
     ていない場合は、`EB_ERR_UNBOUND_BOOK' を返します。

 - Function: EB_Error_Code eb_character_code (EB_Book *BOOK,
          EB_Character_Code *CHARACTER_CODE)
     関数 `eb_character_code()' は、 BOOK が書かれている文字コードを
     CHARACTER_CODE の指す領域に書き込みます。
     書き込む文字コードの値は、`EB_Character_Code' 型 (*note [CD-ROM 書
     籍と `EB_Book' オブジェクト] データ型の詳細 : EB_Book Data Types.)
     のいずれかの定数値です。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、
     CHARACTER_CODE の指す領域に `EB_CHARCODE_INVALID' を書き込み、原因
     を示すエラーコードを返します。

     BOOK は、あらかじめ書籍に結び付いていなければなりません。 結びつい
     ていない場合は、`EB_ERR_UNBOUND_BOOK' を返します。


File: eb-ja.info,  Node: Error Handling,  Next: Subbook,  Prev: EB_Book,  Up: Top

エラー処理
**********

   EB ライブラリの関数の呼び出しは、常に成功するとは限りません。 たとえ
ば、`EB_Book' オブジェクトを書籍に結びつける関数 `eb_bind()' には、引数
として書籍のトップディレクトリを渡しますが、 存在しないディレクトリを指
定した場合、処理は失敗に終わります。

一般にこうした事象は、ユーザが誤ったパスを指定したときに起こりますが、
メモリ不足のように、ユーザのミスが原因ではない失敗も起こりえます。

   本章では、関数の呼び出しが失敗した場合の処理について説明します。

* Menu:

* Error Code and Message::      エラーコードとエラーメッセージ
* Tolerance to Error::          エラーに対する寛容さ
* Error Data Types::            データ型の詳細
* Error Code List::             エラーコードの一覧
* Error Functions::             関数の詳細


File: eb-ja.info,  Node: Error Code and Message,  Next: Tolerance to Error,  Prev: Error Handling,  Up: Error Handling

エラーコードとエラーメッセージ
==============================

   EB ライブラリの関数の多くは、戻り値として `EB_Error_Code' 型の値を返
します。 処理が成功したときに返す値は `EB_SUCCESS' ですが、失敗したとき
はエラーの原因に応じて様々な値を返します。 このため、EB ライブラリでは
次のような `EB_SUCCESS' との比較処理がよく行われます。

     EB_Error_Code error_code;
     
     error_code = eb_bind(&book, "/mnt/cdrom");
     if (error_code != EB_SUCCESS) {
         printf("eb_bind() failed\n");
         return;
     }

   エラーコードの値は、関数 `eb_error_message()' によってエラーメッセ
ージに変換することもできます。 こうすることで、エラーの原因をアプリケー
ションプログラムのユーザにもう少し分かりやすく伝えることができます。

     error_code = eb_bind(&book, "/mnt/cdrom");
     if (error_code != EB_SUCCESS) {
         printf("eb_bind() failed, %s\n",
             eb_error_message(error_code));
         return;
     }

   `error_code' が `EB_ERR_TOO_LONG_FILENAME' にセットされていれば、次
のようなエラーメッセージが出力されます。

     too long filename

あるいは、次のように日本語のメッセージかも知れません。

     ファイル名が長すぎます

メッセージの国際化機能 (NLS) を無効にして EB ライブラリをコンパイルし
た場合は、常に英語のメッセージが返ります。 有効にした場合は、ロケールの
設定によってどちらの言語のメッセージが返るかが決まります。

   本書ではプログラムを簡潔にするために、エラー処理は最低限しか行って
いません。 けれども一般のアプリケーションプログラムでは、関数の呼び出し
が成功したかどうかを常にチェックし、処理が失敗した際はエラーメッセージ
を出力して、ユーザにエラーの原因を伝えるのが望ましいといえます。


File: eb-ja.info,  Node: Tolerance to Error,  Next: Error Data Types,  Prev: Error Code and Message,  Up: Error Handling

エラーに対する寛容さ
====================

   `EB_Book' オブジェクトは、状態に関するパラメタをいくつか持っていま
す。 オブジェクトが CD-ROM 書籍に結び付いているかどうかも、こうしたパラ
メタのうちの一つです。

   引数に `EB_Book' オブジェクトへのポインタを取る関数には、あらかじめ
オブジェクトの特定のパラメタがセットされていることを前提としているもの
もあります。 たとえば、`eb_path()' は、オブジェクトが書籍に結び付いてい
ることを前提としています。 では、もしも書籍に結び付いていないオブジェ
クトを `eb_path()' に渡したらどうなるでしょうか。

     EB_Book book;
     EB_Error_Code error_code;
     char path[EB_MAX_PATH_LENGTH + 1];
     
     eb_initialize_library();
     eb_initialize(&book);
     error_code = eb_path(&book, path);    /* どうなる? */

この場合、`eb_path()' は `EB_ERR_UNBOUND_BOOK' を返します。 EB ライブラ
リの関数は、必要なパラメタがセットされていないオブジェクトを検知して拒
絶します。

   しかしながら、参照マニュアルで明示されている場合を除いて、EB ライブ
ラリの関数は、与えられたポインタが `NULL' かどうかまでは調べません。
次のようなことをすると、プログラムを異常終了させてしまいます。

     eb_bind(NULL, "/mnt/cdrom");    /* 異常終了! */
     eb_bind(&book, NULL);           /* これも異常終了! */


File: eb-ja.info,  Node: Error Data Types,  Next: Error Code List,  Prev: Tolerance to Error,  Up: Error Handling

データ型の詳細
==============

   この節で説明しているデータ型を使うには、次のようにヘッダファイルを
読み込んで下さい。

     #include <eb/error.h>

 - Data type: EB_Error_Code
     データ型 `EB_Error_Code' は、 EB
     ライブラリのエラーコードを表します。 この型は符合付き整数型の別名
     として定義されていますので、 2 つのコードを 2 項演算子 `==' と `!='
     で一致比較することができます。

     EB ライブラリでは、全部で `EB_NUMBER_OF_ERRORS'
     個のフックコードを定義しています。 エラーコードの一覧については、
     次の節 (*note エラーコードの一覧: Error Code List.)  を参照して下
     さい。


File: eb-ja.info,  Node: Error Code List,  Next: Error Functions,  Prev: Error Data Types,  Up: Error Handling

エラーコードの一覧
==================

   この節で説明しているエラーコードを使うには、次のようにヘッダファイル
を読み込んで下さい。

     #include <eb/error.h>

 - Constant: EB_SUCCESS
     成功。 エラーは起きていない。

 - Constant: EB_ERR_MEMORY_EXHAUSTED
     EB ライブラリが `malloc()' を呼び出したが、`NULL' が返ってきた。

 - Constant: EB_ERR_TOO_LONG_FILE_NAME
     与えられた書籍のパス名が長すぎる。

 - Constant: EB_ERR_BAD_FILE_NAME
     書籍のパス名が不正である。

 - Constant: EB_ERR_BAD_DIR_NAME
     ディレクトリ名が不正である。 (EB ライブラリの内部処理用なので、 こ
     のエラーコードがアプリケーションプログラムに返ることはありません。)

 - Constant: EB_ERR_TOO_LONG_WORD
     与えられた検索語は長すぎる。

 - Constant: EB_ERR_BAD_WORD
     与えられた検索語に不正な文字が含まれている。

 - Constant: EB_ERR_EMPTY_WORD
     与えられた検索語は空である。

 - Constant: EB_ERR_FAIL_GETCWD
     `getcwd()' もしくは `getwd()' が失敗した。

 - Constant: EB_ERR_FAIL_OPEN_CAT
     EB ライブラリが、書籍のカタログファイルを開くことに失敗した。

 - Constant: EB_ERR_FAIL_OPEN_CATAPP
     EB ライブラリが、付録のカタログファイルを開くことに失敗した。

 - Constant: EB_ERR_FAIL_OPEN_TEXT
     EB ライブラリが、書籍の本文ファイルを開くことに失敗した。

 - Constant: EB_ERR_FAIL_OPEN_FONT
     EB ライブラリが、書籍の外字ファイルを開くことに失敗した。

 - Constant: EB_ERR_FAIL_OPEN_APP
     EB ライブラリが、付録ファイルを開くことに失敗した。

 - Constant: EB_ERR_FAIL_OPEN_BINARY
     EB ライブラリが、バイナリデータファイルを開くことに失敗した。

 - Constant: EB_ERR_FAIL_READ_CAT
     EB ライブラリが、書籍のカタログファイルを読み込むことに失敗した。

 - Constant: EB_ERR_FAIL_READ_CATAPP
     EB ライブラリが、付録のカタログファイルを読み込むことに失敗した。

 - Constant: EB_ERR_FAIL_READ_TEXT
     EB ライブラリが、書籍の本文ファイルを読むことに失敗した。

 - Constant: EB_ERR_FAIL_READ_FONT
     EB ライブラリが、書籍の外字ファイルを読み込むことに失敗した。

 - Constant: EB_ERR_FAIL_READ_APP
     EB ライブラリが、付録ファイルを読み込むことに失敗した。

 - Constant: EB_ERR_FAIL_READ_BINARY
     EB ライブラリが、書籍のバイナリデータファイルを読み込むことに失敗
     した。

 - Constant: EB_ERR_FAIL_SEEK_CAT
     EB ライブラリが、書籍のカタログファイルのシークに失敗した。

 - Constant: EB_ERR_FAIL_SEEK_CATAPP
     EB ライブラリが、付録のカタログファイルのシークに失敗した。

 - Constant: EB_ERR_FAIL_SEEK_TEXT
     EB ライブラリが、書籍の本文ファイルのシークに失敗した。

 - Constant: EB_ERR_FAIL_SEEK_FONT
     EB ライブラリが、書籍の外字ファイルのシークに失敗した。

 - Constant: EB_ERR_FAIL_SEEK_APP
     EB ライブラリが、付録ファイルのシークに失敗した。

 - Constant: EB_ERR_FAIL_SEEK_BINARY
     EB ライブラリが、書籍のバイナリデータファイルのシークに失敗した。

 - Constant: EB_ERR_UNEXP_CAT
     EB ライブラリが、書籍のカタログファイル内で、期待とは異なるデータ
     列を見つけた。

 - Constant: EB_ERR_UNEXP_CATAPP
     EB ライブラリが、付録のカタログファイル内で、想定外のデータ列を見
     つけた。

 - Constant: EB_ERR_UNEXP_TEXT
     EB ライブラリが、書籍の本文ファイル内で、想定外のデータ列を見つけ
     た。

 - Constant: EB_ERR_UNEXP_FONT
     EB ライブラリが、書籍の外字ファイル内で、想定外のデータ列を見つけ
     た。

 - Constant: EB_ERR_UNEXP_APP
     EB ライブラリが、付録ファイル内で、想定外のデータ列を見つけた。

 - Constant: EB_ERR_UNEXP_BINARY
     EB ライブラリが、書籍のバイナリデータファイル内で、想定外のデータ
     列を見つけた。

 - Constant: EB_ERR_UNBOUND_BOOK
     呼び出された EB ライブラリの関数は、書籍に結び付けられた `EB_Book'
     オブジェクトを引数にとるが、与えられたオブジェクトは書籍に結び付け
     られていなかった。

 - Constant: EB_ERR_UNBOUND_APP
     呼び出された EB ライブラリの関数は、付録に結び付けられた
     `EB_Appendix' オブジェクトを引数にとるが、与えられたオブジェクトは
     付録に結び付けられていなかった。

 - Constant: EB_ERR_NO_SUB
     書籍は副本を一つも持っていない。

 - Constant: EB_ERR_NO_APPSUB
     付録は副本を一つも持っていない。

 - Constant: EB_ERR_NO_FONT
     選択中の副本は、外字を一種類も持っていない。

 - Constant: EB_ERR_NO_TEXT
     選択中の副本は、本文データを持っていない。

 - Constant: EB_ERR_NO_CUR_SUB
     呼び出された関数は、副本が選択されている `EB_Book' オブジェクトを
     引数としてとるが、与えられたオブジェクトでは選択されていなかった。

 - Constant: EB_ERR_NO_CUR_APPSUB
     呼び出された関数は、副本が選択されている `EB_Appendix' オブジェク
     トを引数にとるが、与えられたオブジェクトでは選択されていなかった。

 - Constant: EB_ERR_NO_CUR_FONT
     呼び出された関数は、外字が選択されている `EB_Book' オブジェクトを
     引数にとるが、与えられたオブジェクトでは選択されていなかった。

 - Constant: EB_ERR_NO_CUR_BINARY
     呼び出された関数は、バイナリデータの読み込み要求をセットしている
     `EB_Book' オブジェクトを引数にとるが、与えられたオブジェクトでは
     セットされていなかった。

 - Constant: EB_ERR_NO_SUCH_SUB
     `EB_Book' オブジェクトと副本コードが関数に与えられたが、 `EB_Book'
     オブジェクトに結び付けられている書籍は、その副本コードに一致する
     副本を持っていない。

 - Constant: EB_ERR_NO_SUCH_APPSUB
     `EB_Appendix' オブジェクトと副本コードが関数に与えられたが、
     `EB_Appendix' オブジェクトに結び付けられている付録は、その副本コー
     ドに一致する副本を持っていない。

 - Constant: EB_ERR_NO_SUCH_FONT
     `EB_Book' オブジェクトと外字の縦のサイズが関数に与えられたが、
     `EB_Book' オブジェクトに結びつけられていた書籍で選択中の副本は、
     そのサイズの外字を持っていない。

 - Constant: EB_ERR_NO_SUCH_CHAR_BMP
     `EB_Book' オブジェクトと文字番号が関数に与えられたが、`EB_Book' オ
     ブジェクトに結び付けられていた書籍で選択中の副本は、その番号の外字
     のビットマップデータを持っていない。

 - Constant: EB_ERR_NO_SUCH_CHAR_TEXT
     `EB_Appendix' オブジェクトと文字番号が関数に与えられたが、
     `EB_Appendix'
     オブジェクトに結び付けられている付録で選択中の副本は、 その番号の
     外字の代替文字列を持っていない。

 - Constant: EB_ERR_NO_SUCH_SEARCH
     選択中の副本は、指定された検索メソッドを持っていないので、検索は行
     えない。

 - Constant: EB_ERR_NO_SUCH_HOOK
     不正なフックコードが関数に渡された。

 - Constant: EB_ERR_NO_SUCH_BINARY
     指定された位置に、指定された形式のバイナリデータは存在しない。

 - Constant: EB_ERR_DIFF_CONTENT
     アプリケーションプログラムからテキストデータの取得を要求されたが、
     指定されたテキストデータの種類が、前回リクエストされたときと一致
     していない。

 - Constant: EB_ERR_NO_PREV_SEARCH
     `eb_hit_list()' が呼び出されたが、アプリケーションプログラムから
     前もって検索のリクエストがなされていない。

 - Constant: EB_ERR_NO_SUCH_MULTI_ID
     `EB_Book'
     オブジェクトと複合検索コードが関数に渡されたが、結び付けられた書籍
     で選択中の副本は、そのコードに一致する複合検索を持っていない。

 - Constant: EB_ERR_NO_SUCH_ENTRY_ID
     `EB_Book' オブジェクトと複合検索エントリコードが関数に渡されたが、
     結び付けられた書籍で選択中の副本は、そのエントリコードに一致する
     複合検索エントリを持っていない。

 - Constant: EB_ERR_TOO_MANY_WORDS
     アプリケーションプログラムから条件検索もしくは複合検索の検索をリク
     エストされたが、検索語の個数が多すぎる。

 - Constant: EB_ERR_NO_WORD
     アプリケーションプログラムから条件検索もしくは複合検索の検索をリク
     エストされたが、検索語がすべて空である。

 - Constant: EB_ERR_NO_CANDIDATES
     `eb_multi_entry_candidates()' が呼び出されたが、 指定された複合検
     索エントリは、検索語の候補一覧データを持っていない。

 - Constant: EB_ERR_END_OF_CONTENT
     `eb_forward_text()' あるいは `eb_backward_text()' で本文の頭出し
     を行おうとしたが、すでに本文の末尾ないし先頭に達していて、それ以
     上先に進むことができなかった。

 - Constant: EB_ERR_NO_PREV_SEEK
     あらかじめ `eb_seek_text()' でシークを行っていない状態で、 テキス
     トデータの読み込みや頭出しを行おうとした。



File: eb-ja.info,  Node: Error Functions,  Prev: Error Code List,  Up: Error Handling

関数の詳細
==========

   この節で説明している関数を使うには、次のようにヘッダファイルを読み込
んで下さい。

     #include <eb/error.h>

 - Function: const char * eb_error_string (EB_Error_Code ERROR_CODE)
     関数 `eb_error_string()' は、エラーコード ERROR_CODE を文字列に変
     換したものを返します。 文字列の文字コードは、ASCII になります。 た
     とえば、エラーコード値 `EB_SUCCESS' を渡すと文字列 `"EB_SUCCESS"'
     を返します。 未知のエラーコードを渡したときは、`"EB_ERR_UNKNOWN"'
     を返します。

 - Function: const char * eb_error_message (EB_Error_Code ERROR_CODE)
     関数 `eb_error_message()' は、エラーコード ERROR_CODE に対応した
     メッセージを文字列にして返します。 関数の返すメッセージは、英語か
     日本語になります。

     国際化機能を有効にして EB ライブラリをコンパイルしていない場合は、
     常に英語のメッセージを返します。 このときのメッセージの文字コード
     は、ASCII になります。

     メッセージの国際化機能 (NLS) を有効にして EB ライブラリをコンパイ
     ルした場合は、ロケールの設定に応じてどちらの言語のメッセージを返
     すのかが決まります。 また、 GNU gettext バージョン 0.36 以降では
     iconv() と連携することにより、 メッセージの文字コードもロケールに
     応じて変化します。 gettext が iconv() との連携を行わなければ、英語
     のメッセージは ASCII、 日本語のメッセージは日本語 EUC になります。
     この関数の呼び出しによって、 gettext
     のテキストドメインの設定は変化しません。

     未知のエラーコードを渡したときに返すメッセージは、 英語では
     `"unknown error"'、日本語では `"未知のエラーです"' になります。


File: eb-ja.info,  Node: Subbook,  Next: Search,  Prev: Error Handling,  Up: Top

副本
****

   紙に印刷された本では別々の書籍になっているものでも、電子ブックや
EPWING では 1 枚の CD-ROM にまとめることができます。

   たとえば、ある CD-ROM 書籍は、国語辞書、英々辞典、百科事典という 3
つの (印刷された本で言うところの)
「書籍」を持っていることもあり得ます。 紛らわしさを避けるために、EB ラ
イブラリではここで言う「書籍」のことを "副本 (subbook)"
と呼んでいます。

     　　　ＣＤ−ＲＯＭ書籍
     ┌─────────────┐
     │　副本０：　［国語辞典］　│
     │　副本１：　［英々辞典］　│
     │　副本２：　［百科事典］　│
     └─────────────┘

CD-ROM 書籍では、それぞれの副本はそれ自体が独立した書籍になっています。
また、副本のデータも、副本毎に別々のファイルに収められています。 したが
って、EB ライブラリでも、アプリケーションプログラムの主要な処理である
単語の検索や本文データの取得などは、すべて副本単位で行うようになってい
ます。

   本章では、EB ライブラリでの副本の扱い方について説明します。

* Menu:

* Subbook Code::                副本コード
* Current Subbook::             選択中の副本
* Subbook Sample::              サンプルプログラム
* Subbook Data Types::          データ型の詳細
* Subbook Functions::           関数の詳細


File: eb-ja.info,  Node: Subbook Code,  Next: Current Subbook,  Prev: Subbook,  Up: Subbook

副本コード
==========

EB ライブラリでは、それぞれの副本に対して "副本コード (subbook code)"
を割り当てます。 このコードは EB ライブラリが副本を識別するために用いま
すので、個々の副本コードは、書籍内で同じものがないようになっています。

   以下のソースコードは、`eb_subbook_list()' という関数の使用例です。
この関数は、書籍内のすべての副本の副本コードを取得することができます。

     /* `book' が `EB_Book' のオブジェクトで、すでに書籍に結び付け
      * られていると仮定しています。*/
     EB_Subbook_Code sub_codes[EB_MAX_SUBBOOKS];
     int sub_count;
     
     if (eb_subbook_list(&book, sub_codes, &sub_count)
         != EB_SUCCESS) {
         printf("eb_subbook_list() failed\n");
         return;
     }

`eb_subbook_list()' が成功すると、書籍内のすべての副本コードが配列
`sub_codes[]' に格納されます。 配列の先頭の副本コードは `sub_codes[0]'
と表され、次のコードは `sub_codes[1]'、という具合になります。 副本の個
数は、`sub_count' に格納されます。

   個々の副本には、必ず題名が付けられています。 先頭の副本
(`sub_codes[0]') の題名は、次のようにして得ることができます。

     char title[EB_MAX_TITLE_LENGTH + 1];
     
     if (eb_subbook_title2(&book, sub_codes[0], title)
         != EB_SUCCESS) {
         printf("eb_subbook_title2() failed\n");
         return;
     }

`eb_subbook_title2()' の呼び出しが成功すると、`title' に題名を表す文字
列が格納されます。

   蛇足ですが、 (副本ではなく) CD-ROM の題名を取得する関数はありません。
なぜなら、題名を示すデータが CD-ROM の中には何処にもないからです。


File: eb-ja.info,  Node: Current Subbook,  Next: Subbook Sample,  Prev: Subbook Code,  Up: Subbook

選択中の副本
============

   `EB_Book' オブジェクトは、結びつけられた CD-ROM 書籍の中の任意の副
本から一つ選んで、"選択中の副本 (current subbook)" として指定すること
ができます。 複数の副本を、同時に選択することはできません。 単語の検索
や、本文データの取得など、ほとんどの操作は、選択中の副本に対してだけ行
えます。

`eb_bind()' で `EB_Book' オブジェクトを書籍に結び付けた直後は、いずれ
の副本も選択されていない状態になっています。

     ＥＢ＿Ｂｏｏｋ　　　　　　　　　ＣＤ−ＲＯＭ書籍
     オブジェクト
     ┌────┐　　　　　　　┌─────────────┐
     │選択中　│　　　　　　　│　副本０：　［国語辞典］　│
     │の副本　│　　　　　　　│　副本１：　［英々辞典］　│
     │＜なし＞│　　　　　　　│　副本２：　［百科事典］　│
     └────┘　　　　　　　└─────────────┘

   副本の選択を行うには、関数 `eb_set_subbook()' を使用します。
`eb_set_subbook()' は、引数として渡された副本コードにしたがって副本を
選択します。 以下は、先頭の副本 (`sub_codes[0]')
を選択する場合の例です。

     /* `book' が `EB_Book' のオブジェクトで、すでに書籍に結び付け
      * られていると仮定しています。*/
     EB_Subbook_Code sub_codes[EB_MAX_SUBBOOKS];
     int sub_count;
     
     if (eb_subbook_list(&book, sub_codes, &sub_count)
         != EB_SUCCESS) {
         printf("eb_subbook_list() failed\n");
         return;
     }
     if (eb_set_subbook(&book, sub_codes[0]) != EB_SUCCESS) {
         printf("eb_subbook_list() failed\n");
         return;
     }

成功すると、次のように副本が選択された状態になります。

     ＥＢ＿Ｂｏｏｋ　　　　　　　　　ＣＤ−ＲＯＭ書籍
     オブジェクト
     ┌────┐　　　　　　　┌─────────────┐
     │選択中　│　　┏━━━━┿━副本０：　［国語辞典］　│
     │の副本　│　　┃　　　　│　副本１：　［英々辞典］　│
     │　＊━━┿━━┛　　　　│　副本２：　［百科事典］　│
     └────┘　　　　　　　└─────────────┘


File: eb-ja.info,  Node: Subbook Sample,  Next: Subbook Data Types,  Prev: Current Subbook,  Up: Subbook

サンプルプログラム
==================

     /*
      * 使用方法:
      *     subbook <book-path>
      * 例:
      *     subbook /cdrom
      * 説明:
      *     <boook-path> で指定され CD-ROM 書籍に含まれているすべての副本の
      *     題名を表示します。
      */
     #include "config.h"
     
     #include <stdio.h>
     #include <stdlib.h>
     
     #include <eb/eb.h>
     #include <eb/error.h>
     
     int
     main(argc, argv)
         int argc;
         char *argv[];
     {
         EB_Error_Code error_code;
         EB_Book book;
         EB_Subbook_Code subbook_list[EB_MAX_SUBBOOKS];
         int subbook_count;
         char title[EB_MAX_TITLE_LENGTH + 1];
         int i;
     
         /* コマンド行引数をチェック。*/
         if (argc != 2) {
     	fprintf(stderr, "Usage: %s book-path\n", argv[0]);
     	exit(1);
         }
     
         /* EB ライブラリと `book' を初期化。*/
         error_code = eb_initialize_library();
         if (error_code != EB_SUCCESS) {
     	fprintf(stderr, "%s: failed to initialize EB Library, %s: %s\n",
     	    argv[0], eb_error_message(error_code), argv[1]);
     	goto die;
         }
         eb_initialize_book(&book);
     
         /* 書籍を `book' に結び付ける。*/
         error_code = eb_bind(&book, argv[1]);
         if (error_code != EB_SUCCESS) {
     	fprintf(stderr, "%s: failed to bind the book, %s: %s\n",
     	    argv[0], eb_error_message(error_code), argv[1]);
     	goto die;
         }
     
         /* 副本の一覧を取得。*/
         error_code = eb_subbook_list(&book, subbook_list, &subbook_count);
         if (error_code != EB_SUCCESS) {
     	fprintf(stderr, "%s: failed to get the subbbook list, %s\n",
     	    argv[0], eb_error_message(error_code));
     	goto die;
         }
     
         /* 書籍に含まれている副本の題名を出力。*/
         for (i = 0; i < subbook_count; i++) {
     	error_code = eb_subbook_title2(&book, subbook_list[i], title);
     	if (error_code != EB_SUCCESS) {
     	    fprintf(stderr, "%s: failed to get the title, %s\n",
     		argv[0], eb_error_message(error_code));
     	    continue;
     	}
     	printf("%d: %s\n", i, title);
         }
     
         /* 書籍と EB ライブラリの利用を終了。*/
         eb_finalize_book(&book);
         eb_finalize_library();
         exit(0);
     
         /* エラー発生で終了するときの処理。*/
       die:
         eb_finalize_book(&book);
         eb_finalize_library();
         exit(1);
     }


File: eb-ja.info,  Node: Subbook Data Types,  Next: Subbook Functions,  Prev: Subbook Sample,  Up: Subbook

データ型の詳細
==============

   この節で説明しているデータ型を使うには、次のようにヘッダファイルを
読み込んで下さい。

     #include <eb/eb.h>

 - Data type: EB_Subbook_Code
     データ型 `EB_Subbook_Code' は副本コードを表します。 一冊の書籍の中
     の副本は、それぞれ一意の副本コードを持っています。 この型は符合付
     き整数型の別名として定義されていますので、2 つのコードを 2 項演算
     子 `==' と `!=' で一致比較することができます。

     また、不正な副本コード値を表す `EB_SUBBOOK_INVALID' という特別な
     副本コードが定義されています。 利用可能な副本に対して、この副本コ
     ードが割り当てられることはありません。


File: eb-ja.info,  Node: Subbook Functions,  Prev: Subbook Data Types,  Up: Subbook

関数の詳細
==========

   この節で説明している関数を使うには、次のようにヘッダファイルを読み込
んで下さい。

     #include <eb/eb.h>

 - Function: EB_Error_Code eb_load_all_subbooks (EB_Book *BOOK)
     関数 `eb_load_all_subbooks()' は、BOOK 内のすべての副本を初期化し
     ます。 通常、副本の初期化は、その副本が初めて選択されたときに自動
     的に行われますが、 この関数は初期化を前倒しで行います。 初期化の対
     象となるのは、この関数を呼び出した時点でまだ初期化していないすべ
     ての副本です。 この関数は、スタンドアロンで動作するサーバアプリケ
     ーションなどで有効です。 クライアントからの接続を受ける前にこの関
     数を呼ぶことで、副本の初期化のためにクライアントを待たせなくて済
     みます。

     初期化の対象となったすべての副本の初期化に成功すれば、関数は
     `EB_SUCCESS' を返します。 一冊でも初期化に失敗した場合は、残りの副
     本の初期化を諦め、原因を示すエラーコードを返します。

     BOOK は、あらかじめ書籍に結び付けられていなくてはなりません。 結び
     ついていない場合は、`EB_ERR_UNBOUND_BOOK' を返します。

     この関数を呼び出すと、 BOOK
     は、副本を選択していない状態になります。

 - Function: EB_Error_Code eb_subbook_list (EB_Book *BOOK,
          EB_Subbook_Code *SUBBOOK_LIST, int *SUBBOOK_COUNT)
     関数 `eb_subbook_list()' は、 BOOK 内のすべて副本の副本コードを
     `EB_Subbook_Code' 型の配列にして、SUBBOOK_LIST の指す領域に書き込
     みます。 配列は、最大で `EB_MAX_SUBBOOKS' 個の要素を持ちます。 加
     えて、書籍が収録している副本の個数を SUBBOOK_COUNT の指す領域に書
     き込みます。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、
     SUBBOOK_COUNT の指す領域に 0 を書き込み、原因を示すエラーコードを
     返します。

     BOOK は、あらかじめ書籍に結び付けられていなくてはなりません。 結び
     ついていない場合は、`EB_ERR_UNBOUND_BOOK' を返します。

 - Function: EB_Error_Code eb_subbook (EB_Book *BOOK, EB_Subbook_Code
          *SUBBOOK_CODE)
     関数 `eb_subbook()' は、 BOOK が選択中の副本の副本コードを
     SUBBOOK_CODE の指す領域に書き込みます。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、
     SUBBOOK_CODE の指す領域に `EB_SUBBOOK_INVALID' を書き込み、原因を
     示すエラーコードを返します。

     あらかじめ、BOOK はいずれかの副本を選択していなくてはなりません。
     選択していない場合は、`EB_ERR_NO_CUR_SUB' を返します。

 - Function: EB_Error_Code eb_subbook_title (EB_Book *BOOK, char *TITLE)
     関数 `eb_subbook_title()' は、BOOK が選択中の副本の題名を TITLE の
     指す領域に文字列として書き込みます。 題名の文字列の長さは、最長で
     `EB_MAX_TITLE_LENGTH' バイトです。 この長さは、末尾のナル文字を含
     みません。

     書籍の文字コード (*note [CD-ROM 書籍と `EB_Book' オブジェクト] デ
     ータ型の詳細: EB_Book Data Types.)  が `EB_CHARCODE_ISO8859_1' な
     ら、題名を表す文字列は ISO 8859-1 になり、それ以外の文字コードな
     ら日本語 EUC になります。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、TITLE の
     指す領域に空文字列を書き込み、原因を示すエラーコードを返します。

     あらかじめ、BOOK 内のいずれかの副本が選択されていなくてはなりませ
     ん。 選択していない場合は、`EB_ERR_NO_CUR_SUB' を返します。

 - Function: EB_Error_Code eb_subbook_title2 (EB_Book *BOOK,
          EB_Subbook_Code SUBBOOK_CODE, char *TITLE)
     `eb_subbook_title()' と似ていますが、選択中の副本ではなく、引数
     SUBBOOK_CODE で指定された副本の題名を書き込む点が異なります。

     BOOK は副本を選択していなくても構いませんが、あらかじめ書籍に結び
     付けられていなければなりません。 結びついていない場合は、
     `EB_ERR_UNBOUND_BOOK' を返します。

 - Function: EB_Error_Code eb_subbook_directory (EB_Book *BOOK, char
          *DIRECTORY)
     関数 `eb_subbook_directory()' は、BOOK 内で現在選択中の副本のデー
     タファイルを収めたディレクトリ名を、DIRECTORY の指す領域に書き込
     みます。

     ディレクトリ名の文字列の長さは、最長で
     `EB_MAX_DIRECTORY_NAME_LENGTH' バイトです。 この長さに、末尾のナル
     文字は含みません。 ディレクトリ名は ASCII の数字、英小文字、アンダ
     ースコアで構成されます。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、 DIRECTORY
     の指す領域に空文字列を書き込み、原因にを示すエラーコードを返しま
     す。

     あらかじめ、BOOK 内のいずれかの副本が選択されていなくてはなりませ
     ん。 選択していない場合は、`EB_ERR_NO_CUR_SUB' を返します。

 - Function: EB_Error_Code eb_subbook_directory2 (EB_Book *BOOK,
          EB_Subbook_Code SUBBOOK_CODE, char *DIRECTORY)
     `eb_subbook_directory()' と似ていますが、選択中の副本ではなく、引
     数 SUBBOOK_CODE で指定された副本のディレクトリ名を書き込む点が異
     なります。

     BOOK は副本を選択していなくても構いませんが、あらかじめ書籍に結び
     付けられていなければなりません。 結びついていない場合は、
     `EB_ERR_UNBOUND_BOOK' を返します。

 - Function: EB_Error_Code eb_set_subbook (EB_Book *BOOK,
          EB_Subbook_Code CODE)
     関数 `eb_set_subbook()' は、BOOK の副本 CODE を選択します。 すで
     に副本を選択していた場合は、いったん未選択の状態にしてから副本
     SUBBOOK_CODE を選択します。

     成功すると、関数は `EB_SUCCESS' を返します。 このとき、外字は未選
     択の状態となり、検索、テキストデータの読み込み、 バイナリデータの
     読み込みについての状態記録は、すべてリセットされます。
     失敗すると、副本を未選択の状態にして、原因を示すエラーコードを返し
     ます。

     あらかじめ、BOOK は書籍に結び付けられていなければなりません。 結び
     ついていない場合は、`EB_ERR_UNBOUND_BOOK' を返します。

 - Function: void eb_unset_subbook (EB_Book *BOOK)
     関数 `eb_unset_subbook()' は、BOOK が選択している副本を未選択の状
     態にします。 BOOK が書籍に結び付いていないか、副本が選択されていな
     い場合は、何もしません。


File: eb-ja.info,  Node: Search,  Next: Text Data,  Prev: Subbook,  Up: Top

検索
****

   CD-ROM 書籍において、検索は非常に重要な機能です。 EB
ライブラリでは、次のような検索メソッドが利用できます。

   * 前方一致検索 (word search)

   * 後方一致検索 (end-word search)

   * 完全一致検索 (exact-word search)

   * 条件検索 (keyword search)

   * 複合検索 (multi search)

   ただし、すべての CD-ROM 書籍、すべての副本で、ここに挙げたすべての
検索メソッドが利用可能なわけではありません。 副本の中には、いずれの検索
メソッドも提供しないものも存在します。

   EB ライブラリでは、検索を行うことができるのは、選択中の副本に対して
だけです。

   この章では、それぞれの検索メソッドの簡単な説明と、EB ライブラリでの
扱い方について説明します。

* Menu:

* Word Search::                 前方一致、後方一致、完全一致検索
* Keyword Search::              条件検索
* Multi Search::                複合検索
* EB_Hit::                      一致エントリの情報
* Get Remained Entries::        残っているエントリの取得
* Search Data Types::           データ型の詳細
* Search Functions::            関数の詳細


File: eb-ja.info,  Node: Word Search,  Next: Keyword Search,  Prev: Search,  Up: Search

前方一致、後方一致、完全一致検索
================================

   前方一致、後方一致、完全一致検索は、いずれも一個の入力語に一致する
エントリを探し出す検索メソッドです。

   前方一致検索は、入力語と先頭部分が一致するエントリを検索します。 た
とえば、「江戸」という語は、「江戸」「江戸時代」「江戸っ子」といったエ
ントリに一致します。

   後方一致検索は、入力語と末尾が一致するエントリを検索します。 たとえ
ば、`bye' という語は、`bye'、`good bye'、`bye bye' といったエントリに
一致します。

完全一致検索は、一個の検索語と完全に一致するエントリだけを検索します。

   以下は、前方一致検索のプログラムの例です。 選択中の副本の中から、先
頭が `librar' で始まるエントリを探しています。

     /* `book' が `EB_Book' のオブジェクトで、すでに書籍に結び付け
      * られ、副本を選択中だと仮定しています。*/
     #define MAX_HITS 50
     EB_Hit hits[MAX_HITS];
     int hit_count;
     
     if (eb_search_word(&book, "librar") != EB_SUCCESS) {
         printf("eb_search_word() failed\n");
         return;
     }
     if (eb_hit_list(&book, MAX_HITS, hits, &hit_count)
         != EB_SUCCESS) {
         printf("eb_hit_list() failed\n");
         return;
     }

`eb_search_word()' は前方一致検索をリクエストする関数です。
この例では、`librar' という検索文字列を与えています。 ただし、この関数
は一致したエントリを返すことはしません。

   一致したエントリの取得は、続く `eb_hit_list()' 関数を呼び出した際に
行われます。 `eb_hit_list()' は一致したエントリの一覧を配列 `hits' の指
す領域に書き込み、見つかった一致エントリの個数を `&hit_count' の指す領
域に書き込みます。 この例では、 `eb_hit_list()' は最大で `MAX_HITS' (=
50) 個のエントリを探します。 (つまり、 50
個見つかったら検索を止めます。)

   もし、選択中の副本が英々辞典だとすると、少なくとも `library' と
`librarian' という 2 つのエントリに関する情報が得られるでしょう。 この
とき、配列 `hits[]' は次のようになっています。 (ただし、 `library' と
`librarian' エントリの順序は、 下の絵とは異なっているかも知れません。)

     ┌───────────┬───────────┬─
     │　ｌｉｂｒａｒｉａｎ　│　　ｌｉｂｒａｒｙ　　│
     └───────────┴───────────┴─
     　　　ｈｉｔｓ［０］　　　　　ｈｉｔｓ［１］

`hits' の中身については、本章の後ろの節で説明します。

   ここまでは前方一致検索の例でしたが、後方一致の場合は
`eb_search_word()' の代わりに `eb_search_endword()'
を呼ぶようにします。 後の手順はすべて同じです。

     if (eb_search_endword(&book, "nalization") != EB_SUCCESS) {
         printf("eb_search_endword() failed\n");
         return;
     }

   完全一致の場合も同様です。 `eb_search_exactword()' を呼ぶようにしま
す。 後の手順もやはり同じです。

     if (eb_search_exactword(&book, "library") != EB_SUCCESS) {
         printf("eb_search_exactword() failed\n");
         return;
     }


File: eb-ja.info,  Node: Keyword Search,  Next: Multi Search,  Prev: Word Search,  Up: Search

条件検索
========

   条件検索は、複数個の入力語にすべて適合するエントリを検索します。 た
とえば、英々辞典の条件検索では、入力語をすべて含んだ例文を検索するよう
になっているかも知れません。

   以下は、条件検索で `make', `with' という語の双方と適合するエントリ
を、選択中の副本の中から探し出すプログラムの断片です。

     /* `book' が `EB_Book' のオブジェクトで、すでに書籍に結び付け
      * られ、副本を選択中だと仮定しています。*/
     static const char *keywords[3] = {"make", "with", NULL};
     
     if (eb_search_word(&book, keywords) != EB_SUCCESS) {
         printf("eb_search_word() failed\n");
         return;
     }

条件検索を行う関数は、`eb_search_keyword()' です。 前方一致、後方一致、
完全一致検索の関数と基本的に扱い方は一緒ですが、 複数の入力語を受け付け
るようになっています。 関数には、入力語の文字列 (へのポインタ) を配列に
したものを渡します。 配列の最後には `NULL' を置き、配列の終端を明示する
必要がある点に注意して下さい。

   前方一致、後方一致、完全一致検索と同様に、`eb_search_keyword()' も
検索のリクエストを行うだけで、一致したエントリの取得は行いません。 エン
トリの取得には、やはり同様に `eb_hit_list()' 関数を使います。

     EB_Hit hits[MAX_HITS];
     int hit_count;
     
     if (eb_hit_list(&book, MAX_HITS, hits, &hit_count)
         != EB_SUCCESS) {
         printf("eb_hit_list() failed\n");
         return;
     }


File: eb-ja.info,  Node: Multi Search,  Next: EB_Hit,  Prev: Keyword Search,  Up: Search

複合検索
========

   複合検索は、条件検索と同じく、複数個の入力語にすべて適合するエントリ
を検索しますが、個々の入力語にあらかじめ題目が付けられています。

   また、前方一致、後方一致、完全一致、条件検索はすべて、各副本につき
一種類しかありませんが、複合検索だけは一つの副本の中で複数の種類が用意
されていることがあります。 たとえば、ある世界人名事典には、次のように人
名検索用と頻出用語の検索用の 2 種類の複合検索が用意されているかも知れ
ません。

     (複合検索その 1: 人名を検索する)
         入力語 0: 国・地域
         入力語 1: 時代
         入力語 2: 性別
         入力語 3: キーワード
         入力語 4: キーワード

     (複合検索その 2: 頻出用語を検索する)
         入力語 0: 用語
         入力語 1: キーワード
         入力語 2: キーワード

この例のように、個々の複合検索は、入力語の題目だけでなく、入力語の数も
まちまちです。 また、検索する際はすべての入力語を埋める必要はなく、少な
くとも一個の入力語が空でなければ、検索は成功します。

   個々の複合検索は、"複合検索コード (multi search code)" によって識別
されます。 関数 `eb_multi_search_list()' を使うと、選択中の副本で利用可
能な複合検索の一覧が得られます。

     /* `book' が `EB_Book' のオブジェクトで、すでに書籍に結び付け
      * られ、副本を選択中だと仮定しています。*/
     EB_Multi_Search_Code multi_codes[EB_MAX_MULTI_SEARCHES];
     int multi_count;
     
     if (eb_multi_search_list(&book, multi_codes, &multi_count)
         != EB_SUCCESS) {
         printf("eb_multi_search_list() failed\n");
         return;
     }

この複合検索コードは、複合検索のための関数で必要となります。 たとえば、
`eb_multi_entry_count()' は指定した複合検索の要求する入力語の個数を取
得する関数ですが、 このときの複合検索の指定には、複合検索コードを用いま
す。 以下の例では、最初の複合検索 (`multi_codes[0]') を指定しています。

     int entry_count;
     
     if (eb_multi_entry_count(&book, multi_codes[0], &entry_count)
         != EB_SUCCESS) {
         printf("eb_multi_entry_count() failed\n");
         return;
     }

さらに関数によっては、複合検索コードに加えて、何番目の入力語かも指定し
てやる必要があります。 たとえば、特定の入力語の題目を得る関数
`eb_multi_entry_label()' が、これに該当します。 0 番目の入力語 (つまり
先頭の入力語) の題目を取得するには、次のようにします。

     char label[EB_MAX_MULTI_LABEL_LENGTH + 1];
     
     if (eb_multi_entry_label(&book, multi_code[0], 0, label)
         != EB_SUCCESS) {
         printf("eb_multi_entry_label() failed\n");
         return;
     }

   複合検索を行う関数は、`eb_search_multi()' です。 使い方は条件検索と
ほぼ同じで、入力語の文字列を配列にしたものを引数として渡し、配列の最後
には `NULL' を置いて下さい。 埋められていない入力語のところには、空文字
列を置きます。

   `eb_search_multi()' も検索のリクエストを行うだけで、一致したエント
リの取得は行いません。 取得するには `eb_hit_list()' を使います。

     EB_Hit hits[MAX_HITS];
     int hit_count;
     
     if (eb_hit_list(&book, MAX_HITS, hits, &hit_count)
         != EB_SUCCESS) {
         fprintf(stderr, "an error occurs.\n");
         return;
     }

   なお、複合検索の入力語によっては "候補一覧 (candidates)" があらじめ
用意されていることがあります。 これは、入力語として有効な語をあらかじめ
列挙しておき、
アプリケーションプログラムのユーザに選択させる仕組みです。 候補一覧につ
いては、この章ではなく「テキストデータ」の章で説明します (*note 複合検
索の候補一覧: Multi Candidates.)。


File: eb-ja.info,  Node: EB_Hit,  Next: Get Remained Entries,  Prev: Multi Search,  Up: Search

一致エントリの情報
==================

   `eb_hit_list()' は、リクエストされた検索 (前方一致、後方一致、 完全
一致、条件、複合)
に一致したエントリの情報と見つかったエントリの個数を、それぞれ `EB_Hit'
型の配列領域および `int' 型の領域に書き込みます。

     /* `book' が `EB_Book' のオブジェクトで、すでに書籍に結び付け
      * られ、副本を選択中だと仮定しています。*/
     EB_Hit hits[MAX_HITS];
     int hit_count;
     
     if (eb_hit_list(&book, MAX_HITS, hits, &hit_count)
         != EB_SUCCESS) {
         fprintf(stderr, "an error occurs.\n");
         return;
     }

   `EB_Hit' 配列の個々の要素には、一致したエントリの "見出し (heading)"
と "本文 (text)" の開始位置が書き込まれています。

     　　　　　　　　　　　　　見出し
     　　　　　　　　　　　　┌────────────┐
     　ＥＢ＿Ｈｉｔ　　　┏━┿ｌｉｂｒａｒｉａｎ　ｎ．│
     ┌───────┐　┃　└────────────┘
     │ｈｅａｄｉｎｇ┿━┛　　本文
     │　　　　　　　│　　　┌────────────────────┐
     │　　　ｔｅｘｔ┿━━━┿ｌｉｂｒａｒｉａｎ　　　　　　　　　　　│
     └───────┘　　　│ｎ．（１）Ａ　ｐｅｒｓｏｎ　ｗｈｏ　ｉｓ│
     　　　　　　　　　　　　│ａ　ｓｐｅｃｉａｌｉｓｔ　ｉｎ　　　　　│
     　　　　　　　　　　　　│ｌｉｂｒａｒｙ　ｗｏｒｋ．（２）．．．　│
     　　　　　　　　　　　　└────────────────────┘

見出しと本文についてのより詳しい解説と取得方法については、 *note テキス
トデータ: Text Data.。


File: eb-ja.info,  Node: Get Remained Entries,  Next: Search Data Types,  Prev: EB_Hit,  Up: Search

残っているエントリの取得
========================

   前に述べたように、`eb_hit_list()' を呼び出すときは、適合するエント
リを最大で何個まで探すのかを引数で指定します。 また、`eb_hit_list()' は
処理が成功すると、実際に見つかったエントリの数をアプリケーションプログ
ラムに教えます。

     error_code = eb_hit_list(&book, MAX_HITS, hits, &hit_count);
     if (error_code == EB_SUCCESS)
         printf("%d entries found\n", hit_count);

指定した最大個数よりも多くの適合エントリが副本に存在している場合は、
`eb_hit_list()' を繰り返し呼び出すことで、残りのエントリを取得すること
ができます。

     for (;;) {
         if (eb_hit_list(&book, MAX_HITS, hits, &hit_count)
             != EB_SUCCESS) {
             fprintf(stderr, "an error occurs.\n");
             return;
         }
         if (hit_count == 0)
             break;
         /* 取得した適合エントリの処理 */
     }

適合エントリがもう残っていなければ、`eb_hit_list()' は `&hit_count' の
指す領域に 0 を書き込んで、`EB_SUCCESS' を返します。

   ただし、途中で `eb_hit_list()' が失敗すると (`EB_SUCCESS' 以外の値を
返すと)、検索リクエストに関する状態記録はリセットされるため、 適合エン
トリの取得をそれ以上続けることはできません。


File: eb-ja.info,  Node: Search Data Types,  Next: Search Functions,  Prev: Get Remained Entries,  Up: Search

データ型の詳細
==============

   この節で説明しているデータ型を使うには、次のようにヘッダファイルを
読み込んで下さい。

     #include <eb/eb.h>

 - Data type: EB_Hit
     `EB_Hit' は、検索に適合したエントリの情報を格納するためのデータ型
     です。 内部構造は、次のように定義されています。

          typedef struct EB_Hit_Struct EB_Hit;
          
          struct EB_Hit_Struct {
              EB_Position heading;  /* 見出しの位置 */
              EB_Position text;     /* 本文の位置   */
          };

     アプリケーションプログラムは、直接 `EB_Hit' オブジェクトのメンバ
     を参照したり、セットしたりしても構いません。

 - Data type: EB_Position
     データ型 `EB_Position' は、副本のデータの位置を表します。 内部構造
     は、次のように定義されています。

          typedef struct EB_Position_Struct EB_Position;
          
          struct EB_Position_Struct {
              int page;     /* ページ番号 */
              int offset;   /* ページ内のオフセット */
          };

     ページ番号は 1 から始まり、ページ内のオフセットは 0 〜 2047 の範囲
     となります。 ただし、アプリケーションプログラムを作成する上で、こ
     のことを覚えておく必要はありません。

     アプリケーションプログラムは、直接 `EB_Position' オブジェクトのメ
     ンバを参照したり、セットしたりしても構いません。

 - Data type: EB_Muti_Search_Code
     データ型 `EB_Multi_Search_Code' は複合検索コードを表します。 副本
     に用意されている複合検索は、それぞれ一意の複合検索コードを持って
     います。 この型は符合付き整数型の別名として定義されていますので、 2
     つのコードを 2 項演算子 `==' と `!='
     で一致比較することができます。

     また、不正な複合検索コード値を表す `EB_MULTI_INVALID'
     という特別な副本コードが定義されています。 利用可能な複合検索に対
     して、この複合検索コードが割り当てられることはありません。


File: eb-ja.info,  Node: Search Functions,  Prev: Search Data Types,  Up: Search

関数の詳細
==========

   この節で説明している関数を使うには、次のようにヘッダファイルを読み込
んで下さい。

     #include <eb/eb.h>

 - Function: int eb_have_word_search (EB_Book *BOOK)
 - Function: int eb_have_endword_search (EB_Book *BOOK)
 - Function: int eb_have_exactword_search (EB_Book *BOOK)
     関数 `eb_have_word_search()' は、BOOK が選択中の副本で前方一致検
     索メソッドが利用可能どうかを調べます。 同様に
     `eb_have_endword_search()' は後方一致検索メソッドについて、
     `eb_have_exactword_search()' は完全一致検索メソッドについて利用可
     能どうかを調べます。

     利用可能なら 1 を返します。 メソッドを持っていないか、そもそも副本
     が選択されていない場合は 0 を返します。

 - Function: int eb_have_keyword_search (EB_Book *BOOK)
     関数 `eb_have_keyword_search()' は、BOOK が選択中の副本で条件検索
     メソッドが利用可能どうかを調べます。

     利用可能なら 1 を返します。 メソッドを持っていないか、そもそも副本
     が選択されていない場合は 0 を返します。

 - Function: int eb_have_multi_search (EB_Book *BOOK)
     関数 `eb_have_multi_search()' は、BOOK が選択中の副本で複合検索メ
     ソッドが利用可能どうかを調べます。

     最低 1 種類でも利用可能なら 1 を返します。 メソッドを持っていない
     か、そもそも副本が選択されていない場合は 0 を返します。

 - Function: EB_Error_Code eb_multi_search_list (EB_Book *BOOK,
          EB_Multi_Search_Code *MULTI_LIST, int *MULTI_COUNT)
     関数 `eb_multi_search_list()' は、BOOK が選択中の副本に用意されて
     いる複合検索を調べ、複合検索コードの一覧を `EB_Multi_Search_Code'
     型の配列にして、MULTI_LIST の指す領域に書き込みます。 配列は、最大
     で `EB_MAX_MULTI_SEARCHES' 個の要素を持ちます。 加えて、複合検索の
     種類数を MULTI_COUNT の指す領域に書き込みます。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、
     SUBBOOK_COUNT の指す領域に 0 を書き込み、原因を示すエラーコードを
     返します。

     あらかじめ、BOOK はいずれかの副本を選択していなくてはなりません。
     選択していない場合は、`EB_ERR_NO_CUR_SUB' を返します。

 - Function: EB_Error_Code eb_multi_entry_count (EB_Book *BOOK,
          EB_Multi_Search_Code MULTI_ID, int *ENTRY_COUNT)
     関数 `eb_multi_search_list()' は、BOOK が選択中の副本に用意されて
     いる複合検索 MULTI_ID について調べ、入力語の個数を ENTRY_COUNT の
     指す領域に書き込みます。

     成功すると、関数は `EB_SUCCESS' を返します。 このとき書き込まれる
     入力語の個数は、1 以上 `EB_MAX_MULTI_ENTRIES' 以下になります。 失
     敗すると、ENTRY_COUNT の指す領域には 0 を書き込み、原因を示すエラ
     ーコードを返します。

     あらかじめ、BOOK はいずれかの副本を選択していなくてはなりません。
     選択していない場合は、`EB_ERR_NO_CUR_SUB' を返します。

 - Function: EB_Error_Code eb_multi_entry_label (EB_Book *BOOK,
          EB_Multi_Search_Code MULTI_ID, int ENTRY_INDEX, char *LABEL)
     関数 `eb_multi_search_list()' は、BOOK が選択中の副本に用意されて
     いる複合検索 MULTI_ID について調べ、ENTRY_INDEX 番目の検索語の題
     目を LABEL の指す領域に書き込みます。 ENTRY_INDEX は、先頭の検索語
     を 0 番目と数えます。 題目は最長で `EB_MAX_MULTI_LABEL_LENGTH' バ
     イトになります。 この長さに、ナル文字は含みません。

     書籍の文字コード (*note [CD-ROM 書籍と `EB_Book' オブジェクト] デ
     ータ型の詳細: EB_Book Data Types.)  が `EB_CHARCODE_ISO8859_1' な
     ら、題目を表す文字列は ISO 8859-1 になり、それ以外の文字コードな
     ら日本語 EUC になります。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、LABEL の
     指す領域には空文字列を書き込み、原因を示すエラーコードを返します。

     あらかじめ、BOOK はいずれかの副本を選択していなくてはなりません。
     選択していない場合は、`EB_ERR_NO_CUR_SUB' を返します。

 - Function: int eb_multi_entry_have_candidates (EB_Book *BOOK,
          EB_Multi_Search_Code MULTI_ID, int ENTRY_INDEX)
     関数 `eb_multi_search_list()' は、BOOK が選択中の副本に用意されて
     いる複合検索 MULTI_ID について調べ、ENTRY_INDEX 番目の検索語が候
     補一覧を持っているかどうか調べます。 ENTRY_INDEX は、先頭の検索語
     を 0 番目と数えます。

     持っていれば 1 を返します。 持っていないか、そもそも副本が選択され
     ていない場合、あるいは MULTI_ID, や ENTRY_INDEX が不正な値だった場
     合は 0 を返します。

 - Function: EB_Error_Code eb_multi_entry_candidates (EB_Book *BOOK,
          EB_Multi_Search_Code MULTI_ID, int ENTRY_INDEX, EB_Position
          *POSITION)
     関数 `eb_multi_search_list()' は、BOOK が選択中の副本に用意されて
     いる複合検索 MULTI_ID について調べ、ENTRY_INDEX 番目の検索語の候
     補一覧の位置を POSITION の指す領域に書き込みます。 先頭の検索語が
     0 番目になります。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、POSITIN
     の指す領域には `eb_seek_text()'
     が必ず失敗する位置情報を書き込み、原因を示すエラーコードを返します。

     あらかじめ、BOOK はいずれかの副本を選択していなくてはなりません。
     選択していない場合は、`EB_ERR_NO_CUR_SUB' を返します。

 - Function: EB_Error_Code eb_search_word (EB_Book *BOOK, const char
          *INPUT_WORD)
 - Function: EB_Error_Code eb_search_endword (EB_Book *BOOK, const char
          *INPUT_WORD)
 - Function: EB_Error_Code eb_search_exactword (EB_Book *BOOK, const
          char *INPUT_WORD)
     関数 `eb_search_word()' は、BOOK が選択中の副本に対する前方一致検
     索をリクエストします。 同様に `eb_search_endword()' は後方一致検索
     を、 `eb_search_exactword()' は完全一致検索をリクエストします。

     検索する語は、引数 INPUT_WORD で指定します。 ただし、これらの関数
     は検索をリクエストするだけで、一致したエントリの情報を返すことは
     しません。 一致したエントリの取得には `eb_hit_list()' を使います。
     関数は、成功すると `EB_SUCCESS' を返します。 失敗すると、原因を示
     すエラーコードを返します。 失敗すると、関数を呼び出す前にリクエス
     トしていた検索の状態記録はリセットされますので、その状態のまま
     `eb_hit_list()' を呼び出しても、やはり失敗に終わります。

     書籍の文字コード (*note [CD-ROM 書籍と `EB_Book' オブジェクト] デ
     ータ型の詳細: EB_Book Data Types.)  が `EB_CHARCODE_ISO8859_1' な
     ら、関数に渡す検索語は ISO 8859-1
     で書かれていなければなりません。 それ以外の文字コードの場合は、日
     本語 EUC で書かれていなければなりません。 不正な文字番号を含んでい
     た場合、関数は `EB_ERR_BAD_WORD' を返します。

     加えて、検索語は 1 バイト以上、 `EB_MAX_WORD_LENGTH' (= 255)
     バイト以下でなければなりません。
     この長さに、ナル文字は含みません。 長すぎる場合は、
     `EB_ERR_TOO_LONG_WORD' を、 長さが 0 (空文字列) の場合は
     `EB_ERR_EMPTY_WORD' を返します。

     あらかじめ、BOOK はいずれかの副本を選択していなくてはなりません。
     選択していない場合は、`EB_ERR_NO_CUR_SUB' を返します。 なお、一致
     するエントリが最低 1 個あるかどうかは、戻り値には影響しません。

 - Function: EB_Error_Code eb_search_keyword (EB_Book *BOOK, const char
          * const INPUT_WORDS[])
 - Function: EB_Error_Code eb_search_multi (EB_Book *BOOK,
          EB_Multi_Search_Code MULTI_ID, const char * const
          INPUT_WORDS[])
     関数 `eb_search_word()' は、BOOK が選択中の副本に対する条件検索を
     リクエストします。 同様に `eb_search_multi()' は複合検索をリクエス
     トします。

     検索する語は、引数 INPUT_WORDS で指定します。 条件検索と複合検索は
     いずれも複数個の検索語を受け付けますので、検索語を配列にして渡し
     ます。 このとき、配列の末尾の要素には `NULL' を置き、配列の終端を
     明示します。

     どちらの関数も検索をリクエストするだけで、適合したエントリの情報を
     返すことはしません。 適合したエントリの取得には `eb_hit_list()' を
     使います。 関数は、成功すると `EB_SUCCESS' を返します。
     失敗すると、原因を示すエラーコードを返します。 失敗すると、関数を
     呼び出す前にリクエストしていた検索の状態記録はリセットされますの
     で、その状態のまま `eb_hit_list()' を呼び出しても、やはり失敗に終
     わります。

     書籍の文字コード (*note [CD-ROM 書籍と `EB_Book' オブジェクト] デ
     ータ型の詳細: EB_Book Data Types.)  が `EB_CHARCODE_ISO8859_1' な
     ら、関数に渡す検索語は ISO 8859-1
     で書かれていなければなりません。 それ以外の文字コードの場合は、日
     本語 EUC で書かれていなければなりません。 不正な文字番号を含んでい
     た場合、関数は `EB_ERR_BAD_WORD' を返します。

     加えて、個々の検索語は `EB_MAX_WORD_LENGTH' (= 255) バイト以下で
     なければなりません。 この長さに、ナル文字は含みません。 長すぎる場
     合は、`EB_ERR_TOO_LONG_WORD' を返します。 長さが 0 バイトの検索語
     は無視されますが、少なくとも 1 個の検索語は長さが 1 以上ないとい
     けません。 長さが 1 以上の検索語が 1 つもないときは、
     `EB_ERR_NO_WORD' を返します。

     末尾の NULL を除いた配列の要素数は、条件検索では `EB_MAX_KEYWORDS'
     以下、複合検索では `EB_MAX_MULTI_ENTRIES'
     以下でなくてはなりません。 個数が多すぎると
     `EB_ERRO_TOO_MANY_WORDS' を返します。 空文字列の要素を差し引いた個
     数ではなく、単純に渡された要素数が上限を超えているとエラーになり
     ますので、注意が必要です。

     あらかじめ、BOOK はいずれかの副本を選択していなくてはなりません。
     選択していない場合は、`EB_ERR_NO_CUR_SUB' を返します。 なお、適合
     するエントリが最低 1 個あるかどうかは、戻り値には影響しません。

 - Function: EB_Error_Code eb_hit_list (EB_Book *BOOK, int
          MAX_HIT_COUNT, EB_Hit *HIT_LIST, int *HIT_COUNT)
     関数 `eb_hit_list()' は、あらかじめ以下のいずれかの関数でリクエス
     トされた検索を実行し、適合したエントリを取得します。

        * `eb_search_word()' (前方一致検索)

        * `eb_search_endword()' (後方一致検索)

        * `eb_search_exactword()' (完全一致検索)

        * `eb_search_keyword()' (条件検索)

        * `eb_search_multi()' (複合検索)

     したがって、この関数を呼ぶ前に、上記のいずれかの関数の呼び出しに成
     功していなくてはなりません。

     `eb_hit_list()' は最大で HIT_COUNT 個の適合エントリを HIT_LIST に
     書き込みます。 書き込んだ適合エントリの数は HIT_COUNT が指す領域に
     書き込みます。 それ以上の個数の適合エントリが存在する場合、残った
     エントリの情報は、 この関数を繰り返し呼び出すことで得ることができ
     ます。

     ただし、以下に挙げた関数を呼び出すと、リクエストした検索に関する状
     態記録がリセットされますので、適合したエントリの取得は継続できな
     くなります。

        * `eb_set_subbook()'

        * `eb_unset_subbook()'

        * `eb_load_all_subbooks()'

        * `eb_bind()'

        * `eb_finalize_book()'

        * `eb_search_word()'

        * `eb_search_endword()'

        * `eb_search_exactword()'

        * `eb_search_keyword()'

        * `eb_search_multi()'

     繰り返し呼んだ場合も、適合したエントリの情報はその都度 HIT_LIST の
     先頭から書き込み、 HIT_COUNT が指す領域に書き込む値も、その回の
     `eb_hit_list()' の呼び出しで書き込んだ適合エントリの数になります。

     成功すると、この関数は `EB_SUCCESS' を返します。 たとえ適合したエ
     ントリがなくても、処理が正常に終了すれば、関数は `EB_SUCCESS' を返
     します。

     失敗すると、HIT_COUNT が指す領域に 0 を書き込み、原因を示すエラー
     コードを返します。 この場合、リクエストしていた検索の状態記録はリ
     セットされますので、 これ以上 `eb_hit_list()' を呼んで、残った適合
     エントリを取得することはできなくなります。

     あらかじめ、BOOK はいずれかの副本を選択していなくてはなりません。
     選択していない場合は、`EB_ERR_NO_CUR_SUB' を返します。 また、先に
     挙げた検索のリクエストが成功していない状態でこの関数を呼ぶと、
     `EB_ERR_NO_PREV_SEARCH' を返します。


File: eb-ja.info,  Node: Text Data,  Next: Local Character,  Prev: Search,  Up: Top

テキストデータ
**************

   テキストデータの取得は、検索と並ぶ重要な機能です。

   ここで言う "テキストデータ (text data)" は、"本文 (text body)" とい
う意味ではありません。 CD-ROM 書籍には確かに本文も存在しますが、本文と
同じデータ形式を用いて書かれたデータが数種類あります。 本書では、これ
らのデータをまとめてテキストデータと呼んでいます。 EB ライブラリが扱え
るテキストデータの種類には、次のものがあります。

   * 見出し

   * 本文

   * メニュー

   * 著作権表示

   * 複合検索の入力語の候補一覧

   本章では、これらのテキストデータの取得と加工方法について説明します。

* Menu:

* Seek and Read Text Data::     テキストデータのシークと読み込み
* Text Data Format::            テキストデータの内部形式
* Hook::                        フック
* Hook and Character Code::     フックと文字コードの関係
* Copyright Notice::            著作権表示
* Menu::                        メニュー
* Multi Candidates::            複合検索の候補一覧
* Stop Code Issue::             区切りコードの問題
* Text Data Sample::            サンプルプログラム
* Text Data Types::             データ型の詳細
* Hook Function Details::       フック関数の詳細
* Hook Code List::              フックコードの一覧
* Hookset Access Functions::    フックセット操作関数の詳細
* Builtin Hook Functions::      組み込みフック関数の詳細
* Text Data Functions::         テキストデータ操作関数の詳細


File: eb-ja.info,  Node: Seek and Read Text Data,  Next: Text Data Format,  Prev: Text Data,  Up: Text Data

テキストデータのシークと読み込み
================================

   UNIX でプログラムを組んだ経験のある方には、ファイルからデータを読み
込む際に用いる `lseek()', `read()' というシステムコールをご存じの方も
多いでしょう。

   EB ライブラリでも、テキストデータの取得には、"シーク (seek)" と "読
み込み (read)" という 2 つの操作で行います。 ただし、EB ライブラリでは
ファイルポインタやディスクリプタはなく、 `EB_Book' オブジェクトを通じて
シークや読み込みの操作を行います。

   また、シーク時に指定する位置も `off_t' 型ではなく、 `EB_Position' 型
(*note [検索] データ型の詳細: Search Data Types.)  のオブジェクトを用い
ます。 たとえば、本文の先頭位置は、`eb_text()' という関数を使って次のよ
うに取得できますが、このときも位置データは `EB_Position' 型オブジェク
トに書き込まれます。

     EB_Position position;
     
     /* 関数の処理が成功すると、`position' に本文の開始位置が
      * 書き込まれます。 */
     if (eb_text(&book, &position) != EB_SUCCESS) {
         fprintf(stderr, "an error occurs.\n");
         return;
     }

さらに、検索を行って適合したエントリの見出しや本文を読み込む際にも、 位
置情報の指定には `EB_Position' 型が使われます。 適合したエントリの情報
は、関数 `eb_hit_list()' によって `EB_Hit' という型のオブジェクトに書き
込まれますが、 `EB_Hit' 型は次のように定義されています。 (詳しくは *note
[検索] データ型の詳細: Search Data Types.。)

     typedef struct {
         EB_Position heading;   /* 見出しの位置 */
         EB_Position text;      /* 本文の位置   */
     } EB_Hit;

つまり、このときの見出しと本文の位置も、`EB_Position' 型で表現されてい
るのです。

   では、実際のプログラムを例にして、シークと読み込みを行ってみます。
まずは、シークからです。 これには関数 `eb_seek_text()' を用います。 こ
こでもやはり、位置は `EB_Position' 型で渡します。

     if (eb_seek_text(&book, &position) != EB_SUCCESS) {
         fprintf(stderr, "an error occurs.\n");
         return;
     }

データの種類 (見出し、本文 ...) によらず、テキストデータのシークはすべ
て `eb_seek_text()' で行います。

   ただし、`EB_Book' オブジェクトは、テキストデータの種類別に読み込み
位置を覚えているわけではなく、全種類のテキストデータで共有する位置情報
を一つ覚えているだけです。 たとえば、本文を読み込んだ後で、別の位置に
シークして見出しを読み込むと、 `EB_Book' は本文の読み込み位置のことは忘
れてしまいます。

   さて、シークが終わったら、データを読み込みます。 読み込もうとするテ
キストデータの種類によって、使用する関数が異なります。 見出しだけは
`eb_read_heading()' を使いますが、それ以外では `eb_read_text()' を使い
ます。

   以下は、`eb_read_text()' の使用例です。

     #define MAX_LENGTH 1000
     char buffer[MAX_LENGTH + 1];
     ssize_t text_length;
     
     if (eb_read_text(&book, NULL, NULL, NULL, MAX_LENGTH,
         text, &text_length) != EB_SUCCESS) {
         fprintf(stderr, "an error occurs.\n");
         return;
     }

成功すると、`text' にはテキストデータが、`text_length' には実際に読み
込んだバイト数が書き込まれます。 テキストは最大で `MAX_LENGTH' バイト書
き込まれます。 テキストデータはさらにナル文字で終端されますので、
`buffer' にはもう 1 バイト分の領域が必要になります。

   `eb_read_heading()' の呼び出し方も、`eb_read_text()' とまったく変わ
りません。

     if (eb_read_heading(&book, NULL, NULL, NULL, MAX_LENGTH,
         text, &text_length) != EB_SUCCESS) {
         fprintf(stderr, "an error occurs.\n");
         return;
     }

   `eb_read_text()' や `eb_read_heading()' で読み込んだテキストデータ
は平文のテキストになっていて、ナル文字で終端されています。

     printf("%s\n", text);   /* 出力してみる */

   読み込みたいテキストデータが長すぎて、 `eb_read_text()' あるいは
`eb_read_heading()'
を一回呼び出しただけでは全部読み込めなかった場合は、再度呼び出すことで
続きのデータを読み込むことができます。


File: eb-ja.info,  Node: Text Data Format,  Next: Hook,  Prev: Seek and Read Text Data,  Up: Text Data

テキストデータの内部形式
========================

   前節の例では、読み込んだテキストデータは、平文テキストになっていまし
た。 けれども、CD-ROM 書籍内に平文テキストのデータが、そのまま収録され
ているわけではありません。

   実際のテキストデータの例を、以下に示します。 左側のブロックは 16 進
数でダンプした様子で、右側はそれを基に JIS X 0208 (日本語のかな漢字) の
文字を表している部分を `[　]' という形に直したものです。

          (16進数によるダンプ)            (可能な部分をかな漢字に変換)
     1f0900011f41010026321f611f042121   1f0900011f410100[Σ]1f611f04[　]
     212721211f053e704a734a541f0a1f04   [：][　]1f05[情][報][編]1f0a1f04
     214e1f0525372530255e1f04214f2121   [［]1f05[シ][グ][マ]1f04[］][　]
     214a237323692367236d236121212370   [（][ｓ][ｉ][ｇ][ｍ][ａ][　][ｐ]
     2372236f236a236523632374214b1f05   [ｒ][ｏ][ｊ][ｅ][ｃ][ｔ][）]1f05

   右側のブロックを見ると、おおよそ平文に近い形でテキストデータが収めら
れていることが分かりますが、ところどころに「文字」ではないデータも含ま
れています。

文字ではない部分は、すべて「エスケープシーケンス」と呼ばれるものです。
エスケープシーケンスとは、テキストデータを出力する際に、改行の禁止や強
調修飾といった制御情報を伝えるための仕組みです。 16 進数の `1f' が、エ
スケープシーケンスの開始を意味します。

   参考までに、上のテキストデータで使われているエスケープシーケンスを
すべて列挙すると、次のようになります。

`1f09 0001'
     字下げ (インデント) の量を指定。 (引数が 0010 なので、字下げ量は 1
     。)

`1f41 0100'
     検索キーの開始。 (引数 0100 の意味については、JIS X 4081 に記述が
     ないため不明。)

`1f61'
     検索キーの終了。

`1f04'
     半角表示の開始。

`1f05'
     半角表示の終了。

`1f0a'
     改行

   前節のプログラムで、読み込んだデータが平文テキストになっていたのは、
実は EB ライブラリが加工処理をしたからです。 つまり、「改行」のように平
文テキストでも表現可能なエスケープシーケンスについては処理し、「検索キ
ーの開始」のように表現できないものについては無視するようにして、平文テ
キストになるように加工していたのです。

しかし、平文テキストは表現力が乏しいので、元のデータには含まれているエ
スケープシーケンスの多くを無視することになってしまいます。 HTML のよう
に、もっと表現力のある形式で出力するなら、無視せずに済むシーケンスを増
やせそうです。 では、HTML 形式でテキストデータを取得する関数が EB ライ
ブラリに用意されているかというと、残念ながらありません。

   その代わりに、かなり手間はかかりますが、自由にテキストデータを加工で
きるための仕組みが用意されています。 それが、次の節で説明する "フック
(hook)" です。 フックを使うことで、テキストデータを柔軟に加工することが
できます。


File: eb-ja.info,  Node: Hook,  Next: Hook and Character Code,  Prev: Text Data Format,  Up: Text Data

フック
======

   特に何も指定しなければ、`eb_read_text()', `eb_read_heading()' が返す
テキストデータの加工は、あらかじめ決められた通りの方法で行われます。 た
とえば、「改行」のエスケープシーケンスに対しては、`\n' を書き込むよう
になっています。

   "フック (hook)" を使うと、こうした加工方法を変えることができます。
フックは、あらかじめ決められたフック設定位置に対して、フック関数を登録
することで有効になります。 フック関数が登録されていると、
`eb_read_text()' や `eb_read_heading()' は、あらかじめ決まったやり方で
データを書き込む代わりに、フック関数を呼び出します。 呼び出されたフッ
ク関数がデータの書き込み処理を行うことで、 `eb_read_text()' や
`eb_read_heading()' から返るテキストデータが変化するというわけです。

   EB ライブラリには、多数のフック設定位置が用意されています。 各エスケ
ープシーケンスには、それぞれ専用にフックが用意されており、 それ以外にも
文字のためのフックが存在します。 (どのようなフック設定位置があるか、詳
しくは *note フックコードの一覧: Hook Code List.。)

   それぞれのフック設定位置は、"フックコード (hook code)" と呼ばれるコ
ード値で識別されます。 たとえば、前述の「改行」のエスケープシーケンスに
対応するフックコードは `EB_HOOK_NEWLINE' になります。

   アプリケーションプログラムがフックを扱うには、フックの集合である "フ
ックセット (hook set)" を用意します。 これは、EB ライブラリで利用可能な
すべてのフック設定位置に対して、どのフック関数を使うのかを記録するため
のオブジェクトです。

   では、実際にどうやってフックセットを扱うのか、説明していきましょう。
フックセットは `EB_Hookset' 型のオブジェクトで表しますので、まず
`EB_Hookset' オブジェクトを用意します。

     EB_Hookset hookset;

   `EB_Hookset' オブジェクトは、`EB_Book' オブジェクトと同様に、 使用前
に必ず初期化する必要があります。

     eb_initialize_hookset(&hookset);

   実際のフック関数は、次のようなものになります。 この例では、フック関
数の中で `eb_write_text_string()' という関数を呼び出して、`<br>' とい
う文字列をテキストデータとして書き込んでいます。

     EB_Error_Code
     hook_newline(EB_Book *book, EB_Appendix *appendix, void *container,
         EB_Hook_Code code, int argc, const unsigned int *argv) {
         eb_write_text_string(book, "<br>");
         return 0;
     }

   関数 `eb_set_hook()' を用いることで、このフック関数をフックセットに
登録することができます。 ただし、まず `EB_Hook' という型のオブジェクト
にいったんフックコードとフック関数を設定し、それを `eb_set_hook()' を
渡してやる必要があります。 ここでは、「改行」を表すエスケープシーケン
スに対して、上記のフック関数を登録してみます。

     EB_Hook hook;
     
     hook.code = EB_HOOK_NEWLINE;   # フックコードをセット
     hook.function = hook_newline;  # フック関数をセット
     eb_set_hook(&hookset, &hook);

なお、同じフック設定位置 (フックコード)
に複数回フック関数を登録しても、 有効になるのは最後に登録したものだけで
すので、注意して下さい。 フック関数として `NULL' を指定すると、登録され
ているフックが解除されます。

   関数 `eb_set_hooks()' (最後に `s' が付く) を使えば、複数のフック関
数を一度に登録できます。

     static const EB_Hook hooks[] = {
         {EB_HOOK_NEWLINE,        hook_newline},
         {EB_HOOK_SET_INDENT,     hook_set_indent},
         {EB_HOOK_WIDE_JISX0208,  hook_set_jisx0208},
         {EB_HOOK_NULL,           NULL}
     };
     
     eb_set_hooks(&hookset, &hooks);

配列の末尾を明示するために、`EB_HOOK_NULL' という特殊なフックコードを
置きます。 この点も注意して下さい。

   こうしてフック関数を登録したフックセットを、 `eb_raed_text()',
`eb_raed_heading()' への引数として渡します。 前節までの例では、`NULL'
を渡していましたが、代わりに `&hookset' を渡してみます。

     if (eb_read_text(&book, NULL, &hookset, NULL, MAX_LENGTH,
         text, &text_length) != EB_SUCCESS) {
         fprintf(stderr, "an error occurs.\n");
         return;
     }

これによって、テキストデータ中に改行を表すエスケープシーケンスがあると、
`\n' の代わりに `<br>' という文字列が書き込まれるようになります。

   `EB_Hookset' オブジェクトを使い終わったら、`eb_finalize_hookset()'
を呼んで後始末をします。

     eb_finalize_hookset(&hookset);


File: eb-ja.info,  Node: Hook and Character Code,  Next: Copyright Notice,  Prev: Hook,  Up: Text Data

フックと文字コードの関係
========================

   前節では、エスケープシーケンスに対するフックを例にとりましたが、この
他にも、EB ライブラリには文字に対するフックが用意されています。

`EB_HOOK_ISO8859_1'
     ISO 8859-1 (ラテン文字 1)
     文字へのフック。ただし制御文字を除きます。 引数として、ISO 8859-1
     の文字番号がフック関数に渡されます。

`EB_HOOK_NARROW_JISX0208'
     半角の JIS X 0208 (日本語のかな漢字) 文字へのフック。 引数として、
     日本語 EUC で表現した場合の文字番号が、フック関数に渡されます。

`EB_HOOK_WIDE_JISX0208'
     全角の JIS X 0208 (日本語のかな漢字) 文字へのフック。 引数として、
     日本語 EUC で表現した場合の文字番号が、フック関数に渡されます。

`EB_HOOK_GB2312'
     GB 2312 (中国語の簡体字) 文字へのフック。 引数として、中国語 EUC
     で表現した場合の文字番号が、フック関数に渡されます。

`EB_HOOK_NARROW_FONT'
     半角の外字へのフック。 引数として、外字の文字番号が、フック関数に
     渡されます。

`EB_HOOK_WIDE_FONT'
     半角の外字へのフック。 引数として、外字の文字番号が、フック関数に
     渡されます。

いずれも、その文字がテキストデータ中に現れる度に、フック関数が呼び出さ
れます。

   上の記述を見ても分かるように、フック関数に渡される文字番号は、書籍の
文字コードに応じて、ISO 8859-1, 日本語 EUC、中国語 EUC のいずれかの文
字コードで表現されたものになります。

   フック関数を登録しなければ、その文字番号がテキストデータとしてそのま
ま書き込まれます。

   もし、アプリケーションプログラムが、EB ライブラリの内部コードとは異
なる文字コードを使用したい場合は、これらのフックのフック関数を登録して、
コード変換処理をするのも手です。 ただし、一文字毎にフック関数が呼び出さ
れるので、相応の負荷はかかります。

   また、EBXA-C を扱うには、特別な処理が必要です。 EBXA-C では、文字コ
ードとして GB 2312 と JIS X 0208 が使われますが (*note 文字コード :
Character Code.)、 テキストデータの処理では、どちらも 0xa1a1 〜 0xfefe
にマッピングされて衝突するため、最低でもどちらか一方をフックして文字の
表現方法を変えないと、 正しく出力できません。


File: eb-ja.info,  Node: Copyright Notice,  Next: Menu,  Prev: Hook and Character Code,  Up: Text Data

著作権表示
==========

   先に記したように、テキストデータには何種類かあり、その中に "著作権表
示 (copyright notice)" というものがあります。 名前の通り、著作権表示に
関するテキストデータを収めたものです。

一般に、著作権表示は本文とはまったく独立したデータとして用意されます。
したがって、本文を先頭から末尾まで読んでみても、著作権表示はどこにも見
つかりません。

   選択中の副本について、著作権表示の開始位置を知るには `eb_copyright()'
を使います。 この関数は、副本が著作権表示を持っていなければ
`EB_ERR_NO_SUCH_SEARCH' を返しますので、著作権表示の有無も同時に分かり
ます。 (開始位置は取得せずに、有無だけを調べたいときは、
`eb_have_copyright()' という関数が使えます。)

     EB_Position position;
     EB_Error_Code err;
     
     err = eb_copyright(&book, &position);
     if (err == EB_ERR_NO_SUCH_SEARCH) {
         /* 著作権表示はない */
     } else if (err != EB_SUCCESS) {
         /* それ以外のエラー */
        return;
     }

   後は、得られた位置 (`position') にシークして、`eb_read_text()' でテ
キストデータを読み込みます。


File: eb-ja.info,  Node: Menu,  Next: Multi Candidates,  Prev: Copyright Notice,  Up: Text Data

メニュー
========

   本文とは独立したテキストデータとしては、著作権表示の他に "メニュー
(menu)" というものがあります。 メニューは、主に本文の補助となるデータを
収録しています。 代表的なものでは、「前書き (序)」「凡例」といったもの
が挙げられます。

   メニューでは「別項目参照」というエスケープシーケンスを多用して、階層
的な構造になっているのが一般的です。 このエスケープシーケンスには、参
照先のテキストの位置が記録されています。

   たとえば、ある CD-ROM 書籍のメニューが次のようになっていたとします。
この例では、メニューには 3 つの項目があります。

      * 序文
      * 表記について
      * 奥付

メニューのそれぞれの項目には、参照先があります。 テキストデータの内部表
現では、「序文」「表記について」「奥付」のそれぞれの文字列の前後に別項
目参照開始および終了エスケープシーケンスが付いた形になっています。 視
覚的に分かるように記すと、次のような形になっています。

      * <別項目参照開始シーケンス> "序文" <別項目参照終了シーケンス>
      * <別項目参照開始シーケンス> "表記" <別項目参照終了シーケンス>
      * <別項目参照開始シーケンス> "奥付" <別項目参照終了シーケンス>

   HTML の書き方を知っているなら、`a' タグと言えば分かるのではないかと
思います。

     <a href="./index-ja.html">EB ライブラリのホームページ</a>

   ただし、参照先の位置情報は終了シーケンス側に記載されますので、この点
は HTML とは逆になります。 蛇足ですが、別位置参照はメニューだけでなく、
本文でも一般的に使用されます。

   別項目参照開始および終了シーケンスに対して、それぞれフック
`EB_HOOK_BEGIN_REFERENCE' と `EB_HOOK_END_REFERENCE' が用意されていま
す。 参照先の位置情報は、終了シーケンスへのフック関数に対して、引数とし
て渡されます。 たとえば、`EB_HOOK_END_REFERENCE' へのフック関数の冒頭
では、次のようにすると良いかも知れません。

     EB_Error_Code
     hook_end_ref(EB_Book *book, EB_Appendix *appendix, void *container,
         EB_Hook_Code code, int argc, const unsigned int *argv)
     {
         EB_Position position;
     
         position.page = argv[1];    # 参照先のページ番号
         position.offset = argv[2];  # 参照先のオフセット

   参照先は、メニューの第 2 層となります。 この書籍の「奥付」の参照先を
辿ったら、次のような表記になっていました。

     ○○堂出版社新国語辞典第 2 版 (EPWING 版)
     第 1 版発行 1988年 2月
     第 2 版発行 1999年 11月
     第 2 版 (EPWING 版) 発行 2000年 2月

同様に「序文」「表記に付いて」の参照先についても、こうした文章データが
用意されていました。 図示すると、メニューの階層は次のようになります。

     　　　　　　　　　　　　┌─────┐
     第１層　　　　　　　　　│メニュー　│
     　　　　　　　　　　　　└──┰──┘
     　　　　　　　　　　　　　　　┃
     　　　　　　　┏━━━━━━━╋━━━━━━━┓
     　　　　　　　┃　　　　　　　┃　　　　　　　┃
     　　　　┌──┸──┐　┌──┸──┐　┌──┸──┐
     第２層　│メニュー　│　│メニュー　│　│メニュー　│
     　　　　└─────┘　└─────┘　└─────┘

この辞書の例では、メニューはここで終わりになっていますが、書籍によって
はさらに第 3 層、第 4 層と続く場合もあります。 また、メニュー全体が均
一の階層数になっているとは限りません。 メニューの参照先が本文や著作権表
示になっていることもあります。

   選択中の副本について、 (第 1 層の) メニューの開始位置を知るには
`eb_menu()' を使います。 この関数は、副本がメニューを持っていなければ
`EB_ERR_NO_SUCH_SEARCH' を返しますので、メニューの有無も同時に分かりま
す。 (開始位置は取得せずに、有無だけを調べたいときは、`eb_have_menu()'
という関数が使えます。)

     EB_Position position;
     EB_Error_Code err;
     
     err = eb_menu(&book, &position);
     if (err == EB_ERR_NO_SUCH_SEARCH) {
         /* メニューはない */
     } else if (err != EB_SUCCESS) {
         /* それ以外のエラー */
        return;
     }

   後は、得られた位置 (`position') にシークして、`eb_read_text()' でテ
キストデータを読み込みます。


File: eb-ja.info,  Node: Multi Candidates,  Next: Stop Code Issue,  Prev: Menu,  Up: Text Data

複合検索の候補一覧
==================

   「複合検索」(*note 複合検索 : Multi Search.) のところで述べたように、
複合検索では、入力語に "候補一覧 (candidates)" が用意されていることが
あります。 これは、入力語として有効な語をあらかじめ列挙しておき、 アプ
リケーションプログラムのユーザに選択させる仕組みです。

たとえば、人名を検索するのために、次のような複合検索があったとします。

     入力語 0: 国・地域
     入力語 1: 時代
     入力語 2: 性別
     入力語 3: キーワード
     入力語 4: キーワード

   このうち、入力語 3 の「性別」には、入力語として有効な語は「男」と「
女」 の 2 つしかないでしょう。 このように、入力語として有効な語が限られ
ている場合に、候補一覧が用意されていることがあります。

候補一覧は検索のためのデータではありますが、内部構造はテキストデータそ
のものです。 ユーザに対して候補を列記した示したテキストを示し、その中の
一つを選択してもらうようになっています。

   しかも、候補一覧のデータ構造はメニューと非常に似ており、メニューの
ような階層構造を持っています (*note メニュー: Menu.)。 たとえば、上の複
合検索の入力語 2 「国・地域」にも候補の一覧を設けるとしたら、最初の階
層は次のようになるかも知れません。

     * 日本 (→選択)
     * 日本以外のアジア (→詳細)
     * ヨーロッパ (→詳細)
     * 北アメリカ (→詳細)
     * その他 (→詳細)

「日本」を選ぶと、そこで入力語が決定されたことになります。しかし、 それ
以外の項目についてはさらに細かく分類された選択肢が用意されています。
ここでは、「北アメリカ」を選んでみましょう。 すると、さらに次のような候
補一覧のデータが提示されます。

     * アメリカ (→選択)
     * カナダ (→選択)

ここで、「アメリカ」「カナダ」を選ぶと、入力語が決定されます。

   次に実際に、EB ライブラリを使ってこうした候補一覧を扱う方法について
説明します。 まず、アプリケーションプログラムは、複合検索の入力語が候補
一覧を持っているかどうかを、確認する必要があるでしょう。
`eb_multi_entry_candidates()' を使うと、候補一覧データの開始位置を取得
することができます。 この関数は、候補一覧を持っていなければ
`EB_ERR_NO_CANDIDATES' を返しますので、候補一覧の有無も分かります。 (
開始位置は取得せずに、有無だけを調べたいときは、
`eb_multi_entry_have_candidates()' という関数が使えます。)

     EB_Position position;
     EB_Error_Code err;
     
     /* `mulit_id', `entry_id' で、どの複合検索の何番目の
      * 入力語について確認するのかを指定します。*/
     err = eb_multi_entry_candidates(&book, multi_id, entry_id, &position);
     if (err == EB_ERR_NO_CANDIDATES) {
         /* この入力語には、候補一覧が用意されていない */
        return;
     } else if (err != EB_SUCCESS) {
         /* それ以外のエラー */
        return;
     }

   後は、得られた位置 (`position') にシークして、`eb_read_text()' でテ
キストデータを読み込みます。 読み込んだテキストでは、候補となる語のそれ
ぞれが候補開始と終了を表すエスケープシーケンスに挟まれた形になっていま
す。

     * <候補開始シーケンス> "日本" <候補終了シーケンス>
     * <候補開始シーケンス> "日本以外のアジア" <候補終了シーケンス>
     * <候補開始シーケンス> "ヨーロッパ" <候補終了シーケンス>
     * <候補開始シーケンス> "北アメリカ" <候補終了シーケンス>
     * <候補開始シーケンス> "その他" <候補終了シーケンス>

   候補開始シーケンスに対しては、フックとして `EB_HOOK_BEGIN_CANDIDATE'
が用意されています。 終了シーケンスに対するフックは 2 種類あって、さら
に次の階層へ続く場合に呼ばれる `EB_HOOK_END_CANDIDATE_GROUP' と、その
語がそのまま入力語の候補となる場合に呼ばれる `EB_HOOK_END_GROUP_LEAF'
に分かれています。

   次の階層のデータの開始位置は、終了シーケンスのフック関数に、引数とし
て渡ってきます。 (この点もメニューと同様なので、メニューの解説を参考に
して下さい。)

   終了シーケンスに対するフック関数の中では、`eb_current_candidate()'
という関数が使えます。 この関数は、開始シーケンスと終了シーケンスの間に
挟まれた「候補」の文字列 (ポインタ) を返します。

     const char *candidate;
     
     candidate = eb_current_candidate(book);


File: eb-ja.info,  Node: Stop Code Issue,  Next: Text Data Sample,  Prev: Multi Candidates,  Up: Text Data

区切りコードの問題
==================

   本文は、先頭から末尾まで一本の繋がったデータ列になっています。 英語
辞典なら、最初の単語 `A' から最後の `zzz' までの説明が、すべて一つの「
本文」の中に書かれることになります。

   一般に、アプリケーションプログラムがある単語を検索した際は、本文の中
からその語を説明した部分だけを抜き出して出力することになるでしょう。
しかし、困ったことに CD-ROM 書籍には、単語の説明の終わりを示す印 (エス
ケープシーケンス) が定義されていません。 つまり、ある語の説明部分を正確
に抜き出すことは、電子ブックや EPWING では不可能なのです。

   しかしながら、幸いにも市販の書籍の多くには、単語の説明の終了位置にだ
け出現する、特有のエスケープシーケンスが存在します。 もちろん、このエ
スケープシーケンスは本来「単語の説明の終了」を示すものではなく別の用途
として用いるのですが、「終了位置」として代用できるという意味です。

   EB ライブラリでは、この「終了位置」の印に使えるエスケープシーケンス
のことを、"区切りコード (stop code)" と呼んでいます。 EB ライブラリは
区切りコードを自動判定する機能を持っていますが、判定は完璧ではないので
外れることもあります。 外れると本文が途中で途切れたり、本文の続きが延々
と出力されたりします。

   その場合は、明示的に付録 (詳しくは ....) で区切りコードを指定するこ
とによって回避できる書籍もありますが、残念ながら区切りコードがまったく
存在しない書籍も少数ながら存在します。 区切りコードを持たない書籍に対し
て、有効な対処方法は今のところありません。

   `eb_read_text()' による本文の取得では、区切りコードが検出された時点
で読み込みを止めます。 さらに繰り返し `eb_read_text()' を呼んでも、区切
りコードより先の本文は読み込めません。

   区切りコードを検出したかどうかの判定には、`eb_is_text_stopped()' を
使います。 この関数は、最後に読み込みを行ったテキストデータの中に、区切
りコードを検出していれば 1 を返します。

   本文以外のテキストデータにも区切りコードの概念は存在しますので、
`eb_is_text_stopped()' を使って区切りコードを検出できます。 本文以外で
は EB ライブラリが確実に区切りを判別できますので、誤判定の問題は起きま
せん。

   見出しにおける区切りは、それぞれの単語の見出しの終了位置となります。
メニューおよび複合検索の候補一覧では、階層化された個々のメニューデータ
の終了位置で区切りと判定されます。 (同一階層に複数個のメニューデータが
あっても、個々のメニューデータで区切られます。) 著作権表示では、全文の
終了位置で区切りと判定されます。


File: eb-ja.info,  Node: Text Data Sample,  Next: Text Data Types,  Prev: Stop Code Issue,  Up: Text Data

サンプルプログラム
==================

     /*
      * 使用方法:
      *     text <book-path> <subbook-index> <number>
      * 例:
      *     text /cdrom 0 10
      * 説明:
      *     <book-path> で指定した CD-ROM 書籍から特定の副本を選び、本文
      *     の先頭から <number> 個分の単語の説明を出力します。
      *
      *     <subbook-index> には、検索対象の副本のインデックスを指定しま
      *     す。インデックスは、書籍の最初の副本から順に 0、1、2 ... に
      *     なります。
      */
     #include "config.h"
     
     #include <stdio.h>
     #include <stdlib.h>
     
     #include <eb/eb.h>
     #include <eb/error.h>
     #include <eb/text.h>
     
     #define MAXLEN_TEXT 1023
     
     int
     main(argc, argv)
         int argc;
         char *argv[];
     {
         EB_Error_Code error_code;
         EB_Book book;
         EB_Subbook_Code subbook_list[EB_MAX_SUBBOOKS];
         int subbook_count;
         int subbook_index;
         EB_Position text_position;
         char text[MAXLEN_TEXT + 1];
         ssize_t text_length;
         int text_count;
         int i;
     
         /* コマンド行引数をチェック。*/
         if (argc != 4) {
             fprintf(stderr, "Usage: %s book-path subbook-index number\n",
                 argv[0]);
             exit(1);
         }
         text_count = atoi(argv[3]);
     
         /* EB ライブラリと `book' を初期化。*/
         eb_initialize_library();
         eb_initialize_book(&book);
     
         /* 書籍を `book' に結び付ける。*/
         error_code = eb_bind(&book, argv[1]);
         if (error_code != EB_SUCCESS) {
             fprintf(stderr, "%s: failed to bind the book, %s: %s\n",
                 argv[0], eb_error_message(error_code), argv[1]);
             goto die;
         }
     
         /* 副本の一覧を取得。*/
         error_code = eb_subbook_list(&book, subbook_list, &subbook_count);
         if (error_code != EB_SUCCESS) {
             fprintf(stderr, "%s: failed to get the subbbook list, %s\n",
                 argv[0], eb_error_message(error_code));
             goto die;
         }
     
         /* 副本のインデックスを取得。*/
         subbook_index = atoi(argv[2]);
     
         /*「現在の副本 (current subbook)」を設定。*/
         if (eb_set_subbook(&book, subbook_list[subbook_index]) < 0) {
             fprintf(stderr, "%s: failed to set the current subbook, %s\n",
                 argv[0], eb_error_message(error_code));
             goto die;
         }
     
         /* テキストの開始位置を取得。*/
         error_code = eb_text(&book, &text_position);
         if (error_code != EB_SUCCESS) {
             fprintf(stderr, "%s: failed to get text information, %s\n",
                 argv[0], eb_error_message(error_code));
             goto die;
         }
     
         /* テキストをシーク。*/
         error_code = eb_seek_text(&book, &text_position);
         if (error_code != EB_SUCCESS) {
             fprintf(stderr, "%s: failed to seek text, %s\n",
                 argv[0], eb_error_message(error_code));
             goto die;
         }
     
         i = 0;
         while (i < text_count) {
             /* テキストを取得。*/
     	error_code = eb_read_text(&book, NULL, NULL, NULL, MAXLEN_TEXT,
     	    text, &text_length);
     	if (error_code != EB_SUCCESS) {
                 fprintf(stderr, "%s: failed to read text, %s\n",
                     argv[0], eb_error_message(error_code));
                 goto die;
             }
     	fputs(text, stdout);
     
             if (!eb_is_text_stopped(&book))
     	    continue;
     
     	fputs("\n----------------------------------------\n", stdout);
     
             /* 次の単語の説明へ移動。*/
     	error_code = eb_forward_text(&book, NULL);
     	if (error_code == EB_ERR_END_OF_CONTENT)
     	    fputs("\n[END]\n", stdout);
     	else if (error_code != EB_SUCCESS) {
     	    fprintf(stderr, "%s: failed to read text, %s\n",
     		argv[0], eb_error_message(error_code));
     	    goto die;
     	}
     	i++;
         }
     
         /* 書籍と EB ライブラリの利用を終了。*/
         eb_finalize_book(&book);
         eb_finalize_library();
         exit(0);
     
         /* エラー発生で終了するときの処理。*/
       die:
         eb_finalize_book(&book);
         eb_finalize_library();
         exit(1);
     }


File: eb-ja.info,  Node: Text Data Types,  Next: Hook Function Details,  Prev: Text Data Sample,  Up: Text Data

データ型の詳細
==============

   この節で説明しているデータ型を使うには、次のようにヘッダファイルを
読み込んで下さい。

     #include <eb/eb.h>

 - Data type: EB_Hook_Code
     データ型 `EB_Hook_Hook' は、フックの設定位置コードを表します。

     この型は符合付き整数型の別名として定義されていますので、2 つのコー
     ドを 2 項演算子 `==' と `!=' で一致比較することができます。

     EB ライブラリでは、全部で `EB_NUMBER_OF_HOOKS' 個のフックコードを
     定義しています。 定義されている設定位置コードの一覧については、 次
     の節 (*note フックコードの一覧 : Hook Code List.)
     を参照して下さい。

 - Data type: EB_Hook
     データ型 `EB_Hook' は、フックコードとそれに対応するフック関数の組
     を表します。 内部構造は、次のように定義されています。

          typedef struct EB_Hook_Struct EB_Hook;
          
          struct EB_Hook_Struct {
              EB_Hook_Code code;
              EB_Error_Code (*function)(EB_Book *, EB_Appendix *, void *,
                  EB_Hook_Code, int, const unsigned int *);
          };

     アプリケーションプログラムは、直接 `EB_Hook' オブジェクトのメンバ
     を参照したり、セットしたりしても構いません。

 - Data type: EB_Hookset
     データ型 `EB_Hookset' は、フック一式を表します。 EB ライブラリで利
     用可能なすべてのフック設定位置に対して、どのようなフック関数を指
     定するのかを記録するための型です。

     `EB_Hookiset' オブジェクトの操作は、すべて EB ライブラリが用意し
     ている関数で行います。 アプリケーションプログラムは、直接
     `EB_Hookset' オブジェクトのメンバを参照したり、セットしたりすべき
     ではありません。

     `EB_Hookset' オブジェクトを使用する際は、まずそのオブジェクトに対
     して `eb_initialize_hookset()'
     を呼んで初期化しなくてはなりません。


File: eb-ja.info,  Node: Hook Function Details,  Next: Hook Code List,  Prev: Text Data Types,  Up: Text Data

フック関数の詳細
================

   この節では、フック関数の仕様について記します。

   まず、フック関数を呼び出す `eb_read_text()' および
`eb_read_heading()' のプロトタイプは次のようになっています。

     EB_Error_Code
     eb_read_text(EB_Book *book, EB_Appendix *appendix,
         EB_Hookset *hookset, void *container, size_t text_max_length,
         char *text, ssize_t *text_length)

   一方、フック関数のプロトタイプは、次のようになっています。

     EB_Error_Code
     hook_function(EB_Book *book, EB_Appendix *appendix, void *container,
         EB_Hook_Code code, int argc, const unsigned int *argv);

   引数 BOOK, APPENDIX, CONTAINER は、 `eb_read_text()' あるいは
`eb_read_heading()' に渡された値がそのままフック関数にも渡ってきます。

   APPENDIX というのは、書籍に対する補助データを提供するオブジェクトで
す。 付録 (appendix) について詳しくは ....。

   引数 CONTAINER は、アプリケーションプログラムからフック関数に何かデ
ータを渡したいときに使います。

   最後の ARGC と ARGV には、加工前のテキストデータが渡されます。 文字
に対するフックでは、文字コード番号が渡ってきます。 エスケープシーケンス
に対するフックでは、そのシーケンス自体のコード (`1f' で始まるコード)
と、もしあればエスケープシーケンスへの引数をが渡ってきます。 個々のフ
ックにおいて、 ARGC と ARGV にどうような値が渡ってくるのか、詳しくは
*note フックコードの一覧: Hook Code List.。

フック関数の中から次に挙げる関数を呼び出すことで、テキストデータへの書
き込みを行うことができます。

   * `eb_write_text()'

   * `eb_write_text_string()'

   * `eb_write_text_byte1()'

   * `eb_write_text_byte2()'

これらの関数の仕様に関して詳しくは *note [テキストデータ] 関数の詳細 :
Text Data Functions.。

   フック関数が `EB_SUCCESS' 以外の値を返すと、フック関数を呼び出した
`eb_read_text()', `eb_read_heading()' はエラーが発生したものと見なし、
そのエラーコードをそのままアプリケーションプログラムに返します。

   フック関数の中では、 BOOK
に対して以下の関数を呼び出してはいけません。 呼び出したときの動作は、未
定義です。

   * `eb_seek_text()'

   * `eb_read_text()'

   * `eb_read_heading()'

   * `eb_read_rawtext()'

   * `eb_forward_text()'

   * `eb_set_subbook()'

   * `eb_unset_subbook()'

   * `eb_load_all_subbook()'

   * `eb_finalize_book()'

   * `eb_finalize_library()'


File: eb-ja.info,  Node: Hook Code List,  Next: Hookset Access Functions,  Prev: Hook Function Details,  Up: Text Data

フックコードの一覧
==================

   この節で説明しているフックコードを使うには、次のようにヘッダファイル
を読み込んで下さい。

     #include <eb/text.h>

 - EB_HOOK_NULL:
     `EB_HOOK_NULL' は厳密にはフックではなく、`eb_set_hooks()' で複数
     のフック関数を登録する際に、`EB_Hook' 配列の末尾の要素を示すため
     に用います。
     このフックコードに対して、フック関数は登録できません。

     詳しくは、*note [テキストデータ] フック関数の詳細 : Text Data
     Functions.。

 - EB_HOOK_INITIALIZE:
     フック `EB_HOOK_INITIALIZE' は、`eb_seek_text()' を呼び出した直後
     の最初の `eb_read_text()', `eb_read_heading()' の呼び出し時に処理
     されます。 何か初期化処理をしたいときに、使うと良いでしょう。

     このフックが、フック関数に渡す `argc' は 0 です。 フック関数を登録
     していない状態では、このフックはテキストデータに何も書き込みませ
     ん。

 - EB_HOOK_BEGIN_NARROW:
 - EB_HOOK_END_NARROW:
     フック `EB_HOOK_BEGIN_NARROW' および `EB_HOOK_END_NARROW' は、 半
     角表示の開始と終了を表すエスケープシーケンスに対するフックです。

     どちらのフックも、フック関数に渡す `argc' は 1 です。 `argv[0]' は
     エスケープシーケンスのコードそのもので、 `EB_HOOK_BEGIN_NARROW' な
     ら `0x1f04'、 `EB_HOOK_END_NARROW' なら `0x1f05' になります。

     フック関数を登録していない状態では、これらのフックはテキストデータ
     に何も書き込みません。

 - EB_HOOK_BEGIN_SUBSCRIPT:
 - EB_HOOK_END_SUBSCRIPT:
     フック `EB_HOOK_BEGIN_SUBSCRIPT' および `EB_HOOK_END_SUBSCRIPT'
     は、下付き表示の開始と終了を表すエスケープシーケンスに対するフック
     です。

     どちらのフックも、フック関数に渡す `argc' は 1 です。 `argv[0]' の
     値はエスケープシーケンスのコードそのもので、
     `EB_HOOK_BEGIN_SUBSCRIPT' なら `0x1f06'、 `EB_HOOK_END_SUBSCRIPT'
     なら `0x1f07' になります。

     フック関数を登録していない状態では、これらのフックはテキストデータ
     に何も書き込みません。

 - EB_HOOK_SET_INDENT:
     フック `EB_HOOK_SET_INDENT'
     は、テキストデータの行頭の字下げ指定を表すエスケープシーケンスに対
     するフックです。

     このフックが、フック関数に渡す `argc' は 2 です。 `argv[0]' はエス
     ケープシーケンスのコードそのもので、 `0x1f09' になります。
     `argv[1]' が、字下げの量を表します。

     字下げの量の単位が、何であるのかは不明です。 また、字下げ量の最小
     値は、0 の場合と 1 の場合の二通りがあります。 いずれにしろ、字下げ
     は 1 ずつ増えたり減ったりします。

     フック関数を登録していない状態では、このフックはテキストデータに何
     も書き込みません。

 - EB_HOOK_NEWLINE:
     フック `EB_HOOK_SET_NEWLINE' は、改行を表すエスケープシーケンスに
     対するフックです。

     ただし、`eb_read_heading()' (見出しの読み込み) による処理では、 改
     行を表すエスケープシーケンスは区切りコードとしても扱われます。 そ
     のため、エスケープシーケンスが見つかってもこのフックの処理は行われ
     ず、 ただちに読み込み処理は終了します。

     このフックが、フック関数に渡す `argc' は 1 です。 `argv[0]' はエス
     ケープシーケンスのコードそのもので、`0x1f0a' になります。

     フック関数を登録していない状態では、このフックはテキストデータに何
     も書き込みませんが、`eb_initialize_hookset()' で `EB_Hook' オブジ
     ェクトを初期化すると、フック関数として `eb_hook_newline()' が自動
     的に登録されます。

 - EB_HOOK_BEGIN_SUPERSCRIPT:
 - EB_HOOK_END_SUPERSCRIPT:
     フック `EB_HOOK_BEGIN_SUPERSCRIPT' および
     `EB_HOOK_END_SUPERSCRIPT' は、上付き表示の開始と終了を表すエスケ
     ープシーケンスに対するフックです。

     どちらのフックも、フック関数に渡す `argc' は 1 です。 `argv[0]' は
     エスケープシーケンスのコードそのもので、
     `EB_HOOK_BEGIN_SUPERSCRIPT' なら `0x1f0e'、
     `EB_HOOK_END_SUPERSCRIPT' なら `0x1f0f' になります。

     フック関数を登録していない状態では、これらのフックはテキストデータ
     に何も書き込みません。

 - EB_HOOK_BEGIN_NO_NEWLINE:
 - EB_HOOK_END_NO_NEWLINE:
     フック `EB_HOOK_BEGIN_NO_NEWLINE' および `EB_HOOK_END_NO_NEWLINE'
     は、改行禁止の開始と終了を表すエスケープシーケンスに対するフックで
     す。

     どちらのフックも、フック関数に渡す `argc' は 1 です。 `argv[0]' は
     エスケープシーケンスのコードそのもので、
     `EB_HOOK_BEGIN_NO_NEWLINE' なら `0x1f10'、
     `EB_HOOK_END_NO_NEWLINE' なら `0x1f11' になります。

     フック関数を登録していない状態では、これらのフックはテキストデータ
     に何も書き込みません。

 - EB_HOOK_BEGIN_EMPHASIS:
 - EB_HOOK_END_EMPHASIS:
     フック `EB_HOOK_BEGIN_EMPHASIS' および `EB_HOOK_END_EMPHASIS' は、
     強調表示の開始と終了を表すエスケープシーケンスに対するフックです。

     どちらのフックも、フック関数に渡す `argc' は 1 です。 `argv[0]' は
     エスケープシーケンスのコードそのもので、 `EB_HOOK_BEGIN_EMPHASIS'
     なら `0x1f12'、 `EB_HOOK_END_EMPHASIS' なら `0x1f13' になります。

     フック関数を登録していない状態では、これらのフックはテキストデータ
     に何も書き込みません。

 - EB_HOOK_BEGIN_CANDIDATE:
 - EB_HOOK_END_CANDIDATE_LEAF:
 - EB_HOOK_END_CANDIDATE_GROUP:
     フック `EB_HOOK_BEGIN_CANDIDATE' は、複合検索の候補となる語の開始
     を表すエスケープシーケンスに対するフックです。

     それに対して、終了を表すエスケープシーケンスに対するフックは 2 種
     類あります。 一つは `EB_HOOK_END_CANDIDATE_LEAF' で、候補となる語
     が実際に検索の入力語として使えるものであることを示します。 もう一
     つは `EB_HOOK_END_CANDIDATE_GROUP' で、候補となる語はさらに細かい
     選択肢に分かれていることを示します。 (したがって、候補となる語を検
     索の入力語として使うことはできません。)

     フック `EB_HOOK_BEGIN_CANDIDATES' が、フック関数に渡す `argc' は 1
     です。 `argv[0]' はエスケープシーケンスのコードそのもので、 `0x1f43'
     になります。

     フック `EB_HOOK_END_CANDIDATE_LEAF' および
     `EB_HOOK_END_CANDIDATE_GROUP' が、フック関数に渡す `argc' は 3 で
     す。 どちらのフックも、`argv[0]' はエスケープシーケンスのコードそ
     のもので、 `0x1f63' になります。 フック
     `EB_HOOK_END_CANDIDATE_GROUP' の `argv[1]' と `argv[2]' は、次の階
     層の候補一覧データの開始ページ番号とオフセットです。 これは、
     `EB_Position' オブジェクト (*note [検索] データ型の詳細 : Search
     Data Types.)  の `page' および `offset' メンバの値に相当します。
     フック `EB_HOOK_END_CANDIDATE_LEAF' では、 `argv[1]', `argv[2]' は
     2 つとも 0 になっています。

     フック関数を登録していない状態では、これらのフックはテキストデータ
     に何も書き込みません。

 - EB_HOOK_BEGIN_REFERENCE:
 - EB_HOOK_END_REFERENCE:
     フック `EB_HOOK_BEGIN_REFERENCE' および `EB_HOOK_END_REFERENCE'
     は、別位置のテキストデータの参照開始と終了を表すエスケープシーケン
     スに対するフックです。

     フック `EB_HOOK_BEGIN_REFERENCE' が、フック関数に渡す `argc' は 2
     です。 `argv[0]' はエスケープシーケンスのコードそのもので、 `0x1f42'
     になります。 `argv[1]' の意味は不明です。

     `EB_HOOK_END_REFERENCE' が、フック関数に渡す `argc' は 3 です。
     `argv[0]' はエスケープシーケンスのコードそのもので、`0x1f62' にな
     ります。 `argv[1]' と `argv[2]' は、参照先のページ番号とオフセット
     です。 これは、`EB_Position' オブジェクト (*note [検索] データ型の
     詳細: Search Data Types.)  の `page' および `offset' メンバの値に
     相当します。

     フック関数を登録していない状態では、これらのフックはテキストデータ
     に何も書き込みません。

 - EB_HOOK_BEGIN_KEYWORD:
 - EB_HOOK_END_KEYWORD:
     フック `EB_HOOK_BEGIN_KEYWORD' および `EB_HOOK_END_KEYWORD' は、検
     索キーの開始と終了を表すエスケープシーケンスに対するフックです。

     フック `EB_HOOK_BEGIN_KEYWORD' が、フック関数に渡す `argc' は 2 で
     す。 `argv[0]' はエスケープシーケンスのコードそのもので、`0x1f41'
     になります。 `argv[1]' の意味は不明です。

     `EB_HOOK_END_KEYWORD' は、フック関数に 1 個の引数を渡します。
     `argv[0]' はエスケープシーケンスのコードそのもので、`0x1f61' にな
     ります。

     フック関数を登録していない状態では、これらのフックはテキストデータ
     に何も書き込みません。

 - EB_HOOK_NARROW_FONT:
 - EB_HOOK_WIDE_FONT:
     フック `EB_HOOK_NARROW_FONT' および `EB_HOOK_WIDE_FONT' は、 それ
     ぞれ半角外字と全角外字に対するフックです。

     どちらのフックも、フック関数に渡す `argc' は 1 です。 `argv[0]'
     は、外字の文字番号を表します。

     フック関数を登録していない状態では、このフックはテキストデータに何
     も書き込みませんが、`eb_initialize_hookset()' で `EB_Hook' オブジ
     ェクトを初期化すると、フック関数として
     `eb_hook_narrow_character_text()' および
     `eb_hook_wide_character_text()' が自動的に登録されます。

 - EB_HOOK_ISO8859_1:
     フック `EB_HOOK_ISO8859_1' は、ISO 8859-1 (ラテン文字 1) 文字に対
     するフックです。

     このフックが、フック関数に渡す `argc' は 1 です。 `argv[0]' は、
     ISO 8859-1 の文字番号を表します。

     フック関数を登録していない状態では、`argv[0]' の値をそのままテキ
     ストデータに書き込みます。 つまり、文字はそのまま ISO 8859-1 とし
     て、1 バイト書き込まれます。

     このフックが利用されるのは、処理中の書籍の文字コードが
     `EB_CHARCODE_ISO8859_1' の場合だけです。

 - EB_HOOK_NARROW_JISX0208:
 - EB_HOOK_WIDE_JISX0208:
     フック `EB_HOOK_NARROW_JISX0208' と `EB_HOOK_WIDE_JISX0208' は、半
     角および全角の JIS X 0208 (日本語のかな漢字) 文字に対するフックで
     す。

     どちらのフックも、フック関数に渡す `argc' は 1 です。 `argv[0]'
     は、JIS X 0208 の文字を日本語 EUC で表現したときの文字番号を表し
     ます。

     フック関数を登録していない状態では、`argv[0]' の値をそのままテキ
     ストデータに書き込みます。 つまり、文字はそのまま日本語 EUC
     として、2 バイト書き込まれます。

     このフックが利用されるのは、 処理中の書籍の文字コードが
     `EB_CHARCODE_JISX0208' か `EB_CHARCODE_JISX0208_GB2312' の場合だけ
     です。

 - EB_HOOK_GB2312:
     フック `EB_HOOK_GB2312' は、GB 2312 (中国語の簡体字) 文字に対する
     フックです。

     このフックが、フック関数に渡す `argc' は 1 です。 `argv[0]' は、 GB
     2312 の文字を中国語 EUC で表現したときの文字番号を表します。

     フック関数を登録していない状態では、`argv[0]' の値をそのままテキ
     ストデータに書き込みます。 つまり、文字はそのまま中国語 EUC
     として、2 バイト書き込まれます。

     このフックが利用されるのは、処理中の書籍の文字コードが
     `EB_CHARCODE_JISX0208_GB2312' の場合だけです。

 - EB_HOOK_BEGIN_MONO_GRAPHIC:
 - EB_HOOK_END_MONO_GRAPHIC:
     フック `EB_HOOK_BEGIN_MONO_GRAPHIC' および
     `EB_HOOK_END_MONO_GRAPIHC' は、モノクロ図版の参照開始と終了を表す
     エスケープシーケンスに対するフックです。

     フック `EB_HOOK_BEGIN_MONO_GRAPHIC' が、フック関数に渡す `argc' は
     4 です。 `argv[0]' はエスケープシーケンスのコードそのもので、
     `0x1f32' か `0x1f44' のいずれかになります。 `argv[2]' と `argv[3]'
     は、図版の幅と高さ (ピクセル数) を意味します。 ただし、電子ブック
     のモノクロ図版 (最初の引数が `0x1f32' の場合) には、図版の幅と高さ
     の情報が欠けているので、値はどちらも 0 になります。 `argv[1]' の意
     味は不明です。

     `EB_HOOK_END_MONO_GRAPHIC' が、フック関数に渡す `argc' は 3 です。
     `argv[0]' は、エスケープシーケンスのコードそのものです。
     `EB_HOOK_BEGIN_MONO_GRAPHIC' の `argv[0]' が `0x1f32' なら、
     `EB_HOOK_END_MONO_GRAPHIC' の `argv[0]' は `0x1f52' になり、
     `0x1f44' なら `0x1f64' になります。 `argv[1]' と `argv[2]' は、図
     版データのページ番号とオフセットです。 これは、`EB_Position' オブ
     ジェクト (*note [検索] データ型の詳細 : Search Data Types.)  の
     `page' および `offset' メンバの値に相当します。

     図版データの取り出し方については、....。

     フック関数を登録していない状態では、これらのフックはテキストデータ
     に何も書き込みません。

 - EB_HOOK_BEGIN_GRAY_GRAPHIC:
 - EB_HOOK_END_GRAY_GRAPHIC:
     これらのフック名称は、グレースケール図版のために予約されていますが、
     EB ライブラリ 3.2.1 ではまだ対応していません。

 - EB_HOOK_BEGIN_COLOR_BMP:
 - EB_HOOK_BEGIN_COLOR_JPEG:
 - EB_HOOK_END_COLOR_GRAPHIC:
     フック `EB_HOOK_BEGIN_COLOR_BMP' と `EB_HOOK_COLOR_JPEG' は、 それ
     ぞれ BMP 形式と JPEG 形式のカラー図版の参照開始を表すエスケープシ
     ーケンスに対するフックです。 参照開始のフックは BMP と JPEG とでフ
     ックが分かれていますが、終了のフックは共通で、
     `EB_HOOK_END_COLOR_GRAPIHC' になります。

     フック `EB_HOOK_BEGIN_COLOR_BMP' と `EB_HOOK_COLOR_JPEG' が、 フッ
     ク関数に渡す `argc' は 4 です。 `argv[0]' はエスケープシーケンスの
     コードそのもので、 `0x1f4d' になります。 `argv[2]' と `argv[3]'
     は、図版の幅と高さ (ピクセル数) を意味します。 `argv[1]' の意味は
     不明です。

     フック `EB_HOOK_END_COLOR_BMP' が、フック関数に渡す `argc' は 3 で
     す。 `argv[0]' はエスケープシーケンスのコードそのもので、`0x1f6d'
     になります。 `argv[1]' と `argv[2]' は、図版データのページ番号と
     オフセットです。 これは、`EB_Position' オブジェクト (*note [検索]
     データ型の詳細: Search Data Types.)  の `page' および `offset' メ
     ンバの値に相当します。

     図版データの取り出し方については、....。

     フック関数を登録していない状態では、これらのフックはテキストデータ
     に何も書き込みません。

 - EB_HOOK_BEGIN_IN_COLOR_BMP:
 - EB_HOOK_BEGIN_IN_COLOR_JPEG:
 - EB_HOOK_END_IN_COLOR_GRAPHIC:
     これらのフック名称は、インラインカラー図版のために予約されています
     が、 EB ライブラリ 3.2.1 ではまだ対応していません。

 - EB_HOOK_BEGIN_WAVE:
 - EB_HOOK_END_WAVE:
     フック `EB_HOOK_BEGIN_WAVE' および `EB_HOOK_END_WAVE' は、 WAVE 形
     式の音声データの参照開始と終了を表すエスケープシーケンスに対する
     フックです。

     フック `EB_HOOK_BEGIN_WAVE' が、フック関数に渡す `argc' は 6
     です。 `argv[0]' はエスケープシーケンスのコードそのもので、 `0x1f4a'
     になります。 `argv[2]' と `argv[3]' は図版データの開始位置のページ
     番号とオフセット、 `argv[4]' と `argv[5]'
     は終了位置のページ番号とオフセットをそれぞれ表します。 `argv[1]'
     の意味は不明です。

     `EB_HOOK_END_WAVE' が、フック関数に渡す `argc' は 1 です。
     `argv[0]' はエスケープシーケンスのコードそのもので、`0x1f6a' にな
     ります。

     音声データの取り出し方については、....。

     フック関数を登録していない状態では、これらのフックはテキストデータ
     に何も書き込みません。

 - EB_HOOK_BEGIN_MPEG:
 - EB_HOOK_END_MPEG:
     フック `EB_HOOK_BEGIN_MPEG' および `EB_HOOK_END_MPEG' は、 MPEG 形
     式の動画データの参照開始と終了を表すエスケープシーケンスに対する
     フックです。

     フック `EB_HOOK_BEGIN_MPEG' が、フック関数に渡す `argc' は 6
     です。 `argv[0]' はエスケープシーケンスのコードそのもので、 `0x1f39'
     になります。 `argv[2]' 〜 `argv[5]' は、動画データのファイル名をエ
     ンコードした数値列になります。 `argv[1]' の意味は不明です。

     `EB_HOOK_END_MPEG' が、フック関数に渡す `argc' は 1 です。
     `argv[0]' はエスケープシーケンスのコードそのもので、`0x1f59' にな
     ります。

     動画データの取り出し方については、....。

     フック関数を登録していない状態では、これらのフックはテキストデータ
     に何も書き込みません。


File: eb-ja.info,  Node: Hookset Access Functions,  Next: Builtin Hook Functions,  Prev: Hook Code List,  Up: Text Data

フックセット操作関数の詳細
==========================

   この節で説明している関数を使うには、次のようにヘッダファイルを読み込
んで下さい。

     #include <eb/text.h>

 - Function: void eb_initialize_hookset (EB_Hookset *HOOKSET)
     関数 `initialize_hookset()' は、HOOKSET の指す `EB_Hookset' オブジ
     ェクトを初期化します。 `EB_Hookiset' オブジェクトに対して EB ライ
     ブラリの他の関数を呼ぶ前に、 必ずそのオブジェクトを初期化しなくて
     はなりません。 初期化していないオブジェクトに対して、EB ライブラリ
     の他の関数を呼んだ場合の動作は未定義です。 また、すでに初期化した
     オブジェクトに対して、再度 `eb_initialize_hookset()' を呼んではい
     けません。 呼んだ場合の動作は未定義です。

     この関数は、各フックの初期値を次のようにセットします。

     フック                             フック関数
     `EB_HOOK_NARROW_JISX0208'          `eb_hook_euc_to_ascii()'
     `EB_HOOK_NARROW_FONT'              `eb_hook_narrow_character_text()'
     `EB_HOOK_WIDE_FONT'                `eb_hook_wide_character_text()'
     `EB_HOOK_NEWLINE'                  `eb_hook_newline()'
     上記以外のフック                   `NULL' (フック関数なし)

 - Function: EB_Error_Code eb_finalize_hookset (EB_Hookset *HOOKSET)
     関数 `eb_finalize_hookset()' は、HOOKSET が指す `EB_Hooksest' オブ
     ジェクトの後始末を行います。

     オブジェクトが割り当てて管理していたメモリは、すべて解放されます。
     すべてのフックには、フック関数として `NULL' がセットされます。

     後始末をしたオブジェクトに対して `eb_set_hook()', `eb_set_hooks()'
     を呼ぶことで、オブジェクトを再利用することができます。

 - Function: EB_Error_Code eb_set_hook (EB_Hookset *HOOKSET, const
          EB_Hook *HOOK)
     関数 `eb_set_hook()' は、HOOKSET が指す `EB_Hooksest' オブジェクト
     に、フック関数を一つ登録します。 登録するフックの種類とフック関数
     は、HOOK で指定します。

     同じフックコードに複数回フック関数を登録しても、有効になるのは最後
     に登録したものだけですので、注意して下さい。 フック関数として
     `NULL' を指定すると、登録されているフックが解除されます。

     成功すると、この関数は `EB_SUCCESS' を返します。 失敗すると、原因
     を示すエラーコードを返します。

 - Function: EB_Error_Code eb_set_hooks (EB_Hookset *HOOKSET, const
          EB_Hook *HOOKS)
     この関数は `eb_set_hook()' に似ていますが、任意の個数のフック関数
     を一度に登録できる点が異なります。

     登録するフックの種類とフック関数は、 HOOKS で指定します。 HOOKS は
     `EB_Hook' オブジェクトの配列 (の先頭) を指していなければなりませ
     ん。 また、この配列の末尾には、フックコード `EB_HOOK_NULL' をセッ
     トした `EB_Hook' オブジェクトを配列要素として置く必要があります。

     `eb_set_hooks()' は、配列の先頭から順番に、指定されたフックコード
     に対してフック関数を登録していきます。 エラーが発生すると、残りの
     フックの登録はせずに、原因を示すエラーコードをただちに返します。
     すべてのフック関数の登録に成功すると、`EB_SUCCESS' を返します。


File: eb-ja.info,  Node: Builtin Hook Functions,  Next: Text Data Functions,  Prev: Hookset Access Functions,  Up: Text Data

組み込みフック関数の詳細
========================

   EB ライブラリは、基本的なフック関数をいくつか用意しています。 本節で
は、これらのフック関数についての仕様を解説します。

   この節で説明している関数を使うには、次のようにヘッダファイルを読み込
んで下さい。

     #include <eb/text.h>

   いずれのフック関数も、引数 APPENDIX と CONTAINER に `NULL' を渡され
ても、動作に支障はないようになっています。

 - Function: EB_Error_Code eb_hook_euc_to_ascii (EB_Book *BOOK,
          EB_Appendix *APPENDIX, void *CONTAINER, EB_Hook_Code CODE,
          int ARGC, const unsigned int *ARGV)
     `eb_hook_euc_to_ascii()' は、フックコード
     `EB_HOOK_NARROW_JISX0208' (半角 JIS X 0208 文字) のためのフック関
     数です。

     `EB_Hookset' オブジェクトを関数 `eb_initialiez_hookset()' で初期
     化すると、この関数が自動的に登録されます。

     このフック関数は、`argv[0]' として渡された JIS X 0208 の文字 (エン
     コーディングは日本語 EUC) を調べ、対応する ASCII 文字が存在すれば
     その ASCII 文字をテキストデータとして書き込み、なければ JIS X 0208
     の文字をそのまま書き込みます。

     常に `EB_SUCCESS' を返します。

 - Function: EB_Error_Code eb_hook_narrow_character_text (EB_Book
          *BOOK, EB_Appendix *APPENDIX, void *CONTAINER, EB_Hook_Code
          CODE, int ARGC, const unsigned int *ARGV)
 - Function: EB_Error_Code eb_hook_wide_character_text (EB_Book *BOOK,
          EB_Appendix *APPENDIX, void *CONTAINER, EB_Hook_Code CODE,
          int ARGC, const unsigned int *ARGV)
     `eb_hook_narrow_character_text()' は、フックコード
     `EB_HOOK_NARROW_FONT' (半角外字) のためのフック関数です。 同様に
     `eb_hook_wide_character_text()' は、フックコード
     `EB_HOOK_WIDE_FONT' (全角外字) のためのフック関数です。

     `EB_Hookset' オブジェクトを関数 `eb_initialiez_hookset()' で初期
     化すると、これらの関数が自動的に登録されます。

     この関数は、付録 APPENDIX の選択中している副本が、`argv[0]' として
     渡された外字の代替文字列を持っているかどうか調べます。 持っていれ
     ばその文字列をテキストデータとして書き込み、持っていなければ `<?>'
     という文字列を書き込みます。

     付録 APPENDIX が `NULL'
     の場合や、付録が副本を選択中でない場合も、代替文字列を持っていない
     ものとして扱います。

     この関数は、常に `EB_SUCCESS' を返します。

 - Function: EB_Error_Code eb_hook_newline (EB_Book *BOOK, EB_Appendix
          *APPENDIX, void *CONTAINER, EB_Hook_Code CODE, int ARGC,
          const unsigned int *ARGV)
     `eb_hook_narrow_newline()' は、フックコード `EB_HOOK_NEWLINE' (改
     行) のためのフック関数です。

     `EB_Hookset' オブジェクトを関数 `eb_initialiez_hookset()' で初期
     化すると、これらの関数が自動的に登録されます。

     この関数は、テキストデータに `\n' を書き込みます。 常に
     `EB_SUCCESS' を返します。

 - Function: EB_Error_Code eb_hook_empty (EB_Book *BOOK, EB_Appendix
          *APPENDIX, void *CONTAINER, EB_Hook_Code CODE, int ARGC,
          const unsigned int *ARGV)
     `eb_hook_empty()' は、何もしないフック関数です。 常に `EB_SUCCESS'
     を返します。


File: eb-ja.info,  Node: Text Data Functions,  Prev: Builtin Hook Functions,  Up: Text Data

テキストデータ操作関数の詳細
============================

   この節で説明している関数を使うには、次のようにヘッダファイルを読み込
んで下さい。

     #include <eb/text.h>

 - Function: int eb_have_text (EB_Book *BOOK)
 - Function: int eb_have_menu (EB_Book *BOOK)
 - Function: int eb_have_copyright (EB_Book *BOOK)
     関数 `eb_have_text()' は、BOOK の選択している副本が、本文を持って
     いるかどうかを調べます。 同様に、`eb_have_menu()' はメニューを持っ
     ているかどうか、 `eb_have_copyright()' は著作権表示を持っているか
     どうか調べます。

     いずれの関数も、持っていれば 1 を返し、持っていなければ 0 を返しま
     す。 BOOK が副本を選択していない場合も 0 を返します。

 - Function: EB_Error_Code eb_text (EB_Book *BOOK, EB_Position
          *POSITION)
 - Function: EB_Error_Code eb_menu (EB_Book *BOOK, EB_Position
          *POSITION)
 - Function: EB_Error_Code eb_copyright (EB_Book *BOOK, EB_Position
          *POSITION)
     関数 `eb_text()' は、 BOOK が選択している副本の本文の開始位置を
     POSITION の指す領域に書き込みます。 同様に、`eb_menu()' はメニュー
     の開始位置を、 `eb_have_copyright()' は著作権表示の開始位置を書き
     込みます。

     成功すると、これらの関数は `EB_SUCCESS' を返します。 失敗すると、
     POSITION に必ずシークが失敗する位置を書き込んで、 原因を示すエラー
     コードを返します。

     あらかじめ、BOOK 内のいずれかの副本が選択されていなくてはなりませ
     ん。 BOOK が副本を選択していなければ、`EB_ERR_NO_CUR_SUB' を返しま
     す。 選択中の副本が、対象となるテキストデータを持っていなければ、
     `EB_ERR_NO_SUCH_SEARCH' を返します。

 - Function: EB_Error_Code eb_seek_text (EB_Book *BOOK, const
          EB_Position *POSITION)
     関数 `eb_seek_text()' は、BOOK が選択している副本のテキストデータ
     ファイルをシークします。 シーク位置は POSITION で指定します。 この
     とき、 POSITION は常にファイルの先頭からの位置として解釈されます。
     (相対位置へのシーク機能は、EB ライブラリにはありません。)

     シークを行うと、それまでに行った読み込みの状態記録がリセットされま
     す。 `eb_read_text()', `eb_read_heading()', `eb_read_rawtext()' を
     用いてテキストデータを読み込むには、前もってこの関数を呼び出して
     おく必要があります。

     成功すると、この関数は `EB_SUCCESS' を返します。 失敗すると、原因
     を示すエラーコードを返します。

     あらかじめ、BOOK 内のいずれかの副本が選択されていなくてはなりませ
     ん。 BOOK が副本を選択していなければ、`EB_ERR_NO_CUR_SUB' を返しま
     す。 選択中の副本にテキストデータが存在しないときは、
     `EB_ERR_NO_TEXT' を返します。

     なお、書籍によっては、テキストデータを収めたファイルには他のデータ
     も一緒に格納されていることがありますが、テキスト以外のデータにア
     クセスしても、テキストデータの現在位置、読み込みに関する状態記録
     は変化しません。

 - Function: EB_Error_Code eb_tell_text (EB_Book *BOOK, EB_Position
          *POSITION)
     関数 `eb_seek_text()' は、BOOK が選択している副本のテキストデータ
     ファイルの現在のアクセス位置を返します。

     成功すると、 POSITION の指す領域に現在のアクセス位置を書き込み、
     `EB_SUCCESS' を返します。 失敗すると、シークが必ず失敗する位置を書
     き込み、原因を示すエラーコードを返します。

     あらかじめ、BOOK 内のいずれかの副本が選択されていなくてはなりませ
     ん。 BOOK が副本を選択していなければ、`EB_ERR_NO_CUR_SUB' を返しま
     す。 選択中の副本にテキストデータが存在しないときは、
     `EB_ERR_NO_TEXT' を返します。

 - Function: EB_Error_Code eb_read_text (EB_Book *BOOK, EB_Appendix
          *APPENDIX, EB_Hookset *HOOKSET, void *CONTAINER, size_t
          TEXT_MAX_LENGTH, char *TEXT, ssize_t *TEXT_LENGTH)
 - Function: EB_Error_Code eb_read_heading (EB_Book *BOOK, EB_Appendix
          *APPENDIX, EB_Hookset *HOOKSET, void *CONTAINER, size_t
          TEXT_MAX_LENGTH, char *TEXT, ssize_t *TEXT_LENGTH)
     関数 `eb_read_text()' と `eb_read_heading()' は、BOOK が選択してい
     る副本のテキストデータファイルの現在のアクセス位置からデータを読
     み込みます。 `eb_read_heading()' は見出しの読み込みに用い、
     `eb_read_text()' はそれ以外のテキストデータの読み込みに用います。

     読み込まれたテキストデータは、必要に応じて文字コードの変換 (*note
     文字コード: Character Code.) が行われた後に、HOOKSET の指すフック
     セットにしたがって加工されます。 HOOKSET が `NULL' のときは、代わ
     りに EB ライブラリ側で用意している "標準のフックセット (default
     hookset)" が用いられます。 このフックセットは、
     `eb_initialize_hookset()' によって初期化しただけのフックセットと
     等価です。

     フックセットによって加工された後に、テキストデータは TEXT の指す
     領域に書き込まれ、書き込んだバイト数が TEXT_LENGTH の指す領域に書
     き込まれます。 TEXT はナル文字で終端されますが、TEXT_LENGTH にはナ
     ル文字の分は勘定に入れません。 テキストデータは、TEXT_MAX_LENGTH
     で指定されたバイト数を超えて書き込むことはありません。 ただし、
     TEXT_MAX_LENGTH にもナル文字の分は勘定に入っていませんので、TEXT
     は TEXT_MAX_LENGTH + 1 バイト分のデータを格納できる大きさが必要で
     す。

     どちらの関数も、成功すれば `EB_SUCCESS' を返し、失敗すれば
     TEXT_LENGTH の指す領域に 0 を書き込んで原因を示すエラーコードを返
     します。

     あらかじめ、BOOK 内のいずれかの副本が選択されていなくてはなりませ
     ん。 BOOK が副本を選択していなければ、`EB_ERR_NO_CUR_SUB' を返しま
     す。

     また、`eb_read_text()' と `eb_read_heading()' を呼び出すには、 あ
     らかじめ `eb_seek_text()' の呼び出しを成功させ、テキストデータの
     アクセス位置がセットされた状態にしておかなくてはなりません。 シー
     クをせずに呼び出すと、`EB_ERR_NO_PREV_SEEK' を返します。

     逆に一度シークすれば、区切りコードが検出されるまでの間なら、関数を
     繰り返し呼ぶことでテキストデータの続きを読み込むことができます。
     区切りコードが検出されると、関数を呼び出しても読み込みは行われませ
     ん。 その場合でも、他にエラーが発生しなければ `EB_SUCCESS'
     が返り、 TEXT には空文字列が書き込まれます。

     ただし、一度 `eb_read_text()'
     を呼び出してテキストデータを読み込み始めたら、繰り返し呼び出す際も、
     `eb_read_text()' を使わなければなりません。 途中から
     `eb_read_heading()' および後述の `eb_read_rawtext()' に切り替えて
     呼び出すと `EB_ERR_DIFF_CONTENT' エラーが返ります。 関数
     `eb_read_heading()' についても同様です。 この制限は、再度
     `eb_seek_text()' を呼び出すか、 `eb_set_subbook()' で副本を選択し
     直すまで続きます。

     APPENDIX が `NULL' ではなく、区切りコードの情報を持った副本を選択
     中であれば、本文の区切りコードとしてその値を使用します。 それ以外
     の場合は、`eb_read_text()' が区切りコードを自動判別を試みます。
     ただし、この判定は完璧なものではないので、書籍によっては変な位置で
     本文が切れてしまうかも知れません。 (本文以外のテキストデータに関
     しては、このような問題は起きません。)

     引数 CONTAINER は、アプリケーションプログラムからフック関数にデー
     タを渡すためのものです。 `eb_read_text()', `eb_read_heading()' で
     は、直接この引数の値を参照することはありません。

     引数 APPENDIX, CONTAINER は、そのままフック関数に渡されます。 これ
     らの引数は `NULL' でも構いません。 (ただし、呼び出されるフック関数
     で支障がなければ。)

     なお、フック関数や `eb_read_text()', `eb_read_heading()' 自身が文
     字ないしエスケープシーケンス一個に対するデータを書き込もうとした
     ときに、TEXT に十分な空き領域がないということが起こり得ます。 その
     場合、関数は途中まで TEXT に書き込むことはせずに、いったん処理を
     終えて戻ります。 したがって、マルチバイト文字のデータが途中で切れ
     たりすることはありません。

     書き込めなかった分は、当然ながら TEXT_LENGTH
     の勘定には入りません。 書き込めなかったデータは BOOK 内部に保存さ
     れているので、もう一度 `eb_read_text()', `eb_read_heading()' を呼
     び出すと、前回の呼び出しで書き込めなかったデータがまず TEXT の先
     頭に書き込まれます。 書き込んだデータは TEXT_LENGTH の勘定に入りま
     す。

     ただし、書き込めなかったデータの長さが MAX_TEXT_LENGTH を超えてい
     ると、何も書き込まずに関数は終了します。 このとき、書き込めなかっ
     たデータは引き続き保存されます。

     `eb_seek_text()' を呼び出すか、`eb_set_subbook()' で副本を選択し
     直すと、保存していたデータは破棄されます。

 - Function: EB_Error_Code eb_read_rawtext (EB_Book *BOOK, size_t
          TEXT_MAX_LENGTH, char *TEXT, ssize_t *TEXT_LENGTH)
     関数 `eb_read_rawtext()' は、BOOK が選択している副本のテキストデ
     ータファイルの現在のアクセス位置からデータを読み込みます。

     `eb_read_text()' と似ていますが、この関数はフックセットによるデー
     タの加工や文字コードの変換を一切行わず、データを内部表現のまま返
     します。 読み込むテキストデータの種類は、何であっても構いません。

     読み込んだテキストデータは TEXT
     の指す領域に書き込まれ、書き込んだバイト数が TEXT_LENGTH の指す領
     域に書き込まれます。 テキストデータは、TEXT_MAX_LENGTH で指定され
     たバイト数を超えて書き込むことはありません。 ただし、
     `eb_read_text()' と異なり、TEXT はナル文字で終端されません。 マル
     チバイト文字やエスケープシーケンスの途中で TEXT の残り領域が足り
     なくなった場合も、途中までは書き込みます。

     処理が成功すれば `EB_SUCCESS' を返し、失敗すれば TEXT_LENGTH の指
     す領域に 0 を書き込んで原因を示すエラーコードを返します。

     あらかじめ、BOOK 内のいずれかの副本が選択されていなくてはなりませ
     ん。 BOOK が副本を選択していなければ、`EB_ERR_NO_CUR_SUB' を返しま
     す。

     また、この関数を呼び出すには、あらかじめ `eb_seek_text()' の呼び出
     しを成功させ、テキストデータのアクセス位置がセットされた状態にし
     ておかなくてはなりません。 シークをせずに呼び出すと、
     `EB_ERR_NO_PREV_SEEK' を返します。

     この関数は、繰り返し呼び出すことで、前回読み込んだテキストデータの
     続きを読み込むことができます。 ただし、区切りコードの検出を行いま
     せんので、ひたすら呼び出しを続けると、 テキストデータファイルの末
     尾まで行ってしまいます。

     一度 `eb_read_rawtext()' を呼び出してテキストデータを読み込み始め
     たら、繰り返し呼び出す際も、`eb_read_rawtext()' を使わなければな
     りません。 途中から、`eb_read_text()' や `eb_read_text()' に切り替
     えると、 `EB_ERR_DIFF_CONTENT' エラーが返ります。 この制限は、再度
     `eb_seek_text()' を呼び出すか、 `eb_set_subbook()' で副本を選択し
     直すまで続きます。

 - Function: int eb_is_text_stopped (EB_Book *BOOK)
     関数 `eb_is_text_stopped()' は、最後に読み込んだテキストデータが
     末尾に達したかどうかを判定します。

     BOOK が選択中の副本で、最後に `eb_read_text()' または
     `eb_read_heading()'
     でテキストデータを読み込んだ際に、区切りコードを検出したか、テキス
     トデータの末尾に達して読み込みを終えていれれば、この関数は 1 を返
     します。 それ以外のときは、0 を返します。

     BOOK が副本を選択していない場合や、選択中の副本にテキストデータが
     存在しない場合も 0 が返ります。

     `eb_read_text()' または `eb_read_heading()' でテキストデータを読
     み込んでいない場合も、同様に 0 が返ります。 テキストデータを読み込
     んだ後であっても、テキストデータの読み込みに関する状態記録をリセ
     ットする関数 (eb_read_text() の項を参照) を呼んでしまうと、 読み込
     んでいないと見なされますので、注意して下さい。

 - Function: EB_Error_Code eb_write_text_byte1 (EB_Book *BOOK, int
          BYTE1)
 - Function: EB_Error_Code eb_write_text_byte2 (EB_Book *BOOK, int
          BYTE1, int BYTE2)
 - Function: EB_Error_Code eb_write_text_string (EB_Book *BOOK, const
          char *STRING)
 - Function: EB_Error_Code eb_write_text (EB_Book *BOOK, const char
          *STREAM, size_t STREAM_LENGTH)
     これらの関数は、いずれもフック関数の中から、テキストデータを書き込
     むために用います。
     書き込むデータの種類によって、使い分けて下さい。

     `eb_write_text_byte1()' は、BYTE1 で指定した 1 バイトの値を書き込
     みます。 `eb_write_text_byte2()' は、BYTE1, BYTE2 で指定した 2 バ
     イトを書き込みます。 `eb_write_text_string()' は、STRING で指定し
     た文字列を書き込みます。 `eb_write_text()' は、STREAM から始まる
     長さ STREAM_LENGTH バイトのバイト列を書き込みます。

     どの関数も、成功すると `EB_SUCCESS' を返し、失敗すると原因を示す
     エラーコードを返します。

     最終的に、書き込んだテキストデータは、フック関数の呼び出し元である
     `eb_read_text()', `eb_read_heading()' からアプリケーションプログ
     ラムに渡されます。

     フック関数として呼び出されていないときに、これらの関数を呼び出した
     場合の動作は未定義です。

 - Function: const char * eb_current_candidate (EB_Book *BOOK)
     関数 `eb_current_candidate()' は、アクセス中のテキストデータの現
     在位置に書かれている、複合検索の候補となる語を返します。

     返す文字列の長さは、最長で `EB_MAX_WORD_LENGTH' バイトになります。
     ただし、この長さにナル文字は含みません。

     この関数は非常に特殊で、複合検索の候補となる語の終了を意味するエ
     スケープシーケンスへのフックである `EB_HOOK_END_CANDIDATE_LEAF' お
     よび `EB_HOOK_END_CANDIDATE_GROUP' に対するフック関数の中でのみ呼
     び出すことができます。 それ以外の場所で呼び出したときの動作は、未
     定義です。

     この関数の呼び出し方ですが、フック関数に渡ってきた `EB_Book' オブ
     ジェクト (へのポインタ) を、そのままこの関数に引数として渡してや
     ります。

     BOOK の文字コード (*note [CD-ROM 書籍と `EB_Book' オブジェクト] デ
     ータ型の詳細: EB_Book Data Types.)  が `EB_CHARCODE_ISO8859_1' な
     ら、関数の返す文字列は ISO 8859-1 になり、それ以外の文字コードの場
     合は日本語 EUC になります。 関数の返す文字列は、他のフックによる加
     工処理の影響を受けません。 文字コードの変換を行う以外は、内部デー
     タをそのまま返します。

     なお、この関数が返した文字列を参照できるのは、フック関数から戻るま
     での間だけですので、注意して下さい。

 - Function: EB_Error_Code eb_forward_text (EB_Book *BOOK, EB_Appendix
          *APPENDIX)
 - Function: EB_Error_Code eb_backward_text (EB_Book *BOOK, EB_Appendix
          *APPENDIX)
     関数 `eb_forward_text()' と `eb_backward_text()' は、 BOOK が選択
     している副本の本文のアクセス位置を前後に移動させ、 本文の区切りコ
     ードを単位とした頭出しを行います。 ちょうど、音楽 CD-ROM の曲の頭
     出しと同じです。

     `eb_forward_text()'
     は本文の末尾方向に向かってアクセス位置を進め、 `eb_backward_text()'
     は先頭方向に向かってアクセス位置を戻します。

     `eb_forward_text()' の呼び出しでは、アクセス位置は必ず次の語の説
     明の開始位置まで移動します。 それに対して `eb_backward_text()' の
     呼び出しでは、移動先が状態によって異なります。 もし、現在のアクセ
     ス位置がその単語の説明の先頭にあるときは、 `eb_backward_text()' の
     呼び出しによって、一つ前の単語の説明の先頭にアクセス位置が移動し
     ます。 アクセス位置が単語の説明の途中や末尾にあるときは、その単語
     の説明の先頭に移動します。

     この関数は、成功すると `EB_SUCCESS' を返し、失敗すると原因を示す
     エラーコードを返します。

     あらかじめ、BOOK 内のいずれかの副本が選択されていなくてはなりませ
     ん。 BOOK が副本を選択していなければ、`EB_ERR_NO_CUR_SUB' を返しま
     す。

     加えて、これらの関数を呼び出すには、あらかじめ `eb_seek_text()' か
     `eb_read_text()' を呼び出しが成功していないといけません。
     (`eb_read_text()' の呼び出しを成功させるには、さらに前もって
     `eb_seek_text()' の呼び出しを成功させることが条件となります。)

     `eb_read_text()' ではなく、 `eb_read_heading()' や
     `eb_read_rawtext()' の呼び出しに成功した後でこの関数を呼び出すと、
     `EB_ERR_DIFF_CONTENT' を返します。 また、前もって `eb_seek_text()'
     でシークせずにこの関数を呼び出すと、 `EB_ERR_NO_PREV_SEEK' を返し
     ます。

     本文データの末尾や先頭に達してしまって、その方向にもう本文がないと
     きは、 `EB_ERR_END_OF_CONTENT' を返します。

     APPENDIX が `NULL' ではなく、区切りコードの情報を持った副本を選択
     中であれば、本文の区切りコードとしてその値を使用します。 それ以外
     の場合は、`eb_read_text()' と同じ方法で区切りコードの自動判別を試
     みます。

     アクセス位置上にあるのがメニューや著作権表示のように、本文以外の
     テキストデータであっても、構いません。 ただし、本文以外のテキスト
     データの内部には、頭出し位置が一箇所しかありませんので、この関数
     が役に立つ状況はほとんどありません。

     (メニューでは、個々の階層のメニューデータが、それぞれ独立したテキ
     ストデータになっているため、頭出しを行っても前後のメニューデータへ
     は移動できません。 複合検索の候補一覧も同様です。)


File: eb-ja.info,  Node: Local Character,  Next: Index,  Prev: Text Data,  Up: Top

外字
****

文字コードに収録されていない、私的に定義した文字のことを、俗に「外字」
と言います。 外字として定義した個々の文字を識別するために、文字コードに
収録された文字とは重複しない位置に、各文字の文字番号に割り振るのが普通
です。 (割り当てる文字番号の詳細については、*note 文字コード : Character
Code.。)

   市販の電子ブック、EPWING でも、ほとんどが外字を使っています。 外字の
定義状況は書籍同士でバラバラで、まったく統一感はありません。 つまり、同
じ文字番号を使っていても、定義されている外字は書籍によって違います。
外字は副本毎に定義することが可能ですが、一つの CD-ROM 書籍内でも副本に
よって定義が異なることも珍しくありません。 副本によっては、数百から数千
の外字を定義していることもあります。

   CD-ROM 書籍では、定義した外字の字形データ (つまりフォント) を用意し
ています。 フォントはビットマップデータであり、書籍によっては大きさの
異なる数種類のフォントを用意しています。

   逆に言えば、外字に対して提供されるデータは、フォントだけです。 ある
文字番号を割り当てられた外字が、漢字なのか、発音記号なのか、そういった
補助的な情報は用意されていません。 アプリケーションプログラムが外字をサ
ポートするためには、外字のフォントをそのまま表示する以外に方法はないで
しょう。

* Menu:

* Narrow & Wide Font::          半角外字と全角外字
* Font Size and Font Code::     外字の大きさと外字コード
* Current Font Height::         選択中の外字フォントの高さ
* Get Font::                    外字フォントの取り出し
* Convert Font::                外字フォントの変換
* Local Character in Text::     テキスト中の外字
* Font Data Types::             データ型の詳細
* Font Constants::              定数の詳細
* Font Data Functions::         関数の詳細


File: eb-ja.info,  Node: Narrow & Wide Font,  Next: Font Size and Font Code,  Prev: Local Character,  Up: Local Character

半角外字と全角外字
==================

   CD-ROM 書籍における外字には、「全角外字」「半角外字」の二種類があり
ます。 全角外字は用意されているフォントの横と縦の長さがおよそ 1:1 にな
っており、 半角外字では 1:2 になっています。

     　　　　　　全角外字　　　　　　　　　　半角外字　　
     　　　　（１６×１６）　　　　　　　　（８×１６）
     □□□□□□□□□□□□□□□□　　□□□□□□□□
     □□□□□□□□□□□□□□□□　　□□■■□■□□
     □□□■■■■■■□□□■□□□　　□□□□■□□□
     □□□□□□□□■□■□■□□□　　□□□■■□□□
     □□□□■□□■□□■□■□□□　　□□■□□■□□
     □□□□■□□■■■■■■□□□　　□■□□□■□□
     □□■■■■■□□□■□■□□□　　□□□■□■□□
     □□□□□□□□□□■□■□□□　　□□■□■■□□
     □□□■□□□□□□□□■□□□　　□■□□□■□□
     □□□■□□□□□□□□■□□□　　□■□□□■□□
     □□□■■■■■■■■■■□□□　　□■□□□■□□
     □□□■□□□□□□□□■□□□　　□■□□□■□□
     □□□■□□□□□□□□■□□□　　□■□□□■□□
     □□□■■■■■■■■■■□□□　　□■□□□■□□
     □□□□□□□□□□□□□□□□　　□□■■■□□□
     □□□□□□□□□□□□□□□□　　□□□□□□□□

テキストデータには、半角表示の開始と終了を表すエスケープシーケンスがあ
り (*note テキストデータの内部形式: Text Data Format.)、開始と終了の間
に置かれたものは半角外字、それ以外のところなら全角外字になります。

文字番号は同じでも、字形が全角と半角ではまったく異なることもありますの
で、外字の文字番号だけから、全角と半角のどちらかを判断することはできま
せん。 かならず、前方に半角開始のエスケープシーケンスが出現していたかど
うかという情報に基づいて判断しないといけません。

   ただし、全角か半角かの判定は EB ライブラリ側で行いますので、 アプリ
ケーションプログラムが文脈の解析を行う必要はありません。

   CD-ROM 書籍の副本には、半角外字あるいは全角外字のどちらか一方だけを
定義しているものもありますし、両方とも定義しているものもあります。


File: eb-ja.info,  Node: Font Size and Font Code,  Next: Current Font Height,  Prev: Narrow & Wide Font,  Up: Local Character

外字の大きさと外字コード
========================

各副本には、定義している外字のフォントがビットマップ形式で収録されてい
ます。 フォントの大きさは、縦のピクセル数を基準にすると 16, 24, 30, 48
の 4 種類があり、全角外字、半角外字それぞれのフォントの大きさ (横のピク
セル数×縦のピクセル数) は次の通りになります。

縦のピクセル数                全角全角               半角外字
16                            16x16                  8x16
24                            24x24                  16x24
30                            32x30                  16x30
48                            48x48                  24x48

   ただし、すべての副本でこれら 4 種類のフォントを用意しているわけでは
ありません。 縦が 16 ピクセルのものは必ず用意されていますが、それ以外は
ないことも珍しくありません。 (外字がまったく定義されていなければ、16
ピクセルのフォントも用意されません。)

   EB ライブラリでは、このように縦方向のピクセル数、つまり "フォントの
高さ (font height)" を基準に、外字フォントの大きさを区別しています。
そして、それぞれのフォントの高さ (16, 24, 30, 48) に対して、 "外字コー
ド (font code)" というものを割り当てています。 フォントの高さを指定する
際は、必ずこの外字コードを使います。

縦のピクセル数                       外字コード
16                                   `EB_FONT_16'
24                                   `EB_FONT_24'
30                                   `EB_FONT_30'
48                                   `EB_FONT_48'


File: eb-ja.info,  Node: Current Font Height,  Next: Get Font,  Prev: Font Size and Font Code,  Up: Local Character

選択中の外字フォントの高さ
==========================

   `EB_Book' オブジェクトで選択中の副本が用意している外字フォントの高
さの中から一つ選んで、 "選択中の外字フォントの高さ (current font
height)" として指定することができます。 EB ライブラリで外字のフォント
データ (ビットマップデータ) を取り出すには、 外字フォントの高さをあらか
じめ選択しておく必要があります。

   選択するには、関数 `eb_set_font()' を使います。 以下のプログラムは、
高さ 24 ピクセルのフォントを選択する場合の例です。

     /* `book' が `EB_Book' のオブジェクトで、すでに書籍に結び付け
      * られ、副本を選択中だと仮定しています。*/
     if (eb_set_font(&book, EB_FONT_24) != EB_SUCCESS) {
         printf("eb_set_font_() failed\n");
         return;
     }

   このプログラムでは、高さ 24 ピクセルのフォントを選択中の副本が用意し
ているものと仮定していますが、実際には用意していない副本も珍しくありま
せん。 もし、副本が高さ 24 ピクセルのフォントを用意していなければ、
`eb_set_font()' は `EB_ERR_NO_SUCH_FONT' を返します。

しかし、外字を選択する前に、前もってその副本が用意しているフォントを知
りたいときもあります。 これには、2 通りの方法があります。

   まず 1 つ目は、選択中の副本が用意しているフォントの高さの一覧を
`eb_font_list()' で取得する方法です。 これは、副本コードの一覧を取得す
る `eb_subbook_list()' と使い方が良く似ています。

     EB_Font_Code font_list[EB_MAX_FONTS];
     int font_count;
     int i;
     
     if (eb_font_list(&book, font_list, &font_count) != EB_SUCCESS) {
         printf("eb_font_list() failed\n");
         return;
     }
     
     for (i = 0; i < font_count; i++) {
         if (font_list[i] == EB_FONT_24)
             printf("this subbook has EB_FONT_24\n");
     }

   2 つ目は、`eb_have_font()' を使うやり方です。 この関数は、特定の高さ
のフォントを、選択中の副本が用意しているかどうか調べることができます。

     if (eb_have_font(&book, EB_FONT_24)) {
         printf("this subbook has EB_FONT_24\n");
     }

   また、選択中の副本が半角外字、全角外字を定義しているかどうかは、それ
ぞれ `eb_have_narrow_font()', `eb_have_wide_font()' を使って調べること
ができます。

     if (eb_have_narrow_font(&book))
         printf("this subbook has narrow font\n");
     if (eb_have_wide_font(&book))
         printf("this subbook has wide font\n");

   なお、あらかじめ副本を選択しておかないと、外字の高さは選択できないの
で注意して下さい。 `eb_set_subbook()' で選択中の副本を切り替えると、外
字フォントの高さは常に未選択の状態に戻ります。


File: eb-ja.info,  Node: Get Font,  Next: Convert Font,  Prev: Current Font Height,  Up: Local Character

外字フォントの取り出し
======================

   外字の高さを選択した状態であれば、外字のフォントデータ (ビットマップ
データ) を取り出すことができます。

   フォントデータを取り出す関数は、 全角外字なら
`eb_wide_font_character_bitmap()'、 半角外字なら
`eb_narrow_font_character_bitmap()' です。

   全角外字 `0xa121' のフォントデータを取り出すプログラムは、次のよう
になります。 半角外字の場合は、呼び出す関数名が変わるだけです。

     /* `book' が `EB_Book' のオブジェクトで、すでに書籍に結び付け
      * られ、副本と外字の高さを選択中だと仮定しています。*/
     char bitmap[EB_SIZE_WIDE_FONT_48];
     
     if (eb_wide_font_character_bitmap(book, 0xa121, bitmap)
         != EB_SUCCESS) {
         return;
     }

ここでは、`bitmap' にフォントデータを格納しています。 `bitmap' の領域と
して `EB_SIZE_WIDE_FONT_48' バイトを確保していますが、これは高さ 48 ピ
クセルの外字データを格納するために必要なサイズを表します。

   フォントデータのサイズは、外字の高さに応じて一定です。 高さ 48 ピク
セルは外字の中でも最大のサイズなので、このサイズの領域を用意すれば、ど
の高さの外字でも格納できます。

   外字データは、ビットマップ形式のデータになっています。 背景色をビッ
ト値 0, 前景色をビット値 1 として、各ピクセルの値を並べてあります。 並
び方ですが、左上からまずは右に向かってピクセルを拾っていき、左端まで来
たら一つ下の段に降りて、また右方向にピクセルを拾います。 以下、一番下の
段までこれを繰り返します。

   ただし、バイト内では、1, 2, 4, ... 128 の桁の順にビット値を格納して
います。 つまり、1 の桁は一番左のピクセル、128 の桁は一番右のピクセルに
対応します。

   以下に、 16x16
の全角外字のビットマップの例と、そのバイト列を記します。 背景色が□、前
景色が■です。

     □□□□□□□□□□□□□□□□　　0x00, 0x00,
     □□□□□□□□□□□□□□□□　　0x00, 0x00,
     □□□■■■■■■□□□■□□□　　0xf8, 0x11,
     □□□□□□□□■□■□■□□□　　0x00, 0x13,
     □□□□■□□■□□■□■□□□　　0x90, 0x14,
     □□□□■□□■■■■■■□□□　　0x90, 0x1f,
     □□■■■■■□□□■□■□□□　　0x7c, 0x14,
     □□□□□□□□□□■□■□□□　　0x00, 0x14,
     □□□■□□□□□□□□■□□□　　0x08, 0x10,
     □□□■□□□□□□□□■□□□　　0x08, 0x10,
     □□□■■■■■■■■■■□□□　　0xf8, 0x1f,
     □□□■□□□□□□□□■□□□　　0x08, 0x10,
     □□□■□□□□□□□□■□□□　　0x08, 0x10,
     □□□■■■■■■■■■■□□□　　0xf8, 0x1f,
     □□□□□□□□□□□□□□□□　　0x00, 0x00,
     □□□□□□□□□□□□□□□□　　0x00, 0x00,


File: eb-ja.info,  Node: Convert Font,  Next: Local Character in Text,  Prev: Get Font,  Up: Local Character

外字フォントの変換
==================

   EB ライブラリには、外字のビットマップデータを XBM, XPM, GIF, BMP の
各画像形式に変換する関数が用意されています。 変換を行う関数は、次の 4
つです。

eb_bitmap_to_xbm()                          XBM への変換
eb_bitmap_to_xpm()                          XPM への変換
eb_bitmap_to_gif()                          GIF への変換
eb_bitmap_to_bmp()                          BMP への変換

どの関数も呼び出し方は同じですが、ここでは XBM への変換のプログラム例
を示します。

     /* `bitmap' に高さ 16 の全角外字のビットマップデータが格納
      * されていると仮定しています。*/
     char bitmap[EB_SIZE_WIDE_FONT_16];
     char xbm[EB_SIZE_WIDE_FONT_16_XBM];
     size_t xbmsize;
     
     if (eb_wide_font_character_bitmap(bitmap, EB_WIDTH_WIDE_FONT_16,
         EB_HEIGHT_FONT_16, xbm, &xbmsize) != EB_SUCCESS) {
         return;
     }

   XPM, GIF への変換では、前景色は黒、背景色は透明になります。 BMP への
変換では、前景色は黒、背景色は白になります。 XBM はモノクロ画像用のデー
タ形式なので、色の設定はありません。


File: eb-ja.info,  Node: Local Character in Text,  Next: Font Data Types,  Prev: Convert Font,  Up: Local Character

テキスト中の外字
================

   外字はテキストデータ (本文、メニューなど) の中で使われています。

   アプリケーションプログラムが、テキストデータ中に出現する外字を識別し
て処理を行うには、外字に対するフックを設定して、フック関数の中で処理す
ることになります。

   外字に対するフックは、全角外字に対する `EB_HOOK_WIDE_FONT' と半角外
字に対する `EB_HOOK_NARROW_FONT' の二種類があります。 いずれも、外字が
一字出現する度に、設定したフック関数を呼び出します。

   フックの扱い方については、*note フックコードの一覧: Hook Code List.。


File: eb-ja.info,  Node: Font Data Types,  Next: Font Constants,  Prev: Local Character in Text,  Up: Local Character

データ型の詳細
==============

   この節で説明しているデータ型を使うには、次のようにヘッダファイルを
読み込んで下さい。

     #include <eb/eb.h>

 - Data type: EB_Font_Code
     外字コードは、外字の高さ (ピクセル数) を表します。 現在のところ、
     定義されている高さは次の通りです。

        * `EB_FONT_16'

        * `EB_FONT_24'

        * `EB_FONT_30'

        * `EB_FONT_48'

        * `EB_FONT_INVALID'

     外字コードの実体は整数値ですが、`EB_FONT_16' の値は 16 ではありま
     せん。 他も同様ですので、注意して下さい。

     `EB_FONT_INVALID' は特別な外字コードで、不正な外字コード値を表す
     ために用います。


File: eb-ja.info,  Node: Font Constants,  Next: Font Data Functions,  Prev: Font Data Types,  Up: Local Character

定数の詳細
==========

   この節で説明している定数を使うには、次のようにヘッダファイルを読み
込んで下さい。

     #include <eb/eb.h>

 - Constant: EB_WIDTH_NARROW_FONT_16
 - Constant: EB_WIDTH_NARROW_FONT_24
 - Constant: EB_WIDTH_NARROW_FONT_30
 - Constant: EB_WIDTH_NARROW_FONT_48
 - Constant: EB_WIDTH_WIDE_FONT_16
 - Constant: EB_WIDTH_WIDE_FONT_24
 - Constant: EB_WIDTH_WIDE_FONT_30
 - Constant: EB_WIDTH_WIDE_FONT_48
     これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字
     一個分の幅 (横方向のピクセル数) を `int' 型で表しています。

 - Constant: EB_HEIGHT_NARROW_FONT_16
 - Constant: EB_HEIGHT_NARROW_FONT_24
 - Constant: EB_HEIGHT_NARROW_FONT_30
 - Constant: EB_HEIGHT_NARROW_FONT_48
 - Constant: EB_HEIGHT_WIDE_FONT_16
 - Constant: EB_HEIGHT_WIDE_FONT_24
 - Constant: EB_HEIGHT_WIDE_FONT_30
 - Constant: EB_HEIGHT_WIDE_FONT_48
     これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字
     一個分の縦方向のピクセル数を `int' 型で表しています。

     `EB_HEIGHT_NARROW_FONT_16' および `EB_HEIGHT_WIDE_FONT_16' の実際
     の値は 16 です。 (外字コード `EB_FONT_16' の実際の値は 16 ではあり
     ませんので、注意して下さい。)

 - Constant: EB_SIZE_NARROW_FONT_16
 - Constant: EB_SIZE_NARROW_FONT_24
 - Constant: EB_SIZE_NARROW_FONT_30
 - Constant: EB_SIZE_NARROW_FONT_48
 - Constant: EB_SIZE_WIDE_FONT_16
 - Constant: EB_SIZE_WIDE_FONT_24
 - Constant: EB_SIZE_WIDE_FONT_30
 - Constant: EB_SIZE_WIDE_FONT_48
     これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字
     一個分のビットマップデータを格納するのに必要な領域の大きさを表し
     ています。 値は `int' 型で、単位はバイトです。

 - Constant: EB_SIZE_NARROW_FONT_16_XBM
 - Constant: EB_SIZE_NARROW_FONT_24_XBM
 - Constant: EB_SIZE_NARROW_FONT_30_XBM
 - Constant: EB_SIZE_NARROW_FONT_48_XBM
 - Constant: EB_SIZE_WIDE_FONT_16_XBM
 - Constant: EB_SIZE_WIDE_FONT_24_XBM
 - Constant: EB_SIZE_WIDE_FONT_30_XBM
 - Constant: EB_SIZE_WIDE_FONT_48_XBM
     これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字
     一個分のビットマップデータを `eb_bitmap_to_xbm()' を用いて XBM 形
     式に変換する際に、変換後の XBM
     形式のデータの大きさを表しています。 値は `int' 型で、単位はバイト
     です。

 - Constant: EB_SIZE_NARROW_FONT_16_XPM
 - Constant: EB_SIZE_NARROW_FONT_24_XPM
 - Constant: EB_SIZE_NARROW_FONT_30_XPM
 - Constant: EB_SIZE_NARROW_FONT_48_XPM
 - Constant: EB_SIZE_WIDE_FONT_16_XPM
 - Constant: EB_SIZE_WIDE_FONT_24_XPM
 - Constant: EB_SIZE_WIDE_FONT_30_XPM
 - Constant: EB_SIZE_WIDE_FONT_48_XPM
     これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字
     一個分のビットマップデータを `eb_bitmap_to_xpm()' を用いて XPM 形
     式に変換する際に、変換後の XPM
     形式のデータの大きさを表しています。 値は `int' 型で、単位はバイト
     です。

 - Constant: EB_SIZE_NARROW_FONT_16_GIF
 - Constant: EB_SIZE_NARROW_FONT_24_GIF
 - Constant: EB_SIZE_NARROW_FONT_30_GIF
 - Constant: EB_SIZE_NARROW_FONT_48_GIF
 - Constant: EB_SIZE_WIDE_FONT_16_GIF
 - Constant: EB_SIZE_WIDE_FONT_24_GIF
 - Constant: EB_SIZE_WIDE_FONT_30_GIF
 - Constant: EB_SIZE_WIDE_FONT_48_GIF
     これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字
     一個分のビットマップデータを `eb_bitmap_to_gif()' を用いて GIF 形
     式に変換する際に、変換後の GIF
     形式のデータの大きさを表しています。 値は `int' 型で、単位はバイト
     です。

 - Constant: EB_SIZE_NARROW_FONT_16_BMP
 - Constant: EB_SIZE_NARROW_FONT_24_BMP
 - Constant: EB_SIZE_NARROW_FONT_30_BMP
 - Constant: EB_SIZE_NARROW_FONT_48_BMP
 - Constant: EB_SIZE_WIDE_FONT_16_BMP
 - Constant: EB_SIZE_WIDE_FONT_24_BMP
 - Constant: EB_SIZE_WIDE_FONT_30_BMP
 - Constant: EB_SIZE_WIDE_FONT_48_BMP
     これらの定数は、半角、全角およびそれぞれの高さ (外字コード) の外字
     一個分のビットマップデータを `eb_bitmap_to_bmp()' を用いて BMP 形
     式に変換する際に、変換後の BMP
     形式のデータの大きさを表しています。 値は `int' 型で、単位はバイト
     です。


File: eb-ja.info,  Node: Font Data Functions,  Prev: Font Constants,  Up: Local Character

関数の詳細
==========

   この節で説明している関数を使うには、次のようにヘッダファイルを読み込
んで下さい。

     #include <eb/font.h>

 - Function: EB_Error_Code eb_font (EB_Book *BOOK, EB_Font_Code
          *FONT_CODE)
     関数 `eb_font()' は、選択している副本において、選択中の外字フォン
     トの高さを表す外字コードを FONT_CODE の指す領域に書き込みます。

     成功すると関数は `EB_SUCCESS' を返します。 失敗すると FONT_CODE の
     指す領域に `EB_FONT_INVALID' を書き込み、原因を示すエラーコードを
     返します。

     あらかじめ、外字フォントの高さが選択されていなければなりません。
     外字が選択されていなければ、`EB_ERR_NO_CUR_FONT' を返します。 副本
     そのものを選択していない場合も、同様です。

 - Function: EB_Error_Code eb_set_font (EB_Book *BOOK, EB_Font_Code
          FONT_CODE)
     関数 `eb_set_font()' は、選択中の副本における外字フォントの高さを
     セットします。 セットする外字フォントの「高さ」は、対応する外字コ
     ードを引数 FONT_CODE で指定します。

     この関数は、成功すると `EB_SUCCESS' を返し、指定した「高さ」が「
     選択中の外字フォントの高さ」となります。 すでに外字フォントの高さ
     を選択していた場合は、いったん未選択の状態にしてからあらためて
     FONT_CODE を選択します。

     失敗すると原因を示すエラーコードを返し、外字フォントの高さは未選択
     の状態になります。

     あらかじめ、BOOK 内のいずれかの副本が選択されていなくてはなりませ
     ん。 BOOK が副本を選択していなければ、`EB_ERR_NO_CUR_SUB' を返し
     ます。 また、その副本が持っていない外字フォントの高さが指定される
     と、 `EB_ERR_NO_SUCH_FONT' を返します。

 - Function: void eb_unset_font (EB_Book *BOOK)
     関数 `eb_unset_font()' は、選択中の外字フォントの高さを未選択の状
     態に戻します。 BOOK が書籍に結び付いていない場合や副本が選択されて
     いない場合、 もしくは外字フォントの高さが選択されていない場合は何
     もしません。

 - Function: void eb_font_list (EB_Book *BOOK, EB_Font_Code *FONT_LIST,
          int *FONT_COUNT)
     関数 `eb_font_list()' は、選択中の副本が定義している外字の高さの
     一覧を `EB_Font_Code' 型の配列にして、FONT_LIST の指す領域に書き
     込みます。

     配列は、最大で `EB_MAX_FONTS' 個の要素を持ちます。 加えて、書籍が
     収録している副本の個数を FONT_COUNT の指す領域に書き込みます。 (
     現在のバージョンでは、`EB_MAX_FONTS' の値は 4 になっています。 高
     さ 16, 24, 30, 48 ピクセルの 4 種類です。)

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、
     FONT_COUNT の指す領域に 0 を書き込み、原因を示すエラーコードを返
     します。

     あらかじめ、BOOK 内のいずれかの副本が選択されていなくてはなりませ
     ん。 BOOK が副本を選択していなければ、`EB_ERR_NO_CUR_SUB' を返し
     ます。

 - Function: int eb_have_font (EB_Book *BOOK, EB_Font_Code FONT_CODE)
     関数 `eb_font()' は、FONT_CODE で指定した高さの外字フォントを、選
     択中の副本が持っているかどうかを調べます。

     持っていれば 1 を返し、持っていなければ 0 を返します。 BOOK が副本
     を選択していない場合も 0 を返します。

 - Function: EB_Error_Code eb_font_height (EB_Book *BOOK, int *HEIGHT)
     関数 `eb_font_height()' は、BOOK が選択中の外字フォントの高さ (縦
     方向のピクセル数) を HEIGHT の指す領域に書き込みます。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、HEIGHT の
     指す領域に 0 を書き込み、原因を示すエラーコードを返します。

     あらかじめ、BOOK は外字フォントの高さを選択していなくてはなりませ
     ん。 選択していない場合は、`EB_ERR_NO_CUR_FONT' を返します。

 - Function: EB_Error_Code eb_font_height2 (EB_Font_Code FONT_CODE, int
          *HEIGHT)
     `eb_font_height()' と似ていますが、選択中の副本ではなく、引数
     FONT_HEIGHT で指定された外字コードの高さ (縦方向のピクセル数) を
     書き込む点が異なります。

 - Function: int eb_have_narrow_font (EB_Book *BOOK)
 - Function: int eb_have_wide_font (EB_Book *BOOK)
     関数 `eb_have_narrow_font()' は、選択中の副本が半角外字を定義して
     いるかどうかを調べます。 同様に、関数 `eb_have_wide_font()' は、全
     角外字を定義しているかどうかを調べます。

     定義していれば 1 を、定義していなければ 0 を返します。 BOOK が副本
     を選択していない場合も 0 を返します。

 - Function: EB_Error_Code eb_narrow_font_width (EB_Book *BOOK, int
          *WIDTH)
 - Function: EB_Error_Code eb_wide_font_width (EB_Book *BOOK, int
          *WIDTH)
     関数 `eb_narrow_font_width()' は、BOOK が選択中の外字フォントの高
     さにおける半角外字の幅 (横方向のピクセル数) を、HEIGHT の指す領域
     に書き込みます。 同様に、`eb_wide_font_width()' は全角外字の幅を書
     き込みます。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、WIDTH の
     指す領域に 0 を書き込み、原因を示すエラーコードを返します。

     あらかじめ、BOOK は外字の高さを選択していなくてはなりません。 選択
     していない場合は、`EB_ERR_NO_CUR_FONT' を返します。

 - Function: EB_Error_Code eb_narrow_font_width2 (EB_Font_Code
          FONT_CODE, int *WIDTH)
 - Function: EB_Error_Code eb_wide_font_width2 (EB_Font_Code FONT_CODE,
          int *WIDTH)
     `eb_narrow_font_width()', `eb_wide_font_width()' と似ていますが、
     選択中の副本ではなく、引数 FONT_HEIGHT で指定された外字コードの幅
     (横方向のピクセル数) を書き込む点が異なります。

 - Function: EB_Error_Code eb_narrow_font_size (EB_Book *BOOK, size_t
          *SIZE)
 - Function: EB_Error_Code eb_wide_font_size (EB_Book *BOOK, size_t
          *SIZE)
     関数 `eb_narrow_font_size()' は、BOOK が選択中の外字フォントの高
     さにおける半角外字一個分のデータサイズ (バイト数) を、SIZE の指す
     領域に書き込みます。 同様に、`eb_wide_font_size()' は全角外字のサ
     イズを書き込みます。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、SIZE の指
     す領域に 0 を書き込み、原因を示すエラーコードを返します。

     あらかじめ、BOOK は外字フォントの高さを選択していなくてはなりませ
     ん。 選択していない場合は、`EB_ERR_NO_CUR_FONT' を返します。

 - Function: EB_Error_Code eb_narrow_font_size2 (EB_Font_Code
          FONT_CODE, size_t *SIZE)
 - Function: EB_Error_Code eb_wide_font_size2 (EB_Font_Code FONT_CODE,
          size_t *SIZE)
     `eb_narrow_font_size()', `eb_wide_font_size()' と似ていますが、 選
     択中の副本ではなく、引数 FONT_HEIGHT で指定された外字コードの外字
     一個分のデータサイズを書き込む点が異なります。

 - Function: EB_Error_Code eb_narrow_font_start (EB_Book *BOOK, int
          *START)
 - Function: EB_Error_Code eb_wide_font_start (EB_Book *BOOK, int
          *START)
     関数 `eb_narrow_font_start()' は、BOOK が選択中の副本における半角
     外字の先頭の文字番号 (半角外字の文字番号の中で最小のもの) を、
     START の指す領域に書き込みます。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、原因を示
     すエラーコードを返します。

     あらかじめ、BOOK は副本を選択していなくてはなりません。 選択してい
     ない場合は、`EB_ERR_NO_CUR_SUB' を返します。 副本が半角外字を定義
     していない場合は、`EB_ERR_NO_CUR_FONT' を返します。

     関数 `eb_wide_font_start()' は、半角外字ではなく全角外字について
     調べるという点を除いて、`eb_narrow_font_start()' と同じです。

 - Function: EB_Error_Code eb_narrow_font_end (EB_Book *BOOK, int *END)
 - Function: EB_Error_Code eb_wide_font_end (EB_Book *BOOK, int *END)
     関数 `eb_narrow_font_end()' は、BOOK が選択中の副本における半角外
     字の最後の文字番号 (半角外字の文字番号の中で最大のもの) を、 START
     の指す領域に書き込みます。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、原因を示
     すエラーコードを返します。

     あらかじめ、BOOK は副本を選択していなくてはなりません。 選択してい
     ない場合は、`EB_ERR_NO_CUR_SUB' を返します。 副本が半角外字を定義
     していない場合は、`EB_ERR_NO_CUR_FONT' を返します。

     関数 `eb_wide_font_end()' は、半角外字ではなく全角外字について調
     べるという点を除いて、`eb_narrow_font_end()' と同じです。

 - Function: EB_Error_Code eb_narrow_font_character_bitmap (EB_Book
          *BOOK, int CHARACTER_NUMBER, char *BITMAP)
 - Function: EB_Error_Code eb_wide_font_character_bitmap (EB_Book
          *BOOK, int CHARACTER_NUMBER, char *BITMAP)
     関数 `eb_narrow_font_character_bitmap()' は、BOOK が選択中の副本
     で定義している、半角外字のビットマップデータを取り出します。 取り
     出す外字の文字番号を、CHARACTER_NUMBER で指定します。

     成功すると、関数はビットマップデータを BITMAP
     の指す領域に書き込み、 `EB_SUCCESS' を返します。 失敗すると、
     BITMAP の指す領域に空文字列を書き込み、原因を示すエラーコードを返
     します。

     あらかじめ、BOOK は外字フォントの高さを選択していなくてはなりませ
     ん。 選択していない場合は、`EB_ERR_NO_CUR_FONT' を返します。 副本
     が半角外字を定義していない場合も、やはり `EB_ERR_NO_CUR_FONT' を返
     します。 文字番号 CHARACTER_NUMBER
     が外字の定義範囲外にある場合は、 `EB_ERR_NO_SUCH_CHAR_BMP' を返し
     ます。

     関数 `eb_wide_font_character_bitmap()' は、半角外字ではなく全角外
     字のビットマップデータを取り出すという点を除いて、
     `eb_narrow_font_character_bitmap()' と同じです。

     ビットマップデータの形式については、 *note 外字フォントの取り出し :
     Get Font.。

 - Function: EB_Error_Code eb_forward_narrow_font_character (EB_Book
          *BOOK, int N, int *CHARACTER_NUMBER)
 - Function: EB_Error_Code eb_forward_wide_font_character (EB_Book
          *BOOK, int N, int *CHARACTER_NUMBER)
     関数 `eb_forward_narrow_font_character()' は、BOOK が選択中の副本
     で定義されている半角外字の文字番号 CHARACTER_NUMBER の N 個後ろに
     位置する外字の文字番号を取得します。

     まず、関数を呼び出す際に、CHARACTER_NUMBER の指す領域に文字番号を
     書き込んでおきます。 関数の処理が成功すると、戻ったときに N 個分だ
     け後方の文字番号に書き換わっています。

     成功すると、関数は `EB_SUCCESS' を返します。 失敗すると、原因を示
     すエラーコードを返します。

     あらかじめ、BOOK は副本を選択していなくてはなりません。 選択してい
     ない場合は、`EB_ERR_NO_CUR_SUB' を返します。 副本が半角外字を持っ
     ていない場合は、`EB_ERR_NO_CUR_FONT' を返します。

     N 個後ろにもう外字がない場合や、呼び出した際に CHARACTER_NUMBER の
     指す領域に書き込んであった文字番号が外字の定義範囲外にある場合は
     `EB_ERR_NO_SUCH_CHAR_BMP' を返します。

     N には負の数を指定することもできます。 この場合、次の呼び出しと等
     価になります。

          /* n < 0 とする */
          eb_backward_narrow_font_character (book, -n, character_number);

     関数 `eb_forward_wide_font_character()' は、半角外字ではなく全角
     外字について操作するという点を除いて、
     `eb_forward_narrow_font_character()' と同じです。

 - Function: EB_Error_Code eb_backward_narrow_font_character (EB_Book
          *BOOK, int N, int *CHARACTER_NUMBER)
 - Function: EB_Error_Code eb_backward_wide_font_character (EB_Book
          *BOOK, int N, int *CHARACTER_NUMBER)
     関数 `eb_backward_narrow_font_character()' は
     `eb_forward_narrow_font_character()' とはちょうど逆の関数です。
     BOOK が選択中の副本で定義されている半角外字の文字番号
     CHARACTER_NUMBER の N
     個前方に位置する外字の文字番号を取得します。

     同様に、 `eb_backward_wide_font_character()' は、全角外字について N
     個前方の外字の文字番号を取得する関数で、
     `eb_forward_wide_font_character()' と反対の関数です。

     N には負の数を指定することも可能で、それぞれ次の呼び出しと等価に
     なります。

          /* 半角外字の場合 (n < 0) */
          eb_forward_narrow_font_character (book, -n, character_number);
          
          /* 全角外字の場合 (n < 0) */
          eb_forward_wide_font_character (book, -n, character_number);

 - Function: EB_Error_Code eb_narrow_font_xbm_size (EB_Font_Code
          HEIGHT, size_t *SIZE)
 - Function: EB_Error_Code eb_narrow_font_xpm_size (EB_Font_Code
          HEIGHT, size_t *SIZE)
 - Function: EB_Error_Code eb_narrow_font_gif_size (EB_Font_Code
          HEIGHT, size_t *SIZE)
 - Function: EB_Error_Code eb_narrow_font_bmp_size (EB_Font_Code
          HEIGHT, size_t *SIZE)
 - Function: EB_Error_Code eb_wide_font_xbm_size (EB_Font_Code HEIGHT,
          size_t *SIZE)
 - Function: EB_Error_Code eb_wide_font_xpm_size (EB_Font_Code HEIGHT,
          size_t *SIZE)
 - Function: EB_Error_Code eb_wide_font_gif_size (EB_Font_Code HEIGHT,
          size_t *SIZE)
 - Function: EB_Error_Code eb_wide_font_bmp_size (EB_Font_Code HEIGHT,
          size_t *SIZE)
     最初の 4 つの関数 (`eb_narrow_font_xbm_size()' 〜
     `eb_narrow_font_bmp_size()') は、外字コード HEIGHT の半角外字一個
     のビットマップを XBM, XPM, GIF, BMP 形式にそれぞれ変換したときの
     データサイズを SIZE の指す領域に書き込みます。

     同様に、後ろの 4 つの関数 (`eb_wide_font_xbm_size()' 〜
     `eb_wide_font_bmp_size()') は、全角外字を変換したときのデータサイ
     ズを書き込みます。

     いずれの関数も、成功すると `EB_SUCCESS' を返します。 失敗すると、
     SIZE の指す領域に 0
     を書き込み、原因を示すエラーコードを返します。

 - Function: void eb_bitmap_to_xbm (const char *BITMAP, int WIDTH, int
          HEIGHT, char *IMAGE, size_t *IMAGE_LENGTH)
 - Function: void eb_bitmap_to_xpm (const char *BITMAP, int WIDTH, int
          HEIGHT, char *IMAGE, size_t *IMAGE_LENGTH)
 - Function: void eb_bitmap_to_gif (const char *BITMAP, int WIDTH, int
          HEIGHT, char *IMAGE, size_t *IMAGE_LENGTH)
 - Function: void eb_bitmap_to_bmp (const char *BITMAP, int WIDTH, int
          HEIGHT, char *IMAGE, size_t *IMAGE_LENGTH)
     これら 4 つの関数は、 `eb_narrow_font_character()' または
     `eb_wide_font_character()' で取り出した外字のビットマップを XBM,
     XPM, GIF, BMP 形式にそれぞれ変換します。

     ビットマップデータの指す領域を BITMAP で指定し、ビットマップの高
     さと幅を WIDTH, HEIGHT で渡します。

     関数の呼び出しから戻ると、IMAGE の指す領域に変換後のデータが書き
     込まれ、IMAGE_LENGTH の指す領域に変換後のデータの大きさが書き込ま
     れます。

     XPM, GIF への変換では、前景色は黒、背景色は透明になります。 BMP へ
     の変換では、前景色は黒、背景色は白になります。 XBM はモノクロ画像
     用のデータ形式なので、色の設定はありません。


File: eb-ja.info,  Node: Index,  Prev: Local Character,  Up: Top

索引
****

* Menu:

* Data Type Index::             データ型の索引
* Function Index::              関数の索引
* Variable Index::              変数と定数の索引


File: eb-ja.info,  Node: Data Type Index,  Next: Function Index,  Prev: Index,  Up: Index

データ型の索引
==============

* Menu:

* Book:                                  EB_Book Data Types.
* Character_Code:                        EB_Book Data Types.
* Disc_Code:                             EB_Book Data Types.
* Error_Code:                            Error Data Types.
* Font_Code:                             Font Data Types.
* Hit:                                   Search Data Types.
* Hook:                                  Text Data Types.
* Hook_Code:                             Text Data Types.
* Hookset:                               Text Data Types.
* Multi_Search_Code:                     Search Data Types.
* Position:                              Search Data Types.
* Subbook_Code:                          Subbook Data Types.


File: eb-ja.info,  Node: Function Index,  Next: Variable Index,  Prev: Data Type Index,  Up: Index

関数の索引
==========

* Menu:

* backward_narrow_font_character:        Font Data Functions.
* backward_text:                         Text Data Functions.
* backward_wide_font_character:          Font Data Functions.
* bind:                                  EB_Book Functions.
* bitmap_to_bmp:                         Font Data Functions.
* bitmap_to_gif:                         Font Data Functions.
* bitmap_to_xbm:                         Font Data Functions.
* bitmap_to_xpm:                         Font Data Functions.
* character_code:                        EB_Book Functions.
* copyright:                             Text Data Functions.
* current_candidate:                     Text Data Functions.
* disc_type:                             EB_Book Functions.
* error_message:                         Error Functions.
* error_string:                          Error Functions.
* finalize_book:                         EB_Book Functions.
* finalize_hookset:                      Hookset Access Functions.
* finalize_library:                      Init and Exit Functions.
* font:                                  Font Data Functions.
* font_height:                           Font Data Functions.
* font_height2:                          Font Data Functions.
* font_list:                             Font Data Functions.
* forward_narrow_font_character:         Font Data Functions.
* forward_text:                          Text Data Functions.
* forward_wide_font_character:           Font Data Functions.
* have_copyright:                        Text Data Functions.
* have_endword_search:                   Search Functions.
* have_exactword_search:                 Search Functions.
* have_font:                             Font Data Functions.
* have_menu:                             Text Data Functions.
* have_multi_search:                     Search Functions.
* have_narrow_font:                      Font Data Functions.
* have_text:                             Text Data Functions.
* have_wide_font:                        Font Data Functions.
* have_word_search:                      Search Functions.
* hit_list:                              Search Functions.
* hook_empty:                            Builtin Hook Functions.
* hook_euc_to_ascii:                     Builtin Hook Functions.
* hook_narrow_character_text:            Builtin Hook Functions.
* hook_newline:                          Builtin Hook Functions.
* hook_wide_character_text:              Builtin Hook Functions.
* initialize_book:                       EB_Book Functions.
* initialize_hookset:                    Hookset Access Functions.
* initialize_library:                    Init and Exit Functions.
* is_bound:                              EB_Book Functions.
* is_text_stopped:                       Text Data Functions.
* load_all_subbooks:                     Subbook Functions.
* menu:                                  Text Data Functions.
* multi_entry_count:                     Search Functions.
* multi_entry_have_candidates:           Search Functions.
* multi_entry_label:                     Search Functions.
* multi_search_list:                     Search Functions.
* narrow_font_bmp_size:                  Font Data Functions.
* narrow_font_character_bitmap:          Font Data Functions.
* narrow_font_end:                       Font Data Functions.
* narrow_font_gif_size:                  Font Data Functions.
* narrow_font_size:                      Font Data Functions.
* narrow_font_size2:                     Font Data Functions.
* narrow_font_start:                     Font Data Functions.
* narrow_font_width:                     Font Data Functions.
* narrow_font_width2:                    Font Data Functions.
* narrow_font_xbm_size:                  Font Data Functions.
* narrow_font_xpm_size:                  Font Data Functions.
* path:                                  EB_Book Functions.
* read_heading:                          Text Data Functions.
* read_rawtext:                          Text Data Functions.
* read_text:                             Text Data Functions.
* search_endword:                        Search Functions.
* search_keyword:                        Search Functions.
* search_multi:                          Search Functions.
* search_word:                           Search Functions.
* seek_text:                             Text Data Functions.
* set_font:                              Font Data Functions.
* set_hook:                              Hookset Access Functions.
* set_hooks:                             Hookset Access Functions.
* set_subbook:                           Subbook Functions.
* subbook:                               Subbook Functions.
* subbook_directory:                     Subbook Functions.
* subbook_list:                          Subbook Functions.
* subbook_title:                         Subbook Functions.
* subbook_title2:                        Subbook Functions.
* tell_text:                             Text Data Functions.
* text:                                  Text Data Functions.
* unset_font:                            Font Data Functions.
* unset_subbook:                         Subbook Functions.
* wide_font_bmp_size:                    Font Data Functions.
* wide_font_character_bitmap:            Font Data Functions.
* wide_font_end:                         Font Data Functions.
* wide_font_gif_size:                    Font Data Functions.
* wide_font_size:                        Font Data Functions.
* wide_font_size2:                       Font Data Functions.
* wide_font_start:                       Font Data Functions.
* wide_font_width:                       Font Data Functions.
* wide_font_width2:                      Font Data Functions.
* wide_font_xbm_size:                    Font Data Functions.
* wide_font_xpm_size:                    Font Data Functions.
* write_text:                            Text Data Functions.
* write_text_byte1:                      Text Data Functions.
* write_text_byte2:                      Text Data Functions.
* write_text_string:                     Text Data Functions.


File: eb-ja.info,  Node: Variable Index,  Prev: Function Index,  Up: Index

変数と定数の索引
================

* Menu:

* CHARCODE_INVALID:                      EB_Book Data Types.
* CHARCODE_ISO8859_1:                    EB_Book Data Types.
* CHARCODE_JISX0208:                     EB_Book Data Types.
* CHARCODE_JISX0208_GB2312:              EB_Book Data Types.
* DISC_EB:                               EB_Book Data Types.
* DISC_EPWING:                           EB_Book Data Types.
* DISC_INVALID:                          EB_Book Data Types.
* ERR_BAD_DIR_NAME:                      Error Code List.
* ERR_BAD_FILE_NAME:                     Error Code List.
* ERR_BAD_WORD:                          Error Code List.
* ERR_DIFF_CONTENT:                      Error Code List.
* ERR_EMPTY_WORD:                        Error Code List.
* ERR_END_OF_CONTENT:                    Error Code List.
* ERR_FAIL_GETCWD:                       Error Code List.
* ERR_FAIL_OPEN_APP:                     Error Code List.
* ERR_FAIL_OPEN_BINARY:                  Error Code List.
* ERR_FAIL_OPEN_CAT:                     Error Code List.
* ERR_FAIL_OPEN_CATAPP:                  Error Code List.
* ERR_FAIL_OPEN_FONT:                    Error Code List.
* ERR_FAIL_OPEN_TEXT:                    Error Code List.
* ERR_FAIL_READ_APP:                     Error Code List.
* ERR_FAIL_READ_BINARY:                  Error Code List.
* ERR_FAIL_READ_CAT:                     Error Code List.
* ERR_FAIL_READ_CATAPP:                  Error Code List.
* ERR_FAIL_READ_FONT:                    Error Code List.
* ERR_FAIL_READ_TEXT:                    Error Code List.
* ERR_FAIL_SEEK_APP:                     Error Code List.
* ERR_FAIL_SEEK_BINARY:                  Error Code List.
* ERR_FAIL_SEEK_CAT:                     Error Code List.
* ERR_FAIL_SEEK_CATAPP:                  Error Code List.
* ERR_FAIL_SEEK_FONT:                    Error Code List.
* ERR_FAIL_SEEK_TEXT:                    Error Code List.
* ERR_MEMORY_EXHAUSTED:                  Error Code List.
* ERR_NO_APPSUB:                         Error Code List.
* ERR_NO_CANDIDATES:                     Error Code List.
* ERR_NO_CUR_APPSUB:                     Error Code List.
* ERR_NO_CUR_BINARY:                     Error Code List.
* ERR_NO_CUR_FONT:                       Error Code List.
* ERR_NO_CUR_SUB:                        Error Code List.
* ERR_NO_FONT:                           Error Code List.
* ERR_NO_PREV_SEARCH:                    Error Code List.
* ERR_NO_PREV_SEEK:                      Error Code List.
* ERR_NO_SUB:                            Error Code List.
* ERR_NO_SUCH_APPSUB:                    Error Code List.
* ERR_NO_SUCH_BINARY:                    Error Code List.
* ERR_NO_SUCH_CHAR_BMP:                  Error Code List.
* ERR_NO_SUCH_CHAR_TEXT:                 Error Code List.
* ERR_NO_SUCH_ENTRY_ID:                  Error Code List.
* ERR_NO_SUCH_FONT:                      Error Code List.
* ERR_NO_SUCH_HOOK:                      Error Code List.
* ERR_NO_SUCH_MULTI_ID:                  Error Code List.
* ERR_NO_SUCH_SEARCH:                    Error Code List.
* ERR_NO_SUCH_SUB:                       Error Code List.
* ERR_NO_TEXT:                           Error Code List.
* ERR_NO_WORD:                           Error Code List.
* ERR_TOO_LONG_FILE_NAME:                Error Code List.
* ERR_TOO_LONG_WORD:                     Error Code List.
* ERR_TOO_MANY_WORDS:                    Error Code List.
* ERR_UNBOUND_APP:                       Error Code List.
* ERR_UNBOUND_BOOK:                      Error Code List.
* ERR_UNEXP_APP:                         Error Code List.
* ERR_UNEXP_BINARY:                      Error Code List.
* ERR_UNEXP_CAT:                         Error Code List.
* ERR_UNEXP_CATAPP:                      Error Code List.
* ERR_UNEXP_FONT:                        Error Code List.
* ERR_UNEXP_TEXT:                        Error Code List.
* FONT_16:                               Font Data Types.
* FONT_24:                               Font Data Types.
* FONT_30:                               Font Data Types.
* FONT_48:                               Font Data Types.
* FONT_INVALID:                          Font Data Types.
* HEIGHT_NARROW_FONT_16:                 Font Constants.
* HEIGHT_NARROW_FONT_24:                 Font Constants.
* HEIGHT_NARROW_FONT_30:                 Font Constants.
* HEIGHT_NARROW_FONT_48:                 Font Constants.
* HEIGHT_WIDE_FONT_16:                   Font Constants.
* HEIGHT_WIDE_FONT_24:                   Font Constants.
* HEIGHT_WIDE_FONT_30:                   Font Constants.
* HEIGHT_WIDE_FONT_48:                   Font Constants.
* HOOK_BEGIN_CANDIDATE:                  Hook Code List.
* HOOK_BEGIN_COLOR_BMP:                  Hook Code List.
* HOOK_BEGIN_COLOR_JPEG:                 Hook Code List.
* HOOK_BEGIN_EMPHASIS:                   Hook Code List.
* HOOK_BEGIN_GRAY_GRAPHIC:               Hook Code List.
* HOOK_BEGIN_IN_COLOR_BMP:               Hook Code List.
* HOOK_BEGIN_IN_COLOR_JPEG:              Hook Code List.
* HOOK_BEGIN_KEYWORD:                    Hook Code List.
* HOOK_BEGIN_MONO_GRAPHIC:               Hook Code List.
* HOOK_BEGIN_MPEG:                       Hook Code List.
* HOOK_BEGIN_NARROW:                     Hook Code List.
* HOOK_BEGIN_NO_NEWLINE:                 Hook Code List.
* HOOK_BEGIN_REFERENCE:                  Hook Code List.
* HOOK_BEGIN_SUBSCRIPT:                  Hook Code List.
* HOOK_BEGIN_SUPERSCRIPT:                Hook Code List.
* HOOK_BEGIN_WAVE:                       Hook Code List.
* HOOK_END_CANDIDATE_GROUP:              Hook Code List.
* HOOK_END_CANDIDATE_LEAF:               Hook Code List.
* HOOK_END_COLOR_GRAPHIC:                Hook Code List.
* HOOK_END_EMPHASIS:                     Hook Code List.
* HOOK_END_GRAY_GRAPHIC:                 Hook Code List.
* HOOK_END_IN_COLOR_GRAPHIC:             Hook Code List.
* HOOK_END_KEYWORD:                      Hook Code List.
* HOOK_END_MONO_GRAPHIC:                 Hook Code List.
* HOOK_END_MPEG:                         Hook Code List.
* HOOK_END_NARROW:                       Hook Code List.
* HOOK_END_NO_NEWLINE:                   Hook Code List.
* HOOK_END_REFERENCE:                    Hook Code List.
* HOOK_END_SUBSCRIPT:                    Hook Code List.
* HOOK_END_SUPERSCRIPT:                  Hook Code List.
* HOOK_END_WAVE:                         Hook Code List.
* HOOK_GB2312:                           Hook Code List.
* HOOK_INITIALIZE:                       Hook Code List.
* HOOK_ISO8859_1:                        Hook Code List.
* HOOK_NARROW_FONT:                      Hook Code List.
* HOOK_NARROW_JISX0208:                  Hook Code List.
* HOOK_NEWLINE:                          Hook Code List.
* HOOK_NULL:                             Hook Code List.
* HOOK_SET_INDENT:                       Hook Code List.
* HOOK_WIDE_FONT:                        Hook Code List.
* HOOK_WIDE_JISX0208:                    Hook Code List.
* MAX_DIRECTORY_NAME_LENGTH:             Subbook Functions.
* MAX_FONTS:                             Font Data Functions.
* MAX_KEYWORDS:                          Search Functions.
* MAX_MULTI_ENTRIES:                     Search Functions.
* MAX_MULTI_ENTRY_LABEL_LENGTH:          Search Functions.
* MAX_MULTI_SEARCHES:                    Search Functions.
* MAX_PATH_LENGTH:                       EB_Book Functions.
* MAX_SUBBOOKS:                          Subbook Functions.
* MAX_TITLE_LENGTH:                      Subbook Functions.
* MAX_WORD_LENGTH:                       Search Functions.
* MULTI_INVALID:                         Search Data Types.
* NUMBER_OF_ERRORS:                      Error Data Types.
* NUMBER_OF_HOOKS:                       Text Data Types.
* SIZE_NARROW_FONT_16:                   Font Constants.
* SIZE_NARROW_FONT_16_BMP:               Font Constants.
* SIZE_NARROW_FONT_16_GIF:               Font Constants.
* SIZE_NARROW_FONT_16_XBM:               Font Constants.
* SIZE_NARROW_FONT_16_XPM:               Font Constants.
* SIZE_NARROW_FONT_24:                   Font Constants.
* SIZE_NARROW_FONT_24_BMP:               Font Constants.
* SIZE_NARROW_FONT_24_GIF:               Font Constants.
* SIZE_NARROW_FONT_24_XBM:               Font Constants.
* SIZE_NARROW_FONT_24_XPM:               Font Constants.
* SIZE_NARROW_FONT_30:                   Font Constants.
* SIZE_NARROW_FONT_30_BMP:               Font Constants.
* SIZE_NARROW_FONT_30_GIF:               Font Constants.
* SIZE_NARROW_FONT_30_XBM:               Font Constants.
* SIZE_NARROW_FONT_30_XPM:               Font Constants.
* SIZE_NARROW_FONT_48:                   Font Constants.
* SIZE_NARROW_FONT_48_BMP:               Font Constants.
* SIZE_NARROW_FONT_48_GIF:               Font Constants.
* SIZE_NARROW_FONT_48_XBM:               Font Constants.
* SIZE_NARROW_FONT_48_XPM:               Font Constants.
* SIZE_WIDE_FONT_16:                     Font Constants.
* SIZE_WIDE_FONT_16_BMP:                 Font Constants.
* SIZE_WIDE_FONT_16_GIF:                 Font Constants.
* SIZE_WIDE_FONT_16_XBM:                 Font Constants.
* SIZE_WIDE_FONT_16_XPM:                 Font Constants.
* SIZE_WIDE_FONT_24:                     Font Constants.
* SIZE_WIDE_FONT_24_BMP:                 Font Constants.
* SIZE_WIDE_FONT_24_GIF:                 Font Constants.
* SIZE_WIDE_FONT_24_XBM:                 Font Constants.
* SIZE_WIDE_FONT_24_XPM:                 Font Constants.
* SIZE_WIDE_FONT_30:                     Font Constants.
* SIZE_WIDE_FONT_30_BMP:                 Font Constants.
* SIZE_WIDE_FONT_30_GIF:                 Font Constants.
* SIZE_WIDE_FONT_30_XBM:                 Font Constants.
* SIZE_WIDE_FONT_30_XPM:                 Font Constants.
* SIZE_WIDE_FONT_48:                     Font Constants.
* SIZE_WIDE_FONT_48_BMP:                 Font Constants.
* SIZE_WIDE_FONT_48_GIF:                 Font Constants.
* SIZE_WIDE_FONT_48_XBM:                 Font Constants.
* SIZE_WIDE_FONT_48_XPM:                 Font Constants.
* SUBBOOK_INVALID:                       Subbook Data Types.
* SUCCESS:                               Error Code List.
* WIDTH_NARROW_FONT_16:                  Font Constants.
* WIDTH_NARROW_FONT_24:                  Font Constants.
* WIDTH_NARROW_FONT_30:                  Font Constants.
* WIDTH_NARROW_FONT_48:                  Font Constants.
* WIDTH_WIDE_FONT_16:                    Font Constants.
* WIDTH_WIDE_FONT_24:                    Font Constants.
* WIDTH_WIDE_FONT_30:                    Font Constants.
* WIDTH_WIDE_FONT_48:                    Font Constants.



Tag Table:
Node: Top1012
Node: Introduction4796
Node: Electronic Book and EPWING6637
Node: Construction of This Book7750
Node: Features8889
Node: Header Files9872
Node: Character Code10811
Node: Compressed Book14724
Node: Traditional System15697
Node: Compilation16717
Node: Compilation Simple Way18070
Node: Compilation with Autoconf21454
Node: Init and Exit23526
Node: Init and Exit Sample24314
Node: Init and Exit Functions25358
Node: EB_Book27020
Node: EB_Book Explanation27692
Node: EB_Book Sample29947
Node: EB_Book Data Types32414
Node: EB_Book Functions34679
Node: Error Handling39035
Node: Error Code and Message39872
Node: Tolerance to Error41625
Node: Error Data Types42978
Node: Error Code List43699
Node: Error Functions51686
Node: Subbook53343
Node: Subbook Code54614
Node: Current Subbook56224
Node: Subbook Sample58259
Node: Subbook Data Types60829
Node: Subbook Functions61568
Node: Search67357
Node: Word Search68449
Node: Keyword Search71329
Node: Multi Search72785
Node: EB_Hit76252
Node: Get Remained Entries77838
Node: Search Data Types79132
Node: Search Functions81064
Node: Text Data92558
Node: Seek and Read Text Data94015
Node: Text Data Format97880
Node: Hook100567
Node: Hook and Character Code104724
Node: Copyright Notice106818
Node: Menu107963
Node: Multi Candidates111872
Node: Stop Code Issue115809
Node: Text Data Sample118233
Node: Text Data Types122664
Node: Hook Function Details124517
Node: Hook Code List126891
Node: Hookset Access Functions141835
Node: Builtin Hook Functions144911
Node: Text Data Functions148087
Node: Local Character164474
Node: Narrow & Wide Font166205
Node: Font Size and Font Code168342
Node: Current Font Height169903
Node: Get Font172475
Node: Convert Font175103
Node: Local Character in Text176266
Node: Font Data Types176922
Node: Font Constants177665
Node: Font Data Functions181728
Node: Index195799
Node: Data Type Index196027
Node: Function Index196876
Node: Variable Index203115

End Tag Table
