Update PeterG's internals documentation per Monty's comments;

minor changes only.

1 files changed, 347 insertions, 537 deletions

diff --git a/Docs/internals.texi b/Docs/internals.texi
index 07eea90e229..5c2070abb9c 100644
--- a/Docs/internals.texi
+++ b/Docs/internals.texi
@@ -273,7 +273,7 @@ and then we read the rows in the sorted order into a row buffer
 @itemize @bullet
 
 @item
-We are using @uref{http://www.bitkeeper.com/, BitKeeper} for source management.
+We use @uref{http://www.bitkeeper.com/, BitKeeper} for source management.
 
 @item
 You should use the @strong{MySQL} 4.0 source for all developments.
@@ -3131,42 +3131,38 @@ program is given along with an explanation of its intended function.
 @strong{Directory  --  Short Comment}
 @itemize @bullet
 @item
-bdb  --  The Berkeley Database table handler 
+bdb  --  The Berkeley Database table handler
 @item
 BitKeeper  --  BitKeeper administration (not part of the source distribution)
 @item
-BUILD  --  Some very often used build scripts
+BUILD  --  Frequently used build scripts
 @item
-Build-tools  --  Build tools
+Build-tools  --  Build tools (not part of the source distribution)
 @item
-client  --  Client library 
+client  --  Client library
 @item
 cmd-line-utils  --  Command-line utilities (libedit and readline)
 @item
 dbug  --  Fred Fish's dbug library
 @item
-Docs  --  Preliminary documents about internals and new modules 
+Docs  --  Preliminary documents about internals and new modules; will eventually be moved to the mysqldoc repository
 @item
 extra  --  Some minor standalone utility programs
 @item
 heap  --  The HEAP table handler
 @item
-include  --  Include (*.h) files
+include  --  Header (*.h) files for most libraries; includes all header files distributed with the MySQL binary distribution
 @item
 innobase  --  The Innobase (InnoDB) table handler
 @item
-isam  --  The ISAM (MySQL) table handler
+libmysql  --  For producing MySQL as a library (e.g. a Windows .DLL)
 @item
-libmysql  --  For producing a thread-safe libmysql library
-@item
-libmysql_r  --  Only one file, a makefile
+libmysql_r  --  For building a thread-safe libmysql library
 @item
 libmysqld  --  The MySQL Server as an embeddable library
 @item
 man  --  Some user-contributed manual pages
 @item
-merge  --  The MERGE table handler (see Reference Manual section 7.2)
-@item
 myisam  --  The MyISAM table handler 
 @item
 myisammrg  --  The MyISAM Merge table handler 
@@ -3177,9 +3173,9 @@ mysys  --  MySQL system library (Low level routines for file access etc.)
 @item
 netware  --  Files related to the Novell NetWare version of MySQL 
 @item
-NEW-RPMS  --  Directory to place RPMS while making a distribution
+NEW-RPMS  --  Directory to place RPMs while making a distribution
 @item
-os2  --  Routines for working with the OS/2 operating system 
+os2  --  Routines for working with the OS/2 operating system
 @item
 pstack  --  Process stack display (not currently used)
 @item
@@ -3189,25 +3185,25 @@ SCCS  --  Source Code Control System (not part of source distribution)
 @item
 scripts  --  SQL batches, e.g. mysqlbug and mysql_install_db
 @item
-sql  --  Programs for handling SQL commands. The "core" of MySQL 
+sql  --  Programs for handling SQL commands; the "core" of MySQL 
 @item
 sql-bench  --  The MySQL benchmarks 
 @item
-SSL  --  Secure Sockets Layer 
+SSL  --  Secure Sockets Layer; includes an example certification one can use to test an SSL (secure) database connection
 @item
 strings  --  Library for C string routines, e.g. atof, strchr 
 @item
 support-files  --  Files used to build MySQL on different systems
 @item
-tests  --  Tests in Perl 
+tests  --  Tests in Perl and in C
 @item
-tools  --  mysqlmanager.c (under development, not yet useful)
+tools  --  mysqlmanager.c (tool under development, not yet useful)
 @item
 VC++Files  --  Includes this entire directory, repeated for VC++ (Windows) use
 @item
 vio  --  Virtual I/O Library 
 @item
-zlib  --  data compression library, used on Windows
+zlib  --  Data compression library, used on Windows
 @end itemize
 
 @subsection bdb
@@ -3215,7 +3211,7 @@ zlib  --  data compression library, used on Windows
 The Berkeley Database table handler.
 @*@*
 
-The Berkeley Database (BDB) is maintained by Sleepycat Software. 
+The Berkeley Database (BDB) is maintained by Sleepycat Software.
 MySQL AB maintains only a few small patches to make BDB work
 better with MySQL.
 @*@*
@@ -3231,19 +3227,21 @@ in this document.
 BitKeeper administration.
 @*@*
 
-This directory may be present if you downloaded the MySQL source using
+Bitkeeper administration is not part of the source distribution. This 
+directory may be present if you downloaded the MySQL source using
 BitKeeper rather than via the mysql.com site. The files in the
 BitKeeper directory are for maintenance purposes only -- they are not
 part of the MySQL package.
 @*@*
 
-The MySQL Reference Manual explains how to use Bitkeeper to get the 
-MySQL source.
+The MySQL Reference Manual explains how to use Bitkeeper to get the
+MySQL source. Please see @url{http://www.mysql.com/doc/en/Installing_source_tree.html}
+for more information.
 @*@*
 
 @subsection BUILD
 
-Build switches.
+Frequently used build scripts.
 @*@*
 
 This directory contains the build switches for compilation on various
@@ -3266,11 +3264,11 @@ solaris
 Build tools.
 @*@*
 
-This directory contains batch files for extracting, making
-directories, and making programs from source files. There are 
-several subdirectories with different scripts -- for building 
-Linux executables, for compiling, for performing all build steps, 
-and so on.
+Build-tools is not part of the source distribution. This directory
+contains batch files for extracting, making directories, and making
+programs from source files. There are several subdirectories with
+different scripts -- for building Linux executables, for compiling,
+for performing all build steps, and so on.
 @*@*
 
 @subsection client
@@ -3302,7 +3300,7 @@ mysqladmin.c  --  maintenance of MYSQL databases
 @item
 mysqlcheck.c  --  check all databases, check connect, etc.
 @item
-mysqldump.c  --  dump table's contents as SQL statements
+mysqldump.c  --  dump table's contents as SQL statements, suitable to backup a MySQL database
 @item
 mysqlimport.c  --  import text files in different formats into tables
 @item
@@ -3314,7 +3312,7 @@ mysqlshow.c  --  show databases, tables or columns
 @item
 mysqltest.c  --  test program used by the mysql-test suite, mysql-test-run
 @item
-password.c  --  password checking routines 
+password.c  --  password checking routines (version 4.1 and up)
 @item
 select_test.c  --  test that a select is possible 
 @item
@@ -3328,15 +3326,14 @@ thread_test.c  --  test that threading is possible
 
 @subsection cmd-line-utils
 
-Command-line utilities.
+Command-line utilities (libedit and readline).
 @*@*
 
 There are two subdirectories: \readline and \libedit. All the files
-here are "non-MYSQL" files, in the sense that MySQL AB didn't produce
+here are "non-MySQL" files, in the sense that MySQL AB didn't produce
 them, it just uses them. It should be unnecessary to study the
-programs in these files unless
-you are writing or debugging a tty-like client for MySQL, such as
-mysql.exe.
+programs in these files unless you are writing or debugging a tty-like
+client for MySQL, such as mysql.exe.
 @*@*
 
 The \readline subdirectory contains the files of the GNU Readline
@@ -3346,54 +3343,54 @@ Software Foundation.
 @*@*
 
 The \libedit (library of edit functions) subdirectory has files
-written by Christos Zoulas. They are distributed and modifed under 
+written by Christos Zoulas. They are distributed and modifed under
 the BSD License. These files are for editing the line contents.
 @*@*
 
 These are the program files in the \libedit subdirectory:
 @itemize @bullet
 @item
-chared.c  --  character editor 
+chared.c  --  character editor
 @item
-common.c  --  common editor functions 
+common.c  --  common editor functions
 @item
-el.c  --  editline interface functions 
+el.c  --  editline interface functions
 @item
-emacs.c  --  emacs functions 
+emacs.c  --  emacs functions
 @item
-fgetln.c  --  get line 
+fgetln.c  --  get line
 @item
-hist.c  --  history access functions 
+hist.c  --  history access functions
 @item
-history.c  --  more history access functions 
+history.c  --  more history access functions
 @item
-key.c  --  procedures for maintaining the extended-key map 
+key.c  --  procedures for maintaining the extended-key map
 @item
-map.c  --  editor function definitions 
+map.c  --  editor function definitions
 @item
-parse.c  --  parse an editline extended command 
+parse.c  --  parse an editline extended command
 @item
-prompt.c  --  prompt printing functions 
+prompt.c  --  prompt printing functions
 @item
-read.c  --  terminal read functions 
+read.c  --  terminal read functions
 @item
-readline.c  --  read line 
+readline.c  --  read line
 @item
-refresh.c  --  "lower level screen refreshing functions" 
+refresh.c  --  "lower level screen refreshing functions"
 @item
-search.c  --  "history and character search functions" 
+search.c  --  "history and character search functions"
 @item
-sig.c  --  for signal handling 
+sig.c  --  for signal handling
 @item
-strlcpy.c  --  string copy 
+strlcpy.c  --  string copy
 @item
-term.c  --  "editor/termcap-curses interface" 
+term.c  --  "editor/termcap-curses interface"
 @item
-tokenizer.c  --  Bourne shell line tokenizer 
+tokenizer.c  --  Bourne shell line tokenizer
 @item
-tty.c  --  for a tty interface 
+tty.c  --  for a tty interface
 @item
-vi.c  --  commands used when in the vi (editor) mode 
+vi.c  --  commands used when in the vi (editor) mode
 @end itemize
 @*@*
 
@@ -3403,8 +3400,8 @@ Fred Fish's dbug library.
 @*@*
 
 This is not really part of the MySQL package. Rather, it's a set of
-public-domain routines which are useful for debugging MySQL programs. 
-The MySQL Server and all .c and .cc programs support the use of this 
+public-domain routines which are useful for debugging MySQL programs.
+The MySQL Server and all .c and .cc programs support the use of this
 package.
 @*@*
 
@@ -3415,61 +3412,62 @@ DBUG_ENTER("get_tty_password"); @*
 at the start of a routine, and this line: @*
 DBUG_RETURN(my_strdup(to,MYF(MY_FAE))); @*
 at the end of the routine. These lines don't affect production code.
-Features of the dbug library include extensive reporting and profiling 
+Features of the dbug library include extensive reporting and profiling
 (the latter has not been used by the MySQL team).
 @*@*
 
 The C programs in this directory are:
 @itemize @bullet
 @item
-dbug.c  --  The main module 
+dbug.c  --  The main module
 @item
-dbug_analyze.c  --  Reads a file produced by trace functions 
+dbug_analyze.c  --  Reads a file produced by trace functions
 @item
-example1.c  --  A tiny example 
+example1.c  --  A tiny example
 @item
-example2.c  --  A tiny example 
+example2.c  --  A tiny example
 @item
-example3.c  --  A tiny example 
+example3.c  --  A tiny example
 @item
-factorial.c  --  A tiny example 
+factorial.c  --  A tiny example
 @item
-main.c  --  A tiny example 
+main.c  --  A tiny example
 @item
-sanity.c  --   Declaration of a variable 
+sanity.c  --   Declaration of a variable
 @end itemize
 @*@*
 
 @subsection Docs
 
-Preliminary documents about internals and new modules.
+Preliminary documents about internals and new modules, which will eventually
+be moved to the mysqldoc repository.
 @*@*
 
 This directory doesn't have much at present that's very useful to the
 student, but the plan is that some documentation related to the source
 files and the internal workings of MySQL, including perhaps some
-documentation from developers themselves, will be placed here. Some of 
-these files will eventually be moved to the MySQL documentation repository.
+documentation from developers themselves, will be placed here. Files in
+this directory will eventually be moved to the MySQL documentation repository.
 @*@*
 
 These sub-directories are part of this directory:
 @itemize @bullet
 @item
-books  --  .gif images and empty .txt files; no real information 
+books  --  .gif images and empty .txt files; no real information
 @item
-flags  --  images of flags of countries 
+flags  --  images of flags of countries
 @item
-images  --  flag backgrounds and the MySQL dolphin logo 
+images  --  flag backgrounds and the MySQL dolphin logo
 @item
-mysql-logos  --  more MySQL-related logos, some of them moving 
+mysql-logos  --  more MySQL-related logos, some of them moving
 @item
-raw-flags  --   more country flags, all .gif files 
+raw-flags  --   more country flags, all .gif files
 @item
-support  --  various files for generating texinfo/docbook documentation 
+support  --  various files for generating texinfo/docbook documentation
 @item
-to-be-included...  --  an empty subdirectory 
+to-be-included...  --  an empty subdirectory
 @item
-translations  --  some Portuguese myodbc documentation 
+translations  --  some Portuguese myodbc documentation
 @end itemize
 @*@*
 
@@ -3480,16 +3478,16 @@ has any importance -- internals.texi -- The "MySQL Internals"
 document.
 @*@*
 
-Despite the name, internals.texi is not really much of a description
-of MySQL internals. However, there is some useful description of the
-functions in the mysys directory (see below), and of the structure of
-client/server messages (doubtless very useful for people who want to
-make their own JDBC drivers, or just sniff).
+Despite the name, internals.texi is not yet much of a description of MySQL
+internals although work is in progress to make it so. However, there is 
+some useful description of the functions in the mysys directory (see below), 
+and of the structure of client/server messages (doubtless very useful for 
+eople who want to make their own JDBC drivers, or just sniff).
 @*@*
 
 @subsection extra
 
-Eight minor standalone utility programs.
+Some minor standalone utility programs.
 @*@*
 
 These programs are all standalone utilities, that is, they have
@@ -3498,56 +3496,20 @@ MySQL server needs or produces. Most are unimportant. They are as
 follows:
 @itemize @bullet
 @item
-my_print_defaults.c  --  print all parameters in a default file 
+my_print_defaults.c  --  print parameters from my.ini files. Can also be used in scripts to enable processing of my.ini files.
 @item
-mysql_install.c  --  startup: install MySQL server 
+mysql_waitpid.c  --  wait for a program to terminate. Useful for shell scripts when one needs to wait until a process terminates.
 @item
-mysql_waitpid.c  --  wait for a program to terminate 
-@item
-perror.c  --  "print error" -- given error number, display message 
+perror.c  --  "print error" -- given error number, display message
 @item
 replace.c  --  replace strings in text files or pipe
 @item
-resolve_stack_dump.c  --  show symbolic info from a stack dump 
+resolve_stack_dump.c  --  show symbolic information from a MySQL stack dump, normally found in the mysql.err file
 @item
-resolveip.c  --  convert an IP address to a hostname, or vice versa 
+resolveip.c  --  convert an IP address to a hostname, or vice versa
 @end itemize
 @*@*
 
-@subsection fs
-
-File System.
-@*@*
-
-Here the word "File System" does not refer to the mere idea of a
-directory of files on a disk drive, but to object-based access. The
-concept has been compared with Oracle's Internet File System (iFS).
-@*@*
-
-The original developer of the files on this directory is Tonu Samuel,
-a former MySQL AB employee. Here is a quote (somewhat edited) from
-Tonu Samuel's web page (http://no.spam.ee/~tonu/index.php): 
-"Question: What is it? 
-Answer: Actually this is not filesystem in common terms. MySQL FS
-makes it possible to make SQL tables and some functions available over
-a filesystem. MySQL does not require disk space, it uses an ordinary
-MySQL daemon to store data." 
-The descriptions imply that this is a development project.
-@*@*
-
-There are four program files in the directory:
-@itemize @bullet
-@item
-database.c  --  "emulate filesystem behaviour on top of SQL database" 
-@item
-libmysqlfs.c  --  Search/replace, show-functions, and parse routines
-@item
-mysqlcorbafs.c  --  Connection with the CORBA "Object Request Broker" 
-@item
-mysqlcorbafs_test.c  --  Utility to test the working of mysqlcorbafs.c
-
-@*@*
-
 @subsection heap
 
 The HEAP table handler.
@@ -3567,50 +3529,50 @@ hp_block.c  --  Read/write a block (i.e. a page)
 @item
 hp_clear.c  --  Remove all records in the table
 @item
-hp_close.c  --  * close database 
+hp_close.c  --  * close database
 @item
-hp_create.c  --  * create a table 
+hp_create.c  --  * create a table
 @item
-hp_delete.c  --  * delete a row 
+hp_delete.c  --  * delete a row
 @item
 hp_extra.c  --  * for setting options and buffer sizes when optimizing
 @item
-hp_hash.c  --  Hash functions used for saving keys 
+hp_hash.c  --  Hash functions used for saving keys
 @item
-hp_info.c  --  * Information about database status 
+hp_info.c  --  * Information about database status
 @item
-hp_open.c  --  * open database 
+hp_open.c  --  * open database
 @item
 hp_panic.c  --  * the hp_panic routine, for shutdowns and flushes
 @item
-hp_rename.c  --  * rename a table 
+hp_rename.c  --  * rename a table
 @item
 hp_rfirst.c  --  * read first row through a specific key (very short)
 @item
-hp_rkey.c  --  * read record using a key 
+hp_rkey.c  --  * read record using a key
 @item
 hp_rlast.c  --  * read last row with same key as previously-read row
 @item
 hp_rnext.c  --  * read next row with same key as previously-read row
 @item
-hp_rprev.c  --  * read previous row with same key as previously-read row 
+hp_rprev.c  --  * read previous row with same key as previously-read row
 @item
-hp_rrnd.c  --  * read a row based on position 
+hp_rrnd.c  --  * read a row based on position
 @item
 hp_rsame.c  --  * find current row using positional read or key-based
-read 
+read
 @item
-hp_scan.c  --  * read all rows sequentially 
+hp_scan.c  --  * read all rows sequentially
 @item
 hp_static.c  --  * static variables (very short)
 @item
-hp_test1.c  --  * testing basic functions 
+hp_test1.c  --  * testing basic functions
 @item
-hp_test2.c  --  * testing database and storing results 
+hp_test2.c  --  * testing database and storing results
 @item
-hp_update.c  --  * update an existing row 
+hp_update.c  --  * update an existing row
 @item
-hp_write.c  --  * insert a new row 
+hp_write.c  --  * insert a new row
 @end itemize
 @*@*
 
@@ -3622,7 +3584,8 @@ for a \myisam\mi_cache.c equivalent (to cache reads) or a
 
 @subsection include
 
-Include (*.h) files.
+Header (*.h) files for most libraries; includes all header files distributed
+with the MySQL binary distribution.
 @*@*
 
 These files may be included in C program files. Note that each
@@ -3637,7 +3600,7 @@ rijndael.h. Looking further, you'll find that rijndael.h is also
 included in other places: by my_aes.c and my_aes.h.
 @*@*
 
-The include directory contains 51 *.h (include) files.
+The include directory contains 51 *.h (header) files.
 @*@*
 
 @subsection innobase
@@ -3649,100 +3612,6 @@ A full description of these files can be found elsewhere in this
 document.
 @*@*
 
-@subsection isam
-
-The ISAM table handler.
-@*@*
-
-The C files in this directory are:
-@itemize @bullet
-@item
-_cache.c  --  for reading records from a cache 
-@item
-changed.c  --  a single routine for setting a "changed" flag (very
-short)
-@item
-close.c  --  close database 
-@item
-create.c  --  create a table 
-@item
-_dbug.c  --  support routines for use with "dbug" (see the \dbug
-description)
-@item
-delete.c  --  delete a row 
-@item
-_dynrec.c  --  functions to handle space-packed records and blobs 
-@item
-extra.c  --  setting options and buffer sizes when optimizing table
-handling 
-@item
-info.c  --  Information about database status 
-@item
-_key.c  --  for handling keys 
-@item
-_locking.c  --  lock database 
-@item
-log.c  --  save commands in log file which myisamlog program can read 
-@item
-_packrec.c  --  compress records 
-@item
-_page.c  --  read and write pages containing keys 
-@item
-panic.c  --  the mi_panic routine, probably for sudden shutdowns 
-@item
-range.c  --  approximate count of how many records lie between two
-keys 
-@item
-rfirst.c  --  read first row through a specific key (very short)
-@item
-rkey.c  --  read a record using a key 
-@item
-rlast.c  --  read last row with same key as previously-read row 
-@item
-rnext.c  --  read next row with same key as previously-read row 
-@item
-rprev.c  --  read previous row with same key as previously-read row 
-@item
-rrnd.c  --  read a row based on position 
-@item
-rsame.c  --  find current row using positional read or key-based read 
-@item
-rsamepos.c  --  positional read 
-@item
-_search.c  --  key-handling functions 
-@item
-static.c  --  static variables (very short)
-@item
-_statrec.c  --  functions to handle fixed-length records 
-@item
-test1.c  --  testing basic functions 
-@item
-test2.c  --  testing database and storing results 
-@item
-test3.c  --  testing locking 
-@item
-update.c  --  update an existing row 
-@item
-write.c  --  insert a new row 
-@item
-pack_isam.c  --  pack isam file (NOTE TO SELF ?? equivalent to
-\myisam\myisampack.c)
-@end itemize
-@*@*
-
-Except for one minor C file (pack_isam.c) every program in the ISAM
-directory has a counterpart in the MyISAM directory. For example
-\isam\update.c corresponds to \myisam\mi_update.c. However, the
-reverse is not true -- there are many files in the MyISAM directory
-which have no counterpart in the ISAM directory.
-@*@*
-
-The reason is simple -- it's because the ISAM files are becoming
-obsolete. When MySQL programmers add new features, they add them for
-MyISAM only. The student can therefore ignore all files in this
-directory and study the MyISAM programs instead.
-@*@*
-
 @subsection libmysql
 
 The MySQL Library, Part 1.
@@ -3772,7 +3641,7 @@ errmsg.c  --  English error messages, compare \mysys\errors.c
 @item
 get_password.c  --  get password 
 @item
-libmysql.c  --  the main "packet-sending emulation" program 
+libmysql.c  --  the code that implements the MySQL API, i.e. the functions a client that wants to connect to MySQL will call
 @item
 manager.c  --  initialize/connect/fetch with MySQL manager 
 @end itemize
@@ -3784,7 +3653,7 @@ The MySQL Library, Part 2.
 @*@*
 
 This is a continuation of the libmysql directory. There is only one
-file here:
+file here, used to build a thread-safe libmysql library:
 @itemize @bullet
 @item
 makefile.am
@@ -3796,85 +3665,26 @@ makefile.am
 The MySQL library, Part 3.
 @*@*
 
-This is a continuation of the libmysql directory. The program files on
-this directory are:
+This is a continuation of the libmysql directory and contains the MySQL
+Server as an embeddable library. The program files on this directory
+are:
 @itemize @bullet
 @item
-libmysqld.c  --  The called side, compare the mysqld.exe source 
+libmysqld.c  --  The called side, compare the mysqld.exe source
 @item
-lib_vio.c --  Emulate the vio directory's communication buffer 
+lib_vio.c --  Emulate the vio directory's communication buffer
 @end itemize
 @*@*
 
 @subsection man
 
-Manual pages.
+Some user-contributed manual pages
 @*@*
 
 These are not the actual "man" (manual) pages, they are switches for
 the production.
 @*@*
 
-@subsection merge
-
-The MERGE table handler.
-@*@*
-
-For a description of the MERGE table handler, see the MySQL Reference
-Manual, section 7.2.
-@*@*
-
-You'll notice that there seem to be several directories with
-similar-sounding names of C files in them. That's because the MySQL
-table handlers are all quite similar.
-@*@*
-
-The related directories are:
-@itemize @bullet
-@item
-\isam  --  for ISAM 
-@item
-\myisam  --  for MyISAM 
-@item
-\merge  --  for ISAM MERGE (mostly call functions in \isam programs)
-@item
-\myisammrg  --  for MyISAM MERGE (mostly call functions in \myisam
-programs)
-@end itemize
-@*@*
-
-To avoid duplication, only the \myisam program versions are discussed.
-@*@*
-
-The C programs in this (merge) directory are:
-@itemize @bullet
-@item
-mrg_close.c  --  compare \isam's close.c 
-@item
-mrg_create.c  --  "" create.c 
-@item
-mrg_delete.c  --  "" delete.c 
-@item
-mrg_extra.c  --  "" extra.c 
-@item
-mrg_info.c  --  "" info.c 
-@item
-mrg_locking.c  --  "" locking.c 
-@item
-mrg_open.c  --  "" open.c 
-@item
-mrg_panic.c  --  "" panic.c 
-@item
-mrg_rrnd.c  --  "" rrnd.c 
-@item
-mrg_rsame.c  --  "" rsame.c 
-@item
-mrg_static.c  --  "" static.c 
-@item
-mrg_update.c  --  "" update.c 
-@end itemize
-@*@*
-
 @subsection myisam
 
 The MyISAM table handler.
@@ -3910,10 +3720,9 @@ programs. They are:
 @item
 mi_cache.c  --  for reading records from a cache 
 @item
-mi_changed.c  --  a single routine for setting a "changed" flag (very
-short)
+mi_changed.c  --  a single routine for setting a "changed" flag (very short)
 @item
-mi_check.c  --  doesn't just do checks, ?? for myisamchk program? 
+mi_check.c  --  for checking and repairing tables. Used by the myisamchk program and by the MySQL server.
 @item
 mi_checksum.c  --  calculates a checksum for a row 
 @item
@@ -3921,8 +3730,7 @@ mi_close.c  --  close database
 @item
 mi_create.c  --  create a table 
 @item
-mi_dbug.c  -- support routines for use with "dbug" (see \dbug
-description)
+mi_dbug.c  -- support routines for use with "dbug" (see \dbug description)
 @item
 mi_delete.c  --  delete a row 
 @item
@@ -3940,58 +3748,57 @@ mi_key.c  --  for handling keys
 @item
 mi_locking.c  --  lock database 
 @item
-mi_log.c  --  save commands in log file which myisamlog program can read
+mi_log.c  --  save commands in a log file which myisamlog program can read. Can be used to exactly replay a set of changes to a table.
 @item
 mi_open.c  --  open database 
 @item
 mi_packrec.c  --  read from a data file compresed with myisampack
 @item
-mi_page.c  --  read and write pages containing keys 
+mi_page.c  --  read and write pages containing keys
 @item
-mi_panic.c  --  the mi_panic routine, probably for sudden shutdowns 
+mi_panic.c  --  the mi_panic routine, probably for sudden shutdowns
 @item
 mi_range.c  --  approximate count of how many records lie between two keys
 @item
-mi_rename.c  --  rename a table 
+mi_rename.c  --  rename a table
 @item
 mi_rfirst.c  --  read first row through a specific key (very short)
 @item
-mi_rkey.c  --  read a record using a key 
+mi_rkey.c  --  read a record using a key
 @item
-mi_rlast.c  --  read last row with same key as previously-read row 
+mi_rlast.c  --  read last row with same key as previously-read row
 @item
-mi_rnext.c  --  read next row with same key as previously-read row 
+mi_rnext.c  --  read next row with same key as previously-read row
 @item
-mi_rnext_same.c  --  same as mi_rnext.c, but abort if the key changes 
+mi_rnext_same.c  --  same as mi_rnext.c, but abort if the key changes
 @item
 mi_rprev.c  --  read previous row with same key as previously-read row
 @item
-mi_rrnd.c  --  read a row based on position 
+mi_rrnd.c  --  read a row based on position
 @item
-mi_rsame.c  --  find current row using positional read or key-based
-read 
+mi_rsame.c  --  find current row using positional read or key-based read
 @item
-mi_rsamepos.c  --  positional read 
+mi_rsamepos.c  --  positional read
 @item
-mi_scan.c  --  read all rows sequentially 
+mi_scan.c  --  read all rows sequentially
 @item
-mi_search.c  --  key-handling functions 
+mi_search.c  --  key-handling functions
 @item
 mi_static.c  --  static variables (very short)
 @item
-mi_statrec.c  --  functions to handle fixed-length records 
+mi_statrec.c  --  functions to handle fixed-length records
 @item
-mi_test1.c  --  testing basic functions 
+mi_test1.c  --  testing basic functions
 @item
-mi_test2.c  --  testing database and storing results 
+mi_test2.c  --  testing database and storing results
 @item
-mi_test3.c  --  testing locking 
+mi_test3.c  --  testing locking
 @item
-mi_unique.c  --  functions to check if a row is unique 
+mi_unique.c  --  functions to check if a row is unique
 @item
-mi_update.c  --  update an existing row 
+mi_update.c  --  update an existing row
 @item
-mi_write.c  --  insert a new row 
+mi_write.c  --  insert a new row
 @end itemize
 @*@*
 
@@ -4104,7 +3911,7 @@ tests
 
 @subsection mysys
 
-MySQL system library (Low level routines for file access etc.).
+MySQL system library. Low level routines for file access and so on.
 @*@*
 
 There are 115 *.c programs in this directory:
@@ -4112,13 +3919,11 @@ There are 115 *.c programs in this directory:
 @item
 array.c  --  Dynamic array handling 
 @item
-charset.c  --  Using dynamic character sets, set default character
-set, ... 
+charset.c  --  Using dynamic character sets, set default character set, ...
 @item
-charset2html.c  --  Checking what character set a browser is using 
+charset2html.c  --  Check what character set a browser is using
 @item
-checksum.c  --  Calculate checksum for a memory block, used for
-pack_isam 
+checksum.c  --  Calculate checksum for a memory block, used for pack_isam
 @item
 default.c  --  Find defaults from *.cnf or *.ini files 
 @item
@@ -4128,54 +3933,51 @@ hash.c  --  Hash search/compare/free functions "for saving keys"
 @item
 list.c  --  Double-linked lists 
 @item
-make-conf.c  --  "Make a charset .conf file out of a ctype-charset.c
-file" 
+make-conf.c  --  "Make a charset .conf file out of a ctype-charset.c file"
 @item
 md5.c  --  MD5 ("Message Digest 5") algorithm from RSA Data Security
 @item
-mf_brkhant.c  --  Prevent user from doing a Break during critical
-execution 
+mf_brkhant.c  --  Prevent user from doing a Break during critical execution (not used in MySQL; can be used by standalone MyISAM applications)
 @item
-mf_cache.c  --  "Open a temporary file and cache it with io_cache" 
+mf_cache.c  --  "Open a temporary file and cache it with io_cache"
 @item
-mf_dirname.c  --  Parse/convert directory names 
+mf_dirname.c  --  Parse/convert directory names
 @item
-mf_fn_ext.c  --  Get filename extension 
+mf_fn_ext.c  --  Get filename extension
 @item
-mf_format.c  --  Format a filename 
+mf_format.c  --  Format a filename
 @item
-mf_getdate.c  --  Get date, return in yyyy-mm-dd hh:mm:ss format 
+mf_getdate.c  --  Get date, return in yyyy-mm-dd hh:mm:ss format
 @item
-mf_iocache.c  --  Cached read/write of files in fixed-size units 
+mf_iocache.c  --  Cached read/write of files in fixed-size units
 @item
-mf_iocache2.c  --  Continuation of mf_iocache.c 
+mf_iocache2.c  --  Continuation of mf_iocache.c
 @item
-mf_keycache.c  --  Key block caching for certain file types 
+mf_keycache.c  --  Key block caching for certain file types
 @item
 mf_loadpath.c  --  Return full path name (no ..\ stuff)
 @item
 mf_pack.c  --  Packing/unpacking directory names for create purposes
 @item
-mf_path.c  --  Determine where a program can find its files 
+mf_path.c  --  Determine where a program can find its files
 @item
-mf_qsort.c  --  Quicksort 
+mf_qsort.c  --  Quicksort
 @item
-mf_qsort2.c  --  Quicksort, part 2 
+mf_qsort2.c  --  Quicksort, part 2 (allows the passing of an extra argument to the sort-compare routine)
 @item
-mf_radix.c  --  Radix sort 
+mf_radix.c  --  Radix sort
 @item
-mf_same.c  --  Determine whether filenames are the same 
+mf_same.c  --  Determine whether filenames are the same
 @item
-mf_sort.c  --  Sort with choice of Quicksort or Radix sort 
+mf_sort.c  --  Sort with choice of Quicksort or Radix sort
 @item
-mf_soundex.c  --  Soundex algorithm derived from EDN Nov. 14, 1985
-(pg. 36)
+mf_soundex.c  --  Soundex algorithm derived from EDN Nov. 14, 1985 (pg. 36)
 @item
-mf_strip.c  --  Strip trail spaces from a string 
+mf_strip.c  --  Strip trail spaces from a string
 @item
-mf_tempdir.c  --  Initialize/find/free temporary directory 
+mf_tempdir.c  --  Initialize/find/free temporary directory
 @item
-mf_tempfile.c  --  Create a temporary file 
+mf_tempfile.c  --  Create a temporary file
 @item
 mf_unixpath.c  --  Convert filename to UNIX-style filename 
 @item
@@ -4300,8 +4102,7 @@ my_rename.c  --  Rename without delete
 @item
 my_seek.c  --  Seek, i.e. point to a spot within a file 
 @item
-my_semaphore.c  --  Semaphore routines, for use on OS that doesn't
-support them 
+my_semaphore.c  --  Semaphore routines, for use on OS that doesn't support them
 @item
 my_sleep.c  --  Wait n microseconds 
 @item
@@ -4309,67 +4110,61 @@ my_static.c  --  Static variables used by the mysys library
 @item
 my_symlink.c  --  Read a symbolic link (symlinks are a UNIX thing, I guess)
 @item
-my_symlink2.c  --  Part 2 of my_symlink.c 
+my_symlink2.c  --  Part 2 of my_symlink.c
 @item
-my_tempnam.c  --  Obsolete temporary-filename routine used by ISAM table handler 
+my_tempnam.c  --  Obsolete temporary-filename routine used by ISAM table handler
 @item
-my_thr_init.c  --  initialize/allocate "all mysys & debug thread
-variables" 
+my_thr_init.c  --  initialize/allocate "all mysys & debug thread variables"
 @item
-my_wincond.c  --  Windows-specific: emulate Posix conditions 
+my_wincond.c  --  Windows-specific: emulate Posix conditions
 @item
-my_winsem.c  --  Windows-specific: emulate Posix threads 
+my_winsem.c  --  Windows-specific: emulate Posix threads
 @item
-my_winthread.c  --  Windows-specific: emulate Posix threads 
+my_winthread.c  --  Windows-specific: emulate Posix threads
 @item
-my_write.c  --  Write a specified number of bytes to a file 
+my_write.c  --  Write a specified number of bytes to a file
 @item
-ptr_cmp.c  --  Point to an optimal byte-comparison function 
+ptr_cmp.c  --  Point to an optimal byte-comparison function
 @item
-queues.c  --  Handle priority queues as in Robert Sedgewick's book 
+queues.c  --  Handle priority queues as in Robert Sedgewick's book
 @item
 raid2.c  --  RAID support (the true implementation is in raid.cc)
 @item
-rijndael.c  --  "Optimised ANSI C code for the Rijndael cipher (now
-AES")
+rijndael.c  --  "Optimised ANSI C code for the Rijndael cipher (now AES")
 @item
-safemalloc.c  --  A version of the standard malloc() with safety
-checking 
+safemalloc.c  --  A version of the standard malloc() with safety checking
 @item
-sha1.c  --  Implementation of Secure Hashing Algorithm 1 
+sha1.c  --  Implementation of Secure Hashing Algorithm 1
 @item
-string.c  --  Initialize/append/free dynamically-sized strings 
+string.c  --  Initialize/append/free dynamically-sized strings; see also sql_string.cc in the /sql directory
 @item
-testhash.c  --  Standalone program: test the hash library routines 
+testhash.c  --  Standalone program: test the hash library routines
 @item
-test_charset.c  --  Standalone program: display character set
-information 
+test_charset.c  --  Standalone program: display character set information
 @item
-test_dir.c  --  Standalone program: placeholder for "test all
-functions" idea 
+test_dir.c  --  Standalone program: placeholder for "test all functions" idea
 @item
-test_fn.c  --  Standalone program: apparently tests a function 
+test_fn.c  --  Standalone program: apparently tests a function
 @item
-test_xml.c  --  Standalone program: test XML routines 
+test_xml.c  --  Standalone program: test XML routines
 @item
-thr_alarm.c  --  Thread alarms and signal handling 
+thr_alarm.c  --  Thread alarms and signal handling
 @item
-thr_lock.c  --  "Read and write locks for Posix threads" 
+thr_lock.c  --  "Read and write locks for Posix threads"
 @item
-thr_mutex.c  --  A wrapper for mutex functions 
+thr_mutex.c  --  A wrapper for mutex functions
 @item
-thr_rwlock.c  --  Synchronizes the readers' thread locks with the
-writer's lock 
+thr_rwlock.c  --  Synchronizes the readers' thread locks with the writer's lock
 @item
-tree.c  --  Initialize/search/free binary trees 
+tree.c  --  Initialize/search/free binary trees
 @item
-typelib.c  --  Determine what type a field has 
+typelib.c  --  Find a string in a set of strings; returns the offset to the string found
 @end itemize
 @*@*
 
 You can find documentation for the main functions in these files
-elsewhere in this document.
-For example, the main functions in my_getwd.c are described thus:
+elsewhere in this document. For example, the main functions in my_getwd.c 
+are described thus:
 @*@*
 
 @example
@@ -4399,15 +4194,15 @@ testing.
 These are the five *.c files, all from Novell Inc.:
 @itemize @bullet
 @item
-libmysqlmain.c  --  Only one function: init_available_charsets() 
+libmysqlmain.c  --  Only one function: init_available_charsets()
 @item
-my_manage.c  --  Standalone management utility 
+my_manage.c  --  Standalone management utility
 @item
-mysql_install_db.c  --  Compare \scripts\mysql_install_db.sh 
+mysql_install_db.c  --  Compare \scripts\mysql_install_db.sh
 @item
-mysql_test_run.c  --  Short test program 
+mysql_test_run.c  --  Short test program
 @item
-mysqld_safe.c  --  Compare \scripts\mysqld_safe.sh 
+mysqld_safe.c  --  Compare \scripts\mysqld_safe.sh
 @end itemize
 
 Perhaps the most important file is:
@@ -4419,16 +4214,16 @@ netware.patch  --  NetWare-specific build instructions and switches
 @*@*
 
 For instructions about basic installation, see "Deployment Guide For
-NetWare AMP" at: 
+NetWare AMP" at:
 @url{http://developer.novell.com/ndk/whitepapers/namp.htm}
 @*
 
 @subsection NEW-RPMS
 
-New "RPM Package Manager" files.
+Directory to place RPMs while making a distribution.
 @*@*
 
-This directory is not part of the Windows distribution. It is 
+This directory is not part of the Windows distribution. It is
 a temporary directory used during RPM builds with Linux distributions.
 @*@*
 
@@ -4442,10 +4237,10 @@ people from outside MySQL: Yuri Dario, Timo Maier, and John M
 Alfredsson. There are no .C program files in this directory.
 @*@*
 
-The contents of \os2 are: 
+The contents of \os2 are:
 @itemize @bullet
 @item
-A Readme.Txt file 
+A Readme.Txt file
 @item
 An \include subdirectory containing .h files which are for OS/2 only
 @item
@@ -4460,7 +4255,7 @@ there have been no updates for MySQL 4.0 for this section.
 
 @subsection pstack
 
-Process stack display.
+Process stack display (not currently used).
 @*@*
 
 This is a set of publicly-available debugging aids which all do pretty
@@ -4478,7 +4273,7 @@ and it crashes.
 
 @subsection regex
 
-Regular Expression library for support of REGEXP function.
+Henry Spencer's Regular Expression library for support of REGEXP function.
 @*@*
 
 This is the copyrighted product of Henry Spencer from the University
@@ -4504,7 +4299,7 @@ This program calls the 'regcomp' function, which is the entry point in
 
 @subsection SCCS
 
-Source Code Control System.
+Source Code Control System (not part of source distribution).
 @*@*
 
 You will see this directory if and only if you used BitKeeper for
@@ -4514,10 +4309,10 @@ administration and are not of interest to application programmers.
 
 @subsection scripts
 
-SQL batches, e.g. for converting msql to MySQL.
+SQL batches, e.g. mysqlbug and mysql_install_db.
 @*@*
 
-The *.sh filename extension stands for "shell script". Linux 
+The *.sh filename extension stands for "shell script". Linux
 programmers use it where Windows programmers would use a *.bat
 (batch filename extension).
 @*@*
@@ -4525,23 +4320,23 @@ programmers use it where Windows programmers would use a *.bat
 The *.sh files on this directory are:
 @itemize @bullet
 @item
-fill_help_tables.sh  --  Create help-information tables and insert 
+fill_help_tables.sh  --  Create help-information tables and insert
 @item
 make_binary_distribution.sh  --  Get configure information, make, produce tar
 @item
-msql2mysql.sh  --  Convert mSQL programs and scripts to MySQL, partly
+msql2mysql.sh  --  Convert (partly) mSQL programs and scripts to MySQL
 @item
-mysqlbug.sh  --  Create a bug report and mail it 
+mysqlbug.sh  --  Create a bug report and mail it
 @item
-mysqld_multi.sh  --  Start/stop any number of mysqld instances 
+mysqld_multi.sh  --  Start/stop any number of mysqld instances
 @item
-mysqld_safe-watch.sh  --  Start/restart in safe mode 
+mysqld_safe-watch.sh  --  Start/restart in safe mode
 @item
-mysqld_safe.sh  --  Start/restart in safe mode 
+mysqld_safe.sh  --  Start/restart in safe mode
 @item
-mysqldumpslow.sh  --  Parse and summarize the slow query log 
+mysqldumpslow.sh  --  Parse and summarize the slow query log
 @item
-mysqlhotcopy.sh  --  Hot backup 
+mysqlhotcopy.sh  --  Hot backup
 @item
 mysql_config.sh  --  Get configuration information that might be needed to compile a client
 @item
@@ -4553,15 +4348,14 @@ mysql_find_rows.sh  --  Search for queries containing <regexp>
 @item
 mysql_fix_extensions.sh  --  Renames some file extensions, not recommended
 @item
-mysql_fix_privilege_tables.sh  --  Fix mysql.user etc. if upgrading to MySQL 3.23.14+
+mysql_fix_privilege_tables.sh  --  Fix mysql.user etc. when upgrading. Can be safely run during any upgrade to get the newest 
+MySQL privilege tables
 @item
 mysql_install_db.sh  --  Create privilege tables and func table
 @item
-mysql_secure_installation.sh  --  Disallow remote root login,
-eliminate test, etc.
+mysql_secure_installation.sh  --  Disallow remote root login, eliminate test, etc.
 @item
-mysql_setpermission.sh  --  Aid to add users or databases, sets
-privileges
+mysql_setpermission.sh  --  Aid to add users or databases, sets privileges
 @item
 mysql_tableinfo.sh  --  Puts info re MySQL tables into a MySQL table
 @item
@@ -4577,91 +4371,90 @@ Programs for handling SQL commands. The "core" of MySQL.
 These are the .c and .cc files in the sql directory:
 @itemize @bullet
 @item
-cache_manager.cc  --  manages a number of blocks 
-@item
-convert.cc  --  convert tables between different character sets 
+convert.cc  --  convert tables between different character sets
 @item
-derror.cc  --  read language-dependent message file 
+derror.cc  --  read language-dependent message file
 @item
-des_key_file.cc  --  load DES keys from plaintext file 
+des_key_file.cc  --  load DES keys from plaintext file
 @item
-field.cc  --  "implement classes defined in field.h" (long)
+field.cc  --  "implement classes defined in field.h" (long); defines all storage methods MySQL uses to store field information 
+into records that are then passed to handlers
 @item
 field_conv.cc  --  functions to copy data between fields
 @item
 filesort.cc  --  sort a result set, using memory or temporary files
 @item
-frm_crypt.cc  --  contains only one short function: get_crypt_for_frm 
+frm_crypt.cc  --  contains only one short function: get_crypt_for_frm
 @item
-gen_lex_hash.cc  --  Knuth's algorithm from Vol 3 Sorting and Searching, Chapter 6.3
+gen_lex_hash.cc  --  Knuth's algorithm from Vol 3 Sorting and Searching, Chapter 6.3; used to search for SQL keywords in a query
 @item
 gstream.cc  --  GTextReadStream, used to read GIS objects
 @item
-handler.cc  --  handler-calling functions 
+handler.cc  --  handler-calling functions
 @item
-hash_filo.cc  --  static-sized hash tables 
+hash_filo.cc  --  static-sized hash tables, used to store info like hostname -> ip tables in a FIFO manner
 @item
-ha_berkeley.cc  --  Handler: BDB 
+ha_berkeley.cc  --  Handler: BDB
 @item
-ha_heap.cc  --  Handler: Heap 
+ha_heap.cc  --  Handler: Heap
 @item
-ha_innodb.cc  --  Handler: InnoDB 
+ha_innodb.cc  --  Handler: InnoDB
 @item
-ha_isam.cc  --  Handler: ISAM 
+ha_isam.cc  --  Handler: ISAM
 @item
 ha_isammrg.cc  --  Handler: (ISAM MERGE)
 @item
-ha_myisam.cc  --  Handler: MyISAM 
+ha_myisam.cc  --  Handler: MyISAM
 @item
 ha_myisammrg.cc  --  Handler: (MyISAM MERGE)
 @item
-hostname.cc  --  Given IP, return hostname 
+hostname.cc  --  Given IP, return hostname
 @item
-init.cc  --  Init and dummy functions for interface with unireg 
+init.cc  --  Init and dummy functions for interface with unireg
 @item
-item.cc  --  Item functions 
+item.cc  --  Item functions
 @item
-item_buff.cc  --  Buffers to save and compare item values 
+item_buff.cc  --  Buffers to save and compare item values
 @item
-item_cmpfunc.cc  --  Definition of all compare functions 
+item_cmpfunc.cc  --  Definition of all compare functions
 @item
-item_create.cc  --  Create an item. Used by lex.h. 
+item_create.cc  --  Create an item. Used by lex.h.
 @item
-item_func.cc  --  Numerical functions 
+item_func.cc  --  Numerical functions
 @item
-item_row.cc  --  Row items for comparing rows and for IN on rows 
+item_row.cc  --  Row items for comparing rows and for IN on rows
 @item
 item_sum.cc  --  Set functions (SUM, AVG, etc.)
 @item
-item_strfunc.cc  --  String functions 
+item_strfunc.cc  --  String functions
 @item
-item_subselect.cc  --  Item subselect 
+item_subselect.cc  --  Item subselect
 @item
-item_timefunc.cc  --  Date/time functions, e.g. week of year 
+item_timefunc.cc  --  Date/time functions, e.g. week of year
 @item
 item_uniq.cc  --  Empty file, here for compatibility reasons
 @item
-key.cc  --  Functions to handle keys and fields in forms 
+key.cc  --  Functions to create keys from records and compare a key to a key in a record
 @item
-lock.cc  --  Locks 
+lock.cc  --  Locks
 @item
-log.cc  --  Logs 
+log.cc  --  Logs
 @item
-log_event.cc  --  Log event 
+log_event.cc  --  Log event
 @item
-matherr.c  --  Handling overflow, underflow, etc. 
+matherr.c  --  Handling overflow, underflow, etc.
 @item
 mf_iocache.cc  --  Caching of (sequential) reads and writes
 @item
-mini_client.cc  --  Client included in server for server-server messaging
+mini_client.cc  --  Client included in server for server-server messaging; used by the replication code
 @item
-mysqld.cc  --  Source of mysqld.exe 
+mysqld.cc  --  Source of mysqld.exe; includes the main() program that starts mysqld, handling of signals and connections
 @item
-my_lock.c  --  Lock part of a file 
+my_lock.c  --  Lock part of a file (like /mysys/my_lock.c, but with timeout handling for threads)
 @item
-net_serv.cc  --  Read/write of packets on a network socket 
+net_serv.cc  --  Read/write of packets on a network socket
 @item
-nt_servc.cc  --  Initialize/register/remove an NT service 
+nt_servc.cc  --  Initialize/register/remove an NT service
 @item
 opt_ft.cc  --  Create a FT or QUICK RANGE based on a key (very short)
 @item
@@ -4671,9 +4464,9 @@ opt_sum.cc  --  Optimize functions in presence of (implied) GROUP BY
 @item
 password.c  --  Password checking
 @item
-procedure.cc  --  Procedure
+procedure.cc  --  Procedure interface, as used in SELECT * FROM Table_name PROCEDURE ANALYSE
 @item
-protocol.cc  --  Low level functions for storing data to be sent to client
+protocol.cc  --  Low level functions for PACKING data that is sent to client; actual sending done with net_serv.cc
 @item
 records.cc  --  Functions for easy reading of records, possible through a cache
 @item
@@ -4685,15 +4478,15 @@ slave.cc  --  Procedures for a slave in a master/slave (replication) relation
 @item
 spatial.cc  --  Geometry stuff (lines, points, etc.)
 @item
-sql_acl.cc  --  Functions related to ACL security
+sql_acl.cc  --  Functions related to ACL security; checks, stores, retrieves, and deletes MySQL user level privileges
 @item
-sql_analyse.cc  --  Analyse an input string (?)
+sql_analyse.cc  --  Implements the PROCEDURE analyse, which analyses a query result and returns the 'optimal' data type for each result column
 @item
 sql_base.cc  --  Basic functions needed by many modules
 @item
 sql_cache.cc  --  SQL query cache, with long comments about how caching works
 @item
-sql_class.cc  --  SQL class
+sql_class.cc  --  SQL class; implements the SQL base classes, of which THD (THREAD object) is the most important
 @item
 sql_crypt.cc  --  Encode / decode, very short
 @item
@@ -4707,63 +4500,62 @@ sql_do.cc  --  The DO statement
 @item
 sql_error.cc  --  Errors and warnings
 @item
-sql_handler.cc  --  Direct access to ISAM
+sql_handler.cc  --  Implements the HANDLER interface, which gives direct access to rows in MyISAM and InnoDB
 @item
-sql_help.cc  --  The HELP statement (if there is one?)
+sql_help.cc  --  The HELP statement
 @item
 sql_insert.cc  --  The INSERT statement
 @item
-sql_lex.cc  --  Related to lex or yacc
+sql_lex.cc  --  Does lexical analysis of a query; i.e. breaks a query string into pieces and determines the basic type (number,
+string, keyword, etc.) of each piece
 @item
-sql_list.cc  --  Only list_node_end_of_list, short 
+sql_list.cc  --  Only list_node_end_of_list, short (the rest of the list class is implemented in sql_list.h)
 @item
-sql_load.cc  --  The LOAD DATA statement? 
+sql_load.cc  --  The LOAD DATA statement
 @item
-sql_map.cc  --  Memory-mapped files? 
+sql_map.cc  --  Memory-mapped files (not yet in use)
 @item
-sql_manager.cc  --  Maintenance tasks, e.g. flushing the buffers
-periodically 
+sql_manager.cc  --  Maintenance tasks, e.g. flushing the buffers periodically
 @item
-sql_olap.cc  --  ROLLUP 
+sql_olap.cc  --  ROLLUP
 @item
-sql_parse.cc  --  Parse an SQL statement 
+sql_parse.cc  --  Parse an SQL statement; do initial checks and then jump to the function that should execute the statement
 @item
-sql_prepare.cc  --  Prepare an SQL statement 
+sql_prepare.cc  --  Prepare an SQL statement
 @item
-sql_repl.cc  --  Replication 
+sql_repl.cc  --  Replication
 @item
-sql_rename.cc  --  Rename table 
+sql_rename.cc  --  Rename table
 @item
-sql_select.cc  --  Select and join optimisation 
+sql_select.cc  --  Select and join optimisation
 @item
-sql_show.cc  --  The SHOW statement 
+sql_show.cc  --  The SHOW statement
 @item
-sql_string.cc  --  String functions: alloc, realloc, copy, convert,
-etc. 
+sql_string.cc  --  String functions: alloc, realloc, copy, convert, etc.
 @item
-sql_table.cc  --  The DROP TABLE and ALTER TABLE statements 
+sql_table.cc  --  The DROP TABLE and ALTER TABLE statements
 @item
-sql_test.cc  --  Some debugging information 
+sql_test.cc  --  Some debugging information
 @item
-sql_udf.cc  --  User-defined functions 
+sql_udf.cc  --  User-defined functions
 @item
-sql_union.cc  --  The UNION operator 
+sql_union.cc  --  The UNION operator
 @item
-sql_update.cc  --  The UPDATE statement 
+sql_update.cc  --  The UPDATE statement
 @item
-stacktrace.c  --  Display stack trace (Linux/Intel only?)
+stacktrace.c  --  Display stack trace (Linux/Intel only)
 @item
-table.cc  --  Table metadata retrieval, mostly 
+table.cc  --  Table metadata retrieval; read the table definition from a .frm file and store it in a TABLE object
 @item
-thr_malloc.cc  --  Mallocs used in threads 
+thr_malloc.cc  --  Thread-safe interface to /mysys/my_alloc.c
 @item
-time.cc  --  Date and time functions 
+time.cc  --  Date and time functions
 @item
-udf_example.cc  --  Example file of user-defined functions 
+udf_example.cc  --  Example file of user-defined functions
 @item
-uniques.cc  --  Function to handle quick removal of duplicates 
+uniques.cc  --  Function to handle quick removal of duplicates
 @item
-unireg.cc  --  Create a unireg form file from a FIELD and field-info struct 
+unireg.cc  --  Create a unireg form file (.frm) from a FIELD and field-info struct
 @end itemize
 @*@*
 
@@ -4781,17 +4573,15 @@ available all the material necessary to reproduce all the tests.
 There are five subdirectories and sub-subdirectories:
 @itemize @bullet
 @item
-\Comments  --  Comments about results from tests of Access, Adabas,
-etc. 
+\Comments  --  Comments about results from tests of Access, Adabas, etc.
 @item
-\Data\ATIS  --  .txt files containing input data for the "ATIS" tests 
+\Data\ATIS  --  .txt files containing input data for the "ATIS" tests
 @item
-\Data\Wisconsin  --  .txt files containing input data for the
-"Wisconsin" tests 
+\Data\Wisconsin  --  .txt files containing input data for the "Wisconsin" tests
 @item
-\Results  --  old test results 
+\Results  --  old test results
 @item
-\Results-win32  --  old test results from Windows 32-bit tests 
+\Results-win32  --  old test results from Windows 32-bit tests
 @end itemize
 @*@*
 
@@ -4807,7 +4597,8 @@ There is one README file and one TODO file.
 
 @subsection SSL
 
-Secure Sockets Layer.
+Secure Sockets Layer; includes an example certification one can use
+test an SSL (secure) database connection.
 @*@*
 
 This isn't a code directory. It contains a short note from Tonu Samuel
@@ -4836,7 +4627,7 @@ recent Pentium class processors, though.
 The .C files are:
 @itemize @bullet
 @item
-atof.c  --  ascii-to-float, MySQL version 
+atof.c  --  ascii-to-float, MySQL version
 @item
 bchange.c  --  short replacement routine written by Monty Widenius in
 1987 
@@ -4885,7 +4676,7 @@ r_strinstr.c  --  see if one string is within another
 @item
 str2int.c  --  convert string to integer 
 @item
-strappend.c  --  append one string to another 
+strappend.c  --  fill up a string to n characters
 @item
 strcat.c  --  concatenate strings 
 @item
@@ -4905,11 +4696,11 @@ strinstr.c  --  find string within string
 @item
 strlen.c  --  return length of string in bytes 
 @item
-strmake.c  --  move n characters, or move till end 
+strmake.c  --  create new string from old string with fixed length, append end \0 if needed
 @item
-strmov.c  --  move source to dest and return pointer to end 
+strmov.c  --  move source to dest and return pointer to end
 @item
-strnlen.c  --  return length of string, or return n 
+strnlen.c  --  return min(length of string, n)
 @item
 strnmov.c  --  move source to dest for source size, or for n bytes 
 @item
@@ -4933,9 +4724,9 @@ strxnmov.c  --  like strxmov.c but with a maximum length n
 @item
 str_test.c  --  test of all the string functions encoded in assembler 
 @item
-udiv.c  --  unsigned long divide 
+udiv.c  --  unsigned long divide, for operating systems that don't support these
 @item
-xml.c  --  read and parse XML strings 
+xml.c  --  read and parse XML strings; used to read character definition information stored in /sql/share/charsets
 @end itemize
 @*@*
 
@@ -4947,17 +4738,19 @@ members of the Intel processor family.
 
 @subsection support-files
 
-Support files.
+Files used to build MySQL on different systems.
 @*@*
 
 The files here are for building ("making") MySQL given a package
 manager, compiler, linker, and other build tools. The support files
-provide instructions and switches for the build processes.
+provide instructions and switches for the build processes. They 
+include example my.cnf files one can use as a default setup for
+MySQL.
 @*@*
 
 @subsection tests
 
-Tests in Perl.
+Tests in Perl and in C.
 @*@*
 
 These are tests that were run once to check for bugs in various
@@ -4972,7 +4765,8 @@ Tools -- well, actually, one tool.
 The only file is:
 @itemize @bullet
 @item
-mysqlmanager.c  --  A "server management daemon" by Sasha Pachev 
+mysqlmanager.c  --  A "server management daemon" by Sasha Pachev. This 
+is a tool under development and is not yet useful.
 @end itemize
 @*@*
 
@@ -4984,7 +4778,12 @@ Visual C++ Files.
 Includes this entire directory, repeated for VC++ (Windows) use.
 @*@*
 
-VC++Files has subdirectories which are copies of the main directories.
+VC++Files includes a complete environment to compile MySQL with the VC++
+compiler. To use it, just copy the files on this directory; the make_win_src_distribution.sh
+script uses these files to create a Windows source installation.
+@*@*
+
+This directory has subdirectories which are copies of the main directories.
 For example there is a subdirectory \VC++Files\heap, which has the
 same files as \heap. So for a description of the files in
 \VC++Files\heap, see the description of the files in \heap. The same
@@ -4999,54 +4798,60 @@ directories", VC++Files contains these subdirectories, which are not
 duplicates:
 @itemize @bullet
 @item
-comp_err  --  (nearly empty) 
+comp_err  --  (nearly empty)
 @item
-contrib  --  (nearly empty) 
+contrib  --  (nearly empty)
 @item
-InstallShield     script files 
+InstallShield  --  script files
 @item
-isamchk  --  (nearly empty) 
+isamchk  --  (nearly empty)
 @item
-libmysqltest  --  one small non-MySQL test program: mytest.c 
+libmysqltest  --  one small non-MySQL test program: mytest.c
 @item
-myisamchk  --  (nearly empty) 
+myisamchk  --  (nearly empty)
 @item
-myisamlog  --  (nearly empty) 
+myisamlog  --  (nearly empty)
 @item
-myisammrg  --  (nearly empty) 
+myisammrg  --  (nearly empty)
 @item
-mysqlbinlog  --  (nearly empty) 
+mysqlbinlog  --  (nearly empty)
 @item
-mysqlmanager  --  MFC foundation class files created by AppWizard 
+mysqlmanager  --  MFC foundation class files created by AppWizard
 @item
-mysqlserver  --  (nearly empty) 
+mysqlserver  --  (nearly empty)
 @item
-mysqlshutdown  --  one short program, mysqlshutdown.c 
+mysqlshutdown  --  one short program, mysqlshutdown.c
 @item
-mysqlwatch.c  --  Windows service initialization and monitoring 
+mysqlwatch.c  --  Windows service initialization and monitoring
 @item
-my_print_defaults  --  (nearly empty) 
+my_print_defaults  --  (nearly empty)
 @item
-pack_isam  --  (nearly empty) 
+pack_isam  --  (nearly empty)
 @item
-perror  --  (nearly empty) 
+perror  --  (nearly empty)
 @item
-prepare  --  (nearly empty) 
+prepare  --  (nearly empty)
 @item
-replace  --  (nearly empty) 
+replace  --  (nearly empty)
 @item
-SCCS  --  source code control system 
+SCCS  --  source code control system
 @item
-test1  --  tests connecting via X threads 
+test1  --  tests connecting via X threads
 @item
-thr_insert_test  --  (nearly empty) 
+thr_insert_test  --  (nearly empty)
 @item
 thr_test  --  one short program used to test for memory-allocation bug
 @item
-winmysqladmin  --  the winmysqladmin.exe source. machine-generated? 
+winmysqladmin  --  the winmysqladmin.exe source. machine-generated?
 @end itemize
 @*@*
 
+The "nearly empty" subdirectories noted above (e.g. comp_err and isamchk) 
+are needed because VC++ requires one directory per project (i.e. executable). 
+We are trying to keep to the MySQL standard source layout and compile only 
+to different directories.
+@*@*
+
 @subsection vio
 
 Virtual I/O Library.
@@ -5094,7 +4899,12 @@ obsolete.
 
 @subsection zlib
 
-Data compression library.
+Data compression library, used on Windows.
+@*@*
+
+zlib is a data compression library used to support the compressed
+protocol and the COMPRESS/UNCOMPRESS functions under Windows.
+On Unix, MySQL uses the system libgz.a library for this purpose.
 @*@*
 
 Zlib -- which presumably stands for "Zip Library" -- is not a MySQL