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