Subject: Re: chap-rf.xml overhaul -- testers & proof reading?
To: Christoph Kaegi <>
From: Brian A. Seklecki <>
List: netbsd-docs
Date: 09/07/2004 22:50:06
On Mon, 2004-09-06 at 10:12, Christoph Kaegi wrote:
> Quoting Brian A. Seklecki (


Thank you very much for your feedback.  I have fixed the errors that you
have noted.  Another set of eyes is always best for catching such
mistakes.  I have standardized the use of Component and Disk names.  I
have also reformatted the document with VIM options  expandtab,
softtabstop=2, textwidth=72 per the XML stipulations and have
standardized use of Component/Device names. (Someone explain to me why
we're wrapping at 72 instead of 80 chars?)  The only issue remaining are
the figures/images, which may require a separate thread.  There is
certainly no way that I can translate output form an Award or AMI BIOS
Setup screens on a PC Weasel terminal into TGIF or TeX format.  I'd
rather there be *no* illustrations if have to convert my material.  

I have CC'd Greg Oster per your suggestion to make him aware of this

> > I have posted a viewable copy at:
> > 
> >
> I've attached my notes with typos, questions and other thoughts 
> to this mail.


NOTES & Comments

>>  23.1.1
>>   superfluos word in "... You should be posses some ..."


>> 23.1.2
>>   missing word in "Finally, with regard 'high availability'"


>> 23.1.3
>>   Mailing Lists: Maybe a disclaimer could be made that RAIDFrame
>>   has undergone various developments and old advice on a mailing
>>   list is not necessarily valid anymore.

Added. Good call.

        <caution><para>Because RAIDFrame is constantly undergoing
        development, some information in mailing list archives has the
        potential of being dated and inaccurate.</para></caution>

>> 23.2.1
>>   Static mappings between bus addresses and device nodes: 
>>   I'm not sure, this is needed anymore. I thought I read
>>   something about this beeing not needed anymore, but
>>   can't find written evidence right now

Well, on a system with a single RAID set, the in-RAID auto config magic
works.  But imagine a system with multiple RAID sets, some configuring
on rc.d from /etc/raid[0-9].conf, with multiple controllers, multiple
buses, etc. ... if Component Disk at SCSI ID 0 Bus 0 dies and the system
reboots, every other disk gets offset by 1.  Could be disastrous.

This is why I advocate for the Solaris style /dev system for disks


>>   typo in "... Once you have complete this process ..."


>> 23.2.2
>>   Shouldn't the sentence "If your system has a Uninterpretable Power
>>   read: "If your system has an Uninterruptable Power Supply..." ?
>>   double word in "... On systems without redundant power, the the

Yes, "an" instead of "a" before any word beginning with a vowel. 

>> 23.3
>>   missing comma in "o Or, in the unlikely event..."
>>   superfluos word in "... other RAID levels of RAID should be..."
>>   not clear to me: "... the process will brach separating platform
dependant steps."
>>   did you mean:    "... the process will branch into separate,
platform dependant steps." ?

Yes I taken this approach.  The original material is grammatically
correct, however less easier to translate (English is extremely

>> 23.3.1
>>   unfinished word: "... so the follow pseudo process has become..."
>>   I'd extend step 2. into "... to setup a RAID Set composed of Disk1
and a nonexisting Disk (wd9)"

I'm undecided on this.  Looking into it now.

>>   Add step 2b: "copy the NetBSD System over from Disk0 to the newly
created RAID Set"
>> Figure 23.2
>>   Description of second disk should be "wd1 /", I guess, not "wd / 0"
>> Figure 23.5 Missing?

I have unified the component references.

>> 23.3.2
>>   duplicate word in "... accomplished by teaching the the 1st stage
boot ..."
>>   I'd move the "Note ... If you are using SCSI..." down below the
actual dmesg excerpt.  
>>   or somewhere else *not* following the "These disks are identified


>> 23.3.3
>>   missing words at "... you should examine the and fdisk(8) /

More &man.* macro fixes.

>> 23.3.4
>>   at the end, just before 23.3.5: The Note paragraph begins with
"Note: ..."
>>   which is redundant after the "Note" heading

Fixed.  Error due to verbatim import of original document material.

>> 23.3.5
>>   missing word at "Regardless, a device node in /dev for must exist."

Fixed with <filename>

>> 23.3.6
>>   You note, that the example shown is unrealistic. I'd lose the
Caution Note
>>   and just use a realistic example.
>>   I mean, almost every NetBSD User will want to compile at least a
>>   kernel and install sources into /usr/src, not to mention pkgsrc.
I'd include
>>   /usr and /var Filesystems. But that's just me.
>>   The reference to the Install Guide (did you mean the NetBSD Guide?
Could be
>>   a link then) for other than basic partitioning is a good idea

I went with the "create a link/xref" option because I want to keep these
examples as simplistic as possible for the sake of simplification.

>> 23.3.7
>>   missing words at "... This can be done using or."
>>   missing word at "... installboot(8), this no longer the case."

Fixed both of these by adding &man macro defitions to

>> 23.3.9
>>   redundant word in "Once are you are certain..."


>> 23.3.10
>>   typo and (maybe) missing coma in "... ensure that you system's


>>   Wouldn't it be possible, instead of mangling BIOS Settings on i386
to just
>>   enter "boot hd1a:netbsd" on the second stage Boot menu, in order to
>>   boot from the second disk?

Yes, if a component is failing due to bad sectors, certainly the first
few blocks are readable enough to get boot magic.  However, one point
that I placed a greater amount of emphasis on in my original document
was that:

"At any point, a component sufficiently functional to read 1st and 2nd
stage boot blocks" must be accessible by the BIOS or PROM.

>>   typo in "controller/bus/drive assignments indpendant of..."


>>   typo in "devalias to confirm that both disk are bootable:"


>> Figure ??.?

This was actually a problem with a <title> inside a <figure> not being
closed, probably something related to many regexp i ran through VIM.

>>   The last figure in the document has no name
>>   In this figure, the bottom text should read 
>>   "Volume with correct Component0", I presume

> I'd consider to let Greg Oster review the document also, as he
> is obviously very intimate with RAIDFrame.
> I hope, I could help a bit.
> Many regards from Switzerland
> Chris