Date: Mon, 20 Nov 2006 20:01:53 -0800 From: "Bruce A. Mah" <bmah@freebsd.org> To: freebsd-doc@freebsd.org Cc: bmah@freebsd.org Subject: RFC: Release notes rearrangement Message-ID: <20061121040153.GA17933@tomcat.kitchenlab.org>
next in thread | raw e-mail | index | archive | help
--BOKacYhQ+x31HxR3
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
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=3D"
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
=66rom 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.
--BOKacYhQ+x31HxR3
Content-Type: application/pgp-signature
Content-Disposition: inline
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (FreeBSD)
iD8DBQFFYnov2MoxcVugUsMRAtm4AJ9pJX34ma+Nv++sGWepn7yPXNAzkwCeJjDl
T5VAb2UyNxYb0KZKbu8+sL4=
=P3G8
-----END PGP SIGNATURE-----
--BOKacYhQ+x31HxR3--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20061121040153.GA17933>