From owner-freebsd-current Tue Apr 24 9: 3:26 2001 Delivered-To: freebsd-current@freebsd.org Received: from sj-msg-core-4.cisco.com (sj-msg-core-4.cisco.com [171.71.163.10]) by hub.freebsd.org (Postfix) with ESMTP id F04FC37B422; Tue, 24 Apr 2001 09:03:10 -0700 (PDT) (envelope-from bmah@cisco.com) Received: from bmah-freebsd-0.cisco.com (bmah-freebsd-0.cisco.com [171.70.84.42]) by sj-msg-core-4.cisco.com (8.9.3/8.9.1) with ESMTP id JAA22394; Tue, 24 Apr 2001 09:03:15 -0700 (PDT) Received: (from bmah@localhost) by bmah-freebsd-0.cisco.com (8.11.3/8.11.1) id f3OG3AB06290; Tue, 24 Apr 2001 09:03:10 -0700 (PDT) (envelope-from bmah) Message-Id: <200104241603.f3OG3AB06290@bmah-freebsd-0.cisco.com> X-Mailer: exmh version 2.3.1 01/19/2001 with nmh-1.0.4 To: freebsd-current@freebsd.org Cc: bmah@freebsd.org, freebsd-doc@freebsd.org Subject: [RFC] RELNOTESng for 5-CURRENT From: bmah@freebsd.org (Bruce A. Mah) Reply-To: bmah@freebsd.org X-Face: g~c`.{#4q0"(V*b#g[i~rXgm*w;:nMfz%_RZLma)UgGN&=j`5vXoU^@n5v4:OO)c["!w)nD/!!~e4Sj7LiT'6*wZ83454H""lb{CC%T37O!!'S$S&D}sem7I[A 2V%N&+ X-Image-Url: http://www.employees.org/~bmah/Images/bmah-cisco-small.gif X-Url: http://www.employees.org/~bmah/ Mime-Version: 1.0 Content-Type: multipart/signed; boundary="==_Exmh_-1738867376P"; micalg=pgp-sha1; protocol="application/pgp-signature" Content-Transfer-Encoding: 7bit Date: Tue, 24 Apr 2001 09:03:10 -0700 Sender: owner-freebsd-current@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG --==_Exmh_-1738867376P Content-Type: text/plain; charset=us-ascii (Apologies to -doc people who have probably heard this ad nauseum.) Over the past few months, I've been working on a project that I've taken to calling RELNOTESng, which is the overhaul of RELNOTES.TXT and related files that we package along with a FreeBSD distribution. I've been soliciting feedback from the other -doc folks, and it's time to socialize this out to a wider audience. The main problem this is intended to solve is that there's a lot of information in many different files, and not all of its is consistent. For example, a list of hardware supported by FreeBSD can currently be found in four different places (the alpha and i386 RELNOTES.TXT files, HARDWARE.TXT, and the Handbook). What I've done is to reorganize and reformat all of the *.TXT files. The new versions of these files are done in DocBook/SGML, which is the markup language used for the Handbook, FAQ, and so on. This gives us several distinct advantages: 1. By using conditional inclusion of text, we can have one set of source files that contains platform-independent text plus text applicable to particular architectures (no more double commits for each new release note). Looking down the road, when we support other architectures (for example, ia64 or ppc), we'll have a scalable way of handling them. 2. By going to DocBook, we can produce release notes in formats other than plain ASCII text; for example, we can do HTML or PDF. We gain greater readability, plus we can take advantages of features such as hyperlinks within documents. Of course the boot floppies still get the TXT files. 3. By adopting the same naming conventions and directory structures as the doc/ subtree, we can support translations of release notes, if the translation teams are so inclined. 4. Reorganizing the *.TXT files elminates some redundant information and reduces the number of files that people have to read through (they're a bit longer, but better-organized). There are two disadvantages to going this route. I think they're fairly minor: 1. Generating a set of release notes requires the DocBook toolchain to be built, as well as the doc/ subtree. Note that RELNOTESng will have absolutely no effect on the buildworld/installworld procedure. 2. It raises the bar a bit for committers wanting to make changes to the release notes, since they'll need to make changes to the DocBook files. Barring objections, I want to commit RELNOTESng, plus a patch to src/ release/Makefile, to the CVS tree. RELNOTESng still needs a bit of testing, and so for now, I have it controlled by a make(1) flag defaulting to off. Once the bugs have been shaken out, I'll make RELNOTESng the default and stop maintaining the *.TXT files. Eventually, the *.TXT files will get removed. There's a snapshot of RELNOTESng for -CURRENT, updated irregularly, at: http://people.freebsd.org/~bmah/relnotes/ It contains PDF, HTML, and TXT versions of the various documents, as well as a tarball of my working sources, the patch for src/release/Makefile to integrate RELNOTESng into the release build, and an ISO of a 5.0-CURRENT, i386 release I did with RELNOTESng enabled. I'd very much like to get comments from people. Bruce. --==_Exmh_-1738867376P Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.4 (FreeBSD) Comment: Exmh version 2.2 06/23/2000 iD8DBQE65aO+2MoxcVugUsMRAu8kAKCVOBVKdM053tgWJEc4j/ptcuiNlgCg8JhQ enjK7AXO/LlN5Uz1G4LLsy4= =jhEY -----END PGP SIGNATURE----- --==_Exmh_-1738867376P-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-current" in the body of the message