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 of time zone. This is a Y2K fixed version. This
105 works with old GNUS 3.14.4 under version 18 of Emacs, too.
107 ** product.el --- Functions for product version information.
111 ** run in expanded place
113 If you don't want to install other directories, please do only
114 following (You can use make.bat for MS-DOS OS family. If you want to
115 use it, see `make.bat (for MS-DOS family)'):
119 You can specify the emacs command name, for example
123 If `EMACS=...' is omitted, EMACS=emacs is used.
127 If you want to install other directories, please do following:
131 You can specify the emacs command name, for example
133 % make install EMACS=xemacs
135 If `EMACS=...' is omitted, EMACS=emacs is used.
137 You can specify the prefix of the directory tree for Emacs Lisp
138 programs and shell scripts, for example:
140 % make install PREFIX=~/
142 If `PREFIX=...' is omitted, the prefix of the directory tree of the
143 specified emacs command is used (perhaps /usr/local).
145 For example, if PREFIX=/usr/local and Emacs 20.2 is specified, it
146 will create the following directory tree:
148 /usr/local/share/emacs/20.2/site-lisp/ --- emu
149 /usr/local/share/emacs/site-lisp/apel/ --- APEL
151 You can specify the lisp directory for Emacs Lisp programs,
154 % make install LISPDIR=~/elisp
156 You can also specify the version specific lisp directory where the
157 emu modules will be installed in, for example:
159 % make install VERSION_SPECIFIC_LISPDIR=~/elisp
161 If you would like to know what files belong to the emu modules or
162 the apel modules, or where they will be installed in, for example,
163 please type the following command.
165 % make what-where LISPDIR=~/elisp VERSION_SPECIFIC_LISPDIR=~/elisp
167 You can specify other optional settings by editing the file
168 APEL-CFG. Please read comments in it.
170 ** install as a XEmacs package
172 If you want to install to XEmacs package directory, please do
175 % make install-package
177 You can specify the emacs command name, for example
179 % make install-package XEMACS=xemacs-21
181 If `XEMACS=...' is omitted, XEMACS=xemacs is used.
183 You can specify the package directory, for example:
185 % make install PACKAGEDIR=~/.xemacs
187 If `PACKAGEDIR=...' is omitted, the first existing package
190 Notice that XEmacs package system requires XEmacs 21.0 or later.
193 ** make.bat (for MS-DOS family)
195 make.bat is available for MS-DOS family. You have to edit
196 make.bat if you want to use it. If you use cygwin environment,
197 you can use make.exe and Makefile instead of make.bat.
199 In make.bat, a line which contain `rem' in its beginning is a
200 comment. You have to insert or delete `rem', if necessary.
202 Default setups of make.bat is;
205 set PREFIX=c:\usr\meadow
206 set EMACS=%PREFIX%\%MEADOWVER%\bin\meadow95.exe
207 set LISPDIR=%PREFIX%\site-lisp
208 set VLISPDIR=%PREFIX%\%MEADOWVER%\site-lisp
210 It assumes that meadow executable binary exists in
211 c:\usr\meadow\1.10\bin\meadow95.exe. On such basis make.bat will
212 try to install meadow version independent modules of APEL to;
214 c:\usr\meadow\site-lisp
216 and meadow version dependent modules to;
218 c:\usr\meadow\1.10\site-lisp
220 Please edit make.bat for your own environment and run make.bat
222 Emacs 19.3x or earlier does not have (e.x. Mule for Windows based on
223 19.28) an Emacs version dependent site-lisp directory
224 (e.x. c:\usr\meadow\1.10\site-lisp), and its load-path does not refer
225 to such directory by default. If you want install APEL to such an Emacs
226 you may install all APEL modules to an Emacs version independent
227 site-lisp directory such as c:\usr\mule\site-lisp.
229 We cannot provide you with a Demacs example for make.bat. If you
230 install APEL to Demacs, please send us such an example to
231 apel-en@lists.chise.org (you can post a message to the ML, even if you
234 If you checkout APEL by using Windows native cvs.exe (not cygwin
235 version), cvs.exe will regularize end of line codes, LF to CRLF. And
236 it also will try to convert CRLF to CRCRLF. make.bat of which eol
237 code is CRCRLF does not work, so if you get such a make.bat, edit it
238 to really regularize eol codes to CRLF. If you need further
239 information, see the following URL (n.b. Japanese only)
241 http://openlab.ring.gr.jp/skk/cvswin-ja.html
243 * load-path (for Emacs or MULE)
245 If you are using Emacs or Mule, please add directory of apel to
246 load-path. If you install by default setting with Emacs 19.29 or
247 later or Emacs 20.1/20.2, you can write subdirs.el for example:
249 --------------------------------------------------------------------
250 (normal-top-level-add-to-load-path '("apel"))
251 --------------------------------------------------------------------
253 If you are using Emacs 20.3 or later or XEmacs, there are no need to
254 set up load-path with normal installation.
257 * Version specific information
259 ** For Emacs 18 users: "old byte-compiler" vs "new byte-compiler"
261 In this package, we use compile-time evaluation heavily.
262 Unfortunately, the byte-compiler bundled with Emacs 18 (the "old
263 byte-compiler") does not have features such as `eval-when-compile'
264 and `eval-and-compile', and our emulation version of these macros
265 evaluate "compile-time evaluation" at load-time or at run-time!
266 In addition, the "old byte-compiler" cannot compile top-level use of
267 macros and leaves most of our code uncompiled.
269 Therefore, we recommend you to use the "new" optimizing byte-compiler.
270 It is the origin of byte-compiler bundled with Emacs 19 and later.
272 Optimizing byte-compiler for Emacs 18 is available from the Emacs
273 Lisp Archive and its mirrors.
275 In Mule 1.* days, "contrib" package for Mule 1.* was distributed and
276 it contained the "new byte-compiler" for Mule. But, I think it is
277 difficult to obtain this package now.
279 AFAIK, the "new byte-compiler" for Emacs 18 is also bundled with SKK
280 9.6 or SKK 10.62a. You can get SKK 10.62a from the following URL;
282 http://openlab.ring.gr.jp/skk/maintrunk
284 They include patch for Mule 1.*.
287 ** For Emacs 19.34 and XEmacs 19.14 users: "old custom" vs "new custom"
289 "custom" library bundled with Emacs 19.32 - 19.34, XEmacs 19.14, and
290 Gnus 5.2/5.3 is "old", its API is incompatible with "new custom"
291 bundled with Emacs 20.1, XEmacs 19.15, or newer, and Gnus 5.4/5.5.
293 "new custom" for Emacs 19.34 and XEmacs 19.15 - 20.2 is available
294 from the following URL.
296 ftp://ftp.dina.kvl.dk/pub/Staff/Per.Abrahamsen/custom/custom-1.9962.tar.gz
298 (Note that "new custom" bundled with XEmacs 19.15 - 20.2, and Gnus
299 5.4/5.5 is older than this version.)
301 Before installing "new custom", you should check the following points.
303 1) If you stick to Gnus 5.2/5.3 (or any other applications which
304 use "old custom"), you should not install "new custom".
306 2) If you use Mule (based on Emacs 19), you must apply this patch
309 ----8<------8<------8<------8<------8<------8<------8<------8<----
310 --- custom-1.9962/cus-face.el~ Wed Mar 4 19:52:39 1998
311 +++ custom-1.9962/cus-face.el Mon Mar 9 08:05:33 1998
313 "Define a new FACE on all frames, ignoring X resources."
314 (interactive "SMake face: ")
315 (or (internal-find-face name)
316 - (let ((face (make-vector 8 nil)))
317 + (let ((face (make-vector face-vector-length nil)))
320 (let* ((frames (frame-list))
321 ----8<------8<------8<------8<------8<------8<------8<------8<----
323 3) Applications compiled with "custom" require the same version of
324 "custom" at load-time (and run-time). Therefore, if you use "new
325 custom", you must always include "new custom" in your load-path.
326 The easiest way to achieve this is "subdirs.el"; if you installed
327 "new custom" in "/usr/local/share/emacs/19.34/site-lisp/custom/",
328 put the following line to "/usr/local/share/emacs/19.34/site-lisp/subdirs.el".
330 (normal-top-level-add-to-load-path '("custom"))
337 *** Function put-alist (ITEM VALUE ALIST)
339 Modify ALIST to set VALUE to ITEM. If there is a pair whose car is
340 ITEM, replace its cdr by VALUE. If there is not such pair, create
341 new pair (ITEM . VALUE) and return new alist whose car is the new
342 pair and cdr is ALIST.
344 *** Function del-alist (ITEM ALIST)
346 If there is a pair whose key is ITEM, delete it from ALIST.
348 *** Function set-alist (SYMBOL ITEM VALUE)
350 Modify a alist indicated by SYMBOL to set VALUE to ITEM.
352 Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode)
354 *** Function modify-alist (MODIFIER DEFAULT)
356 Modify alist DEFAULT into alist MODIFIER.
358 *** Function set-modified-alist (SYMBOL MODIFIER)
360 Modify a value of a SYMBOL into alist MODIFIER. The SYMBOL should be
361 alist. If it is not bound, its value regard as nil.
365 *** Function add-path (PATH &rest OPTIONS)
367 Add PATH to `load-path' if it exists under `default-load-path'
368 directories and it does not exist in `load-path'.
370 You can use following PATH styles:
372 load-path relative: "PATH" (it is searched from `default-load-path')
374 home directory relative: "~/PATH" "~USER/PATH"
376 absolute path: "/FOO/BAR/BAZ"
378 You can specify following OPTIONS:
380 'all-paths --- search from `load-path' instead of
383 'append --- add PATH to the last of `load-path'
385 *** Function add-latest-path (PATTERN &optional ALL-PATHS)
387 Add latest path matched by regexp PATTERN to `load-path' if it
388 exists under `default-load-path' directories and it does not exist
391 For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp,
392 and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is
393 /usr/local/share/emacs/site-lisp,
395 (add-latest-path "bbdb")
397 it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of
400 If optional argument ALL-PATHS is specified, it is searched from all
401 of `load-path' instead of `default-load-path'.
403 *** Function get-latest-path (PATTERN &optional ALL-PATHS)
405 Return latest directory in default-load-path which is matched to
406 regexp PATTERN. If optional argument ALL-PATHS is specified, it is
407 searched from all of load-path instead of default-load-path.
409 Ex. (let ((gnus-path (get-latest-path "gnus")))
410 (add-path (expand-file-name "lisp" gnus-path))
411 (add-to-list 'Info-default-directory-list
412 (expand-file-name "texi" gnus-path)))
414 *** Function file-installed-p (FILE &optional PATHS)
416 Return absolute-path of FILE if FILE exists in PATHS. If PATHS is
417 omitted, `load-path' is used.
419 *** Function exec-installed-p (FILE &optional PATHS SUFFIXES)
421 Return absolute-path of FILE if FILE exists in PATHS. If PATHS is
422 omitted, `exec-path' is used. If SUFFIXES is omitted,
423 `exec-suffix-list' is used.
425 *** Function module-installed-p (MODULE &optional PATHS)
427 Return non-nil if MODULE is provided or exists in PATHS. If PATHS is
428 omitted, `load-path' is used.
432 *** Function replace-as-filename (string)
434 Return safety file-name from STRING.
436 It refers variable `filename-filters'. It is list of functions for
437 file-name filter. Default filter refers following variables:
439 **** Variable filename-limit-length
441 Limit size of file-name.
443 **** Variable filename-replacement-alist
445 Alist list of characters vs. string as replacement. List of
446 characters represents characters not allowed as file-name.
451 If you write bug-reports and/or suggestions for improvement, please
452 send them to the APEL Mailing List:
454 apel-en@lists.chise.org (English)
455 apel-ja@lists.chise.org (Japanese)
457 Via the APEL ML, you can report APEL bugs, obtain the latest release
458 of APEL, and discuss future enhancements to APEL. To join the APEL
459 ML, please see the descriptions of the following pages:
461 http://lists.chise.org/mailman/listinfo/apel-en (English)
462 http://lists.chise.org/mailman/listinfo/apel-ja (Japanese)
467 Latest release of APEL can be obtained from:
469 ftp://ftp.m17n.org/pub/mule/apel/
474 Development of APEL uses CVS. So latest developing version is
477 ** cvs login (first time only)
479 % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login
481 CVS password: [CR] # NULL string
485 % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout apel
487 If you would like to join CVS based development, please send mail to
491 with your account name and your public key for ssh. cvsroot is
492 :ext:cvs@cvs.m17n.org:/cvs/root.
494 We hope you will join the open development.