Better autogenerated documentation.

2025-10-31 11:17:01 -07:00 · 2023-05-25 21:14:41 +02:00
parent 28ca2b72f1
commit 854b3e9c59
49 changed files with 592 additions and 67 deletions
--- a/doc/disk-40track_drive.md
+++ b/doc/disk-40track_drive.md
@@ -1,4 +1,6 @@
+40track_drive
+====
+## Adjust configuration for a 40-track drive
 <!-- This file is automatically generated. Do not edit. -->
-# Adjust configuration for a 40-track drive

 (This format has no documentation. Please file a bug.)
--- a/doc/disk-acornadfs.md
+++ b/doc/disk-acornadfs.md
@@ -1,5 +1,7 @@
+acornadfs
+====
+## BBC Micro, Archimedes
 <!-- This file is automatically generated. Do not edit. -->
-# BBC Micro, Archimedes

 Acorn ADFS disks are used by the 6502-based BBC Micro and ARM-based Archimedes
 series of computers. They are yet another variation on MFM encoded IBM scheme
@@ -18,5 +20,20 @@ they might require nudging as the side order can't be reliably autodetected.

 ## Options

-(no options)
+  - Format variants:
+      - `160`: 160kB 3.5" or 5.25" 40-track SSDD; S format
+      - `320`: 320kB 3.5" or 5.25" 80-track SSDD; M format
+      - `640`: 640kB 3.5" or 5.25" 80-track DSDD; L format
+      - `800`: 800kB 3.5" 80-track DSDD; D and E formats
+      - `1600`: 1600kB 3.5" 80-track DSHD; F formats
+
+## Examples
+
+To read:
+
+  - `fluxengine read acornadfs --160 -s drive:0 -o acornadfs.img`
+  - `fluxengine read acornadfs --320 -s drive:0 -o acornadfs.img`
+  - `fluxengine read acornadfs --640 -s drive:0 -o acornadfs.img`
+  - `fluxengine read acornadfs --800 -s drive:0 -o acornadfs.img`
+  - `fluxengine read acornadfs --1600 -s drive:0 -o acornadfs.img`

--- a/doc/disk-acorndfs.md
+++ b/doc/disk-acorndfs.md
@@ -1,5 +1,7 @@
+acorndfs
+====
+## Acorn Atom, BBC Micro series
 <!-- This file is automatically generated. Do not edit. -->
-# Acorn Atom, BBC Micro series

 Acorn DFS disks are used by the Acorn Atom and BBC Micro series of computers.
 They are pretty standard FM encoded IBM scheme disks, with 256-sectors and
@@ -14,7 +16,21 @@ requires a bit of fiddling as they have the same tracks on twice.

 ## Options

-(no options)
+  - Format variants:
+      - `100`: 100kB 40-track SSSD
+      - `200`: 200kB 80-track SSSD
+
+## Examples
+
+To read:
+
+  - `fluxengine read acorndfs --100 -s drive:0 -o acorndfs.img`
+  - `fluxengine read acorndfs --200 -s drive:0 -o acorndfs.img`
+
+To write:
+
+  - `fluxengine write acorndfs --100 -d drive:0 -i acorndfs.img`
+  - `fluxengine write acorndfs --200 -d drive:0 -i acorndfs.img`

 ## References

--- a/doc/disk-aeslanier.md
+++ b/doc/disk-aeslanier.md
@@ -1,5 +1,7 @@
+aeslanier
+====
+## 616kB 5.25" 77-track SSDD hard sectored
 <!-- This file is automatically generated. Do not edit. -->
-# 616kB 5.25" 77-track SSDD hard sectored

 Back in 1980 Lanier released a series of very early integrated word processor
 appliances, the No Problem. These were actually [rebranded AES Data Superplus
@@ -31,6 +33,12 @@ based on what looks right. If anyone knows _anything_ about these disks,

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read aeslanier -s drive:0 -o aeslanier.img`
+
 ## References

  * [SA800 Diskette Storage Drive - Theory Of
--- a/doc/disk-agat.md
+++ b/doc/disk-agat.md
@@ -1,5 +1,7 @@
+agat
+====
+## 840kB 5.25" 80-track DS
 <!-- This file is automatically generated. Do not edit. -->
-# 840kB 5.25" 80-track DS

 The Agat (Russian: ↊fd74
 1983. These were based around a 6502 and were nominally Apple II-compatible
@@ -14,6 +16,16 @@ profile.

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read agat -s drive:0 -o agat.img`
+
+To write:
+
+  - `fluxengine write agat -d drive:0 -i agat.img`
+
 ## References

  - [Magazine article on the
--- a/doc/disk-amiga.md
+++ b/doc/disk-amiga.md
@@ -1,5 +1,7 @@
+amiga
+====
+## 880kB 3.5" DSDD
 <!-- This file is automatically generated. Do not edit. -->
-# 880kB 3.5" DSDD

 Amiga disks use MFM, but don't use IBM scheme. Instead, the entire track is
 read and written as a unit, with each sector butting up against the previous
@@ -16,7 +18,19 @@ distinctly subpar and not particularly good at detecting errors.

 ## Options

-(no options)
+  - Sector size:
+      - `without_metadata`: 512-byte sectors
+      - `with_metadata`: 528-byte sectors
+
+## Examples
+
+To read:
+
+  - `fluxengine read amiga -s drive:0 -o amiga.adf`
+
+To write:
+
+  - `fluxengine write amiga -d drive:0 -i amiga.adf`

 ## References

--- a/doc/disk-ampro.md
+++ b/doc/disk-ampro.md
@@ -1,5 +1,7 @@
+ampro
+====
+## CP/M
 <!-- This file is automatically generated. Do not edit. -->
-# CP/M

 The Ampro Little Board was a very simple and cheap Z80-based computer from
 1984, which ran CP/M. It was, in fact, a single PCB which you could mount
@@ -33,7 +35,16 @@ kayinfo.lbr

 ## Options

-(no options)
+  - Format variants:
+      - `400`: 400kB 40-track DSDD
+      - `800`: 800kB 80-track DSDD
+
+## Examples
+
+To read:
+
+  - `fluxengine read ampro --400 -s drive:0 -o ampro.img`
+  - `fluxengine read ampro --800 -s drive:0 -o ampro.img`

 ## References

--- a/doc/disk-apple2.md
+++ b/doc/disk-apple2.md
@@ -1,5 +1,7 @@
+apple2
+====
+## Prodos, Appledos, and CP/M
 <!-- This file is automatically generated. Do not edit. -->
-# Prodos, Appledos, and CP/M

 Apple II disks are nominally fairly sensible 40-track, single-sided, 256
 bytes-per-sector jobs. However, they come in two varieties: DOS 3.3/ProDOS and
@@ -42,7 +44,7 @@ volume.

 ## Options

-  - Format variant:
+  - Format variants:
      - `140`: 140kB 5.25" 35-track SS
      - `640`: 640kB 5.25" 80-track DS
  - Filesystem and sector skew:
@@ -52,6 +54,18 @@ volume.
      - `cpm`: use CP/M soft sector skew and filesystem
  - `side1`: for AppleDOS file system access, read the volume on side 1 of a disk

+## Examples
+
+To read:
+
+  - `fluxengine read apple2 --140 -s drive:0 -o apple2.img`
+  - `fluxengine read apple2 --640 -s drive:0 -o apple2.img`
+
+To write:
+
+  - `fluxengine write apple2 --140 -d drive:0 -i apple2.img`
+  - `fluxengine write apple2 --640 -d drive:0 -i apple2.img`
+
 ## References

  - [Beneath Apple DOS](https://fabiensanglard.net/fd_proxy/prince_of_persia/Beneath%20Apple%20DOS.pdf)
--- a/doc/disk-apple2_drive.md
+++ b/doc/disk-apple2_drive.md
@@ -1,4 +1,6 @@
+apple2_drive
+====
+## Adjust configuration for a 40-track Apple II drive
 <!-- This file is automatically generated. Do not edit. -->
-# Adjust configuration for a 40-track Apple II drive

 (This format has no documentation. Please file a bug.)
--- a/doc/disk-atarist.md
+++ b/doc/disk-atarist.md
@@ -1,5 +1,7 @@
+atarist
+====
+## Almost PC compatible
 <!-- This file is automatically generated. Do not edit. -->
-# Almost PC compatible

 Atari ST disks are standard MFM encoded IBM scheme disks without an IAM header.
 Disks are typically formatted 512 bytes per sector with between 9-10 (sometimes
@@ -13,7 +15,39 @@ Be aware that many PC drives (including mine) won't do the 82 track formats.

 ## Options

-(no options)
+  - Format variants:
+      - `360`: 360kB 3.5" 80-track 9-sector SSDD
+      - `370`: 370kB 3.5" 82-track 9-sector SSDD
+      - `400`: 400kB 3.5" 80-track 10-sector SSDD
+      - `410`: 410kB 3.5" 82-track 10-sector SSDD
+      - `720`: 720kB 3.5" 80-track 9-sector DSDD
+      - `740`: 740kB 3.5" 82-track 9-sector DSDD
+      - `800`: 800kB 3.5" 80-track 10-sector DSDD
+      - `820`: 820kB 3.5" 82-track 10-sector DSDD
+
+## Examples
+
+To read:
+
+  - `fluxengine read atarist --360 -s drive:0 -o atarist.img`
+  - `fluxengine read atarist --370 -s drive:0 -o atarist.img`
+  - `fluxengine read atarist --400 -s drive:0 -o atarist.img`
+  - `fluxengine read atarist --410 -s drive:0 -o atarist.img`
+  - `fluxengine read atarist --720 -s drive:0 -o atarist.img`
+  - `fluxengine read atarist --740 -s drive:0 -o atarist.img`
+  - `fluxengine read atarist --800 -s drive:0 -o atarist.img`
+  - `fluxengine read atarist --820 -s drive:0 -o atarist.img`
+
+To write:
+
+  - `fluxengine write atarist --360 -d drive:0 -i atarist.img`
+  - `fluxengine write atarist --370 -d drive:0 -i atarist.img`
+  - `fluxengine write atarist --400 -d drive:0 -i atarist.img`
+  - `fluxengine write atarist --410 -d drive:0 -i atarist.img`
+  - `fluxengine write atarist --720 -d drive:0 -i atarist.img`
+  - `fluxengine write atarist --740 -d drive:0 -i atarist.img`
+  - `fluxengine write atarist --800 -d drive:0 -i atarist.img`
+  - `fluxengine write atarist --820 -d drive:0 -i atarist.img`

 ## References

--- a/doc/disk-bk.md
+++ b/doc/disk-bk.md
@@ -1,5 +1,7 @@
+bk
+====
+## 800kB 5.25"/3.5" 80-track 10-sector DSDD
 <!-- This file is automatically generated. Do not edit. -->
-# 800kB 5.25"/3.5" 80-track 10-sector DSDD

 The BK (an abbreviation for 1ba9
 is a Soviet era personal computer from Elektronika based on a PDP-11
@@ -16,3 +18,13 @@ on what was available at the time, with the same format on both.

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read bk -s drive:0 -o bk800.img`
+
+To write:
+
+  - `fluxengine write bk -d drive:0 -i bk800.img`
+
--- a/doc/disk-brother.md
+++ b/doc/disk-brother.md
@@ -1,5 +1,7 @@
+brother
+====
+## GCR family
 <!-- This file is automatically generated. Do not edit. -->
-# GCR family

 Brother word processor disks are weird, using custom tooling and chipsets.
 They are completely not PC compatible in every possible way other than the
@@ -34,7 +36,21 @@ investigate.

 ## Options

-(no options)
+  - Format variants:
+      - `120`: 120kB 3.5" 39-track SS GCR
+      - `240`: 240kB 3.5" 78-track SS GCR
+
+## Examples
+
+To read:
+
+  - `fluxengine read brother --120 -s drive:0 -o brother.img`
+  - `fluxengine read brother --240 -s drive:0 -o brother.img`
+
+To write:
+
+  - `fluxengine write brother --120 -d drive:0 -i brother.img`
+  - `fluxengine write brother --240 -d drive:0 -i brother.img`

 Dealing with misaligned disks
 -----------------------------
--- a/doc/disk-commodore.md
+++ b/doc/disk-commodore.md
@@ -1,5 +1,7 @@
+commodore
+====
+## 1541, 1581, 8050 and variations
 <!-- This file is automatically generated. Do not edit. -->
-# 1541, 1581, 8050 and variations

 Commodore 8-bit computer disks come in two varieties: GCR, which are the
 overwhelming majority; and MFM, only used on the 1571 and 1581. The latter were
@@ -41,7 +43,29 @@ A CMD FD2000 disk (a popular third-party Commodore disk drive)

 ## Options

-(no options)
+  - Format variants:
+      - `171`: 171kB 1541, 35-track variant
+      - `192`: 192kB 1541, 40-track variant
+      - `800`: 800kB 3.5" 1581
+      - `1042`: 1042kB 5.25" 8051
+      - `1620`: 1620kB, CMD FD2000
+
+## Examples
+
+To read:
+
+  - `fluxengine read commodore --171 -s drive:0 -o commodore.d64`
+  - `fluxengine read commodore --192 -s drive:0 -o commodore.d64`
+  - `fluxengine read commodore --800 -s drive:0 -o commodore.d64`
+  - `fluxengine read commodore --1042 -s drive:0 -o commodore.d64`
+  - `fluxengine read commodore --1620 -s drive:0 -o commodore.d64`
+
+To write:
+
+  - `fluxengine write commodore --171 -d drive:0 -i commodore.d64`
+  - `fluxengine write commodore --192 -d drive:0 -i commodore.d64`
+  - `fluxengine write commodore --800 -d drive:0 -i commodore.d64`
+  - `fluxengine write commodore --1620 -d drive:0 -i commodore.d64`

 ## References

--- a/doc/disk-eco1.md
+++ b/doc/disk-eco1.md
@@ -1,5 +1,7 @@
+eco1
+====
+## CP/M; 1210kB 77-track mixed format DSHD
 <!-- This file is automatically generated. Do not edit. -->
-# CP/M; 1210kB 77-track mixed format DSHD

 The Eco1 is a Italian CP/M machine produced in 1982. It had 64kB of RAM, in
 later models expandable up to 384kB, and _two_ Z80 processors. One of these was
@@ -27,6 +29,12 @@ images.

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read eco1 -s drive:0 -o eco1.img`
+
 ## References

  - [Apulio Retrocomputing's page on the
--- a/doc/disk-epsonpf10.md
+++ b/doc/disk-epsonpf10.md
@@ -1,5 +1,7 @@
+epsonpf10
+====
+## CP/M; 3.5" 40-track DSDD
 <!-- This file is automatically generated. Do not edit. -->
-# CP/M; 3.5" 40-track DSDD

 The Epson PF10 is the disk unit for the Epson Z80 series of 'laptops', running
 CP/M. It uses a single-sided 40-track 3.5" format, which is unusual, but the
@@ -9,3 +11,9 @@ format itself is yet another IBM scheme variant.

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read epsonpf10 -s drive:0 -o epsonpf10.img`
+
--- a/doc/disk-f85.md
+++ b/doc/disk-f85.md
@@ -1,5 +1,7 @@
+f85
+====
+## 461kB 5.25" 77-track SS
 <!-- This file is automatically generated. Do not edit. -->
-# 461kB 5.25" 77-track SS

 The Durango F85 was an early office computer based around a 5MHz 8085 processor,
 sold in 1977. It had an impressive 64kB of RAM, upgradable to 128kB, and ran
@@ -30,6 +32,12 @@ touch](https://github.com/davidgiven/fluxengine/issues/new).

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read f85 -s drive:0 -o f85.img`
+
 ## References

 There's amazingly little information about these things.
--- a/doc/disk-fb100.md
+++ b/doc/disk-fb100.md
@@ -1,5 +1,7 @@
+fb100
+====
+## 100kB 3.5" 40-track SSSD
 <!-- This file is automatically generated. Do not edit. -->
-# 100kB 3.5" 40-track SSSD

 The Brother FB-100 is a serial-attached smart floppy drive used by a several
 different machines for mass storage, including the Tandy Model 100 and
@@ -24,6 +26,12 @@ I don't have access to one of those disks.

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read fb100 -s drive:0 -o fb100.img`
+
 ## References

  - [Tandy Portable Disk Drive operations
--- a/doc/disk-hplif.md
+++ b/doc/disk-hplif.md
@@ -1,5 +1,7 @@
+hplif
+====
+## a variety of disk formats used by HP
 <!-- This file is automatically generated. Do not edit. -->
-# a variety of disk formats used by HP

 LIF, a.k.a. Logical Interchange Format, is a series of formats used by
 Hewlett-Packard across their entire range of computers, from calculators to
@@ -11,5 +13,22 @@ encoding scheme.

 ## Options

-(no options)
+  - Format variants:
+      - `264`: 264kB 3.5" 66-track SSDD; HP9121 format
+      - `616`: 616kB 3.5" 77-track DSDD
+      - `770`: 770kB 3.5" 77-track DSDD
+
+## Examples
+
+To read:
+
+  - `fluxengine read hplif --264 -s drive:0 -o hplif.img`
+  - `fluxengine read hplif --616 -s drive:0 -o hplif.img`
+  - `fluxengine read hplif --770 -s drive:0 -o hplif.img`
+
+To write:
+
+  - `fluxengine write hplif --264 -d drive:0 -i hplif.img`
+  - `fluxengine write hplif --616 -d drive:0 -i hplif.img`
+  - `fluxengine write hplif --770 -d drive:0 -i hplif.img`

--- a/doc/disk-ibm.md
+++ b/doc/disk-ibm.md
@@ -1,5 +1,7 @@
+ibm
+====
+## Generic PC 3.5"/5.25" disks
 <!-- This file is automatically generated. Do not edit. -->
-# Generic PC 3.5"/5.25" disks

 IBM scheme disks are _the_ most common disk format, ever. They're used by a
 huge variety of different systems, and they come in a huge variety of different
@@ -36,7 +38,47 @@ image format. FluxEngine will use these parameters.

 ## Options

-(no options)
+  - Format variants:
+      - `auto`: try to autodetect the format (unreliable)
+      - `160`: 160kB 5.25" 40-track 8-sector SSDD
+      - `180`: 180kB 5.25" 40-track 9-sector SSDD
+      - `320`: 320kB 5.25" 40-track 8-sector DSDD
+      - `360`: 360kB 5.25" 40-track 9-sector DSDD
+      - `720_96`: 720kB 5.25" 80-track 9-sector DSDD
+      - `720_135`: 720kB 3.5" 80-track 9-sector DSDD
+      - `1200`: 1200kB 5.25" 80-track 15-sector DSHD
+      - `1232`: 1232kB 5.25" 77-track 8-sector DSHD
+      - `1440`: 1440kB 3.5" 80-track 18-sector DSHD
+      - `1680`: 1680kB 3.5" 80-track 21-sector DSHD; DMF
+
+## Examples
+
+To read:
+
+  - `fluxengine read ibm --auto -s drive:0 -o ibm.img`
+  - `fluxengine read ibm --160 -s drive:0 -o ibm.img`
+  - `fluxengine read ibm --180 -s drive:0 -o ibm.img`
+  - `fluxengine read ibm --320 -s drive:0 -o ibm.img`
+  - `fluxengine read ibm --360 -s drive:0 -o ibm.img`
+  - `fluxengine read ibm --720_96 -s drive:0 -o ibm.img`
+  - `fluxengine read ibm --720_135 -s drive:0 -o ibm.img`
+  - `fluxengine read ibm --1200 -s drive:0 -o ibm.img`
+  - `fluxengine read ibm --1232 -s drive:0 -o ibm.img`
+  - `fluxengine read ibm --1440 -s drive:0 -o ibm.img`
+  - `fluxengine read ibm --1680 -s drive:0 -o ibm.img`
+
+To write:
+
+  - `fluxengine write ibm --160 -d drive:0 -i ibm.img`
+  - `fluxengine write ibm --180 -d drive:0 -i ibm.img`
+  - `fluxengine write ibm --320 -d drive:0 -i ibm.img`
+  - `fluxengine write ibm --360 -d drive:0 -i ibm.img`
+  - `fluxengine write ibm --720_96 -d drive:0 -i ibm.img`
+  - `fluxengine write ibm --720_135 -d drive:0 -i ibm.img`
+  - `fluxengine write ibm --1200 -d drive:0 -i ibm.img`
+  - `fluxengine write ibm --1232 -d drive:0 -i ibm.img`
+  - `fluxengine write ibm --1440 -d drive:0 -i ibm.img`
+  - `fluxengine write ibm --1680 -d drive:0 -i ibm.img`

 Mixed-format disks
 ------------------
--- a/doc/disk-icl30.md
+++ b/doc/disk-icl30.md
@@ -1,5 +1,7 @@
+icl30
+====
+## CP/M; 263kB 35-track DSSD
 <!-- This file is automatically generated. Do not edit. -->
-# CP/M; 263kB 35-track DSSD

 The ICL Model 30 is a reasonably standard CP/M machine using 35-track single
 density disks and the traditional CP/M 128-byte secotrs --- 30 of them per
@@ -9,3 +11,9 @@ track! Other than that it's another IBM scheme variation.

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read icl30 -s drive:0 -o icl30.img`
+
--- a/doc/disk-mac.md
+++ b/doc/disk-mac.md
@@ -1,5 +1,7 @@
+mac
+====
+## 400kB/800kB 3.5" GCR
 <!-- This file is automatically generated. Do not edit. -->
-# 400kB/800kB 3.5" GCR

 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
@@ -36,11 +38,23 @@ standard for disk images is to omit it. If you want them, specify that you want

 ## Options

-  - Format variant:
+  - 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),
--- a/doc/disk-micropolis.md
+++ b/doc/disk-micropolis.md
@@ -1,5 +1,7 @@
+micropolis
+====
+## 100tpi MetaFloppy disks
 <!-- This file is automatically generated. Do not edit. -->
-# 100tpi MetaFloppy disks

 Micropolis MetaFloppy disks use MFM and hard sectors. Mod I was 48 TPI and
 stored 143k per side. Mod II was 100 TPI and stored 315k per side. Each of the
@@ -45,6 +47,16 @@ need to apply extra options to change the format if desired.
      - `630`: 630kB 5.25" DSDD hard-sectored; Micropolis MetaFloppy Mod II
  - `vgi`: Read/write VGI format images with 275 bytes per sector

+## Examples
+
+To read:
+
+  - `fluxengine read micropolis -s drive:0 -o micropolis.img`
+
+To write:
+
+  - `fluxengine write micropolis -d drive:0 -i micropolis.img`
+
 ## References

  - [Micropolis 1040/1050 S-100 Floppy Disk Subsystems User's Manual][micropolis1040/1050].
--- a/doc/disk-mx.md
+++ b/doc/disk-mx.md
@@ -1,5 +1,7 @@
+mx
+====
+## Soviet-era PDP-11 clone
 <!-- This file is automatically generated. Do not edit. -->
-# Soviet-era PDP-11 clone

 The DVK (in Russian, 沾7d65
 Computing Complex) was a late 1970s Soviet personal computer, a cut-down
@@ -40,7 +42,20 @@ Words are all stored little-endian.

 ## Options

-(no options)
+  - Format variants:
+      - `110`: 110kB 5.25" 40-track SSSD
+      - `220ds`: 220kB 5.25" 40-track DSSD
+      - `220ss`: 220kB 5.25" 80-track SSSD
+      - `440`: 440kB 5.25" 80-track DSSD
+
+## Examples
+
+To read:
+
+  - `fluxengine read mx --110 -s drive:0 -o mx.img`
+  - `fluxengine read mx --220ds -s drive:0 -o mx.img`
+  - `fluxengine read mx --220ss -s drive:0 -o mx.img`
+  - `fluxengine read mx --440 -s drive:0 -o mx.img`

 ## References

--- a/doc/disk-n88basic.md
+++ b/doc/disk-n88basic.md
@@ -1,5 +1,7 @@
+n88basic
+====
+## PC8800/PC98 5.25" 77-track 26-sector DSHD
 <!-- This file is automatically generated. Do not edit. -->
-# PC8800/PC98 5.25" 77-track 26-sector DSHD

 The N88-BASIC disk format is the one used by the operating system of the same
 name for the Japanese PC8800 and PC98 computers. It is another IBM scheme
@@ -12,3 +14,13 @@ boot ROM could only read single density data.)

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read n88basic -s drive:0 -o n88basic.img`
+
+To write:
+
+  - `fluxengine write n88basic -d drive:0 -i n88basic.img`
+
--- a/doc/disk-northstar.md
+++ b/doc/disk-northstar.md
@@ -1,5 +1,7 @@
+northstar
+====
+## 5.25" hard sectored
 <!-- This file is automatically generated. Do not edit. -->
-# 5.25" hard sectored

 Northstar Floppy disks use 10-sector hard sectored disks with either FM or MFM
 encoding.  They may be single- or double-sided.  Each of the 10 sectors contains
@@ -20,7 +22,24 @@ equivalent to .img images.

 ## Options

-(no options)
+  - Format variants:
+      - `87`: 87.5kB 5.25" 35-track SSSD hard-sectored
+      - `175`: 175kB 5.25" 40-track SSDD hard-sectored
+      - `350`: 350kB 5.25" 40-track DSDD hard-sectored
+
+## Examples
+
+To read:
+
+  - `fluxengine read northstar --87 -s drive:0 -o northstar.nsi`
+  - `fluxengine read northstar --175 -s drive:0 -o northstar.nsi`
+  - `fluxengine read northstar --350 -s drive:0 -o northstar.nsi`
+
+To write:
+
+  - `fluxengine write northstar --87 -d drive:0 -i northstar.nsi`
+  - `fluxengine write northstar --175 -d drive:0 -i northstar.nsi`
+  - `fluxengine write northstar --350 -d drive:0 -i northstar.nsi`

 ## References

--- a/doc/disk-psos.md
+++ b/doc/disk-psos.md
@@ -1,5 +1,7 @@
+psos
+====
+## 800kB DSDD with PHILE
 <!-- This file is automatically generated. Do not edit. -->
-# 800kB DSDD with PHILE

 pSOS was an influential real-time operating system from the 1980s, used mainly
 on 68000-based machines, lasting up until about 2000 when it was bought (and
@@ -18,3 +20,13 @@ and, oddly, swapped sides.

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read psos -s drive:0 -o pme.img`
+
+To write:
+
+  - `fluxengine write psos -d drive:0 -i pme.img`
+
--- a/doc/disk-rolandd20.md
+++ b/doc/disk-rolandd20.md
@@ -1,5 +1,7 @@
+rolandd20
+====
+## 3.5" electronic synthesiser disks
 <!-- This file is automatically generated. Do not edit. -->
-# 3.5" electronic synthesiser disks

 The Roland D20 is a classic electronic synthesiser with a built-in floppy
 drive, used for saving MIDI sequences and samples.
@@ -18,3 +20,9 @@ you know anything about it.

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read rolandd20 -s drive:0 -o rolandd20.img`
+
--- a/doc/disk-rx50.md
+++ b/doc/disk-rx50.md
@@ -1,5 +1,7 @@
+rx50
+====
+## 400kB 5.25" 80-track 10-sector SSDD
 <!-- This file is automatically generated. Do not edit. -->
-# 400kB 5.25" 80-track 10-sector SSDD

 The Digital RX50 is one of the external floppy drive units used by Digital's
 range of computers, especially the DEC Rainbow microcomputer. It is a fairly
@@ -9,3 +11,13 @@ vanilla single-sided IBM scheme variation.

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read rx50 -s drive:0 -o rx50.img`
+
+To write:
+
+  - `fluxengine write rx50 -d drive:0 -i rx50.img`
+
--- a/doc/disk-shugart_drive.md
+++ b/doc/disk-shugart_drive.md
@@ -1,4 +1,6 @@
+shugart_drive
+====
+## Adjust configuration for a Shugart drive
 <!-- This file is automatically generated. Do not edit. -->
-# Adjust configuration for a Shugart drive

 (This format has no documentation. Please file a bug.)
--- a/doc/disk-smaky6.md
+++ b/doc/disk-smaky6.md
@@ -1,5 +1,7 @@
+smaky6
+====
+## 308kB 5.25" 77-track 16-sector SSDD, hard sectored
 <!-- This file is automatically generated. Do not edit. -->
-# 308kB 5.25" 77-track 16-sector SSDD, hard sectored

 The Smaky 6 is a Swiss computer from 1978 produced by Epsitec. It's based
 around a Z80 processor and has one or two Micropolis 5.25" drives which use
@@ -20,6 +22,12 @@ this is completely correct, so don't trust it!

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read smaky6 -s drive:0 -o smaky6.img`
+
 ## References

  - [Smaky Info, 1978-2002 (in French)](https://www.smaky.ch/theme.php?id=sminfo)
--- a/doc/disk-tids990.md
+++ b/doc/disk-tids990.md
@@ -1,5 +1,7 @@
+tids990
+====
+## 1126kB 8" DSSD
 <!-- This file is automatically generated. Do not edit. -->
-# 1126kB 8" DSSD

 The Texas Instruments DS990 was a multiuser modular computing system from 1998,
 based around the TMS-9900 processor (as used by the TI-99). It had an 8" floppy
@@ -20,6 +22,16 @@ FluxEngine will read and write these (but only the DSDD MFM variant).

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read tids990 -s drive:0 -o tids990.img`
+
+To write:
+
+  - `fluxengine write tids990 -d drive:0 -i tids990.img`
+
 ## References

  - [The FD1000 Depot Maintenance
--- a/doc/disk-tiki.md
+++ b/doc/disk-tiki.md
@@ -1,5 +1,7 @@
+tiki
+====
+## CP/M
 <!-- This file is automatically generated. Do not edit. -->
-# CP/M

 The Tiki 100 is a Z80-based Norwegian microcomputer from the mid 1980s intended
 for eductional use. It mostly ran an unbranded CP/M clone, and uses fairly
@@ -8,5 +10,18 @@ on the precise format.

 ## Options

-(no options)
+  - Format variants:
+      - `90`: 90kB 40-track 18-sector SSSD
+      - `200`: 200kB 40-track 10-sector SSDD
+      - `400`: 400kB 40-track 10-sector DSDD
+      - `800`: 800kB 80-track 10-sector DSDD
+
+## Examples
+
+To read:
+
+  - `fluxengine read tiki --90 -s drive:0 -o tiki.img`
+  - `fluxengine read tiki --200 -s drive:0 -o tiki.img`
+  - `fluxengine read tiki --400 -s drive:0 -o tiki.img`
+  - `fluxengine read tiki --800 -s drive:0 -o tiki.img`

--- a/doc/disk-victor9k.md
+++ b/doc/disk-victor9k.md
@@ -1,5 +1,7 @@
+victor9k
+====
+## 1224kB 5.25" DSDD GCR
 <!-- This file is automatically generated. Do not edit. -->
-# 1224kB 5.25" DSDD GCR

 The Victor 9000 / Sirius One was a rather strange old 8086-based machine
 which used a disk format very reminiscent of the Commodore format; not a
@@ -36,7 +38,21 @@ FluxEngine can read and write both the single-sided and double-sided variants.

 ## Options

-(no options)
+  - Format variants:
+      - `612`: 612kB 80-track DSHD GCR
+      - `1224`: 1224kB 80-track DSHD GCR
+
+## Examples
+
+To read:
+
+  - `fluxengine read victor9k --612 -s drive:0 -o victor9k.img`
+  - `fluxengine read victor9k --1224 -s drive:0 -o victor9k.img`
+
+To write:
+
+  - `fluxengine write victor9k --612 -d drive:0 -i victor9k.img`
+  - `fluxengine write victor9k --1224 -d drive:0 -i victor9k.img`

 ## References

--- a/doc/disk-zilogmcz.md
+++ b/doc/disk-zilogmcz.md
@@ -1,5 +1,7 @@
+zilogmcz
+====
+## 320kB 8" 77-track SSSD hard-sectored
 <!-- This file is automatically generated. Do not edit. -->
-# 320kB 8" 77-track SSSD hard-sectored

 The Zilog MCZ is an extremely early Z80 development system, produced by
 Zilog, which came out in 1976. It used twin 8-inch hard sectored floppy
@@ -28,6 +30,12 @@ touch](https://github.com/davidgiven/fluxengine/issues/new)...

 (no options)

+## Examples
+
+To read:
+
+  - `fluxengine read zilogmcz -s drive:0 -o zilogmcz.img`
+
 ## References

  * [About the Zilog MCZ](http://www.retrotechnology.com/restore/zilog.html),