Merge from trunk.

doc/building.md

@@ -292,7 +292,7 @@ INDEX300 ---+ 3.0|     | GND+--------------------------+
             +----+     +----+                 +--+--+  |
 INDEX360 ---+ 3.1|     | 1.7+------ DISKCHG --+34+33+--+
             +----+     +----+                 +--+--+
-            + 3.2|     | 1.6+------- SIDE1 ---+32+31+
+    TK43 ---+ 3.2|     | 1.6+------- SIDE1 ---+32+31+
             +----+     +----+                 +--+--+
             + 3.3|     | 1.5+------- RDATA ---+30+29+
             +----+     +----+                 +--+--+
@@ -306,7 +306,7 @@ INDEX360 ---+ 3.1|     | 1.7+------ DISKCHG --+34+33+--+
             +----+     +----+                 +--+--+
             +15.0|     | 1.0+------- STEP ----+20+19+
             +----+     +----+                 +--+--+
-            +15.1|     |12.0+-------- DIR ----+18+17+
+            +15.1|     |12.0+--- DIR/SIDE1 ---+18+17+
             +----+     +----+                 +--+--+
             +15.2|     |12.1+------- MOTEB ---+16+15+
             +----+     +----+                 +--+--+
@@ -343,6 +343,10 @@ INDEX360 ---+ 3.1|     | 1.7+------ DISKCHG --+34+33+--+
 
 Notes:
 
+  - `DIR/SIDE1` is the step direction pin. During reads or writes, `SIDE1` is
+  also multiplexed onto it, because some drives expect this. This is harmless
+  on other drives because the `DIR` pin is ignored during reads or writes.
+
   - `TX` is the debug UART port. It's on pin 12.7 because the board routes it
   to the USB serial port on the programmer, so you can get debug information
   from the FluxEngine by just plugging the programming end into a USB port
@@ -365,6 +369,10 @@ Notes:
   rather exotic things. See the section on flippy disks [in the FAQ](faq.md)
   for more details; you can normally ignore these.
 
+  - `TK43` is an optional output pin which goes low when the drive is seeking
+  to track 43 or above. This is useful when using 8" floppy drives, which
+  require reduced write current when writing to these tracks.
+
 ## Next steps
 
 You should now be ready to go. You'll want to read [the client

doc/disk-trs80.md

@@ -32,3 +32,11 @@ If you've got a 40-track disk, use `-s :t=0-79x2`.
 
 If you've got a single density disk, use `--read-fm=true`. (Double density is
 the default.)
+
+
+Useful references
+-----------------
+
+  - [The JV3 file format](https://www.tim-mann.org/trs80/dskspec.html):
+	documents the most popular emulator disk image.
+

doc/using.md

@@ -136,6 +136,10 @@ exact format varies according to the extension:
 	format due to the weird layout of Mac GCR disks, but it can also support
 	720kB and 1440kB IBM disks (although there's no real benefit).
 
+  - `.jv3`: a disk image format mainly used by the TRS-80. These images can be
+	read, but not yet written. You only get the data; the density and DAM bits
+	are ignored.
+
 ### High density disks
 
 High density disks use a different magnetic medium to low and double density
@@ -228,21 +232,16 @@ directory.
 	format in a non-backwards-compatible way; this tool will upgrade flux files
 	to the new format.
 
-  - `fluxengine convert`: converts flux files from various formats to various
-	other formats. You can use this to convert Catweasel flux files to
+  - `fluxengine convert`: converts files from various formats to various other
+	formats. The main use of this is probably `fluxengine convert image`, which
+	will convert a disk image from one format to another.
+
+	There are also subcommands for converting Catweasel flux files to
 	FluxEngine's native format, FluxEngine flux files to various other formats
 	useful for debugging (including VCD which can be loaded into
 	[sigrok](http://sigrok.org)), and bidirectional conversion to and from
 	Supercard Pro `.scp` format.
 
-	**Important SCP note:** import (`fluxengine convert scptoflux`) should be
-	fairly robust, but export (`fluxengine convert fluxtoscp`) should only be
-	done with great caution as FluxEngine files contain features which can't be
-	represented very well in `.scp` format and they're probably pretty dubious.
-	As ever, please [get in
-	touch](https://github.com/davidgiven/fluxengine/issues/new) with any
-	reports.
-
 Commands which normally take `--source` or `--dest` get a sensible default if
 left unspecified. `fluxengine read ibm` on its own will read drive 0 and
 write an `ibm.img` file.