From owner-freebsd-doc Wed Nov 10 12:21:49 1999 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id 2641114D92; Wed, 10 Nov 1999 12:21:04 -0800 (PST) (envelope-from nik@nothing-going-on.demon.co.uk) Received: from kilt.nothing-going-on.org (kilt.nothing-going-on.org [192.168.1.18]) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) with ESMTP id TAA54908; Wed, 10 Nov 1999 19:47:05 GMT (envelope-from nik@catkin.nothing-going-on.org) Received: (from nik@localhost) by kilt.nothing-going-on.org (8.9.3/8.9.3) id IAA90788; Wed, 10 Nov 1999 08:01:54 GMT (envelope-from nik@catkin.nothing-going-on.org) Date: Wed, 10 Nov 1999 08:01:54 +0000 From: Nik Clayton To: Kris Kennaway Cc: doc@freebsd.org Subject: Re: Outdated version information Message-ID: <19991110080153.A90762@kilt.nothing-going-on.org> References: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.95.4i In-Reply-To: ; from Kris Kennaway on Tue, Nov 09, 1999 at 01:41:31PM -0800 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Tue, Nov 09, 1999 at 01:41:31PM -0800, Kris Kennaway wrote: > > 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. I'll be writing this up more fully later, but in a nutshell, the plan is to modify DocBook to add three new attributes to each element, osversionmin, osversionmax, osversionequal. Usage is something like Yada yada, only applies to 2.2 Yada yada, applies to all versions between 2.2 and 3.0, inclusive. I may have got the release tag names wrong, but you can see the general idea. We'll probably also have a bunch of entities to minimise typing. ... or similar. Then, before producing the formatted output we run the text through a pre-processor that encodes the logic for determining the sort order of the release tags. The pre-processor spits out text without certain elements included, depending on the command line options passed. We could (possibly) also have the stylesheets look for these attributes, and automatically include certain pieces of text as well. Some text... might be converted to

2.2-RELEASE only: Some text... Credit for this overall idea goes to the Debian folks, we've only refined it somewhat, and made some of the concepts more OS neutral. They're happy to use this approach for their documentation as well, so we'll have two documentation projects that are using the same attribute names -- this should hopefully be enough to get other projects onboard as well. N -- If you want to imagine the future, imagine a tennis show stamping on a penguin's face forever. --- with apologies to George Orwell To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message