From owner-freebsd-doc Thu Jun 24 3:11: 0 1999 Delivered-To: freebsd-doc@freebsd.org Received: from firewall1.lehman.com (firewall.Lehman.COM [192.147.65.66]) by hub.freebsd.org (Postfix) with ESMTP id 5D53F152EA; Thu, 24 Jun 1999 03:10:49 -0700 (PDT) (envelope-from nclayton@lehman.com) Received: from relay3.messaging-svcs5.lehman.com by firewall1.lehman.com (8.8.6/8.8.6) id GAA08928; Thu, 24 Jun 1999 06:10:45 -0400 (EDT) Message-ID: <19990624111012.L15628@lehman.com> Date: Thu, 24 Jun 1999 11:10:12 +0100 From: Nik Clayton To: Satoshi - Ports Wraith - Asami , nik@nothing-going-on.demon.co.uk Cc: doc@freebsd.org, freebsd-translate@ngo.org.uk, tech-jp@jp.freebsd.org, cvs@freebsd.org Subject: Re: FDP Directory Reorganisation References: <19990603195027.A31941@catkin.nothing-going-on.org> <37593369.10E2888D@sky.rim.or.jp> <19990607233227.A34938@catkin.nothing-going-on.org> <199906162246.PAA02177@silvia.hip.berkeley.edu> <19990617194856.A26011@catkin.nothing-going-on.org> <199906172252.PAA11221@vader.cs.berkeley.edu> <199906181152.EAA24735@silvia.hip.berkeley.edu> <199906231041.DAA51528@silvia.hip.berkeley.edu> <19990623231108.A71294@catkin.nothing-going-on.org> <199906232344.QAA55779@silvia.hip.berkeley.edu> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.93.2i In-Reply-To: <199906232344.QAA55779@silvia.hip.berkeley.edu>; from Satoshi - Ports Wraith - Asami on Wed, Jun 23, 1999 at 04:44:14PM -0700 Organization: Lehman Brothers Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Wed, Jun 23, 1999 at 04:44:14PM -0700, Satoshi - Ports Wraith - Asami wrote: > * From: Nik Clayton > > * Doesn't apply. I'm not asking that the installation directory change, > * just the directory in which it's held in the CVS repository. > > I did not realize that you were proposing to make the names in the CVS > repository inconsistent with the installation directory. Why do you > want to do that? Because while the files will only exist in one place in the CVS repository, they might exist in several places when they are installed. Consider the Japanese translations. Right now we only have one encoding, EUC-JP in the repository. What's more, we can mechanically convert from EUC to ShiftJIS encoding (at least, I've been told on this list that we can do that). So, what's going to happen when you do # cd doc/ja_JP.EUC-JP/books/handbook # make install Lots of things. Firstly, the formatted documentation will be installed in to the PRIMARY installation directory. That directory will almost certainly be /usr/share/doc/ja_JP.EUC-JP/books/handbook to match the repository name (it might be /usr/local/... instead, that's really a policy issue for the local machine admin, and not something that's important right now). However, the files can also be installed into other places as well (note: when I say "installed", mechanisms such as symlinks can be used instead for the same effect, indeed, this is how it's likely to be implemented). So, our hypothetical Japanese admin doesn't want that sort of long name in his install directory, and would prefer it to be "ja". That's fine; they can either make the symlink themselves; /usr/share/doc/ja -> /usr/share/doc/ja_JP.EUC-JP or the Makefile can support the concept itself, through a space separated list of aliases in the Makefile ("ALIASES= ja" for example). The Japanese translation team aren't the only ones that will want this functionality, every other language will need it as well. For example, the English docs will install in to /usr/share/doc/en_US.ISO-8859-1 (or similar) but the plain "en" symlink will exist as well. Now suppose that you're a Chinese admin, and you've got the choice of documentation that is available in two different encodings. You can install both of them (because the encoding names don't clash) and use a symlink from /usr/share/doc/zh to point to whichever one you want to be 'local preferred format'. This sort of mechanism will also be used a lot to create extra symlinks to help categorise the installed documentation. Suppose that you have 3 pieces of documentation about printing on Unix. 1. A quick FAQ (an article) 2. A walkthrough of printing to a Win95 hosted printer, using Samba (an article) 3. A larger book going in to all the ins and outs of printing under FreeBSD (a book) In the repository, those three pieces of documentation will probably live in the following areas; doc//articles/printing-faq doc//articles/printing-to-win95 doc//books/printing When these three pieces of documentation are installed the master copies will be installed in subdirectories that reflect the book/article distinction. That's OK, but not great. How is the user supposed to know where to look for information about printing? The solution is 'virtual categories'. I've touched on these briefly in other messages a month or so ago. Basically, the respective Makefiles for these three pieces of documentation will contain lines like VIRTUAL_CATEGORIES= printing VIRTUAL_CATEGORIES= printing win95 VIRTUAL_CATEGORIES= printing The install target in the Makefile will then use this to create symlinks like /usr/doc//printing/articles/printing-faq /usr/doc//printing/articles/printing-to-win95 /usr/doc//printing/books/printing /usr/doc//win95/articles/printing-to-win95 Notice how there are four directories there instead of three. One of those articles is now available under both the "printing" category and the "win95" category. I might extend this a third way, so that as well as categorising by document type (article, book, or manual page) and virtual category, documentation is also categoriesed by installation format. So if you just want to see HTML docs you go to /usr/doc//html/... or similar. But that might be going a bit too far. So the user now has a much better chance of being able to find the documentation they want. Couple this with some XML based programs that can extract the titles from the documentation we should even be able to create a master index of all the installed documentation in something like /usr/doc//index.html with links to all the installed documentation, nicely categorised. How cool is that, eh? :-) > * Agreed. You've done more research on this than I have. The one thing > * I have dug up that agrees with this is the IANA assignments document > * that suggests "ja_JP.EUC-JP" (the URL of which I mailed out earlier). > * > * My preferences, therefore, are (in order) > * > * ja_JP.EUC-JP > * ja_JP.eucJP > * ja_JP.ujis > * > * and I'm very strongly in favour of the first option. > > Note that currently none of the above are officially supported locale > names for FreeBSD. Doesn't matter. If, as you've said, we'll be switching to one of those in 6 months time we can use the ALIAS mechanism I described above to make sure that the Japanese documentation is installed in to directories that match the current Japanese locale. > * We can use symlinks in the *installed* directories so that all of > * the above (and more) work. However, for the CVS repositories I would > * like to follow standards wherever possible. > > "ja" is an acceptable locale name, and is therefore suitable both as > installation and repository directory names. No it's not (as a repository directory name). Directories in the repository will be encoding the language, location, and encoding. I want this to be an inviolate rule -- if we need it for one language, then, for future proofing, we need it for all. Consider what happens as and when we provide a mechanism to mechanically translate from EUC to ShiftJIS (for example). Because this can be done mechanically I envisage two directories at the top level, ja_JP.EUC-JP ja_JP.ShiftJIS (I think that's the right encoding name for ShiftJIS, but don't quote me on that). ja_JP.EUC-JP contains the documentation. ja_JP.ShiftJIS contains a skeleton structure and a Makefile that, when run, populates the skeleton structure with documentation mechanically converted from the EUC encoding, which the user can then play with as they wish. For languages where you can not mechanically translate between encodings, such as Chinese, we will actually be storing two different copies of the documentation in the two directory structures. I am 100% dead set against this being something like ja ja_JP.ShiftJIS directories instead. This is inconsistent with how the rest of the tree will be organised, and will required kludges anywhere the directory name is split apart in to its constituent components to take account of the fact that one of the Japanese directories is named differently. I don't want these sort of kludges in the tree. N -- --+==[ Systems Administrator, Year 2000 Test Lab, Lehman Brothers, Inc. ]==+-- --+==[ 1 Broadgate, London, EC2M 7HA 0171-601-0011 x5514 ]==+-- --+==[ Year 2000 Testing: It's about time. . . ]==+-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message