1 [README for APEL (English Version)]
6 APEL stands for "A Portable Emacs Library". It consists of
9 poe.el --- emulation module mainly for basic functions and special
10 forms/macros of latest emacsen
11 poe-xemacs.el --- for XEmacs
12 poe-18.el --- for Emacs 18/Nemacs
13 env.el --- env.el for Emacs 18
14 localhook.el --- hook functions for Emacs 19.28 and earlier.
16 poem.el --- provide basic functions to write portable MULE
18 poem-nemacs.el --- for Nemacs
19 poem-ltn1.el --- for Emacs 19/XEmacs without MULE
20 poem-om.el --- for MULE 1.*, 2.*
21 poem-20.el --- shared module between Emacs 20 and XEmacs-MULE
22 poem-e20_2.el --- for Emacs 20.1/20.2
23 poem-e20_3.el --- for Emacs 20.3
24 poem-xm.el --- for XEmacs-MULE
26 invisible.el --- provide features about invisible region
27 inv-18.el --- for Emacs 18
28 inv-19.el --- for Emacs 19
29 inv-xemacs.el --- for XEmacs
31 mcharset.el --- provide MIME charset related features
32 mcs-nemacs.el --- for Nemacs
33 mcs-ltn1.el --- for Emacs 19/XEmacs without MULE
34 mcs-om.el --- for MULE 1.*, 2.*
35 mcs-20.el --- shared module between Emacs 20 and XEmacs-MULE
36 mcs-e20.el --- for Emacs 20
37 mcs-xm.el --- for XEmacs-MULE
38 mcs-xmu.el --- for XEmacs-MULE to unify ISO646 characters
40 static.el --- utility for static evaluation
42 broken.el --- provide information of broken facilities of Emacs
44 pccl.el --- utility to write portable CCL program
45 pccl-om.el --- for MULE 2.*
46 pccl-20.el --- for Emacs 20/XEmacs-21-MULE
48 alist.el: utility for Association-list
50 calist.el: utility for condition tree and
51 condition/situation-alist
53 path-util.el: utility for path management or file detection
55 filename.el: utility to make file-name
57 install.el: utility to install emacs-lisp package
59 mule-caesar.el: ROT 13-47-48 Caesar rotation utility
61 emu.el --- (emu bundled in tm-7.106 compatibility module; it
62 required poe, poem and mcharset)
63 emu-mule: for MULE 1.*, 2.*
64 richtext.el --- text/richtext module
65 for Emacs 19.29 or later,
67 tinyrich.el --- text/richtext module for old emacsen
69 pcustom.el --- provide portable custom environment
71 tinycustom.el --- emulation module of custom.el
77 (a) run in expanded place
79 If you don't want to install other directories, please do only
84 You can specify the emacs command name, for example
88 If `EMACS=...' is omitted, EMACS=emacs is used.
92 If you want to install other directories, please do following:
96 You can specify the emacs command name, for example
98 % make install EMACS=xemacs
100 If `EMACS=...' is omitted, EMACS=emacs is used.
102 You can specify the prefix of the directory tree for Emacs Lisp
103 programs and shell scripts, for example:
105 % make install PREFIX=~/
107 If `PREFIX=...' is omitted, the prefix of the directory tree of the
108 specified emacs command is used (perhaps /usr/local).
110 For example, if PREFIX=/usr/local and Emacs 20.2 is specified, it
111 will create the following directory tree:
113 /usr/local/share/emacs/20.2/site-lisp/ --- emu
114 /usr/local/share/emacs/site-lisp/apel/ --- APEL
116 You can specify the lisp directory for Emacs Lisp programs,
119 % make install LISPDIR=~/elisp
121 You can also specify the version specific lisp directory where the
122 emu modules will be installed in, for example:
124 % make install VERSION_SPECIFIC_LISPDIR=~/elisp
126 If you would like to know what files belong to the emu modules or
127 the apel modules, or where they will be installed in, for example,
128 please type the following command.
130 % make what-where LISPDIR=~/elisp VERSION_SPECIFIC_LISPDIR=~/elisp
132 You can specify other optional settings by editing the file
133 APEL-CFG. Please read comments in it.
135 (c) install as a XEmacs package
137 If you want to install to XEmacs package directory, please do
140 % make install-package
142 You can specify the emacs command name, for example
144 % make install-package XEMACS=xemacs-21
146 If `XEMACS=...' is omitted, XEMACS=xemacs is used.
148 You can specify the package directory, for example:
150 % make install PACKAGEDIR=~/.xemacs
152 If `PACKAGEDIR=...' is omitted, the first existing package
155 Notice that XEmacs package system requires XEmacs 21.0 or later.
158 (d) make.bat (for MS-DOS family)
160 make.bat is available for MS-DOS family. You have to edit
161 make.bat if you want to use it. If you use cygwin environment,
162 you can use make.exe and Makefile instead of make.bat.
164 In make.bat, a line which contain `rem' in its beginning is a
165 comment. You have to insert or delete `rem', if necessary.
167 Default setups of make.bat is;
170 set PREFIX=c:\usr\meadow
171 set EMACS=%PREFIX%\%MEADOWVER%\bin\meadow95.exe
172 set LISPDIR=%PREFIX%\site-lisp
173 set VLISPDIR=%PREFIX%\%MEADOWVER%\site-lisp
175 It assumes that meadow executable binary exists in
176 c:\usr\meadow\1.10\bin\meadow95.exe. On such basis make.bat will
177 try to install meadow version independent modules of APEL to;
179 c:\usr\meadow\site-lisp
181 and meadow version dependent modules to;
183 c:\usr\meadow\1.10\site-lisp
185 Please edit make.bat for your own environment and run make.bat
187 Emacs 19.3x or earlier does not have (e.x. Mule for Windows based on
188 19.28) an Emacs version dependent site-lisp directory
189 (e.x. c:\usr\meadow\1.10\site-lisp), and its load-path does not refer
190 to such directory by default. If you want install APEL to such an Emacs
191 you may install all APEL modules to an Emacs version independent
192 site-lisp directory such as c:\usr\mule\site-lisp.
194 We cannot provide you with a Demacs example for make.bat. If you install
195 APEL to Demacs, please send us such an example to apel-en@m17n.org (you
196 can post a message to the ML, even if you are not a member).
198 If you checkout APEL by using Windows native cvs.exe (not cygwin),
199 cvs.exe will regularize end of line codes, LF to CRLF. And it also will
200 try to convert CRLF to CRCRLF. make.bat of which eol code is CRCRLF does
201 not work, so if you get such a make.bat, edit it to really regularize eol
202 codes to CRLF. If you need further information, see the following URL
205 http://openlab.ring.gr.jp/skk/cvswin-ja.html
207 load-path (for Emacs or MULE)
208 =============================
210 If you are using Emacs or Mule, please add directory of apel to
211 load-path. If you install by default setting with Emacs 19.29 or
212 later or Emacs 20.1/20.2, you can write subdirs.el for example:
214 --------------------------------------------------------------------
215 (normal-top-level-add-to-load-path '("apel"))
216 --------------------------------------------------------------------
218 If you are using Emacs 20.3 or later or XEmacs, there are no need to
219 set up load-path with normal installation.
222 Version specific information
223 ============================
225 For Emacs 18 users: "old byte-compiler" vs "new byte-compiler"
227 In this package, we use compile-time evaluation heavily.
228 Unfortunately, the byte-compiler bundled with Emacs 18 (the "old
229 byte-compiler") does not have features such as `eval-when-compile'
230 and `eval-and-compile', and our emulation version of these macros
231 evaluate "compile-time evaluation" at load-time or at run-time!
232 In addition, the "old byte-compiler" cannot compile top-level use of
233 macros and leaves most of our code uncompiled.
235 Therefore, we recommend you to use the "new" optimizing byte-compiler.
236 It is the origin of byte-compiler bundled with Emacs 19 and later.
238 Optimizing byte-compiler for Emacs 18 is available from the Emacs
239 Lisp Archive and its mirrors.
241 In Mule 1.* days, "contrib" package for Mule 1.* was distributed and
242 it contained the "new byte-compiler" for Mule. But, I think it is
243 difficult to obtain this package now.
245 AFAIK, the "new byte-compiler" for Emacs 18 is also bundled with SKK
246 9.6 or SKK 10.62a. You can get SKK 10.62a from the following URL;
247 http://openlab.ring.gr.jp/skk/maintrunk
248 They include patch for Mule 1.*.
251 For Emacs 19.34 and XEmacs 19.14 users: "old custom" vs "new custom"
253 "custom" library bundled with Emacs 19.32 - 19.34, XEmacs 19.14, and
254 Gnus 5.2/5.3 is "old", its API is incompatible with "new custom"
255 bundled with Emacs 20.1, XEmacs 19.15, or newer, and Gnus 5.4/5.5.
257 "new custom" for Emacs 19.34 and XEmacs 19.15 - 20.2 is available
258 from the following URL.
260 ftp://ftp.dina.kvl.dk/pub/Staff/Per.Abrahamsen/custom/custom-1.9962.tar.gz
262 (Note that "new custom" bundled with XEmacs 19.15 - 20.2, and Gnus
263 5.4/5.5 is older than this version.)
265 Before installing "new custom", you should check the following points.
267 1) If you stick to Gnus 5.2/5.3 (or any other applications which
268 use "old custom"), you should not install "new custom".
270 2) If you use Mule (based on Emacs 19), you must apply this patch
273 ----8<------8<------8<------8<------8<------8<------8<------8<----
274 --- custom-1.9962/cus-face.el~ Wed Mar 4 19:52:39 1998
275 +++ custom-1.9962/cus-face.el Mon Mar 9 08:05:33 1998
277 "Define a new FACE on all frames, ignoring X resources."
278 (interactive "SMake face: ")
279 (or (internal-find-face name)
280 - (let ((face (make-vector 8 nil)))
281 + (let ((face (make-vector face-vector-length nil)))
284 (let* ((frames (frame-list))
285 ----8<------8<------8<------8<------8<------8<------8<------8<----
287 3) Applications compiled with "custom" require the same version of
288 "custom" at load-time (and run-time). Therefore, if you use
289 "new custom", you must always include "new custom" in your
290 load-path. The easiest way to achieve this is "subdirs.el";
291 if you installed "new custom" in "/usr/local/share/emacs/19.34/
292 site-lisp/custom/", put the following line to "/usr/local/share/
293 emacs/19.34/site-lisp/subdirs.el".
295 (normal-top-level-add-to-load-path '("custom"))
304 Function put-alist (ITEM VALUE ALIST)
306 Modify ALIST to set VALUE to ITEM. If there is a pair whose car is
307 ITEM, replace its cdr by VALUE. If there is not such pair, create
308 new pair (ITEM . VALUE) and return new alist whose car is the new
309 pair and cdr is ALIST.
311 Function del-alist (ITEM ALIST)
313 If there is a pair whose key is ITEM, delete it from ALIST.
315 Function set-alist (SYMBOL ITEM VALUE)
317 Modify a alist indicated by SYMBOL to set VALUE to ITEM.
319 Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode)
321 Function modify-alist (MODIFIER DEFAULT)
323 Modify alist DEFAULT into alist MODIFIER.
325 Function set-modified-alist (SYMBOL MODIFIER)
327 Modify a value of a SYMBOL into alist MODIFIER. The SYMBOL should
328 be alist. If it is not bound, its value regard as nil.
333 Function add-path (PATH &rest OPTIONS)
335 Add PATH to `load-path' if it exists under `default-load-path'
336 directories and it does not exist in `load-path'.
338 You can use following PATH styles:
340 load-path relative: "PATH" (it is searched from
343 home directory relative: "~/PATH" "~USER/PATH"
345 absolute path: "/FOO/BAR/BAZ"
347 You can specify following OPTIONS:
349 'all-paths --- search from `load-path' instead of
352 'append --- add PATH to the last of `load-path'
354 Function add-latest-path (PATTERN &optional ALL-PATHS)
356 Add latest path matched by regexp PATTERN to `load-path' if it
357 exists under `default-load-path' directories and it does not exist
360 For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp,
361 and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is
362 /usr/local/share/emacs/site-lisp,
364 (add-latest-path "bbdb")
366 it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of
369 If optional argument ALL-PATHS is specified, it is searched from all
370 of `load-path' instead of `default-load-path'.
372 Function get-latest-path (PATTERN &optional ALL-PATHS)
374 Return latest directory in default-load-path which is matched to
375 regexp PATTERN. If optional argument ALL-PATHS is specified, it is
376 searched from all of load-path instead of default-load-path.
378 Ex. (let ((gnus-path (get-latest-path "gnus")))
379 (add-path (expand-file-name "lisp" gnus-path))
380 (add-to-list 'Info-default-directory-list
381 (expand-file-name "texi" gnus-path))
384 Function file-installed-p (FILE &optional PATHS)
386 Return absolute-path of FILE if FILE exists in PATHS. If PATHS is
387 omitted, `load-path' is used.
389 Function exec-installed-p (FILE &optional PATHS SUFFIXES)
391 Return absolute-path of FILE if FILE exists in PATHS. If PATHS is
392 omitted, `exec-path' is used. If SUFFIXES is omitted,
393 `exec-suffix-list' is used.
395 Function module-installed-p (MODULE &optional PATHS)
397 Return non-nil if MODULE is provided or exists in PATHS. If PATHS
398 is omitted, `load-path' is used.
403 Function replace-as-filename (string)
405 Return safety file-name from STRING.
407 It refers variable `filename-filters'. It is list of functions for
408 file-name filter. Default filter refers following variables:
410 Variable filename-limit-length
412 Limit size of file-name.
414 Variable filename-replacement-alist
416 Alist list of characters vs. string as replacement. List of
417 characters represents characters not allowed as file-name.
423 If you write bug-reports and/or suggestions for improvement, please
424 send them to the APEL Mailing List:
426 apel-en@m17n.org (English)
427 apel-ja@m17n.org (Japanese)
429 Via the APEL ML, you can report APEL bugs, obtain the latest release
430 of APEL, and discuss future enhancements to APEL. To join the APEL
431 ML, send an empty e-mail to
433 apel-en-ctl@m17n.org (English)
434 apel-ja-ctl@m17n.org (Japanese)
440 Latest release of APEL can be obtained from:
442 ftp://ftp.m17n.org/pub/mule/apel/
448 Development of APEL uses CVS. So latest developing version is
451 (0) cvs login (first time only)
453 % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login
455 CVS password: [CR] # NULL string
459 % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout apel
461 If you would like to join CVS based development, please send mail to
465 with your account name and your public key for ssh. cvsroot is
466 :ext:cvs@cvs.m17n.org:/cvs/root.
468 If you cannot use ssh, please send UNIX /etc/passwd style crypted
469 password. you can commit with the cvsroot
470 :pserver:<accountname>@cvs.m17n.org:/cvs/root.
472 We hope you will join the open development.