ReadMe for dsktool-5.1-Win32.zip
--------------------------------

Introduction:
-------------

dsktool.rb is a command line tool + libraries (all in ruby) written by Jonno
Downes for manipulating DSK format images used by Apple 2 emulators.
dsktool.rb also comes with dskexplorer.rb which will run in your web browser
and let you view Apple 2 disk images in the current directory. Usage for both
dsktool.rb and dskexlorer.rb is listed below.

dsktool.rb supports Apple 2 CP/M disk images for READ/WRITE operations. 
More information about disk image support in dsktool.rb is listed below.

Bad News and Good News
----------------------

Since dsktool.rb is written in the ruby programming language it cannot be run
unless ruby is installed on your computer. You can think of it as being
similar to interpreted BASIC in that it needs to run from within another
program. But ruby is infinitely more advanced than interpreted BASIC.

You might be better to think of it as being similar to java in that it runs
on many platforms and shares other characteristics, some which are discussed
at the following link:

http://en.wikipedia.org/wiki/Model-view-controller

But unlike java which must be compiled to be run, ruby programs can be viewed
in a text editor. Ruby is a scripting language also sharing characteristics
with the less advanced but capable perl scripting language from the 
Unix world.

Like java, ruby installs many files. On a Windows XP machine this can take a
large amount of disk space. For example, on my Windows XP machine the
installation in this zip file (and described below) once complete added the
following under the C:\ruby\ directory:

22411 File(s)     89,761,286 bytes
9404 Dir(s)  86,741,917,696 bytes free

Double that amount for unzipping this zip file. If you don't have that amount
of space you can't install this.

That's the bad news. The good news is that if you are familiar with command
line utilities and especially if you work with Apple 2 CP/M you will find
dsktool.rb and dskexplorer.rb useful tools for your collection.

More good news for users of other modern computer systems like Linux Ubuntu
as well as Windows XP users is that dsktool.rb should run on all systems
that support ruby.

Getting Started
---------------

Listed below the links is the reformatted usage output from dsktool.rb and
dskexplorer.rb which will help get you started, and below that is a summary
of how to install and run all this. Html documentation is also provided in
the docs directory in this zip file (and on the http://www.cpm8680.com/
website). These are reformatted duplicates of this readme which you can load
into your favourite web browser by clicking on them from within Windows
Explorer.

Links
-----

This LARGE zip file can be downloaded from http://www.cpm8680.com/ at the
following link:

http://www.cpm8680.com/dsktool/dsktool-5.1-Win32.zip

If you have a slow Internet connection you may not wish to do so.

The html version of this readme can be viewed online at:

http://www.cpm8680.com/dsktool/

More information about dsktool.rb is available at the following links:

http://dsktool.jamtronix.com/
http://rubyforge.org/projects/dsktool

Information specific to dskexplorer.rb which comes with dsktool.rb:

http://blog.jamtronix.com/2007/06/dskexplorerrb.html

More information about Jonno Downes' peekbot project:

http://peekbot.jamtronix.com/


dsktool.rb Usage
----------------

Synopsis
--------
Manipulate DSK format files (as used by Apple 2 emulators)


Usage
-----
dsktool.rb [switches] <filename.dsk>

 -a | --add FILENAME       (*) add file
 -A | --ascii              force output to be ASCII (even if binary)
 -b | --base BASE          use BASE as address to load Binary File
                           this will add 2 bytes to the start of file
                           BASE should be a hex number
                           (can be prefixed with $, 0x, or nothing)
 -B | --bootcode FILENAME  FILENAME gets written to track 0, sector 0
                           FILENAME should be compiled to run at $0801
                           FILENAME can be up to 4Kb in size.
 -c | --catalog            display catalog
 -d | --dump FILENAME      hex dump
 -D | --diskdump           hex dump of entire disk
 -L | --delete FILENAME    (*) delete named file
 -e | --extract FILENAME   extract file by name (either to stdout,
                           or file specified by --output)
 -h | --help               display this message
 -I | --init FILESYSTEM    initialise the disk with the specified filesytem
                           DSK will be created if it doesn't exist.
                           FILESYSTEM can be : cpm,dos33,nadol,pascal,none
 -l | --list FILENAME      monitor style listing (disassembles 65C02 opcodes)
 -o | --output FILENAME    specify name to save extracted file as
 -r | --raw                don't convert files to ASCII
 -S | --showtrace          show full stack trace on any error
 -t | --filetype FILETYPE  file type for file being added.
                           Can be a single letter (A/I/B/T) or number.
                           Default for DOS 3.3 is 0x00 (Text)
 -T | --tokenise           (*) tokenise input file before adding
 -v | --version            show version number
 -x | --explode            extract all files

  (*) options marked with an asterisk are only available for
      file systems that have READ/WRITE support.

       Currently supported filesystems:
               Apple Pascal         (read only)
               CP/M                 (READ/WRITE)
               DOS 3.3              (READ/WRITE)
               NADOL                (READ/WRITE)
               ProDOS 8             (read only)

       Supports 16 sector DSK images
       files with extension .gz will be read & written using gzip
       input files can be URLs

examples:

       dsktool.rb -c http://jamtronix.com/dsks/apshai.dsk.gz
       dsktool.rb --list fid -o fid.lst DOS3MASTR.dsk
       dsktool.rb --extract "COLOR DEMOSOFT" DOS3MASTR.dsk
       dsktool.rb -e HELLO -o HELLO.bas DOS3MASTR.dsk
       dsktool.rb -x DOS3MASTR.dsk.gz -o /tmp/DOS3MASTR/
       dsktool.rb --add STARTUP -T nadol.po
       dsktool.rb --add c:\src\dosdemo\a.out -t B -b $2000 dosdemo.dsk
       dsktool.rb --init dos33 new_dos_disk.dsk.gz
       dsktool.rb -I none -B /tmp/a.out demo1.dsk

dskexplorer.rb Usage:
--------------------

Synopsis
--------
A web-based DSK file explorer


Usage
-----
dskexplorer.rb [switches]

 -h | --help               display this message
 -p | --port PORT_NUMBER   port number to listen on (default is 6502)
 -r | --root ROOT_DIR      root directory to explore from 
                           (default is current directory)
 -v | --version            show version number

Examples

    dskexplorer.rb -r http://www.apple2.org.za/mirrors/
    dskexplorer.rb -r c:\downloads\apple2\ -p 8080


Installing dsktool.rb (in Windows XP)
-------------------------------------
This installation assumes that you don't have ruby installed. 

If you already have ruby installed you can skip the ruby installation. It
won't work anyway. You may need to remove ruby and any other ruby programs if
the rest of the installation fails. Advanced installations of ruby are beyond
the scope of this document.

The version of dsktool.rb that is included in this zip file needs the
following steps to be installed on a Windows XP Machine. Other systems that
ruby supports will follow similar steps: After installing ruby, the gem
installer that comes with ruby is used from the Windows command prompt to
install the rest of dsktool.rb. The following is given for users who will
install on their C: drive.

Summary
-------

- Unzip this zip file with paths intact to the root of your C: drive
- Install ruby - run C:\dsktool\install\dsktool\ruby186-26.exe. 
- Ruby should now be on path.
- Open the command prompt in C:\dsktool\
- Install png -  gem install install\png-1.0.0.gem
- Install dsktool.rb - gem install install\dsktool-0.5.1.gem

If you don't wish to keep the installation files after successfully
installing dsktool just remove the entire C:\dsktool\install directory.

In Windows Xp, two batch files are provided to run dsktool.rb and
dskexplorer.rb. These are used by typing dsktool.rb or dskexplorer.rb
followed by their respective command line switches and options and since ruby
is on path they can be used from the Windows XP command line in any
directory.

Running dsktool.rb (in Windows XP)
----------------------------------

Included in this zip file is an Apple CP/M disk image which you can use to
perform some post-installation tests with to make sure dsktool.rb is working
correctly.

Two simple non-destructive tests can be performed; catalog the disk image and
extract a file from the disk image. 

To catalog the disk image:

dsktool.rb -c SoftcardCPM.dsk

SoftcardCPM.dsk
sector order:   physical
filesystem:     cpm
   APDOS.COM   1664
     ASM.COM   8192
CONFIGIO.BAS   7424
    COPY.COM   1024
   CPM56.COM  10752
     DDT.COM   5120
DOWNLOAD.COM    512
    DUMP.ASM   4224
    DUMP.COM    512
      ED.COM   6656
  FORMAT.COM   2304
  GBASIC.COM  25600
    LOAD.COM   1792
  MBASIC.COM  24576
     PIP.COM   7424
    RW13.COM   2304
    STAT.COM   6144
  SUBMIT.COM   1280
    XSUB.COM    768

To extract a file from the disk image:

dsktool.rb -e APDOS.COM -o foo.com --raw SoftcardCPM.dsk

Directory of C:\cpmtools

04/12/2008  09:07 PM             1,664 foo.com

Running dskexplorer,rb (in Windows Xp)
--------------------------------------

If you have never run a browser based application from your local computer
(many Windows users haven't) this may seem a little strange. Ruby starts-up
dskexplorer.rb and it prompts you to point your web browser to an intranet
address.

You will see a message like the following:

[2008-12-06 14:29:50] INFO  WEBrick 1.3.1
[2008-12-06 14:29:50] INFO  ruby 1.8.6 (2007-09-24) [i386-mswin32]
point your browser at http://localhost:6502/
[2008-12-06 14:29:50] INFO  WEBrick::HTTPServer#start: pid=1428 port=6502

To make things a little easier for Windows XP users, this zip file
has Windows cmd files in place to start-up your browser and then start
dskexplorer.rb. If your browser starts before dskexplorer.rb click on refresh
on your browser when dskexplorer.rb starts.

Just click-on the \dsktool\dskroot.cmd from Windows explorer to start
dskbrowser.rb in your root directory (usually C:\)

Click-on the \dsktool\dskcwd.cmd to start dskbrowser.rb in the
\dsktool\ directory.

You can also type these commands in a command window.

Make sure when you close your browser that you also close dskbrowser.rb's
Windows cmd window or dskbrowser.rb will continue to run its service. On the
other hand you may wish to leave dskbrowser.rb running between browser
sessions so I will leave the further exploration of dskbrowser.rb and
dsktool.rb and Apple 2 disk images in general up to you.

Licence
-------

This program is Copyright (c) 2007 Jonno Downes (jonno@jamtronix.com).

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Disclaimer
----------

This document was created and formatted by hand by Bill Buckels
(bbuckels@mts.net). Its contents are either part of dsktool.rb or provide
additional information about using dsktool.rb. 

Bill Buckels has no warranty obligations or liability resulting from this
document's use in any way whatsoever. If you don't agree then don't read it.
