1 files changed, 111 insertions, 0 deletions
diff --git a/mkcart.rst b/mkcart.rst
new file mode 100644
index 0000000..dbf5480
--- /dev/null
+++ b/mkcart.rst
@@ -0,0 +1,111 @@
+======
+mkcart
+======
+
+-------------------------------------------------------
+Convert between raw ROM images and atari800 CART format
+-------------------------------------------------------
+
+.. |date| date::
+
+:Manual section: 1
+:Manual group: DASM-Dillon
+:Authors: `B. Watson <yalhcru@gmail.com>`
+:Date: |date|
+:Version: 2.10.12
+:Copyright: This document is licensed under the same terms as DASM
+            itself, see the file COPYING for details.
+
+SYNOPSIS
+========
+
+mkcart -oCARTFILE -tTYPE RAWFILE [RAWFILE ...]
+
+mkcart -cCARTFILE
+
+mkcart -xRAWFILE CARTFILE
+
+mkcart -l
+
+DESCRIPTION
+===========
+
+A companion tool to `dasm(1)`, mkcart can:
+
+- convert one or more `dasm(1)` raw (-f3) object files to a CART image
+  format for use with emulators such as `atari800(1)`.
+
+- convert a CART image back to a raw image.
+
+- check the integrity and report information about a CART image.
+
+OPTIONS
+=======
+
+-tTYPE       Cartridge type (1-67, see `-l` for list), default = guess (poorly!).
+             Only used in -o mode.
+
+-oCARTFILE   Create CARTFILE from RAWFILE(s). `-t` optional but highly
+             recommended.
+
+-cCARTFILE   Check integrity of file (header, checksum, and size).
+
+-xRAWFILE    Create raw binary from CARTFILE (remove header).
+
+-l           List all supported -t types with their sizes in
+             bytes and their human-readable names, and exit.
+
+-?, -h       Show built-in help message.
+
+EXAMPLES
+========
+
+| # a standard 8KB cartridge:
+| dasm example.asm -f3 -oexample.bin
+| mkcart -oexample.cart -t1 example.bin
+
+| # a bankswitched OSS 16KB cartridge:
+| dasm bank1.asm -f3 -obank1.bin
+| dasm bank2.asm -f3 -obank2.bin
+| mkcart -oexample.cart -t15 bank1.bin bank2.bin
+
+EXIT CODES
+==========
+
+With -o and -x, mkcart will exit with status `0` if it was able
+to complete the conversion, or `1` if something went wrong.
+
+With -c, mkcart will exit with status `0` if the image is OK (has a
+valid header, known type, good checksum, etc), or `1` if not.
+
+BUGS
+====
+
+With -o and -x, the input files are opened, read, and closed twice:
+once to calculate the checksum and verify that there's enough data, then
+the header is written and the input files are re-opened and reread. Bad
+Things will probably happen if any of the input files change in between
+the two passes.
+
+The -x option should split bankswitched cartridges into multiple raw
+images instead of one combined image. Workaround: use `split(1)`
+or `dd(1)` to split the raw image into bank-sized chunks:
+
+| mkcart -xmac65.bin mac65.cart
+
+| # split into mac65.bank00 and mac65.bank01
+| split -b8192 mac65.bin mac65.bank
+
+| # same thing, with dd
+| dd if=mac65.bin of=mac65.bank00 bs=1024 count=8
+| dd if=mac65.bin of=mac65.bank01 bs=1024 count=8 skip=8
+
+Either way, you have to know the bank size (usually 8 or 16 KB), which
+is less than ideal.
+
+SEE ALSO
+========
+
+* `dasm(1)`
+* `atari800(1)`
+* `cart.txt`