				DOSBase V.1.5 (Final)
					Manual
				---------------------

INTRODUCTION
------------           
	Wow, you decided to read the manual.  I'll try to keep the 
	information in this text file as concise and clear-cut as
	possible, but if you need further support you may submit
	questions or bug reports to DJSlakoR@hotmail.com

	DOSBase is a multifunctional list creation utility for mp3 
	collectors.  It is a win32 console application with an intuitive
	DOS interface.  It is intended to be used by collectors who name
	their mp3 files with a particular naming convention (such as
	title - artist.mp3  or  (title)_artist.mp3.  DOSBase extracts
	all information and creates nice looking TXT files or HTML 
	documents (refer to example.txt & example.html).  
           
	Features:

		* ASCII Text File Creation
			- User defined column order
			- Ability to sort by title or artist
              
		* HTML Document Creation
			- A-Z Navigation Bar for quick hyperlinks to letters
			- Ability to sort by title or artist
			- Easily Addable To Your Homepage!
              
		* Binary DATabase file creation for future reloading of lists
		(This way if for example you have a list with 20+ CD-Rs,
		you won't have to rescan every cd to add 1 new CD-R to your list)             

		* "Smart Add" (DOSBase doesn't add identical entries more
		than one time)

		* Recursion Of Subdirectories
			- Easily scan & rescan entire harddrives for mp3s
              
		* File Name Parsing (including user defined strings)
		Also support for multiple naming conventions. Simply
		rescan the specified locations with the new search
		pattern and let DOSBase do the rest

		* Underscore Removal 
              
		* MPEG Frame Header Decoding
              
		* Long file-name support...So far as to not require those
		nasty "" marks around paths and files.  Just type away.

		* 100% Open Source Distributed Under The Terms Of The GPL
		(General Public License), refer to license.txt. 
		
		* Source Code Available At http://revolutionaudio.dhs.org/dosbase


BASIC USAGE
-----------
	Before you can create nifty ASCII files or HTML documents, you
	must first create a list.  This is done by pressing F1, then
	following the onscreen instructions.  

	After you have added entries to the list (as displayed by the 
	"total counter" at the top of the interface), you may create
	ASCII text files or HTML documents by choosing the respective
	option's function key.  Again, these features are very easy
	to use.

	Next is the ability to save your lists for future use.
	With this feature, if you have previously made a list
	(say of 30 mp3 cds), you'll no longer have to rescan every
	single cd just to add to your currently existing list. 
	Once you have a list created, simply chose "write DAT" to
	save your list as a DOSBase .DAT file (a very simple non-compressed
	storage format). Then in the future when you need to reload your list
	simply choose "read DAT"!  It's that simple.  All sorting, etc
	still works very intuitively, so if you have "I wonder if I..."
	questions, the answer is probably "yes." :-)
 
	Note also that all input dialogs are fully escapable. If at any point
	you wish to cancel the operation you are currently on, simply press
	"ESC". 	

	IMPORTANT:
	For all dialogs requesting a filename (file to save to, file to read
	from, etc) long filenames may be used (along with spaces). Unlike many
	other software packages available, this software does NOT require the 
	usage of quotes around long filenames, in fact, it won't work. Be aware
	of this fact.

TIPS
----
	If you collect mp3s with more than one naming convention, 
	simply use "Change Format" to change the current search format,
	then rescan directories and DOSBase will filter out the correct
	files.  This is a fairly useful feature.  

	DOSBase is so easy to use, writing a manual for it is almost as
	simple as saying "just use the program."  However, one feature
	that requires some special attention is the use of user defined
	search substrings.   This would be used if the user named his
	files with a convention not supported by DOSBase.

	Example:  The user's naming convention is such:

	(Artist)-*-(Title).mp3

	True, a gay naming convention... but purely for example.

	In order to define the substrings so DOSBase can extrapolate
	needed information the user has to define 3 substrings:

	Substring 1 - Characters occuring before artist 
			(or title depending on the order)
              
	Substring 2 - Characters between artist & title

	Substring 3 - Characters after title (not including .mp3)
			(or artist depending on the order)

	And finally, the user must define the order in which the 
	title and artist substrings appear.  

	So, for our example:  (Artist)-*-(Title).mp3 ...

	Substring 1: (
	Substring 2: )-*-(
	Substring 3: )
        Order      : Artist First

	Another example: Title - Arist.mp3 (what I personally use)

	Substring 1:   	(nothing comes before Title, simply hit "enter")
	Substring 2:  - 	(note the space on each side of "-" making " - ")
	Substring 3:	(again, nothing comes after Artist)
	Order      : Title First

	It's as simple as that folks.  

           
OPEN SOURCE FREEWARE
--------------------
	DOSBase is freeware and may be used and distributed as much as you
	so desire.  However, no cost may be placed on DOSBase including any
	usage of it. If you enjoy using this software or you find it useful,
	please drop me an e-mail and let me know you like it! Feedback keeps
	developers happy, and it is rewarding! DJSlakoR@hotmail.com

	Refer to license.txt for license agreement.

	Please feel free to distribute this software as much as you can!	
	However, charging a fee for distribution is STRICTLY prohibited. 

	For developers: PLEASE notify me of any new features you add to the 
	source-code as I will incorporate your changes in future releases
	(if changes are submitted, otherwise this is the final release).
	Note also as the GPL mentions, if you use any or all parts of this
	sourcecode in your own work you must explicitly site reference to the
	original author, Clint Kennedy. 


IDEAS CONSIDERED (FOR DEVELOPERS)
---------------------------------
	Considering the final release (1.5) is open-source and distributed 
	under the terms of the GPL, here are a few features I planned on
	doing, but never got around to it. Perhaps a developer with more time
	would like to implement these (or other) features and produce DOSBase 1.6.
	Features NOT implemented (but were considered):

	***  ID3 Tag Support & Features
		- Mass ID3 De-tag
		- Generation of ID3 Tags Based On Parsed Filename
		- Sort By Artist/Title Stored In ID3 Tag

	***  Playing Time Column In Text File Generation (code adabptable
		from the MPEG Frame Header Decoder)

	***  Searching Capabilities

	***  Resort Based On New Sort Option (see setSort() in dialogs.c)

	If e-mails / feedback requests are great enough, I will add these
	features myself when I get a chance, but I doubt this will happen.
	Console programs aren't too popular these days. :-) 


KNOWN ISSUES:
-------------

Problem:	Function Keys seem to not work, or certain function keys cause
		DOSBase to become an inactive window.

Solution:	In 99.99% of the cases, this problem occurs due to a Windows
		HotKey being mapped to one of the function keys.  Since the
		interface for DOSBase is function-key driven, if you wish to
		use it, you must disable all function-key related HotKeys.

Problem:	When scanning a certain directory for mp3s, I receive an illegal
		operation or General Protection Fault and DOSBase terminates or
		locks up.

Solution:	I have only encountered this issue one time.  The dynamic memory
		allocation procedures in DOSBase were designed very carefully.
		Several error-checking routines are also performed when DOSBase
		adds entries.  The chances of a legitimate memory leak existing are
		slim to none.  Nevertheless, at one time problems were narrowed down
		to a single file, which was named correctly, yet would lock up if
		that file was considered in the scan.  I have absolutely no idea
		what would cause this error (probably internal to findnext()), but
		if you encounter it...... I wouldn't be completely suprised. 

		*Note: As of release 1.5 Final, the code was rewritten to utilize
		win32api function calls (as opposed to compiler-specific utility 
		functions), so this problem should most certainly be gone.


AUTHOR
------
I wrote this program purely for my own need when mp3 audio first came about,
so if you don't like it, don't use it! It turned out to be a nifty utility,
and I figure someone out there might be looking for the same functionality.
I agree, the console interface is rather antiquated, but when I originally wrote
the software I did not yet know Windows programming. Now, I do. :-)  
For the curious, the codebase was written in ANSI C and originally compiled
with the Borland C++ compiler. The source has recently been updated and
is now compiled under Visual C++ 6.0, although it should compile on any win32
capable compiler.

If you like this program, please respond to me at DJSlakoR@hotmail.com.  I'd
love to get some feedback!!!

Shoutouts to Mavroxur for ideas and beta testing (summer of 1999).
Shoutouts to Snicker for adamantly bashing the "blah, boring" DOS interface. :-)

http://revolutionaudio.dhs.org/dosbase

/* EOF :: DJSlakoR */
