From owner-freebsd-doc Tue May 4 8:37: 0 1999 Delivered-To: freebsd-doc@freebsd.org Received: from firewall2.lehman.com (firewall2.Lehman.COM [192.147.65.83]) by hub.freebsd.org (Postfix) with ESMTP id 590C715851 for ; Tue, 4 May 1999 08:36:06 -0700 (PDT) (envelope-from nclayton@lehman.com) Received: from relay.messaging-svcs2.lehman.com by firewall2.lehman.com (8.8.6/8.8.6) id LAA19570; Tue, 4 May 1999 11:36:04 -0400 (EDT) Received: from lonmailhost.lehman.com by relay.messaging-svcs2.lehman.com (8.9.3/8.8.5) id LAA17659; Tue, 4 May 1999 11:35:34 -0400 (EDT) Received: by lonmailhost.lehman.com (SMI-8.6/Lehman Bros. V1.5) id QAA19603; Tue, 4 May 1999 16:35:33 +0100 Message-ID: <19990504163533.S14492@lehman.com> Date: Tue, 4 May 1999 16:35:33 +0100 From: nclayton@lehman.com To: doc@freebsd.org Subject: doc//books/*, doc//articles/*, and docs.freebsd.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.91.1i Organization: Lehman Brothers Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org FDP folks, [ I'm sort of thinking out loud at the moment ] The doc/ directory structure is currently organised as doc//handbook doc//FAQ doc//tutorials/* where 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//books/ and doc//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//books/printing/* doc//books/security/* doc//books/FDP-primer/* ... doc//articles/FAQ/* doc//articles/fonts/* doc//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//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