README.en

   1 [README for APEL (English Version)]
   2 by MORIOKA Tomohiko <morioka@jaist.ac.jp>
   3 $Id: README.en,v 1.11 1998-04-17 07:39:49 morioka Exp $
   4
   5 What's APEL?
   6 ============
   7
   8   APEL stands for "A Portable Emacs Library".  It consists of
   9   following modules:
  10
  11     emu: A package to fill incompatibilities of emacsen
  12         emu.el --- main module
  13         About mule API:
  14             emu-nemacs.el --- for NEmacs
  15             emu-latin1.el --- for Emacs 19 or XEmacs without mule
  16             emu-mule.el   --- for MULE 2.3
  17             emu-20.el     --- for Emacs 20 and XEmacs with mule
  18                 emu-e20.el  --- for Emacs 20.1 or later
  19                     emu-e20_2.el  --- for Emacs 20.1, 20.2
  20                     emu-e20_3.el  --- for Emacs 20.3 or later
  21                 emu-x20.el  --- for XEmacs with mule
  22         About other API
  23             emu-18.el     --- for Emacs 18
  24             emu-e19.el    --- for Emacs 19 or later
  25             emu-xemacs.el --- for XEmacs
  26             env.el        --- env.el for Emacs 18
  27             richtext.el   --- text/richtext module
  28                                   for Emacs 19.29 or later,
  29                                       XEmacs 19.14 or later
  30             tinyrich.el   --- text/richtext module for old emacsen
  31
  32         alist.el: utility for Association-list
  33
  34         atype.el: utility for atype
  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 install 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
  91 load-path (for Emacs or MULE)
  92 =============================
  93
  94   If you are using Emacs or Mule, please add directory of apel to
  95   load-path.  If you install by default setting, you can write
  96   subdirs.el for example:
  97
  98   --------------------------------------------------------------------
  99   (normal-top-level-add-to-load-path '("apel"))
 100   --------------------------------------------------------------------
 101
 102   If you are using XEmacs, there are no need of setting about
 103   load-path.
 104
 105
 106 How to use
 107 ==========
 108
 109 alist
 110 -----
 111
 112 Function put-alist (ITEM VALUE ALIST)
 113
 114   Modify ALIST to set VALUE to ITEM.  If there is a pair whose car is
 115   ITEM, replace its cdr by VALUE.  If there is not such pair, create
 116   new pair (ITEM . VALUE) and return new alist whose car is the new
 117   pair and cdr is ALIST.
 118
 119 Function del-alist (ITEM ALIST)
 120
 121   If there is a pair whose key is ITEM, delete it from ALIST.
 122
 123 Function set-alist (SYMBOL ITEM VALUE)
 124
 125   Modify a alist indicated by SYMBOL to set VALUE to ITEM.
 126
 127   Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode)
 128
 129 Function modify-alist (MODIFIER DEFAULT)
 130
 131   Modify alist DEFAULT into alist MODIFIER.
 132
 133 Function set-modified-alist (SYMBOL MODIFIER)
 134
 135   Modify a value of a SYMBOL into alist MODIFIER.  The SYMBOL should
 136   be alist. If it is not bound, its value regard as nil.
 137
 138 path-util
 139 ---------
 140
 141 Function add-path (PATH &rest OPTIONS)
 142
 143   Add PATH to `load-path' if it exists under `default-load-path'
 144   directories and it does not exist in `load-path'.
 145
 146   You can use following PATH styles:
 147
 148     load-path relative: "PATH" (it is searched from
 149                                 `defaul-load-path')
 150
 151     home directory relative: "~/PATH" "~USER/PATH"
 152
 153     absolute path: "/FOO/BAR/BAZ"
 154
 155   You can specify following OPTIONS:
 156
 157     'all-paths --- search from `load-path' instead of
 158                    `default-load-path'
 159
 160     'append --- add PATH to the last of `load-path'
 161
 162 Function add-latest-path (PATTERN &optional ALL-PATHS)
 163
 164   Add latest path matched by regexp PATTERN to `load-path' if it
 165   exists under `default-load-path' directories and it does not exist
 166   in `load-path'.
 167
 168   For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp,
 169   and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is
 170   /usr/local/share/emacs/site-lisp,
 171
 172         (add-path "bbdb")
 173
 174   it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of
 175   `load-path'.
 176
 177   If optional argument ALL-PATHS is specified, it is searched from all
 178   of `load-path' instead of `default-load-path'.
 179
 180 Function get-latest-path (PATTERN &optional ALL-PATHS)
 181
 182   Return latest directory in default-load-path which is matched to
 183   regexp PATTERN.  If optional argument ALL-PATHS is specified, it is
 184   searched from all of load-path instead of default-load-path.
 185
 186   Ex. (let ((gnus-path (get-latest-path "gnus")))
 187         (add-path (expand-file-name "lisp" gnus-path))
 188         (add-to-list 'Info-default-directory-list
 189                      (expand-file-name "texi" gnus-path))
 190         )
 191
 192 Function file-installed-p (FILE &optional PATHS)
 193
 194   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 195   omitted, `load-path' is used.
 196
 197 Function exec-installed-p (FILE &optional PATHS SUFFIXES)
 198
 199   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
 200   omitted, `exec-path' is used.  If suffixes is omitted,
 201   `exec-suffix-list' is used.
 202
 203 Function module-installed-p (MODULE &optional PATHS)
 204
 205   Return non-nil if module is provided or exists in PATHS.  If PATHS
 206   is omitted, `load-path' is used.
 207
 208 filename
 209 --------
 210
 211 Function replace-as-filename (string)
 212
 213   Return safety file-name from STRING.
 214
 215   It refers variable `filename-filters'.  It is list of functions for
 216   file-name filter.  Default filter refers following variables:
 217
 218         Variable filename-limit-length
 219
 220           Limit size of file-name.
 221
 222         Variable filename-replacement-alist
 223
 224           Alist list of characters vs. string as replacement.  List of
 225           characters represents characters not allowed as file-name.
 226
 227
 228 Bug reports
 229 ===========
 230
 231   If you write bug-reports and/or suggestions for improvement, please
 232   send them to the tm Mailing List:
 233
 234         bug-tm-en@chamonix.jaist.ac.jp  (English)
 235         bug-tm-ja@chamonix.jaist.ac.jp  (Japanese)
 236
 237   Via the tm ML, you can report APEL bugs, obtain the latest release
 238   of APEL, and discuss future enhancements to APEL.  To join the tm
 239   ML, send an empty e-mail to
 240
 241         tm-en-help@chamonix.jaist.ac.jp (English)
 242         tm-ja-help@chamonix.jaist.ac.jp (Japanese)