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



David Byers's avatar
David Byers committed
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
---------------------------------------------------------------------------

                     The LysKOM Emacs Lisp Client

---------------------------------------------------------------------------




    LysKOM is a project in progress at the Lysator Academic Computing
    Society at Linköping University in Sweden. For information abuot
    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
23
24
    the Free Software Foundation; either version 2, or (at your
    option) any later version.
David Byers's avatar
David Byers committed
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

    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,
    c/o ISY, Linkoping University, S-581 83 Linkoping, SWEDEN, or the
    Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
    USA.

    Please mail bug reports to bug-lyskom@lysator.liu.se. 
    Please mail change requests to kom@lysator.liu.se


41

42
1.  What do I need
David Byers's avatar
David Byers committed
43

44
45
46
    You need an Emacs. The client appears to work with the following
    versions of Emacs:

47
    * XEmacs version 20.4, 21.1 and 21.2.
48
    * Gnu Emacs version 19.34 [1]
49
    * Gnu Emacs version 20.5 and newer [2]
50
51
52
53

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

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

58
59
60
    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
61

62
    The version that is bundled with recent versions of XEmacs, with
63
    Gnu Emacs 20, with recent versions of Gnus and w3 is the one you 
64
    need. 
David Byers's avatar
David Byers committed
65

66
    Custom is not longer distributed as a separate package, but it may
67
68
69
    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
70

71
72
73
    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
74

75
76
77
78
    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
    heavly on. The redefinition is buggy. You can recognize this
    problem if your Emacs says something like this: "Key sequence < m
79
    o u s e - 2 > uses invalid prefix characters".
80

David Byers's avatar
David Byers committed
81
82


83
84
85
2.  What should I have

    LysKOM can use w3 for displaying HTML and calc for performing
86
87
    calculations. Neither package is required, but since they are
    useful in their own right you might as well install them anyway.
88
89
90
91
92

    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>
    
    The latest version of calc, when writing this, is available at
93
94
95
96
97
98
99
100
101
102
103
104
    <URL:ftp://ftp.gnu.org/pub/gnu/calc/calc-2.02f.tar.gz>


3.  Installation

    There are two ways to install the client. You can assemble,
    compile and install it from a tar file, or from a single emacs
    lisp file. 

    If you are using a Unix system (or something sufficiently
    similar), try installing from the tar file. If you are using
    Microsoft Windows, install using the single file.
105

David Byers's avatar
David Byers committed
106

107
3.1 Installation from the tar file
David Byers's avatar
David Byers committed
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

    Edit the Makefile in the distribution to reflect your environment. 
    You can change the following variables:

        EMACS should be set to the command used to start Emacs. Usually 
        this will be either emacs or xemacs.

        LISPDIR is the directory in which the compiled and uncompiled
        client will go. This will normally be set to your site-lisp
        directory.

        INFODIR is where the info files will go, once we've written
        them. You should set this variable on the off chance that we
        distributed some documentation with the code.

        LANGUAGES is a list of languages to compile in. As of version
        0.45 there are only two translations of LysKOM. The Makefile
        states which values are legal. Just list all the languages you
        want, separated by whitespace. The first language you specify
        will be the default language.

    Type `make envcheck' to make sure your Emacs environment is set up
130
131
132
    correctly. The environment check is somewhat pessimistic. It is
    entirely possible that LysKOM will run just fine even if it
    complains.
David Byers's avatar
David Byers committed
133

134
135
    If you need to add anything to the default load path for
    compiling, edit the file lpath.el.
David Byers's avatar
David Byers committed
136
137
138

    Type `make'. If your environment is set up correctly, LysKOM
    should be compiled. When compilation is finished, type `make
David Byers's avatar
David Byers committed
139
140
141
    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, which is probably not a good idea.
David Byers's avatar
David Byers committed
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

    Start Emacs, load lyskom.elc and type M-x lyskom RET, and you
    should be in business.

    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. 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.



161
3.2.  Installation from a single .el file
David Byers's avatar
David Byers committed
162

David Byers's avatar
David Byers committed
163
164
165
166
167
168
169
170
171
172
173
174
175
176
    If you have received the client as a single file named
    lyskom-0.46.el or something similar, first rename the file to
    lyskom.el. Make sure that the custom package is in the default
    load path (they are if you're using XEmacs 19.15 or later, or Gnu
    Emacs 20.1 or later.) To compile, simply issue the following
    commend:

        emacs -batch -f batch-byte-compile lyskom.el

    This will create a file named lyskom.elc which should be placed
    somewhere where Emacs will find it.



177
4.  Reporting Bugs
David Byers's avatar
David Byers committed
178
179
180
181
182
183
184
185
186

    Please report bugs to bug-lyskom@lysator.liu.se. Please give us the 
    following information (at least):

    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.
187
        Please do not try to make conclusions. Just give us the facts.
David Byers's avatar
David Byers committed
188
189
190
191
192

    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.

193
194
195
196
    o   How you started Emacs, what variables you have changed and
        which packages you have loaded. If possible, try to  reproduce
        the bug with Emacs started with the -q command line switch.

197
198
199
    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.)