--- wikisrc/zfs.mdwn	2021/02/17 17:40:26	1.35
+++ wikisrc/zfs.mdwn	2021/02/17 17:44:58	1.36
@@ -8,17 +8,6 @@ emphatically not a tutorial or an introd
 Many things are marked with \todo because they need a better
 explanation, and some have question marks
 
-# Documentation Pointers
-
-See the man pages for zfs(8), zpool(8).  Also see zdb(8), if only for
-seeing pool config info when run with no arguments.
-
-  - [OpenZFS Documentation](https://openzfs.github.io/openzfs-docs/)
-  - [OpenZFS admin docs index page](https://github.com/openzfs/zfs/wiki/Admin-Documentation)
-  - [FreeBSD Handbook ZFS Chapter](https://www.freebsd.org/doc/handbook/zfs.html)
-  - [Oracle ZFS Administration Manual](https://docs.oracle.com/cd/E26505_01/html/E37384/index.html)
-  - [Wikipedia](https://en.wikipedia.org/wiki/ZFS)
-
 # Status of ZFS in NetBSD
 
 ## NetBSD 8
@@ -36,20 +25,6 @@ likely best served by the most recent ve
 branch.  As of 2021-02, ZFS in the NetBSD 9.1 release is very close to
 netbsd-9.
 
-### Native blocksize
-
-ZFS attempts to find out the native blocksize for a disk when using it
-in a pool; this is almost always 512 or 4096.  Somewhere between 9.0
-and 9.1, at least some disks on some controllers that used to report
-512 now report 4096.  This provokes a blocksize mismatch warning.
-
-Given that the native blocksize of the disk didn't change, and things
-seemed OK using the 512 emulated blocks, the warning is likely not
-critical.  However, it is also likely that rebuilding the pool with
-the 4096 blocksize is likely to result in better behavior because ZFS
-will only try to do 4096-byte writes.  \todo Verify this and find the
-actual change and explain better.
-
 ## NetBSD-current
 
 NetBSD-current (as of 2021-02) has similar ZFS code to 9.
@@ -59,12 +34,13 @@ ffs and pivoting.
 
 ## NetBSD/xen special issues
 
+Summary: if you are using NetBSD, xen and zfs, use NetBSD-current.
+
 In NetBSD-9, MAXPHYS is 64KB in most places, but because of xbd(4) it
 is set to 32KB for XEN kernels.  Thus the standard zfs kernel modules
 do not work under xen.  In NetBSD-current, xbd(4) supports 64 KB
-MAXPHYS and this is no longer an issue.
-
-Xen and zfs on current are reported to work well together, as of 2021-02.
+MAXPHYS and this is no longer an issue.  Xen and zfs on current are
+reported to work well together, as of 2021-02.
 
 ## Architectures
 
@@ -92,7 +68,18 @@ the first item is NetBSD specific.
   - Create a filesystem mounted on /n0 as "zfs create -o
     mountpoint=/n0 pool1/n0".
 
-  - Go back and read the documentation and start over.
+  - Read the documentation referenced in the next section.
+
+## Documentation Pointers
+
+See the man pages for zfs(8), zpool(8).  Also see zdb(8), if only for
+seeing pool config info when run with no arguments.
+
+  - [OpenZFS Documentation](https://openzfs.github.io/openzfs-docs/)
+  - [OpenZFS admin docs index page](https://github.com/openzfs/zfs/wiki/Admin-Documentation)
+  - [FreeBSD Handbook ZFS Chapter](https://www.freebsd.org/doc/handbook/zfs.html)
+  - [Oracle ZFS Administration Manual](https://docs.oracle.com/cd/E26505_01/html/E37384/index.html)
+  - [Wikipedia](https://en.wikipedia.org/wiki/ZFS)
 
 # NetBSD-specific information
 
@@ -113,6 +100,20 @@ areas to be included include:
 Information about created or imported pools is stored in
 /etc/zfs/zpool.cache.
 
+## pool Native blocksize mismatch
+
+ZFS attempts to find out the native blocksize for a disk when using it
+in a pool; this is almost always 512 or 4096.  Somewhere between 9.0
+and 9.1, at least some disks on some controllers that used to report
+512 now report 4096.  This provokes a blocksize mismatch warning.
+
+Given that the native blocksize of the disk didn't change, and things
+seemed OK using the 512 emulated blocks, the warning is likely not
+critical.  However, it is also likely that rebuilding the pool with
+the 4096 blocksize is likely to result in better behavior because ZFS
+will only try to do 4096-byte writes.  \todo Verify this and find the
+actual change and explain better.
+
 ## pool importing problems
 
 While one can "zpool pool0 /dev/wd0f" and have a working pool, this