
Ion
===

Copyright (c) Tuomo Valkonen 1999-2007.

tuomov at iki.fi

<http://iki.fi/tuomov/ion/>
          

Building and installing
-----------------------

1. Make sure you have the following tools and libraries installed:

    * GNU make
    * Lua 5.1 (see <http://www.lua.org/>). 

2. a) Edit `system.mk` to suit your system. Most GNU/Linux users should
      need very few changes.

   b) Alternatively, go to the directory `build/ac`, run `autoreconf`
      and then `./configure`. Switch back to the top lvel directory 
      afterwards. See `build/ac/README.autoconf` for details on parameters, 
      especially if you are using the Debian Lua packages. If you try 
      this method and it fails for some reason, please make sure 
      `build/ac/system-ac.mk` does not exist before falling back to
      alternative a). Also in such a case, find someone else to complain
      to: I (tuomov) will have nothing to do with autoconf.

3. If you want to build some extra modules now or do not want to build
   some of the standard modules, edit `modulelist.mk`.
   
4. 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.
   
5. 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/`.

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

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

2. 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` (or `system-ac.mk`
   if you used autoconf). 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 autoconf script written by Tom Payne for the most part.

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

`share/ion-completefile/ion-completefile.c` is based on editline, (c)
1992 Simmule Turner and Rich Salz. See the file for details.

The code that `de/fontset.c` is based on was apparently originally written 
by Tomohiro Kubota; see
<http://www.debian.org/doc/manuals/intro-i18n/ch-examples.en.html#s13.4.5>.

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