On Sat, Aug 28, 1999 at 03:01:58AM -0700, Chris Waters wrote:
> > "Documentation must be accessible from /usr/doc/<package>.
> > In order to ease the transition to FHS, packages should
> > put documentation in /usr/share/doc/<package>, and install a
> > symlink from /usr/doc/<package> -> /usr/share/doc/<package>. Due
> > do a dpkg bug, this symlink should not be included in the package
> > itself, but created by the maintainer scripts like so:
> My proposal would have been very similar, with the substitution of
> "may" for "should" in the first line of the second paragraph. And
> possibly a comment about "at some point in the future, documentation
> will be required to be accessible from /usr/share/doc/<package> for
> full FHS compliance."
>
> I still don't like the idea of *mandatory* symlinks.
Having all documentation available from one directory location is a `known
feature' (cf known bug) of Debian. It's used for the http://localhost/doc
links, it's used for dwww and it's used by people. A single pathname for
changelogs and copyright files is also a `known feature'. These features
are relied upon by other programs (as per the release critical bug I cited
in the previous message), and in any case it's a nice feature to have.
The transition strategy is "you can do either FSSTND or FHS stuff. We're
going to make FHS compulsory eventually, so that's probably a good thing
to do now, so you don't have to do the work then."
The mandatory symlinks is just to make sure we can keep the single-doc
location while we're transitioning.
> It's a lot of
> overhead for packages with close-to-nothing in /usr(/share)?/doc.
Then those packages are welcome to stay in /usr/doc, if complying with the
transition strategy irks the maintainer too much. When policy changes,
they'll just have to be prepared to move more or less immediately,
without as much time for debugging as everyone else had.
They're also welcome to leave their docs in /usr/doc, and move everything
else into /usr/share, so if they've got other problems with the FHS move,
they can solve them without having to stress about the /usr/doc portion.
Oh, also: wrt the -doc packages thread: doing the thing with the symlinks
for /usr/doc/package, where package-doc.deb is installed and puts docs
in /usr/doc/package isn't going to work. Packages like that can either
take special trouble (eg, conflicting with pre-/usr/share versions of
each other), or just delay the /usr/doc portion of the switch.
> Which may be why an ugly transition doesn't scare me -- it's
> only adding a little extra annoyance to something that's already quite
> annoying, IMO.
Other people do make use of /usr/doc though.
> Docs should be in man pages, or info files, or in html
> registered with doc-base, or in on-line help accessible from the
> program itself. Anything else is just a hassle, period.
I'm getting to the point where I'd like all docs to be either manpages
or info files.
I love pinfo. *heartfelt sigh*
Cheers,
aj
--
Anthony Towns <aj@humbug.org.au> <http://azure.humbug.org.au/~aj/>
I don't speak for anyone save myself. PGP encrypted mail preferred.
``The thing is: trying to be too generic is EVIL. It's stupid, it
results in slower code, and it results in more bugs.''
-- Linus Torvalds
Attachment:
pgp7rG0mo45Dv.pgp
Description: PGP signature