distribution-README 12.5 KB
Newer Older
Per Cederqvist's avatar
.    
Per Cederqvist committed
1
2
3



4
5
6
    The LysKOM Emacs Lisp Client
    -------------------------------------------
    Release notes for version @@CLIENTVERSION@@
David Byers's avatar
David Byers committed
7
8
9
10



    LysKOM is a project in progress at the Lysator Academic Computing
11
    Society at Linköping University in Sweden. For information about
David Byers's avatar
David Byers committed
12
13
14
15
16
17
18
19
    Lysator, see <URL:http://www.lysator.liu.se/>. For more information
    on LysKOM, see <URL:http://www.lysator.liu.se/lyskom/>.

    The latest version of the Emacs Lisp client for LysKOM is available 
    from <URL:ftp://ftp.lysator.liu.se/pub/lyskom/elisp-client/>.

    LysKOM is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by
David Byers's avatar
David Byers committed
20
21
    the Free Software Foundation; either version 2, or (at your
    option) any later version.
David Byers's avatar
David Byers committed
22
23
24
25
26
27
28
29

    LysKOM is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
    General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with LysKOM; see the file COPYING. If not, write to Lysator,
30
31
32
    c/o ISY, Linköpings universitet, S-581 83 Linköping, SWEDEN, or
    the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
    02139, USA.
David Byers's avatar
David Byers committed
33
34

    Please mail bug reports to bug-lyskom@lysator.liu.se. 
Joel Rosdahl's avatar
Joel Rosdahl committed
35
    Please mail change requests to kom@lysator.liu.se.
David Byers's avatar
David Byers committed
36
37


38

39
1.  REQUIREMENTS
David Byers's avatar
David Byers committed
40

41
42
43
    You need an Emacs. The client appears to work with the following
    versions of Emacs:

44
    * XEmacs version 20.4, 21.1 and 21.2.
45
    * Gnu Emacs version 19.34 [1]
46
    * Gnu Emacs version 20.7 and newer [2]
47
48
49
50

    [1] You'll have to replace the included custom package, and if you 
        use Gnus, you may have to update that as well.

51
    [2] It should be possible to run the client in Gnu Emacs 20.2 and
52
53
        later, but you may experience some additional problems. Column
        alignment is known to fail in version 20.2.
54

David Byers's avatar
David Byers committed
55

56
    There are also some requirements on supplemental elisp packages:
David Byers's avatar
David Byers committed
57

58
    * custom
David Byers's avatar
David Byers committed
59

60
61
62
      You need to have a recent version of the custom package
      installed. The custom.el file that is bundled with Gnu Emacs
      19.34 and older versions of Gnus will not work.
David Byers's avatar
David Byers committed
63

64
65
66
      The version that is bundled with recent versions of XEmacs, with
      Gnu Emacs 20, with recent versions of Gnus and w3 is the one you
      need.
67

68
69
70
71
72
      Custom is not longer distributed as a separate package, but it
      may be available at <URL:http://www.dina.kvl.dk/~abraham/
      custom/>. An old version is available in the elisp-client ftp
      directory at <URL:ftp://ftp.lysator.liu.se/pub/lyskom/elisp-
      client/>.
David Byers's avatar
David Byers committed
73

74
75
76
      If you have a version of Gnus installed that uses the old custom
      package, it's time to upgrade. The latest version of Gnus is
      available from <URL:http://www.gnus.org/>.
David Byers's avatar
David Byers committed
77

78
    * You must NOT HAVE macedit.el
79

80
81
      Make sure you do not have a file called macedit.el early in your
      load path. This file redefines a function that the client relies
82
      heavily on. The redefinition is buggy. You can recognize this
83
84
85
      problem if your Emacs says something like this: "Key sequence <
      m o u s e - 2 > uses invalid prefix characters" when you load or
      compile the elisp client.
86

87
88
89
90
91
92
93
    * w3 4.0 or later (optional)

      LysKOM can use w3 for displaying HTML. At the time of writing
      this, the latest version of W3 is 4.0. It is available from
      <URL:http://www.cs.indiana.edu/elisp/w3/w3.html> and included in
      many distributions of Emacs. If w3 is not installed, LysKOM will
      be unable to display HTML.
94

95
96
97
98
99
100
    * calc (optional)

      LysKOM uses calc to implement the "Compute" command. If you want
      to use it you need calc. The latest version of calc, as of
      writing this, is available at <URL:ftp://ftp.gnu.org/pub/gnu/
      calc/calc-2.02f.tar.gz>
101
102


Joel Rosdahl's avatar
Joel Rosdahl committed
103
2.  Installation
104

105
    You will have received the client in a compressed tar archive or
Joel Rosdahl's avatar
Joel Rosdahl committed
106
107
    in a zip archive. The archive contains all the files needed to
    build the client.
108

Joel Rosdahl's avatar
Joel Rosdahl committed
109
110
    You can either install manually (see section 2.1) or use the
    Makefile (section 2.2). However you install, there are a few
111
    additional steps that you may want to follow to facilitate using
Joel Rosdahl's avatar
Joel Rosdahl committed
112
    the client (section 2.3).
113

Joel Rosdahl's avatar
Joel Rosdahl committed
114
    The client is also available as a Debian package, which works for
115
116
117
    all supported Emacs/XEmacs flavors listed in section 1 above. You
    can also get the Debian package automatically via apt; see
    <URL:ftp://ftp.lysator.liu.se/pub/lyskom/elisp-client/debian/README>
Joel Rosdahl's avatar
Joel Rosdahl committed
118
119
120
    for more information. After installing the package, continue
    reading section 2.3.

Joel Rosdahl's avatar
Joel Rosdahl committed
121
122
123
    There are currently no prebuilt RPMs, but the source archive
    includes an RPM spec file that might be useful.

124

Joel Rosdahl's avatar
Joel Rosdahl committed
125
2.1 Manual installation
126
127
128
129

    This procedure should work on any system, including Windows.

    1. Compile the client with the command `emacs -batch -f
130
       batch-byte-compile lyskom-@@CLIENTVERSION@@.el' 
131

132
133
134
135
       You may see some warnings when you compile. Most of these can
       be ignored. When compilation is done you should have a new file
       named lyskom-@@CLIENTVERSION@@.elc located in the same directory as
       lyskom-@@CLIENTVERSION@@.el.
136

137
138
139
    2. Copy lyskom-@@CLIENTVERSION@@.elc to where you want to install
       the client and either rename the file lyskom.elc or create a
       symbolic link from lyskom.elc to lyskom-@@CLIENTVERSION@@.elc. 
David Byers's avatar
David Byers committed
140

141
142
143
       If possible you should place it in your site-lisp directory. 
       Check the value of load-path (C-h v l o a d - p a t h RET) to
       see possible locations.
David Byers's avatar
David Byers committed
144
145


Joel Rosdahl's avatar
Joel Rosdahl committed
146
2.2 Using the Makefile
David Byers's avatar
David Byers committed
147

148
149
150
151
    If you are on a Unix-like system (or anything that supports
    Makefiles) you can use make to install the client. You have to use
    the Makefile method if you want to change the list of available
    languages.
David Byers's avatar
David Byers committed
152
153


154
    1. Edit the Makefile in the distribution to reflect your
155
       environment. There are instructions in the Makefile.
David Byers's avatar
David Byers committed
156

157
158
159
       Optionally, use the configure script. It attempts to find
       suitable defaults for the settings in the Makefile. Simply run
       ./configure in the directory containing the client sources. 
David Byers's avatar
David Byers committed
160

161
162
       You may customize the output of the configure script with the
       following command-line arguments:
David Byers's avatar
David Byers committed
163

164
165
166
167
       --with-emacs=EMACS   Specify the name of the Emacs you want to
                            use (usually `emacs' or `xemacs'). The
                            script will attempt to locate an emacs
                            automatically.
David Byers's avatar
David Byers committed
168

169
170
171
172
173
174
       --with-lispdir=DIR   Specify where to install the client. You
                            will have to specify this if the script
                            fails to locate a suitable directory
                            automatically.

       --enable-language=LANG
Joel Rosdahl's avatar
Joel Rosdahl committed
175
176
                            Enable a language. Currently Swedish and
                            English are available. If you do not
177
178
179
180
                            explicitly enable any language, all will
                            be enabled.

       --with-default-language=LANG
Joel Rosdahl's avatar
Joel Rosdahl committed
181
182
                            Set the default language to LANG (Swedish
                            or English). If you do not specify a
183
184
185
186
187
                            default language the script will choose
                            one for you.

       The configure script is an experiment. It might work and it
       might not. If it doesn't, edit the Makefile by hand instead.
David Byers's avatar
David Byers committed
188

189
190
191
192
193
    2. Run `make envcheck' to make sure your Emacs environment is set
       up correctly. The environment check does not read your .emacs,
       so it will not find libraries that are not in the default load
       path. This means that it is possible that LysKOM will run just
       fine for you even if it complains.
David Byers's avatar
David Byers committed
194

195
196
197
    3. Edit the file lpath.el if you need to change the default load
       path for compiling (this should only happen if the custom
       package is not on your default load path).
David Byers's avatar
David Byers committed
198

David Byers's avatar
David Byers committed
199
200
201
    4. If you changed the list of languages, ran the configure script
       or are recompiling with a different Emacs version, run `make
       clean'.
David Byers's avatar
David Byers committed
202

203
204
205
206
207
    5. Run `make'. If your environment is set up correctly, LysKOM
       should be compiled. When compilation is finished, type `make
       install' to copy all the relevant files to the relevant places. 
       If you do `make install' without just doing `make', you'll
       bypass the environment check.
David Byers's avatar
David Byers committed
208
209


Joel Rosdahl's avatar
Joel Rosdahl committed
210
2.3 After installing
David Byers's avatar
David Byers committed
211

212
    After installing you can set Emacs to load LysKOM automatically.
David Byers's avatar
David Byers committed
213

214
215
216
217
218
219
    1. Set up autoloading by adding the following line to your .emacs
       or any other file that Emacs loads at startup (such as
       site-start.el or default.el):

            (autoload 'lyskom "lyskom" "Start LysKOM" t)

220
221
       (This is not needed if you are using the Debian package.)

222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
    2. If you have your own LysKOM server you may want to modify the
       variable kom-server-aliases. The best place to change it is in
       your site init file (default.el or site-start.el). For example,
       if you are running a server on kom.domain.org, you might want
       to say something like this in your init file:
   
            (defvar kom-server-aliases 
                    '(("kom.domain.org     . "DomainKOM")
                      ("kom.lysator.liu.se . "LysKOM")))
   
       The first server listed in kom-server-aliases will be the
       default server for new users.

    3. Restart Emacs. You should be able to use the command lyskom
       (M-x l y s k o m RET) to start the client. Enjoy!
David Byers's avatar
David Byers committed
237
238
239
240




Joel Rosdahl's avatar
Joel Rosdahl committed
241
3.  Reporting bugs
David Byers's avatar
David Byers committed
242

243
    Before reporting a bug, please check that it is not one of the
244
245
246
247
248
    known issues below. Please report bugs by posting them to the
    bugzilla at http://bugzilla.lysator.liu.se/. You can also e-mail
    bug reports to bug-lyskom@lysator.liu.se. 

    To evaluate your bug report we need the following information:
David Byers's avatar
David Byers committed
249
250
251
252
253
254

    o   The LysKOM version you are using. This is shown when you start
        LysKOM and is also contained in the variable
        lyskom-clientversion.

    o   The symptoms of the bug. Please be as detailed as possible.
255
        Please do not try to make conclusions. Just give us the facts.
David Byers's avatar
David Byers committed
256
257
258
259
260

    o   How you triggered the bug. If you know how to reproduce it,
        please tell us. We're pretty good at fixing bugs we can
        reproduce.

261
    o   How you started Emacs, what variables you have changed and
Joel Rosdahl's avatar
Joel Rosdahl committed
262
        which packages you have loaded. If possible, try to reproduce
263
264
        the bug with Emacs started with the -q command line switch.

265
266
267
268
269
    The command kom-bug-report may come in handy. It gives us a lot of
    information that you might not think of (such as what the internal
    data structures look like). If you post a bug report to our
    bugzilla, please make the result of kom-bug-report an attachment
    to your bug report.
270
271


Joel Rosdahl's avatar
Joel Rosdahl committed
272
4. Known issues
273

274
   Issue:  I see \201 before Swedish characters in the string showing
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
           what some other user is doing (e.g. L\201äser).

   Reason: The user is probably using an old version of the client in
           a new version of Emacs. You can confirm this by using the
           command kom-list-clients (Lista klienter, List clients).


   Issue:  I get the message "Key sequence < m o u s e - 2 > uses
           invalid prefix characters" when I load lyskom.elc.

   Reason: You have a file named macedit.el or macedit.elc installed.
           Remove this file.


   Issue:  I get the "Symbol's value as variable is void: \," when I
           try to run lyskom. 

   Reason: You have loaded the uncompiled client (e.g. lyskom.el or
           lyskom-@@CLIENTVERSION@@.el). Compile the client and load the compiled
           file (e.g. lyskom.elc or lyskom-@@CLIENTVERSION@@.elc).


297
   Issue:  Columns containing Swedish characters or characters in
298
299
300
           numeric representation are not aligned correctly.

   Reason: This happens in certain versions of Emacs when running
301
           without multi-byte character support and is due to bugs in
302
           Emacs. The only workaround is to either upgrade Emacs or
303
           enable multi-byte character support.
304
305
306
307
308


   Issue:  Swedish characters show up as blanks, question marks or
           numbers.

309
   Reason: If Swedish characters show up as blanks your font probably
310
311
312
313
314
315
316
317
318
           does not support them. If they show up as question marks or
           numbers your language environment does not support them.

           Make sure that your language environment is set correctly
           with set-language-environment. Just setting the environment
           variable LC_CTYPE to the proper value (iso_8859_1 is
           usually correct) should be enough.

           Do not use standard-display-european to fix this problem.