Date: Thu, 24 Jun 1999 11:10:12 +0100 From: Nik Clayton <nclayton@lehman.com> To: Satoshi - Ports Wraith - Asami <asami@freebsd.org>, 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 Message-ID: <19990624111012.L15628@lehman.com> In-Reply-To: <199906232344.QAA55779@silvia.hip.berkeley.edu>; from Satoshi - Ports Wraith - Asami on Wed, Jun 23, 1999 at 04:44:14PM -0700 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>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, Jun 23, 1999 at 04:44:14PM -0700, Satoshi - Ports Wraith - Asami wrote:
> * From: Nik Clayton <nik@nothing-going-on.demon.co.uk>
>
> * 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/<language_and_encoding>/articles/printing-faq
doc/<language_and_encoding>/articles/printing-to-win95
doc/<language_and_encoding>/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/<language>/printing/articles/printing-faq
/usr/doc/<language>/printing/articles/printing-to-win95
/usr/doc/<language>/printing/books/printing
/usr/doc/<language>/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/<language>/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/<language>/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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990624111012.L15628>