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 20.1/20.2,
 163   you can write subdirs.el for example:
 164
 165   --------------------------------------------------------------------
 166   (normal-top-level-add-to-load-path '("apel"))
 167   --------------------------------------------------------------------
 168
 169   If you have installed the new CUSTOM library, e.g. custom-1.9962, to
 170   specify the path as below before building this package is advised.
 171
 172   --------------------------------------------------------------------
 173   (normal-top-level-add-to-load-path '("custom" "apel"))
 174   --------------------------------------------------------------------
 175
 176   If you are using Emacs 20.3 or later or XEmacs, there are no need to
 177   set up load-path with normal installation.
 178
 179
 180 How to use
 181 ==========
 182
 183 alist
 184 -----
 185
 186 Function put-alist (ITEM VALUE ALIST)
 187
 188   Modify ALIST to set VALUE to ITEM.  If there is a pair whose car is
 189   ITEM, replace its cdr by VALUE.  If there is not such pair, create
 190   new pair (ITEM . VALUE) and return new alist whose car is the new
 191   pair and cdr is ALIST.
 192
 193 Function del-alist (ITEM ALIST)
 194
 195   If there is a pair whose key is ITEM, delete it from ALIST.
 196
 197 Function set-alist (SYMBOL ITEM VALUE)
 198
 199   Modify a alist indicated by SYMBOL to set VALUE to ITEM.
 200
 201   Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode)
 202
 203 Function modify-alist (MODIFIER DEFAULT)
 204
 205   Modify alist DEFAULT into alist MODIFIER.
 206
 207 Function set-modified-alist (SYMBOL MODIFIER)
 208
 209   Modify a value of a SYMBOL into alist MODIFIER.  The SYMBOL should
 210   be alist. If it is not bound, its value regard as nil.
 211
 212 path-util
 213 ---------
 214
 215 Function add-path (PATH &rest OPTIONS)
 216
 217   Add PATH to `load-path' if it exists under `default-load-path'
 218   directories and it does not exist in `load-path'.
 219
 220   You can use following PATH styles:
 221
 222     load-path relative: "PATH" (it is searched from
 223                                 `default-load-path')
 224
 225     home directory relative: "~/PATH" "~USER/PATH"
 226
 227     absolute path: "/FOO/BAR/BAZ"
 228
 229   You can specify following OPTIONS:
 230
 231     'all-paths --- search from `load-path' instead of
 232                    `default-load-path'
 233
 234     'append --- add PATH to the last of `load-path'
 235
 236 Function add-latest-path (PATTERN &optional ALL-PATHS)
 237
 238   Add latest path matched by regexp PATTERN to `load-path' if it
 239   exists under `default-load-path' directories and it does not exist
 240   in `load-path'.
 241
 242   For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp,
 243   and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is
 244   /usr/local/share/emacs/site-lisp,
 245
 246         (add-latest-path "bbdb")
 247
 248   it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of
 249   `load-path'.
 250
 251   If optional argument ALL-PATHS is specified, it is searched from all
 252   of `load-path' instead of `default-load-path'.
 253
 254 Function get-latest-path (PATTERN &optional ALL-PATHS)
 255
 256   Return latest directory in default-load-path which is matched to
 257   regexp PATTERN.  If optional argument ALL-PATHS is specified, it is
 258   searched from all of load-path instead of default-load-path.
 259
 260   Ex. (let ((gnus-path (get-latest-path "gnus")))
 261         (add-path (expand-file-name "lisp" gnus-path))
 262         (add-to-list 'Info-default-directory-list
 263                      (expand-file-name "texi" gnus-path))
 264         )
 265
 266 Function file-installed-p (FILE &optional PATHS)
 267
 268   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 269   omitted, `load-path' is used.
 270
 271 Function exec-installed-p (FILE &optional PATHS SUFFIXES)
 272
 273   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 274   omitted, `exec-path' is used.  If SUFFIXES is omitted,
 275   `exec-suffix-list' is used.
 276
 277 Function module-installed-p (MODULE &optional PATHS)
 278
 279   Return non-nil if MODULE is provided or exists in PATHS.  If PATHS
 280   is omitted, `load-path' is used.
 281
 282 filename
 283 --------
 284
 285 Function replace-as-filename (string)
 286
 287   Return safety file-name from STRING.
 288
 289   It refers variable `filename-filters'.  It is list of functions for
 290   file-name filter.  Default filter refers following variables:
 291
 292         Variable filename-limit-length
 293
 294           Limit size of file-name.
 295
 296         Variable filename-replacement-alist
 297
 298           Alist list of characters vs. string as replacement.  List of
 299           characters represents characters not allowed as file-name.
 300
 301
 302 Bug reports
 303 ===========
 304
 305   If you write bug-reports and/or suggestions for improvement, please
 306   send them to the tm Mailing List:
 307
 308         bug-tm-en@chamonix.jaist.ac.jp  (English)
 309         bug-tm-ja@chamonix.jaist.ac.jp  (Japanese)
 310
 311   Via the tm ML, you can report APEL bugs, obtain the latest release
 312   of APEL, and discuss future enhancements to APEL.  To join the tm
 313   ML, send an empty e-mail to
 314
 315         tm-en-help@chamonix.jaist.ac.jp (English)
 316         tm-ja-help@chamonix.jaist.ac.jp (Japanese)
 317
 318
 319 Anonymous FTP
 320 =============
 321
 322   Latest release of APEL can be obtained from:
 323
 324     ftp://ftp.m17n.org/pub/mule/apel/
 325
 326
 327 CVS
 328 ===
 329
 330   Development of APEL uses CVS.  So latest developing version is
 331   available at CVS.
 332
 333 (0) cvs login (first time only)
 334
 335     % cvs -d :pserver:anonymous@chamonix.jaist.ac.jp:/hare/cvs/root \
 336         login
 337
 338     CVS password: [CR] # NULL string
 339
 340 (1) checkout
 341
 342     % cvs -d :pserver:anonymous@chamonix.jaist.ac.jp:/hare/cvs/root \
 343         checkout apel
 344
 345
 346   If you would like to join CVS based development, please send mail to
 347
 348         cvs@chamonix.jaist.ac.jp
 349
 350   with your account name and UNIX /etc/passwd style crypted password.
 351   We hope you will join the open development.