Date: Tue, 4 May 1999 16:35:33 +0100 From: nclayton@lehman.com To: doc@freebsd.org Subject: doc/<lang>/books/*, doc/<lang>/articles/*, and docs.freebsd.org Message-ID: <19990504163533.S14492@lehman.com>
next in thread | raw e-mail | index | archive | help
FDP folks,
[ I'm sort of thinking out loud at the moment ]
The doc/ directory structure is currently organised as
doc/<lang>/handbook
doc/<lang>/FAQ
doc/<lang>/tutorials/*
where <lang> is the appropriate language code (ignore doc/FAQ/* for the
time being, it's migrating soon-ish).
In addition, there's a doc/share/mk and a doc/share/sgml for language
independent bits and pieces.
I'm wondering whether it's worthwhile migrating the existing
content to a doc/<lang>/books/ and doc/<lang>/articles/ directory
structure instead?
Specifically, I'm not happy about the FAQ and the Handbook being a
directory level higher than the other content. It's not 'clean', and
it means that any automated tools to process the documentation
have to consider either the FAQ and Handbook as special cases, or the
tutorials as a special case instead.
This will get worse when I (and anyone else that wants to help) start
splitting the Handbook up into separate, smaller, books[1]. Where does
the new content go?
I think this then allows for things like
doc/<lang>/books/printing/*
doc/<lang>/books/security/*
doc/<lang>/books/FDP-primer/*
...
doc/<lang>/articles/FAQ/*
doc/<lang>/articles/fonts/*
doc/<lang>/articles/ip-aliasing/*
...
and so on.
This sort of thing could be done as part of the DocBook conversion --
instead of doing it in-place, the results of the conversion are placed in
the new directories, in the same way that doc/handbook/ was migrated to
doc/en/handbook/.
This wouldn't happen overnight, and I'm not advocating changing the URLs
on the website.
Yet.
This brings me on to my second point. docs.freebsd.org.
At the moment the FDP doc/ tree and the www/ tree sit a little uneasily
together. Building the website requires that the doc/ tree be available
as well, and in the process all sorts of symlinks are created and little
hacks exist in several Makefiles to get the build to work properly.
It's all fairly fragile, and I'd be happier if it was a little more
separate.
I think that in an ideal world we'd also have a doc/<lang>/www/ tree
which would contain *just* those pieces of infrastructure necessary to
support a docs.freebsd.org which had a front-end that listed the available
documentation, linked to it, and let the user search it. In the fullness
of time (once the technology's mature) it might support XML in some way
as well.
For an idea of what I'm thinking of, take a look at http://docs.sun.com/.
Take their "Hardware" and "Software" headings and replace them with
"Books" and "Articles", and it's pretty close to the end product I have
in mind.
Of course, we don't have to do either one of these. But to my mind,
docs.freebsd.org becomes that bit easier to create (and automate) if
the directory structure's a bit more rigid.
Of course, this does bring up some issues. Two immediately spring to
mind.
The first is mirroring -- we already have many mirror sites who mirror
www.freebsd.org around the world. Would they be prepared to mirror
docs.freebsd.org as well? The only way to find out is to ask, which is
part of the reason for this message.
The second is URLs changing -- in an ideal world, once you've published a
URL it stays the same forever, otherwise you get link rot. But you can
get around this by remapping URLs on the webserver, so that
www.freebsd.org/handbook/foo.html
is automatically mapped to
docs.freebsd.org/books/handbook/foo.html
instead.
Thoughts?
N
--
--+==[ Systems Administrator, Year 2000 Test Lab, Lehman Brothers, Inc. ]==+--
--+==[ 1 Broadgate, London, EC2M 7HA 0171-601-0011 x5514 ]==+--
--+==[ Year 2000 Testing: It's about time. . . ]==+--
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?19990504163533.S14492>