(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

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,


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

I'd very much like to get comments from people.


PGP signature

Reply via email to