README

   1
   2 Ion
   3 ===
   4
   5 Copyright (c) Tuomo Valkonen 1999-2007.
   6
   7 tuomov at iki.fi
   8
   9 <http://iki.fi/tuomov/ion/>
  10
  11
  12 Building and installing
  13 -----------------------
  14
  15 1. Make sure you have the following tools and libraries installed:
  16
  17     * GNU make
  18     * Lua 5.1 (see <http://www.lua.org/>).
  19
  20 2. Edit `system.mk` to suit your system. Most GNU/Linux users should
  21    need very few changes.
  22
  23 3. If you want to build some extra modules now or do not want to build
  24    some of the standard modules, edit `modulelist.mk`.
  25
  26 4. Run `make`. Note that `make` here refers to GNU make which is usually
  27    named `gmake` on systems with some other implementation of make as
  28    default.
  29
  30 5. Run `make install`, as root if you set `$PREFIX` in `system.mk` to a
  31    directory that requires those privileges.
  32
  33    YOU SHOULD NOT SKIP THIS STEP unless you know what you are doing. Ion
  34    will refuse to start if it can not find all the necessary uncorrupt
  35    configuration files either in `$PREFIX/etc/ion3/` or in `~/.ion3/`.
  36
  37 6. How to best set up `startx` or whatever to start Ion instead of your
  38    current window manager depends on your system's setup. A good guess
  39    is creating or modifying an executable shell script `.xsession` in your
  40    home directory to start Ion. This should usually (but not always) work
  41    if you're using some X display/login manager. If `~/.xsession` does not
  42    help and you're not using a display manager, modifying `~/.xinitrc` or
  43    creating one based on your system's `xinitrc` (wherever that may be;
  44    use `locate`) may be what you need to do. Note that unlike `.xsession`,
  45    a `.xinitrc` should usually do much more setup than simply start a few
  46    programs of your choice.
  47
  48 Please see the file `RELNOTES` for additional release-specific installation
  49 and configuration notes.
  50
  51
  52 Some optional installation steps
  53 --------------------------------
  54
  55 1. The F5 and F6 keys expect to find the program `run-mailcap` to select
  56    a program to view a file based on its guessed MIME type. Unless you are
  57    using Debian, most likely you don't have it, but any other similar
  58    program (or just plain old text editor) will do as well -- just modify the
  59    bindings in `cfg_ioncore.lua`. Of course, if you don't want to use the
  60    feature at this time or never, you may simply skip this step. If you want
  61    to use `run-mailcap`, it can be found from the following address, as a
  62    source tarball as well:
  63
  64        <http://www.debian.org/Packages/unstable/net/mime-support.html>
  65
  66 2. Ion supports caching known man-pages in a file for faster man-page
  67    completion in the F1 man page query. To enable this feature, you must
  68    periodically run a cronjob to build this list. To create a system-wide
  69    man page cache, run `crontab -e` (might vary depending on platform) as
  70    root and enter a line such as follows:
  71
  72         15 05 * * * $SHAREDIR/ion-completeman -mksyscache
  73
  74    Replace `$SHAREDIR` with the setting from `system.mk` (or `system-ac.mk`
  75    if you used autoconf). This example runs daily at 05:15, but you may
  76    modify the  run times to your needs; see the crontab manual.
  77
  78    If you can't or do not want to build a system-wide man page cache, run
  79    `crontab -e` as your normal user and replace `-mksyscache` with
  80    `-mkusercache` above. The cache file will be `~/.ion3/mancache`.
  81
  82    It may also be useful to run `ion-completeman` with the suitable
  83    `-mk*cache` argument once manually to build the initial cache.
  84
  85    If the `MANPATH` environment variable is not set on your system and it
  86     does not have the `manpath` command (or it does not print anything
  87    sensible), you may also want to set the `ION_MANPATH` environment
  88    variable to the list of paths where the system stores manual pages.
  89
  90
  91 Configuration
  92 -------------
  93
  94 For help on modifying Ion's configuration files, PLEASE READ THE DOCUMENT
  95 "Configuring and extending Ion3 with Lua" available from the Ion web page,
  96 listed at the top of this file.
  97
  98
  99 Questions, comments, problems?
 100 ------------------------------
 101
 102 If the available documentation does not answer your question, please
 103 post it to the mailing list. Details can be found on the Ion web page
 104 listed at the top of this file.
 105
 106
 107 Credits
 108 -------
 109
 110 Ion was written by Tuomo Valkonen.
 111
 112 The dock module was written by Tom Payne and Per Olofsson.
 113
 114 `utils/ion-completefile/ion-completefile.c` is based on editline, (c)
 115 1992 Simmule Turner and Rich Salz. See the file for details.
 116
 117 The code that `de/fontset.c` is based on was apparently originally
 118 written by Tomohiro Kubota; see
 119 <http://www.debian.org/doc/manuals/intro-i18n/ch-examples.en.html#s13.4.5>.
 120
 121 Various (minor) patches have been contributed by other individuals
 122 unlisted  here. See the mailing list archives and the darcs source
 123 repository history at <http://iki.fi/tuomov/repos/>. For translators
 124 see the individual `.po` files in `po/`.
 125
 126 See `libtu/README` for code by others integrated into libtu.