README.en

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