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

From: Markus Koschany <[email-masked]>
Date: Wed, 11 Jul 2018 18:35:21 +0200

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".

Regards,

Markus