Date: Sat, 06 Jan 2001 09:35:30 -0800 From: bmah@freebsd.org (Bruce A. Mah) To: Wilko Bulte <wkb@freebie.demon.nl> Cc: "Bruce A. Mah" <bmah@freebsd.org>, freebsd-doc@freebsd.org, wilko@freebsd.org Subject: Re: RELNOTESng update Message-ID: <200101061735.f06HZUg34503@bmah-freebsd-0.cisco.com> In-Reply-To: <20010106001658.A70625@freebie.demon.nl> References: <200101051950.f05Jo0H24919@bmah-freebsd-0.cisco.com> <20010106001658.A70625@freebie.demon.nl>
next in thread | previous in thread | raw e-mail | index | archive | help
--==_Exmh_994126474P
Content-Type: text/plain; charset=us-ascii
If memory serves me right, Wilko Bulte wrote:
> On Fri, Jan 05, 2001 at 11:50:00AM -0800, Bruce A. Mah wrote:
> > 1. Conditional text so we can support multiple architectures from one
> > set of source files (no more editing {i386,alpha}/RELNOTES.TXT).
>
> Yes!
I knew you would like this part. :-)
> > 2. The Supported Hardware lists from HARDWARE.TXT and RELNOTES.TXT
> > have been combined.
>
> For alpha I have my doubts about this. There is far too much
> untested hardware on alpha, and experience has shown that x86 != alpha
> even when would expect no cpu-port specifics. This is fundamental
> problem because we lack a wide alpha user base. And hence lack widespread
> testing of hardware.
Perhaps I was unclear. The problem I was trying to address was that a
device we support could show up in at least four places:
src/release/texts/HARDWARE.TXT
src/release/texts/alpha/RELNOTES.TXT
src/release/texts/i386/RELNOTES.TXT
doc/en_US.ISO_8859-1/books/handbook/install
Ergo, if we start supporting a new device, we need to edit as many as
four files, and that's *before* the translation teams get to the
handbook.
Jim Mock was talking about nuking the section of the handbook with this
information. I support this. For the remaining three TXT files, my
goal was to take the union of HARDWARE.TXT and i386/RELNOTES.TXT (which
should be, but are not, consistent), and to use conditionals to make the
result consistent with alpha/RELNOTES.TXT when we build for that
platform. The result is that we only have *one* source file for our
Supported Hardware list. (Note that this doesn't preclude the
information showing up in multiple documents, should we want this.)
If you're concerned that some people have been adding devices to the
alpha list without actually verifying whether or not they work, mea
culpa, I've probably done this. In the future, new devices get
surrounded by the appropriate conditional unless there's strong reason
to believe they've actually been tested on multiple architectures. An
example of where (I think) this is done right is the Adaptec SCSI
controllers, as well as the newer RAID controllers.
I *think* this addresses your concern above. It not, could you clarify?
> > 3. DocBook markup, so we can generate release notes in multiple
> > formats.
>
> Good idea.
Except that our release notes are now 40+ pages long in PDF format. :-p
> > At this point I would like to get some input from people. In
> > particular:
> >
> > 1. First and foremost, is the concept a Good Thing(TM)? I'm pretty
> > convinced we need something like this (particularly to deal with
> > multiple architectures and information listed in various places). But
> > if the consensus is "no", I want to bail out now.
>
> For me it is a good thing.
>
> > 2. Since I only use i386 architecture machines, I want to make sure
> > we can cover the alpha (and later the ia64, sparc, ppc, or whatever
> > else turns up). So I'd like some alpha folks to look their version
> > over. One question I'd like to get answered: The alpha has its own
> > HARDWARE.TXT file listing different processor/motherboard notes. I'd
> > like to know people's thoughts about folding this in as well
> > (particularly from Wilko, since he's maintaining it).
>
> I'm more than willing to convert alpha/HARDWARE.TXT into the right
> input format. Assuming I'm allowed to bug someone about the right formatting
> tools etc ;-)
I learned from reading Nik's FDP Primer. IMHO, DocBook/SGML is like
HTML with different (and more) tags. (Pause for groans from the "real"
-doc committers.) If you bug me, at least you'll get another newbie's
perspective.
> I do not want to pull the HW.TXT into the Relnotes. I don't think that this
> is a good idea. For me release notes are a thing that should be as small and
> comprehensive as possible. More static info, like details on hardware
> support etc, should be kept seperate.
I was leaning towards putting everything in a single file, but my
enthusiasm for this is starting to wane. It sounds like you would like
the Supported Hardware list out of the release notes and have the users
read this in exactly one document, which would be analogous to
HARDWARE.TXT (and which would also contain the content from alpha/
HARDWARE.TXT). Is that right? I think I could go for that, but I'd
like to hear from Nik and Jordan as well.
Doing this will mean generalizing the infrastructure I've set up so
that it can handle multiple documents. But that's not necessarily bad.
While we're at it, we could think about supporting eventual
translations. (Pause for groans from the translation teams.)
> > 3. At some point, I'll need to talk to someone who's familiar with
> > "make release" to see about how to integrate this into the build. It'll
>
> You want someone to look at that, no doubt. I've had some, um, interesting
> discussions with David when I screwed up the release makefile during
> introduction of alpha's HW.TXT. My bad, but not something to repeat.
Oh yeah, gonna try real hard not to break release or world.
Thanks!
Bruce.
--==_Exmh_994126474P
Content-Type: application/pgp-signature
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.4 (FreeBSD)
Comment: Exmh version 2.2 06/23/2000
iD8DBQE6V1di2MoxcVugUsMRAizcAKD7SBgwqaHdlL3VIlSel9AMVeCKkwCglT8j
zb2ZDk74DIpLp0hLRhNunkQ=
=l6pA
-----END PGP SIGNATURE-----
--==_Exmh_994126474P--
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?200101061735.f06HZUg34503>