This document demonstrates the use of cpShuffleSature through various
examples

You may, for example, want to know the effect (the option is '-d', which
means "dummy mode") of an attempt to random copy some files named '*.ogg'
(-f '\.ogg$') which are somewhere under '/music' (-s '/music') into the
/somewhere/target directory :
cpShuffleSature -d -f '\.ogg$' -s '/music' -t /somewhere/target 
Note : '-s' stands for 'source directory' and '-t' means 'target
directory'. One may also use the corresponding 'long forms' which are
'--source' and '--target'
Any subdirectory of a source directory is also explored

To randomly copy into /mnt/usb all '*.mp3', '*.mpeg' and '*.mpg' which are
under '/music' then under /pic/, storing no more than 30MB into any
target directory (-m 30M):
cpShuffleSature -t /mnt/usb -f '\.mp(3|e?g)$' -s '/music' -s '/pic' -m 30M

Beware:
 - the selection filter is a Perl regular expression

 - units (for example the 'M' in 'MB') are expressed with respect to the
   International System of Units (SI), therefore 'M' is 1e6 (not 2e20)
   bytes

 - the Nth 'source' directory stated (-s) will only be explored if the
   (N-1)th did not lead to an end of the process (for example by target
   saturation).  in other words: when multiple source directories are
   stated the whole process (file selection, shuffling then copy) is done
   on files selected in the first source, then it is done for the second,
   then it is done from the third (and so on).  we DO NOT select all files
   in all source directories THEN process them!

 - -s is cumulative, therefore "-s /music -s /pic" and "-s /music,/pic" are
    equivalent

To randomly select files under '/home/music', avoiding sparse files (for
example to copy complete albums) and therefore copy all files of the
directory storing any of them (-w, for 'whole'), let at least 20GB+500KB
bytes available (-a '20G 500K') on the target disk, without copying more
than half a Go of source data (-c .5G) and mount then unmount the target
directory (-p, for 'player') before then after processing:
cpShuffleSature -s '/home/music' -t /mnt/usb -w -a '20G 500K' -c .5G -p
Note: -p is only available under Unix

A history file stores informations about copied files accross runs, to
ensure that no file is selected more often than another. It is named
~/.cpShuffleSature_history. Just delete it to reset the counters.

You can always add or delete files to your source(s) directory. To avoid
seing any new one of them being overcopied just after his arrival (to
'compensate' for his 'lateness') it is inserted in history with an somewhat
average value for the field 'VCopy' (Virtual Number of Copies already
done).

To list the history file content:
cpShuffleSature --showhistory
Note: 'cpShuffleSature --sh' is equivalent because the 'sufficient' prefix
of any 'long form' of an option is understood.

To read (use) but not write (modify) the history file during a given run
use '--ignorehistory' (or '--noremember')
To completely ignore the history use the '--ignorehistory=2' (or '-0')

Any source directory which name is suffixed .cpsslock will be ignored.
Furthermore: a given source directory named D will be ignored if a target
directory named "D.cpsslock" exists. The suffix used can be defined thru
the "--lockindicator" parameter.

To only produce the names of all selected files (option '-n', long form:
'--names-only'), forbid selection of any files already selected less than
2.5 days ago (-days 2.5) and select at most 40 files:
cpShuffleSature -s /music -t /mnt/usb -n -days 2.5 --maxfiles 40
Note: one may use '--mintime AmountOfTimeInSeconds'

To somewhat bias the selection of the files which will be processed you can
use '--prefer SomeThing'. 'SomeThing' is a case insensitive regexp and will
be applied to the complete filenames. To absolutely 'prefer' the content of
a directory please name it as the first source (-s).