TAP utilities (John Elliott, 6 February 2009)
=============================================

  General note: All these programs except specform, unspecform and mkp3fs
operate on files in the .TAP format. They also support .ZXT, which is a .TAP 
file with a +3DOS header, used by TAPROM on the +3.

  When compiling this software, it helps to have LibDsk 
<http://www.seasip.demon.co.uk/Unix/LibDsk/> installed. Otherwise tap2dsk 
and mkp3fs will be severely restricted in their output capabilities.

  Programs in this archive are:

specform
--------
  specform adds a +3DOS header to one or more files, or corrects the checksum 
in an existing +3DOS header.

  Syntax is: specform { -F } { -a addr } <file> <file> ...

  If the -F option is not present, a +3DOS header will be added to each file
(even those that have one already) and the result saved as a file with the 
same name, but ending in .zxb.
  If the -a option is present, the load address specified will be used in
the +3DOS header added to each file. Otherwise, a load address of 0 will be
used.
  If the -F option is present, each file must be a +3DOS file. The header
checksum will be recalculated and saved back to the same file.

unspecform   (unspecfm in DOS)
----------

  unspecform removes the +3DOS header from a single file. It also removes 
any bytes beyond the end of the file (usually caused by the process of copying
+3DOS files from CP/M media).

  Syntax is: unspecform { input { output }}

  If the input and output filenames aren't specified, standard input and 
output are used. 


bin2bas
-------

  bin2bas converts wraps a binary file (with or without a +3DOS header) in
a BASIC program consisting of two lines. The first line is a REM statement
containing the binary file, and the second is a BASIC USR command to execute
the code in the REM:

	LET x = USR(5 + PEEK 23635 + 256 * PEEK 23636)

  Your binary file should therefore begin with Z80 code. This should be 
position-independent, and follow the usual Spectrum BASIC calling conventions:

* At entry, BC holds the load address.
* If it returns, x will contain the value in BC.
* If you want ROM code to run, observe normal precautions with IY and HL'.
  
Syntax is: bin2bas { -t=filename | -z=filename | -p } input { output }

  If no output filename is present, stdout will be used. The options are:

   -t=filename: Output the BASIC as a .TAP file containing the named program.
   -z=filename: Output the BASIC as a .ZXT file containing the named program.
   -p:          Output the BASIC in +3DOS format (default)

tapcat
------

  tapcat creates a .TAP file from one or more files (either +3DOS or raw). 
         It can also append to an existing .TAP file.

  Syntax is: tapcat { -N } { -a addr } <tapfile> <file> <file>

  If the -N option is present, then a new .TAP file is created. If not, the 
files will be appended to an existing .TAP file. 
  If the -a option is present, the load address specified will be used in
the tape header added to each file. Otherwise, a load address of 0 will be
used.

tapget
------

   tapget extracts one or more files from a .TAP file. 

Syntax is: tapget <tapfile> <file> <file> ...

   The filenames passed can include '*' and '?' as wildcards. Each specified
file will be saved in +3DOS format. Note that tapget can't extract headerless
blocks.

tapls
-----

  tapls lists the contents of one or more .TAP files.

Syntax is: tapls { -l | -3 } <tapfile> <tapfile> ...

  The options control how the output is formatted. If no options are present,
a simple list of names is displayed:

astroclone
loader    
pic       
[Headerless]

  -3 produces a listing similar to the +3DOS 'CAT "T:"' command:

Program: astroclone LINE 0 
Bytes: loader     CODE 24500,100
Bytes: pic        CODE 50000,7000
Headerless block: Type=255 length=40536

  -l produces a listing similar to the UNIX 'ls -l' command:

-r--r--r-- BASIC     190 astroclone
-r--r--r-- Bytes     100 loader    
-r--r--r-- Bytes    7000 pic       
-r--r--r-- [0xff]  40536 (Headerless block)

tapsplit
--------
 
  tapsplit explodes an entire .TAP file into its component parts, including
any headerless blocks. 

Syntax is: tapsplit <tapfile> { <output-dir> }

  If no output directory is supplied, the current directory will be used.

  Each file in the .TAP will be written to the chosen output directory. If its 
name collides with an existing file, ".1" will be appended and the process 
repeated.

sna2tap
-------

  sna2tap converts a Spectrum snapshot in the .SNA format to a .TAP file that
can be loaded on a 48k Spectrum.

Syntax is: sna2tap {options} { input-file { output-file } }

  Options are:

--base=addr: sna2tap overwrites 62-65 bytes of the snapshot with its 
            final-stage loader code. By default this is placed just below the
            bottom of the Z80 stack. Some games, particularly those which 
            use the stack for copying memory to and fro, may be corrupted by
            this; if so, you need to find somewhere else to put this code. In
            some cases the video RAM may be suitable; in others, you would 
            have to find a free space in the snapshot, perhaps using a hex 
            editor.
             The address can be specified in decimal or (if preceded by "0x") 
            hex. So --base=16384 or --base=0x4000 are equivalent.

--name=name: The name to give the BASIC loader (by default, "SNAPSHOT")
--tap:       Output in .TAP format (default)
--zxt:       Output in .ZXT format

  If the input and output filenames aren't specified, standard input and 
output are used. 

  To reverse the process, run tapsplit on the generated .TAP file. It will 
save the snapshot as "Block1.sna".

  (Technical note: tapls, tapsplit and tap2dsk assume that any block of type 
  0x53 ('S') and length 49179 bytes is a .SNA-format snapshot, and display it 
  accordingly.)

tap2dsk / mkp3fs
----------------

  tap2dsk and mkp3fs are both programs that generate a new +3DOS-format disc
image. mkp3fs creates a disc image and injects one or more files into it, 
while tap2dsk transfers the contents of a .TAP file into the new disc image.
  Don't pass the name of an existing disc image to either program, unless 
you want it overwritten without warning.

Syntax is: 
	mkp3fs  { options } dskfile filename filename ...
	tap2dsk { options } tapfile dskfile

  Both programs take the same options:

-180:               Generate a 180k disc image.
-720:               Generate a 720k disc image.
-cpmonly:	    Omit the FAT12 directory, FAT and boot sector (see below)
-dosonly:           Make the disc fully FAT12 (see below)
-nostamps:          Do not include file time stamps. You may want to use this
                    if you are writing headerless files to a 720k disc image,
                    because +3DOS appears to have difficulty reading 
		    headerless files in this situation.
-label <labelname>: The CP/M disc label. If none is specified, tap2dsk will 
		    use the name of the TAP file and mkp3fs won't create a 
		    label. If -nostamps is present, the label will not be 
                    written either.
-type <type>        The LibDsk type of the file to write (eg, dsk/edsk for a 
                    disc image, floppy for a real drive). If LibDsk wasn't
                    present at compile time, this option is ignored.
-compress <type>    The LibDsk compression method with which the new file 
                    should be compresssed. Again, if LibDsk wasn't around this
		    option is ignored.

Disc compatibility
~~~~~~~~~~~~~~~~~~
  By default, the disc images written by tap2dsk are readable not only as
CP/M discs under +3DOS, but also as FAT12 discs under Windows 9x, Linux and 
DOS. They are not, however, readable on Windows NT/2000/XP/Vista. Even under
those systems that can read them, there are a couple of caveats:

* If you've got Windows 95/98/ME, run the included DUALDOS.REG registry script
 to stop Windows' volume tracker scribbling on the boot sector.

* Changes made to the +3DOS directory won't update the PCDOS directory or 
 vice versa, so don't rely on this feature after writing to the disc.

Two options are supplied to control this feature:

-cpmonly  leaves out the DOS directory, FAT and boot sector. The disc will 
          still work as a CP/M disc under +3DOS, but not as a FAT12 disc under
          anything else.

-dosonly  writes a fully DOS-compatible boot sector. The disc will work 
          fine as a FAT12 disc under Windows NT/2000/XP/Vista, and won't 
          require the registry script to be run under Windows 95/98/ME, but
          it won't be usable on the +3.

  If both options are supplied, -cpmonly takes priority.



