Subject: Re: Bug#903428: javadocs generated by javahelper include jquery

From: tony mancill <[email-masked]>
Date: Mon, 16 Jul 2018 22:00:15 -0700

On Wed, Jul 11, 2018 at 06:35:21PM +0200, Markus Koschany wrote:
> Hi tony,
> 
> Am 10.07.2018 um 05:22 schrieb tony mancill:
> [...]
> > I'm in favor of dropping the -java-doc packages completely and instead
> > using our time and effort to improve the state of our runtime libraries,
> > toolchain and application packages.  (It would be a different story if
> > we were developing a distribution for Java developers who don't have
> > ready access to other sources of documentation, but I have a hard time
> > imagining that our users would prefer javadocs over functioning and
> > secure libraries.)
> > 
> >> Well, now we have to convince doku to implement this solution, or at
> >> least to accept it, without closing the bug report again. Volunteers?
> > 
> > Hmm... I choose to believe that the bug (we're talking about [1],
> > right?) was mass-closed along with everything else that was open against
> > src:openjdk-9.  It seems like a reasonable and very "Debian" approach to
> > avoid embedding an available system library.  If we really want javadoc,
> > we could resubmit (preferably with a patch).
> 
> Yes, I was talking about #883981. There are two main issues with javadoc
> at the moment. Firstly the syntax checker has been much more strict
> since OpenJDK 8 and we currently work around a couple of problems by
> simply ignoring javadoc errors, otherwise a lot more packages would be
> RC buggy (FTBFS). Maybe this option will even go away in the future and
> this would leave us with the following choice; either fix the underlying
> error or drop the -doc package. Since we ship a lot of older or even
> unmaintained software, which is still somehow useful to us though, I can
> imagine that for some people our corresponding -doc packages are still a
> good read because there is no equivalent source on the Internet (anymore).
> 
> Sure, that's not the sole reason why we should keep javadoc. My main
> argument is that we would risk to overlook javadoc related issues in our
> tool chain, if we dropped it completely. There should be at least a way
> for people to create their own javadoc packages, preferably without too
> much hassle. As long as that works, we could get over the rest. But
> everything else is a regression.
> 
> And secondly then there is this jquery issue. I don't even know why they
> need Javascript while HTML5 could do probably the same or even a better
> job. Anyway we could fix this at the packaging level by replacing the
> embedded copy with symlinks. There is one issue that remains: Should
> -doc packages depend on jquery as well? There is a chance that the JRE
> (which pulls in the jquery dependency) is not installed on the system.
> 
> So in my opinion it's not a choice between two options, javadoc yes or
> no because at least for the jquery part this should be manageable.
> However the first step is to acknowledge a problem but if bugs get
> closed and everyone is more in favor of dropping javadoc completely,
> then I also become rather "Meh".
 
Hi Markus,

Fair enough.  I can see the value in providing javadoc (or at least a
way to build the javadoc) for older versions of libraries. 

I think Martin Quinson's suggestion of "shim" jquery package has some
merit.  It means that we would have to touch every -java-doc package -
475 of them, by my current count - but I'm not sure that can be avoided
unless we take the path of patching openjdk-11 to use the Debian system
library.

And finally, although I'm still biased towards working on better runtime
support (to wit, libjide-oss-java is currently FTBFS, so the lintian
jquery warning seems less important than that), I don't think we should
ignore the problem and don't want anyone to feel unnecessarily "meh"
about it either... :)

Other ideas?

Cheers,
tony