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