From 82c7a4d367f5f7ba42d31acfdcf66b787c0bdb78 Mon Sep 17 00:00:00 2001
From: "B. Watson" <urchlay@slackware.uk>
Date: Wed, 19 Nov 2025 15:31:53 -0500
Subject: Update fileformat.txt.

---
 doc/fileformat.txt | 49 ++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 36 insertions(+), 13 deletions(-)

diff --git a/doc/fileformat.txt b/doc/fileformat.txt
index 5c33f2a..7d87000 100644
--- a/doc/fileformat.txt
+++ b/doc/fileformat.txt
@@ -1,14 +1,36 @@
-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.
+ALF Archive Structure
+---------------------
+
+An ALF archive is laid out almost exactly like an ARC archive that
+only uses compression types 2 or greater: 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.
 
+Header structure:
+
+Offset | Length | Description
+-------+--------+------------------------------------------------------
+0      | 2      | ALF signature bytes: $1A $0F
+2      | 13     | Filename (null-terminated)
+15     | 4      | 32-bit compressed size (little-endian)
+19     | 2      | File date in MS-DOS format (same as ARC)
+21     | 2      | File time in MS-DOS format (same as ARC)
+23     | 2      | Checksum (simple additivie, *not* a CRC)
+25     | 4      | 32-bit original size (little-endian)
+-------+--------+------------------------------------------------------
+
+The compressed data for the file starts at offset 29.
+
 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).
+- ALF files use $0F for the 'compression type' (offset 1), whereas
+  ARC files use compression types 1 through 8.
+
+- ALF always uses the 29-byte header; ARC uses 29-byte headers for
+  compression types >= 2, but only 25 bytes for type 1 (stored).
 
 - The actual compressed data is incompatible with any of the
   compression types supported by ARC. Although ALF uses an
@@ -25,18 +47,17 @@ The differences are:
   a valid ALF archive... unless there's "junk at EOF" on the first
   file.
 
-Other things caused by the limitations of the Atari:
+- ARC uses CRC-16 for its checksums; ALF just adds the bytes together
+  and uses the low 16 bits of the result as the checksum.
 
 - 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).
+  an Atari DOS other than SpartaDOS (or, on SpartaDOS, but without
+  the R-Time 8 cartridge).
 
-- 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).
+- ARC and ALF are both limited to 12 character filenames, with a
+  null terminator. With ALF, any remaining bytes in the field after
+  the null will be set to $20 (ASCII spaces, *not* more nulls).
 
 - Atari filenames with no extensions (e.g. "FOO") are stored with
   a trailing period (e.g. "FOO.") in the ALF header. Upon extraction,
@@ -55,3 +76,5 @@ Other things caused by the limitations of the Atari:
   maximum size for a single file is 16MB. I have actually tested the
   Atari ALF and UNALF programs with an emulator (and emulated hard
   drive) with a file of 200KB in size, and it worked fine.
+
+Author: B. Watson (urchlay@slackware.uk)
-- 
cgit v1.2.3