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