Detox README

-----------------------------------------------------------------------------
                                   OVERVIEW
-----------------------------------------------------------------------------

detox is a program that renames files to make them easier to work with under
Unix and related operating systems.  Spaces and various other unsafe
characters (such as "$") get replaced with "_".  ISO 8859-1 (Latin-1)
characters can be replaced as well, as can UTF-8 characters.  More details
are contained in the detox.1 man page.

This is a BETA release.  Please watch for falling bits.

-----------------------------------------------------------------------------
                           COMPILATION INSTRUCTIONS
-----------------------------------------------------------------------------

Compilation:
	./configure
	make

Installation:
	make install

Installation that overwrites config files and translation tables:
	make force-install

-----------------------------------------------------------------------------
                              COMPILATION NOTES
-----------------------------------------------------------------------------

Ensure that the path to lex/yacc (or an equivalent) is in your $PATH
environmental variable.  For instance, under Solaris, you may need to add
/usr/ccs/bin to your path to get detox to compile:
	export PATH=${PATH}:/usr/ccs/bin

     -------------------------------------------------------------------

To get detox working with long options on Darwin or Solaris (or any other OS
without getopt_long in its C library), I've included support for libpopt.
Install libpopt and configure with the following:
	./configure --with-popt

If you've installed libpopt in a directory other than /usr, which is likely,
you'll want to specify the base path to libpopt.  So, if popt.h is in
/usr/local/include, you'll run configure like so:
	./configure --with-popt=/usr/local

-----------------------------------------------------------------------------
                                RUNTIME NOTES
-----------------------------------------------------------------------------

The most important option to learn is -n, aka --dry-run.  This will let you
run detox without actually changing any files, so that you can get an idea
of what detox is all about.

The simplest way to run detox is to just run it on a directory containing
files that need work:
	detox xfer_files/

You can also just to specify the filename:
	detox my\ bad\ file.txt

You can also specify recursion (this works best on directories):
	detox -r /music/transferred_from_elsewhere/

-----------------------------------------------------------------------------
                                 OTHER NOTES
-----------------------------------------------------------------------------

This project was initially developed under Linux (RedHat 7.x, 8.x), and is
presently being maintained under the FreeBSD 5.x series.  If you run into any
problems with installation or operation please feel free to contact me.

-----------------------------------------------------------------------------
                                     BUGS
-----------------------------------------------------------------------------

None known at the moment.

-----------------------------------------------------------------------------
	  SPECIAL THANKS (TO CONTRIBUTORS OF CODE AND SUGGESTIONS)
-----------------------------------------------------------------------------

Many thanks to Miguel Angelo Rozsas for suggesting UTF-8 support and his
valuable input following that suggestion.  This change helped introduce
translation tables into detox.

Ciaran McCreesh put together a package for Gentoo (rock!), submitted a patch
to add a prefix onto install paths (for package builds) and helped fix
parallel builds.

Lou Alfonso for suggesting that the safe filter be controlled through a
table so that it can be tuned easily.

Christoph Wegscheider noticed that the install script was installing
everything 755, for pointing out that not everyone has lex or yacc, and for
his input on how umlauts should be converted.

Gerg Thor informed me that characters on the PowerPC platform are unsigned
by default and that the libpopt parser was rolling into an infinite loop as
a result.

Jon Amundsen pointed out that the lowercase converting sequence was only
really working on case-insensitive filesystems.

zero_dogg from sourceforget.net suggested adding the ability to prevent
certain files from being translated.

rsnemmen from sourceforge.net pointed out a bug in the way directories are
handled when passed in from the command line.

-----------------------------------------------------------------------------
                                    THANKS
-----------------------------------------------------------------------------

Eric S. Raymond for his work on "The Art of UNIX Programming"

http://www.bbsinc.com/iso8859.html for their help in building a complete list
of Latin-1 translations.

SourceForge.net for their generous hosting of this and many other projects.

http://en.wikipedia.org/wiki/UTF-8 for its help with explaining UTF-8.

Data Structures Using C - Tenenbaum, Langsam and Augenstein - for their help
with hashes.

Paul Oakenfold for his unbelievable mixes.  Version 1.0.0 was developed with
the help of his Great Wall mix.

-----------------------------------------------------------------------------
                                   CONTACT
-----------------------------------------------------------------------------

Doug Harple [purgedhalo at users.sourceforge.net]