Hello, going through the NetBSD Guide a bit, recently, I found some problems that should be fixed.
I've already sent a few diffs to www@ for non-controversial fixes. Some problems and their possible solutions need a bit of review and, maybe, discussion, however. So, here are my notes on "Chapter 2. Installing NetBSD: Preliminary considerations and preparations"[1]: #1 Concerning the listing in "2.2.4. Network settings", I'd say that the first list item should not start with a capital letter. I.e., it should say "your" instead of "Your". As far as I know, the rules for writing lists in English are: a) Do as you please. b) Be consistent. Now, the list in question is written with punctuation omitted and most items not having their first word capitalized. Therefore, "Your" should become "your". #2a The heading of section 2.2.6. reads: Preparing the installation media This should, I think, be changed to one of: * Preparing the installation medium * Preparing installation media The reason for this is that a user will only use one installation medium at a time to set up NetBSD. #2b The same problem occurs within the actual text of section 2.2.6. The 1st paragraph contains the sentence: This kernel contains the NetBSD install program sysinst and it is booted from the install media (e.g, CD/DVD, USB drive, memory card, etc.). It should be "medium" because you'd be using one of "CD/DVD, USB drive…". (Just noticed it's also got to be "(e.g., CD/DVD…".) The 2nd paragraph then says: sysinst will usually fetch these files from the install media you booted from Again, I'd say: "media" -> "medium". You just don't boot from "install media". #3a This is about section "2.2.6.1. Booting the install system from USB". The first sentence here says: To use a bootable USB install image (on amd64, i386), download the img.gz file for your hardware architecture, decompress and copy the image to a USB. As I have recently pointed out in #netbsd on Freenode, the last part of that sentence provokes the question: "USB what?" I still think that presuming that this is a non-issue because it's common parlance is not a good idea. In fact, taking this issue seriously is actually a chance to make NetBSDs documentation way better in one particular respect. The reason it says just "USB" in that sentence is, obviously, that umass(4) supports a ton of different devices. This should simply be explained then. Will any USB-connected device work? If not, are there some that are generally not going to work? Etc. And while I'm at it, I think that the distinction between booting from CD/DVD or "USB" is structurally flawed. I mean, I'm pretty sure, I could download a NetBSD installation image, `dd' it to a spare internal hard drive, and boot from that. #3b The example `dd' command given in section 2.2.6.1 is: dd if=NetBSD-9.0-amd64-install.img of=/dev/your-usb bs=2m The text above it states that this will work "on a Unix-like system", which suggests it will do that on just about any Unix-like system. It will, however, not work on Linux, as far as I can see: # dd --version dd (coreutils) 8.26 Copyright (C) 2016 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses /gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Written by Paul Rubin, David MacKenzie, and Stuart Kemp # dd if=NetBSD-9.0-amd64-uefi-install.img of=/dev/sdb bs=2m dd: invalid number: '2m' You'll need to say "2M" instead of "2m". On NetBSD, on the other hand, saying "2M" will make `dd' reply with: block size '2M': illegal number The OpenBSD FAQ warns about this[2], and so should the NetBSD Guide. Okay, so much for my notes on Chapter 2. Looking forward to the discussion. --Michael [1] https://www.netbsd.org/docs/guide/en/chap-inst.html [2] https://www.openbsd.org/faq/faq4.html#MkInsMedia
