kcd - Kriang's Change Directory
Version 5.0.3 (May 6, 2001)
Copyright (c) 1996,1997,1998,1999,2000 By Kriang Lerdsuwanakij
email: lerdsuwa@users.sourceforge.net
kcd home page: http://kcd.sourceforge.net

Important Notice
================
	This program is free software; you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation; either version 2 of the License, or
	(at your option) any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with this program; if not, write to the Free Software
	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

What Is kcd ?
=============
	kcd is a set of programs that help you navigate through directories
easily.  kcd is developed for Linux and hopefully it will work with any 
UNIX-clone operating system with the right libraries (libc, ncurses and zlib).

Minimum System Requirements
===========================
	- Linux or any UNIX-clone operating system.
	- gcc 2.8.0 and libstdc++ 2.8.0 (or newer) or egcs 1.0 (or newer).
	- ncurses 1.9.9e or better (required although buggy - incorrect 
	                            screen update)
	  or ncurses 4.2.
	- zlib 1.0.4 or better.

Documentations in the Distribution
==================================
	README		Program usage (This file)
	INSTALL		Installation procedure
	COPYING		GNU General Public Licence
	NEWS		Summary of changes from previous versions
	FILELIST	List of files and their functions
	BUGREPORT	Instruction for obtaining stack backtrace if
			kcd dumps core
	RPM		Instruction for generating kcd RPM packages
	TODO		To do list for future versions

kcd Basics
==========
	kcd works by consulting the directory tree file `~/.kcd.save.gz' for
the list of directories available.  This file is automatically created when
kcd is run for the first time.

	When you type the command

			kcd

it will display the saved entire directory tree and place the highlight bar 
on the current directory.  You can use arrow keys, Page Up, Page Down, Home 
and End keys to move the highlight bar to the desired directory.  Pressing 
Enter will exit kcd and jump the the selected directory.  If you choose to 
remain in the current directory, just press F10.

	If you know the name of directory you want to change to, for example,
`/usr/include',  you can type

			kcd include

To save some keystrokes, you can type only a part of `include' such as

			kcd incl

	If kcd found from that there are more than 4 directories contain the 
text `include' or `incl' (for the second example),  it will list all matched 
directories.  You can again use arrow keys, Page Up, Page Down, etc. to move
the highlight bar to `/usr/include' and press Enter.

	If there are less than or equal 4 matched directory, kcd will pick a
directory and jump.  Repeat the same kcd command, in this case `kcd include'
or `kcd incl', will go to the next matched one, and so on.   You can use 
shell's command history for this purpose.  For example, in several shells, 
pressing Up arrow key and Enter will repeat the previous command.  You may
change the number of matched directory threshold to any value other than 4
by modifying configuration file.  See the `Configuration File' section 
below.

	Besides using arrow keys, etc. to move the highlight bar,  you may
type the some text string to limit the highlight bar to move between items
containing the string.  The text string is shown at the bottom of the screen
inside [...].  To restore highlight bar behavior,  press Tab key.

	The list of directories used in all operations above is taken from 
`~/.kcd.save.gz'.  You may want to update it for directories added/removed.
To update the file,  type

			kcd -r

This will still use some information from the old file, especially directory 
time stamp, to speedup directory scanning.  If you found that simply using 
`kcd -r' is not accurate (see the next section for possible causes),  use 
`kcd -rf' instead.


Directory Tree Window
=====================

	The directory tree window appears when you type kcd without any
other parameter.   Initially kcd is in the `navigation' mode.  You can use 
arrow keys to move the highlight bar to any directory you want.  There is 
another mode called `find' mode which can be distinguish from navigation
mode by the string ` Find: ' displayed at the bottom of the screen.  Pressing 
arrow keys will move the highlight bar to the nearest directory containing the
search string inside the brackets ([...]).   Displayed at the last row on 
screen is the full path name of highlighted directory.

	Summary of Keys in Navigation Mode
	==================================

		Arrow keys, Page up, Page down, Home and End
			Move the highlight bar.

		Space bar or Enter
			Change to the highlighted directory and exit.

		F10 or ^C (Ctrl-C)
			Exit without changing directory.

		F8
			Repaint screen.

		F9 or ^R (Ctrl-R)
			Switch between status display:
			Destination directory <--> Key help.

		Center key on numeric keypad
			Center highlight bar on the middle of the screen.

		Characters from `a' to `z', from `A' to `Z' and from `0' to
		`9'
			Switch to find mode.

		`,' and `.'
			Panning screen left/right.  This works when the 
			directory tree is too wide to fit the screen.

	Summary of Keys in Find Mode
	============================

		Any characters, Ins, Del, Backspace, left arrow, right arrow
			Edit search string

		Up arrow or Page up, down arrow or Page down
			Go to the previous or next directory that match the
			search string

		Backspace or Del when the search string is empty
		or Tab
			Return to navigation mode

		Space bar or Enter
			If the highlighted directory is a normal directory:
				Change to that directory and exit.
			If the highlighted directory is a symbolic link:
				Move highlight bar to the linked directory.

		F10 or ^C (Ctrl-C)
			Exit without changing directory.

		F8 or ^R (Ctrl-R)
			Repaint screen.

	For terminals without function keys, you can press ^F+num where 
num is from 0 to 9 to get the same result.  ^F+1 (Press and hold `Ctrl' key, 
press and release `F', release `Ctrl', then press `1') is the same as F1.
Similarly ^F+2 to ^F+9 correspond to F2 to F9 respectively.  To emulate F10, 
use ^F+0.

	Legends for Displayed Directory
	===============================

	All accessible directories (except links) are shown as green (color 
console) or underlined (B&W console) and can be selected.

	/dev and /proc plus other directories specified in `SkipDir' setting 
(See `Configuration File' section below for more information) are shown with 
[skipped].   Subdirectories inside skipped directories are not displayed but 
you may able to access them using shell's `cd' command.

	Directories with [*] means that it is not present in the saved file.
They are added automatically to the screen when current directory is not in
the file.  As of the current version of kcd, added directory are not written 
to file.  To update your directory to disk, you have to rescan directory.

	Directories without execute permission are shown with [unreadable].
You cannot change to this directory.

	Directories without read permission but with execute permission are
also shown with [unreadable].  You can change to this directory, however,
you cannot read the content of the directory (i.e. using the `ls' command).

	Symbolic links are shown with -> and the destination directory.  
If the destination directory cannot be found (such as skipped or dangling
link), it is marked with [not found].  Note that in find mode, only strings 
before `->' are searched.


kcd Command Line Syntaxes
=========================

	kcd		Display directory tree and allow you to choose the 
			directory you would like to change to.

	kcd <TEXT>	Search and change to the directory containing the 
			TEXT string.  Parent directories are excluded from 
			string searching.

			For example, the command

				kcd lin

			will match /usr/src/linux-2.x.x,
			/usr/lib/gcc-lib/i486-linux, 
			/usr/doc/SlingShot, etc.  It does not match
			/usr/src/linux-2.x.x/fs because `lin' appear as the 
			parent directory of `fs'.

			If you want to change to directory that contains
			some special symbols (for example, `&', `|', etc.),
			enclose the TEXT string with single quote '...'.
			For example,

				kcd 'b&w'

			Avoid using spaces (very common in VFAT file system)
			in the TEXT string.  The shell may not correctly 
			parse the string,  resulting an error message.

	kcd --config	Display current configuration (excluding screen 
			attributes) obtained from /etc/kcd.conf, 
			/usr/etc/kcd.conf, /usr/local/etc/kcd.conf and 
			~/.kcd.conf.

	kcd --configattr	Display current screen attribute 
				configuration.

	kcd --features	Display availability of all features:

			xterm/rxvt resize	Yes if kcd can redraw itself
						if the size of xterm/rxvt 
						terminal changes.
			mouse support		Yes if kcd can response to
						mouse click.
			default scroll bar	Yes if scroll bar will be
						used.  It can be overrided
						by `ScrollBar' command in
						configuration file.

	kcd -h		Display help message.
or	kcd --help

	kcd --helpinst	Display help for shell alias/function installation.

	kcd -v		Display version number.
or	kcd --version

	kcd -r		Rescan directory tree using the default mode as 
			specified in configuration file.

	kcd -rf		Rescan directory using `full' scan mode.  kcd will 
			ignore all previously saved directory tree information 
			and start scanning from scratch.  By default, the 
			`smart' scan mode is used whenever possible to reduce 
			time needed for directory scanning.   

			The full scan mode is provided in case you change 
			configuration files - some command may not affect
			directory tree until you recan in full mode.

			Another possible problem is that some old file system 
			may not have the change time (which is updated when 
			directory permission is changed) so that kcd cannot 
			correctly update the directory tree.  (msdos file 
			system is an example, but fortunately we cannot 
			change their directory permission anyway.)

	kcd -rp <DIR>	Rescan part of directory tree beginning at DIR.

	kcd -rq		Rescan directory tree using the quiet mode,
			overriding default mode.  No current progress is 
			displayed.

	kcd -rQ		Rescan directory tree using the verbose mode
			(opposite of -rq), overriding default mode.  
			Current checked directory is displayed.

	Rescan options can be combined, i.e., `kcd -rf -rq' is the same as 
	`kcd -rfq'.

	Following parameters are useful when you type `kcd' and get a 
	command not found error:
		
		-ia, -ic, -if, -iau, -icu, -ifu, -ias, -ics, -ifs

	`kcd' is actually a shell function or shell alias so it must be setup 
	before you can type any kcd command.  You will have to use `kcdmain' 
	as the command name (since kcd command is not available yet).  The 
	syntax for shell function/alias installation is

			eval `kcdmain <OPTION>`		(Notice the quote)

	where OPTION is determined from the shell you use and the location of 
	kcd programs installed in your system.

	- If you install kcd in /usr/bin,  possible choices for OPTION are
	  `-ia', `-ic' and `-if'.

	- If you install kcd in ~/kcd-bin (user-specific installation),  
	  possible choices for OPTION are `-iau', `-icu' and `-ifu'.

	- If you install kcd elsewhere (usually /usr/local/bin),  possible 
	  choices for OPTION are `-ias', `-ics' and `-ifs'.  You have to 
	  specify the directory name containing kcd programs after OPTION.

	Example:	eval `kcdmain -ia`
	  or		eval `kcdmain -iau`
	  or		eval `kcdmain -ias /usr/local/bin`

	The quote used must be `...`.

	If you use C shell (for example tcsh),  you will have to use
	`-ic', `-icu' or `-ics'.

	For other shell,  kcd can be either installed as shell alias or 
	shell function.  Some shells support both alias and function,  some 
	only support one of them.  You have to try each of them to see which 
	one works.   `-ia', `-iau' and `-ias' are for shell alias 
	installation while `-if', `-ifu' and `-ifs' are for shell function.
		

Configuration File
==================
	kcd consults settings in `/etc/kcd.conf', `/usr/etc/kcd.conf', 
`/usr/local/etc/kcd.conf' and `~/.kcd.conf', in that order, each time 
the program executes if available.  Commands in the latter configuration
file will usually override the former one.  However, you have to use the 
ClearStartDir and ClearSkipDir commands in `~/.kcd.conf', for example, if 
you want to undo StartDir and SkipDir commands in `/etc/kcd.conf'.

	The syntax of each command is

		command_name = value

	All command names are case-insensitive.  All value NOT in double
quotes are also case-insensitive.  `~' and `~username', where username
is an account name,  are properly expanded to home directory.  Wildcards
`*', `?' and regular expressions are not supported.

	The symbol `#' serves as comment and all characters starting from `#'
till end of line are ignored.   The `#' inside double quotes, however, will
be treated as part of value passed to the command.

	Command Summary
	===============
		SkipDir		This tell kcd to skip scanning for directories 
				inside the specified directory name.   Multiple
				SkipDir commands are allowed.  /dev and /proc 
				are automatically excluded from the list of 
				directories to be scanned.  Directory name
				must be inside a pair of double quot ("...").

				Example:	SkipDir = "/cdrom"

		StartDir	This tell kcd to start scanning from the
				specified directories.   Multiple StartDir 
				commands are allowed.  In that case, kcd
				will generate output containing multiple
				directory trees.   Directory name must be 
				inside a pair of double quot ("...").
				If no StartDir is specified,  kcd starts
				scanning from the root directory.

				Example:	StartDir = "~"

		QuietFullScan	(allowed value = yes/no, default value = no)
				This command toggle progress report when
				kcd scan for directories using full scan
				mode.  Only the last QuietFullScan command 
				are effective.  This option can be overrided 
				by `-rq' or `-rQ'.

				Example:	QuietFullScan = yes

		QuietSmartScan	(allowed value = yes/no, default value = no)
				This command is similar to QuietFullScan but
				is intended for smart scan mode.  This 
				option can be overrided by `-rq' or `-rQ'.

		QuietPartialScan (allowed value = yes/no, default value = no)
				This command is similar to QuietFullScan but
				is intended for `-rp' option.  This 
				option can be overrided by `-rq' or `-rQ'.

		SortTree	(allowed value = yes/no, default value = yes)
				This command cause kcd to sort the directory 
				tree.  If you change the SortTree value from
				yes to no,  directory tree must be rescanned 
				using full scan mode to make this command to 
				properly restore the original order.

		GraphicChar	(allowed value = yes/no, default value = yes)
				Choose whether special line graphic and 
				arrow characters are used.  If `no' is 
				given, simple characters such as `+', `|', 
				`>', etc. is used instead.

		ScrollBar	(allowed value = yes/no, 
				 default value = yes for ncurses version
						 >= 4.2)
				Choose whether scroll bars will be displayed.

		CaseSensitiveSort	(allowed value = yes/no, 
					 default value = no)
				Choose between case-sensitive or
				case-insensive sort.  SortTree must not be set
				to no in order for this to be effective.

		ClearSkipDir	(allowed value = all/"directory")
				Do not skip the specified directory previously 
				set as SkipDir.  If `all' is used, ClearSkipDir 
				discards all directory.  `/dev' and `/proc' 
				are not affected by this command.

				Example:	ClearSkipDir = all
						ClearSkipDir = "/dosc"

		ClearStartDir	(allowed value = all/"directory")
				Do not use the specified directory previously 
				set as StartDir.  If `all' is used, 
				ClearStartDir discards all StartDir directory.

		SpaceSelect	(allowed value = yes/no, default value = yes)
				Setting this to no, when in find mode,
				pressing spacebar will not select the
				highlighted directory but proceed looking
				for the directory containing the space.

		ShowListThreshold	(allowed value: any numbers >= 0,
					 default value = 4)
				If the number of matched directories given
				in the command line is less than or equal 
				this number, kcd will jump immediately.  
				Otherwise, the list of all matches are
				shown.

		GlobDot		(allowed value = yes/no, default value = no)
				Select whether wildcard can match the
				leading `.' in the path name.  It effects
				only commands following it.

		GlobPath	(allowed value = yes/no, default value = no)
				Select whether wildcard can match the `/'
				in the path name.  It effects only commands 
				following it.

		DefaultBackground	(allowed value = Black/Red/Green/
					 Yellow/Blue/Magenta/Cyan/White,
					 default value = Black)
					Select background color for the 
					directory tree window.

	Screen Attribute Command Summary
	================================

		Screen attribute command for color display has the following
	syntax:
		
	   <ITEM>ColorAttr = [normal | <ATTR> ...] <FG_COLOR> on <BG_COLOR>

	while for black and white display is:

			<ITEM>BWAttr = [normal | <ATTR>]

	Available values for <ITEM>:

		Normal			Majority of main window area, 
					including line drawing characters,
					inaccessible directories,
					[*], [skipped] and [unreadable].
		Dir			Directory names.
		HighlightDir		Highlighted directory names.
		SymLink			Symbolic links.
		HighlightSymLink	Highlighted symbolic links.
		Title			Program name, text entered in find 
					mode.
		Status			Status bar.
		More			Small area on rightmost column of
					display area that `+' is displayed
					when window content is too wide to 
					fit on the screen.
		ScrollArrow		Arrows on the scroll bars.
		ScrollBlock		The moving block on the scroll bars.
		ScrollBar		Background of the scroll bars.

	Available values for <ATTR>:

		Standout	Underline	Reverse		Blink
		Dim		Bold

	Available values for <FG_COLOR> and <BG_COLOR>:

		Black		Red		Green		Yellow
		Blue		Magenta		Cyan		White

	<BG_COLOR> can also be `Default' which means that the background 
	color of the directory tree window is used here.

	Example:
		# Change both foreground and background
		NormalColorAttr = cyan on black
		DirColorAttr = bold red on blue
		SymLinkColorAttr = blue on white
		
		# Change only foreground
		NormalColorAttr = cyan on default

		# For black and white display
		NormalBWAttr = normal
		DirBWAttr = underline
		TitleBWAttr = bold reverse

	Note:	Whether a particular combination of attributes and/or colors
		works is terminal dependent.


	Wildcards and Quoting Rules
	===========================

		The following symbols have special meanings inside double
	quotes values (such as in SkipDir command):

			\  '  "  `  *  ?  [  ]

	Currently the commands SkipDir, ClearSkipDir, ClearStartDir can 
	accept `*', `?', `[' and `]' and interpret them as shell wildcard
	pattern.  Those wildcards normally does not match `/' and leading
	`.' but the behavior can be overrided using GlobPath and GlobDot
	commands respectively.  Here is the list of wildcard pattern that
	kcd recognizes:

		*		Match any characters

		?		Match single character

		[set]		Match single character in the set

				Example: "lib[cm]" matches libc and libm.

		[!set]		Match single character not in the set

				Example: "lib[!m]" matches libc but not libm.

		[^set]		Same as [!set] but only available if in some
				cases.  If glibc is your C library (true on
				Linux), it works when the environment
				variable POSIXLY_CORRECT is not set.

		[from-to]	Match single character within the range

				Example: "x[a-m]m" matches xbm but not xpm.

		[:class:]	Match single character in the class where
				class can be one of

				alpha	upper	lower	digit	alnum
				xdigit	space	print	punct	graph
				cntrl	blank

	Example:	SkipDir = "~/.*"
			SkipDir = "~/*/CVS"

		Note that the matching rules depends on the C library in 
	your system.  The above rules apply when you have POSIX.2 conforming 
	library.  System with older libraries may not accept some of the 
	rules.

		If you want these symbols inside double quotes to actually
	refer to the characters.  You have to add an extra `\' in front of 
	them.  Note that here, `*' and `?' refer to characters inside 
	directory name,  not wildcards.

	For example:

		SkipDir = "~/\`Cool\?\'"

	is used to skip the directory named

			`Cool?'		(the enclosing quotes and the 
					 question mark are parts
					 of the directory name)

	inside your home directory.  (You may not know that can created this
	kind of weird directory name!)

		``' and `'' are not part of wildcards and are reserved for 
	future use.

	Sample Configuration File
	=========================
		Following is for directory tree starting from root directory:

		# Sample configuration file for kcd
		SkipDir = "/cdrom"	# Ignore cdrom mounting point
		SkipDir = "/dosc"	# MSDOS C: partition


		Following is for directory tree starting from home directory:

		# Another sample configuration file for kcd
		StartDir = "~"		# Start from home directory
		SkipDir = "~/.terminfo"	# No scan inside .terminfo
		QuietFullScan = yes
		QuietSmartScan = yes


Common Error Messages
=====================
	- Shell message reporting that it cannot find a particular file or
	  directory (the actual message depends on the shell used).
	  For example, bash displays
			`bash: <dirname>: No such file or directory'

	  Cause:	kcd attempts to change to a directory that no longer
			exists.
	  Solution:	Rescan directory.

	- `kcd: cannot find a link containing the string ...'
	  Cause:	kcd cannot find any directory matching specified
			string given in the command line.  This may due to:

	  		- There may be some typos in directory name
			  given.
		Solution: Retype the correct name.

			- The desired directory is created after the last
			  directory scan.
		Solution: Rescan directory.

			- kcd has been configured to skip it.
		Solution: Change directory manually by the `cd' command or
			  modify the configuration file (See the Configuration
			  File section).

	- `kcd: your ncurses library is bad.  Refer to kcd README file
	   for solution'
	  Cause:	ncurses library (libncurses.a or libncurses.so.X.X.X
			in /usr/lib) and header file (/usr/include/curses.h)
			do not match.

		or	The library is built based using a different 
			configuration, compiler or library that is
			incompatible with the current installed ones.

		or	The library is build not to support C++ applications.

	  Solution:	Recompile kcd.

	- `kcd: internal error: bad directory `xxx' in ExpandDirectory(...)'
	  Cause:	The values of `StartDir' or `SkipDir' inside the
			configuration file (such as `~/.kcd.conf') must be 
			absolute directories, i.e., they must start with 
			either `/', `~' or `~user' where user is a valid user 
			name.
	  Solution:	Fix errors in configuration file.


Bugs Report and Feedback
========================
	For the program home page, latest news, message forums, mailing 
lists, bug reports, check out http://kcd.sourceforge.net

	Program author can be contacted at lerdsuwa@users.sourceforge.net


Future Improvements
===================
	See the `TODO' file.
