Welcome to the Wonderfully Ancient World of CP/M 80 and
The Wonderfully Modern World of Apple 2 Disk Images and Ruby and Everything
dsktool.rb and dskexplorer.rb for Windows (and other) Users

Getting Started

Introduction
Licence
Disclaimer

Program Documentation

dsktool.rb - Manipulate Apple 2 DSK format files
dskexplorer.rb - A web-based DSK file explorer

Installation

Bad News and Good News
Getting Started
Links
Installing dsktool.rb (in Windows XP)
Running dsktool.rb (in Windows XP)
Running dskexplorer,rb (in Windows Xp)

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 in the dsktool.rb program documentation and the dskexplorer.rb program documentation respectively.
dsktool.rb supports Apple 2 CP/M disk images for READ/WRITE operations. More information about disk image support in dsktool.rb is listed in the dsktool.rb program documentation.
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 the zip file in the Links section 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 the zip file installation in the Links section below. 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.
<< Back to Top

Getting Started
The download for the zip file installation of dsktool.rb for Windows (and other) users is in the following Links section.Below the links is a summary of how to install and run all this. Html documentation is also provided in the docs directory in the zip file (and on the http://www.cpm8680.com/ website). You can load these into your favourite web browser by clicking on them from within Windows Explorer.
Links
The zip file installation of dsktool.rb for Windows (and other) users 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.
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/

<< Back to Top

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 the zip file installation 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.rb 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.
<< Back to Top

Running dsktool.rb (in Windows XP)
Included in the installation 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

<< Back to Top

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, the installation 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.
<< Back to Top

Licence and Copyright
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.
<< Back to Top

Caveat Emptor
This document was created and formatted by hand by Bill Buckels. 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.