(What's APEL?): Add std11 and mule-caesar.el.
[elisp/apel.git] / README.en
1 [README for APEL (English Version)]
2 by MORIOKA Tomohiko <morioka@jaist.ac.jp>
3 $Id: README.en,v 1.2 1997-05-10 19:39:12 morioka Exp $
4
5 What's APEL?
6 ============
7
8   APEL stands for "A Portable Emacs Library".  It consists of
9   following modules:
10
11         emu:    A package to fill incompatibilities of emacsen
12                 emu.el --- main module
13             About mule API:
14                 emu-nemacs.el --- for NEmacs
15                 emu-e19.el    --- for Emacs 19 or XEmacs without mule
16                 emu-mule.el   --- for MULE 2.3
17                 emu-e20.el    --- for Emacs/mule (Emacs 20, MULE 3)
18                 emu-x20.el    --- for XEmacs/mule
19             About other API
20                 emu-18.el     --- for Emacs 18
21                 emu-19.el     --- for Emacs 19 or later
22                 emu-xemacs.el --- for XEmacs
23                 env.el        --- env.el for Emacs 18
24                 richtext.el   --- text/richtext module
25                                     for Emacs 19.29 or later,
26                                         XEmacs 19.14 or later
27                 tinyrich.el   --- text/richtext module for old emacsen
28
29         alist.el: utility for Association-list
30
31         atype.el: utility for atype
32
33         file-detect.el: load-path or file-detection
34
35         filename.el: utility to make file-name
36
37         install.el: utility to install emacs-lisp package
38
39         mule-caesar.el: ROT 13-47-48 Caesar rotation utility
40
41         std11: RFC 822/STD 11 parser and utility
42             std11.el       --- main module
43             std11-parse.el --- parser
44
45
46 Installation
47 ============
48
49 (a) run in expanded place
50
51   If you don't want to install other directories, please do only
52   following:
53
54         % make
55
56   You can specify the emacs command name, for example
57
58         % make install EMACS=xemacs
59
60   If `EMACS=...' is omitted, EMACS=emacs is used.
61
62 (b) make install
63
64   If you want to install other directories, please do following:
65
66         % make install
67
68   You can specify the emacs command name, for example
69
70         % make install EMACS=xemacs
71
72   If `EMACS=...' is omitted, EMACS=emacs is used.
73
74   You can specify the prefix of the directory tree for Emacs Lisp
75   programs and shell scripts, for example:
76
77         % make install PREFIX=~/
78
79   If `PREFIX=...' is omitted, the prefix of the directory tree of the
80   specified emacs command is used (perhaps /usr/local).
81
82   For example, if PREFIX=/usr/local and EMACS 19.34 is specified, it
83   will create the following directory tree:
84
85         /usr/local/share/emacs/19.34/site-lisp/  --- emu
86         /usr/local/share/emacs/site-lisp/apel/   --- APEL
87
88   You can specify other optional settings by editing the file
89   APEL-CFG.  Please read comments in it.
90
91
92 load-path (for Emacs or MULE)
93 =============================
94
95   If you are using Emacs or Mule, please add directory of apel to
96   load-path.  If you install by default setting, you can write
97   subdirs.el for example:
98
99   --------------------------------------------------------------------
100   (normal-top-level-add-to-load-path '("apel"))
101   --------------------------------------------------------------------
102
103   If you are using XEmacs, there are no need of setting about
104   load-path.
105
106
107 How to use
108 ==========
109
110 alist
111 -----
112
113 Function put-alist (ITEM VALUE ALIST)
114
115   Modify ALIST to set VALUE to ITEM.  If there is a pair whose car is
116   ITEM, replace its cdr by VALUE.  If there is not such pair, create
117   new pair (ITEM . VALUE) and return new alist whose car is the new
118   pair and cdr is ALIST.
119
120 Function del-alist (ITEM ALIST)
121
122   If there is a pair whose key is ITEM, delete it from ALIST.
123
124 Function set-alist (SYMBOL ITEM VALUE)
125
126   Modify a alist indicated by SYMBOL to set VALUE to ITEM.
127
128   Ex. (set-alist 'auto-mode-alist "\\.pln$" 'text-mode)
129
130 Function modify-alist (MODIFIER DEFAULT)
131
132   Modify alist DEFAULT into alist MODIFIER.
133
134 Function set-modified-alist (SYMBOL MODIFIER)
135
136   Modify a value of a SYMBOL into alist MODIFIER.  The SYMBOL should
137   be alist. If it is not bound, its value regard as nil.
138
139 file-detect
140 -----------
141
142 Function add-path (PATH &rest OPTIONS)
143
144   Add PATH to `load-path' if it exists under `default-load-path'
145   directories and it does not exist in `load-path'.
146
147   You can use following PATH styles:
148
149     load-path relative: "PATH" (it is searched from
150                                 `defaul-load-path')
151
152     home directory relative: "~/PATH" "~USER/PATH"
153
154     absolute path: "/FOO/BAR/BAZ"
155
156   You can specify following OPTIONS:
157
158     'all-paths --- search from `load-path' instead of
159                    `default-load-path'
160
161     'append --- add PATH to the last of `load-path'
162
163 Function add-latest-path (PATTERN &optional ALL-PATHS)
164
165   Add latest path matched by regexp PATTERN to `load-path' if it
166   exists under `default-load-path' directories and it does not exist
167   in `load-path'.
168
169   For example, if there is bbdb-1.50 and bbdb-1.51 under site-lisp,
170   and if bbdb-1.51 is newer than bbdb-1.50, and site-lisp is
171   /usr/local/share/emacs/site-lisp,
172
173         (add-path "bbdb")
174
175   it adds "/usr/local/share/emacs/site-lisp/bbdb-1.51" to top of
176   `load-path'.
177
178   If optional argument ALL-PATHS is specified, it is searched from all
179   of `load-path' instead of `default-load-path'.
180
181 Function get-latest-path (PATTERN &optional ALL-PATHS)
182
183   Return latest directory in default-load-path which is matched to
184   regexp PATTERN.  If optional argument ALL-PATHS is specified, it is
185   searched from all of load-path instead of default-load-path.
186
187   Ex. (let ((gnus-path (get-latest-path "gnus")))
188         (add-path (expand-file-name "lisp" gnus-path))
189         (add-to-list 'Info-default-directory-list
190                      (expand-file-name "texi" gnus-path))
191         )
192
193 Function file-installed-p (FILE &optional PATHS)
194
195   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
196   omitted, `load-path' is used.
197
198 Function exec-installed-p (FILE &optional PATHS SUFFIXES)
199
200   Return absolute-path of FILE if FILE exists in PATHS.  If PATHS is
201   omitted, `exec-path' is used.  If suffixes is omitted,
202   `exec-suffix-list' is used.
203
204 Function module-installed-p (MODULE &optional PATHS)
205
206   Return non-nil if module is provided or exists in PATHS.  If PATHS
207   is omitted, `load-path' is used.
208
209 filename
210 --------
211
212 Function replace-as-filename (string)
213
214   Return safety file-name from STRING.
215
216   It refers variable `filename-filters'.  It is list of functions for
217   file-name filter.  Default filter refers following variables:
218
219         Variable filename-limit-length
220
221           Limit size of file-name.
222
223         Variable filename-replacement-alist
224
225           Alist list of characters vs. string as replacement.  List of
226           characters represents characters not allowed as file-name.
227
228
229 Bug reports
230 -----------
231
232   If you write bug-reports and/or suggestions for improvement, please
233   send them to the tm Mailing List:
234
235         bug-tm-en@chamonix.jaist.ac.jp  (English)
236         bug-tm-ja@chamonix.jaist.ac.jp  (Japanese)
237
238   Via the tm ML, you can report tm bugs, obtain the latest release of
239   tm, and discuss future enhancements to tm. To join the tm ML, send
240   e-mail to
241
242         tm-ja-admin@chamonix.jaist.ac.jp        (Japanese)
243         tm-en-admin@chamonix.jaist.ac.jp        (English)
244
245   Since the user registration is done manually, please write the mail
246   body in human-recognizable language (^_^).