Date: Sun, 9 May 1999 01:15:27 +0200 From: Wolfram Schneider <wosch@panke.de.freebsd.org> To: nclayton@lehman.com, doc@FreeBSD.ORG Cc: cvs@FreeBSD.ORG Subject: Re: doc/<lang>/books/*, doc/<lang>/articles/*, and docs.freebsd.org Message-ID: <19990509011527.18124@panke.de.freebsd.org> In-Reply-To: <19990504163533.S14492@lehman.com>; from nclayton@lehman.com on Tue, May 04, 1999 at 04:35:33PM %2B0100 References: <19990504163533.S14492@lehman.com>
next in thread | previous in thread | raw e-mail | index | archive | help
[cc: cvs masters] On 1999-05-04 16:35:33 +0100, nclayton@lehman.com wrote: > 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? This is a nightmare for the webmaster and the cvs masters. CVS does not handle directory moves well. > 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 is Makefile problem, not a directory structure. > 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. Hm, you are renaming 'handbook' to 'books' and 'tutorials' to 'articles'???? > 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 doubt that the symlinks are a real problem. `make world' also create a lot of symlinks. If you think replacing symlinks with directories will fix a bug, you should contact Bruce so he can improve make world ;-) Building the website from scratch is not so hard: $ cvs co www doc && cd www && make && cd en && make all install > 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. Our documentation is tiny, compared with docs.sun.com I see now reason why we should move the handbook from www.freebsd.org to docs.freebsd.org > 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. I'm still fixing the broken links from the linuxdoc to docbook conversions, the list of redirects doubled in size ;-( -- Wolfram Schneider <wosch@freebsd.org> http://wolfram.schneider.org 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?19990509011527.18124>