Subject: misc/27059: NetBSD Guide chap-rf overhaul commit request
To: None <>
From: None <>
List: netbsd-bugs
Date: 09/28/2004 03:09:26
>Number:         27059
>Category:       misc
>Synopsis:       NetBSD Guide chap-rf overhaul commit request
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    misc-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Tue Sep 28 03:10:00 UTC 2004
>Originator:     Brian A. Seklecki
>Release:        -current
Spiritual Machines
This is an official request to commit a massive revision to chap-rf.xml in the NetBSD Guide doc / htdocs module.

See the thread in which includes positive feedback from the RAIDFrame maintainer.


I've composed a large revision to the RAIDFrame document.  It merges
into Martti Kuparinen's existing document much content from a similar
document I wrote in Sep/Nov 2002, as well as the original document at (in CC:)

Most important changes:

*) It is no longer strictly a RAID-1 root example.  It is a general
RAIDFrame oriented document with one example and room for expansion.

*) The RAID-1 Root instructions have become platform independent, with
both i386 and sparc64 specific caveats.

*) 1.6.x series notes have been removed in preparation for the NetBSD
2.x release.

*) A few cheap illustrations have been added.

A list of to-do's:

*) Audit for consistent use of terminology such as 'drive', 'component',
'volume', 'set", 'mirror'

*) Audit use of <note> v.s. <replaceable> + {} syntax for platform
specific /dev devices. 

*) Clean up XML indentation (shiftwidth=4 --> shiftwidth=2) -- After the
second <sect1>, it's bad; real bad(R)

*) Re-add Dump-to-raw-SWAP-offset calculation instructions.

*) some &man; macros fail -- atactl(8), disklabel(8), installboot(8). 
More than likely the commiter will simply exclude the illustration images because they were not made in TGIF.  I've yet to determine if Dia (Gnome) can export to a compatable file format, or hear any feedback on whether PNG images or DIA diagrams could potentially be an acceptable format for the Guide moving forward.
Apply the patch.  There's a bzip2'd unified diff against chap-rf.xml above.
 >From the makefile, it seems to be a macro, but perhaps there's a
 database of permitted entries somewhere that I missed?
 *) GIF insead of PNG for images?  Images were created using "dia".
 I have posted a viewable copy at:
 This copy reflects some changes to NetBSD.css that I recommended due the
 amount of screen output / user input.  I'm still looking for feedback on
 this.  This copy also features another makefile change permitting both
 the main and in-chapter TOCs to descend to <sect3>...defined in 
 # for common
 I've uploaded both my chap-rf.xml and a patch against
 htdocs/guide/en/chap-rf.xml rev 1.18, however since the patch is larger
 than the file...
 Right now I'm looking for people to help test and proofread the new