NetBSD Guide: Issues with Chapter 2

[Michael Siegel <msi%malbolge.net@localhost>]

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