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 or SKK 10.62a.  You can get SKK 10.62a from the following URL;
 198     http://openlab.ring.gr.jp/skk/maintrunk
 199   They include patch for Mule 1.*.
 200
 201
 202 For Emacs 19.34 and XEmacs 19.14 users: "old custom" vs "new custom"
 203
 204   "custom" library bundled with Emacs 19.32 - 19.34, XEmacs 19.14, and
 205   Gnus 5.2/5.3 is "old", its API is incompatible with "new custom"
 206   bundled with Emacs 20.1, XEmacs 19.15, or newer, and Gnus 5.4/5.5.
 207
 208   "new custom" for Emacs 19.34 and XEmacs 19.15 - 20.2 is available
 209   from the following URL.
 210
 211   ftp://ftp.dina.kvl.dk/pub/Staff/Per.Abrahamsen/custom/custom-1.9962.tar.gz
 212
 213   (Note that "new custom" bundled with XEmacs 19.15 - 20.2, and Gnus
 214   5.4/5.5 is older than this version.)
 215
 216   Before installing "new custom", you should check the following points.
 217
 218     1) If you stick to Gnus 5.2/5.3 (or any other applications which
 219        use "old custom"), you should not install "new custom".
 220
 221     2) If you use Mule (based on Emacs 19), you must apply this patch
 222        to "new custom".
 223
 224 ----8<------8<------8<------8<------8<------8<------8<------8<----
 225 --- custom-1.9962/cus-face.el~  Wed Mar  4 19:52:39 1998
 226 +++ custom-1.9962/cus-face.el   Mon Mar  9 08:05:33 1998
 227 @@ -96,7 +96,7 @@
 228        "Define a new FACE on all frames, ignoring X resources."
 229        (interactive "SMake face: ")
 230        (or (internal-find-face name)
 231 -         (let ((face (make-vector 8 nil)))
 232 +         (let ((face (make-vector face-vector-length nil)))
 233             (aset face 0 'face)
 234             (aset face 1 name)
 235             (let* ((frames (frame-list))
 236 ----8<------8<------8<------8<------8<------8<------8<------8<----
 237
 238     3) Applications compiled with "custom" require the same version of
 239        "custom" at load-time (and run-time).  Therefore, if you use
 240        "new custom", you must always include "new custom" in your
 241        load-path.  The easiest way to achieve this is "subdirs.el";
 242        if you installed "new custom" in "/usr/local/share/emacs/19.34/
 243        site-lisp/custom/", put the following line to "/usr/local/share/
 244        emacs/19.34/site-lisp/subdirs.el".
 245
 246        (normal-top-level-add-to-load-path '("custom"))
 247
 248
 249 How to use
 250 ==========
 251
 252 alist
 253 -----
 254
 255 Function put-alist (ITEM VALUE ALIST)
 256
 257   Modify ALIST to set VALUE to ITEM.  If there is a pair whose car is
 258   ITEM, replace its cdr by VALUE.  If there is not such pair, create
 259   new pair (ITEM . VALUE) and return new alist whose car is the new
 260   pair and cdr is ALIST.
 261
 262 Function del-alist (ITEM ALIST)
 263
 264   If there is a pair whose key is ITEM, delete it from ALIST.
 265
 266 Function set-alist (SYMBOL ITEM VALUE)
 267
 268   Modify a alist indicated by SYMBOL to set VALUE to ITEM.
 269
 270   Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode)
 271
 272 Function modify-alist (MODIFIER DEFAULT)
 273
 274   Modify alist DEFAULT into alist MODIFIER.
 275
 276 Function set-modified-alist (SYMBOL MODIFIER)
 277
 278   Modify a value of a SYMBOL into alist MODIFIER.  The SYMBOL should
 279   be alist. If it is not bound, its value regard as nil.
 280
 281 path-util
 282 ---------
 283
 284 Function add-path (PATH &rest OPTIONS)
 285
 286   Add PATH to `load-path' if it exists under `default-load-path'
 287   directories and it does not exist in `load-path'.
 288
 289   You can use following PATH styles:
 290
 291     load-path relative: "PATH" (it is searched from
 292                                 `default-load-path')
 293
 294     home directory relative: "~/PATH" "~USER/PATH"
 295
 296     absolute path: "/FOO/BAR/BAZ"
 297
 298   You can specify following OPTIONS:
 299
 300     'all-paths --- search from `load-path' instead of
 301                    `default-load-path'
 302
 303     'append --- add PATH to the last of `load-path'
 304
 305 Function add-latest-path (PATTERN &optional ALL-PATHS)
 306
 307   Add latest path matched by regexp PATTERN to `load-path' if it
 308   exists under `default-load-path' directories and it does not exist
 309   in `load-path'.
 310
 311   For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp,
 312   and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is
 313   /usr/local/share/emacs/site-lisp,
 314
 315         (add-latest-path "bbdb")
 316
 317   it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of
 318   `load-path'.
 319
 320   If optional argument ALL-PATHS is specified, it is searched from all
 321   of `load-path' instead of `default-load-path'.
 322
 323 Function get-latest-path (PATTERN &optional ALL-PATHS)
 324
 325   Return latest directory in default-load-path which is matched to
 326   regexp PATTERN.  If optional argument ALL-PATHS is specified, it is
 327   searched from all of load-path instead of default-load-path.
 328
 329   Ex. (let ((gnus-path (get-latest-path "gnus")))
 330         (add-path (expand-file-name "lisp" gnus-path))
 331         (add-to-list 'Info-default-directory-list
 332                      (expand-file-name "texi" gnus-path))
 333         )
 334
 335 Function file-installed-p (FILE &optional PATHS)
 336
 337   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 338   omitted, `load-path' is used.
 339
 340 Function exec-installed-p (FILE &optional PATHS SUFFIXES)
 341
 342   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 343   omitted, `exec-path' is used.  If SUFFIXES is omitted,
 344   `exec-suffix-list' is used.
 345
 346 Function module-installed-p (MODULE &optional PATHS)
 347
 348   Return non-nil if MODULE is provided or exists in PATHS.  If PATHS
 349   is omitted, `load-path' is used.
 350
 351 filename
 352 --------
 353
 354 Function replace-as-filename (string)
 355
 356   Return safety file-name from STRING.
 357
 358   It refers variable `filename-filters'.  It is list of functions for
 359   file-name filter.  Default filter refers following variables:
 360
 361         Variable filename-limit-length
 362
 363           Limit size of file-name.
 364
 365         Variable filename-replacement-alist
 366
 367           Alist list of characters vs. string as replacement.  List of
 368           characters represents characters not allowed as file-name.
 369
 370
 371 Bug reports
 372 ===========
 373
 374   If you write bug-reports and/or suggestions for improvement, please
 375   send them to the APEL Mailing List:
 376
 377         apel-en@m17n.org        (English)
 378         apel-ja@m17n.org        (Japanese)
 379
 380   Via the APEL ML, you can report APEL bugs, obtain the latest release
 381   of APEL, and discuss future enhancements to APEL.  To join the APEL
 382   ML, send an empty e-mail to
 383
 384         apel-en-ctl@m17n.org    (English)
 385         apel-ja-ctl@m17n.org    (Japanese)
 386
 387
 388 Anonymous FTP
 389 =============
 390
 391   Latest release of APEL can be obtained from:
 392
 393     ftp://ftp.m17n.org/pub/mule/apel/
 394
 395
 396 CVS
 397 ===
 398
 399   Development of APEL uses CVS.  So latest developing version is
 400   available at CVS.
 401
 402 (0) cvs login (first time only)
 403
 404     % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login
 405
 406     CVS password: [CR] # NULL string
 407
 408 (1) checkout
 409
 410     % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout apel
 411
 412   If you would like to join CVS based development, please send mail to
 413
 414         cvs@cvs.m17n.org
 415
 416   with your account name and your public key for ssh.  cvsroot is
 417   :ext:cvs@cvs.m17n.org:/cvs/root.
 418
 419   If you cannot use ssh, please send UNIX /etc/passwd style crypted
 420   password.  you can commit with the cvsroot
 421   :pserver:<accountname>@cvs.m17n.org:/cvs/root.
 422
 423   We hope you will join the open development.