MySQL Bugs: #19822: README.txt in the menagerie database download difficult to follow

Bug #19822	README.txt in the menagerie database download difficult to follow
Submitted:	15 May 2006 16:04	Modified:	24 May 2006 15:37
Reporter:	Steven Ginzbarg	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S2 (Serious)
Version:	MySql 5.0	OS:	Windows (WindowsXP)
Assigned to:	Paul DuBois	CPU Architecture:	Any

Description:
I found the README.txt in the menagerie database download difficult to follow. Here is my revised version for consideration.

In what situations would one want to use one's command interpreter rather than the MySQL program? It seems tedious to have to execute mysql and supply connection parameters for each command. 

README.txt 

This directory contains files that can be used to set up the menagerie database that is used in the tutorial chapter of the MySQL Reference Manual. 

First, you should create the database. In the mysql program, issue this statement: 

mysql> CREATE DATABASE menagerie; 

The examples below assume that you have unzipped menagerie.zip or menagerie.tar.gz to the C: drive creating a temporary folder C:\menagerie containing the downloaded files. 

To create the pet table: 

mysql> use menagerie 
Database changed 
mysql> source c:/menagerie/cr_pet_tbl.sql 

(Note the use of forward slashes for specifying paths at the mysql> prompt.) 

To load the pet table, use this command in mysql: 

mysql> LOAD DATA LOCAL INFILE 'c:/menagerie/pet.txt' INTO TABLE pet; 

To add Puffball's record, use this command: 

mysql> source c:/menagerie/ins_puff_rec.sql 

To create the event table: 

mysql> source c:/menagerie/cr_event_tbl.sql 

To load the event table, use this command: 

mysql> LOAD DATA LOCAL INFILE 'c:/menagerie/event.txt' INTO TABLE event; 

The commands above were entered in the MySQL program. If you have created an account for yourself and granted yourself privileges (see http://dev.mysql.com/doc/refman/5.0/en/adding-users.html) you can also set up the menagerie database by using your command interpreter. This will require executing mysql.exe for each command. If you set the PATH environmental variable (search your operating system's help for 'environmental variable') to include the path of mysql.exe you will be able to execute mysql commands from any directory. 

To set up the menagerie database using your command interpreter: 

(Note, the ‘shell>’ is used to indicate any command prompt, e.g. c:\> or c:\temp>.) 

Start the mysql program. 

shell>mysql <connection parameters> 
mysql> 

(Note that for the mysql and mysqlimport commands, you must supply any connection parameters necessary (host, user, password) on the command line after ‘mysql’. For example, your command might be 

shell>mysql –-user=username –password=somepass 
mysql> 

Create the database. In the mysql program, issue 
this statement: 

mysql> CREATE DATABASE menagerie; 

Quit the mysql program. 
mysql>quit 
Bye 

shell> 

To create the pet table: 

shell>mysql <connection parameters> menagerie < c:/menagerie/cr_pet_tbl.sql 

To load the pet table, use the following command: 

shell> mysqlimport <connection parameters> menagerie c:/menagerie/pet.txt 

(shell> mysql <connection parameters> menagerie < c:/menagerie/load_pet_tbl.sql gives an error because the sql file contains a reference to pet.txt w/o a path.) 

To add Puffball's record, use this command: 

shell> mysql <connection parameters> menagerie < c:/menagerie/ins_puff_rec.sql 

To create the event table: 

shell> mysql <connection parameters> menagerie < c:/menagerie/cr_event_tbl.sql 

To load the event table, use this command: 

shell> mysqlimport <connection parameters> menagerie c:/menagerie/event.txt

How to repeat:
Have a novice try to follow the instructions in the ReadMe.txt file included in menagerie database download

Suggested fix:
Revise the ReadMe.txt file included in menagerie database download

We're sorry, but the bug system is not the appropriate forum for 
asking help on using MySQL products. Your problem is not the result 
of a bug.

Support on using our products is available both free in our forums
at http://forums.mysql.com and for a reasonable fee direct from our
skilled support engineers at http://www.mysql.com/support/

Thank you for your interest in MySQL.

Additional info:

"shell>" in the text means cmd.exe command line window on Windows. To enter mysql and other command you need to use command line window, with command interpreter, that is, "shell". I see nothing difficult in the actions described.

This is not a request for support. Where is the appropriate place to report the problem? If MySQL is interested in improving the service it offers there should be an avenue. (The problem did include an actual bug since one of the commands did not work.)

OK. So, README.txt should be made more clear, and either load_pet_tbl.sql should include a full pathname, or, better, README.txt should contain explanation about the need to cd to the appropriate directory.

I'll mark this report as a verified documentation request.

Thank you for your bug report. This issue has been addressed in the
documentation. The updated documentation will appear on our website
shortly, and will be included in the next release of the relevant
product(s).

Additional info:

Note: Regarding one of the commands not working: It's
assumed that you execute the commands in the directory
where the menagerie files are located.  I'll make this
assumption explicit in the README.txt file.