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 -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
