From owner-freebsd-doc Sun Mar 18 6:40:38 2001 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id 356CD37B719; Sun, 18 Mar 2001 06:40:14 -0800 (PST) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.11.1/8.11.1) id f2IEd7513292; Sun, 18 Mar 2001 14:39:07 GMT (envelope-from nik) Date: Sun, 18 Mar 2001 14:39:07 +0000 From: Nik Clayton To: Jun Kuriyama Cc: Nik Clayton , doc@FreeBSD.ORG Subject: Re: http://www.freebsd.org/docs/, /FAQ/, /handbook/, and others Message-ID: <20010318143907.A13242@canyon.nothing-going-on.org> 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> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-md5; protocol="application/pgp-signature"; boundary="EeQfGwPcQSOJBaQU" Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <7mg0gdt0mg.wl@waterblue.imgsrc.co.jp>; from kuriyama@imgsrc.co.jp on Sat, Mar 17, 2001 at 02:39:35PM +0900 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org --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//{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