Date: Tue, 9 Nov 1999 13:41:31 -0800 (PST) From: Kris Kennaway <kris@hub.freebsd.org> To: doc@freebsd.org Subject: Re: Outdated version information Message-ID: <Pine.BSF.4.10.9911091329590.47956-100000@hub.freebsd.org> In-Reply-To: <Pine.BSF.4.10.9911081218100.38503-100000@hub.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, 8 Nov 1999, Kris Kennaway wrote: > Hmm, every time I happen to look at the FAQ/handbook/website to locate > information for someone I seem to find another case of an outdated FreeBSD > version being referred to as current (this time: > http://www.freebsd.org/FAQ/preface.html#AEN53). > > We really need a system whereby these will be flagged and/or updated > automatically each time a new release comes around. Perhaps by tagging > sections related to a particular release and then "aging" them somehow, or > presenting them on a list of "things to be checked that they're still > current" - I don't know enough about the specifics of the build mechanism > to suggest an explicit solution, but I'm sure one of you guys do. I was thinking about this and came up with the following: We add a new SGML tag called "volatile" or something, which has parametrs "ID" and "Level". This is purely meta-information and has no effect on the rendered version of the document. ID is for distinguishing between different volatile blocks for external reference, and "Level" is the expected frequency of change of the information, which can be thought of as a priority for checking whether it remains valid. ID would be (say) a 64-bit random string generated by the user when the tag is added (making it random means you don't have to deal with an external "namespace authority" or fit the numbering scheme by hand, which doesn't deal well with deletion of items in the sequence). Things like references to current versions of FreeBSD, "this is expected to be the case in a future version", etc, would be marked as being volatile, and an external database would index these and allow people to "approve" the assertions (indexed by the volatility level) as still being valid for FreeBSD x.y (if not, they'd go in and make any necessary changes and then approve the fixed block, or remove it altogether). The simpler alternative is that we could just add a "current stable version" tag which resolves to e.g. "3.3" to superficially deal with old version numbers remaining in the handbook, but the danger is that just renumbering 3.3 to 3.4 doesn't deal with any associated semantic changes - i.e. the statement may NOT be valid for 3.4 and having it say so just adds to the confusion of the reader who assumes it was intentionally written that way. The only real solution is to present these to a human for approval. Can anyone think of a better way to accomplish the goal, or suggestions as to how to implement the above? Kris ---- Cthulhu for President! For when you're tired of choosing the _lesser_ of two evils.. 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?Pine.BSF.4.10.9911091329590.47956-100000>