From owner-freebsd-doc@FreeBSD.ORG Tue Nov 21 04:01:54 2006 Return-Path: X-Original-To: freebsd-doc@freebsd.org Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id B5B9E16A403; Tue, 21 Nov 2006 04:01:54 +0000 (UTC) (envelope-from bmah@freebsd.org) Received: from b.mail.sonic.net (b.mail.sonic.net [64.142.19.5]) by mx1.FreeBSD.org (Postfix) with ESMTP id 9141B43D5A; Tue, 21 Nov 2006 04:01:34 +0000 (GMT) (envelope-from bmah@freebsd.org) Received: from tomcat.kitchenlab.org (tomcat.kitchenlab.org [64.142.31.107]) by b.mail.sonic.net (8.13.8.Beta0-Sonic/8.13.7) with ESMTP id kAL41s3x013096 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 20 Nov 2006 20:01:54 -0800 Received: from tomcat.kitchenlab.org (localhost.kitchenlab.org [127.0.0.1]) by tomcat.kitchenlab.org (8.13.8/8.13.8) with ESMTP id kAL41rc3017943; Mon, 20 Nov 2006 20:01:53 -0800 (PST) (envelope-from bmah@freebsd.org) Received: (from bmah@localhost) by tomcat.kitchenlab.org (8.13.8/8.13.8/Submit) id kAL41rhW017942; Mon, 20 Nov 2006 20:01:53 -0800 (PST) (envelope-from bmah@freebsd.org) X-Authentication-Warning: tomcat.kitchenlab.org: bmah set sender to bmah@freebsd.org using -f Date: Mon, 20 Nov 2006 20:01:53 -0800 From: "Bruce A. Mah" To: freebsd-doc@freebsd.org Message-ID: <20061121040153.GA17933@tomcat.kitchenlab.org> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="BOKacYhQ+x31HxR3" Content-Disposition: inline X-Image-Url: http://www.kitchenlab.org/~bmah/Images/bmah-cisco-small.gif X-url: http://www.kitchenlab.org/~bmah/ User-Agent: Mutt/1.5.13 (2006-08-11) Cc: bmah@freebsd.org Subject: RFC: Release notes rearrangement X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 21 Nov 2006 04:01:54 -0000 --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 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--