Date: Sun, 25 Jun 2000 19:53:27 +0000 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org Cc: dgl@bsdi.com, jim@cdrom.com, papowell@astart.com, wpaul@freebsd.org, ceren@magnesium.net, ryan@ryan.net, murray@bsdi.com Subject: Sharing the documentation with other systems Message-ID: <20000625195327.D470@kilt.nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
Another biggie. There are two major parts to this.
All the major free documentation projects are switching to DocBook. Some of
them are more advanced along this path than others.
So far, I think we're ahead of the curve in terms of getting the toolchain
working, and customising the output. This is work that I'd like to share
with the other documentation projects wherever possible. By and large,
we're doing that just by making the tools and infrastructure we use
available via CVSweb.
But it certainly can't hurt to have representatives from the FreeBSD
Doc. Project on other Doc. Project mailing lists to provide the benefit of
our experience where necessary. And, of course, it gives us the opportunity
to learn from what the other projects are doing.
The second part relates to the actual content.
Consider the Handbook. A glance through it will show that there's an
*awful* lot of content there that's not really FreeBSD specific. A
reasonable chunk isn't even BSD specific.
I'd like to share as much of this as possible with the other documentation
projects. Intially the other BSD projects, simply because it's going to be
easier to manage. But ultimately with some of the non-BSD documentation
projects as well.
This brings up the issue of how we distinguish the content that *is*
specific to different operating systems.
Some of you will probably recall an earlier proposal of mine to allow
documentation for various versions of FreeBSD to be embedded in the docs, in
the form of additional attributes on the majority of elements. For
example
<para osversionmin="RELENG_3" osversionmax="RELENG_4">This para
contains text that is only application to versions of FreeBSD between
3.x and 4.x.</para>
<para osversionin="RELENG_2_2_8">This para contains text that is only
applicable to FreeBSD 2.2.8.</para>
it should be relatively easy to extend this model to support different
operating systems, so that we could have NetBSD specific paragraphs,
BSD/OS specific notes, and so on.
BSD/OS will probably be the first to benefit from this. Their current
documentation set is being migrated to DocBook by Debbie, and there's
definitely content that both systems can share -- I'm waiting the final word
on this, but I hope that the BSD/OS documentation will be made available in
the same way that FreeBSD's is, and, ideally (at least I think it's ideal)
the FreeBSD Handbook and the BSD/OS equivalent can merge quite closely.
I had the opportunity to speak to Charles Hannum (NetBSD's big cheese) at
Usenix. He suggested I get in touch with www@netbsd.org to kick this idea
around with them, which I've done. If you look at the documentation on
Netbsd's site they have a document similar to the Handbook, but smaller.
However, in certain sections it's much better written than ours, and again,
large chunks of it are cross-BSD compatible. Then again, we have more
content, and more active translation teams than they do, so we've both got
reasons for collaborating.
Assuming things go well on this I'll talk to the OpenBSD folks as well. I'm
holding off at the moment simply because trying to merge three sets of docs
together is going to be bad enough, without bringing in a fourth.
However, if someone else wants to step up to the plate and do this then
please do, and feel free to bring in anyone you want.
This is also going to be affected by another on-going task, that of
splitting the Handbook up in to smaller documents. I'll talk about this in
a separate message.
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?20000625195327.D470>