///////////////////////////////////////////////////////////////////////////////////////////////////////////
Title:
	Color Directory Lister 
		Copywright 1994 by John D. Hendrickson (see license)
///////////////////////////////////////////////////////////////////////////////////////////////////////////
Sections in this document:
	Summary
	Before Using
	Requirements: negligible
	Installation Instructions
	The Basics:  building helpful lists, input sources
	Tips
	Advanced
	Tricks
	Common Command Reference
	Advanced Command Reference
	Limits
	Return Values
	Important: Disclaimer and License
	Contact Info
///////////////////////////////////////////////////////////////////////////////////////////////////////////
Summary:

Color Directory Lister.  DOS 3.0-WIN95 (long filename supported).  99.9%
compatible with DIR (incl. set dircmd).  Automates better readability with
choosable formats.  Takes advantage of screens > 25x80.  Has four coloring
schemes.  Is 'Quick' interactive.  Can be used to find files and folders, to
go to found folders.  Searches also by date/time/size.  Uses config file to
store preferences.  Sorts up to 7 million files!  Supports redirection both
ways.  Has many options.  Public Domain.

	 Used as an extended file listing utility at the MS-DOS prompt.
		Collects, aggregates, and presents file information upon request.
		Automates better readability.
		'Quick' user interactive.
		Provides a wide variety of options.
		Can be used to find files and folders, to go to found folders, and more.
		Is a 'drop in' for dir and is mostly compatible.
///////////////////////////////////////////////////////////////////////////////////////////////////////////
Before Using:  Things you should know.
	When using most listing programs (even Explorer), remember the following:
		It is assumed that your data is backed up.
		It is assumed you know that a directory lister is not truely informative; for example:
			 A file is shown as directories due to a single bit; which does not indicate that
				the given file is a directory that works properly.
			 File information may be incorrect.
///////////////////////////////////////////////////////////////////////////////////////////////////////////
Requirements:
	Initial requirements are insignificant.  Runtime requirments are variable.
///////////////////////////////////////////////////////////////////////////////////////////////////////////
Installation Instructions:
	 See your MS-DOS/WIN/WIN95 manual, if necessary, to do the following.
	 Place Cdir in a file folder that is in the search path (see the 'set' and 'copy' commands).
	 Run in the MS-DOS prompt just as most MS-DOS commands.
		Cdir accepts user input on commandline including the generic help command '/?'.
		Cdir uses the DIRCMD MS-DOS environment variable, if present.
	 The files of Cdir: If the following files are damaged or missing, re-install Cdir.
			Cdir.exe is the executable.
			Cdir.rc is the re-configureation file; a user editable file.
			Cdir.txt is the manual.
///////////////////////////////////////////////////////////////////////////////////////////////////////////
The Basics:  building helpful lists, input sources
	The file system is also known as a system data base.
	A directory lister is a convenient way to get a quick look at whats before you whenever 
		you've forgotten where you are and what you are looking for.  It's quick, simple, and unobtrusive.  
		Its also used by Gurus who save the lists for processing (and who also do quite a bit of forgetting).
	You may wish to have a special list; for this Cdir needs your input.
		For example, you wish files sorted by date the of last change, instead of by name.
		For example, you may wish Cdir to search all of your drives for some files (not just a directory).
	The input consists of options and or search strings.  You type these with the keyboard.  Where you
		type them provides how they are used (once, allways, etc...).
			 All options must be preceeded by the front-slash '/' for identification as options.
				-> Try 'Cdir /?' to get a list of options.  See the MS-DOS manual.  See 'cdir.rc'.  See below.
			 One search string is either a name to find or a folder location to look in.
	Cdir takes input from the following sources, if present, in the following order.
		 the MS-DOS environment variable DIRCMD
			see your MS-DOS manual to use this
		 'cdir.rc' (a re-configureation file; 'dir' doesn't use this)
			This file is taken as input if present when cdir starts.  It is easily edited with any text (.txt) editor.
			In the .rc file, appropriate commands are listed and preceded by a comment explaining.
			them quickly.  Commands can then be made active or inactive by simply inserting 
			or deleting a single pre-fix (comment) character '#'.
		 The MS-DOS commandline; 'c:\>cdir ...'
			Cdir takes input from the commandline in the same manner as MS-DOS's 'dir'.
		 redirected input ('dir' doesn't do this)
			See your MS-DOS manual to use this.  Use also Cdir's /stdin switch.
		 interaction
			The 'quick' user interaction may have all the answers and features you need.
			The last line printed on a page lists commands.  Press the	letter on the keyboard 
			corresponding to the letter capitalized in the command 	you wish to try.
				Note that you must not have turned pausing off to use; 'pause' is the time provided for user interaction.
///////////////////////////////////////////////////////////////////////////////////////////////////////////			
Tips:
	- Preferencial option are in quick help 'cdir /?'
	- WIN95
		All files have THREE date/time pairs, being their times of:
			'creation', 'last access', and  'last write'.
	- The commandline works much like the 'find dialog box': except that
				'cdir [file list] [folder list] [options]'
			all goes in on the current command line at the MS-DOS prompt.					
			(Use spaces, no commas, [things] have no particular order.)
			[file list] goes in a files box, [folder list] goes in a folder box (automatically).
			Use 'cdir /find filename(s) /in foldername(s)' to specify which box if necessary.
		- As usual, quote long filenames; and in filenames:
			'*' means 'guess this part of the file name'.
			'?' means 'guess only this character'.
			., .., ..., etc: are symbols that refer to this and previous directory, respectively.
	- /find and /goto are much faster when /in is used, since /in tells cdir 
		what path(s) to search and so what path(s) not to search.
///////////////////////////////////////////////////////////////////////////////////////////////////////////
Advanced: 					
	- a file size entry corresponds to bytes and matches equality; sign indicating above or below
	- If the cdir.rc reconfigureation file is present and in the same folder as 
		cdir.exe it is taken automatically (note that DIRCMD environment variable is allways taken).
	- Cdir uses any text mode up to 256x256 (writing to the screen).
	- The use of 'smartdrive' can speed up cdir significantly (exponentially).
		(under TRUE DOS, not WIN95 DOS).
	- Cdir has MANY advanced options, however, most are on
		by default; cdir has many options to turn off so that cdir will be 
		useable in many strange environments (to shut off the nice stuff).
	- Cdir allows Ctrl-C to terminate it immediately (OK).  Cdir has documented batch return codes.
	- Cdir accepts piping and re-direction under some situations.
	- See the 'cdir.rc' file for advanced configuration
	- see 'cdir.man'
///////////////////////////////////////////////////////////////////////////////////////////////////////////
Tricks:
	- Cdir accepts a list of places to search, and a list of what to search for, allways taken separately
		'dir\file' is just a short form of this (just like entering the same in the Win95 Find 'named' box)
	- [b]ack one the quick menu works while recursing to go back directories			
	- The general quick fix for text screen anomalies:
		/r standard text output
	- The general quick fix for formatting/exiting anomalies:
		/-vrf and or /-p try these cuplrits first.
		/b turns off most options, add options that work from there.
	- Cdir doesn't do scroll bars correctly with 'more ':
		cdir will if it's /y option is set to 22 (screen text lines)
	- Some video card/mode/bios combinations will see anomalies with block scrolling:
		/scr is a general fix.  Uses DOS to scroll normally, which should be 'nice'.
		I had one combo which the BIOS actually had the wrong count of rows
			on the screen! 	(here, specify /y (number of rows)).
	- Cdir uses the DOS palete of 16 colors which can be remapped with
		utilities like ni.exe which is shipped with one of the Norton Utilities packs.
///////////////////////////////////////////////////////////////////////////////////////////////////////////		
Common Command Reference: (see also: Advanced Command Reference)
(in no particular order; but there's some nice ones!)

	-----------------------------------------------
	- toggle prefixed switches (ie. /+l, /-scroll)
	-----------------------------------------------
	"l"				
		use lower case letter for 8_3 filenames
	"b"				
		setup dos bare listing format
	"col"			
		view lists in columns (vertical reading format)
	"page"			
		paginated output
	"p"				
		allow pause
	"prompt"
		prompt for commands when paused
	"all_drives"	
		check drive letters c-z recursively
	"s"				
		sub directories checked
	"r"		 		
		redirected (file or screen) output
		(regular dos text output)
	"medium"		
		size in megabytes
	"large"			
		size in kilobytes
	"huge"		
		size in bytes
	"comma"			
		use commas in numbers
	"hvol"			
		volume label in header
	"hdirec"		
		directory label in header
	"hfiles"     	
		file info in header
	"ffiles"     	
		file info in footer
	"headings"	
		labels for fields in header
	"sec"			
		seconds displayed in date of files
		note that seconds are in increments of 2
	"csep"		
		color by change in extention
		csep works defaults to 1 column output
		It can also operate under /csep /-w /-vrf
	"ccol"		
		color by column
	"crow"		
		color by row
	-----------------------------------------------
	- numberic arguement expected (ie. /w:4 or /w4)
	-----------------------------------------------
	"w" 	
		width - number of columns to make
		default is automatic
	"y"			
		height of screen (and page size)
	"x"			
		width of screen (and output)
	"foreground"	
		foreground color
	"background"	
		background color
	-----------------------------------------------
	- catenated string arguement (ie: /o:gen /size:-1000 /date:
	-----------------------------------------------
	"o" 
		sort order
		see "help" from commandline for choices
	"f"			
		fields to display
		see "help" from commandline for choices
	"a"			
		displays file with specified attribute
		see "help" from commandline for choices
	"date"		
		specify file date to find
		[wac][+-][01-01-98] (+- are inclusive)
		[01-01-98] (defaults: lastWrite, equal to)
		time and date searches are independant
		Up to 3 times and 3 dates can be uniquely specified per search 
			w,a,c are specified separately
			time/date are specified separately
	"time"		
		specify file time to find
		[wac][+-][01:01][p][a] (+- are inclusive)
		[wac][+-][01:01:01][p][a] (see /+sec)
		[01:01] (defaults: lastWrite, equal to, no adjustment to hours)
		time and date searches are independant
		Up to 3 times and 3 dates can be uniquely specified per search 
			w,a,c are specified separately
			time/date are specified separately
	"size"		
		specify file size to find
		only one size can be specified in a search
		[+-][number of bytes] (+- are inclusive)
		1000 (defaults: equal to)
	-----------------------------------------------
	- 'no' (or many) arg or arg in ARGV
	-----------------------------------------------
	"h" 
	"help"		
	"?"			
		quick help
	"find"
		assert to cdir that you're trying to find a file
		output formatting for searching vs listing
	"goto"
		specify directory to change to
		see also "sTay" at pause prompt
	"in"
		specify a list of folders to look in
	"files"		
		specify a list of files to find
	"ctab"
		use color by table entries (see .rc file)
	-----------------------------------------------	
///////////////////////////////////////////////////////////////////////////////////////////////////////////		
Advanced Command Reference:

	-----------------------------------------------
	- toggle prefixed switches (ie. /+l, /-scroll)
	-----------------------------------------------
	"p!"			
		force a final pause when done
	"scroll"		
		force bios scroll by line (not by page)
	"prompt"
		prompt for commands when paused
	"list"			
		an internal mode
		output formatting for searching vs listing 
	"sep_comma"		
		separate file information using commas
	"small"			
		size in terabytes
	"compact"		
		size in gigabytes
	"dotdir"		
		show "." and ".." directories toggle
	"path"			
		includes path in the filename field
	"ansi"			
		uses ansi notation for output (for colors)
	"stdin"			
		takes standard input as a source of program arguements
	"raw"			
		an internal mode
		sprintf for -uF, -up, -um
	"white"
		separate file info using a space
	"quiet"    		
		an internal mode
		output formatting for searching vs listing
	"sec"
		seconds displayed in date of files
		note that seconds are in increments of 2
	"mark_exe"		
		executable files postfixed with star
		"raw" is required
	"mark_path"		
		"raw" directories postfixed with front slash
	"keep_background" 
		whether to keep background color in certain conditions
	"v"				
		verbose mode; for compatibility with dir only
	"c"
		compressed ratio mode; for compatibility with dir only
		cdir isn't currently able to get the compressed ratio
	"vga_probe"	
		whether to test for vga
	"resource_min" 
		use minimum resources 
		no list length limitations, minimal memory used
		can't sort, pre-format, etc 
		storage of arguements isn't counted
		storage for recursion isn't counted
	"disk" 
		use only file memory
	"memory" 
		use only on-board memory
	"one_list"	
		put all finds in one list - use path if necessary
	-----------------------------------------------
	- numberic arguement expected (ie. /w:4 or /w4)
	-----------------------------------------------
	"i!"			
		advanced
		sort base
	"j!"			
		advanced
		sort option
	-----------------------------------------------
	- catenated string arguement (ie: /o:gen /size:-1000 /date:
	-----------------------------------------------
	"u"			
		unix like option (ie. "/ut or /ula")
		some work! but no longer supported...
		-u1 ............. unix's -1  makes one column output on terminal
		-ua ............. unix's -a  lists all files, including dot directories
		-ub ............. unix's -b  displays non-printable characters in octal: \ooo
		                  This option is NOT supported.
		-uC ............. unix's -C  sorted column output, going down columns
		-ud ............. unix's -d  give info. on a directory instead of its contents
		-uF ............. unix's -F  append a / to directories and a * to executables
		-ul ............. unix's -l  long format for DOS displays attrib, size, time and name
		-um ............. unix's -m  list is separated by commas, uses screen width
		-up ............. unix's -p  append a / to directories
		-uq ............. unix's -q  displays non-printable characters as ?
		                  This option is NOT supported.
		-uR ............. unix's -R  lists subdirectories recursively
		-ur ............. unix's -r  sort in reverse order
		-us ............. unix's -r  for DOS displays number of clusters

		-ut ............. unix's -t  sort by time
		-ux ............. unix's -x  sorted column output, left to right format
	-----------------------------------------------
	- 'no' (or many) arg or arg in ARGV
	-----------------------------------------------
	"ctab"
		use color by table entries (see .rc file)
	-----------------------------------------------
///////////////////////////////////////////////////////////////////////////////////////////////////////////
LIMITS:
	- Certainly, logic error exists.  Cdir has ALLOT of logic.
	- totals, for recursion, are added for ea. directory viewed
		- [b]ack from the Quick menu can completely alter recursion and is not accounted for
	- Video: DOS [and ANSI] or BIOS [and color]
		- some BIOS modes and video cards cause unpleasing output
	- Memory: uses memory space first then file space by default (uses up to 4G DOS file)
		- about 7,329,295 files can be in a single list
	- Command line: old DOS limit commandline, redirection uses up to 4G file, L->R ordered w/ ENV Lmost
	- This version specifically for the DOS and Win95 environments.
		- Not for generic use with NT.
			- The Win95 OS services do not service UNC or Unicode internally.
			- Cdir will be misleading and incomplete under non FAT systems (NT...).
				- If Cdir works properly on your NT volume, it is for a particular volume or situation.
	- DOS Disk Space Free: will only be correct in the approx. range [0, 4G]
		- if you have more than about 4 gig. free, your reading will be incorrect.
		- this does NOT effect tot. space used by files
	- numberical input is +Z and or Z notation
	- let file max FM = unsigned long/586 ~= 7.3M
		- grow-by is ~75k; small
		- no entries (incl. the following) have been tested to this limit
	- max files in one single directory (one list; several lists possible)
		- FM
	- input (environment+commandline+cdir.rc+redirected) AFTER separation
		- FM
	- recurse directories
		- FM
	- sorting
		- FM
		- selecting same element twice will cause it to be sorted twice
	- formatted print width
		- ~ 65534
		- selecting same element twice will cause it to be printed twice
		- not tested to limit
	- file sizes: 64bit WIN95, 32bit TRUE DOS
	- file sizes: 20 char precision (64bit is 15 chars)
	- files & dirs totals: 32bit
	- disk free: 32bit DOS
	- It's not perfect; it's Robust.
///////////////////////////////////////////////////////////////////////////////////////////////////////////
- Return Values:
	0 no failures encountered
	1 search not successful, one or more specs not found
	2 low mem - can't complete task - quit
		CDIR quits so that user does not get a "seemingly sorted" 
		list and act upon it: user or batch must SPECIFY a memory option
		so no confusion insues the issue.
	3 Search failed AND sort failed. 
	4 general failure; also: an unexpected DOS error Cdir can't continue after.
	5 no longer used; writing cdir.exe error - cdir.exe is probably corrupted
		no longer used; Cdir DOESN'T write to the executable
	6 runtime error - sytem may be unstable
	7 no longer used; cdir.exe is most probably corrupted, the system might be unstable.
		no longer used; Cdir DOESN'T write to the executable
	8 OK
///////////////////////////////////////////////////////////////////////////////////////////////////////////
Important!
	Cdir, in this important section, refers to the author to all materials released under the Cdir title.
	Cdir is not responsible for any or all education to anything or everything in this important section.
	Cdir has errors.  Cdir will not operate correctly at any and or all time(s).
	Lack of truely safe use of Cdir will lead to any kind of damage.
	Cdir cannot be liable in any way.
	Persons not truely educated to this important section should not operate Cdir in any way.
	Cdir should not be operated if the intent of this important section is transgressed in any way(s).
	Cdir apollogizes if you have recieved Cdir in any or all improper contexts.

	Cdir author holds USA copywright 1994 and extends or excludes these licenses:
		No ownership is granted.
		No right to recast, transform, or adapt is granted.
		Free of charge use is granted.
		Free of charge distribution is granted.
		Free of charge reproduction is granted.
///////////////////////////////////////////////////////////////////////////////////////////////////////////
Contact Info:

	hend@doubled.com

	http://customers.doubled.com/~hend/cdir.html
