From owner-freebsd-stable Wed Jun 13 4:45:49 2001 Delivered-To: freebsd-stable@freebsd.org Received: from sgi04-e.std.com (sgi04-e.std.com [199.172.62.134]) by hub.freebsd.org (Postfix) with ESMTP id 9475837B401; Wed, 13 Jun 2001 04:45:43 -0700 (PDT) (envelope-from kwc@world.std.com) Received: from world.std.com (world-f.std.com [199.172.62.5]) by sgi04-e.std.com (8.9.3/8.9.3) with ESMTP id HAA7455613; Wed, 13 Jun 2001 07:45:41 -0400 (EDT) Received: (from kwc@localhost) by world.std.com (8.9.3/8.9.3) id HAA08631; Wed, 13 Jun 2001 07:45:39 -0400 (EDT) Date: Wed, 13 Jun 2001 07:45:39 -0400 (EDT) From: Kenneth W Cochran Message-Id: <200106131145.HAA08631@world.std.com> To: bmah@freebsd.org Subject: Re: RELNOTESng problems Cc: freebsd-stable@freebsd.org References: <200106121443.KAA18844@world.std.com> Sender: owner-freebsd-stable@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.ORG >To: Kenneth W Cochran >Cc: freebsd-stable@FreeBSD.ORG >Subject: Re: RELNOTESng problems >From: "Bruce A. Mah" >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