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