Date: Wed, 13 Jun 2001 07:45:39 -0400 (EDT) From: Kenneth W Cochran <kwc@world.std.com> To: bmah@freebsd.org Cc: freebsd-stable@freebsd.org Subject: Re: RELNOTESng problems Message-ID: <200106131145.HAA08631@world.std.com> References: <200106121443.KAA18844@world.std.com>
next in thread | previous in thread | raw e-mail | index | archive | help
>To: Kenneth W Cochran <kwc@world.std.com>
>Cc: freebsd-stable@FreeBSD.ORG
>Subject: Re: RELNOTESng problems
>From: "Bruce A. Mah" <bmah@FreeBSD.ORG>
>Date: Tue, 12 Jun 2001 09:13:39 -0700
>
>If memory serves me right, Kenneth W Cochran wrote:
>> With the recent move of RELNOTESng to -stable, what do we need
>> to do to build/maintain this documentation along with source?
>
>If you want to build a copy locally, install the textproc/docproj port
>and bring in the doc-all collection from current. You got that right
>as far as I can tell.
Ok; so far so good...
>> For example, does {build,install}world take care of this?
>> (Apparently not, but I'd appreciate The Official Word(tm). :)
>
>Well, I'm the guy who designed RELNOTESng, so I guess I count as
>"official" (?!?).
Indeed. Absolutely. :)
>buildworld/installworld doesn't do this. I didn't even consider this,
>because this would make buildworld and installworld take even longer
>than they do now. :-)
Ok; makes sense. In that case some explicit instructions
as to How To Do This sould be a Good Thing(tm). :)
This rings of /stand/sysinstall, which, btw, I've seen no
instructions for building, other than the occasional
mailing-list reminder(?)
Kernel maintenance being separate from {build,install}world
is well-documented, but sysinstall & now release-docs seem
to not be. ??
>> I tried going to /usr/src/release/doc & then "make" & I'm
>> getting what appear to be build-errors. Attached are the last
>> several output lines from that make. As per instructions in
>> /usr/src/release/doc/README, I have built textproc/docproj
>> from fresh -ports & additionally brought doc-all current.
>
>We're kind of at a strange state right now; RELNOTESng for 4-STABLE is
>broken (see my earlier heads-up) due to some other commits that took me
>rather by surprise. I hope it'll get fixed soon (I know how to fix it,
>but the fix depends on one or two decisions that are out of my hands.)
Well, I'm somewhat relieved to know it's probably not (my) pilot-error... :)
>I think I know what problem you're seeing, and I can fix it after this
>other (bigger) breakage gets fixed. I have no idea why earlier testing
>didn't catch this problem. Sorry about that!
Ok; I'll be watching for updates...
>> So, to restate my question:
>> 1. How do I build/maintain -stable documentation?
>
>So far you seem to be doing the right thing.
>
>> 2. How (where) do I go to look at said documentation?
>
>When the build is done, you can point a Web browser at the subdirectorie
>s under /usr/src/release/doc/en_US.ISO_8859-1/ and read the HTML files
>there. If you did the build with additional document FORMATS (i.e "make
>'FORMATS=html pdf txt'") you'll see the other output files there as well.
Excellent; I think it would be a Good Idea(tm) to place
something like the above instructions in someplace like
src/UPDATING or src/release/texts/*. Maybe it'll help
head-off some mailing-list-semi-noise(?) :)
>Alternatively you can just read the Web versions at:
>
>http://people.freebsd.org/~bmah/relnotes/
>
>The plan is for these to be moved into a more "official" spot on the
>FreeBSD web site and automatically generated along with the Web site build.
>
>> Commentary:
>> While I think the move to RELNOTESng is probably a Good Thing,
>> I think deletion/removal of the ascii-plaintext versions from
>> src/release/texts/* is probably Not Such A Good Thing.
>> Additionally, I "question" the necessity of requiring tools
>> "outside" the base-OS solely for reading the relevant release
>> notes/errata.
>
>Noted. We debated this at some length on -doc when I was working on it.
>The outcome of this debate was that we decided to put frequently-updated
>versions of the release notes on the Web site (the URL I gave above is a
>part of my testing process). I'd rather not rehash all the arguments
>for this...you can see them in the -doc archives.
So I guessed (lotsa discussion in some place like -doc);
that's why I'm not sanguine to stirring up a ruckus,
especially here on -stable. There are Good Reasons(tm) for
having done this; I guess it's safe to say that there are
still a few "rough edges." :)
-kc
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-stable" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200106131145.HAA08631>