NAME:
  mysqldoc
 PURPOSE:   (one line only)
  Build a documentation file from internal mySQL documentation.
 DESCRIPTION:
 CATEGORY:
  Database
 CALLING SEQUENCE:
  mysqldoc,lun,table,outfile
 INPUTS:
     lun     - The logical unit of the pipe (previously opened by openmysql).
                   -or-
               String with the name of the database to access.
                 If string is supplied then the database is opened
                 at the start and closed at the end.
     table   - String containing name of mySQL table to document.
                  Default is to process all tables in the database.
                  If default is used, then outfile is ignored.
                  If processing the entire database, then an extra file
                  named "documentation.html" is created with a master index
                  for the entire database.
     outfile - String with file name for output (default=table+'.html')
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
     DBNAME  - String with name of the database being examined.
                  Default='' if the database is already open.  If the
                  database name is provided in lun then the default is
                  to use the value of lun.
     OUTDIR  - String with the name of the directory to put the output files.
                  Default=current directory
 OUTPUTS:
     All output is to the output file.
 KEYWORD OUTPUT PARAMETERS:
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
   Requires access to a MySQL server (established by
   use of openmysql) as well as valid permissions for reading
   the database.

   I don't yet know how to test and make sure the table sought actually
     exists in the database.  For the moment, if you give a non-existent
     table, the program will crash most unpleasantly.
 PROCEDURE:

   Special information:
     The documentation for a database resides in the "doc" table.
     This table must be defined similar to this:
       +-----------+-------------+------+-----+---------+-------+
       | Field     | Type        | Null | Key | Default | Extra |
       +-----------+-------------+------+-----+---------+-------+
       | tablename | varchar(20) | YES  |     | NULL    |       |
       | field     | varchar(20) | YES  |     | NULL    |       |
       | units     | varchar(20) | YES  |     | NULL    |       |
       | source    | varchar(80) | YES  |     | NULL    |       |
       | info      | text        | YES  |     | NULL    |       |
       +-----------+-------------+------+-----+---------+-------+
     The exact lengths of the first four fields is not critical.
     For a normal field in a database you will provide the tablename
     and field along with its information in units,source,info.  An
     indirect reference can be imbedded in the info field and looks
     like <> where key is replaced by a short string.  This string
     will be searched for under the "field" field where tablename is
     set to NULL.  The text found will replace <> in the output
     html file.  The general description of a table is stored in a
     record with tablename="table" and field is NULL.  For these records
     "source" will contain a short description that will populate the
     master summary table and "info" will contain a detailed but general
     description of the purpose and usage for the table.  There is also
     one special record per doc database where tablename and field are
     both NULL.  In this record, the info field will contain a general
     description of the entire database which will appear on the master
     index page.

     In general, units, source, and info will all be filled in for every
     database field.  Sometimes units make no sense for a field.  In this
     case put [[none]] in the field to leave the units blank.  NULL is
     reserved to indicate that no information has yet been provided.

     If you want to suppress a documentation page for a table (ie., one
     that is for internal testing purposes only), then set source to
     xxHIDExx in the record where tablename="table" and field is NULL.
   
 MODIFICATION HISTORY:
   2005/01/19, Written by Marc W. Buie, Lowell Observatory
   2005/02/01, MWB, special handling for enum types.
   2005/10/10, MWB, added call to mysqldocscan validator
   2017/12/26, MWB, cosmetic changes to html output