Date: Thu, 15 Mar 2001 10:32:48 +0000 From: Nik Clayton <nik@freebsd.org> To: Jun Kuriyama <kuriyama@imgsrc.co.jp> Cc: doc@FreeBSD.ORG Subject: Re: http://www.freebsd.org/docs/, /FAQ/, /handbook/, and others Message-ID: <20010315103248.A49019@canyon.nothing-going-on.org> In-Reply-To: <7mk85rvksr.wl@waterblue.imgsrc.co.jp>; from kuriyama@imgsrc.co.jp on Thu, Mar 15, 2001 at 11:16:20AM %2B0900 References: <20010314212034.A45244@canyon.nothing-going-on.org> <7mk85rvksr.wl@waterblue.imgsrc.co.jp>
next in thread | previous in thread | raw e-mail | index | archive | help
--OXfL5xGRrasGEqWY
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
On Thu, Mar 15, 2001 at 11:16:20AM +0900, Jun Kuriyama wrote:
> At 14 Mar 2001 19:09:50 GMT,
> nik wrote:
> > The patch uses symlinks, but since these are links to files (note: *not*
> > directories, which drew the most ire a few weeks ago) these could easily
> > be made hardlinks instead.
>=20
> To reduce multiple results from search engine, this approach is same
> as previsou one (directory symlink). I think what Wosch want to say
> is symlinking file is *less* evil than symlinking directory because it
> affects only few URLs. If you symlinking every file in directory, it
> may be same result as directory symlink.
I was confused about this too -- I can't see the difference, but people
were saying that directory symlinks are bad, but file symlinks are not
(or, at least, less bad).
> I want to understand your plan of directory hierachy on web. Current
> structure is:
>=20
> / English top
> /handbook/ English Handbook
> /docs/en/books/handbook/ English Handbook
> /docs/en/articles/committers-guide/ English Committer's Guide
> /ja/ Japanese top
> /ja/handbook/ Japanese Handbook
>=20
> So, if we can forget old URL and redirects (of cource it's assumption
> :-), what structure you want to use?
Basically, I want the documentation to install in to a hierarchy
similar, or identical to the one that's used in the doc/ repo.
The existing FAQ/, handbook/, and tutorials/ directories were fine when
we only had 2 'tier 1' documents, and a few small tutorials. Now we
have a number of 'tier 1' documents (Porter's Handbook, FDP Primer,
Developer's Handbook, and that list is increasing). We are getting more
smaller documents, many of which are not tutorials -- the 'Explaining
BSD' document I committed last night, for example, or the 'Getting
results from freebsd-questions' document.
I would like all the documentation to be easily accessible from
docs/index.html (or doc/index.html, I'm easy on that point) on the web
site. This page (and/or set of pages) would then contain links to the
actual documentation, shielding the user from the length of the URLs.
We have some existing, well known, URLs that don't fit in to this
scheme. Specifically, FAQ/, handbook/, and tutorials/. I think we're
all in agreement that these URLs need to work for the foreseeable
future, and the question then is "How?".
1. Use redirects in the web server config file.
2. Symlink the FAQ/ directory to ../docs/en*/books/faq/
3. Symlink the contents of ../docs/en*/books/faq/ in to FAQ
4. Duplicate the content by installing copies of the documentation=20
in to FAQ and Handbook.
(repeat 2, 3, and 4 for handbook/ and tutorials/).
I am emphatically opposed to doing (1). History shows that our mirrors
*do not* reliably replicate our web server configuration, so if we rely
on (1) we break the mirrors (also, it means that you need to run a
webserver to fully test changes to the site locally, but that is very
much a side issue).
(2), (3), and (4) all avoid this problem. (4) pushes up the diskspace
requirements slightly. The patch I just sent out implements (3),
currently, the website implements (4).
Note that whichever way we do this, we will end up with duplicated
content appearing in search engines like Google. There's no way around
that. I don't think it's going to cause the users any harm (after all,
it's not going to make it any harder for them to find the documentation
they are looking for). As long as we restrict this to just the existing
FAQ, Handbook, and tutorials the load on the webserver due to spidering
should also be negligable (and can be reducted, if not entirely
eliminated, with robots.txt).
> We should consider how to use language identifier in URL.
Good question. Again, IMHO, I think that someone going to www.freebsd.org
would expect to see the English home page, going to
www.freebsd.org/handbook/ would expect to see the English Handbook, and
so on.
I'm not very comfortable with the current approach of putting the other
languages in subdirectories, such as ja/, although I can see some merits
to it. But as a user, I would expect to go www.ja.freebsd.org and see
the Japanese page by default.
I also like the work I've seen on other sites where most pages have a
link at the bottom of them that says something like
This page also available in: [English] [Japanese] [Spanish] [...]
where the various language names take you to the translation of the same
page. I have not yet given any thought to how we could easily achieve
this, given that different translations have progressed differently in
terms of the amount they have translated.
[ Speaking of which, is your automated list of where the translations
lag the English version still available? We should probably put a
link to that somewhere prominent, and extend it for the other
translations ]
Perhaps we should be installing all the HTML files with an additional
suffix depending on the language: index.html.en, index.html.ja, and so
forth. A variable set during install time would then symlink these back
to the regular filename. So if you do "make install" with WEB_LANG set
to en_US.ISO_8859-1 then index.html is a link to index.html.en. If
WEB_LANG is set to ja_JP.eucJP then index.html is a link to
index.html.ja, and so forth. A proof of concept of this is probably
only a couple of hours work, if someone wants to send a patch.
I'm just kicking out ideas for discussion at the moment.
N
--=20
FreeBSD: The Power to Serve http://www.freebsd.org/
FreeBSD Documentation Project http://www.freebsd.org/docproj/
--- 15B8 3FFC DDB4 34B0 AA5F 94B7 93A8 0764 2C37 E375 ---
--OXfL5xGRrasGEqWY
Content-Type: application/pgp-signature
Content-Disposition: inline
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.4 (FreeBSD)
Comment: For info see http://www.gnupg.org
iEYEARECAAYFAjqwmk8ACgkQk6gHZCw343WP8ACgkTnUDO2+nCB6f7F5JKw3rKEZ
hToAn1i5VRQE/M8jb9gWBI95JPadFWQF
=4q7a
-----END PGP SIGNATURE-----
--OXfL5xGRrasGEqWY--
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?20010315103248.A49019>