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


These are the files for the program "whatfor".

"whatfor" is designed to help those who wonder what the purpose is of 
the many files in their Linux distribution. "whatfor" lists filenames 
in a manner similar to the 'ls' utility except that it appends short 
descriptions gleened from a database "whatfor_db" containing several 
thousand filename and directory descriptions.

You should already have done something like

	tar -xvzf whatfor-0.3.02.tar.gz
  or
	tar -xvzf whatfor.tgz

to create a directory "whatfor-0.3.02" (nominally in /usr/src).  This 
subdirectory is contains the following files:


Makefile    Makefile for whatfor program
README      Release instructions and Copyright License for whatfor
X11R6_db    whatfor database entries for /X11R6 X-Windows directories
bin_db      whatfor database entries for /bin and /usr/bin directories
boot_db     whatfor database entries for /boot directory
default_db  default entries for whatfor database 
dev_db      whatfor database entries for /dev directory
etc_db      whatfor database entries for /etc directory
include_db  whatfor database entries for /include directories
lib_db      whatfor database entries for /lib and /usr/lib directories
misc_db     whatfor database entries for miscellaneous other directories
proc_db     whatfor database entries for /proc directory
sbin_db     whatfor database entries for /sbin and /usr/sbin directories
src_linux_db whatfor database entries for Linux source code directory
var_db      whatfor database entries for /var directory
w4          Script to find 'whatis' descriptions missing from 'whatfor'
w4all       Script that runs 'w4' over a set of directories
whatfor     whatfor binary executable for i486 systems
whatfor.1   Manual page file for 'whatfor' program
whatfor.c   C source code for 'whatfor' program
whatfor.lsm Linux Software Map entry for whatfor
whatfor_db.1 Manual page file for the database of the 'whatfor' program


The Makefile is normally used by simply entering "make install". If the 
user has the appropriate permissions in /usr/local, this should do the 
following:
	- compile the 'whatfor' source code
	- glue together the necessary pieces making the 'whatfor_db' 
	    description database file
	- clean out old 'whatfor' files
	- install the new 'whatfor' files into /usr/local/...
	- run 'whatfor' showing the files in the source directory
	

If for some reason you cannot do the compilation and you are using 
an i486 compatible machine, perhaps you can use the executable
file "whatfor".  To do so, enter "make nocomp-install".


If your system doesn't have a /usr/src/linux directory, the descriptions
of Linux source files will not be placed in 'whatfor_db'.

USE "man whatfor" TO SEE USAGE INSTRUCTIONS.

If you want to modify the database, a description of its format can 
be obtained by doing "man whatfor_db".  Modify the pieces and reinstall
rather than directly editing "whatfor_db".


To remove all unnecessary files from the source directory enter 
"make clean".

To uninstall enter "make uninstall".


Feedback and database enhancements will be greatly appreciated.


The scripts w4 and w4all (contributed by Leo Toetsch) can be run to 
identify items missing in "whatfor_db" that are covered by your man 
pages.  If you send me the results of w4all, it can help in growing 
"whatfor_db".  Unfortunately, the "whatis" notes often contain 
mysterious abbreviations or references and need editing.



Craig Van Degrift
KanjiFlash@CompuServe.com

August 14, 1999



TODO:
	Incorporate latest findings of w4all into whatfor_db.
	Explain the use of w4 and w4all:
		w4all script runs w4 on /bin, /sbin, /usr/bin, and 
		/usr/sbin, collecting and compressing with 'gzip' the 
		results of running 'whatis' on files for which 'whatfor'
		came up empty.  The results are placed in _bin.gz, 
		_sbin.gz, _usr_bin.gz, and _usr_sbin.gz, respectively. 
		w4all and w4 need 'perl', 'awk', 'sed', 'gzip' and 
		'uniq' available in order to do their job. w4 can be 
		used with any directory that has files covered by man 
		pages and hence by 'whatis'. Its prints to standard out 
		if it finds anything.

	Add more linux source file info to 'whatfor_db'.
	For each release be sure to update revision numbers and dates 
		in man and program files.
	For each release be sure to update the LSM file and the
		README with its revision history.
	Maybe add a '--search_db=x' option to 'grep' on the db for
		items related to 'x'.

_______________________________________


Revision History:


August 13, 1999

	Enhanced and corrected descriptions in database for /proc.

	Fixed /lib/modules/ tree descriptions & added more module info

	Fixed bug in handling of numeric directory and file names.

	Cleaned up a few more sloppy or wrong descriptions in whatfor_db


May 18, 1999

	Fixed problem with --color=auto not working like 'ls' (bug 
found by Leo Toetsch).

	Incorporated w4 and w4all scripts and their output on SuSE
system.  These were contributed by Leo Toetsch.


May 16, 1999

	Following the recommendations of Ocie Mitchell & Leo Toetsch,
whatfor.c now uses "char *getenv(const char* name);" instead of 
"extern char* environ[];" to check the environment.

	Changed matching algorithm to not allow for version numbers
in /dev and /proc directories.  This was causing problems with 
tty10 being considered the same as tty1 and similar cases.


May 4, 1999 - Version 0.3.00 released to sunsite.


May 3, 1999

	Reworked Makefile and created whatfor.lsm file in preparation

	for release to sunsite.

	Added a few more entries to bin_db

	Revised man pages a bit.


May 1, 1999

	Split man page into program and database parts.

	Added 100 X11R6-related executables to whatfor_db and added
	directories and files inspired by studying the "Filesystem 
	Hierarchy Standard - Version 2.0".  Also added skeleton for 
	rest of X11R6 hierarchy.

	Moved 'whatfor_db' to /usr/local/share/misc.


April 28, 1999 - Version 0.2.01 released
	
	Made changes suggested by Trevor Johnson of the San Gabriel 
Valley Linux User's Group:

        Added #include <unistd.h> containing environ[]. For some 
           reason my system didn't need it, but other systems do.

	Made main return int rather than void.

	Made a few minor changes to whatfor_db including making key
           directory descriptions better match the "Linux Filesystem
           Structure - Release 1.2" from Daniel.Quinlan@linux.org

	Changed installation locations of files to match guidelines
           given in "Linux Filesystem Structure - Release 1.2".

	Improved README and WWW page description.
	

April 22, 1999 - Version 0.2.00 released

	Tuned up whatfor.1, README, and Makefile

	Fixed match failure on single letter filename

	Changed directory match condition to tolerate version 
extensions on directories. 

	Finished off adding /bin entries to whatfor_db and tidied up
whatfor_db a bit.


April 18, 1999

	Added more /bin entries to whatfor_db.


April 17, 1999

	Changed file match condition to tolerate version extensions
containing only digits, '.', and '-' such as are often present at 
the ends of libraries and source directories.

	Added more /lib entries to whatfor_db

	Inserted checks for NULL return by malloc in case of 
"out of memory" condition.


April 11, 1999

	Further sanitization of program - comments, error handling,
and code readability improved - normal operation unchanged (I hope).

	More /usr/bin executables added to whatfor_db


April 9, 1999

	Sanitized program and added table for shortcuts to directory
linked list based on directory name length.

	Added more executables found in /usr/bin to whatfor_db


April 8, 1999

	Corrected pattern rule in Makefile 


April 8, 1999

	Made manual and code comments better match reality.
	Added revision history to README file.


April 7, 1999

	Fixed problem recursing directories and restructured internal 
linked lists to cause the checking against longer filenames before 
shorter ones.

	Fixed problem with color on first directory during directory 
recursion.

	Added a chunk of Linux source directories to whatfor_db - more 
still to do.

	Made /dev entries more comprehensive in whatfor_db.
