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