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