Installation Guide for kcd
==========================

System requirement for kcd:
===========================
You have to install these software before process with kcd installation
procedure.

- ncurses 1.9.9e or better.  ncurses 4.2 or better is recommended.
  Scroll bar in kcd is disabled unless ncurses 4.2 or better is used.
- zlib 1.0.4 or better.
- gcc and g++ version 2.8 or newer together with libstdc++.  egcs
  versions also work.

If you don't have root access to install ncurses or zlib, just build the 
static library and put header files in ../include and libraries in
../lib relative to kcd source files.  For example if kcd source directory 
is ~/tmp/kcd-x.y.z, put then in ~/tmp/include and ~/tmp/lib.
kcd will automatically recognize the files and use them instead of the
global ones.

If you are installing ncurses to shared location, you must use the 
option `--with-shared' in ncurses `configure' command.


kcd Installation Procedure:
===========================

Decide whether you want to install kcd for every user in your system
(which will be refered to as `system-wide' installation) or only for
your account only (will be refered to as `user-specific'
installation).   The latter is useful if you do not have root access.


kcd Installation Procedure (System-wide):
=========================================

By default kcd will be installed in
 - `/usr/bin'		if former kcd installation was in /usr/bin
 - `/usr/local/bin'	otherwise

Type `./configure' (do not type the enclosing quotes) if you want 
to install kcd in the default directory shown above.  To override
the destination directory to `PREFIX/bin', add the `--prefix=PREFIX'
option to configure.  For example, if you want to install to
`/usr/bin', type `./configure --prefix=/usr'.

There are several options that can be fine tuned for other directories.

 --sysconfdir=DIR	Directory for shared configuration file.
			(default = /etc.  When PREFIX begins with /opt/
			and FHS is used, the default is /etc/PREFIX)
			Here FHS refers to FHS version 2.1.
 --mandir=DIR		Base directory for man pages.  (default = PREFIX/man
			for non-FHS systems.  It can be PREFIX/share/en_US/man
			or PREFIX/share/en/man or PREFIX/share/man for FHS.)
			Man pages will be installed in MANDIR/man1.
 --datadir=DIR		Base directory for translated messages.
			(default = PREFIX/share)  Message files will be 
			installed in directories inside DATADIR/locale.

Other configure options:

 --enable-wide-chars	Include wide char support.  This requires a special
			version of ncurses.  Read the file UNICODE for more
			information about this support.
 --enable-debug-memory	Compile some memory debugging code into kcd.  It may
			be turned on by default on some versions of kcd that
			is known to contain memory-related bugs to aid
			debugging.  It's unlikely that you'll need this
			option.
 --disable-nls		Do not use message translation.
 --disable-fhs		Do not install using directories introduced in FHS.
 --with-static-ncurses	Link with static version of ncurses library.  It may
			be useful if you built a new version of ncurses
			library but forget to create the shared one.
 --with-included-gettext	Use included gettext functions instead of
				ones already installed in your system.
				Useful on platform without glibc.
 --with-catgets		Use catgets message system.  It's unlikely that 
			you'll need this option.

Create kcdmain executable by typing `make'.  If you have any error during 
compiling the program, refer to the Troubleshooting Section at the end of 
this file.

If you do not want to keep debugging information, type `make strip'.

Type `make install'.  make will automatically install the required 
executable files to PREFIX/bin.

If the directory `SYSCONFDIR/profile.d' exists, copy `kcd.sh.init' to 
`SYSCONFDIR/profile.d/kcd.sh' and copy `kcd.csh.init' to 
`SYSCONFDIR/profile.d/kcd.csh'.
Otherwise `kcd.sh.init' and `kcd.csh.init' are copied to `SYSCONFDIR',
the following lines are added to `SYSCONFDIR/profile'

		# For kcd
		. /etc/kcd.sh.init

and the following lines are added to `SYSCONFDIR/csh.login'.

		# For kcd
		source /etc/kcd.csh.init

Note:  If you mess with SYSCONFDIR during configure, you will have to
modify those files in /etc to make kcd works.

Note:  In case you use bash, you might want to add the above lines for
`SYSCONFDIR/profile' to `/etc/bashrc' or `~/.bashrc'.  This makes sure 
that kcd works with any bash invoked.  The kcd-inst program automatically
do this when run.


kcd Installation Procedure (User-specific):
===========================================

Type `./configure' (do not type the enclosing quotes).  kcd will only 
install in the directory `kcd-bin' inside your home directory.

Options --enable-wide-chars, --enable-debug-memory, --disable-nls, 
--with-included-gettext and --with-catgets described in the previous
section may be used.

Create kcdmain executable by typing `make'.  If you have any error during 
compiling the program, refer to the Troubleshooting Section at the end of 
this file.

If you do not want to keep debugging information, type `make strip'.

Type `make installuser'.  The script will copy the executable files
to `~/kcd-bin'.  The following lines are added to `.bashrc' (and
to `.zshrc' or `.profile' if your login shell is zsh or ash, respectively.)

		# For kcd
		. (your home dir. name)/kcd-bin/kcd.sh.userinit

and the following lines are added to `.cshrc'.

		# For kcd
		source (your home dir. name)/kcd-bin/kcd.csh.userinit

Note:  The script added was tested under bash, tcsh, zsh, pdksh and ash.  
If you use other shells, you may have to modify to make it works.  You
should also leave the string `For kcd' inside the comment generated by 
`make installuser' intact.  The string is used as a marker so that any 
future kcd installation will not touch these files again.


Creating kcd Configuration Files
================================

kcd uses its default parameters when no configuration files are found.
You can find more information about configuration commands in the README
file.  The following instructions are provided as an example to jump
start kcd.

If you want to skip some directories from being scanned and displayed, 
create `SYSCONF/kcd.conf' (that effects all users) or a private `.kcd.conf'
in your home directory (that effects only your account).   Following is a 
sample content of such file:

	SkipDir = "/mnt/cdrom"
	SkipDir = "/mnt/c"

Here subdirectories inside `/mnt/cdrom' and `/mnt/c' are not scanned and
stored.  Note that `/dev' and `/proc' are always treated as special
directories and are automatically skipped even when it is not specified
in `/etc/kcd.conf' or `.kcd.conf'.


Running kcd for the First Time
==============================

Logout and login again.  Type `kcd' at your prompt.  You should see a 
graphical display of directory tree.   kcd may have to scan all directories 
(except the ones specified in the configuration) in your system.   Press 
F10 to exit.

If you want to rescan directory to reflect changes at any time later, just 
type `kcd -r' (normal mode) or `kcd -rq' (for quiet mode).


Troubleshooting
===============

- Compilation fails

	One common problem is that ncurses shared library is old compare to 
static library.  That because you forgot use the option `--with-shared' in 
ncurses `configure' command.  Follow the steps below to force kcd to be 
linked to static library.

	1 In kcd directory, type `rm config.cache'.

	2 If `libncurses.a' is in either `/usr/local/lib' or `/usr/lib', 
	  restart Step 3 with the option `--with-static-ncurses'
	  added to configure command.  Note that configure looks for
	  libncurses.a in /usr/local/lib before /usr/lib.

	  Otherwise restart Step 3 with the option
	  `--with-static-ncurses' and specify the directory name that 
	  contains libncurses.a as an argument.  For example, when your 
	  ncurses static library is in /mydir/lib, type

		./configure --with-static-ncurses=/mydir/lib

- During login, it cannot find one of the libraries used by kcd

	If you are using csh or tcsh, look for one of the following files:

		/etc/kcd.csh.init, /etc/profile.d/kcd.csh
		or ~/kcd-bin/kcd.csh.userinit

	and modify this file to set the environment variable 
	LD_LIBRARY_PATH to the directory containing the libraries.

	If you are using other shells, look for one of the following files
	instead:

		/etc/kcd.sh.init, /etc/profile.d/kcd.sh
		or ~/kcd-bin/kcd.sh.userinit

- When running kcd, it cannot find terminfo database or open the terminal

	If you are using csh or tcsh, look for one of the following files:

		/etc/kcd.csh.init, /etc/profile.d/kcd.csh
		or ~/kcd-bin/kcd.csh.userinit

	and modify this file to set the environment variable 
	TERMINFO to the directory containing the terminfo database.

	If you are using other shells, look for one of the following files
	instead:

		/etc/kcd.sh.init, /etc/profile.d/kcd.sh
		or ~/kcd-bin/kcd.sh.userinit
