Re: Which directory to use for packagename-doc documentation files?
Steve Greenland wrote:
> On 24-Jul-01, 10:24 (CDT), Peter S Galbraith <GalbraithP@dfo-mpo.gc.ca> wrote
> :
> > Here's what I think:
> >
> > - When source package `foo' creates binary packages `foo' and
> > `foo-doc', there's no reason not to put foo-doc's documentation
> > files under /usr/share/doc/foo/. Just say where they are in
> > /usr/share/doc/foo-doc/README.Debian
>
> I mostly agree, but let me play devil's advocate: It should be possible
> to install foo-doc w/o foo (I want to read the docs to see if it's
> the right package for me.) It might be confusing to have to look in
> /usr/share/doc/foo to find the docs that I just installed via package
> name foo-doc.
True enough. That's why where they are located should be spelled
out in /usr/share/doc/foo-doc/README.Debian. But still true;
the fact that we need the info in README.Debian illustrates it's
not perfect.
> > - If source package `foo-doc' (creating binary-all package foo-doc)
> > documents source package `foo' (which creates simply binary-arch
> > package foo, or alternatively foo-bin + foo-bin2), then it might be
> > best to leave documentation files under /usr/share/doc/foo-doc/.
>
> I really don't like this. The problem I want to solve is that given
> related packages foo and foo-doc (whether one source pkg or >1), I
> want to *know* where those docs are located[1]. It should be either
> /usr/share/doc/foo or /usr/share/doc/foo-doc. I don't really care which.
Might it be possible that foo-doc documents foo-bin and foo-lib
and that there's no foo package at all? And consequently no
/usr/share/doc/foo directory?
If so, then if we must choose between _always_ /usr/share/doc/foo
or /usr/share/doc/foo-doc, then perhaps /usr/share/doc/foo-doc is
the only consistent choice.
There's a problem: smaller packages that don't have a foo-doc
package bundle docs in the foo package. So you'd have to know
there's a foo-doc package in order to look in /usr/share/doc/foo-doc
> > This makes it more obvious that foo-doc may document a different
> > version of foo than is installed on the system.
>
> That's always true, though, as there is nothing forcing me to keep
> foo-doc and foo in sync, no matter what the source package situation.
True. But at least in that case the docs _are_ available. Is
the source packages are different in the first place, it's
possible that they are out of sync wrt versions (different
authors perhaps).
> I think my personal favorite would be that package foo contain the
> symlink /usr/share/doc/foo/docs->../../foo-doc. I can see that others
> might not like it though. If foo-doc isn't installed, the broken link is
> ugly,
That's why I didn't like it. Unless it's handled and foo and
foo-doc postinst and postrm scripts?
> but it's also a big hint that 'apt-get install foo-doc' might be
> useful.
Hmmm.
-
I kinda like the postinst and postrm script idea. Any reason why
it's bad that anybody can think of?
Thanks,
Peter
Reply to: