3 [README for APEL (English Version)]
7 APEL stands for "A Portable Emacs Library". It consists of following
12 This is an emulation module mainly for basic functions and special
13 forms/macros of latest emacsen.
15 poe-xemacs.el --- for XEmacs
16 poe-18.el --- for Emacs 18/Nemacs
17 env.el --- env.el for Emacs 18
18 localhook.el --- hook functions for Emacs 19.28 and earlier.
19 pym.el --- macros for poe.
23 This module provides basic functions to write portable MULE programs.
25 poem-nemacs.el --- for Nemacs
26 poem-ltn1.el --- for Emacs 19/XEmacs without MULE
27 poem-om.el --- for MULE 1.*, 2.*
28 poem-20.el --- shared module between Emacs 20 and XEmacs-MULE
29 poem-e20_2.el --- for Emacs 20.1/20.2
30 poem-e20_3.el --- for Emacs 20.3
31 poem-xm.el --- for XEmacs-MULE
35 This module provides portable character encoding scheme
36 (coding-system) features.
38 pces-20.el --- for Emacs 20 and XEmacs with coding-system.
39 pces-e20.el --- for Emacs 20.
40 pces-e20_2.el --- for Emacs 20.1 and 20.2.
41 pces-nemacs.el --- for Nemacs.
42 pces-om.el --- for Mule 1.* and Mule 2.*.
43 pces-raw.el --- for emacsen without coding-system features.
44 pces-xfc.el --- for XEmacs with file coding.
45 pces-xm.el --- for XEmacs-mule.
49 This modules provides features about invisible region.
51 inv-18.el --- for Emacs 18
52 inv-19.el --- for Emacs 19
53 inv-xemacs.el --- for XEmacs
57 This modules provides MIME charset related features.
59 mcs-nemacs.el --- for Nemacs
60 mcs-ltn1.el --- for Emacs 19/XEmacs without MULE
61 mcs-om.el --- for MULE 1.*, 2.*
62 mcs-20.el --- shared module between Emacs 20 and XEmacs-MULE
63 mcs-e20.el --- for Emacs 20
64 mcs-xm.el --- for XEmacs-MULE
65 mcs-xmu.el --- for XEmacs-MULE to unify ISO646 characters
67 ** static.el --- utility for static evaluation
69 ** broken.el --- provide information of broken facilities of Emacs
71 ** pccl.el --- utility to write portable CCL program
73 pccl-om.el --- for MULE 2.*
74 pccl-20.el --- for Emacs 20/XEmacs-21-MULE
76 ** alist.el: utility for Association-list
78 ** calist.el: utility for condition tree and condition/situation-alist
80 ** path-util.el: utility for path management or file detection
82 ** filename.el: utility to make file-name
84 ** install.el: utility to install emacs-lisp package
86 ** mule-caesar.el: ROT 13-47-48 Caesar rotation utility
90 This module provides emu bundled in tm-7.106 compatibility. It
91 required poe, poem and mcharset.
93 emu-mule: --- for MULE 1.*, 2.*.
94 richtext.el --- text/richtext module for Emacs 19.29 or later,
96 tinyrich.el --- text/richtext module for old emacsen
98 ** pcustom.el --- provide portable custom environment
100 tinycustom.el --- emulation module of custom.el
104 This is a utility to maintain last change time stamps in files edited
109 This is a utility of time zone. This is a Y2K fixed version. This
110 works with old GNUS 3.14.4 under version 18 of Emacs, too.
112 ** product.el --- Functions for product version information.
116 ** run in expanded place
118 If you don't want to install other directories, please do only
119 following (You can use make.bat for MS-DOS OS family. If you want to
120 use it, see `make.bat (for MS-DOS family)'):
124 You can specify the emacs command name, for example
128 If `EMACS=...' is omitted, EMACS=emacs is used.
132 If you want to install other directories, please do following:
136 You can specify the emacs command name, for example
138 % make install EMACS=xemacs
140 If `EMACS=...' is omitted, EMACS=emacs is used.
142 You can specify the prefix of the directory tree for Emacs Lisp
143 programs and shell scripts, for example:
145 % make install PREFIX=~/
147 If `PREFIX=...' is omitted, the prefix of the directory tree of the
148 specified emacs command is used (perhaps /usr/local).
150 For example, if PREFIX=/usr/local and Emacs 20.2 is specified, it
151 will create the following directory tree:
153 /usr/local/share/emacs/20.2/site-lisp/ --- emu
154 /usr/local/share/emacs/site-lisp/apel/ --- APEL
156 You can specify the lisp directory for Emacs Lisp programs,
159 % make install LISPDIR=~/elisp
161 You can also specify the version specific lisp directory where the
162 emu modules will be installed in, for example:
164 % make install VERSION_SPECIFIC_LISPDIR=~/elisp
166 If you would like to know what files belong to the emu modules or
167 the apel modules, or where they will be installed in, for example,
168 please type the following command.
170 % make what-where LISPDIR=~/elisp VERSION_SPECIFIC_LISPDIR=~/elisp
172 You can specify other optional settings by editing the file
173 APEL-CFG. Please read comments in it.
175 ** install as a XEmacs package
177 If you want to install to XEmacs package directory, please do
180 % make install-package
182 You can specify the emacs command name, for example
184 % make install-package XEMACS=xemacs-21
186 If `XEMACS=...' is omitted, XEMACS=xemacs is used.
188 You can specify the package directory, for example:
190 % make install PACKAGEDIR=~/.xemacs
192 If `PACKAGEDIR=...' is omitted, the first existing package
195 Notice that XEmacs package system requires XEmacs 21.0 or later.
198 ** make.bat (for MS-DOS family)
200 make.bat is available for MS-DOS family. You have to edit
201 make.bat if you want to use it. If you use cygwin environment,
202 you can use make.exe and Makefile instead of make.bat.
204 In make.bat, a line which contain `rem' in its beginning is a
205 comment. You have to insert or delete `rem', if necessary.
207 Default setups of make.bat is;
210 set PREFIX=c:\usr\meadow
211 set EMACS=%PREFIX%\%MEADOWVER%\bin\meadow95.exe
212 set LISPDIR=%PREFIX%\site-lisp
213 set VLISPDIR=%PREFIX%\%MEADOWVER%\site-lisp
215 It assumes that meadow executable binary exists in
216 c:\usr\meadow\1.10\bin\meadow95.exe. On such basis make.bat will
217 try to install meadow version independent modules of APEL to;
219 c:\usr\meadow\site-lisp
221 and meadow version dependent modules to;
223 c:\usr\meadow\1.10\site-lisp
225 Please edit make.bat for your own environment and run make.bat
227 Emacs 19.3x or earlier does not have (e.x. Mule for Windows based on
228 19.28) an Emacs version dependent site-lisp directory
229 (e.x. c:\usr\meadow\1.10\site-lisp), and its load-path does not refer
230 to such directory by default. If you want install APEL to such an Emacs
231 you may install all APEL modules to an Emacs version independent
232 site-lisp directory such as c:\usr\mule\site-lisp.
234 We cannot provide you with a Demacs example for make.bat. If you install
235 APEL to Demacs, please send us such an example to apel-en@m17n.org (you
236 can post a message to the ML, even if you are not a member).
238 If you checkout APEL by using Windows native cvs.exe (not cygwin
239 version), cvs.exe will regularize end of line codes, LF to CRLF. And
240 it also will try to convert CRLF to CRCRLF. make.bat of which eol
241 code is CRCRLF does not work, so if you get such a make.bat, edit it
242 to really regularize eol codes to CRLF. If you need further
243 information, see the following URL (n.b. Japanese only)
245 http://openlab.ring.gr.jp/skk/cvswin-ja.html
247 * load-path (for Emacs or MULE)
249 If you are using Emacs or Mule, please add directory of apel to
250 load-path. If you install by default setting with Emacs 19.29 or
251 later or Emacs 20.1/20.2, you can write subdirs.el for example:
253 --------------------------------------------------------------------
254 (normal-top-level-add-to-load-path '("apel"))
255 --------------------------------------------------------------------
257 If you are using Emacs 20.3 or later or XEmacs, there are no need to
258 set up load-path with normal installation.
261 * Version specific information
263 ** For Emacs 18 users: "old byte-compiler" vs "new byte-compiler"
265 In this package, we use compile-time evaluation heavily.
266 Unfortunately, the byte-compiler bundled with Emacs 18 (the "old
267 byte-compiler") does not have features such as `eval-when-compile'
268 and `eval-and-compile', and our emulation version of these macros
269 evaluate "compile-time evaluation" at load-time or at run-time!
270 In addition, the "old byte-compiler" cannot compile top-level use of
271 macros and leaves most of our code uncompiled.
273 Therefore, we recommend you to use the "new" optimizing byte-compiler.
274 It is the origin of byte-compiler bundled with Emacs 19 and later.
276 Optimizing byte-compiler for Emacs 18 is available from the Emacs
277 Lisp Archive and its mirrors.
279 In Mule 1.* days, "contrib" package for Mule 1.* was distributed and
280 it contained the "new byte-compiler" for Mule. But, I think it is
281 difficult to obtain this package now.
283 AFAIK, the "new byte-compiler" for Emacs 18 is also bundled with SKK
284 9.6 or SKK 10.62a. You can get SKK 10.62a from the following URL;
286 http://openlab.ring.gr.jp/skk/maintrunk
288 They include patch for Mule 1.*.
291 ** For Emacs 19.34 and XEmacs 19.14 users: "old custom" vs "new custom"
293 "custom" library bundled with Emacs 19.32 - 19.34, XEmacs 19.14, and
294 Gnus 5.2/5.3 is "old", its API is incompatible with "new custom"
295 bundled with Emacs 20.1, XEmacs 19.15, or newer, and Gnus 5.4/5.5.
297 "new custom" for Emacs 19.34 and XEmacs 19.15 - 20.2 is available
298 from the following URL.
300 ftp://ftp.dina.kvl.dk/pub/Staff/Per.Abrahamsen/custom/custom-1.9962.tar.gz
302 (Note that "new custom" bundled with XEmacs 19.15 - 20.2, and Gnus
303 5.4/5.5 is older than this version.)
305 Before installing "new custom", you should check the following points.
307 1) If you stick to Gnus 5.2/5.3 (or any other applications which
308 use "old custom"), you should not install "new custom".
310 2) If you use Mule (based on Emacs 19), you must apply this patch
313 ----8<------8<------8<------8<------8<------8<------8<------8<----
314 --- custom-1.9962/cus-face.el~ Wed Mar 4 19:52:39 1998
315 +++ custom-1.9962/cus-face.el Mon Mar 9 08:05:33 1998
317 "Define a new FACE on all frames, ignoring X resources."
318 (interactive "SMake face: ")
319 (or (internal-find-face name)
320 - (let ((face (make-vector 8 nil)))
321 + (let ((face (make-vector face-vector-length nil)))
324 (let* ((frames (frame-list))
325 ----8<------8<------8<------8<------8<------8<------8<------8<----
327 3) Applications compiled with "custom" require the same version of
328 "custom" at load-time (and run-time). Therefore, if you use "new
329 custom", you must always include "new custom" in your load-path.
330 The easiest way to achieve this is "subdirs.el"; if you installed
331 "new custom" in "/usr/local/share/emacs/19.34/site-lisp/custom/",
332 put the following line to "/usr/local/share/emacs/19.34/site-lisp/subdirs.el".
334 (normal-top-level-add-to-load-path '("custom"))
341 *** Function put-alist (ITEM VALUE ALIST)
343 Modify ALIST to set VALUE to ITEM. If there is a pair whose car is
344 ITEM, replace its cdr by VALUE. If there is not such pair, create
345 new pair (ITEM . VALUE) and return new alist whose car is the new
346 pair and cdr is ALIST.
348 *** Function del-alist (ITEM ALIST)
350 If there is a pair whose key is ITEM, delete it from ALIST.
352 *** Function set-alist (SYMBOL ITEM VALUE)
354 Modify a alist indicated by SYMBOL to set VALUE to ITEM.
356 Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode)
358 *** Function modify-alist (MODIFIER DEFAULT)
360 Modify alist DEFAULT into alist MODIFIER.
362 *** Function set-modified-alist (SYMBOL MODIFIER)
364 Modify a value of a SYMBOL into alist MODIFIER. The SYMBOL should be
365 alist. If it is not bound, its value regard as nil.
369 *** Function add-path (PATH &rest OPTIONS)
371 Add PATH to `load-path' if it exists under `default-load-path'
372 directories and it does not exist in `load-path'.
374 You can use following PATH styles:
376 load-path relative: "PATH" (it is searched from `default-load-path')
378 home directory relative: "~/PATH" "~USER/PATH"
380 absolute path: "/FOO/BAR/BAZ"
382 You can specify following OPTIONS:
384 'all-paths --- search from `load-path' instead of
387 'append --- add PATH to the last of `load-path'
389 *** Function add-latest-path (PATTERN &optional ALL-PATHS)
391 Add latest path matched by regexp PATTERN to `load-path' if it
392 exists under `default-load-path' directories and it does not exist
395 For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp,
396 and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is
397 /usr/local/share/emacs/site-lisp,
399 (add-latest-path "bbdb")
401 it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of
404 If optional argument ALL-PATHS is specified, it is searched from all
405 of `load-path' instead of `default-load-path'.
407 *** Function get-latest-path (PATTERN &optional ALL-PATHS)
409 Return latest directory in default-load-path which is matched to
410 regexp PATTERN. If optional argument ALL-PATHS is specified, it is
411 searched from all of load-path instead of default-load-path.
413 Ex. (let ((gnus-path (get-latest-path "gnus")))
414 (add-path (expand-file-name "lisp" gnus-path))
415 (add-to-list 'Info-default-directory-list
416 (expand-file-name "texi" gnus-path)))
418 *** Function file-installed-p (FILE &optional PATHS)
420 Return absolute-path of FILE if FILE exists in PATHS. If PATHS is
421 omitted, `load-path' is used.
423 *** Function exec-installed-p (FILE &optional PATHS SUFFIXES)
425 Return absolute-path of FILE if FILE exists in PATHS. If PATHS is
426 omitted, `exec-path' is used. If SUFFIXES is omitted,
427 `exec-suffix-list' is used.
429 *** Function module-installed-p (MODULE &optional PATHS)
431 Return non-nil if MODULE is provided or exists in PATHS. If PATHS is
432 omitted, `load-path' is used.
436 *** Function replace-as-filename (string)
438 Return safety file-name from STRING.
440 It refers variable `filename-filters'. It is list of functions for
441 file-name filter. Default filter refers following variables:
443 **** Variable filename-limit-length
445 Limit size of file-name.
447 **** Variable filename-replacement-alist
449 Alist list of characters vs. string as replacement. List of
450 characters represents characters not allowed as file-name.
454 If you write bug-reports and/or suggestions for improvement, please
455 send them to the APEL Mailing List:
457 apel-en@m17n.org (English)
458 apel-ja@m17n.org (Japanese)
460 Via the APEL ML, you can report APEL bugs, obtain the latest release
461 of APEL, and discuss future enhancements to APEL. To join the APEL
462 ML, send an empty e-mail to
464 apel-en-ctl@m17n.org (English)
465 apel-ja-ctl@m17n.org (Japanese)
470 Latest release of APEL can be obtained from:
472 ftp://ftp.m17n.org/pub/mule/apel/
477 Development of APEL uses CVS. So latest developing version is
480 ** cvs login (first time only)
482 % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login
484 CVS password: [CR] # NULL string
488 % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout apel
490 If you would like to join CVS based development, please send mail to
494 with your account name and your public key for ssh. cvsroot is
495 :ext:cvs@cvs.m17n.org:/cvs/root.
497 We hope you will join the open development.