Date: Thu, 26 Oct 2000 12:15:40 -0700 From: bmah@freebsd.org (Bruce A. Mah) To: freebsd-doc@freebsd.org Cc: bmah@freebsd.org Subject: HARDWARE.TXT and RELNOTES.TXT Message-ID: <200010261915.e9QJFep73565@bmah-freebsd-0.cisco.com>
next in thread | raw e-mail | index | archive | help
--==_Exmh_1609580408P Content-Type: text/plain; charset=us-ascii Hi folks-- Here's some problems I've been having trying to maintain the RELNOTES.TXT and HARDWARE.TXT files, and a couple of random ideas about how to solve them. In case you aren't familiar with them, they are ASCII text files (in src/release/texts) that change fairly rapidly as new features and bugfixes are applied to FreeBSD. I've been committing most of the changes to them as of late, although I encourage developers to write their own release notes for their features and commit them themselves. For reasons that elude me, we have two different RELNOTES.TXT files per release (one for the i386 and one for the alpha, which contain similar, but slightly different contents). Frequently, I have four different emacs windows open to commit changes to the i386 and alpha files for both 5-CURRENT and 4-STABLE. We're on our way to having ia64 support in the not-too-distant future, and I keep hearing rumbles about ppc and sparc support as well. Clearly the current release notes aren't going to scale well. We also have problems keeping the RELNOTES.TXT files in sync with HARDWARE.TXT, which I just-rediscovered after adding some data for uscanner(4). (The RELNOTES.TXT files each have what-should-be-a-copy of some sections of HARDWARE.TXT included within them.) I'd really like to have one set of release notes and one list of supported hardware per release. To generate the architecture-specific release notes, there would have to be some conditionals in the text, which would then get run through a preprocessor. Since I'm really a coder-type person, I thought in terms of cpp(1) directives, like this: #ifdef alpha_docs Feature that only applies to the alpha. #endif alpha_docs #ifdef ia64_docs Feature that only applies to the ia64. #endif ia64_docs Then I could build appropriate outputs with: % cpp < relnotes.txt1 -Dalpha_docs > alpha/RELNOTES.TXT % cpp < relnotes.txt1 -Dia64_docs > ia64/RELNOTES.TXT I've generated window manager configs like this for years, but to do this for documentation seems like a real hack. However, I was wondering if we could do something like this with DocBook to generate the release notes? Pros: 1. We would be able to collapse several (which depends on the number of architectures we support) files that need to be edited regularly down to a constant number (hardware list and release notes). 2. We would be able to generate release notes in PDF, PS, HTML, etc. Cons: 1. I'm not sure how to do this in DocBook. 2. We would need to make the DocBook toolchain part of "make release". (Well, in a sense it is already, but in addition to having the Handbook and FAQ depend on the toolchain's presence, we'd also make the release notes dependent on this too. I don't think this is a Good Thing (TM).) 3. Doing release notes in DocBook might "raise the bar" to people committing their own release notes. Thoughts? Thanks for reading this far in any case... Bruce. --==_Exmh_1609580408P Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.4 (FreeBSD) Comment: Exmh version 2.2 06/23/2000 iD8DBQE5+ILc2MoxcVugUsMRAhsJAKCIbLcLKQYcetClq5+gzHS/uozZIgCg1Qah o3dtwgjFIDEOofpq9vnLqJg= =QX1t -----END PGP SIGNATURE----- --==_Exmh_1609580408P-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200010261915.e9QJFep73565>