README.en

   1 -*- outline -*-
   2
   3 [README for APEL (English Version)]
   4
   5 * What's APEL?
   6
   7 APEL stands for "A Portable Emacs Library".  It consists of following
   8 modules:
   9
  10 **  poe.el
  11
  12 This is an emulation module mainly for basic functions and special
  13 forms/macros of latest emacsen.
  14
  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.
  20
  21 ** poem.el
  22
  23 This module provides basic functions to write portable MULE programs.
  24
  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
  32
  33 ** pces.el
  34
  35 This module provides portable character encoding scheme
  36 (coding-system) features.
  37
  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.
  46
  47 ** invisible.el
  48
  49 This modules provides features about invisible region.
  50
  51   inv-18.el     --- for Emacs 18
  52   inv-19.el     --- for Emacs 19
  53   inv-xemacs.el --- for XEmacs
  54
  55 ** mcharset.el
  56
  57 This modules provides MIME charset related features.
  58
  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
  66
  67 ** static.el --- utility for static evaluation
  68
  69 ** broken.el --- provide information of broken facilities of Emacs
  70
  71 ** pccl.el --- utility to write portable CCL program
  72
  73   pccl-om.el --- for MULE 2.*
  74   pccl-20.el --- for Emacs 20/XEmacs-21-MULE
  75
  76 ** alist.el: utility for Association-list
  77
  78 ** calist.el: utility for condition tree and condition/situation-alist
  79
  80 ** path-util.el: utility for path management or file detection
  81
  82 ** filename.el: utility to make file-name
  83
  84 ** install.el: utility to install emacs-lisp package
  85
  86 ** mule-caesar.el: ROT 13-47-48 Caesar rotation utility
  87
  88 ** emu.el
  89
  90 This module provides emu bundled in tm-7.106 compatibility.  It
  91 required poe, poem and mcharset.
  92
  93   emu-mule:     --- for MULE 1.*, 2.*.
  94   richtext.el   --- text/richtext module for Emacs 19.29 or later,
  95                      XEmacs 19.14 or later
  96   tinyrich.el   --- text/richtext module for old emacsen
  97
  98 ** pcustom.el --- provide portable custom environment
  99
 100   tinycustom.el --- emulation module of custom.el
 101
 102 ** timezone.el
 103
 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.
 106
 107 ** product.el --- Functions for product version information.
 108
 109 * Installation
 110
 111 ** run in expanded place
 112
 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)'):
 116
 117   % make
 118
 119 You can specify the emacs command name, for example
 120
 121   % make EMACS=xemacs
 122
 123 If `EMACS=...' is omitted, EMACS=emacs is used.
 124
 125 ** make install
 126
 127 If you want to install other directories, please do following:
 128
 129   % make install
 130
 131 You can specify the emacs command name, for example
 132
 133   % make install EMACS=xemacs
 134
 135 If `EMACS=...' is omitted, EMACS=emacs is used.
 136
 137 You can specify the prefix of the directory tree for Emacs Lisp
 138 programs and shell scripts, for example:
 139
 140   % make install PREFIX=~/
 141
 142 If `PREFIX=...' is omitted, the prefix of the directory tree of the
 143 specified emacs command is used (perhaps /usr/local).
 144
 145 For example, if PREFIX=/usr/local and Emacs 20.2 is specified, it
 146 will create the following directory tree:
 147
 148   /usr/local/share/emacs/20.2/site-lisp/        --- emu
 149   /usr/local/share/emacs/site-lisp/apel/        --- APEL
 150
 151 You can specify the lisp directory for Emacs Lisp programs,
 152 for example:
 153
 154   % make install LISPDIR=~/elisp
 155
 156 You can also specify the version specific lisp directory where the
 157 emu modules will be installed in, for example:
 158
 159   % make install VERSION_SPECIFIC_LISPDIR=~/elisp
 160
 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.
 164
 165   % make what-where LISPDIR=~/elisp VERSION_SPECIFIC_LISPDIR=~/elisp
 166
 167 You can specify other optional settings by editing the file
 168 APEL-CFG.  Please read comments in it.
 169
 170 ** install as a XEmacs package
 171
 172 If you want to install to XEmacs package directory, please do
 173 following:
 174
 175   % make install-package
 176
 177 You can specify the emacs command name, for example
 178
 179   % make install-package XEMACS=xemacs-21
 180
 181 If `XEMACS=...' is omitted, XEMACS=xemacs is used.
 182
 183 You can specify the package directory, for example:
 184
 185   % make install PACKAGEDIR=~/.xemacs
 186
 187 If `PACKAGEDIR=...' is omitted, the first existing package
 188 directory is used.
 189
 190 Notice that XEmacs package system requires XEmacs 21.0 or later.
 191
 192
 193 ** make.bat (for MS-DOS family)
 194
 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.
 198
 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.
 201
 202 Default setups of make.bat is;
 203
 204   set MEADOWVER=1.10
 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
 209
 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;
 213
 214   c:\usr\meadow\site-lisp
 215
 216 and meadow version dependent modules to;
 217
 218   c:\usr\meadow\1.10\site-lisp
 219
 220 Please edit make.bat for your own environment and run make.bat
 221
 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.
 228
 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
 232 are not a member).
 233
 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)
 240
 241   http://openlab.ring.gr.jp/skk/cvswin-ja.html
 242
 243 * load-path (for Emacs or MULE)
 244
 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:
 248
 249 --------------------------------------------------------------------
 250 (normal-top-level-add-to-load-path '("apel"))
 251 --------------------------------------------------------------------
 252
 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.
 255
 256
 257 * Version specific information
 258
 259 ** For Emacs 18 users: "old byte-compiler" vs "new byte-compiler"
 260
 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.
 268
 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.
 271
 272 Optimizing byte-compiler for Emacs 18 is available from the Emacs
 273 Lisp Archive and its mirrors.
 274
 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.
 278
 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;
 281
 282   http://openlab.ring.gr.jp/skk/maintrunk
 283
 284 They include patch for Mule 1.*.
 285
 286
 287 ** For Emacs 19.34 and XEmacs 19.14 users: "old custom" vs "new custom"
 288
 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.
 292
 293 "new custom" for Emacs 19.34 and XEmacs 19.15 - 20.2 is available
 294 from the following URL.
 295
 296 ftp://ftp.dina.kvl.dk/pub/Staff/Per.Abrahamsen/custom/custom-1.9962.tar.gz
 297
 298 (Note that "new custom" bundled with XEmacs 19.15 - 20.2, and Gnus
 299 5.4/5.5 is older than this version.)
 300
 301 Before installing "new custom", you should check the following points.
 302
 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".
 305
 306   2) If you use Mule (based on Emacs 19), you must apply this patch
 307      to "new custom".
 308
 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
 312 @@ -96,7 +96,7 @@
 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)))
 318             (aset face 0 'face)
 319             (aset face 1 name)
 320             (let* ((frames (frame-list))
 321 ----8<------8<------8<------8<------8<------8<------8<------8<----
 322
 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".
 329
 330        (normal-top-level-add-to-load-path '("custom"))
 331
 332
 333 * How to use
 334
 335 ** alist
 336
 337 *** Function put-alist (ITEM VALUE ALIST)
 338
 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.
 343
 344 *** Function del-alist (ITEM ALIST)
 345
 346 If there is a pair whose key is ITEM, delete it from ALIST.
 347
 348 *** Function set-alist (SYMBOL ITEM VALUE)
 349
 350 Modify a alist indicated by SYMBOL to set VALUE to ITEM.
 351
 352   Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode)
 353
 354 *** Function modify-alist (MODIFIER DEFAULT)
 355
 356 Modify alist DEFAULT into alist MODIFIER.
 357
 358 *** Function set-modified-alist (SYMBOL MODIFIER)
 359
 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.
 362
 363 ** path-util
 364
 365 *** Function add-path (PATH &rest OPTIONS)
 366
 367 Add PATH to `load-path' if it exists under `default-load-path'
 368 directories and it does not exist in `load-path'.
 369
 370 You can use following PATH styles:
 371
 372   load-path relative: "PATH" (it is searched from `default-load-path')
 373
 374   home directory relative: "~/PATH" "~USER/PATH"
 375
 376   absolute path: "/FOO/BAR/BAZ"
 377
 378 You can specify following OPTIONS:
 379
 380   'all-paths --- search from `load-path' instead of
 381                  `default-load-path'
 382
 383   'append --- add PATH to the last of `load-path'
 384
 385 *** Function add-latest-path (PATTERN &optional ALL-PATHS)
 386
 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
 389 in `load-path'.
 390
 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,
 394
 395   (add-latest-path "bbdb")
 396
 397 it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of
 398 `load-path'.
 399
 400 If optional argument ALL-PATHS is specified, it is searched from all
 401 of `load-path' instead of `default-load-path'.
 402
 403 *** Function get-latest-path (PATTERN &optional ALL-PATHS)
 404
 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.
 408
 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)))
 413
 414 *** Function file-installed-p (FILE &optional PATHS)
 415
 416 Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 417 omitted, `load-path' is used.
 418
 419 *** Function exec-installed-p (FILE &optional PATHS SUFFIXES)
 420
 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.
 424
 425 *** Function module-installed-p (MODULE &optional PATHS)
 426
 427 Return non-nil if MODULE is provided or exists in PATHS.  If PATHS is
 428 omitted, `load-path' is used.
 429
 430 ** filename
 431
 432 *** Function replace-as-filename (string)
 433
 434 Return safety file-name from STRING.
 435
 436 It refers variable `filename-filters'.  It is list of functions for
 437 file-name filter.  Default filter refers following variables:
 438
 439 **** Variable filename-limit-length
 440
 441 Limit size of file-name.
 442
 443 **** Variable filename-replacement-alist
 444
 445 Alist list of characters vs. string as replacement.  List of
 446 characters represents characters not allowed as file-name.
 447
 448
 449 * Bug reports
 450
 451 If you write bug-reports and/or suggestions for improvement, please
 452 send them to the APEL Mailing List:
 453
 454   apel-en@lists.chise.org       (English)
 455   apel-ja@lists.chise.org       (Japanese)
 456
 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:
 460
 461   http://lists.chise.org/mailman/listinfo/apel-en       (English)
 462   http://lists.chise.org/mailman/listinfo/apel-ja       (Japanese)
 463
 464
 465 * Anonymous FTP
 466
 467 Latest release of APEL can be obtained from:
 468
 469   ftp://ftp.m17n.org/pub/mule/apel/
 470
 471
 472 * CVS
 473
 474 Development of APEL uses CVS.  So latest developing version is
 475 available at CVS.
 476
 477 ** cvs login (first time only)
 478
 479   % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login
 480
 481   CVS password: [CR] # NULL string
 482
 483 ** checkout
 484
 485   % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout apel
 486
 487   If you would like to join CVS based development, please send mail to
 488
 489   cvs@cvs.m17n.org
 490
 491 with your account name and your public key for ssh.  cvsroot is
 492 :ext:cvs@cvs.m17n.org:/cvs/root.
 493
 494 We hope you will join the open development.