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 (d) make.bat (for MS-DOS family)
 159
 160   make.bat is available for MS-DOS family.  You have to edit
 161   make.bat if you want to use it.  If you use cygwin environment,
 162   you can use make.exe and Makefile instead of make.bat.
 163
 164   In make.bat, a line which contain `rem' in its beginning is a
 165   comment.  You have to insert or delete `rem', if necessary.
 166
 167   Default setups of make.bat is;
 168
 169     set MEADOWVER=1.10
 170     set PREFIX=c:\usr\meadow
 171     set EMACS=%PREFIX%\%MEADOWVER%\bin\meadow95.exe
 172     set LISPDIR=%PREFIX%\site-lisp
 173     set VLISPDIR=%PREFIX%\%MEADOWVER%\site-lisp
 174
 175   It assumes that meadow executable binary exists in
 176   c:\usr\meadow\1.10\bin\meadow95.exe.  On such basis make.bat will
 177   try to install meadow version independent modules of APEL to;
 178
 179     c:\usr\meadow\site-lisp
 180
 181   and meadow version dependent modules to;
 182
 183     c:\usr\meadow\1.10\site-lisp
 184
 185   Please edit make.bat for your own environment and run make.bat
 186
 187   Emacs 19.3x or earlier does not have (e.x. Mule for Windows based on
 188   19.28) an Emacs version dependent site-lisp directory
 189   (e.x. c:\usr\meadow\1.10\site-lisp), and its load-path does not refer
 190   to such directory by default.  If you want install APEL to such an Emacs
 191   you may install all APEL modules to an Emacs version independent
 192   site-lisp directory such as c:\usr\mule\site-lisp.
 193
 194   We cannot provide you with a Demacs example for make.bat.  If you install
 195   APEL to Demacs, please send us such an example to apel-en@m17n.org (you
 196   can post a message to the ML, even if you are not a member).
 197
 198   If you checkout APEL by using Windows native cvs.exe (not cygwin),
 199   cvs.exe will regularize end of line codes, LF to CRLF.  And it also will
 200   try to convert CRLF to CRCRLF.  make.bat of which eol code is CRCRLF does
 201   not work, so if you get such a make.bat, edit it to really regularize eol
 202   codes to CRLF.  If you need further information, see the following URL
 203   (n.b. Japanese only)
 204
 205     http://openlab.ring.gr.jp/skk/cvswin-ja.html
 206
 207 load-path (for Emacs or MULE)
 208 =============================
 209
 210   If you are using Emacs or Mule, please add directory of apel to
 211   load-path.  If you install by default setting with Emacs 19.29 or
 212   later or Emacs 20.1/20.2, you can write subdirs.el for example:
 213
 214   --------------------------------------------------------------------
 215   (normal-top-level-add-to-load-path '("apel"))
 216   --------------------------------------------------------------------
 217
 218   If you are using Emacs 20.3 or later or XEmacs, there are no need to
 219   set up load-path with normal installation.
 220
 221
 222 Version specific information
 223 ============================
 224
 225 For Emacs 18 users: "old byte-compiler" vs "new byte-compiler"
 226
 227   In this package, we use compile-time evaluation heavily.
 228   Unfortunately, the byte-compiler bundled with Emacs 18 (the "old
 229   byte-compiler") does not have features such as `eval-when-compile'
 230   and `eval-and-compile', and our emulation version of these macros
 231   evaluate "compile-time evaluation" at load-time or at run-time!
 232   In addition, the "old byte-compiler" cannot compile top-level use of
 233   macros and leaves most of our code uncompiled.
 234
 235   Therefore, we recommend you to use the "new" optimizing byte-compiler.
 236   It is the origin of byte-compiler bundled with Emacs 19 and later.
 237
 238   Optimizing byte-compiler for Emacs 18 is available from the Emacs
 239   Lisp Archive and its mirrors.
 240
 241   In Mule 1.* days, "contrib" package for Mule 1.* was distributed and
 242   it contained the "new byte-compiler" for Mule.  But, I think it is
 243   difficult to obtain this package now.
 244
 245   AFAIK, the "new byte-compiler" for Emacs 18 is also bundled with SKK
 246   9.6 or SKK 10.62a.  You can get SKK 10.62a from the following URL;
 247     http://openlab.ring.gr.jp/skk/maintrunk
 248   They include patch for Mule 1.*.
 249
 250
 251 For Emacs 19.34 and XEmacs 19.14 users: "old custom" vs "new custom"
 252
 253   "custom" library bundled with Emacs 19.32 - 19.34, XEmacs 19.14, and
 254   Gnus 5.2/5.3 is "old", its API is incompatible with "new custom"
 255   bundled with Emacs 20.1, XEmacs 19.15, or newer, and Gnus 5.4/5.5.
 256
 257   "new custom" for Emacs 19.34 and XEmacs 19.15 - 20.2 is available
 258   from the following URL.
 259
 260   ftp://ftp.dina.kvl.dk/pub/Staff/Per.Abrahamsen/custom/custom-1.9962.tar.gz
 261
 262   (Note that "new custom" bundled with XEmacs 19.15 - 20.2, and Gnus
 263   5.4/5.5 is older than this version.)
 264
 265   Before installing "new custom", you should check the following points.
 266
 267     1) If you stick to Gnus 5.2/5.3 (or any other applications which
 268        use "old custom"), you should not install "new custom".
 269
 270     2) If you use Mule (based on Emacs 19), you must apply this patch
 271        to "new custom".
 272
 273 ----8<------8<------8<------8<------8<------8<------8<------8<----
 274 --- custom-1.9962/cus-face.el~  Wed Mar  4 19:52:39 1998
 275 +++ custom-1.9962/cus-face.el   Mon Mar  9 08:05:33 1998
 276 @@ -96,7 +96,7 @@
 277        "Define a new FACE on all frames, ignoring X resources."
 278        (interactive "SMake face: ")
 279        (or (internal-find-face name)
 280 -         (let ((face (make-vector 8 nil)))
 281 +         (let ((face (make-vector face-vector-length nil)))
 282             (aset face 0 'face)
 283             (aset face 1 name)
 284             (let* ((frames (frame-list))
 285 ----8<------8<------8<------8<------8<------8<------8<------8<----
 286
 287     3) Applications compiled with "custom" require the same version of
 288        "custom" at load-time (and run-time).  Therefore, if you use
 289        "new custom", you must always include "new custom" in your
 290        load-path.  The easiest way to achieve this is "subdirs.el";
 291        if you installed "new custom" in "/usr/local/share/emacs/19.34/
 292        site-lisp/custom/", put the following line to "/usr/local/share/
 293        emacs/19.34/site-lisp/subdirs.el".
 294
 295        (normal-top-level-add-to-load-path '("custom"))
 296
 297
 298 How to use
 299 ==========
 300
 301 alist
 302 -----
 303
 304 Function put-alist (ITEM VALUE ALIST)
 305
 306   Modify ALIST to set VALUE to ITEM.  If there is a pair whose car is
 307   ITEM, replace its cdr by VALUE.  If there is not such pair, create
 308   new pair (ITEM . VALUE) and return new alist whose car is the new
 309   pair and cdr is ALIST.
 310
 311 Function del-alist (ITEM ALIST)
 312
 313   If there is a pair whose key is ITEM, delete it from ALIST.
 314
 315 Function set-alist (SYMBOL ITEM VALUE)
 316
 317   Modify a alist indicated by SYMBOL to set VALUE to ITEM.
 318
 319   Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode)
 320
 321 Function modify-alist (MODIFIER DEFAULT)
 322
 323   Modify alist DEFAULT into alist MODIFIER.
 324
 325 Function set-modified-alist (SYMBOL MODIFIER)
 326
 327   Modify a value of a SYMBOL into alist MODIFIER.  The SYMBOL should
 328   be alist. If it is not bound, its value regard as nil.
 329
 330 path-util
 331 ---------
 332
 333 Function add-path (PATH &rest OPTIONS)
 334
 335   Add PATH to `load-path' if it exists under `default-load-path'
 336   directories and it does not exist in `load-path'.
 337
 338   You can use following PATH styles:
 339
 340     load-path relative: "PATH" (it is searched from
 341                                 `default-load-path')
 342
 343     home directory relative: "~/PATH" "~USER/PATH"
 344
 345     absolute path: "/FOO/BAR/BAZ"
 346
 347   You can specify following OPTIONS:
 348
 349     'all-paths --- search from `load-path' instead of
 350                    `default-load-path'
 351
 352     'append --- add PATH to the last of `load-path'
 353
 354 Function add-latest-path (PATTERN &optional ALL-PATHS)
 355
 356   Add latest path matched by regexp PATTERN to `load-path' if it
 357   exists under `default-load-path' directories and it does not exist
 358   in `load-path'.
 359
 360   For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp,
 361   and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is
 362   /usr/local/share/emacs/site-lisp,
 363
 364         (add-latest-path "bbdb")
 365
 366   it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of
 367   `load-path'.
 368
 369   If optional argument ALL-PATHS is specified, it is searched from all
 370   of `load-path' instead of `default-load-path'.
 371
 372 Function get-latest-path (PATTERN &optional ALL-PATHS)
 373
 374   Return latest directory in default-load-path which is matched to
 375   regexp PATTERN.  If optional argument ALL-PATHS is specified, it is
 376   searched from all of load-path instead of default-load-path.
 377
 378   Ex. (let ((gnus-path (get-latest-path "gnus")))
 379         (add-path (expand-file-name "lisp" gnus-path))
 380         (add-to-list 'Info-default-directory-list
 381                      (expand-file-name "texi" gnus-path))
 382         )
 383
 384 Function file-installed-p (FILE &optional PATHS)
 385
 386   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 387   omitted, `load-path' is used.
 388
 389 Function exec-installed-p (FILE &optional PATHS SUFFIXES)
 390
 391   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 392   omitted, `exec-path' is used.  If SUFFIXES is omitted,
 393   `exec-suffix-list' is used.
 394
 395 Function module-installed-p (MODULE &optional PATHS)
 396
 397   Return non-nil if MODULE is provided or exists in PATHS.  If PATHS
 398   is omitted, `load-path' is used.
 399
 400 filename
 401 --------
 402
 403 Function replace-as-filename (string)
 404
 405   Return safety file-name from STRING.
 406
 407   It refers variable `filename-filters'.  It is list of functions for
 408   file-name filter.  Default filter refers following variables:
 409
 410         Variable filename-limit-length
 411
 412           Limit size of file-name.
 413
 414         Variable filename-replacement-alist
 415
 416           Alist list of characters vs. string as replacement.  List of
 417           characters represents characters not allowed as file-name.
 418
 419
 420 Bug reports
 421 ===========
 422
 423   If you write bug-reports and/or suggestions for improvement, please
 424   send them to the APEL Mailing List:
 425
 426         apel-en@m17n.org        (English)
 427         apel-ja@m17n.org        (Japanese)
 428
 429   Via the APEL ML, you can report APEL bugs, obtain the latest release
 430   of APEL, and discuss future enhancements to APEL.  To join the APEL
 431   ML, send an empty e-mail to
 432
 433         apel-en-ctl@m17n.org    (English)
 434         apel-ja-ctl@m17n.org    (Japanese)
 435
 436
 437 Anonymous FTP
 438 =============
 439
 440   Latest release of APEL can be obtained from:
 441
 442     ftp://ftp.m17n.org/pub/mule/apel/
 443
 444
 445 CVS
 446 ===
 447
 448   Development of APEL uses CVS.  So latest developing version is
 449   available at CVS.
 450
 451 (0) cvs login (first time only)
 452
 453     % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root login
 454
 455     CVS password: [CR] # NULL string
 456
 457 (1) checkout
 458
 459     % cvs -d :pserver:anonymous@cvs.m17n.org:/cvs/root checkout apel
 460
 461   If you would like to join CVS based development, please send mail to
 462
 463         cvs@cvs.m17n.org
 464
 465   with your account name and your public key for ssh.  cvsroot is
 466   :ext:cvs@cvs.m17n.org:/cvs/root.
 467
 468   If you cannot use ssh, please send UNIX /etc/passwd style crypted
 469   password.  you can commit with the cvsroot
 470   :pserver:<accountname>@cvs.m17n.org:/cvs/root.
 471
 472   We hope you will join the open development.