Date: Sat, 26 Jun 1999 01:42:03 +0100 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: Satoshi - Ports Wraith - Asami <asami@FreeBSD.ORG> Cc: nclayton@lehman.com, motoyuki@snipe.rim.or.jp, jkh@zippy.cdrom.com, kuriyama@sky.rim.or.jp, doc@FreeBSD.ORG, freebsd-translate@ngo.org.uk, jdp@FreeBSD.ORG, freebsd-tech-jp@jp.freebsd.org Subject: Re: Resolution: FDP reorganisation Message-ID: <19990626014203.B71532@catkin.nothing-going-on.org> In-Reply-To: <199906252311.QAA04505@silvia.hip.berkeley.edu>; from Satoshi - Ports Wraith - Asami on Fri, Jun 25, 1999 at 04:11:03PM -0700 References: <57461.930305624@zippy.cdrom.com> <199906251220.VAA22552@sakura.snipe.rim.or.jp> <19990625150942.K15628@lehman.com> <199906252311.QAA04505@silvia.hip.berkeley.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
On Fri, Jun 25, 1999 at 04:11:03PM -0700, Satoshi - Ports Wraith - Asami wrote:
> (Have you seen /usr/X11R6/lib/X11/locale?)
I have. It could be clearer.
* How many distinct languages are catered for in that directory? There's
no way to tell.
* It's incredibly inconsistent. Look at
en_US.utf/ US English, probably
ja/ Japanese, but which encoding?
ja.JIS/ JIS encoding, so the previous one is probably EUC
ko/ Korean, presumably EUC encoding
koi8-r/ Which language is this? Korean? No, this
directory probably contains Russian info, because
koi8-r is a Russian encoding.
zh/ Chinese, but which encoding?
zh_TW/ Presumably Big5 encoding, but why isn't the
previous one zh_CN?
All those questions. Anyone wanting to work in that directory has to
answer them for themselves, and because there's no consistency, you can't
explain it with simple rules.
I like simple rules. They're easy to document, they're easy to explain,
and they don't scare away potential documentors. I'm looking to make
the doc/ repository as clear and as simple to understand as possible,
without sacrificing functionality that we already have.
> * Just to make this completely clear;
> *
> * 1. After making the change I am proposing, the Japanese documentation
> * will *still* install into a .../doc/ja/ directory.
> *
> * No change.
> *
> * 2. At some point in the future (when it's written, debugged, and
> * tested), *all* the docs will install into a variant of
> * .../doc/<lang>_<region>.<encoding>/. Symlinks will be used to
> * ensure that this approach allows an admin to be 100% compatible
> * with the current mechanism, while affording those admins that want
> * it to be more flexible.
> *
> * Yes, this is a change, but I guarantee that when this change does
> * happen that the default will be to ensure that any symlinks necessary
> * for compatability will be retained. The admin will have to make
> * conscious changes to break compatability.
>
> Um, that's the same thing. We are objecting to the eventual goal in
> item 2, and 1 _as the preparation for 2_.
>
> We have already tried the symlinks approach when we moved stuff from
> ja_JP.EUC to ja. It was a disaster.
More details (or pointers to English language mailing list archives with
this discussion in) would be appreciated, thanks.
> There are so many systems out
> there where it would break (what if both directories already exist?).
Firstly, it shouldn't do, as the doc/ tree installs (by default) in to
/usr/share, and I was under the impression that the ports docs, by
default, install in to /usr/local/share/doc (or whatever the admin's set
${PREFIX} to (or whichever variable it is).
There shouldn't be a clash -- I'm not changing where the ports docs
install in to, nor am I proposing to.
And in the second case we do what we usually do when we make changes that
can potentially break things -- we write HEADS UP notices to the
appropriate mailing lists, we make the patches available for review and
comment first, and (if this does turn out to be as involved as you think)
I (and others) can spend the extra time writing a FAQ for people to refer
to.
> What we learned was that it is near impossible to convert an existing
> system seamlessly. Docs should stay where they are, where people and
> ports expect them to be, and symlinks added for additional names --
> not the other way around.
Fine. My system has lots of ports docs installed in /usr/local/share/doc,
and none in /usr/share/doc/ The only stuff in /usr/share/doc is either
in the src/ or doc/ repositories.
And yes, I know that foreign language manual pages install directly
under /usr/share/. Perhaps it should be /usr/local/share/man instead?
Or the manpath can be set in /etc/manpath.config as necessary, and for
the cutover period (defined, say, as the time between two major versions
of FreeBSD) we can include both paths in manpath.config to minimise (or
eliminate) any pain.
> Note that the whole locale directory issue is not that of the doc
> project alone. There are manuals, ports, and web pages (and god knows
> how many third party software and scripts that have been written
> according to our old convention). Unless you want the doc project
> stuff to be inconsistent with the rest of FreeBSD, you need to realize
> that this problem is much bigger and deeper than you think.
Yes. However, if we tried to tackle everything at once we'd get
swamped, it would never be co-ordinated, and it wouldn't happen. I'm
trying to break off a chunk of the problem and tackle it in my area
of competence (to wit, the FDP).
As and when this happens, the ports team can watch how we did it, look at
the benefits it provides to the end user, and decide if and when you want
to adopt the same approach. You might want to, you might not.
And as for 'inconsistent with FreeBSD'. To my mind the term "FreeBSD"
in this context applied to three things "FreeBSD - the source", "FreeBSD -
the ports", and "FreeBSD - the docs".
Of those three entities (or Trinity, if you will, I've just come back from
seeing _The Matrix_ for the first time, excellent film, if you're reading
this in the UK and haven't seen it yet, go and do so), "FreeBSD - the
source" already uses the <lang>_<location>.<encoding> scheme (c.f.,
/usr/share/locale). I'm trying to move the docs to the same scheme, which
if anything is making things more consistent, not less.
> That said, I won't object if your eventual goal will allow a
> per-language *default* in directory names. For instance, if we can
> put "LANGSUBDIR ?= ja" in ja_JP.eucJP/Makefile to have all the
> Japanese documents install in the "ja" subdir by default (and have
> symlinks pointing to there from ja_JP.eucJP or whatever), that is fine
> for me. Each language/territory can choose their own default (maybe
> most of them will just want it to be the same as the repository name,
> although I have a hunch that Mandarin folks will prefer "zh" or
> "zh_CN" -- but don't quote me on this) that makes the most sense to
> them.
Yes. I want to allow this flexibility. In my mind, a sysadmin is likely
to want to install the docs in to a canonical location, and then symlink
to this location from other, possibly friendlier, directory names.
As an admin myself, I'd want the canonical location to be as precise as
possible, and have the symlinks be less precise. Which is why I'd suggest
the canonical location be 'ja_JP.eucJP' (or whatever) and the symlinks be
'ja'. Other admins (e.g., you) might want this reversed, and have the
canonical directory be 'ja', and the symlinks be things like 'ja_JP.eucJP'.
I have no problem with this, and the arguments about which approach should
be the default (6 or 12 months down the line) are likely to more
entertaining than "vi vs. Emacs" :-)
N
--
[intentional self-reference] can be easily accommodated using a blessed,
non-self-referential dummy head-node whose own object destructor severs
the links.
-- Tom Christiansen in <375143b5@cs.colorado.edu>
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?19990626014203.B71532>