Date: Thu, 21 Dec 2000 13:53:40 +0000 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org Subject: Version specific documentation Message-ID: <20001221135340.B61525@canyon.nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
Hopefully some of you remember my ramblings for allowing us to version
content in the documentation.
Specifically, I've talked about extending DocBook with 3 new attributes
on each element;
osversionmin Minimum version of FreeBSD this text applies to
osversionmax Maximum version of FreeBSD this text applies to
osversionin List of FreeBSD versions this text applies to
First, let me make clear that those names are *not* set in stone. In
particular, it precludes other projects (such as GNOME or KDE) from
picking up our changes and using them to handle differences between the
documentation for their different releases. Perhaps s/subj/os/ where
"subj" means the subject of the document.
However, for the purposes of testing they'll do for the time being.
If you pull down
http://people.freebsd.org/~nik/faq.test.tar.gz
and extract it under doc/en*/books/ you'll have a faq.test directory.
In there is a very simple book.sgml, a Makefile, and a freebsd.dsl that
contains logic to handle osversionmin and osversionmax (osversionin is
left as an exercise for the reader). To use it, edit the definition of
'for-release' in freebsd.dsl, and 'make' the documentation. You'll see
paragraphs coming and going depending on the version you want.
[ Variable names like "for-release" in the code are also bad. Something
like "for-version" or similar would be better. I'll clean that up
later. ]
Currently, these are just proof of concept, but it's sufficient to show
that, using DSSSL, we can programmatically include or exclude certain
elements based on their attributes, and a mechanism for doing so.
The main problem with this at the moment is that it lets you write
things like
==
Example 1.
<para osversionmax="RELENG_2_2_8_RELEASE">SCSI devices have a
<filename>/dev/sd</filename> prefix.</para>
<para osversionmin="RELENG_3_0_0_RELEASE">SCSI devices have a
<filename>/dev/da</filename> prefix.</para>
==
or
==
Example 2.
<para>SCSI devices have a
<filename osversionmax="RELENG_2_2_8_RELEASE">/dev/sd</filename>
<filename osversionmin="RELENG_3_0_0_RELEASE">/dev/da</filename>
prefix.</para>
==
Which one do we use?
Personally, I think we should always use the style in Example 1. The
reason for this is that Example 1 allows the end user to build a
document that contains information appropriate for both versions,
Example 2 doesn't. I can see a need for wanting to build a FAQ or
Handbook that covers each version of FreeBSD. If that's the case, the
stylesheets should automatically preceed the text with something like
FreeBSD 2.2.8 and below: SCSI devices have a /dev/sd prefix.
FreeBSD 3.0.0 and up: SCSI devices have a /dev/da prefix.
(in the same way that using the <note> element includes a "Note: "
before your text -- naturally there are i18n issues to consider here).
That's going to look damn silly with example 2.
SCSI devices have a FreeBSD 2.2.8 and below: /dev/sd FreeBSD 3.0.0
and up /dev/da prefix.
This will entail some rewriting as we do this. For example the first
paragraph of;
http://www.freebsd.org/FAQ/install.html#FLOPPY-DOWNLOAD
would have to become two paras, one for 3.0 and below, one for 3.1 and
up (exactly as I describe above).
http://www.freebsd.org/FAQ/install.html#INSTALL-BAD-BLOCKS
is another example of something that can benefit from this treatment.
Thoughts? Talented DSSSL hackers who want to finish this for me?
N
--
Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95.
Telephone line, $24.95 a month. Software, free. USENET transmission,
hundreds if not thousands of dollars. Thinking before posting, priceless.
Somethings in life you can't buy. For everything else, there's MasterCard.
-- Graham Reed, in the Scary Devil Monastery
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?20001221135340.B61525>