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