Subject: INSTALL thoughts
To: None <>
From: James K. Lowden <>
List: netbsd-docs
Date: 10/29/2006 22:22:47

I'm upgrading to 3.0 and noticed a few things in INSTALL.html, ranging
from the trivial to the confusing.  I thought I'd mention them here in
case anyone else thinks they should be fixed, too.   

1.	"As is usual between releases, the i386 port has had many improvements
made to it--too many to detail all of them here."

Couldn't we get '&mdash;' in there instead of the typewriter's '--'

2.  It's not clear to me if the xfont set is used by the client or server.
 I want to support X clients, but I'm never going to run a server on this

3.  It's not clear what install kernel I'd use on my Soekris box with its
serial console. 

4.	"#( cd /usr/pkgsrc ; tar -zxpf - ) < pkgsrc.tar.gz "

Typographically, this command should be in boldface (like the one above
it).  But for my money it's over-fancy, confusing, and old-fashioned.  I
would say:

	# cd /usr/pkgsrc
	# pax -rzpe -f pkgsrc.tar.gz
(or)	# tar -xzp  -f pkgsrc.tar.gz

5.	"Many of the /etc files are documented in section 5"

I checked.  On my 2.0 system, 45 of 80 files in /etc are documented. 
Some, like "weekly" probably don't need to be.  I think we can say "Most
files" or even "Files in /etc are documented in section 5".  (IMHO any
significant file in /etc lacking a man page is a flaw.)  

6.  Under "Issues fixed by postinstall" there's one bullet point, and if
the indentation is taken literally (so to speak) it would seem that the
fixed issues include "The following issues need to be resolved manually". 
This would be clearer if there were two headings: files updated/created by
postinstall, and those not.  As is, it's a bit clumsy.  

7.  The tone varies a bit from novice hand-holding to
one-expert-to-another.  For example, "Change to the /etc directory and
take a look at the /etc/rc.conf file. Modify it to your tastes" comes
before mentioning that vi won't run without /usr being mounted (and
explaining how to do that, bravo).  And "More complete documentation can
be found in rc.conf(5)" comes before the section that describes how the
manual is organized and how to use man(1).  I'd be willing to try to
improve it.  

8.  There's a claim that "We are planning future support for many of these
devices" beneath a list that includes QIC-40 and QIC-80 tape drives.  Is
it credible?  

9.  I am glad for the list of versions of 3rd party software included.  I
wish for a file /etc/3rd_party.txt (or a 3party(1) man page) that
documented them on installed systems.  It's not easy (afaik) to discover
what version of BIND or tcpdump is installed.  

That's what I came up with.  Thanks for listening.