===============================================================
  MGT - esxDOS dot command for the ZX Spectrum and compatibles
    file listing and export tool for disk images
===============================================================

Supported disk formats:
  GDOS, G+DOS, BetaDOS, SAMDOS, MasterDOS

Developed and tested on:
  eLeMeNt ZX computer and MB03+ interface

Version limitations:
  0.6   UniDOS directories skipped
        Files in MasterDOS directories handled,
          but directory structure is not followed
        MasterBASIC files may be uncompressed
        Microdrive files exported as raw sector files

Warning:
  Do not use the old esxDOS version 0.8.8 (e.g. in the
  Omni computer). You may corrupt files or your SD card!

The command makes intensive use of esxDOS services. In some
cases, it may behave differently with overwritten files or
in directories on your working SD card - compared to a
cleanly formatted SD card with freshly saved files.

In case of any issues, please also send me the disk image
file for which .MGT produces non-standard or incorrect
outputs.

---------------------------------------------------------------


USAGE
-----
  .MGT image[.ext]     show disk image directory listing

  .MGT [switches] image[.ext]


SWITCHES
--------
  -n   No Scroll? prompt
       Suppresses the "Scroll?" pause by setting the scroll
       counter before every new line. The directory listing
       runs to completion without interruption.

  -x   Export files to SD card
       Exports files from the disk image to the current
       directory on the SD card. A root folder named after
       the disk image file is created. If the folder already
       exists, you are prompted: Overwrite? Y/N

  -d   Directory listing to file
       Writes the directory listing to a file. The output
       filename is derived from the image name:

         .MGT -d IMAGE         output: IMAGE.DIR
         .MGT -d IMAGE.LST     output: IMAGE.LST
         .MGT -d IMAGE.TXT     output: IMAGE.TXT
         .MGT -d IMAGE.PRN     output: IMAGE.PRN

       Any extension is accepted except .MGT and .DSK.
       The disk image is always located by auto-detecting the
       image name + MGT/DSK, regardless of the extension
       given. If the output file already exists: Overwr.? Y/N

  -i   Disk image info
       Displays disk parameters: geometry, used/free space,
       slot count, and counts of file types present.

  -t   Transform IMG to MGT
       Converts a disk image from IMG format (side-track-
       sector layout) to MGT format (track-side-sector
       layout). Input must be a .IMG file. Output is a new
       file with the same name but with extension .MGT.
       If the output file already exists: Overwrite? Y/N


SUPPORTED FILE EXTENSIONS
--------------------------
  .MGT   Opened directly. Size is verified (must be exactly
         819200 bytes). Compatible with GDOS, G+DOS, BetaDOS,
         SAMDOS and MasterDOS disk images (UniDOS and
         MasterDOS are partly supported).

  .DSK   Opened directly. Size is verified (must be exactly
         819200 bytes). Same filesystem as .MGT; this
         alternative extension is used by some emulators.
         eDSK format is not supported. The DSK extension is
         not recommended, as it is used by many different
         retro platforms in various formats.

  (none) If no extension is given, .MGT is tried first.
         If not found, .DSK is tried. If neither is found,
         an error is reported.

  .IMG   Only valid with the -t switch. If you specify a
         .IMG file without -t, the error message is shown:
            Only .MGT or .DSK allowed. Use -t switch.


EXPORT (-x): ZX SPECTRUM DISK (GDOS / G+DOS / BetaDOS)
-------------------------------------------------------

A root folder named after the disk image file is created.
BASIC files each get their own subdirectory; all subsequent
non-BASIC files are placed in that subdir until the next
BASIC file is encountered.

File naming: the 10-character MGT filename is cleaned to at
most 8 valid FAT characters (A-Z, a-z, 0-9, - and _). If
the resulting name conflicts with an existing file, a 2-digit
suffix (00-99) is added after the first six characters.

  ZX type       Ext    Header    Notes
  ------------- ------ --------- ---------------------------
  BAS     (1)   .BAS   +3DOS     autostart line preserved
  D.ARRAY (2)   .NAR   +3DOS
  $.ARRAY (3)   .SAR   +3DOS
  CDE     (4)   .COD   +3DOS     load address preserved
  SNP 48k (5)   .SNP   RAW       fixed length: 49152 bytes
  M/DRIVE (6)   .MDX   RAW       sector data, see note
  SCREEN$ (7)   .SCR   RAW       fixed length: 6912 bytes
  SNP128k (9)   .SNP   RAW
  EXECUTE (11)  .BIN   RAW       fixed length: 510 bytes
  All others    .BIN   RAW

Note on M/DRIVE (.MDX): Microdrive files are exported as
raw sector data. The .MDX file preserves all data, but
cannot be directly used as an emulator .MDR cartridge file.

+3DOS header (128 bytes, for BAS/NAR/SAR/COD):
  The +3DOS header is built from the directory entry fields.
  The checksum is the sum of bytes 0-126, modulo 256.
  The first 9 bytes stored on disk are the G+DOS tape-style
  header and are skipped on export. 


EXPORT (-x): SAM COUPE DISK (SAMDOS / MasterDOS)
-------------------------------------------------
Same folder and subdirectory structure as ZX disks. Each
SAM BASIC file gets its own subdirectory; subsequent files
go into that subdirectory until the next SAM BASIC file
is encountered.

The first 9 bytes of every SAM file on disk are the SAMDOS
file header and are always skipped during export.

  SAM type        Condition             Ext    Header
  --------------- --------------------- ------ --------
  BASIC    (16)                         .BIN   RAW
  C (CODE) (19)   length = 6912 B       .SCR   RAW
  C (CODE) (19)   start 0-65535 and     .COD   +3DOS
                  start + len <= 65536
  DIR      (21)   skipped, not exported
  all others                            .BIN   RAW

+3DOS header for SAM CODE (.COD):
  byte 15 = 3 (CODE), bytes 16-17 = data length,
  bytes 18-19 = load address (from directory entry),
  bytes 20-21 = 0. Checksum: sum of bytes 0-126 mod 256.


TRANSFORM (-t): IMG to MGT CONVERSION
--------------------------------------
The IMG and MGT formats contain identical data but in a
different sector order:

  IMG: Side 0 all tracks, then Side 1 all tracks
  MGT: Each track: Side 0 then Side 1

The -t switch reads each sector from its IMG position and
writes it to the correct MGT position. The source .IMG file
is not modified.

Usage:
  .MGT -t GAMES        searches for GAMES.IMG
  .MGT -t GAMES.IMG    opens GAMES.IMG directly

Output: GAMES.MGT (in the current directory)


ERROR MESSAGES
--------------

  No MGT/DSK image found.
       No file with the given name was found with either
       .MGT or .DSK extension (auto-detect mode).

  Only .MGT or .DSK allowed.
       The file extension is not supported. Use .MGT or .DSK.

  Use -t switch.
       Shown when a .IMG file is given without the -t switch.

  File IMGNAME.EXT not found.
       The specified file does not exist in the current
       directory on the SD card.

  Wrong size (not 819200 bytes): IMGNAME.EXT
       The file exists but is not exactly 819200 bytes.
       A valid MGT/DSK/IMG image must be 80 tracks x 2 sides
       x 10 sectors x 512 bytes = 819200 bytes.

  Not a valid MGT/SAM image.
       The file size is correct but the directory structure
       does not match the expected MGT format.

  Incompatible DSK image size.
       The .DSK file is not the correct size for an MGT
       filesystem image.

  File read/write error.
       An I/O error occurred while reading the disk image
       or writing to the SD card.

  Write error (disk full?): FILENAME
       A file could not be written during export. The SD
       card may be full. Export continues with remaining
       files.

  Invalid switch.
       An unrecognised switch was given. Valid switches
       are -n, -x, -d, -i and -t.

  MGT/DSK not allowed as output
       The -d switch does not allow .MGT or .DSK as the
       output file extension, as these are reserved for
       disk image files.

===============================================================
end-of-file
