Date: Sun, 18 Mar 2001 14:39:07 +0000 From: Nik Clayton <nik@freebsd.org> To: Jun Kuriyama <kuriyama@imgsrc.co.jp> Cc: Nik Clayton <nik@FreeBSD.ORG>, doc@FreeBSD.ORG Subject: Re: http://www.freebsd.org/docs/, /FAQ/, /handbook/, and others Message-ID: <20010318143907.A13242@canyon.nothing-going-on.org> In-Reply-To: <7mg0gdt0mg.wl@waterblue.imgsrc.co.jp>; from kuriyama@imgsrc.co.jp on Sat, Mar 17, 2001 at 02:39:35PM %2B0900 References: <20010314212034.A45244@canyon.nothing-going-on.org> <7mk85rvksr.wl@waterblue.imgsrc.co.jp> <20010315103248.A49019@canyon.nothing-going-on.org> <7mg0gdt0mg.wl@waterblue.imgsrc.co.jp>
next in thread | previous in thread | raw e-mail | index | archive | help
--EeQfGwPcQSOJBaQU
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
On Sat, Mar 17, 2001 at 02:39:35PM +0900, Jun Kuriyama wrote:
> At 15 Mar 2001 10:34:30 GMT,
> nik wrote:
> > 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).
>=20
> IMHO, problem is not whether file or directory, but how many
> duplicates caused by that.
Currently, 20 in the case of the FAQ, 172 in the case of the Handbook.
Is that too many? Personally, I don't think so.
> > 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.
>=20
> Ideally, that's good. But usually, I often type URL of the Handbook
> directory, not use hyper-link on top page.
Me too. That's why a mechanism for ensuring that the /faq/ and
/handbook/ URLs continue to work is a good thing.
> But as you said, we now have many documents to be linked. So I agree
> with you to use docs/index.html for portal of documents.
>=20
> > 1. Use redirects in the web server config file.
> >=20
> > 2. Symlink the FAQ/ directory to ../docs/en*/books/faq/
> >=20
> > 3. Symlink the contents of ../docs/en*/books/faq/ in to FAQ
> >=20
> > 4. Duplicate the content by installing copies of the documentation=
=20
> > in to FAQ and Handbook.
>=20
> Hmmm, what I want to know is not *how* to achieve new hierarchy,
> *what* hierarchy you want to use.
I would like the canonical URL for a document to be:
http://www.freebsd.org/docs/<lang.encoding>/{books,articles}/document/{=
index,article,book}.html
Basically, the result of running 'make install' in the doc/ tree.
If you look at the result of 'make install' at the moment, you'll see
that it also creates shortcut symlinks, like
en/books/...
instead of
en_US.ISO_8859-1
This would be another set of symlinks to support, with the pros and cons
that we've already outlined. Personally, I don't care about this bit
either way.
Yes, this is a long URL. However, I don't think it's a problem:
1. 95% + of URL references given by people in e-mail for
documentation on the FreeBSD site are going to be for either the
FAQ or the Handbook.
Those URLs will continue to work.
2. For everything else, we get people to point to
http://www.freebsd.org/docs.html (or doc.html) instead. This can
then list the documentation and link to it.
3. If someone wants to refer back to a particular document frequently
then they can bookmark it, avoiding the need to key in the URL=20
manually.
> > > We should consider how to use language identifier in URL.
> >=20
> > 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.
>=20
> Agreed.
>=20
> > 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.
>=20
> I think making new domain (like www.ja) is not good idea. If we
> decide to use www.FreeBSD.rog/ja for Japanese translated pages, that
> is enough for us (of course it's my point of view).
>=20
> Japanese translation is often old information than the English
> version. So we often refer the English version to know latest
> information. This causes switching both version frequently.
> I like current structure which includes multiple languages in one
> domain.
Good point.
> I want to know other person's opinion about this...
>=20
> > 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
> >=20
> > This page also available in: [English] [Japanese] [Spanish] [...]
> >=20
> > 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.
>=20
> Honestly, I have no idea to use this feature because:
>=20
> o We are using language separated directory. Default behavior of
> Apache requires language suffix to select localized contents.
> o We should not request special configuration for mirror site
> administrators.
>=20
> I hope someone knows neat idea...
Change the way we do things. Instead of having a CVS repo that looks
like
www/{en,ja,es,...}
have one that looks like
www/{data,cgi,share,...}
The data/ directory is where all the existing content goes.
Instead of segregating the content by language in to different
directories, have *all* the content in the data/ directory (and it's
subdirectories), with names like
index.en.sgml
index.ja.sgml
index.es.sgml
and so on.
When you run make(1), it does something like
sgmlnorm index.en.sgml > index.en.html
sgmlnorm index.ja.sgml > index.ja.html
and so on. After doing that, it does one final pass, using symlinks to
link in the 'default' file. For example, if the user has
WEB_DEFAULT_LANG set to 'ja' then it would run
ln -s index.ja.html index.html
If WEB_DEFAULT_LANG was set to 'en' then it would run
ln -s index.en.html index.html
This could also help translators who want to start. You could modify
that rule slightly so that, if index.ja.html doesn't exist then
index.en.html is linked to instead, thereby providing a default language
for the translators to fall back to.
This would also mean doing something clever with internal links within
the web site. The correct language code would need to be in each
internal link for it to work properly. That can probably be hacked up
pretty easily.
I haven't written any infrastructure to support what I've just described
yet, but I think it would certainly be an interesting exercise for
someone to do. Then we could test it out, and see what problems (if
any) it causes, and whether or not it really is a benefit.
Does anyone want to put together a prototype?
> > 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.
> >=20
> > I'm just kicking out ideas for discussion at the moment.
>=20
> Using content negotiation should be discussed more carefully. Please
> give me more time to consider.
The approach I've outlined above shouldn't require the web server to do
any content negotiation. Instead, the user would have to (once)
explicitly request the language they want to see the page in. It's not
quite as slick as content negotiation, but it would mean that the
approach is completely independent of the web server.
> As first step, how about to install books, articles and so on like
> this (not using docs/en):
>=20
> /index.html
> /docs/books/handbook/index.html
> /docs/books/porters-handbook/index.html
> /docs/articles/committers-guide/index.html
> /ja/index.html
> /ja/docs/books/handbook/index.html
> /ja/docs/books/porters-handbook/index.html
> /ja/docs/articles/committers-guide/index.html
Could do. Patches?
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 ---
--EeQfGwPcQSOJBaQU
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
iEYEARECAAYFAjq0yIoACgkQk6gHZCw343W6tACdGDUIeY2Fqf6jb0uFv9aTi1pD
c4kAnjLS02QiBtZ8h14Dfp5IP7wXnu+d
=pTdy
-----END PGP SIGNATURE-----
--EeQfGwPcQSOJBaQU--
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?20010318143907.A13242>