NetBSD Problem Report #55413

From www@netbsd.org  Wed Jun 24 10:53:49 2020
Return-Path: <www@netbsd.org>
Received: from mail.netbsd.org (mail.netbsd.org [199.233.217.200])
	(using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits))
	(Client CN "mail.NetBSD.org", Issuer "mail.NetBSD.org CA" (not verified))
	by mollari.NetBSD.org (Postfix) with ESMTPS id 75D281A9217
	for <gnats-bugs@gnats.NetBSD.org>; Wed, 24 Jun 2020 10:53:49 +0000 (UTC)
Message-Id: <20200624105348.81AC71A921F@mollari.NetBSD.org>
Date: Wed, 24 Jun 2020 10:53:48 +0000 (UTC)
From: bugcounterism@malbolge.net
Reply-To: bugcounterism@malbolge.net
To: gnats-bugs@NetBSD.org
Subject: Typos etc. in (amd64) INSTALL files for NetBSD 9.0
X-Send-Pr-Version: www-1.0

>Number:         55413
>Category:       install
>Synopsis:       Typos etc. in (amd64) INSTALL files for NetBSD 9.0
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    install-manager
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Wed Jun 24 10:55:00 +0000 2020
>Closed-Date:    
>Last-Modified:  Wed Jun 09 22:56:11 +0000 2021
>Originator:     Michael Siegel
>Release:        9.0
>Organization:
>Environment:
>Description:
I've found a few typos etc. in the HTML version of the amd64 INSTALL
file for NetBSD 9.0
(https://ftp.netbsd.org/pub/NetBSD/NetBSD-9.0/amd64/INSTALL.html).

The issues mentioned below very likely concern all four versions of the
amd64 INSTALL file. Some of them probably concern parts common to all
INSTALL files for all architectures. As I'm new to NetBSD and my time is
quite limited, I've decided to leave it to more experienced people to
find out exactly where to solve any of the problems reported here.

I'll go through the file section by section (for the most part).


A)
## Quick install notes for the impatient

  * "For third-party programs which are not part of the base NetBSD
    distribution, you will want to explore the pkgsrc package management
    system, which contains thousands of third party software 
    applications."

    * Should say "third-party software applications" at the end.

  * There is one other instance of "third party" needing to be
    "third-party" in the "Post installation steps" section.


B)
## What is NetBSD?

In the 1st sentence, I think it should be "open-source" rather than
"Open Source", i.e., lowercase, and hyphenated just like "Unix-like" in
that same sentence because "open-source" is a compound adjective.


C)
## Dedication

In the 2nd sentence of the 2nd paragraph, it should be:

  * "long-term contributor" instead of "long term contributor"

  * "weird" instead of "weired"


D)
## The NetBSD Foundation

  * "…goals and Spirit of the NetBSD Project"

    * "Spirit" should not be capitalized here.


E)
## NetBSD/amd64 System Requirements and Supported Devices

It should be "64-bit" instead of "64bit" in the first sentence.


F)
## "Getting the NetBSD System on to Useful Media"

All instances of "USB-stick" should be changed to "USB stick".


G)
## Running the sysinst installation program

  * 3. General

    * "sysinst is a menu driven program" -> "menu-driven"

  * 4. Quick install

    * Should say "installation medium" instead of "installation media"
      at the end of the 1st paragraph because the user will only use one 
      medium (i.e., singular) to install NetBSD.

    * "What you need" says "An optical drive." However, you don't need 
      an optical drive if you're installing from a USB stick.

    * "The Quick installation"

      * Says "USB memstick" at one point. I think it should be kept to 
        "USB stick" throughout the document in order not cause 
        unnecessary confusion, especially for non-native speakers of 
        English.

      * "The default values for the path and device should be ok."

	* If a bit of nitpicking is allowed, "ok" should either be "OK" 
          or "okay".

	* There are other occurrences of that in the document.

  * 5. Booting NetBSD

    * "The boot loader will start, which will print a countdown and 
      begin booting."

      * That sentence sounds a bit weird.

  * 6. Network configuration

    * "If you do not intend to use networking during the installation,
      but you do want your machine to be configured for networking once 
      it is installed…"

     * Should rather say "once NetBSD" or "once the system is 
       installed".

  * 14. Installation using FTP

    * All occurrences of "ftp" should be changed to "FTP".
>How-To-Repeat:

>Fix:
Modify the respective source files.

>Release-Note:

>Audit-Trail:
From: bugcounterism@malbolge.net
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: install/55413
Date: Tue, 25 May 2021 13:06:26 +0200

 As nearly all of those issues are still present in -current, here are
 some patches for files in src/distrib/notes/common to start fixing them:


 #1 main

 This patch fixes:

  * A), bullet point 1
  * B)
  * D)

 Index: main
 ===================================================================
 RCS file: /cvsroot/src/distrib/notes/common/main,v
 retrieving revision 1.563
 diff -u -r1.563 main
 --- main        26 Jul 2020 11:05:39 -0000      1.563
 +++ main        25 May 2021 10:28:27 -0000
 @@ -469,7 +469,7 @@
  .Nx
  distribution, you will want to explore the
  .Ic pkgsrc
 -package management system, which contains thousands of third party
 software +package management system, which contains thousands of
 third-party software applications.
  .El
  .\}
 @@ -478,11 +478,9 @@
  .
  The
  .Nx
 -Operating System is a fully functional
 -.Tn Open Source
 -.Ul
 -operating system derived from the University of California, Berkeley
 -Networking Release 2 (Net/2), 4.4BSD-Lite, and 4.4BSD-Lite2 sources.
 +Operating System is a fully functional open-source operating system
 derived +from the University of California, Berkeley Networking Release
 2 (Net/2), +4.4BSD-Lite, and 4.4BSD-Lite2 sources.
  .Nx
  runs on many different different system architectures (ports)
  across a variety of distinct CPU families, and is being ported to more.
 @@ -589,7 +587,7 @@
  The
  .Nx
  Foundation is a tax exempt, not-for-profit 501(c)(3) corporation
 -that devotes itself to the traditional goals and Spirit of the
 +that devotes itself to the traditional goals and spirit of the
  .Nx
  Project and owns the trademark of the word
  .Dq NetBSD .


 #2 postinstall

 This patch fixes:

   * A), bullet point 2

 Index: postinstall
 ===================================================================
 RCS file: /cvsroot/src/distrib/notes/common/postinstall,v
 retrieving revision 1.88
 diff -u -r1.88 postinstall
 --- postinstall 21 Oct 2020 07:46:22 -0000      1.88
 +++ postinstall 25 May 2021 10:36:15 -0000
 @@ -308,7 +308,7 @@
  .\}
  .\}
  .It
 -Installing third party packages
 +Installing third-party packages
  .Pp
  If you wish to install any of the software freely available for
  .Ul


 #3 sysinst

 This patch fixes:

   * G)
     * 3.
     * 4., bullet points 3.1 and 3.2.1
     * 14.

 Index: sysinst
 ===================================================================
 RCS file: /cvsroot/src/distrib/notes/common/sysinst,v
 retrieving revision 1.110
 diff -u -r1.110 sysinst
 --- sysinst	27 Nov 2019 09:29:25 -0000	1.110
 +++ sysinst	25 May 2021 10:45:56 -0000
 @@ -149,7 +149,7 @@
  .Nx
  on your hard disk.
  .Ic sysinst
 -is a menu driven program that guides you through the installation
 process. +is a menu-driven program that guides you through the
 installation process. Sometimes questions will be asked, and in many
 cases the default answer will be displayed in brackets
  .Pq Dq \&[\ ]
 @@ -402,7 +402,7 @@
  .ie \n[alpha]:\n[amd64]:\n[i386] \{\
  Insert the CD into the drive
  .if \n[amd64]:\n[i386] \{\
 -or the USB memstick into an available USB port
 +or the USB stick into an available USB port
  .\}
  and boot the computer from it.
  .if \n[alpha] \{\
 @@ -1381,7 +1381,7 @@
  .
  .Pp
  You will then be asked to name your disk's disklabel.
 -The default response will be ok for most purposes.
 +The default response will be OK for most purposes.
  If you choose to name it something different, make sure the name
  is a single word and contains no special characters.
  You don't need to remember this name.
 @@ -1473,7 +1473,7 @@
  .To 2 "Installation using FTP"
  .Em Installation using FTP
  .Pp
 -To install using ftp, you first need to configure
 +To install using FTP, you first need to configure
  your network setup if you haven't already done so.
  .Ic sysinst
  will help you with this, asking if you want to use DHCP.
 @@ -1487,9 +1487,9 @@
  You will also be asked to specify the host that you want
  to transfer the sets from, the directory on that host,
  the account name and password used to log into that
 -host using ftp, and optionally a proxy server to use.
 +host using FTP, and optionally a proxy server to use.
  If you did not set up DNS, you will need to
 -specify an IP address instead of a hostname for the ftp
 +specify an IP address instead of a hostname for the FTP
  server.
  .Pp
  .Ic sysinst


 #4 xfer

 This patch fixes:

   * F)

 Index: xfer
 ===================================================================
 RCS file: /cvsroot/src/distrib/notes/common/xfer,v
 retrieving revision 1.76
 diff -u -r1.76 xfer
 --- xfer        21 Nov 2019 19:23:17 -0000      1.76
 +++ xfer        25 May 2021 10:33:48 -0000
 @@ -39,7 +39,7 @@
  .It
  .\} \" \n[amiga]
  .
 -CD-ROM / DVD / USB-stick
 +CD-ROM / DVD / USB stick
  .
  .It
  FTP
 @@ -83,7 +83,7 @@
  .Note)
  .\}
  .
 -.(tag CD-ROM\ /\ DVD\ /\ USB-stick
 +.(tag CD-ROM\ /\ DVD\ /\ USB stick
  .
  .if \n[amiga] \{\
  .It Em AmigaDOS partition
 @@ -103,7 +103,7 @@
  step in the installation process, preparing your hard disk.
  .\} \" \n[amiga]
  .
 -.It Em CD-ROM / DVD / USB-stick
 +.It Em CD-ROM / DVD / USB stick
  .if \n[amiga] \{\
  To install
  .Nx


 Also, C) is now irrelevant because it was specific to the 9.0 release.

From: "Martin Husemann" <martin@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/55413 CVS commit: src/distrib/notes/common
Date: Thu, 27 May 2021 15:47:42 +0000

 Module Name:	src
 Committed By:	martin
 Date:		Thu May 27 15:47:42 UTC 2021

 Modified Files:
 	src/distrib/notes/common: main postinstall sysinst xfer

 Log Message:
 Consistency and typo/grammar fixes from Michael Siegel in PR 55413,
 With minor adjustments.


 To generate a diff of this commit:
 cvs rdiff -u -r1.563 -r1.564 src/distrib/notes/common/main
 cvs rdiff -u -r1.88 -r1.89 src/distrib/notes/common/postinstall
 cvs rdiff -u -r1.110 -r1.111 src/distrib/notes/common/sysinst
 cvs rdiff -u -r1.76 -r1.77 src/distrib/notes/common/xfer

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

From: Michael Siegel <bugcounterism@malbolge.net>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: install/55413 (More patches)
Date: Thu, 27 May 2021 23:13:38 +0200

 Two additional patches:


 #5 amd64/hardware

 This patch fixes:

   * E)

 Index: hardware
 ===================================================================
 RCS file: /cvsroot/src/distrib/notes/amd64/hardware,v
 retrieving revision 1.1
 diff -u -r1.1 hardware
 --- hardware	21 Aug 2005 18:35:26 -0000	1.1
 +++ hardware	27 May 2021 20:37:33 -0000
 @@ -1,6 +1,6 @@
  .\"$NetBSD: hardware,v 1.1 2005/08/21 18:35:26 riz Exp $
  .
  .Nx*M
 -supports CPUs that implement the 64bit AMD64 architecture.
 +supports CPUs that implement the 64-bit AMD64 architecture.
  These currently include AMD Opteron, AMD Athlon64, and Intel CPUs that 
  implement the EM64T extension.


 #6 sysinst

 This patch fixes:

   * G)
     * 4., bullet point 3.2.2
     * 6.

 Index: sysinst
 ===================================================================
 RCS file: /cvsroot/src/distrib/notes/common/sysinst,v
 retrieving revision 1.111
 diff -u -r1.111 sysinst
 --- sysinst	27 May 2021 15:47:42 -0000	1.111
 +++ sysinst	27 May 2021 20:48:02 -0000
 @@ -509,7 +509,7 @@
  When prompted, choose
  .Me CD-ROM
  as the install medium if booted from CD-ROM.
 -The default values for the path and device should be ok.
 +The default values for the path and device should be OK.
  .if \n[amd64]:\n[i386] \{\
  If you booted using a USB image, choose
  .Me Local directory .
 @@ -745,7 +745,7 @@
  .Pp
  If you do not intend to use networking during the installation,
  but you do want your machine to be configured for networking once
 -it is installed, you should first go to the
 +the system is installed, you should first go to the
  .Me Utility menu
  and select the
  .Me Configure network
 @@ -1287,7 +1287,7 @@
  to pick the operating system to start up when your computer
  is (re-)started.
  .Pp
 -If everything is ok, you can go on to the next step,
 +If everything is OK, you can go on to the next step,
  editing the
  .Nx
  disklabel.

From: "Martin Husemann" <martin@netbsd.org>
To: gnats-bugs@gnats.NetBSD.org
Cc: 
Subject: PR/55413 CVS commit: src/distrib/notes
Date: Fri, 28 May 2021 13:55:25 +0000

 Module Name:	src
 Committed By:	martin
 Date:		Fri May 28 13:55:25 UTC 2021

 Modified Files:
 	src/distrib/notes/amd64: hardware
 	src/distrib/notes/common: sysinst

 Log Message:
 PR 55413: 64-bit and OK police; grammar improvements.
 From Michael Siegel.


 To generate a diff of this commit:
 cvs rdiff -u -r1.1 -r1.2 src/distrib/notes/amd64/hardware
 cvs rdiff -u -r1.111 -r1.112 src/distrib/notes/common/sysinst

 Please note that diffs are not public domain; they are subject to the
 copyright notices on the relevant files.

State-Changed-From-To: open->feedback
State-Changed-By: dholland@NetBSD.org
State-Changed-When: Wed, 09 Jun 2021 17:05:12 +0000
State-Changed-Why:
done?


From: Michael Siegel <bugcounterism@malbolge.net>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: install/55413 (More problems)
Date: Wed, 9 Jun 2021 19:34:13 +0200

 I've had another look at G), 4., bullet point 2.

 In -current, the relevant portion of text now looks as follows:

   First, let's describe a quick install. The other sections of this
   document go into the installation procedure in more detail, but you
   may find that you do not need this. If you want detailed
   instructions, skip to the next section. This section describes a
   basic installation, using a CD / DVD (or USB stick) as the install
   medium.

     What you need.

       - The distribution sets (in this example, they are on the CD or
         DVD).

       - An optical drive.

       - A hard drive with at least 700 MB of free space for a complete
         base install, not including room for swap. If you wish to
         install the X Window System as well, you will need at least
         225 MB more. 

 The only two non-problematic adjustments I'd make here are these:

 Index: sysinst
 ===================================================================
 RCS file: /cvsroot/src/distrib/notes/common/sysinst,v
 retrieving revision 1.112
 diff -u -r1.112 sysinst
 --- sysinst	28 May 2021 13:55:24 -0000	1.112
 +++ sysinst	31 May 2021 15:55:05 -0000
 @@ -169,8 +169,8 @@
  The other sections of this document go into the installation procedure in more
  detail, but you may find that you do not need this.
  If you want detailed instructions, skip to the next section.
 -This section describes a basic installation, using a CD / DVD
 -.if \n[i386]:\n[amd64] (or USB stick)
 +This section describes a basic installation, using a CD/DVD
 +.if \n[i386]:\n[amd64] or a USB stick
  as the install medium.
  .Pp
  .(bullet


 The rest would need some investigation.

 H)
   - The distribution sets (in this example, they are on the CD or
     DVD).
     --> s/CD or DVD/installation medium

   Some architectures, e.g., acorn32, arc, and atari seem to require
   using a mix of floppy discs and optical discs for installation that
   is really not clear to me. That makes it kind of hard to tell if the
   suggested substitution would break things.

 I)
   - An optical drive.

   At least for architectures that also support installing from a USB
   stick, this should rather say

     - An optical drive or a free USB port.

   Now, it seems as if the INSTALL files for all architectures that use
   sysinst (or have it documented), claim that you need an optical
   drive. I wonder whether that is actually adequate.

State-Changed-From-To: feedback->open
State-Changed-By: dholland@NetBSD.org
State-Changed-When: Wed, 09 Jun 2021 22:56:11 +0000
State-Changed-Why:
not yet


>Unformatted:

Home	PR Database Search