>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
>Closed-Date:
>Last-Modified:
>Originator:     Brian A. Seklecki
>Release:        -current
>Organization:
Spiritual Machines
>Environment:
N/A
>Description:
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 netbsd-docs@netbsd.org which includes positive feedback from the RAIDFrame maintainer.

http://mail-index.netbsd.org/netbsd-docs/2004/09/

---------------------------------
All:

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
http://www.neverland.ch/netbsd/ (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). 
>How-To-Repeat:
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.
>Fix:
Apply the patch.  There's a bzip2'd unified diff against chap-rf.xml above.
>Release-Note:
>Audit-Trail:
>Unformatted:
 >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:
 
 http://digitalfreaks.org/~lavalamp/htdocs/guide/en/chap-rf.html
 
 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 
 htdocs/share/mk/doc.docbook.xsl.mk:
 
 [...snip...]
 
 # for common
 XSL_DBX_WITH_MANIFEST?=                                 
 XSL_DBX_WITH_GENERATE_SECTION_TOC_LEVEL?=               
 XSL_DBX_WITH_TOC_SECTION_DEPTH?=                        
 XSL_DBX_WITH_TOC_MAX_DEPTH?=                            
 XSL_DBX_WITH_SECTION_AUTOLABEL?=                        
 XSL_DBX_WITH_SECTION_LABEL_INCLUDES_COMPONENT_LABEL?=   
 
 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
 material.
 
 Files:
 
 http://digitalfreaks.org/~lavalamp/chap-rf.xml.bz2
 http://digitalfreaks.org/~lavalamp/chap-rf_1.18.diff.bz2
 http://digitalfreaks.org/~lavalamp/nbsd_rfgi_r1r_overview.dia.bz2
 http://digitalfreaks.org/~lavalamp/awardbios1.png.bz2
 http://digitalfreaks.org/~lavalamp/awardbios1.png.bz2
 
 TIA,
 ~Brian