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