Date: Mon, 10 May 1999 10:46:05 +0100 From: nclayton@lehman.com To: Wolfram Schneider <wosch@panke.de.freebsd.org>, doc@FreeBSD.ORG Cc: cvs@FreeBSD.ORG Subject: Re: doc/<lang>/books/*, doc/<lang>/articles/*, and docs.freebsd.org Message-ID: <19990510104605.D14492@lehman.com> In-Reply-To: <19990509011527.18124@panke.de.freebsd.org>; from Wolfram Schneider on Sun, May 09, 1999 at 01:15:27AM %2B0200 References: <19990504163533.S14492@lehman.com> <19990509011527.18124@panke.de.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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/<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.
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/<whatever>
% convert-linuxdoc-to-docbook doc/en/tutorials/<whatever>/<whatever>.sgml \
> doc/en/articles/<whatever>/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 <some random change>, 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/<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'????
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
<p>A complete list of the FreeBSD Documentation is available at
<a href="http://docs.freebsd.org/">docs.freebsd.org</a>, and can
be viewed on-line, or downloaded in a wide variety of Unix, Windows,
and Macintosh friendly formats.</p>
> > 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990510104605.D14492>