README.en

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