README.en

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