From owner-freebsd-doc Thu Mar 15 2:34:27 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 2E7EC37B71C for ; Thu, 15 Mar 2001 02:34:18 -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 f2FAWnt50367; Thu, 15 Mar 2001 10:32:49 GMT (envelope-from nik) Date: Thu, 15 Mar 2001 10:32:48 +0000 From: Nik Clayton To: Jun Kuriyama Cc: doc@FreeBSD.ORG Subject: Re: http://www.freebsd.org/docs/, /FAQ/, /handbook/, and others Message-ID: <20010315103248.A49019@canyon.nothing-going-on.org> References: <20010314212034.A45244@canyon.nothing-going-on.org> <7mk85rvksr.wl@waterblue.imgsrc.co.jp> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-md5; protocol="application/pgp-signature"; boundary="OXfL5xGRrasGEqWY" Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <7mk85rvksr.wl@waterblue.imgsrc.co.jp>; from kuriyama@imgsrc.co.jp on Thu, Mar 15, 2001 at 11:16:20AM +0900 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org --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