Hi All

After feedback from Niels on my first package for Debian I've been
trying to get a new maven based package (args4j - see [0]) to link its
javadoc against the default-jdk-doc API files provided
in /usr/share/doc/openjdk-6-doc/api.

The package is using maven-debian-helper which calls the maven
javadoc:jar and javadoc:aggregate targets to build the javadoc.

I've tried following the advice in the maven-javadoc-plugin FAQ (see
[1]) by populating the maven.properties file with:

maven.javadoc.offlineLinks=/usr/share/doc/openjdk-6-doc/api/

but I can't seem to get maven to generate offline links to the JDK
provided API. As a result links to classes provided by Java (and I
would suspect any other library) are not generated.

Anyone else run into this issue or have a solution?

Thanks in advance for any help!

Cheers

James

[0] http://git.debian.org/?p=pkg-java/args4j.git;a=summary
[1]
http://maven.apache.org/maven-1.x/plugins/javadoc/faq.html#offlineLinks

--
James Page
Software Engineer, Ubuntu Server Team

On Fri, May 6, 2011 at 8:04 PM, James Page <james.page@canonical.com> wrote:
> Hi All
>
> After feedback from Niels on my first package for Debian I've been
> trying to get a new maven based package (args4j - see [0]) to link its
> javadoc against the default-jdk-doc API files provided
> in /usr/share/doc/openjdk-6-doc/api.
>
> The package is using maven-debian-helper which calls the maven
> javadoc:jar and javadoc:aggregate targets to build the javadoc.
>
> I've tried following the advice in the maven-javadoc-plugin FAQ (see
> [1]) by populating the maven.properties file with:
>
> * * * *maven.javadoc.offlineLinks=/usr/share/doc/openjdk-6-doc/api/

You should really link to /usr/share/doc/default-jdk-doc/api to make
the links functional on all architectures.

> but I can't seem to get maven to generate offline links to the JDK
> provided API. *As a result links to classes provided by Java (and I
> would suspect any other library) are not generated.
>
> Anyone else run into this issue or have a solution?
>
> Thanks in advance for any help!

Any chance that you forgot to add default-jdk-doc to build dependencies.
Sorry, can't help you more as I have not worked on any packages using
maven as build system.

Cheers,
Onkar
--
Passion - Some people climb mountains - others write Free software.
Don't ask why - the reason is the same.


--
To UNSUBSCRIBE, email to debian-java-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: BANLkTiki4eSgonf3udsKURVhEP1qcm0jVw@mail.gmail.com ">http://lists.debian.org/BANLkTiki4eSgonf3udsKURVhEP1qcm0jVw@mail.gmail.com

On Fri, May 6, 2011 at 10:04 AM, James Page <james.page@canonical.com> wrote:
> I've tried following the advice in the maven-javadoc-plugin FAQ (see
> [1]) by populating the maven.properties file with:
>
> * * * *maven.javadoc.offlineLinks=/usr/share/doc/openjdk-6-doc/api/

I tried something like that sometime ago with no luck. I don't know if there is
a bug with maven javadoc plugin or with maven debian helper.

The only way that I could make that work was patching the POM, something
like this:

--- checkstyle-5.3.orig/pom.xml
+++ checkstyle-5.3/pom.xml
@@ -375,6 +375,12 @@
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<source>1.5</source>
+ <offlineLinks>
+ <offlineLink>
+ <url>file:///usr/share/doc/default-jdk-doc/api/</url>
+ <location>file:///usr/share/doc/default-jdk-doc/api/</location>
+ </offlineLink>
+ </offlineLinks>
</configuration>
<reportSets>
<reportSet>


This probably is just a hack but you can take a look at checkstyle package:
http://svn.debian.org/wsvn/pkg-java/trunk/checkstyle/debian/patches/01_link_to_system_javadocs.diff

If you succeed on this without having to patch pom files, please let me know.

Cheers,

--
Miguel Landaeta, miguel at miguel.cc
secure email with PGP 0x7D8967E9 available at http://keyserver.pgp.com/
"Faith means not wanting to know what is true." -- Nietzsche


--
To UNSUBSCRIBE, email to debian-java-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: BANLkTi=OUv5ZqO4gvquOgGNueg6RdNojSA@mail.gmail.com ">http://lists.debian.org/BANLkTi=OUv5ZqO4gvquOgGNueg6RdNojSA@mail.gmail.com

Hi Onkar

On Fri, 2011-05-06 at 20:21 +0530, Onkar Shinde wrote:
> > I've tried following the advice in the maven-javadoc-plugin FAQ (see
> > [1]) by populating the maven.properties file with:
> >
> > maven.javadoc.offlineLinks=/usr/share/doc/openjdk-6-doc/api/
>
> You should really link to /usr/share/doc/default-jdk-doc/api to make
> the links functional on all architectures.

Makes sense - I'll update accordingly.

>
> > but I can't seem to get maven to generate offline links to the JDK
> > provided API. As a result links to classes provided by Java (and I
> > would suspect any other library) are not generated.
> >
> > Anyone else run into this issue or have a solution?
> >
> > Thanks in advance for any help!
>
> Any chance that you forgot to add default-jdk-doc to build
> dependencies.
> Sorry, can't help you more as I have not worked on any packages using
> maven as build system.

That would have been a nice easy fix - alas the package does
build-depend on default-jdk-doc so no such luck.

Thanks for you help.

James

--
James Page
Software Engineer, Ubuntu Server Team

Hi Miguel

On Fri, 2011-05-06 at 10:26 -0430, Miguel Landaeta wrote:
> The only way that I could make that work was patching the POM,
> something
> like this:
>
> --- checkstyle-5.3.orig/pom.xml
> +++ checkstyle-5.3/pom.xml
> @@ -375,6 +375,12 @@
> <artifactId>maven-javadoc-plugin</artifactId>
> <configuration>
> <source>1.5</source>
> + <offlineLinks>
> + <offlineLink>
> + <url>file:///usr/share/doc/default-jdk-doc/api/</url>
> +
> <location>file:///usr/share/doc/default-jdk-doc/api/</location>
> + </offlineLink>
> + </offlineLinks>
> </configuration>
> <reportSets>
> <reportSet>
>
>
> This probably is just a hack but you can take a look at checkstyle
> package:
> http://svn.debian.org/wsvn/pkg-java/trunk/checkstyle/debian/patches/01_link_to_system_javadocs.diff

Yes - I considered this approach - works OK for simple libraries;
however I have some packages that have lots of dependencies so that's
not going to scale that well or be very maintainable.

Thanks for the pointer though - I'll let you know if I find a better
solution.

Cheers

James

--
James Page
Software Engineer, Ubuntu Server Team

On 05/06/2011 04:34 PM, James Page wrote:

Hi All

After feedback from Niels on my first package for Debian I've been
trying to get a new maven based package (args4j - see [0]) to link its
javadoc against the default-jdk-doc API files provided
in /usr/share/doc/openjdk-6-doc/api.


please reference /usr/share/doc/openjdk-6/api. Every package should ship its
documentation in /usr/share/doc/<package name without -doc>/api so that the
location doesn't change if you split out the api docs into another package.


Matthias



--
To UNSUBSCRIBE, email to debian-java-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Archive: 4DC41550.9030101@ubuntu.com">http://lists.debian.org/4DC41550.9030101@ubuntu.com