README.en

   1 [README for APEL (English Version)]
   2
   3 What's APEL?
   4 ============
   5
   6   APEL stands for "A Portable Emacs Library".  It consists of
   7   following modules:
   8
   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.
  15
  16     poem.el --- provide basic functions to write portable MULE
  17                 programs
  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
  25
  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
  30
  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
  39
  40     static.el --- utility for static evaluation
  41
  42     broken.el --- provide information of broken facilities of Emacs
  43
  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
  47
  48     alist.el: utility for Association-list
  49
  50     calist.el: utility for condition tree and
  51                condition/situation-alist
  52
  53     path-util.el: utility for path management or file detection
  54
  55     filename.el: utility to make file-name
  56
  57     install.el: utility to install emacs-lisp package
  58
  59     mule-caesar.el: ROT 13-47-48 Caesar rotation utility
  60
  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,
  66                             XEmacs 19.14 or later
  67       tinyrich.el   --- text/richtext module for old emacsen
  68
  69     pcustom.el --- provide portable custom environment
  70
  71       tinycustom.el --- emulation module of custom.el
  72
  73
  74 Installation
  75 ============
  76
  77 (a) run in expanded place
  78
  79   If you don't want to install other directories, please do only
  80   following:
  81
  82         % make
  83
  84   You can specify the emacs command name, for example
  85
  86         % make EMACS=xemacs
  87
  88   If `EMACS=...' is omitted, EMACS=emacs is used.
  89
  90 (b) make install
  91
  92   If you want to install other directories, please do following:
  93
  94         % make install
  95
  96   You can specify the emacs command name, for example
  97
  98         % make install EMACS=xemacs
  99
 100   If `EMACS=...' is omitted, EMACS=emacs is used.
 101
 102   You can specify the prefix of the directory tree for Emacs Lisp
 103   programs and shell scripts, for example:
 104
 105         % make install PREFIX=~/
 106
 107   If `PREFIX=...' is omitted, the prefix of the directory tree of the
 108   specified emacs command is used (perhaps /usr/local).
 109
 110   For example, if PREFIX=/usr/local and Emacs 20.2 is specified, it
 111   will create the following directory tree:
 112
 113         /usr/local/share/emacs/20.2/site-lisp/  --- emu
 114         /usr/local/share/emacs/site-lisp/apel/  --- APEL
 115
 116   You can specify the lisp directory for Emacs Lisp programs,
 117   for example:
 118
 119         % make install LISPDIR=~/elisp
 120
 121   You can also specify the version specific lisp directory where the
 122   emu modules will be installed in, for example:
 123
 124         % make install VERSION_SPECIFIC_LISPDIR=~/elisp
 125
 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.
 129
 130         % make what-where LISPDIR=~/elisp VERSION_SPECIFIC_LISPDIR=~/elisp
 131
 132   You can specify other optional settings by editing the file
 133   APEL-CFG.  Please read comments in it.
 134
 135 (c) install as a XEmacs package
 136
 137   If you want to install to XEmacs package directory, please do
 138   following:
 139
 140         % make install-package
 141
 142   You can specify the emacs command name, for example
 143
 144         % make install-package XEMACS=xemacs-21
 145
 146   If `XEMACS=...' is omitted, XEMACS=xemacs is used.
 147
 148   You can specify the package directory, for example:
 149
 150         % make install PACKAGEDIR=~/.xemacs
 151
 152   If `PACKAGEDIR=...' is omitted, the first existing package
 153   directory is used.
 154
 155   Notice that XEmacs package system requires XEmacs 21.0 or later.
 156
 157
 158 load-path (for Emacs or MULE)
 159 =============================
 160
 161   If you are using Emacs or Mule, please add directory of apel to
 162   load-path.  If you install by default setting with Emacs 19.29 or
 163   later or Emacs 20.1/20.2, you can write subdirs.el for example:
 164
 165   --------------------------------------------------------------------
 166   (normal-top-level-add-to-load-path '("apel"))
 167   --------------------------------------------------------------------
 168
 169   If you are using Emacs 20.3 or later or XEmacs, there are no need to
 170   set up load-path with normal installation.
 171
 172
 173 Version specific information
 174 ============================
 175
 176 For Emacs 18 users: "old byte-compiler" vs "new byte-compiler"
 177
 178   In this package, we use compile-time evaluation heavily.
 179   Unfortunately, the byte-compiler bundled with Emacs 18 (the "old
 180   byte-compiler") does not have features such as `eval-when-compile'
 181   and `eval-and-compile', and our emulation version of these macros
 182   evaluate "compile-time evaluation" at load-time or at run-time!
 183   In addition, the "old byte-compiler" cannot compile top-level use of
 184   macros and leaves most of our code uncompiled.
 185
 186   Therefore, we recommend you to use the "new" optimizing byte-compiler.
 187   It is the origin of byte-compiler bundled with Emacs 19 and later.
 188
 189   Optimizing byte-compiler for Emacs 18 is available from the Emacs
 190   Lisp Archive and its mirrors.
 191
 192   In Mule 1.* days, "contrib" package for Mule 1.* was distributed and
 193   it contained the "new byte-compiler" for Mule.  But, I think it is
 194   difficult to obtain this package now.
 195
 196   AFAIK, the "new byte-compiler" for Emacs 18 is also bundled with SKK
 197   9.6.  It includes patch for Mule 1.*.
 198
 199
 200 For Emacs 19.34 and XEmacs 19.14 users: "old custom" vs "new custom"
 201
 202   "custom" library bundled with Emacs 19.32 - 19.34, XEmacs 19.14, and
 203   Gnus 5.2/5.3 is "old", its API is incompatible with "new custom"
 204   bundled with Emacs 20.1, XEmacs 19.15, or newer, and Gnus 5.4/5.5.
 205
 206   "new custom" for Emacs 19.34 and XEmacs 19.15 - 20.2 is available
 207   from the following URL.
 208
 209   ftp://ftp.dina.kvl.dk/pub/Staff/Per.Abrahamsen/custom/custom-1.9962.tar.gz
 210
 211   (Note that "new custom" bundled with XEmacs 19.15 - 20.2, and Gnus
 212   5.4/5.5 is older than this version.)
 213
 214   Before installing "new custom", you should check the following points.
 215
 216     1) If you stick to Gnus 5.2/5.3 (or any other applications which
 217        use "old custom"), you should not install "new custom".
 218
 219     2) If you use Mule (based on Emacs 19), you must apply this patch
 220        to "new custom".
 221
 222 ----8<------8<------8<------8<------8<------8<------8<------8<----
 223 --- custom-1.9962/cus-face.el~  Wed Mar  4 19:52:39 1998
 224 +++ custom-1.9962/cus-face.el   Mon Mar  9 08:05:33 1998
 225 @@ -96,7 +96,7 @@
 226        "Define a new FACE on all frames, ignoring X resources."
 227        (interactive "SMake face: ")
 228        (or (internal-find-face name)
 229 -         (let ((face (make-vector 8 nil)))
 230 +         (let ((face (make-vector face-vector-length nil)))
 231             (aset face 0 'face)
 232             (aset face 1 name)
 233             (let* ((frames (frame-list))
 234 ----8<------8<------8<------8<------8<------8<------8<------8<----
 235
 236     3) Applications compiled with "custom" require the same version of
 237        "custom" at load-time (and run-time).  Therefore, if you use
 238        "new custom", you must always include "new custom" in your
 239        load-path.  The easiest way to achieve this is "subdirs.el";
 240        if you installed "new custom" in "/usr/local/share/emacs/19.34/
 241        site-lisp/custom/", put the following line to "/usr/local/share/
 242        emacs/19.34/site-lisp/subdirs.el".
 243
 244        (normal-top-level-add-to-load-path '("custom"))
 245
 246
 247 How to use
 248 ==========
 249
 250 alist
 251 -----
 252
 253 Function put-alist (ITEM VALUE ALIST)
 254
 255   Modify ALIST to set VALUE to ITEM.  If there is a pair whose car is
 256   ITEM, replace its cdr by VALUE.  If there is not such pair, create
 257   new pair (ITEM . VALUE) and return new alist whose car is the new
 258   pair and cdr is ALIST.
 259
 260 Function del-alist (ITEM ALIST)
 261
 262   If there is a pair whose key is ITEM, delete it from ALIST.
 263
 264 Function set-alist (SYMBOL ITEM VALUE)
 265
 266   Modify a alist indicated by SYMBOL to set VALUE to ITEM.
 267
 268   Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode)
 269
 270 Function modify-alist (MODIFIER DEFAULT)
 271
 272   Modify alist DEFAULT into alist MODIFIER.
 273
 274 Function set-modified-alist (SYMBOL MODIFIER)
 275
 276   Modify a value of a SYMBOL into alist MODIFIER.  The SYMBOL should
 277   be alist. If it is not bound, its value regard as nil.
 278
 279 path-util
 280 ---------
 281
 282 Function add-path (PATH &rest OPTIONS)
 283
 284   Add PATH to `load-path' if it exists under `default-load-path'
 285   directories and it does not exist in `load-path'.
 286
 287   You can use following PATH styles:
 288
 289     load-path relative: "PATH" (it is searched from
 290                                 `default-load-path')
 291
 292     home directory relative: "~/PATH" "~USER/PATH"
 293
 294     absolute path: "/FOO/BAR/BAZ"
 295
 296   You can specify following OPTIONS:
 297
 298     'all-paths --- search from `load-path' instead of
 299                    `default-load-path'
 300
 301     'append --- add PATH to the last of `load-path'
 302
 303 Function add-latest-path (PATTERN &optional ALL-PATHS)
 304
 305   Add latest path matched by regexp PATTERN to `load-path' if it
 306   exists under `default-load-path' directories and it does not exist
 307   in `load-path'.
 308
 309   For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp,
 310   and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is
 311   /usr/local/share/emacs/site-lisp,
 312
 313         (add-latest-path "bbdb")
 314
 315   it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of
 316   `load-path'.
 317
 318   If optional argument ALL-PATHS is specified, it is searched from all
 319   of `load-path' instead of `default-load-path'.
 320
 321 Function get-latest-path (PATTERN &optional ALL-PATHS)
 322
 323   Return latest directory in default-load-path which is matched to
 324   regexp PATTERN.  If optional argument ALL-PATHS is specified, it is
 325   searched from all of load-path instead of default-load-path.
 326
 327   Ex. (let ((gnus-path (get-latest-path "gnus")))
 328         (add-path (expand-file-name "lisp" gnus-path))
 329         (add-to-list 'Info-default-directory-list
 330                      (expand-file-name "texi" gnus-path))
 331         )
 332
 333 Function file-installed-p (FILE &optional PATHS)
 334
 335   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 336   omitted, `load-path' is used.
 337
 338 Function exec-installed-p (FILE &optional PATHS SUFFIXES)
 339
 340   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 341   omitted, `exec-path' is used.  If SUFFIXES is omitted,
 342   `exec-suffix-list' is used.
 343
 344 Function module-installed-p (MODULE &optional PATHS)
 345
 346   Return non-nil if MODULE is provided or exists in PATHS.  If PATHS
 347   is omitted, `load-path' is used.
 348
 349 filename
 350 --------
 351
 352 Function replace-as-filename (string)
 353
 354   Return safety file-name from STRING.
 355
 356   It refers variable `filename-filters'.  It is list of functions for
 357   file-name filter.  Default filter refers following variables:
 358
 359         Variable filename-limit-length
 360
 361           Limit size of file-name.
 362
 363         Variable filename-replacement-alist
 364
 365           Alist list of characters vs. string as replacement.  List of
 366           characters represents characters not allowed as file-name.
 367
 368
 369 Bug reports
 370 ===========
 371
 372   If you write bug-reports and/or suggestions for improvement, please
 373   send them to the APEL Mailing List:
 374
 375         apel-en@m17n.org        (English)
 376         apel-ja@m17n.org        (Japanese)
 377
 378   Via the APEL ML, you can report APEL bugs, obtain the latest release
 379   of APEL, and discuss future enhancements to APEL.  To join the APEL
 380   ML, send an empty e-mail to
 381
 382         apel-en-ctl@m17n.org    (English)
 383         apel-ja-ctl@m17n.org    (Japanese)
 384
 385
 386 Anonymous FTP
 387 =============
 388
 389   Latest release of APEL can be obtained from:
 390
 391     ftp://ftp.m17n.org/pub/mule/apel/
 392
 393
 394 CVS
 395 ===
 396
 397   Development of APEL uses CVS.  So latest developing version is
 398   available at CVS.
 399
 400 (0) cvs login (first time only)
 401
 402     % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login
 403
 404     CVS password: [CR] # NULL string
 405
 406 (1) checkout
 407
 408     % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout apel
 409
 410   If you would like to join CVS based development, please send mail to
 411
 412         cvs@cvs.m17n.org
 413
 414   with your account name and UNIX /etc/passwd style crypted password.
 415   We hope you will join the open development.