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