Re: Suggestion for javadoc building
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hello Mark,
> > > most libraries have api docs created with javadocs. When calling
> > > javadoc, links can be given to link to the used api's. I think there
> > > should be a central registry for all javadoc documentations installed.
> > > For this, I suggest a directory which links to all api doc directories.
> > > During javadoc creation, these directories could simply be included in
> > > the package building scripts. The packages using these links, then also
> > > have to depend and build-depend on the packages offering the used api
> > > docs. Later this can be automated by a wget spider or something else.
> gjdoc doesn't currently support -link, although hopefully it will in the
> future (If there are any java programmers listening who aren't busy at
> the moment...).
Never looked at it. I use the j2sdk from blackdown. But having these
directories doesn't imply, that they have to be used, only should if
possible.
> This might not be easier for package scripts as the maintainers would
> have to build-depend on each -doc package and also -link dir, where each
> api doc directory is listed (javadoc looks for a single package-list
> file in each directory).
I know they have to list all. But this can be supported by debhelper. The
dependencies could also be checked after compiling. When the binary is
generated, the build dependencies can be checked against the needed packages
via the links.
> However, having everything in a central
> location and all links pointing there might be a good idea, especially
> from the user POV.
Thats another argument. I think having it in the policy can only be useful.
When it's there, debhelper tools can be created easily.
> I guess work will have to be done on policy after gjdoc is working and
> in Debian,
Hmm. I think gjdoc will be compatible with javadoc when it supports link. And
until there, javadoc will be used by most users. And I think, when it is
avalaible, the most will still use javadoc (or another alternative being
called javadoc and having the same command line api).
> but one question I have is how should interlinking java
> packages dependencies be handled?
First the maintainers of the java-packages can suggest what they need for
using them. I think the most use ant or make. The make users need a script
which outputs the parameters, like with pkg-config, the ant users simply take
all directories in the directory containing the links to the javadocs (via
patterns).
The last would be dh_java which checks against the build-dependencies and
outputs the normal dependencies. Generating them can be done after the docs
are created. Via a shell script and a link spider, all local links can be
extracted. Then the packages can be resolved via the dpkg database.
> We will have a general java api documentation package generated from
> classpath sources.
No, all packages will have their seperate documentation, but link to files in
other packages on which they depend.
> Libraries could then build javadoc linking against this.
Against those packagES you mean? Yes.
> Then, when a user wants the documentation for one library, will he
> also have to download the entire core java api docs and api for any
> linked libraries?
When he whats to recompile the package yes. When he doesn't, that depends on
what dependencies we create.
> or is it appropriate to just Recommend the other
> packages and have broken links?
It's a question of policy. I think it should be debian policy, not only debian
java policy, to have no broken links. So I think depend is the best, the
others should use equivs.
> or are there any better solutions?
Yes, there is. As long as the documentation is also in the internet. A script
could check if the other documentation packages are installed and change the
links for local file's or online versions as necessary. But I think this is
overkill. I think most people using java for development have relativly fast
computers and enough disk space. So why bother.
With kind regards
Torsten Knodt
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.0 (GNU/Linux)
iD8DBQE9r+PeX1/CjdwsodIRApnfAJ9/sxQ1l3Xe12Rigw17r+dZ0NXiNQCgqjRt
TnQmQunUWM6vp4ZUJmspyz4=
=eDme
-----END PGP SIGNATURE-----
Reply to: