Re: [summary] Re: policy proposition for javadoc installation
On Fri, Nov 23, 2001 at 12:21:57PM +0100, Guillaume Rousse wrote:
> According to discussion, it seems we agreed on following points:
I didn't realize there was consensus, though that may be because
I've been skimming lots of back mail. I don't think this proposal
has much merit.
> - have standard documentation and javadoc documentation in differents packages
What exactly do you mean by "standard documentation"? I assume you
mean "non-developer documentation". In this case, you are
presenting a false division, because "developer documentation" is
not synonymous with "javadoc documentation". Many (probably most)
libraries have developer documentation that is not javadoc.
There is no reason to take javadoc per se into consideration when
dividing up packages: just go by the usual Debian conventions. In
most cases, I would probably just put docs in a -dev package or a
-doc package. (Depending on what kind of package it is. If it is a
pure library, then libfoo-doc makes sense. If it is mainly an
application, then foo-dev makes more sense. Or maybe foo-dev-doc,
which has some precedent.)
> - install javadoc documentation in /usr/share/javadoc/<package>
The only specific argument I heard in favor was that we already have
/usr/share/man and /usr/share/info . However, man and info
documentation are processed by special-purpose programs. javadoc is
essentially free-form HTML, intended to be read with general-purpose
programs. As long as this is true, I think putting javadoc in a new
place would cause confusion for no gain.
On the other hand, if there are special tools that benefit from
having all the javadoc in one structure, then there would be a good
case for /usr/share/javadoc. But AFAIK, there are no such tools,
and we should wait for them to exist before we codify a special
directory structure.
Also, Debian would have to update policy in order to use this
directory, otherwise it would violate section 13.3 .
> - is cross-linking of javadoc an interesting/achievable feature ?
> When building foo package, depending of bar package, add -linkoffline
> /usr/share/javadoc/bar option to javadoc would provide cross-linked api
> documentation
This would be highly desirable, but slightly problematic because you
could not know (unless you force it with a dependency) that the
linked documentation is installed, so you might have broken links.
This is another reason against /usr/share/javadoc, IMO: If it has
its own /usr/share directory, I expect it to be well-integrated, and
broken links disqualify it as well-integrated.
On the other hand, I have no problem with a convention that javadoc
go under /usr/share/doc/<package>/javadoc , and linking between
those directories. Here <package> should probably be the base
package name; if the javadoc is provided by another package, it can
provide a symlink (I didn't think of this:
http://lists.debian.org/debian-devel/2001/debian-devel-200107/msg01768.html
).
Andrew
Reply to: