Date: Wed, 10 Nov 1999 08:01:54 +0000 From: Nik Clayton <nik@freebsd.org> To: Kris Kennaway <kris@hub.freebsd.org> Cc: doc@freebsd.org Subject: Re: Outdated version information Message-ID: <19991110080153.A90762@kilt.nothing-going-on.org> In-Reply-To: <Pine.BSF.4.10.9911091329590.47956-100000@hub.freebsd.org>; from Kris Kennaway on Tue, Nov 09, 1999 at 01:41:31PM -0800 References: <Pine.BSF.4.10.9911081218100.38503-100000@hub.freebsd.org> <Pine.BSF.4.10.9911091329590.47956-100000@hub.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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.
<snip>
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
<note osversionequal="RELENG_2_2_RELEASE">
<para>Yada yada, only applies to 2.2</para>
</note>
<para osversionmin="RELENG_2_0_RELEASE"
osversionmax="RELENG_3_0_RELEASE">Yada yada, applies to all versions
between 2.2 and 3.0, inclusive.</para>
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.
<ENTITY release.22 "RELENG_2_2_RELEASE">
<note osversionequal="&release.22">
...
</note>
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.
<para osversionequal="RELENG_2_2_RELEASE">Some text...</para>
might be converted to
<p><b>2.2-RELEASE only:</b> Some text...</para>
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19991110080153.A90762>