RFC: Release notes rearrangement

[Bruce A. Mah]

Executive summary: Some parts of the release documentation
(specifically release notes, hardware list, and installation guide)
have machine-dependent (MD) versions for each architecture.  The
current scheme was developed by me when we supported two
architectures, but this doesn't scale very well to the half-dozen or
so we now support.  I want to rearrange the release documentation so
that there exists only one machine-independent (MI) version for all
documents.  This would apply only to HEAD, no effect on RELENG_[456].

Long version: The release notes, hardware list, and installation guide
are all MD documents, in that they rely on conditional inclusion of
text to custom-tailor versions of each document for different
architectures.  Thus, the i386 release notes are different from the
amd64 release notes, etc.  I designed this arrangement to mimic the
original {i386,alpha}/RELNOTES.TXT files in FreeBSD 4.X.

This worked moderately well when we supported two architectures, but
we now support six in HEAD (amd64, i386, ia64, pc98, powerpc, and
sparc64), with two more (sun4v and arm) coming along well enough that
we may need to think about release documentation for them as well.
There are several limitations with the current scheme:

1.  It's hard to work with multiple versions of documents, especially
    when it comes to editing and proofreading (one really needs to
    look at multiple versions).

2.  The implementation of the conditional text scheme is limited (it's
    not possible to exclude sections of text, or any SGML elements
    that could affect numbering of sections).  This limits the ways in
    which we can use it.

3.  The Web site and other collections of documents need to support
    the various architectures explicitly.

4.  There is not a single file to which we can point users, saying
    "here are the release notes (or hardware list or installation
    guide) for this version of FreeBSD".  It's difficult for
    users to see all of the changes that took place for a given
    version of FreeBSD.

To address these problems I'd like to collapse all of the MD documents
into a single set of MI documents.  For paragraphs (sections,
whatever) that only apply to given architectures, we'd simply add
in-line text indicating this, something like:

	[i386] Some sentence applying only to i386.

(As a point of reference, the main part of the release notes on HEAD,
new.sgml, contains 353 <para> elements, of which 27 have MD "arch="
properties  So more than 90% of the paragraphs in the release notes
are common to all architectures anyway.)

I want to start first with the release notes because this change would
be the most straight-forward for that document.  The hardware list is
similar, although it has MD sections of text that would need to be
organized into some reasonable document structure.  I think that the
install guide really needs to be rewritten; I actually have some work
from a few years ago in this direction that gave me the idea for MI
release documentation in the first place.

Comments?

Thanks in advance,

Bruce.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20061120/d0ca69ae/attachment.sig>