initial commit

1 files changed, 45 insertions, 0 deletions

diff --git a/doc/fileformat.txt b/doc/fileformat.txt
new file mode 100644
index 0000000..eb08d13
--- /dev/null
+++ b/doc/fileformat.txt
@@ -0,0 +1,45 @@
+An ALF archive is laid out exactly like an ARC version 2 or greater
+archive, with a 29-byte header for each file, followed by the
+compressed data, followed by either EOF or the next file's header.
+
+See the file Arcinfo for the original ARC file format. For ALF files,
+"Byte 2: Compression version" will always be $0F.
+
+The differences are:
+
+- ALF files use $0F for the 'compression type' (Byte 1), whereas
+  ARC files use compression types 2 through 8 (or 1, for ARC v1).
+
+- The actual compressed data is incompatible with any of the
+  compression types supported by ARC. Although ALF uses an
+  implementation of Lempel-Zev, it's not the same implementation
+  as any of the ones that ARC uses.
+
+- For ARC, the last file's compressed data is followed by a 0 byte
+  (in place of the $1A header), to signal "end of archive". For
+  ALF, there's no data after the last byte of the last compressed
+  file;
+
+Other things caused by the limitations of the Atari:
+
+- Not really a file format difference, but the dates stored inside
+  ALF files might be wrong or gibberish, if they were created on
+  an Atari OS other than SpartaDOS (or, on SpartaDOS, but without
+  the time set correctly).
+
+- Atari filenames are generally limited to 12 characters, e.g.
+  PROGRAM1.BAS, so the filename field (Bytes 3-15, 13 bytes long)
+  will never be completely filled. ALF uses a null (0) byte for
+  the filename terminator, and any remaining bytes in the field
+  will be set to $20 (ASCII spaces, *not* more nulls).
+
+- ALF files are never embedded inside a self-extracting executable,
+  so the first file's header always starts at the first byte of
+  the file.
+
+- ARC and ALF both store the compressed and uncompressed file lengths
+  as 32-bit unsigned integers... but for ALF, the maximum file size
+  that can be compressed is probably under 64KB, so both the lengths
+  should have their last 2 bytes set fo 0. I haven't yet attempted
+  to compress a file larger than 64KB with ALF on the Atari, so I
+  may be wrong...