IcqScm Files

                    ================================================
                        icqscm - ICQ Sound Scheme Archive Editor
                    ================================================

                      Queries to: renemann@users.sourceforge.net
                      Patches to: icqscm-devel@lists.sourceforge.net
                          (Subscribe on sourceforge project page)

                       URL: http://sourceforge.net/projects/icqscm
                    ================================================



1. How to get started quickly:
==============================

icqscm is using Python's Distutils so make sure you have installed a recent Python version. Anything equal or greater than 1.6 will do.

Note: Window's support for pure Python scripts is somewhat awkward. However, if you are familiar with the command line on windows you will find ways to create a batch file that wraps the command line used for starting icqscm.py.



1.1 LINUX / UNIX
----------------

Assumed that you have unpacked the archive into ~/icqscm-1.0
cd ~/icqscm-1.0
su
python setup.py install
logout  # root

Now type
icqscm.py    # [ENTER]

and you will get the usage info which contains useful examples that sould get you started very quickly. icqscm.py's command line options are VERY similar to the ones tar uses.



1.2 Windows 
-----------

NOTE:  

All installation methods for Windows create the main python script "icqscm.py" in the "Scripts" directory of your Python installation. If you run Python 2.2 this would be "C:\python22\scripts\". In this document I will refer to C:\python22\scripts; change this to C:\python21\scripts or C:\python23\scripts, according to the version of Python that you have installed.

 

1.2.1 Using the executable installer:
-------------------------------------

The executable installer (eg icqscm-1.0.win32.exe) provides a graphical interface for installing icqscm.py.
Start the downloaded executable by doubleclicking its icon. Follow the instructions on screen, this should be fairly easy.

Open a command line session ("DOS-box"). Type
python C:\python22\scripts\icqscm.py  [ENTER]

and you will get the usage info which contains useful examples that sould get you started very quickly. icqscm.py's command line options are VERY similar to the ones tar uses.



1.2.2 Using the zipped source distribution for Windows
------------------------------------------------------ 

Using the zipped source distribution for Windows (eg icqscm-1.0.zip) is only slightly harder compared to the GUI install:

First unzip the archive. Then open a command shell and "cd" to the contents of the archive, where setup.py is located. Eg:
cd C:\tmp\icqscm-1.0

Enter:
python setup.py install

After that verify the install by typing:
python C:\python22\scripts\icqscm.py  [ENTER]

and you will get the usage info which contains useful examples that sould get you started very quickly. icqscm.py's command line options are VERY similar to the ones tar uses.




2. Example: Extract WAVE files from a sound scheme
==================================================



2.1 LINUX / UNIX
----------------

Assumed you have downloaded an ICQ sound scheme named coolsounds.scm into ~/download/.

cd ~/download
mkdir coolsounds
icqscm.py -tvf coolsounds.scm
# the above command will list the WAVE files contained in the sound scheme archive.
icqscm.py -C ./coolsounds -xvf coolsounds.scm

Now all WAVE files have been extracted into the directory ~/download/coolsounds.



2.2 Windows
-----------

Assumed you have downloaded an ICQ sound scheme named winsounds.scm into C:\downloads\

Fire up a command shell ("DOS-box") and type:

cd C:\downloads
python icqscm.py -tvf winsounds.scm

(You will be presented a list of all the WAVE files contained in the .scm file)

Now type:

md winsounds
python icqscm.py -C winsounds -xvf winsounds.scm

Now all WAVE files have been extracted into the subfolder "winsounds" in C:\download.



3. Advanced Usage
=================

Icqscm.py's usage text will have to suffice for now...

Usage: icqscm.py [OPTION]... [FILE]...

Examples:
icqscm.py -tf my.scm           # lists all files in my.scm
icqscm.py -xf my.scm Email.wav # extracts Email.wav from my.scm
icqscm.py -C /tmp -xf my.scm   # extracts all files from my.scm into /tmp
icqscm.py -cf my.scm *.wav     # creates my.scm and adds all WAVE files
icqscm.py -uf my.scm Email.wav # updates Email.wav in my.scm
icqscm.py --delete -f my.scm EMail.wav # removes EMail.wav from my.scm

Main operation mode:
  -t, --list      list the contents of a scheme archive
  -x, --extract   extract files from a scheme archive
  -c, --create    create a new scheme archive
  -r, --append    append files to the end of a scheme archive
                  Note: custom positions can be specified, see 'Local file
                        selection'
  -u, --update    replace file in the scheme archive by a local file
  -D, --delete    delete from the archive

Operation modifiers:
  -O, --to-stdout      extract files to standard output

Archive file selection:
  -f, --file=ARCHIVE   use archive file ARCHIVE

Local file selection:
  -C, --directory=DIR   change to directory DIR

  @n                    refers to file in archive at position n; can be used as
                        alias for filenames.
                        0 < n < (numberOfFilesInArchive + 1)
                        This is useful if one WAV is used multiple times.
                        Example:
                        icqscm.py -cvf my.scm one.wav one.wav one.wav
                        # my.scm contains one.wav, one.wav, and one.wav
                        icqscm.py -Dvf my.scm @2 @3
                        # my.scm now only contains one.wav

  @n:filename           only for -u/--update and -r/--append
                        same as @n but additionally specifies a new filename
                        Note: When "appending", the new file will be inserted
                              at position n. That means, in this case, the
                              file will be PREpended, actually.

                        Example for updating:
                        icqscm.py -cvf my.scm one.wav one.wav one.wav
                        # my.scm contains one.wav, one.wav, and one.wav
                        icqscm.py -uvf my.scm @2:two.wav @3:three.wav
                        # my.scm now contains one.wav, two.wav, and three.wav

                        Example for inserting:
                        icqscm.py -cvf my.scm two.wav
                        icqscm.py -rvf my.scm @1:one.wav

Informative output:
  -v, --verbose         verbosely list files processed