RFC: Release notes rearrangement

[Christian Brueffer]

On Mon, Nov 20, 2006 at 08:01:53PM -0800, Bruce A. Mah wrote:
[...]
> 
> 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.
> 

Hmm, what I like about the current notes is that if I'm only interested
in on arch, I just get the stuff that concerns this specific arch.  From
what you describe here it sounds like this:

[i386] Some sentence applying only to i386.

[amd64] Some sentence applying only to amd64.

[arm] Some sentence applying only to arm.

[sparc64] Some sentence applying only to sparc64.

[i386] Some sentence applying only to i386.

Of course many items are general, but I think we want to avoid clutter
like this.  Do you have something in mind for this?  Maybe put all the
arch specific stuff in special arch sections below all the generic
stuff?

OTOH, maybe I've just completely misunderstood you :-)

> (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?
> 

Apart from the comment above, this sounds like a good idea.

- Christian

-- 
Christian Brueffer	chris at unixpages.org	brueffer at FreeBSD.org
GPG Key:	 http://people.freebsd.org/~brueffer/brueffer.key.asc
GPG Fingerprint: A5C8 2099 19FF AACA F41B  B29B 6C76 178C A0ED 982D
-------------- 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/20061121/728fcb5b/attachment.sig>