Re: [summary] Re: policy proposition for javadoc installation
Ainsi parlait Andrew Pimlott :
> 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.
You're right there, but:
- distinguishing between user and developper documentation is a subjective
choice, whereas javadoc-generated vs hand-written doc is objective.
- javadoc is present in every java package, while additional
developper-targeted documentation is only present in some cases.
- making -javadoc requires -doc would ensure all other documentation get
installed when installing 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.)
Please keep in mind than this proposition comes from jpackage project, so
usal debian convention don't automatically apply. And the goal is precisely
to be able to install part of the documentation (what you need to run the
application) without having to install everything (what you need to extend
the application).
> > - 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.
Dependencies between -javadoc package is not really a concern IMHO. I was
more concerned about build requirement, where you actually only need the
list-package file, not the HTML files.
> 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
> ).
As long as exact location of list-package (necessary for cross-linking) can
be computed from package name, i'm OK, be it under a new /usr/share/javadoc
directory, or in standard /usr/share/doc location.
For the name of the specific javadoc subdirectory, some applications
(including Sun JDK) uses api, other apidoc, and you just proposed javadoc.
Can we have a quick poll for prefered name here ?
--
Guillaume Rousse <rousse@ccr.jussieu.fr>
GPG key http://lis.snv.jussieu.fr/~rousse/gpgkey.html
Reply to: