Document the Mac support.

doc/index.md

@@ -76,6 +76,9 @@ markers.
   - [Brother 120kB and 240kB word processor disks](brother.html); read and
     write
 
+  - [Macintosh 800kB (and probably 400kB too) disks](macintosh.html); read and
+    write
+
 ...aaaand that's it. If you want more, please [get in
 touch](https://github.com/davidgiven/fluxengine/issues/new); I need samples
 of floppy disks to scan and play with.

doc/macintosh.md

@@ -0,0 +1,65 @@
+Macintosh disks
+===============
+
+Macintosh disks come in two varieties: the newer 1440kB ones, which are
+perfectly ordinary PC disks you should use `fe-readibm` to read, and the
+older 800kB disks (and 400kB for the single sides ones). They have 80 tracks
+and up to 12 sectors per track.
+
+They are also completely insane.
+
+It's not just the weird, custom GCR encoding. It's not just the utterly
+bizarre additional encoding/checksum built on top of that where [every byte
+is mutated according to the previous bytes in the
+sector](https://www.bigmessowires.com/2011/10/02/crazy-disk-encoding-schemes/).
+It's not just the odd way in which disks think they have four sides, two on
+one side and two on the other, so that the track byte stores only the bottom
+6 bits of the track number. It's not just the way that Macintosh sectors are
+524 bytes long. No, it's the way the Macintosh drive changes speed depending
+on which track it's looking at, so that each track contains a different
+amount of data.
+
+The reason for this is actually quite sensible: the tracks towards the centre
+of the disk are obviously moving more slowly, so you can't pack the bits in
+quite as closely (due to limitations in the magnetic media). You can use a
+higher bitrate at the edge of the disk than in the middle. Many platforms,
+for example the Commodore 64 1541 drive, changed bitrate this way.
+
+But Macintosh disks used a constant bitrate and changed the speed that the
+disk spun instead to achieve the same effect...
+
+_Anyway_: FluxEngine will read them fine on a conventional drive. Because
+it's clever.
+
+Reading discs
+-------------
+
+Just do:
+
+```
+.obj/fe-readmac
+```
+
+You should end up with an `mac.img` which is 1001888 bytes long (for a normal
+DD disk). If you want the single-sided variety, use `-s :s=0`.
+
+**Big warning!** The image may not work in an emulator. Mac disk images are
+complicated due to the way the tracks are different sizes and the odd sector
+size. FluxEngine chooses to store them in a simple 524 x 12 x 2 x 80 layout,
+with holes where missing sectors should be. This was easiest. If anyone can
+suggest a better way, please [get in
+touch](https://github.com/davidgiven/fluxengine/issues/new).
+
+Useful references
+-----------------
+
+  - [MAME's ap_dsk35.cpp file]
+    (https://github.com/mamedev/mame/blob/4263a71e64377db11392c458b580c5ae83556bc7/src/lib/formats/ap_dsk35.cpp),
+    without which I'd never have managed to do this
+
+  - [Crazy Disk Encoding
+    Schemes](https://www.bigmessowires.com/2011/10/02/crazy-disk-encoding-schemes/), which made
+    me realise just how nuts the format is
+
+  - [Les Disquettes et le drive Disk II](http://www.hackzapple.com/DISKII/DISKIITECH.HTM), an
+    epicly detailed writeup of the Apple II disk format (which is closely related)

lib/macintosh/decoder.cc

@@ -22,7 +22,9 @@ static int decode_data_gcr(uint8_t gcr)
     return -1;
 };
 
-/* This is, um, extremely inspired by the MESS implementation. */
+/* This is extremely inspired by the MESS implementation, written by Nathan Woods
+ * and R. Belmont: https://github.com/mamedev/mame/blob/4263a71e64377db11392c458b580c5ae83556bc7/src/lib/formats/ap_dsk35.cpp
+ */
 static std::vector<uint8_t> decode_crazy_data(const uint8_t* inp, int& status)
 {
     std::vector<uint8_t> output;