-*- outline -*-

[APEL の README (日本語版)]

* APEL とは？

APEL は "A Portable Emacs Library." の略です。これは以下のモジュールで
構成されています:

** poe.el

主に最新の emacs 環境のための基礎的な関数と特殊形式/マクロの emulation
のモジュール。

  poe-xemacs.el  --- XEmacs用
  poe-18.el	 --- Emacs 18/Nemacs 用
  env.el         --- Emacs 18 用の env.el
  localhook.el   --- Emacs 18 と Emacs 19.28 以前用の hook 関数群
  pym.el         --- poe のための macros

** poem.el

移植性の高い MULE プログラムを書くための基礎的な関数を提供する。

  poem-nemacs.el --- Nemacs 用
  poem-ltn1.el   --- MULE なし Emacs 19/XEmacs 用
  poem-om.el     --- MULE 1.*, 2.* 用
  poem-20.el     --- Emacs 20 と XEmacs-MULE の共有モジュール
  poem-e20_2.el  --- Emacs 20.1/20.2 用
  poem-e20_3.el  --- Emacs 20.3 用
  poem-xm.el     --- XEmacs-MULE 用

** pces.el

移植性の高い character encoding スキーム (coding-system) を提供する。

  pces-20.el     --- coding-system 機能を持つ Emacs 20 and XEmacs 用
  pces-e20.el    --- Emacs 20 用
  pces-e20_2.el  --- Emacs 20.1 and 20.2 用
  pces-nemacs.el --- Nemacs 用
  pces-om.el     --- Mule 1.* and Mule 2.* 用
  pces-raw.el    --- coding-system 機能を持たない emacsen 用
  pces-xfc.el    --- file coding 機能を持つ XEmacs 用
  pces-xm.el     --- XEmacs-mule 用

** invisible.el --- 不可視 region に関する機能を提供する

  inv-18.el     --- for Emacs 18
  inv-19.el     --- for Emacs 19
  inv-xemacs.el --- for XEmacs

** mcharset.el --- MIME charset 関連の機能を提供する

  mcs-nemacs.el --- Nemacs 用
  mcs-ltn1.el   --- MULE Emacs 19/XEmacs 用
  mcs-om.el     --- MULE 1.*, 2.* 用
  mcs-20.el     --- Emacs 20 と XEmacs-MULE 用の共有モジュール
  mcs-e20.el    --- Emacs 20 用
  mcs-xm.el     --- XEmacs-MULE 用
  mcs-xmu.el    --- XEmacs-MULE 用 (ISO646 文字の単一化)

** static.el --- 静的評価のためのユーティリティー

** broken.el --- Emacs の壊れている機能の情報を提供する

** pccl.el --- 移植可能な CCL プログラムを書くためのユーティリティー

  pccl-om.el --- MULE 2.* 用
  pccl-20.el --- Emacs 20/XEmacs-21-MULE 用

** alist.el: 連想リストのためのユーティリティー

** calist.el: 状態木と状態/状況連想リスト用のユーティリティー

** path-util.el: パス管理とファイル探索のためのユーティリティー

** filename.el:ファイル名を作るためのユーティリティ

** install.el: emacs-lisp パッケージインストールするためのユーティリティー

** mule-caesar.el: ROT 13-47-48 Caesar 変換のユーティリティー

** emu.el

tm-7.106 に入っていた emu との互換性を保つためのモジュール。poe, poem,
mcharset を require する。

  emu-mule:	MULE 1.*, 2.* 用

  richtext.el   --- Emacs 19.29 かそれ以降 XEmacs 19.14 かそれ以降のた
                    めの text/richtext モジュール
  tinyrich.el   --- 古い emacs 環境のための text/richtext モジュール

** pcustom.el --- 移植性の高い custom 環境を提供する

  tinycustom.el --- custom.el のエミュレーションを行なう

** timezone.el

タイムゾーンユーティリティ。2000 年問題対応版。Emacs 18 と GNUS 3.14.4
でも動作可。

** product.el --- プロダクトのバージョン情報のための機能を提供するモジュール。


* インストール

** 展開した場所で実行

他のディレクトリーにインストールしたくないなら、以下のことだけをやって
ください (MS-DOS 系の OS のために MAKEIT.BAT が用意されています。
MAKEIT.BAT の利用については下記「MAKEIT.BAT を利用する (MS-DOS 系 OS
の場合)」を参照して下さい)。:

  % make

emacs のコマンド名を指定することができます。例えば、

  % make EMACS=xemacs

`EMACS=...' が省略されると、Emacs=emacs が使われます。

** make install

他のディレクトリーにインストールしたいなら、以下のことをしてください:

  % make install

emacs のコマンド名を指定することができます。例えば、

  % make install EMACS=xemacs

`EMACS=...' が省略されると、Emacs=emacs が使われます。

Emacs Lisp プログラムとシェルスクリプトのためのディレクトリー木の接頭
辞 (prefix) を指定することができます。例えば、

  % make install PREFIX=~/

`PREFIX=...' が省略されると、指定された emacs コマンドのディレクトリー
木の接頭辞が使用されます (おそらく /usr/local です)。

例えば、PREFIX=/usr/local と Emacs 20.2 が指定されれば、以下のディレク
トリー木が作成されます。

  /usr/local/share/emacs/20.2/site-lisp/	--- emu
  /usr/local/share/emacs/site-lisp/apel/	--- APEL

Emacs Lisp プログラムのための lisp ディレクトリーを指定することができ
ます。例えば、:

  % make install LISPDIR=~/elisp

emu モジュールがインストールされる、バージョン特有の lisp ディレクトリー
を指定することもできます。例えば、:

  % make install VERSION_SPECIFIC_LISPDIR=~/elisp

どのファイルが emu モジュールか apel モジュールの一部なのか、それらが
どこにインストールされるかを知りたいときは、次のようなコマンドを入力す
ることができます。

  % make what-where LISPDIR=~/elisp VERSION_SPECIFIC_LISPDIR=~/elisp

ファイル APEL-CFG を編集することで他の選択自由な設定を指定することがで
きます。その中のコメントを読んでください。

** XEmacs のパッケージとしてインストールする

XEmacs のパッケージディレクトリーにインストールする場合は、以下のこと
をしてください:

  % make install-package

emacs のコマンド名を指定することができます。例えば、

  % make install-package XEMACS=xemacs-21

`XEMACS=...' が省略されると、XEMACS=xemacs が使用されます。

パッケージのディレクトリーを指定することができます。例えば:

  % make install PACKAGEDIR=~/.xemacs

`PACKAGEDIR=...' が省略されると、存在するパッケージディレクトリーの最
初のものが使われます。

XEmacs のパッケージシステムは XEmacs 21.0 かそれ以降を要求することに注
意してください。

** MAKEIT.BAT を利用する (MS-DOS 系 OS の場合)

MS-DOS 系の OS のために MAKEIT.BAT と MAKE1.BAT が用意されています
(cygwin 環境を利用している方は make.exe と Makefile を利用することがで
きます)。MAKEIT.BAT は、インストールの環境変数を設定した後に MAKE1.BAT
を呼出します。MAKE1.BAT によって実際のインストールに必要なコマンドが実
行されます。

これらを利用するには MAKEIT.BAT を編集することが必要です。安全のためす
べての環境変数のデフォルトの値は空文字列になっています。お使いのシステ
ムにあわせてこれらの変数を指定してください。

開発、動作確認が Windows でしか行なわれていないため、古いバージョンの
DOS では動作しない可能性があります。不都合を発見した方は
apel-ja@m17n.org までご連絡下さい。

*** MAKEIT.BAT の編集

DOS のバッチファイルの中では `rem' が行頭にある行はコメントとして扱わ
れます。必要に応じ、MAKEIT.BAT の各行頭に `rem' を挿入したり、または削
除したりして下さい。

また、バッチファイル内の `%変数名%' は実行時の環境変数の値と置き換えら
れます。

c:\usr\Meadow にインストールされている 1.10 の Meadow を使用
している場合の変数設定の例を挙げます。

  set PREFIX=c:\usr\Meadow
  set EMACS=%PREFIX%\1.10\bin\meadow95.exe
  set EXEC_PREFIX=
  set LISPDIR=%PREFIX%\site-lisp
  set VERSION_SPECIFIC_LISPDIR=%PREFIX%\1.10\site-lisp
  set DEFAULT_MAKE_ARG=elc

上記の例では、meadow のバイナリが c:\usr\Meadow\1.10\bin\meadow95.exe
にインストールされていることを前提にしています。その前提に基づき、APEL
のモジュールのうち、meadow のバージョンに依存しないモジュールを

  c:\usr\Meadow\site-lisp

に、バージョンに依存するモジュールを

  c:\usr\Meadow\1.10\site-lisp

にインストールしようとします。

19.3x 以前の Emacs (例えば 19.28 ベースの Mule for Windows) にはバージョ
ン依存の site-lisp ディレクトリ (上記の例で言えば
c:\usr\Meadow\1.10\site-lisp) が存在せず、ディフォルトでは load-path も
通っていません。この場合は c:\usr\mule\site-lisp などのバージョン非依存
の site-lisp ディレクトリに APEL の全てのモジュールを入れれば良いでしょ
う。

Demacs の設定例を準備することができませんでした。Demacs に APEL をイン
ストールした方は、設定例を apel-ja@m17n.org に送って下さい (非購読者で
も送信はできます)。


*** MAKEIT.BAT の編集の際、知っておくと便利な Tips

引数を指定しないで MAKEIT.BAT を実行させると、DEFAULT_MAKE_ARG に指定
されている target が実行されます (ディフォルトは安全のために target が
空になっており、メッセージだけ吐いて止まるようになってます)。

MAKEIT.BAT を編集して、

  set DEFAULT_MAKE_ARG=install

と記述しておくことで、MAKEIT.BAT をダブルクリックするだけでインストー
ルすることができます。

MAKEIT.BAT は、下記のいずれかのファイルが存在するときは、そのファイル
の設定を優先して読み込むので、適宜編集した MAKEIT.BAT は下記のいずれか
のファイルとして、コピーしてキープしておくと、アップグレードの際に
MAKEIT.BAT を再編集する必要がなく便利です。

優先順に並べると下記のようになります。下記の 1-x は apel 専用、2-x は
同種の MAKEIT.BAT を利用している cmail, skk と共通して利用することがで
きます。

  1-1. %HOME%\.elispmk.apel.bat
  1-2. %HOME%\elisp\elispmk.apel.bat
  1-3. %HOME%\config\elispmk.apel.bat
  1-4. c:\Program Files\Meadow\elispmk.apel.bat
  1-5. c:\Meadow\elispmk.apel.bat
  1-6. d:\Meadow\elispmk.apel.bat

  2-1. %HOME%\.elispmk.bat
  2-2. %HOME%\elisp\elispmk.bat
  2-3. %HOME%\config\elispmk.bat
  2-4. c:\Program Files\Meadow\elispmk.bat
  2-5. c:\Meadow\elispmk.bat
  2-6. d:\Meadow\elispmk.bat

*** バッチファイル実行時の注意

MAKEIT.BAT, MAKE1.BAT は環境変数を利用しているために、実行時に環境変数
のためのメモリ割当てができずに、エラーになることがあります。Windows を
利用している場合は、DOSPROMPT のプロパティで環境変数の初期サイズが「自
動」になっていると、環境変数が設定できないというエラーが出るので、適当
な値 (2048 など) を入れておく必要があります。non Windows の DOS の場合
は、config.sys に

   SHELL=C:\COMMAND.COM /E:4096 /P

などと書き、環境変数に割当て可能なメモリを確保します。DOS のバージョン
によって /E:nnn で指定できる環境変数領域のサイズの制約が異なり、指定の
仕方が違ったり、特定の値を指定すると不具合を生じる可能性があるので詳し
くはご利用の version のマニュアル等をご覧下さい。

*** Windows の cvs.exe でチェックアウトした MAKEIT.BAT を利用する場合の問題点

なお、Windows ネイティブの cvs.exe (not cygwin) を利用して APEL を
checkout した場合は、cvs.exe により行末コードが正規化されて CRCRLF に
なっている可能性があります。このような場合、MAKEIT.BAT, MAKE1.BAT は動
きませんので行末コードを CRLF に修正してお使い下さい。この問題について
詳しくは、

  http://openlab.ring.gr.jp/skk/cvswin-ja.html

をご参照下さい。

* load-path（Emacs と MULE の場合）

もし Emacs もしくは Mule をお使いなら、APEL を install した場所を
load-path に追加してください。もし Emacs 19.29 以降または Emacs 20.1,
20.2 を使って初期設定でインストールしたのなら、次のように subdirs.el
を書くことができます。

--------------------------------------------------------------------
(normal-top-level-add-to-load-path '("apel"))
--------------------------------------------------------------------

もし Emacs 20.3 以降もしくは XEmacs を使って普通にインストールするの
ならば、load-path を設定する必要はありません。


* Emacs のバージョンに関連した情報

** 「古い byte-compiler」と「新しい byte-compiler」

Emacs 18 のユーザのみなさんへ:

このパッケージではコンパイル時における条件判断をたくさん行なっていま
す。残念ながら Emacs 18 に付属している byte-compiler には、例えば
`eval-when-compile' や `eval-and-compile' の機能が無いので代用品のマ
クロを用意してありますが、これらはコンパイル時だけでなく load 時また
は実行時にも働いてしまいます!   加えて「古い byte-compiler」はトップ
レベルのマクロをコンパイルしてくれないので、APEL の多くのコードがコ
ンパイルされないままになってしまいます。

そこで、最適化を行なう「新しい byte-compiler」を使うことをお勧めしま
す。それは Emacs 19 以降に付属している byte-compiler の元になってい
るものです。

最適化を行なう byte-compiler は Emacs Lisp Archive およびそれらのミ
ラーから入手することができます。

Mule 1.* の時代には Mule 用の「新しい byte-compiler」を含む Mule 1.*
用の "contrib" パッケージが配布されていました。しかし現在ではこのパッ
ケージを手に入れることは難しいでしょう。

我々の知る限りでは Emacs 18 用の「新しい byte-compiler」は SKK 9.6,
または SKK 10.62a に付属しています。SKK 10.62a は

  http://openlab.ring.gr.jp/skk/maintrunk

から入手することができます。これらは Mule 1.* 用のパッチも含んでいます。


** 「古い custom」と「新しい custom」

Emacs 19.34 と XEmacs 19.14 のユーザのみなさんへ:

Emacs 19.32〜19.34、XEmacs 19.14 および Gnus 5.2/5.3 に含まれている
custom ライブラリは「古い」もので、これの API は Emacs 20.1 または
XEmacs 19.15 より新しい Emacsen と Gnus 5.4/5.5 に含まれている
「新しい custom」とは違っています。

Emacs 19.34 と XEmacs 19.15〜20.2 用の「新しい custom」は、以下の
URL から手に入れることができます。

ftp://ftp.dina.kvl.dk/pub/Staff/Per.Abrahamsen/custom/custom-1.9962.tar.gz

(注: XEmacs 19.15〜20.2 と Gnus 5.4/5.5 に含まれている「新しい custom」
はこの版より古いものです。)

「新しい custom」をインストールする前に、次の各項目をチェックして下
さい。

  1) もしあなたが Gnus 5.2/5.3 (または他の「古い custom」を使うアプ
     リケーション) を使うことに固執しているのならば「新しい custom」
     をインストールしてはいけません。

  2) Emacs 19 を元にした Mule を使うのならば、このパッチを「新しい
     custom」に当てる必要があります。

----8<------8<------8<------8<------8<------8<------8<------8<----
--- custom-1.9962/cus-face.el~	Wed Mar  4 19:52:39 1998
+++ custom-1.9962/cus-face.el	Mon Mar  9 08:05:33 1998
@@ -96,7 +96,7 @@
       "Define a new FACE on all frames, ignoring X resources."
       (interactive "SMake face: ")
       (or (internal-find-face name)
-	  (let ((face (make-vector 8 nil)))
+	  (let ((face (make-vector face-vector-length nil)))
 	    (aset face 0 'face)
 	    (aset face 1 name)
 	    (let* ((frames (frame-list))
----8<------8<------8<------8<------8<------8<------8<------8<----

  3) custom を使うコンパイルされたアプリケーションは、それを load す
     るときや実行するときに同じバージョンの custom を必要とします。
     したがって、いつも load-path に「新しい custom」を含めておかな
     ければなりません。
     これを行なうためのもっとも簡単な方法は subdirs.el を使うことで
     す。
     「新しい custom」が /usr/local/share/emacs/19.34/site-lisp/custom/
     にインストールされているのならば、
     /usr/local/share/emacs/19.34/site-lisp/subdirs.el というファイ
     ルに以下の行を書き込んで下さい。

     (normal-top-level-add-to-load-path '("custom"))


* 使い方

** alist

*** 関数 put-alist (ITEM VALUE ALIST)

ALIST を ITEM の値が VALUE になるように修正します。car が ITEM であ
る対が存在すれば、その cdr を VALUE で置き換えます。そのような対がな
ければ、新しい対 (ITEM . VALUE) を作り、car が新しい対で、cdr が
ALIST である新しい連想リストを返します。

*** 関数 del-alist (ITEM ALIST)

連想リスト ALIST に key が ITEM である対があれば、それを ALIST から取
り除きます。

*** 関数 set-alist (SYMBOL ITEM VALUE)

SYMBOL で指定されている連想リストを、ITEM の値が VALUE であるように修
正します。

  例. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode)

*** 関数 modify-alist (MODIFIER DEFAULT)

連想リスト DEFAULT を連想リスト MODIFIER に修正します。

*** 関数 set-modified-alist (SYMBOL MODIFIER)

SYMBOL の値を連想リスト MODIFIER に修正します。SYMBOL は連想リストであ
る必要があります。それが束縛されていなければ、その値を nil とみなしま
す。

** path-util

*** 関数 add-path (PATH &rest OPTIONS)

PATH が `default-load-path' のディレクトリーの下に存在して、
`load-path'に存在しないときに、それを `load-path' に追加します。

次のような PATH の様式を使うことができます:

  load-path からの相対: "PATH" (それは `default-load-path から探されま
                        す。)

  ホームディレクトリーからの相対: "~/PATH" "~USER/PATH"

  絶対パス: "/FOO/BAR/BAZ"

次のような OPTIONS を指定することができます:

  'all-paths --- `default-load-path の代わり `load-path' から探しま
	           す。

  'append --- PATH を `load-path' の最後に追加します。

*** 関数 add-latest-path (PATTERN &optional ALL-PATHS)

正規表現 PATTERN に合致した最新のパスが `default-load-path' の下に存在
していて、`load-path' の下に存在していないときにそれを `load-path' に
追加します。

例えば、bbdb-1.50 と bbdb-1.51 が site-lisp の下にあって、bbdb-1.51 が
bbdb-1.50 よりも新しく、site-lisp が /usr/local/share/emacs/site-lisp
であるときは、

  (add-latest-path "bbdb")

は "/usr/local/share/emacs/site-lisp/bbdb-1.51" を `load-path' の先頭
に追加します。

省略可能な引数 ALL-PATHS が指定されると、`default-load-path' のかわり
に `load-path' から探します。

*** 関数 get-latest-path (PATTERN &optional ALL-PATHS)

正規表現 PATTERN に合致する default-load-path にある最新のディレクトリー
を返します。省略可能な引数 ALL-PATHS が指定されると、default-load-path
の代わりに load-path の全てから探します。

  例. (let ((gnus-path (get-latest-path "gnus")))
        (add-path (expand-file-name "lisp" gnus-path))
        (add-to-list 'Info-default-directory-list
		     (expand-file-name "texi" gnus-path)))

*** 関数 file-installed-p (FILE &optional PATHS)

FILE が PATHS に存在した場合、FILE の絶対パスを返します。PATHS が省略
されると、`load-path' が使われます。

*** 関数 exec-installed-p (FILE &optional PATHS SUFFIXES)

FILE が PATHS に存在した場合に FILE の絶対パスを返します。PATHS が省略
されると、`exec-path' が使われます。SUFFIXES が省略されると、
`exec-suffix-list' が使われます。

*** 関数 module-installed-p (MODULE &optional PATHS)

MODULE が提供されている (provided) か、PATHS に存在する場合に nil で
ない値を返します。PATHS が省略されると、`load-path' が使われます。

** filename

*** 関数 replace-as-filename (string)

STRING から安全なファイル名を返します。

それは変数 'filename-filters' を参照します。その変数はファイル名の選
別器のための関数のリストです。初期設定の選別器は以下の変数を参照してい
ます。

**** 変数 filename-limit-length

ファイル名の長さの制限。

**** 変数 filename-replacement-alist

文字と文字列が対になったリストの連想リストです。文字のリストはファイル
名として許されない文字を現わします。


* バグ報告

バグ報告や改善の提案を書いたときは、是非 APEL メーリングリストに送って
ください:

  apel-en@m17n.org	(英語)
  apel-ja@m17n.org	(日本語)

APEL ML を通して、APEL のバグを報告したり、APEL の最新のリリースを取得
したり、APEL の将来の拡張の議論をしたりすることができます。APEL ML に
参加するには、空の電子メールを

  apel-en-ctl@m17n.org	(英語)
  apel-ja-ctl@m17n.org	(日本語)

に送ってください。


* Anonymous FTP

最新の APEL のリリースは以下の場所から取得できます:

    ftp://ftp.m17n.org/pub/mule/apel/


* CVS

APEL の開発は CVS を使っています。最新の開発バージョンを CVS で取得で
きます。

** cvs login (一回目だけ)

  % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login

  CVS password: [CR] # 空文字列

** checkout

  % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout apel

CVS に基づいた開発に参加したいときは、

  cvs@cvs.m17n.org

にアカウント名と、ssh の公開鍵を送ってください。ssh 経由では、cvsroot
は :ext:cvs@cvs.m17n.org:/cvs/root となります。

開かれた開発に参加してくださることを期待します。
