The LysKOM Emacs Lisp Client
-------------------------------------------
Release notes for version 0.46.1
LysKOM is a project in progress at the Lysator Academic Computing
Society at Link�ping University in Sweden. For information about
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
the Free Software Foundation; either version 2, or (at your
option) any later version.
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, Link�pings universitet, S-581 83 Link�ping, 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.
1. REQUIREMENTS
You need an Emacs. The client appears to work with the following
versions of Emacs:
* XEmacs version 20.4, 21.1 and 21.2.
* Gnu Emacs version 19.34 [1]
* Gnu Emacs version 20.5 and newer [2]
[1] You'll have to replace the included custom package, and if you
use Gnus, you may have to update that as well.
[2] It should be possible to run the client in Gnu Emacs 20.2 and
later, but you may experience some additional problems. Column
alignment is known to fail in version 20.2.
There are also some requirements on supplemental elisp packages:
* custom
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.
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.
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/>.
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/>.
* You must NOT HAVE macedit.el
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
heavily on. The redefinition is buggy. You can recognize this
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.
* 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.
* 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>
2. Installation
You will have received the client in a compressed tar archive or
in a zip archive. The archive contains all the files needed to
build the client.
You can either install manually (see section 2.1) or use the
Makefile (section 2.2). However you install, there are a few
additional steps that you may want to follow to facilitate using
the client (section 2.3).
The client is also available as a Debian package, which works for
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>
for more information. After installing the package, continue
reading section 2.3.
There are currently no prebuilt RPMs, but the source archive
includes an RPM spec file that might be useful.
2.1 Manual installation
This procedure should work on any system, including Windows.
1. Compile the client with the command `emacs -batch -f
batch-byte-compile lyskom-0.46.1.el'
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-0.46.1.elc located in the same directory as
lyskom-0.46.1.el.
2. Copy lyskom-0.46.1.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-0.46.1.elc.
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.
2.2 Using the Makefile
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.
1. Edit the Makefile in the distribution to reflect your
environment. There are instructions in the Makefile.
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.
You may customize the output of the configure script with the
following command-line arguments:
--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.
--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
Enable a language. Currently Swedish and
English are available. If you do not
explicitly enable any language, all will
be enabled.
--with-default-language=LANG
Set the default language to LANG (Swedish
or English). If you do not specify a
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.
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.
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).
4. If you changed the list of languages, ran the configure script
or are recompiling with a different Emacs version, run `make
clean'.
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.
2.3 After installing
After installing you can set Emacs to load LysKOM automatically.
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)
(This is not needed if you are using the Debian package.)
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!
3. Reporting bugs
Before reporting a bug, please check that it is not one of the
known issues below. 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.
Please do not try to make conclusions. Just give us the facts.
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.
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.
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).
4. Known issues
Issue: I see \201 before Swedish characters in the string showing
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-0.46.1.el). Compile the client and load the compiled
file (e.g. lyskom.elc or lyskom-0.46.1.elc).
Issue: Columns containing Swedish characters or characters in
numeric representation are not aligned correctly.
Reason: This happens in certain versions of Emacs when running
without multi-byte character support and is due to bugs in
Emacs. The only workaround is to either upgrade Emacs or
enable multi-byte character support.
Issue: Swedish characters show up as blanks, question marks or
numbers.
Reason: If Swedish characters show up as blanks your font probably
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.