Date: Fri, 24 Mar 2000 02:07:06 +0000 From: Nik Clayton <nik@freebsd.org> To: Jim Mock <jim@luna.cdrom.com> Cc: Wolfram Schneider <wosch@panke.de.freebsd.org>, Alexey Zelkin <phantom@cris.net>, Nik Clayton <nik@FreeBSD.ORG>, doc@FreeBSD.ORG Subject: Re: Repo copies for the doc/ tree Message-ID: <20000324020705.B75564@catkin.nothing-going-on.org> In-Reply-To: <20000323145728.A89569@luna.cdrom.com>; from Jim Mock on Thu, Mar 23, 2000 at 02:57:28PM -0800 References: <20000323003054.B43966@catkin.nothing-going-on.org> <20000323105437.A5757@scorpion.crimea.ua> <20000323090141.A85935@catkin.nothing-going-on.org> <20000323120945.A14715@scorpion.crimea.ua> <20000323120109.A3954@luna.cdrom.com> <20000323234434.B1600@paula.panke.de.freebsd.org> <20000323145728.A89569@luna.cdrom.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Thu, Mar 23, 2000 at 02:57:28PM -0800, Jim Mock wrote:
> > This is a silly change. We do not rename foo/foo.c to foo/main.c
> > just because someone think it looks better (ask Bruce if you don't
> > believe me ;-). And we should not do that with HTML pages too.
> >
> > The users will have no benefits from these changes.
>
> I think it's more an issue of consistency. IMO, things should be one
> way or the other, not a mix of the two, and it doesn't really matter
> which at this point.
That's it, pretty much, in a nutshell.
The fewer inconsistencies there are in the structure of the site,
the less headspace I (and anyone else working on it) have to devote
to remembering them, and the easier it is to document.
Alexey (I think) said that this point was moot because of the INDEXLINK
variable. If you look at web.mk, you'll see
...
.if defined(INDEXLINK) && !empty(INDEXLINK)
(cd ${DOCINSTALLDIR}; ln -s -f ${INDEXLINK} index.html)
.endif
...
Now I'm sorry, but things like this are a kludge to work around a bad
initial design. If you're going to install something as "index.html"
then it should be called "index.sgml" in the repo. That's how all the
other .sgml files in the repository work.
I'm not knocking the efforts of the people who originally created the
site -- it's easy to make the wrong decision about things like this when
you first create a site, and CVS does tend to carve these mistakes in to
stone. I've made similar decisions in my web design career, and lived
to regret them. I'd rather they went perpetuated any further than is
absolutely necessary on this project.
As far as I can see, there are two things to be careful about this
change. One is that for a short time there will be a foo.sgml and an
index.sgml with the same content. If someone commits to foo.sgml before
I've updated the Makefile and "cvs remove"d it then they'll be out of
sync. I can either freeze the tree immediately after the repo copy,
do the work, and then unfreeze it (nice and simple, but it locks everyone
else out) or just propogate any commits to each index file over, and
then commit and remove in the same action (more work for me, less work
for everybody else).
The other is that doubtless there are links out there to
/docproj/docproj.html. I suggest we deal with these by:
1. For one month, put in a simple redirect in httpd.conf
2. For one month, put in a redirect, with a warning message displayed
first.
Then, kill the redirect, and watch the error log to see if there are still
lots of links. If there are, go back to step 1, but extend the waiting
period another month (or two).
N
--
Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95.
Telephone line, $24.95 a month. Software, free. USENET transmission,
hundreds if not thousands of dollars. Thinking before posting, priceless.
Somethings in life you can't buy. For everything else, there's MasterCard.
-- Graham Reed, in the Scary Devil Monastery
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?20000324020705.B75564>