Fix bad documentation which got checked in somehow.

doc/disk-mac.md

@@ -1,2 +1,73 @@
--d
-\r
+mac
+====
+## 400kB/800kB 3.5" GCR
+<!-- This file is automatically generated. Do not edit. -->
+
+Macintosh disks come in two varieties: the newer 1440kB ones, which are
+perfectly ordinary PC disks you should use the `ibm` profile to read them, 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 conventional drives.  Because it's
+clever.
+
+Macintosh computers never really used the twelve bytes of metadata and the
+standard for disk images is to omit it. If you want them, specify that you want
+524-byte sectors. The metadata will follow the 512 bytes of user data.
+
+## Options
+
+  - Format variants:
+      - `400`: 400kB 80-track SSDD
+      - `800`: 800kB 80-track DSDD
+  - `metadata`: read/write 524 byte sectors
+
+## Examples
+
+To read:
+
+  - `fluxengine read mac --400 -s drive:0 -o mac.dsk`
+  - `fluxengine read mac --800 -s drive:0 -o mac.dsk`
+
+To write:
+
+  - `fluxengine write mac --400 -d drive:0 -i mac.dsk`
+  - `fluxengine write mac --800 -d drive:0 -i mac.dsk`
+
+## 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)
+
+  - [The DiskCopy 4.2
+        format](https://www.discferret.com/wiki/Apple_DiskCopy_4.2), described on
+        the DiskFerret website.
+