Date: Tue, 24 Apr 2001 09:03:10 -0700 From: bmah@freebsd.org (Bruce A. Mah) To: freebsd-current@freebsd.org Cc: bmah@freebsd.org, freebsd-doc@freebsd.org Subject: [RFC] RELNOTESng for 5-CURRENT Message-ID: <200104241603.f3OG3AB06290@bmah-freebsd-0.cisco.com>
next in thread | raw e-mail | index | archive | help
--==_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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200104241603.f3OG3AB06290>