File	Date	Author	Commit
src	2010-11-30	Steve Perkins	[6f0d29] Merge branch 'master' of ssh://steveperkins.git...
README.TXT	2010-11-30	Steve Perkins	[6f0d29] Merge branch 'master' of ssh://steveperkins.git...

Read Me

CREDITS / LICENSE
-----------------
Mediasync Utility, version 1.0
Copyright 2010, Steve D. Perkins

This software is covered by version 2 of the GNU Public License.  See http://www.gnu.org/licenses/gpl-2.0.html.



INTRO
-----
This is a small Tcl/Tk script that I wrote for the purpose of managing files between media device and some 
larger archive of media files.  A secondary purpose was to scrape the rust off my Tcl/Tk scripting skills, and 
create my first custom Tk widget (checkboxtree-1.0.tm).


DESCRIPTION / USAGE
-------------------
I am a big fan of the Rockbox open source firmware for portable media devices (http://www.rockbox.org).  Rather 
than requiring me to organize my device around ID3 and other metatags, it allows me to navigate the files on my 
device as a traditional filesystem,

The downside is that for managing a library of media files, and keeping the device in sync with it, most of the 
available software is metatag-based.  There are some general-purpose tools for keeping two folders in sync, but 
I couldn't find anything which quite met these requirements:

   * Selective sync -- The tool should not assume that the user wants ALL the library content present 
                       on the device at all times.  Only selected content will be copied to the device, 
                       and it will be removed from the device when de-selected.
                       
   * Delete safety  -- The tool should err on the side of safety, and never allow content to be completely 
                       destroyed.  The tool should not be able to remove content from the device unless 
                       content is already backed-up in the archive.  The tool should not be able to remove 
                       content from from the archive at all.
                       
   * Portability    -- The tool should require zero-installation, such that it can be carried and executed 
                       from the portable device.  Any configuration file(s) should be saved in the same 
                       directory as the Tcl script... rather than making any alterations to system 
                       directories, or the Windows registry, or anything else.
                       
The tool is intended to be used in a two-step process, and the user interface consists of two tabs representing 
these steps.  

The first step is to sync the archive from the device.  This means that if any new content is found on the device, 
which has not yet been backed-up in the archive, the user will have the option to archive that content.  After the 
user clicks the "Scan for New Files on Device" button, any new content on the device will be presented with a 
checkbox beside each file.  When the user then clicks the "Archive Selected Files" button, checkmarked files will
be copied from the device to the archive.  Non-checkmarked will be ignored altogether.

The second step is to sync the device from the archive.  This means that the user will have the option to copy
different file(s) from the archive to the device... and/or remove file(s) from the device, so long as they are 
archived.  The "Refresh Archive View" button will present all the content in the archive, with checkmarks beside 
the files which are already on the device.  When the user clicks the "Sync Device to Selected Files" button... any 
newly-checkmarked files will be copied to the device, and any un-checkmarked items will be removed from the device.

Common to both tabs are fields for declaring the root directory of the device and the archive.  For a Rockbox
device mounted in Windows as drive letter "E:", the value for the device would be "E:\Music".  These directory
locations are saved to a properties file, stored in the same location from which the script was executed, and 
re-loaded the next time the script is run.