X-Git-Url: http://git.chise.org/gitweb/?p=elisp%2Fapel.git;a=blobdiff_plain;f=README.en;h=87003a3632d88cafb14f701566000aa2c9a494a4;hp=cede2edbf8bed00bef2a052945d6afb6d8498120;hb=24a3e5bce8c3c1228130d84b297002c73b185f70;hpb=6a5359dee2763bf52c359cf824a2e7f33bcabda2 diff --git a/README.en b/README.en index cede2ed..87003a3 100644 --- a/README.en +++ b/README.en @@ -1,328 +1,486 @@ +-*- outline -*- + [README for APEL (English Version)] -What's APEL? -============ +* What's APEL? + +APEL stands for "A Portable Emacs Library". It consists of following +modules: + +** poe.el + +This is an emulation module mainly for basic functions and special +forms/macros of latest emacsen. + + poe-xemacs.el --- for XEmacs + poe-18.el --- for Emacs 18/Nemacs + env.el --- env.el for Emacs 18 + localhook.el --- hook functions for Emacs 19.28 and earlier. + pym.el --- macros for poe. + +** poem.el + +This module provides basic functions to write portable MULE programs. + + poem-nemacs.el --- for Nemacs + poem-ltn1.el --- for Emacs 19/XEmacs without MULE + poem-om.el --- for MULE 1.*, 2.* + poem-20.el --- shared module between Emacs 20 and XEmacs-MULE + poem-e20_2.el --- for Emacs 20.1/20.2 + poem-e20_3.el --- for Emacs 20.3 + poem-xm.el --- for XEmacs-MULE + +** pces.el + +This module provides portable character encoding scheme +(coding-system) features. + + pces-20.el --- for Emacs 20 and XEmacs with coding-system. + pces-e20.el --- for Emacs 20. + pces-e20_2.el --- for Emacs 20.1 and 20.2. + pces-nemacs.el --- for Nemacs. + pces-om.el --- for Mule 1.* and Mule 2.*. + pces-raw.el --- for emacsen without coding-system features. + pces-xfc.el --- for XEmacs with file coding. + pces-xm.el --- for XEmacs-mule. + +** invisible.el + +This modules provides features about invisible region. + + inv-18.el --- for Emacs 18 + inv-19.el --- for Emacs 19 + inv-xemacs.el --- for XEmacs + +** mcharset.el + +This modules provides MIME charset related features. + + mcs-nemacs.el --- for Nemacs + mcs-ltn1.el --- for Emacs 19/XEmacs without MULE + mcs-om.el --- for MULE 1.*, 2.* + mcs-20.el --- shared module between Emacs 20 and XEmacs-MULE + mcs-e20.el --- for Emacs 20 + mcs-xm.el --- for XEmacs-MULE + mcs-xmu.el --- for XEmacs-MULE to unify ISO646 characters + +** static.el --- utility for static evaluation + +** broken.el --- provide information of broken facilities of Emacs + +** pccl.el --- utility to write portable CCL program + + pccl-om.el --- for MULE 2.* + pccl-20.el --- for Emacs 20/XEmacs-21-MULE + +** alist.el: utility for Association-list + +** calist.el: utility for condition tree and condition/situation-alist + +** path-util.el: utility for path management or file detection + +** filename.el: utility to make file-name + +** install.el: utility to install emacs-lisp package + +** mule-caesar.el: ROT 13-47-48 Caesar rotation utility + +** emu.el + +This module provides emu bundled in tm-7.106 compatibility. It +required poe, poem and mcharset. + + emu-mule: --- for MULE 1.*, 2.*. + richtext.el --- text/richtext module for Emacs 19.29 or later, + XEmacs 19.14 or later + tinyrich.el --- text/richtext module for old emacsen + +** pcustom.el --- provide portable custom environment + + tinycustom.el --- emulation module of custom.el + +** timezone.el + +This is a utility of time zone. This is a Y2K fixed version. This +works with old GNUS 3.14.4 under version 18 of Emacs, too. + +** product.el --- Functions for product version information. + +* Installation + +** run in expanded place + +If you don't want to install other directories, please do only +following (You can use make.bat for MS-DOS OS family. If you want to +use it, see `make.bat (for MS-DOS family)'): + + % make + +You can specify the emacs command name, for example + + % make EMACS=xemacs + +If `EMACS=...' is omitted, EMACS=emacs is used. + +** make install + +If you want to install other directories, please do following: + + % make install + +You can specify the emacs command name, for example + + % make install EMACS=xemacs + +If `EMACS=...' is omitted, EMACS=emacs is used. + +You can specify the prefix of the directory tree for Emacs Lisp +programs and shell scripts, for example: + + % make install PREFIX=~/ + +If `PREFIX=...' is omitted, the prefix of the directory tree of the +specified emacs command is used (perhaps /usr/local). + +For example, if PREFIX=/usr/local and Emacs 20.2 is specified, it +will create the following directory tree: + + /usr/local/share/emacs/20.2/site-lisp/ --- emu + /usr/local/share/emacs/site-lisp/apel/ --- APEL + +You can specify the lisp directory for Emacs Lisp programs, +for example: + + % make install LISPDIR=~/elisp + +You can also specify the version specific lisp directory where the +emu modules will be installed in, for example: - APEL stands for "A Portable Emacs Library". It consists of - following modules: + % make install VERSION_SPECIFIC_LISPDIR=~/elisp - poe.el --- emulation module mainly for basic functions and special - forms/macros of latest emacsen - poe-xemacs.el --- for XEmacs - poe-18.el --- for Emacs 18/Nemacs - env.el --- env.el for Emacs 18 +If you would like to know what files belong to the emu modules or +the apel modules, or where they will be installed in, for example, +please type the following command. - poem.el --- provide basic functions to write portable MULE - programs - poem-nemacs.el --- for Nemacs - poem-ltn1.el --- for Emacs 19/XEmacs without MULE - poem-om.el --- for MULE 1.*, 2.* - poem-20.el --- shared module between Emacs 20 and XEmacs-MULE - poem-e20_2.el --- for Emacs 20.1/20.2 - poem-e20_3.el --- for Emacs 20.3 - poem-xm.el --- for XEmacs-MULE + % make what-where LISPDIR=~/elisp VERSION_SPECIFIC_LISPDIR=~/elisp - invisible.el --- provide features about invisible region - inv-18.el --- for Emacs 18 - inv-19.el --- for Emacs 19 - inv-xemacs.el --- for XEmacs +You can specify other optional settings by editing the file +APEL-CFG. Please read comments in it. - mcharset.el --- provide MIME charset related features - mcs-nemacs.el --- for Nemacs - mcs-ltn1.el --- for Emacs 19/XEmacs without MULE - mcs-om.el --- for MULE 1.*, 2.* - mcs-20.el --- shared module between Emacs 20 and XEmacs-MULE - mcs-e20.el --- for Emacs 20 - mcs-xm.el --- for XEmacs-MULE +** install as a XEmacs package - broken.el --- provide information of broken facilities of Emacs. +If you want to install to XEmacs package directory, please do +following: - pccl.el --- utility to write portable CCL program - pccl-om.el --- for MULE 1.*, 2.* - pccl-20.el --- for Emacs 20/XEmacs-21-MULE + % make install-package - alist.el: utility for Association-list +You can specify the emacs command name, for example - calist.el: utility for condition tree and - condition/situation-alist + % make install-package XEMACS=xemacs-21 - path-util.el: utility for path management or file detection +If `XEMACS=...' is omitted, XEMACS=xemacs is used. - filename.el: utility to make file-name +You can specify the package directory, for example: - install.el: utility to install emacs-lisp package + % make install PACKAGEDIR=~/.xemacs - mule-caesar.el: ROT 13-47-48 Caesar rotation utility +If `PACKAGEDIR=...' is omitted, the first existing package +directory is used. - emu.el --- (emu bundled in tm-7.106 compatibility module; it - required poe, poem and mcharset) - emu-mule: for MULE 1.*, 2.* - richtext.el --- text/richtext module - for Emacs 19.29 or later, - XEmacs 19.14 or later - tinyrich.el --- text/richtext module for old emacsen +Notice that XEmacs package system requires XEmacs 21.0 or later. -Installation -============ +** make.bat (for MS-DOS family) -(a) run in expanded place +make.bat is available for MS-DOS family. You have to edit +make.bat if you want to use it. If you use cygwin environment, +you can use make.exe and Makefile instead of make.bat. - If you don't want to install other directories, please do only - following: +In make.bat, a line which contain `rem' in its beginning is a +comment. You have to insert or delete `rem', if necessary. - % make +Default setups of make.bat is; - You can specify the emacs command name, for example + set MEADOWVER=1.10 + set PREFIX=c:\usr\meadow + set EMACS=%PREFIX%\%MEADOWVER%\bin\meadow95.exe + set LISPDIR=%PREFIX%\site-lisp + set VLISPDIR=%PREFIX%\%MEADOWVER%\site-lisp - % make EMACS=xemacs +It assumes that meadow executable binary exists in +c:\usr\meadow\1.10\bin\meadow95.exe. On such basis make.bat will +try to install meadow version independent modules of APEL to; - If `EMACS=...' is omitted, EMACS=emacs is used. + c:\usr\meadow\site-lisp -(b) make install +and meadow version dependent modules to; - If you want to install other directories, please do following: + c:\usr\meadow\1.10\site-lisp - % make install +Please edit make.bat for your own environment and run make.bat - You can specify the emacs command name, for example +Emacs 19.3x or earlier does not have (e.x. Mule for Windows based on +19.28) an Emacs version dependent site-lisp directory +(e.x. c:\usr\meadow\1.10\site-lisp), and its load-path does not refer +to such directory by default. If you want install APEL to such an Emacs +you may install all APEL modules to an Emacs version independent +site-lisp directory such as c:\usr\mule\site-lisp. - % make install EMACS=xemacs +We cannot provide you with a Demacs example for make.bat. If you +install APEL to Demacs, please send us such an example to +apel-en@lists.chise.org (you can post a message to the ML, even if you +are not a member). - If `EMACS=...' is omitted, EMACS=emacs is used. +If you checkout APEL by using Windows native cvs.exe (not cygwin +version), cvs.exe will regularize end of line codes, LF to CRLF. And +it also will try to convert CRLF to CRCRLF. make.bat of which eol +code is CRCRLF does not work, so if you get such a make.bat, edit it +to really regularize eol codes to CRLF. If you need further +information, see the following URL (n.b. Japanese only) - You can specify the prefix of the directory tree for Emacs Lisp - programs and shell scripts, for example: + http://openlab.ring.gr.jp/skk/cvswin-ja.html - % make install PREFIX=~/ +* load-path (for Emacs or MULE) - If `PREFIX=...' is omitted, the prefix of the directory tree of the - specified emacs command is used (perhaps /usr/local). +If you are using Emacs or Mule, please add directory of apel to +load-path. If you install by default setting with Emacs 19.29 or +later or Emacs 20.1/20.2, you can write subdirs.el for example: - For example, if PREFIX=/usr/local and Emacs 20.2 is specified, it - will create the following directory tree: +-------------------------------------------------------------------- +(normal-top-level-add-to-load-path '("apel")) +-------------------------------------------------------------------- - /usr/local/share/emacs/20.2/site-lisp/ --- emu - /usr/local/share/emacs/site-lisp/apel/ --- APEL +If you are using Emacs 20.3 or later or XEmacs, there are no need to +set up load-path with normal installation. - You can specify the lisp directory for Emacs Lisp programs, - for example: - % make install LISPDIR=~/elisp +* Version specific information - You can also specify the version specific lisp directory where the - emu modules will be installed in, for example: +** For Emacs 18 users: "old byte-compiler" vs "new byte-compiler" - % make install VERSION_SPECIFIC_LISPDIR=~/elisp +In this package, we use compile-time evaluation heavily. +Unfortunately, the byte-compiler bundled with Emacs 18 (the "old +byte-compiler") does not have features such as `eval-when-compile' +and `eval-and-compile', and our emulation version of these macros +evaluate "compile-time evaluation" at load-time or at run-time! +In addition, the "old byte-compiler" cannot compile top-level use of +macros and leaves most of our code uncompiled. - If you would like to know what files belong to the emu modules or - the apel modules, or where they will be installed in, for example, - please type the following command. +Therefore, we recommend you to use the "new" optimizing byte-compiler. +It is the origin of byte-compiler bundled with Emacs 19 and later. - % make what-where LISPDIR=~/elisp VERSION_SPECIFIC_LISPDIR=~/elisp +Optimizing byte-compiler for Emacs 18 is available from the Emacs +Lisp Archive and its mirrors. - You can specify other optional settings by editing the file - APEL-CFG. Please read comments in it. +In Mule 1.* days, "contrib" package for Mule 1.* was distributed and +it contained the "new byte-compiler" for Mule. But, I think it is +difficult to obtain this package now. -(c) install as a XEmacs package +AFAIK, the "new byte-compiler" for Emacs 18 is also bundled with SKK +9.6 or SKK 10.62a. You can get SKK 10.62a from the following URL; - If you want to install to XEmacs package directory, please do - following: + http://openlab.ring.gr.jp/skk/maintrunk - % make install-package +They include patch for Mule 1.*. - You can specify the emacs command name, for example - % make install-package XEMACS=xemacs-21 +** For Emacs 19.34 and XEmacs 19.14 users: "old custom" vs "new custom" - If `XEMACS=...' is omitted, XEMACS=xemacs is used. +"custom" library bundled with Emacs 19.32 - 19.34, XEmacs 19.14, and +Gnus 5.2/5.3 is "old", its API is incompatible with "new custom" +bundled with Emacs 20.1, XEmacs 19.15, or newer, and Gnus 5.4/5.5. - You can specify the package directory, for example: +"new custom" for Emacs 19.34 and XEmacs 19.15 - 20.2 is available +from the following URL. - % make install PACKAGEDIR=~/.xemacs +ftp://ftp.dina.kvl.dk/pub/Staff/Per.Abrahamsen/custom/custom-1.9962.tar.gz - If `PACKAGEDIR=...' is omitted, the first existing package - directory is used. +(Note that "new custom" bundled with XEmacs 19.15 - 20.2, and Gnus +5.4/5.5 is older than this version.) - Notice that XEmacs package system requires XEmacs 21.0 or later. +Before installing "new custom", you should check the following points. + 1) If you stick to Gnus 5.2/5.3 (or any other applications which + use "old custom"), you should not install "new custom". -load-path (for Emacs or MULE) -============================= + 2) If you use Mule (based on Emacs 19), you must apply this patch + to "new custom". - If you are using Emacs or Mule, please add directory of apel to - load-path. If you install by default setting with Emacs 20.1/20.2, - you can write subdirs.el for example: +----8<------8<------8<------8<------8<------8<------8<------8<---- +--- custom-1.9962/cus-face.el~ Wed Mar 4 19:52:39 1998 ++++ custom-1.9962/cus-face.el Mon Mar 9 08:05:33 1998 +@@ -96,7 +96,7 @@ + "Define a new FACE on all frames, ignoring X resources." + (interactive "SMake face: ") + (or (internal-find-face name) +- (let ((face (make-vector 8 nil))) ++ (let ((face (make-vector face-vector-length nil))) + (aset face 0 'face) + (aset face 1 name) + (let* ((frames (frame-list)) +----8<------8<------8<------8<------8<------8<------8<------8<---- - -------------------------------------------------------------------- - (normal-top-level-add-to-load-path '("apel")) - -------------------------------------------------------------------- + 3) Applications compiled with "custom" require the same version of + "custom" at load-time (and run-time). Therefore, if you use "new + custom", you must always include "new custom" in your load-path. + The easiest way to achieve this is "subdirs.el"; if you installed + "new custom" in "/usr/local/share/emacs/19.34/site-lisp/custom/", + put the following line to "/usr/local/share/emacs/19.34/site-lisp/subdirs.el". - If you are using Emacs 20.3 or later or XEmacs, there are no need to - set up load-path with normal installation. + (normal-top-level-add-to-load-path '("custom")) -How to use -========== +* How to use -alist ------ +** alist -Function put-alist (ITEM VALUE ALIST) +*** Function put-alist (ITEM VALUE ALIST) - Modify ALIST to set VALUE to ITEM. If there is a pair whose car is - ITEM, replace its cdr by VALUE. If there is not such pair, create - new pair (ITEM . VALUE) and return new alist whose car is the new - pair and cdr is ALIST. +Modify ALIST to set VALUE to ITEM. If there is a pair whose car is +ITEM, replace its cdr by VALUE. If there is not such pair, create +new pair (ITEM . VALUE) and return new alist whose car is the new +pair and cdr is ALIST. -Function del-alist (ITEM ALIST) +*** Function del-alist (ITEM ALIST) - If there is a pair whose key is ITEM, delete it from ALIST. +If there is a pair whose key is ITEM, delete it from ALIST. -Function set-alist (SYMBOL ITEM VALUE) +*** Function set-alist (SYMBOL ITEM VALUE) - Modify a alist indicated by SYMBOL to set VALUE to ITEM. +Modify a alist indicated by SYMBOL to set VALUE to ITEM. Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode) -Function modify-alist (MODIFIER DEFAULT) +*** Function modify-alist (MODIFIER DEFAULT) - Modify alist DEFAULT into alist MODIFIER. +Modify alist DEFAULT into alist MODIFIER. -Function set-modified-alist (SYMBOL MODIFIER) +*** Function set-modified-alist (SYMBOL MODIFIER) - Modify a value of a SYMBOL into alist MODIFIER. The SYMBOL should - be alist. If it is not bound, its value regard as nil. +Modify a value of a SYMBOL into alist MODIFIER. The SYMBOL should be +alist. If it is not bound, its value regard as nil. -path-util ---------- +** path-util -Function add-path (PATH &rest OPTIONS) +*** Function add-path (PATH &rest OPTIONS) - Add PATH to `load-path' if it exists under `default-load-path' - directories and it does not exist in `load-path'. +Add PATH to `load-path' if it exists under `default-load-path' +directories and it does not exist in `load-path'. - You can use following PATH styles: +You can use following PATH styles: - load-path relative: "PATH" (it is searched from - `default-load-path') + load-path relative: "PATH" (it is searched from `default-load-path') - home directory relative: "~/PATH" "~USER/PATH" + home directory relative: "~/PATH" "~USER/PATH" - absolute path: "/FOO/BAR/BAZ" + absolute path: "/FOO/BAR/BAZ" - You can specify following OPTIONS: +You can specify following OPTIONS: - 'all-paths --- search from `load-path' instead of - `default-load-path' + 'all-paths --- search from `load-path' instead of + `default-load-path' - 'append --- add PATH to the last of `load-path' + 'append --- add PATH to the last of `load-path' -Function add-latest-path (PATTERN &optional ALL-PATHS) +*** Function add-latest-path (PATTERN &optional ALL-PATHS) - Add latest path matched by regexp PATTERN to `load-path' if it - exists under `default-load-path' directories and it does not exist - in `load-path'. +Add latest path matched by regexp PATTERN to `load-path' if it +exists under `default-load-path' directories and it does not exist +in `load-path'. - For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp, - and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is - /usr/local/share/emacs/site-lisp, +For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp, +and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is +/usr/local/share/emacs/site-lisp, - (add-latest-path "bbdb") + (add-latest-path "bbdb") - it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of - `load-path'. +it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of +`load-path'. - If optional argument ALL-PATHS is specified, it is searched from all - of `load-path' instead of `default-load-path'. +If optional argument ALL-PATHS is specified, it is searched from all +of `load-path' instead of `default-load-path'. -Function get-latest-path (PATTERN &optional ALL-PATHS) +*** Function get-latest-path (PATTERN &optional ALL-PATHS) - Return latest directory in default-load-path which is matched to - regexp PATTERN. If optional argument ALL-PATHS is specified, it is - searched from all of load-path instead of default-load-path. +Return latest directory in default-load-path which is matched to +regexp PATTERN. If optional argument ALL-PATHS is specified, it is +searched from all of load-path instead of default-load-path. Ex. (let ((gnus-path (get-latest-path "gnus"))) (add-path (expand-file-name "lisp" gnus-path)) (add-to-list 'Info-default-directory-list - (expand-file-name "texi" gnus-path)) - ) + (expand-file-name "texi" gnus-path))) -Function file-installed-p (FILE &optional PATHS) +*** Function file-installed-p (FILE &optional PATHS) - Return absolute-path of FILE if FILE exists in PATHS. If PATHS is - omitted, `load-path' is used. +Return absolute-path of FILE if FILE exists in PATHS. If PATHS is +omitted, `load-path' is used. -Function exec-installed-p (FILE &optional PATHS SUFFIXES) +*** Function exec-installed-p (FILE &optional PATHS SUFFIXES) - Return absolute-path of FILE if FILE exists in PATHS. If PATHS is - omitted, `exec-path' is used. If SUFFIXES is omitted, - `exec-suffix-list' is used. +Return absolute-path of FILE if FILE exists in PATHS. If PATHS is +omitted, `exec-path' is used. If SUFFIXES is omitted, +`exec-suffix-list' is used. -Function module-installed-p (MODULE &optional PATHS) +*** Function module-installed-p (MODULE &optional PATHS) - Return non-nil if MODULE is provided or exists in PATHS. If PATHS - is omitted, `load-path' is used. +Return non-nil if MODULE is provided or exists in PATHS. If PATHS is +omitted, `load-path' is used. -filename --------- +** filename -Function replace-as-filename (string) +*** Function replace-as-filename (string) - Return safety file-name from STRING. +Return safety file-name from STRING. - It refers variable `filename-filters'. It is list of functions for - file-name filter. Default filter refers following variables: +It refers variable `filename-filters'. It is list of functions for +file-name filter. Default filter refers following variables: - Variable filename-limit-length +**** Variable filename-limit-length - Limit size of file-name. +Limit size of file-name. - Variable filename-replacement-alist +**** Variable filename-replacement-alist - Alist list of characters vs. string as replacement. List of - characters represents characters not allowed as file-name. +Alist list of characters vs. string as replacement. List of +characters represents characters not allowed as file-name. -Bug reports -=========== +* Bug reports - If you write bug-reports and/or suggestions for improvement, please - send them to the tm Mailing List: +If you write bug-reports and/or suggestions for improvement, please +send them to the APEL Mailing List: - bug-tm-en@chamonix.jaist.ac.jp (English) - bug-tm-ja@chamonix.jaist.ac.jp (Japanese) + apel-en@lists.chise.org (English) + apel-ja@lists.chise.org (Japanese) - Via the tm ML, you can report APEL bugs, obtain the latest release - of APEL, and discuss future enhancements to APEL. To join the tm - ML, send an empty e-mail to +Via the APEL ML, you can report APEL bugs, obtain the latest release +of APEL, and discuss future enhancements to APEL. To join the APEL +ML, please see the descriptions of the following pages: - tm-en-help@chamonix.jaist.ac.jp (English) - tm-ja-help@chamonix.jaist.ac.jp (Japanese) + http://lists.chise.org/mailman/listinfo/apel-en (English) + http://lists.chise.org/mailman/listinfo/apel-ja (Japanese) -CVS -=== +* Download - Development of APEL uses CVS. So latest developing version is - available at CVS. +The latest release of APEL can be obtained from: -(0) cvs login + http://git.chise.org/elisp/dist/apel/ - % cvs -d :pserver:anonymous@chamonix.jaist.ac.jp:/hare/cvs/root \ - login - CVS password: [CR] # NULL string +* Git -(1) checkout +Development of APEL uses Git. So the latest developing version is +available at the following Git repository: - % cvs -d :pserver:anonymous@chamonix.jaist.ac.jp:/hare/cvs/root \ - checkout apel + % git clone http://git.chise.org/git/elisp/apel.git +Or you can view the APEL repository via WWW at: - If you would like to join CVS based development, please send mail to + http://git.chise.org/gitweb/?p=elisp/apel.git - cvs@chamonix.jaist.ac.jp +If you would like to join Git based development, please declare it in +the APEL mailing list. - with your account name and UNIX /etc/passwd style crypted password. - We hope you will join the open development. +We hope you will join the open development.