Date: Thu, 19 Aug 1999 00:57:35 +0100 From: Nik Clayton <nik@freebsd.org> To: Satoshi - Ports Wraith - Asami <asami@freebsd.org> Cc: Nik Clayton <nik@freebsd.org>, doc@freebsd.org Subject: Re: Default FDP docs installation directory? Message-ID: <19990819005735.C83680@catkin.nothing-going-on.org> In-Reply-To: <vqcr9l0eol7.fsf@silvia.hip.berkeley.edu>; from Satoshi - Ports Wraith - Asami on Wed, Aug 18, 1999 at 03:00:36PM -0700 References: <19990818121931.A4266@kilt.nothing-going-on.org> <vqcr9l0eol7.fsf@silvia.hip.berkeley.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, Aug 18, 1999 at 03:00:36PM -0700, Satoshi - Ports Wraith - Asami wrote:
> * From: Nik Clayton <nik@freebsd.org>
>
> * With the repo-change comes an opportunity to change where our docs
> * are installed.
>
> Why don't you discuss these stuff BEFORE you make the changes?
It's an opportunity -- it's not something we *have* to do. I'm posting
this for wider discussion because we now have an implementation that makes
it fairly trivial to actually make the change.
If this had been discussed before the repo move, we would have had a nice
long thread discussing the various pros and cons, and no conclusion would
have emerged, because no one could try out the various options to see
what happens.
Well, now you can. Check out the repository, and try
make DOC_INSTALL_PREFIX=/tmp/foo install
and then look at the directory structure in /tmp/foo/ (some of the FAQs
might not honour DOC_INSTALL_PREFIX yet, but this is proof of concept
only).
Take a look at the created directory structure, and have a think about
where in the tree you'd like that grafted.
The top level of that tree looks like
en_US.ISO_8859-1/ es_ES.ISO_8859-1/ ja/
ru_RU.KOI8-R/ zh_TW.Big5/
and includes the compatability symlinks (which I haven't shown above).
I don't think that's terribly informative on their own, which is why I
think dropping those directories straight in to /usr/share/doc/ or
/usr/local/share/doc/ is a bad idea.
I think they need to be need sub-directories of a directory which indicates
(in the same way that "mutt/" indicates you're going to be looking at
documentation put together by the Mutt maintainers) that you're going to
be seeing documentation put together by the FreeBSD Documentation Project.
Which is why I think some variation on /usr/share/doc/fdp/ or
/usr/local/share/doc/fdp/ is appropriate. The FDP documentation is then
kept separate from documentation that is not maintained by the FDP.
> * Historically, the documentation has been installed in to /usr/doc. This
>
> Wrong. They have been installed in /usr/share/doc.
Yes, think-o on my part.
> * Does anyone have any objections to /usr/local/share/doc/fdp/ as the root
> * path for the documentation? 'fdp' is a little bit cryptic, but I like
> * TLAs, and the only other alternative I could think of ('docproj', or
> * 'doc-proj') is quite ugly.
>
> fdp is even uglier, and I can't recall anyone other than you using
> that particular acronym.
Alternatives? "docproj"? "doc-proj"? "doc-project"? Something better?
> * One more thing -- A mid-term goal is for the pre-built docs (HTML, PS, PDF
> * and so on) to be distributed as binary packages, to be managed using the
> * pkg_* family. I'm pretty certain this precludes putting the documentation
> * anywhere other than a subdirectory of /usr/local/, so the old /usr/doc/
> * directory is right out.
>
> As a mid-term goal, everything in the system is going to be packages
> (if we believe what Jordan is saying) so where it's going is
> irrelevant.
>
> Please keep stuff in /usr/share/doc. I don't see any reason to change
> that, especially not with all the other changes going on around now.
That will lead to /usr/share/doc/en_US.ISO_8859-1/
es_ES.ISO_8859-1/
ja/
papers/
psd/
ru_RU.KOI8-R
smm/
usd/
zh_TW.Big/
and so on. We can do it, but I'm not convinced it's a good idea.
I stress that doesn't mean we won't do it, just that I don't think it's a
good idea. However, if the consensus on this list is that it's a good
idea then we can do that.
Of course, it would also be possible during "make install" time to
designate one language as the default, which could lead to
/usr/share/doc/articles@ -> en_US.ISO_8859-1/articles/
books@ -> en_US.ISO-8859-1/books/
en_US.ISO_8859-1
es_ES.ISO_8859-1/
ja/
papers/
psd/
ru_RU.KOI8-R
smm/
usd/
zh_TW.Big/
which might be more palatable.
I don't know what we'll end up with -- but now we have a framework that's
capable of actually implementing these sorts of changes relatively
quickly, which means that as well as discussing the changes, people can
actually put their money where their mouth is, and actually submit diffs
to the framework, so the rest of us can test out their changes.
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?19990819005735.C83680>