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-19.el      --- for Emacs 19
  13       poe-18.el      --- for Emacs 18/Nemacs
  14          env.el      --- env.el for Emacs 18
  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     mcharset.el --- provide MIME charset related features
  27       mcs-nemacs.el --- for Nemacs
  28       mcs-ltn1.el   --- for Emacs 19/XEmacs without MULE
  29       mcs-om.el     --- for MULE 1.*, 2.*
  30       mcs-20.el     --- shared module between Emacs 20 and XEmacs-MULE
  31       mcs-e20.el    --- for Emacs 20
  32       mcs-xm.el     --- for XEmacs-MULE
  33
  34     broken.el --- provide information of broken facilities of Emacs.
  35
  36     pccl.el --- utility to write portable CCL program
  37       pccl-om.el --- for MULE 1.*, 2.*
  38       pccl-20.el --- for Emacs 20/XEmacs-MULE
  39
  40     alist.el: utility for Association-list
  41
  42     calist.el: utility for condition tree and
  43                condition/situation-alist
  44
  45     path-util.el: utility for path management or file detection
  46
  47     filename.el: utility to make file-name
  48
  49     install.el: utility to install emacs-lisp package
  50
  51     mule-caesar.el: ROT 13-47-48 Caesar rotation utility
  52
  53     emu.el --- (emu bundled in tm-7.106 compatibility module; it
  54                 required poe, poem and mcharset)
  55       emu-mule: for MULE 1.*, 2.*
  56       richtext.el   --- text/richtext module
  57                         for Emacs 19.29 or later,
  58                             XEmacs 19.14 or later
  59       tinyrich.el   --- text/richtext module for old emacsen
  60
  61
  62 Installation
  63 ============
  64
  65 (a) run in expanded place
  66
  67   If you don't want to install other directories, please do only
  68   following:
  69
  70         % make
  71
  72   You can specify the emacs command name, for example
  73
  74         % make EMACS=xemacs
  75
  76   If `EMACS=...' is omitted, EMACS=emacs is used.
  77
  78 (b) make install
  79
  80   If you want to install other directories, please do following:
  81
  82         % make install
  83
  84   You can specify the emacs command name, for example
  85
  86         % make install EMACS=xemacs
  87
  88   If `EMACS=...' is omitted, EMACS=emacs is used.
  89
  90   You can specify the prefix of the directory tree for Emacs Lisp
  91   programs and shell scripts, for example:
  92
  93         % make install PREFIX=~/
  94
  95   If `PREFIX=...' is omitted, the prefix of the directory tree of the
  96   specified emacs command is used (perhaps /usr/local).
  97
  98   For example, if PREFIX=/usr/local and Emacs 20.2 is specified, it
  99   will create the following directory tree:
 100
 101         /usr/local/share/emacs/20.2/site-lisp/  --- emu
 102         /usr/local/share/emacs/site-lisp/apel/  --- APEL
 103
 104   You can specify the lisp directory for Emacs Lisp programs,
 105   for example:
 106
 107         % make install LISPDIR=~/elisp
 108
 109   You can also specify the version specific lisp directory where the
 110   emu modules will be installed in, for example:
 111
 112         % make install VERSION_SPECIFIC_LISPDIR=~/elisp
 113
 114   If you would like to know what files belong to the emu modules or
 115   the apel modules, or where they will be installed in, for example,
 116   please type the following command.
 117
 118         % make what-where LISPDIR=~/elisp VERSION_SPECIFIC_LISPDIR=~/elisp
 119
 120   You can specify other optional settings by editing the file
 121   APEL-CFG.  Please read comments in it.
 122
 123 (c) install as a XEmacs package
 124
 125   If you want to install to XEmacs package directory, please do
 126   following:
 127
 128         % make install-package
 129
 130   You can specify the emacs command name, for example
 131
 132         % make install-package XEMACS=xemacs-21
 133
 134   If `XEMACS=...' is omitted, XEMACS=xemacs is used.
 135
 136   You can specify the package directory, for example:
 137
 138         % make install PACKAGEDIR=~/.xemacs
 139
 140   If `PACKAGEDIR=...' is omitted, the first existing package
 141   directory is used.
 142
 143   Notice that XEmacs package system requires XEmacs 21.0 or later.
 144
 145
 146 load-path (for Emacs or MULE)
 147 =============================
 148
 149   If you are using Emacs or Mule, please add directory of apel to
 150   load-path.  If you install by default setting with Emacs 20.1/20.2,
 151   you can write subdirs.el for example:
 152
 153   --------------------------------------------------------------------
 154   (normal-top-level-add-to-load-path '("apel"))
 155   --------------------------------------------------------------------
 156
 157   If you are using Emacs 20.3 or later or XEmacs, there are no need to
 158   set up load-path with normal installation.
 159
 160
 161 How to use
 162 ==========
 163
 164 alist
 165 -----
 166
 167 Function put-alist (ITEM VALUE ALIST)
 168
 169   Modify ALIST to set VALUE to ITEM.  If there is a pair whose car is
 170   ITEM, replace its cdr by VALUE.  If there is not such pair, create
 171   new pair (ITEM . VALUE) and return new alist whose car is the new
 172   pair and cdr is ALIST.
 173
 174 Function del-alist (ITEM ALIST)
 175
 176   If there is a pair whose key is ITEM, delete it from ALIST.
 177
 178 Function set-alist (SYMBOL ITEM VALUE)
 179
 180   Modify a alist indicated by SYMBOL to set VALUE to ITEM.
 181
 182   Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode)
 183
 184 Function modify-alist (MODIFIER DEFAULT)
 185
 186   Modify alist DEFAULT into alist MODIFIER.
 187
 188 Function set-modified-alist (SYMBOL MODIFIER)
 189
 190   Modify a value of a SYMBOL into alist MODIFIER.  The SYMBOL should
 191   be alist. If it is not bound, its value regard as nil.
 192
 193 path-util
 194 ---------
 195
 196 Function add-path (PATH &rest OPTIONS)
 197
 198   Add PATH to `load-path' if it exists under `default-load-path'
 199   directories and it does not exist in `load-path'.
 200
 201   You can use following PATH styles:
 202
 203     load-path relative: "PATH" (it is searched from
 204                                 `defaul-load-path')
 205
 206     home directory relative: "~/PATH" "~USER/PATH"
 207
 208     absolute path: "/FOO/BAR/BAZ"
 209
 210   You can specify following OPTIONS:
 211
 212     'all-paths --- search from `load-path' instead of
 213                    `default-load-path'
 214
 215     'append --- add PATH to the last of `load-path'
 216
 217 Function add-latest-path (PATTERN &optional ALL-PATHS)
 218
 219   Add latest path matched by regexp PATTERN to `load-path' if it
 220   exists under `default-load-path' directories and it does not exist
 221   in `load-path'.
 222
 223   For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp,
 224   and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is
 225   /usr/local/share/emacs/site-lisp,
 226
 227         (add-path "bbdb")
 228
 229   it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of
 230   `load-path'.
 231
 232   If optional argument ALL-PATHS is specified, it is searched from all
 233   of `load-path' instead of `default-load-path'.
 234
 235 Function get-latest-path (PATTERN &optional ALL-PATHS)
 236
 237   Return latest directory in default-load-path which is matched to
 238   regexp PATTERN.  If optional argument ALL-PATHS is specified, it is
 239   searched from all of load-path instead of default-load-path.
 240
 241   Ex. (let ((gnus-path (get-latest-path "gnus")))
 242         (add-path (expand-file-name "lisp" gnus-path))
 243         (add-to-list 'Info-default-directory-list
 244                      (expand-file-name "texi" gnus-path))
 245         )
 246
 247 Function file-installed-p (FILE &optional PATHS)
 248
 249   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 250   omitted, `load-path' is used.
 251
 252 Function exec-installed-p (FILE &optional PATHS SUFFIXES)
 253
 254   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 255   omitted, `exec-path' is used.  If suffixes is omitted,
 256   `exec-suffix-list' is used.
 257
 258 Function module-installed-p (MODULE &optional PATHS)
 259
 260   Return non-nil if module is provided or exists in PATHS.  If PATHS
 261   is omitted, `load-path' is used.
 262
 263 filename
 264 --------
 265
 266 Function replace-as-filename (string)
 267
 268   Return safety file-name from STRING.
 269
 270   It refers variable `filename-filters'.  It is list of functions for
 271   file-name filter.  Default filter refers following variables:
 272
 273         Variable filename-limit-length
 274
 275           Limit size of file-name.
 276
 277         Variable filename-replacement-alist
 278
 279           Alist list of characters vs. string as replacement.  List of
 280           characters represents characters not allowed as file-name.
 281
 282
 283 Bug reports
 284 ===========
 285
 286   If you write bug-reports and/or suggestions for improvement, please
 287   send them to the tm Mailing List:
 288
 289         bug-tm-en@chamonix.jaist.ac.jp  (English)
 290         bug-tm-ja@chamonix.jaist.ac.jp  (Japanese)
 291
 292   Via the tm ML, you can report APEL bugs, obtain the latest release
 293   of APEL, and discuss future enhancements to APEL.  To join the tm
 294   ML, send an empty e-mail to
 295
 296         tm-en-help@chamonix.jaist.ac.jp (English)
 297         tm-ja-help@chamonix.jaist.ac.jp (Japanese)