From owner-freebsd-doc Mon May 10 2:46:51 1999 Delivered-To: freebsd-doc@freebsd.org Received: from firewall1.lehman.com (firewall1.Lehman.COM [192.147.65.82]) by hub.freebsd.org (Postfix) with ESMTP id 3CB0114DEA; Mon, 10 May 1999 02:46:41 -0700 (PDT) (envelope-from nclayton@lehman.com) Received: from relay.messaging-svcs2.lehman.com by firewall1.lehman.com (8.8.6/8.8.6) id FAA10486; Mon, 10 May 1999 05:46:38 -0400 (EDT) Received: from lonmailhost.lehman.com by relay.messaging-svcs2.lehman.com (8.9.3/8.8.5) id FAA17726; Mon, 10 May 1999 05:46:07 -0400 (EDT) Received: by lonmailhost.lehman.com (SMI-8.6/Lehman Bros. V1.5) id KAA16662; Mon, 10 May 1999 10:46:05 +0100 Message-ID: <19990510104605.D14492@lehman.com> Date: Mon, 10 May 1999 10:46:05 +0100 From: nclayton@lehman.com To: Wolfram Schneider , doc@FreeBSD.ORG Cc: cvs@FreeBSD.ORG Subject: Re: doc//books/*, doc//articles/*, and docs.freebsd.org References: <19990504163533.S14492@lehman.com> <19990509011527.18124@panke.de.freebsd.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.91.1i In-Reply-To: <19990509011527.18124@panke.de.freebsd.org>; from Wolfram Schneider on Sun, May 09, 1999 at 01:15:27AM +0200 Organization: Lehman Brothers Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Sun, May 09, 1999 at 01:15:27AM +0200, Wolfram Schneider wrote: > On 1999-05-04 16:35:33 +0100, nclayton@lehman.com wrote: > > I'm wondering whether it's worthwhile migrating the existing > > content to a doc//books/ and doc//articles/ directory > > structure instead? > > This is a nightmare for the webmaster and the cvs masters. > CVS does not handle directory moves well. Migrating was the wrong word. We currently have the following docs (on the English side) doc/FAQ doc/en/handbook doc/en/tutorials/* Of these, doc/FAQ needs converting to DocBook, as do almost all of doc/en/tutorials. I don't think these conversions should be done "in place" as it where. When I converted the Handbook from LinuxDoc to DocBook the converted files were placed in doc/en/handbook, instead of sitting on a branch of doc/handbook. I'd like to do the same thing with the DTD migration for the FAQ and the majority of the tutorials. This entails no more CVS bloat than will be incurred by the DTD migration anyway. Being more precise LinuxDoc (current) DocBook (new) ------------------------------------------------------------------------ doc/FAQ -> doc/en/articles/FAQ doc/en/tutorials/ddwg -> doc/en/articles/writing-device-drivers doc/en/tutorials/devel -> doc/en/articles/programming-tools doc/en/tutorials/diskformat -> doc/en/articles/formatting-media doc/en/tutorials/disklessx -> doc/en/articles/diskless-X * doc/en/tutorials/docproj-primer -> doc/en/books/FDP-primer doc/en/tutorials/fonts -> doc/en/articles/fonts doc/en/tutorials/mh -> doc/en/articles/mh doc/en/tutorials/multios -> doc/en/articles/multios doc/en/tutorials/newuser -> doc/en/articles/newuser doc/en/tutorials/ppp -> doc/en/books/ppp * = Repository copy required, because this is already in DocBook format Note: As you can see, I'm in favour of longer names to be more explicit, in general. The *vast* majority of people are going to click on these as URLs, so won't care how long they are. Those of us that are actually maintaining them have TAB-completion on our shell, so it's no big deal. The distinction between a "book" and an "article" is roughly "If it has chapters, it's a book, otherwise it's an article". More precisely, if the top level DocBook element is "book" then it's a book. If the top level element is "article" then it's an article. PPP in the above list is a special case, as it'll probably become part of a larger handbook under doc/en/books. Why not just stick with "tutorials"? "tutorials" is a slightly loaded term. "articles" is neutral as to the content. It also (conveniently) maps to a DocBook element name. The FAQ could well slot into "books" instead of "articles". I'll be talking to the newly formed FAQ team about this. In every one of those examples except for docproj-primer, the move will be done by % mkdir doc/en/articles/ % convert-linuxdoc-to-docbook doc/en/tutorials//.sgml \ > doc/en/articles//article.sgml The mechanically translated article.sgml is then fixed up by hand. So, for a period of time we will have two copies of the article in the repository, one in LinuxDoc, one in DocBook -- this is exactly how the Handbook conversion worked. The articles can be translated one by one, and the LinuxDoc versions will only be removed when the DocBook conversion is finished. > > 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. No. make(1) is not the only tool that will be traversing this tree. It'd probably help if I describe the end-goal I'm working towards, rather than outlining the individual steps to get there. I want a docs.freebsd.org web site (or a subsite of www.freebsd.org, the domain name and URL organisation is not relevant) that maintains itself as automatically as possible. Adding new documentation and having it appear linked in on the web site should be a case of adding the new DocBook SGML files in to the right place on the tree, the HTML files can be generated automatically. This is going to require some scripts that can traverse the docs tree and build the HTML files. Experience tells me that these scripts should be as simple as possible. Sooner or later someone else is going to be maintaining them, and the less head scratching they have to do, the better. So I want these scripts to contain as few "special cases" as possible. I don't want the FAQ or the Handbook living in special directories where the code to handle them needs to be something like if($curdir == "FAQ" || $curdir == "handbook") { do_something(); else { do_something_else(); } scattered throughout. It's fragile, and it leads to a system where people say "But you can't make , because all these programs will break." > > 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. > > Hm, you are renaming 'handbook' to 'books' and 'tutorials' to 'articles'???? Yes. See above. The "Convert the Handbook from one large handbook to a collection of smaller 'handbooks'" idea has been discusses several times on -doc in the past couple of months, and I was under the impression that people thought it was a good idea. So we'll end up with two classes of documentation, books and articles. The Handbook *will not be* the only "book". Take a look at my FDP primer. It's not finished, and it's already far too large to be considered a tutorial, or an article. It's a book, and when it's finished it'll probably be 120-140 pages long. Under the current scheme, it really has to live in tutorials/. This is a misnomer, as it's not a tutorial. > > 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 Right. But if I'm building the website, why do I need the doc/ repository? Because (currently) the FAQ, Handbook, and so on, are part of the main FreeBSD web site. I don't think they should be. They should certainly be available on the web (obviously, I'm not *that* stupid :-) ) but not as part of the main FreeBSD site. Bits of the FreeBSD site can then become

A complete list of the FreeBSD Documentation is available at docs.freebsd.org, and can be viewed on-line, or downloaded in a wide variety of Unix, Windows, and Macintosh friendly formats.

> > 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 Our documentation is currently small. FreeBSD's growing, the available documentation is going to grow. I'd rather put in place a scaleable infrastructure to support it now, while the disturbance is still relatively small. > > 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 ;-( I know. Do you keep a list of referrers to URLs that we're redirecting? I'm happy to put together a standard e-mail to send to people who've linked to obsolete URLs advising them to update their links. 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