Updated README with example for OS X

README.rst

@@ -1,7 +1,8 @@
 ATRCopy
 =======
 
-Support Atari 8-bit emulator disk images in pyfilesystem
+Utilities to list files on and extract files from Atari 8-bit emulator disk
+images.  Eventually, I hope to add support for these images to pyfilesystem.
 
 References
 ==========
@@ -10,3 +11,97 @@ References
 * http://atari.kensclassics.org/dos.htm
 * http://www.crowcastle.net/preston/atari/
 * http://www.atarimax.com/jindroush.atari.org/afmtatr.html
+
+
+Example Usage
+=============
+
+$ python atrcopy.py GAMES1.ATR -x -n --dry-run --xex
+File #0 : *DOS     SYS  039 : DRY_RUN: skipping system file
+File #1 : *MINER2       138 : DRY_RUN: copying to MINER2.XEX
+File #2 : *DEFENDER     132 : DRY_RUN: copying to DEFENDER.XEX
+File #3 : *CENTIPEDE    045 : DRY_RUN: copying to CENTIPEDE.XEX
+File #4 : *GALAXIAN     066 : DRY_RUN: copying to GALAXIAN.XEX
+File #5 : *AUTORUN SYS  005 : DRY_RUN: skipping system file
+File #6 : *DIGDUG       133 : DRY_RUN: copying to DIGDUG.XEX
+File #7 : *ANTEATER     066 : DRY_RUN: copying to ANTEATER.XEX
+File #8 : *ASTEROIDS    066 : DRY_RUN: copying to ASTEROIDS.XEX
+
+
+Example on Mac OS X
+-------------------
+
+OS X supplies python with the operating system so you shouldn't need to install
+a framework version from python.org.
+
+To prevent overwriting important system files, it's best to create a working
+folder: a new empty folder somewhere and do all your testing in that folder.
+For this example, create a folder called `atrtest` in your Documents folder. Put a few `.ATR` images in this directory as well
+
+Download or copy the file atrcopy.py and put the Documents/atrtest folder.
+folder.
+
+Since this is a command line programe, you must start a Terminal by double
+clicking on Terminal.app in the Applications/Utilities folder in the Finder.
+When Terminal opens, it will put you in your home folder.  Go do the atrtest
+folder by typing::
+
+    cd Documents/atrtest
+
+You should see the file `atrcopy.py` as well as the other ATR images you placed
+in this directory by using the command::
+
+    ls -l *
+
+For example, you might see::
+
+    mac:~/Documents/atrtest $ ls -l
+    -rw-r--r-- 1 rob  staff  92176 May 18 21:57 GAMES1.ATR
+    -rwxr-xr-x 1 rob  staff   8154 May 18 22:36 atrcopy.py*
+
+Now, run the program by typing `python atrcopy.py YOURFILE.ATR` and you should
+see the contents of the ATR image in the familiar Atari DOS format::
+
+    mac:~/Documents/atrtest $ python atrcopy.py GAMES1.ATR
+    GAMES1.ATR
+    File #0 : *DOS     SYS  039 
+    File #1 : *MINER2       138 
+    File #2 : *DEFENDER     132 
+    File #3 : *CENTIPEDE    045 
+    File #4 : *GALAXIAN     066 
+    File #5 : *AUTORUN SYS  005 
+    File #6 : *DIGDUG       133 
+    File #7 : *ANTEATER     066 
+    File #8 : *ASTEROIDS    066 
+
+Without any additional arguments, it will not extract files.  To actually
+pull the files out of the ATR image, you need to specify the -x command line
+argument::
+
+    mac:~/Documents/atrtest $ python atrcopy.py -x GAMES1.ATR
+    GAMES1.ATR
+    File #0 : *DOS     SYS  039 : copying to DOS.SYS
+    File #1 : *MINER2       138 : copying to MINER2
+    File #2 : *DEFENDER     132 : copying to DEFENDER
+    File #3 : *CENTIPEDE    045 : copying to CENTIPED.E
+    File #4 : *GALAXIAN     066 : copying to GALAXIAN
+    File #5 : *AUTORUN SYS  005 : copying to AUTORUN.SYS
+    File #6 : *DIGDUG       133 : copying to DIGDUG
+    File #7 : *ANTEATER     066 : copying to ANTEATER
+    File #8 : *ASTEROIDS    066 : copying to ASTEROID.S
+
+There are other flags, like the `-l` flag to covert to lower case, and the
+`--xex` flag to add the `.XEX` extension to the filename, and `-n` to skip DOS
+files.  So a full example might be::
+
+    mac:~/Documents/atrtest $ python atrcopy.py -n -l -x --xex GAMES1.ATR
+    GAMES1.ATR
+    File #0 : *DOS     SYS  039 : skipping system file dos.sys
+    File #1 : *MINER2       138 : copying to miner2.xex
+    File #2 : *DEFENDER     132 : copying to defender.xex
+    File #3 : *CENTIPEDE    045 : copying to centipede.xex
+    File #4 : *GALAXIAN     066 : copying to galaxian.xex
+    File #5 : *AUTORUN SYS  005 : skipping system file autorun.sys
+    File #6 : *DIGDUG       133 : copying to digdug.xex
+    File #7 : *ANTEATER     066 : copying to anteater.xex
+    File #8 : *ASTEROIDS    066 : copying to asteroids.xex