The LysKOM Emacs Lisp Client ------------------------------------------- Release notes for version @@CLIENTVERSION@@ LysKOM is a project in progress at the Lysator Academic Computing Society at Linköping University in Sweden. For information about Lysator, see . For more information on LysKOM, see . The latest version of the Emacs Lisp client for LysKOM is available from . 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 . An old version is available in the elisp-client ftp directory at . 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 . * 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 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 3. Installation You will have received the client in a compressed tar archive or in a zip file. The archive contains all the files needed to build the client and a pre-built client. The client is also available as an RPM and a Debian package. These assume that you are using Gnu Emacs 20.5 or later. You can either install manually (see section 3.1) or using the Makefile (section 3.3). However you install, there are a few additional steps that you may want to follow to facilitate using the client (section 3.3). 3.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-file lyskom-@@CLIENTVERSION@@.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-@@CLIENTVERSION@@.elc located in the same directory as lyskom-@@CLIENTVERSION@@.el. 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. 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. 3.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. 3.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) 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! 4. 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.) 5. 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-@@CLIENTVERSION@@.el). Compile the client and load the compiled file (e.g. lyskom.elc or lyskom-@@CLIENTVERSION@@.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.