1-*- outline -*- 2 3[README for APEL (English Version)] 4 5* What's APEL? 6 7APEL stands for "A Portable Emacs Library". It consists of following 8modules: 9 10** poe.el 11 12This is an emulation module mainly for basic functions and special 13forms/macros of latest emacsen. 14 15 poe-xemacs.el --- for XEmacs 16 pym.el --- macros for poe. 17 18** poem.el 19 20This module provides basic functions to write portable MULE programs. 21 22 poem-ltn1.el --- for Emacs 19/XEmacs without MULE 23 poem-20.el --- shared module between Emacs 20 and XEmacs-MULE 24 poem-e20_3.el --- for Emacs 20.3 25 poem-xm.el --- for XEmacs-MULE 26 27** pces.el 28 29This module provides portable character encoding scheme 30(coding-system) features. 31 32 pces-20.el --- for Emacs 20 and XEmacs with coding-system. 33 pces-e20.el --- for Emacs 20. 34 pces-raw.el --- for emacsen without coding-system features. 35 pces-xfc.el --- for XEmacs with file coding. 36 pces-xm.el --- for XEmacs-mule. 37 38** invisible.el 39 40This modules provides features about invisible region. 41 42 inv-19.el --- for Emacs 19 43 inv-23.el --- for Emacs 23 44 inv-xemacs.el --- for XEmacs 45 46** mcharset.el 47 48This modules provides MIME charset related features. 49 50 mcs-ltn1.el --- for Emacs 19/XEmacs without MULE 51 mcs-20.el --- shared module between Emacs 20 and XEmacs-MULE 52 mcs-e20.el --- for Emacs 20 53 mcs-xm.el --- for XEmacs-MULE 54 mcs-xmu.el --- for XEmacs-MULE to unify ISO646 characters 55 56** static.el --- utility for static evaluation 57 58** broken.el --- provide information of broken facilities of Emacs 59 60** pccl.el --- utility to write portable CCL program 61 62 pccl-20.el --- for Emacs 20/XEmacs-21-MULE 63 64** alist.el: utility for Association-list 65 66** calist.el: utility for condition tree and condition/situation-alist 67 68** path-util.el: utility for path management or file detection 69 70** filename.el: utility to make file-name 71 72** install.el: utility to install emacs-lisp package 73 74** mule-caesar.el: ROT 13-47-48 Caesar rotation utility 75 76** emu.el 77 78This module provides emu bundled in tm-7.106 compatibility. It 79required poe, poem and mcharset. 80 81 richtext.el --- text/richtext module for Emacs 19.29 or later, 82 XEmacs 19.14 or later 83 84** pcustom.el --- provide portable custom environment 85 86** product.el --- Functions for product version information. 87 88* Installation 89 90** run in expanded place 91 92If you don't want to install other directories, please do only 93following (You can use make.bat for MS-DOS OS family. If you want to 94use it, see `make.bat (for MS-DOS family)'): 95 96 % make 97 98You can specify the emacs command name, for example 99 100 % make EMACS=xemacs 101 102If `EMACS=...' is omitted, EMACS=emacs is used. 103 104** make install 105 106If you want to install other directories, please do following: 107 108 % make install 109 110You can specify the emacs command name, for example 111 112 % make install EMACS=xemacs 113 114If `EMACS=...' is omitted, EMACS=emacs is used. 115 116You can specify the prefix of the directory tree for Emacs Lisp 117programs and shell scripts, for example: 118 119 % make install PREFIX=~/ 120 121If `PREFIX=...' is omitted, the prefix of the directory tree of the 122specified emacs command is used (perhaps /usr/local). 123 124For example, if PREFIX=/usr/local and Emacs 20.2 is specified, it 125will create the following directory tree: 126 127 /usr/local/share/emacs/20.2/site-lisp/ --- emu 128 /usr/local/share/emacs/site-lisp/apel/ --- APEL 129 130You can specify the lisp directory for Emacs Lisp programs, 131for example: 132 133 % make install LISPDIR=~/elisp 134 135You can also specify the version specific lisp directory where the 136emu modules will be installed in, for example: 137 138 % make install VERSION_SPECIFIC_LISPDIR=~/elisp 139 140If you would like to know what files belong to the emu modules or 141the apel modules, or where they will be installed in, for example, 142please type the following command. 143 144 % make what-where LISPDIR=~/elisp VERSION_SPECIFIC_LISPDIR=~/elisp 145 146You can specify other optional settings by editing the file 147APEL-CFG. Please read comments in it. 148 149** install as a XEmacs package 150 151If you want to install to XEmacs package directory, please do 152following: 153 154 % make install-package 155 156You can specify the emacs command name, for example 157 158 % make install-package XEMACS=xemacs-21 159 160If `XEMACS=...' is omitted, XEMACS=xemacs is used. 161 162You can specify the package directory, for example: 163 164 % make install PACKAGEDIR=~/.xemacs 165 166If `PACKAGEDIR=...' is omitted, the first existing package 167directory is used. 168 169Notice that XEmacs package system requires XEmacs 21.0 or later. 170 171 172** make.bat (for MS-DOS family) 173 174make.bat is available for MS-DOS family. You have to edit 175make.bat if you want to use it. If you use cygwin environment, 176you can use make.exe and Makefile instead of make.bat. 177 178In make.bat, a line which contain `rem' in its beginning is a 179comment. You have to insert or delete `rem', if necessary. 180 181Default setups of make.bat is; 182 183 set MEADOWVER=1.10 184 set PREFIX=c:\usr\meadow 185 set EMACS=%PREFIX%\%MEADOWVER%\bin\meadow95.exe 186 set LISPDIR=%PREFIX%\site-lisp 187 set VLISPDIR=%PREFIX%\%MEADOWVER%\site-lisp 188 189It assumes that meadow executable binary exists in 190c:\usr\meadow\1.10\bin\meadow95.exe. On such basis make.bat will 191try to install meadow version independent modules of APEL to; 192 193 c:\usr\meadow\site-lisp 194 195and meadow version dependent modules to; 196 197 c:\usr\meadow\1.10\site-lisp 198 199Please edit make.bat for your own environment and run make.bat 200 201Emacs 19.3x or earlier does not have (e.x. Mule for Windows based on 20219.28) an Emacs version dependent site-lisp directory 203(e.x. c:\usr\meadow\1.10\site-lisp), and its load-path does not refer 204to such directory by default. If you want install APEL to such an Emacs 205you may install all APEL modules to an Emacs version independent 206site-lisp directory such as c:\usr\mule\site-lisp. 207 208We cannot provide you with a Demacs example for make.bat. If you 209install APEL to Demacs, please send us such an example to 210apel-en@lists.chise.org (you can post a message to the ML, even if you 211are not a member). 212 213 214* load-path (for Emacs or MULE) 215 216If you are using Emacs or Mule, please add directory of apel to 217load-path. If you install by default setting with Emacs 19.29 or 218later or Emacs 20.1/20.2, you can write subdirs.el for example: 219 220-------------------------------------------------------------------- 221(normal-top-level-add-to-load-path '("apel")) 222-------------------------------------------------------------------- 223 224If you are using Emacs 20.3 or later or XEmacs, there are no need to 225set up load-path with normal installation. 226 227 228* How to use 229 230** alist 231 232*** Function put-alist (ITEM VALUE ALIST) 233 234Modify ALIST to set VALUE to ITEM. If there is a pair whose car is 235ITEM, replace its cdr by VALUE. If there is not such pair, create 236new pair (ITEM . VALUE) and return new alist whose car is the new 237pair and cdr is ALIST. 238 239*** Function del-alist (ITEM ALIST) 240 241If there is a pair whose key is ITEM, delete it from ALIST. 242 243*** Function set-alist (SYMBOL ITEM VALUE) 244 245Modify a alist indicated by SYMBOL to set VALUE to ITEM. 246 247 Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode) 248 249*** Function modify-alist (MODIFIER DEFAULT) 250 251Modify alist DEFAULT into alist MODIFIER. 252 253*** Function set-modified-alist (SYMBOL MODIFIER) 254 255Modify a value of a SYMBOL into alist MODIFIER. The SYMBOL should be 256alist. If it is not bound, its value regard as nil. 257 258** path-util 259 260*** Function add-path (PATH &rest OPTIONS) 261 262Add PATH to `load-path' if it exists under `default-load-path' 263directories and it does not exist in `load-path'. 264 265You can use following PATH styles: 266 267 load-path relative: "PATH" (it is searched from `default-load-path') 268 269 home directory relative: "~/PATH" "~USER/PATH" 270 271 absolute path: "/FOO/BAR/BAZ" 272 273You can specify following OPTIONS: 274 275 'all-paths --- search from `load-path' instead of 276 `default-load-path' 277 278 'append --- add PATH to the last of `load-path' 279 280*** Function add-latest-path (PATTERN &optional ALL-PATHS) 281 282Add latest path matched by regexp PATTERN to `load-path' if it 283exists under `default-load-path' directories and it does not exist 284in `load-path'. 285 286For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp, 287and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is 288/usr/local/share/emacs/site-lisp, 289 290 (add-latest-path "bbdb") 291 292it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of 293`load-path'. 294 295If optional argument ALL-PATHS is specified, it is searched from all 296of `load-path' instead of `default-load-path'. 297 298*** Function get-latest-path (PATTERN &optional ALL-PATHS) 299 300Return latest directory in default-load-path which is matched to 301regexp PATTERN. If optional argument ALL-PATHS is specified, it is 302searched from all of load-path instead of default-load-path. 303 304 Ex. (let ((gnus-path (get-latest-path "gnus"))) 305 (add-path (expand-file-name "lisp" gnus-path)) 306 (add-to-list 'Info-default-directory-list 307 (expand-file-name "texi" gnus-path))) 308 309*** Function file-installed-p (FILE &optional PATHS) 310 311Return absolute-path of FILE if FILE exists in PATHS. If PATHS is 312omitted, `load-path' is used. 313 314*** Function exec-installed-p (FILE &optional PATHS SUFFIXES) 315 316Return absolute-path of FILE if FILE exists in PATHS. If PATHS is 317omitted, `exec-path' is used. If SUFFIXES is omitted, 318`exec-suffix-list' is used. 319 320*** Function module-installed-p (MODULE &optional PATHS) 321 322Return non-nil if MODULE is provided or exists in PATHS. If PATHS is 323omitted, `load-path' is used. 324 325** filename 326 327*** Function replace-as-filename (string) 328 329Return safety file-name from STRING. 330 331It refers variable `filename-filters'. It is list of functions for 332file-name filter. Default filter refers following variables: 333 334**** Variable filename-limit-length 335 336Limit size of file-name. 337 338**** Variable filename-replacement-alist 339 340Alist list of characters vs. string as replacement. List of 341characters represents characters not allowed as file-name. 342 343 344* Bug reports 345 346If you write bug-reports and/or suggestions for improvement, please 347send them to the APEL Mailing List: 348 349 apel-en@lists.chise.org (English) 350 apel-ja@lists.chise.org (Japanese) 351 352Via the APEL ML, you can report APEL bugs, obtain the latest release 353of APEL, and discuss future enhancements to APEL. To join the APEL 354ML, please see the descriptions of the following pages: 355 356 http://lists.chise.org/mailman/listinfo/apel-en (English) 357 http://lists.chise.org/mailman/listinfo/apel-ja (Japanese) 358 359 360* Download 361 362The latest release of APEL can be obtained from: 363 364 http://git.chise.org/elisp/dist/apel/ 365 366 367* Git 368 369Development of APEL uses Git. So the latest developing version is 370available at the following Git repository: 371 372 % git clone http://git.chise.org/git/elisp/apel.git 373 374Or you can view the APEL repository via WWW at: 375 376 http://git.chise.org/gitweb/?p=elisp/apel.git 377 378If you would like to join Git based development, please declare it in 379the APEL mailing list. 380 381We hope you will join the open development. 382