kcd - Kriang's Change Directory
Version 7.15.0 (Feb 18, 2009)
Copyright (c) 1996,1997-9,2000-4,2005 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 helps you navigate through directories easily in console or
terminal command line.  A shell alias or function is setup to provide the 
functionality.  You can use it to jump to the desired directory through
command line or full screen navigation.

	It works with shells bash, tcsh, pdksh, zsh, and ash.  Although 
kcd is developed for Linux, it should also work with any UNIX operating 
system with the right libraries (libc, ncurses and zlib).  To compile kcd 
yourself, you also need a decent C++ compiler.

Minimum System Requirements
===========================
	- Linux or any UNIX-clone operating system.
	- gcc 3.0 and libstdc++ 3.0 (or newer).
	- ncurses 4.2 (or newer).
	- zlib 1.0.4 (or newer).

Documentations in the Distribution
==================================
	README		Program usage (This file)
	INSTALL		Installation procedure
	COPYING		GNU General Public License
	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
	UNICODE		Instruction for building kcd with Unicode support
	TODO		To do list for future versions

kcd Basics
==========
	kcd works by consulting the directory tree file for the list of 
directories available.  By default the file is named `~/.kcd.save.kcd.gz'
but may change according to the kcd configuration file.  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 or Ctrl-C.

	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.  Alternately, if you
have to jump to, say, `/usr/include' that always appears as matched directory
number 2 in the list.  You can force kcd to jump to that directory
immediately without showing a list by specifying this number in the command
line as

			kcd incl 2

	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 kcd configuration file.  See the `Configuration File' section 
below.

	On the other hand, if kcd cannot find the requested directory,
fuzzy finding mode is used.  In fuzzy mode, directories that approximately
matches the given text is listed.  By default, fuzzy mode will find 10
closest matches.  This too can be changed by the configuration file.

	Special symbols `/' and `//' are available to fine tune directory
matching.  For example, the command line

			kcd usr/bin

will find any directory containing `bin' such that its immediate parent
directory contains `usr'.  This matches `/usr/bin', and `/usr/sbin'.
On the other hand, the command line

			kcd usr//bin

this will find any directory containing `bin' such that any of its parent
directories contain `usr'.  This also matches `/usr/local/bin', and
`/usr/local/lib/mozilla/bin' for example.  Multiple such symbols may
appear in the command line such as

			kcd usr//include//std

	You may create bookmarks via option `-ba' to help locate frequently
accessed directories.  When kcd searches for directories matching a given
text and finds that at least one is bookmarked, then all non-bookmarked 
directories are ignored.  So bookmarked directories are always chosen over
non-bookmarked ones.  You can override this behavior by supplying kcd with 
`-B' option before the text such as

			kcd -B incl

You can also list all bookmarked directory using `-b' option.

	While in full screen mode, 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 added or removed 
directories.  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 "kcd Command Line Syntaxes" section for
possible causes), use `kcd -rf' instead.


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

	The directory tree window appears when you type kcd without any
other parameter.  Following are the meaning of different colors and symbols
used to display a directory in the tree.

	Green (color console) or underlined (B&W console)
		Accessible normal directories.  You can move the highlight
		bar and press Enter to exit kcd and jump to this directory.

	Yellow (color console) or underlined bold (B&W console)
		Accessible symbolic link.  If the link points inside the
		directory tree, selecting this directory will move to
		the linked directory while remaining in the directory tree
		window.  On the other hand, if it points outside, selecting
		it will exit kcd and jump to the target directory.

	Gray (color console) or normal (B&W console)
		Inaccessible directory.  You don't have permission to change
		into this directory.

	[skipped]
		Directory skipped from scanning so that its subdirectories
		are not displayed.  /dev is always skipped since its
		content is really entry points for kernel drivers and this
		takes very long time to scan.  /proc is also skipped due to
		continuously changing content.  You can configure other
		directories to skip using `SkipDir' setting.  See 
		`Configuration File' section below for more information.

	[*]
		Directory is not currently 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.

	[unreadable]
		You don't have either read permission to display the
		content or execute permission to change to this directory.

	[outside tree]
		This is a symbolic link that points outside saved directory
		tree.


Key Binding
===========

	When kcd is first in full screen display, it stays in the
`navigation' mode where you can use arrow keys to move the highlight bar
around to any directory you want.  There is another mode called `find' mode
which highlight bar is restricted to directories that match the string
appearing at the bottom of the screen.  You can distinguish find mode by
the string ` Find: ' displayed at the bottom of the screen.  The matching
search string is displayed inside the brackets ([...]).

	Note that strings both before and after `->' of the symbolic links
are searched in find mode.

	Displayed at the last row on screen is the full path name of
highlighted directory.  Online help also utilizes this area.  You can
switch between different displays by repeatly pressing F9 key.

	By default, the key binding used is the one that has been used since
kcd version 1.0.  It is based on arrow keys, PageUp, PageDown, Home, End and
function keys.  This is also referred to as kcd mode.  Beside this mode,
Vi and Emacs key binding modes are provided.  You may change the key binding
via the KeyBinding configuration command.  However, changing the action of
individual keys is not available in the current version.

	kcd Key Binding
	===============

		Note that in kcd key binding mode, you can press Ctrl-F
	follow by a number key fro 0 to 9 to get the same results as the
	function keys.  This is handy for terminals without function key
	support.  The number 1 to 9 correspond to F1 to F9 respectively.  
	To emulate F10, use number 0.  As an example, typing Ctrl-F+1
	(Press and hold Ctrl key, press and release F, release Ctrl, then
	press and release 1) is the same as F1.

		Navigation Mode
		===============

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

		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 Ctrl-C
			Exit without changing directory.

		F8
			Repaint screen.

		F9 or 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.

		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 Ctrl-C
			Exit without changing directory.

		F8 or Ctrl-R
			Repaint screen.

	Vi Key Binding
	==============

		In this configuration, key binding in navigation mode acts
	acts like cursor movement while find mode acts like text searching.
	All arrow keys, PageUp, PageDown, function keys, and Enter retains
	the same meaning as kcd key binding.  Following is the list of keys
	available.

		0, ^		First directory of line
		$		Last directory of line
		h, b, B		Previous directory
		l, w, W		Next directory
		k, -		Up
		j, +, _		Down
		Ctrl-B		Previous page
		Ctrl-F		Next page
		Ctrl-U, Ctrl-Y	Scroll up
		Ctrl-D, Ctrl-E	Scroll down
		gg		First page
		G		Last page
		/		Search forward
		?		Search backward
		Ctrl-L		Refresh screen
		q, ZQ, Ctrl-C	Quit

		For most commands, a number prefix to indicate
		the repeat count, such as 5 Ctrl-B representing
		previous 5 pages, is supported.

	Emacs Key Binding
	=================

		In this configuration, key binding in navigation mode acts
	acts like cursor movement while find mode acts like text searching.
	All arrow keys, PageUp, PageDown, function keys, and Enter retains
	the same meaning as kcd key binding.  Following is the list of keys
	available.  The notation used below is the one used in Emacs.  For
	example, C-b means Ctrl-B while M-b usually means Alt-B.

		C-a		First directory of line
		C-e		Last directory of line
		C-b, M-b	Previous directory
		C-f, M-f	Next directory
		C-p		Up
		C-n		Down
		M-v		Previous page
		C-v		Next page
		C-s		Search forward
		C-r		Search backward
		C-c		Quit


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

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

	kcd [-B] <TEXT> [<NUMBER>]
			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.  Some shell may not correctly 
			parse the string, resulting an error message.

			NUMBER is the matched directory number used in case
			of multiple matches.

			If the option `-B' is specified, all directories are
			searched, not just the bookmarked ones.

	kcd -b [<TEXT>]	Display bookmarks matching TEXT, or all bookmark if
			TEXT is not supplied.

	kcd -ba [<DIR> [...]]
			Bookmark specified directories.  If none is specified,
			the current directory is used.

	kcd -br [<DIR> [...]]
			Remove bookmark from specified directories.  If none 
			is specified, the current directory is used.

	kcd -M		Don't scan directories given by MountDir.

	kcd -t [<DIR>]	Display partial directory tree beginning with DIR.
			If DIR is not specified, the current directory is
			used.

	kcd -tr [<DIR>]	Like -t but rescan directory tree before display.

	kcd -T		Display full directory tree.

	kcd --config	Display current configuration (excluding screen 
			attributes) obtained from SYSCONFDIR/kcd.conf and
			~/.kcd.conf.  SYSCONFDIR is the directory given to
			--sysconfdir option during configure, which usually is
			/etc, /usr/etc or /usr/local/etc.

	kcd --configattr	Display current screen attribute 
				configuration.

	kcd --profiles	Display the list of configuration profiles available.

	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 overridden
						by `ScrollBar' command in
						configuration file.
			UTF-8 support		Yes if kcd is compiled with
						Unicode UTF-8 support.  A
						Unicode enabled terminal is
						required for proper function.
			d_type speedup		Yes if a faster way to obtain
						information whether a
						directory entry is a file
						or directory is available.

	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 change may not take effect
			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, -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 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 -ias /usr/local/bin`

	The quote used must be `...`.

	If you use C shell (for example tcsh),  you will have to use
	`-ic' 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' and `-ias' are for shell alias installation while
	`-if' and `-ifs' are for shell function.

	Other shell function or shell alias may be introduced with the 
	above options.  Details can be found in `Profile' subsection in
	`Configuration File'.  You can force a particular profile to be
	chosen by using '-p' option followed by profile name.  This must be
	the first option present in the command line.
		

Configuration File
==================
	kcd consults settings in `SYSCONFDIR/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 the global
`SYSCONFDIR/kcd.conf'.

	The syntax of each command is

		command_name = value

	All command names are case-insensitive.  Values, however, depends on
whether the command requests a double quoted value or not.  Only values NOT in
double quotes are treated as case-insensitive.

	There are 2 possible ways to specify value for double quoted string: 
glob, and regular expression.

	Glob uses characters like `?' and `*' as wildcards.  It is placed 
within a pair of double quotes like "/usr/lib/lib*".

	Regular expression uses extended regular expression format and is 
placed within double quotes prefixed by either `R' or `r' such as
r"/usr/lib/lib[a-z]-.*".  kcd automatically adds a `^' and `$' at the
beginning and the end of string, respectively.

	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.

	The file `~/.kcd.conf' may also contain profile of the form

		[profile_name]

This allows kcd to behave differently depending on the configuration profile
used.  See the `Profile' subsection below for more explanation.


	Command Summary
	===============

		SkipDir		(allowed value = "directory"/r"directory",
				 with optional GlobDot and GlobPath override
				 allowed)
				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 quote ("...").

				You may override the current GlobDot and
				GlobPath settings for this SkipDir command.
				Just specify each setting separated by comma
				after the directory name.

				Example:	SkipDir = "/cdrom"
						SkipDir = "~/*rc", GlobDot=yes

		StartDir	(allowed value = "directory")
				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 quote ("...").
				If no StartDir is specified,  kcd starts
				scanning from the root directory.
				Wild cards are not supported by StartDir.

				Example:	StartDir = "~"

		MountDir	(allowed value = "directory",
				 with optional actions All/Tree/Skip)
				This tell kcd to handle the specified
				directory according to the action given:

				All		Always scan regardless if
						search string is provided in
						the command line.
				Tree		Scan only when search string
						is not supplied.
				Skip		Always skip scanning.

				If the action is not provided, the default
				`Skip' action is used.

				Multiple actions, separated by commas can
				be specified.  However this is intended for
				features to be introduced later.

				Wild cards are not supported by MountDir.

				Example:	MountDir = "/mnt/floppy", Skip
						MountDir = "/mnt/usb", All

				Note: Directories given by MountDir should
				not overlap.  The following does not work

						MountDir = "/mnt/mount_c", All
						MountDir = "/mnt/mount_c/temp", Skip

				Use the following instead

						MountDir = "/mnt/mount_c", All
						SkipDir = "/mnt/mount_c/temp"

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

		MouseScrollRate	(allowed value: any number >= 0,
				 default value = 2)
				Select scrolling rate when mouse button is
				held down.  Unit is in 0.1 sec.  Set to 0 
				disable this feature.

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

		ClearSkipDir	(allowed value = all/"directory"/r"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"/r"directory")
				Do not use the specified directory previously 
				set as StartDir.  If `all' is used, 
				ClearStartDir discards all StartDir directory.

		ClearMountDir	(allowed value = all/"directory"/r"directory")
				Do not use the specified directory previously 
				set as MountDir.  If `all' is used, 
				ClearMountDir discards all MountDir 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.

		ShowNewDir	(allowed value = yes/no/multi,
				 default value = multi
				Choose whether the new directory will be
				displayed when kcd decides to jump without
				showing list of matches.  `Multi' means
				display only when there are multiple matches.

		FuzzySize	(allowed value: any numbers >= 0,
					 default value = 10)
				If there is no matched directories given
				in the command line, kcd will search for
				directories that provide the closest match.
				The number of matches is given by this
				configuration.

		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.

		DefaultTree	(allowed value = quoted string)
				This specifies the default subtree displayed
				in directory tree mode.  It can be overriden
				by `-t' or `-T' options.

		KeyBinding	(allowed value = default/kcd/vi/emacs,
				 default value = default)
				Select a particular key binding.  See section
				Directory Tree Window for key details.

	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):

			\  '  "  `  ~

	and

			*  ?  [  ]

	for glob, or

			^  .  [  ]  $  (  )  |  *  +  ?  {  }

	for regular expression.  Currently the commands SkipDir,
	ClearSkipDir, ClearStartDir, ClearMountDir can accept glob or
	regular expression.

		`~' and `~username', where username is an account name, 
	are properly expanded to home directory when it appears at the
	beginning of the string.  The special symbols ``' and `'' are 
	reserved for future use.

		Control characters can be entered using \xHH quoting where
	HH is the hexadecimal value of the character.


	Glob Special Characters
	=======================

		Shell wildcards normally does not match `/' and the
	leading `.' but the behavior can be overridden 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 you can create
	directory with this kind of weird name!)


	Regular Expression Special Characters
	=====================================

		For information check Section 7 of `regex' man pages, i.e.,
	type `man 7 regex' in command line.


	Sample Configuration Files
	==========================

		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


	Profile
	=======

		This feature allows kcd to behave differently depending on
	the invoked profile name.  The following is an example of
	configuration file containing multiple profiles.

		[kcd]
		StartDir = "/"
		[hcd]
		StartDir = "~"

		With the example above, two shell functions/aliases are
	introduced, `kcd' and `hcd'.  If you type `kcd' in the command line,
	the entire system is searched and displayed.  But if you want to
	restrict to only inside home directory, you can use `hcd' command
	instead.  More profiles can be introduced using in similar manner.
	There is no limit on the number of profiles.  The only restriction
	is the name of the profile.  The profile name must be a valid C or
	C++ identifier, i.e., contains only alphanumeric characters or
	underscore and must not begin with a number.

		There are two special profiles, `*' and `kcd'.  The `*'
	profile is the default profile and is used for commands when no
	profile name is specified.  The `kcd' profile is always created
	regardless if it actually appears in the configuration file.
	An ordinary profile (including `kcd'), when declared, will be
	initialized from the current configuration of `*'.  Afterwards,
	any changes to `*' does not affect the previously initialized one.
	Here is an example.

		ShowListThreshold = 3	# No profile specified yet,
					# store in [*]
		[kcd]			# Copy configuration from [*]
					# So the ShowListThreshold
					# command also applies to [kcd]
		StartDir = "/"
		[*]
		SkipDir = "~/.*"	# Add SkipDir command to [*]
					# Does not affect [kcd]
		[hcd]			# Inherit ShowListThreshold
					# and SkipDir from [*]
		StartDir = "~"
		[ucd]			# Inherit ShowListThreshold
					# and SkipDir from [*]
		StartDir = "/home"

		Note: Profile may not work on some shells such as ash.
	bash and tcsh work fine.


Using kcd with suid/sudo
========================
	kcd, beginning with version 5.2.0, allow you to set environment
variables KCD_DIRTREE, KCD_BOOKMARK, KCD_TEMP and KCD_CONFIG to control 
files used by kcd for saved directory tree (default is ~/.kcd.save.*.gz), 
temporary file storing the destination directory (default is ~/.kcd.newdir) 
and user's configuration file (default is ~/.kcd.conf).  These environment
variables are disabled in kcdscr script by default.

	When running as root, whether they are set or not, KCD_DIRTREE, 
KCD_BOOKMARK, and KCD_TEMP can be exploited to overwrite files while 
KCD_CONFIG can be used to read protected files such as /etc/shadow.  
You should set all of them explicitly.  To do this, you have to create a 
new script similar to kcdscr.  KCD_DIRTREE, KCD_BOOKMARK and KCD_TEMP 
should point inside directory which ordinary user does not have permission.  
For example, you may create a directory /var/kcd which only root can 
read/write to the directory and set KCD_DIRTREE to 
/var/kcd/dirtree.$SUDO_USER, KCD_BOOKMARK to /var/kcd/bookmark.$SUDO_USER, 
and KCD_TEMP to /var/kcd/temp.$SUDO_USER.  Currently there are tests to 
make sure that the file KCD_CONFIG refers to is not a symbolic link, is a 
regular file and has link count = 1.

	Note that you should not suid kcdmain or kcdsrc directly.  Do suid 
the script you create instead.


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.


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.
