README.en

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