Subject: misc/27059: NetBSD Guide chap-rf overhaul commit request
To: None <gnats-bugs@gnats.NetBSD.org>
From: None <lavalamp@spiritual-machines.org>
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
>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