Readme for ion-3

tuomov at iki.fi

Building and installing

Make sure you have the following tools and libraries installed (along with, of course, standard X11 and libc stuff).
- GNU make http://www.gnu.org/software/make/
- Lua 5.1 http://www.lua.org/
- gettext http://www.gnu.org/software/gettext/
Edit system.mk to suit your system.
If you want to build some extra modules now or do not want to build some of the standard modules, edit modulelist.mk.
Run make. Note that make here refers to GNU make which is usually named gmake on systems with some other implementation of make as default.
Run make install, as root if you set $PREFIX in system.mk to a directory that requires those privileges.

YOU SHOULD NOT SKIP THIS STEP unless you know what you are doing. Ion will refuse to start if it can not find all the necessary uncorrupt configuration files either in $PREFIX/etc/ion3/ or in ~/.ion3/.

How to best set up startx or whatever to start Ion instead of your current window manager depends on your system's setup. A good guess is creating or modifying an executable shell script .xsession in your home directory to start Ion. This should usually (but not always) work if you're using some X display/login manager. If ~/.xsession does not help and you're not using a display manager, modifying ~/.xinitrc or creating one based on your system's xinitrc (wherever that may be; use locate) may be what you need to do. Note that unlike .xsession, a .xinitrc should usually do much more setup than simply start a few programs of your choice.

Please see the file RELNOTES for additional release-specific installation and configuration notes.

Some optional installation steps

The F5 and F6 keys expect to find the program run-mailcap to select a program to view a file based on its guessed MIME type. Unless you are using Debian, most likely you don't have it, but any other similar program (or just plain old text editor) will do as well -- just modify the bindings in cfg_ioncore.lua. Of course, if you don't want to use the feature at this time or never, you may simply skip this step. If you want to use run-mailcap, it can be found from the following address, as a source tarball as well:

http://www.debian.org/Packages/unstable/net/mime-support.html
Ion supports caching known man-pages in a file for faster man-page completion in the F1 man page query. To enable this feature, you must periodically run a cronjob to build this list. To create a system-wide man page cache, run crontab -e (might vary depending on platform) as root and enter a line such as follows:
```
15 05 * * * $SHAREDIR/ion-completeman -mksyscache
```

Replace $SHAREDIR with the setting from system.mk. This example runs daily at 05:15, but you may modify the run times to your needs; see the crontab manual.

If you can't or do not want to build a system-wide man page cache, run crontab -e as your normal user and replace -mksyscache with -mkusercache above. The cache file will be ~/.ion3/mancache.

It may also be useful to run ion-completeman with the suitable -mk*cache argument once manually to build the initial cache.

If the MANPATH environment variable is not set on your system and it does not have the manpath command (or it does not print anything sensible), you may also want to set the ION_MANPATH environment variable to the list of paths where the system stores manual pages.

Configuration

For help on modifying Ion's configuration files, PLEASE READ THE DOCUMENT "Configuring and extending Ion3 with Lua" available from the Ion web page, listed at the top of this file.

Questions, comments, problems?

If the available documentation does not answer your question, please post it to the mailing list. Details can be found on the Ion web page listed at the top of this file.

Credits

Ion was written by Tuomo Valkonen.

The dock module was written by Tom Payne and Per Olofsson.

The code that de/fontset.c is based on seems to have been originally written by Tomohiro Kubota, but see the file for details.

Various (minor) patches have been contributed by other individuals unlisted here. See the mailing list archives and the darcs source repository history at http://iki.fi/tuomov/repos/. For translators see the individual .po files in po/.

See libtu/README for code by others integrated into libtu.