[gentoo-java] Installing Javadoc documentation with java-pkg_dohtml

[gentoo-java] Installing Javadoc documentation with java-pkg_dohtml

[Ernst de Haan]

Hi all,


While new to writing Ebuilds, I'm creating one for 'xmlenc', a
Java-based XML output library. I'm using the information I find in the
Gentoo Java Developer Guide (
http://www.gentoo.org/proj/en/java/java-devel.xml )

In the section "Directory Names" it says:
"Javadoc documentation is installed in /usr/share/doc/${PF}/html/api/"

Then further down it says:
"If the program provides documentation, in particular API
documentation, make certain your ebuild runs javadoc and installs the
documentation using java-pkg_dohtml."

However, I find that java-pkg_dohtml rather installs in
/usr/share/doc/${PF}/html/ without the "api/" suffix.

Is this correct behaviour? Is there a flag that will install the
Javadoc in a subdirectory of the "html" directory?

Note that I plan to write another Ebuild for a Java-based framework
(XINS) that would come with both Javadoc API documentation and log
documentation, so in that case I wonder which function I should use
for the latter. Should it be java-pkg_dohtml or just dohtml ?


Kind regards,


Ernst de Haan

PS 1: xmlenc can be found at http://xmlenc.sourceforge.net/
PS 2: XINS can be found at http://xins.sourceforge.net/

-- 
gentoo-java@gentoo.org mailing list

[gentoo-java] Re: Installing Javadoc documentation with java-pkg_dohtml

[Ernst de Haan]

[-- Attachment #1: Type: text/plain, Size: 315 bytes --]

> While new to writing Ebuilds, I'm creating one for 'xmlenc', a
> Java-based XML output library. I'm using the information I find in the

While I'm at it, attached is the current version of my xmlenc ebuild.
As this is my very first Ebuild, feedback is highly appreciated.

Kind regards,


Ernst de Haan

[-- Attachment #2: dev-java_xmlenc.tgz --]
[-- Type: application/x-gzip, Size: 1462 bytes --]

Re: [gentoo-java] Re: Installing Javadoc documentation with java-pkg_dohtml

[Petteri Räty]

[-- Attachment #1: Type: text/plain, Size: 582 bytes --]

Ernst de Haan wrote:
>>While new to writing Ebuilds, I'm creating one for 'xmlenc', a
>>Java-based XML output library. I'm using the information I find in the
> 
> 
> While I'm at it, attached is the current version of my xmlenc ebuild.
> As this is my very first Ebuild, feedback is highly appreciated.
> 
> Kind regards,
> 

Please don't send tarballs to this mailing list. Just simple plain text
attachements will do. It's not like a simple ebuild would be big in
size. It is a lot easier to review the stuff when the email client is
able to inline it. Thanks.

Regards,
Petteri

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-java] Installing Javadoc documentation with java-pkg_dohtml

[Joshua Nichols]

Ernst de Haan wrote:
> Hi all,
>
>
> While new to writing Ebuilds, I'm creating one for 'xmlenc', a
> Java-based XML output library. I'm using the information I find in the
> Gentoo Java Developer Guide (
> http://www.gentoo.org/proj/en/java/java-devel.xml )
>
> In the section "Directory Names" it says:
> "Javadoc documentation is installed in /usr/share/doc/${PF}/html/api/"
>
> Then further down it says:
> "If the program provides documentation, in particular API
> documentation, make certain your ebuild runs javadoc and installs the
> documentation using java-pkg_dohtml."
>
> However, I find that java-pkg_dohtml rather installs in
> /usr/share/doc/${PF}/html/ without the "api/" suffix.
>   
> Is this correct behaviour? Is there a flag that will install the
> Javadoc in a subdirectory of the "html" directory?
>
>   
As you have pointed out, currently java-pkg_dohtml does not 
automatically put the javadocs into the api/ directory.

Instead, what you need to do is make sure that the javadocs somehow get 
into a directory named 'api', and then call 'java-pkg_dohtml -r ' on 
that directory. If the package uses ant, sometimes the destination of 
javadocs is controlled by a property, so you could redefine that to be 
'api'. But the simplest way would be to simply rename the directory 
where the javadocs live to 'api'.

I've mentioned this before somewhere, but maybe we should have a 
dojavadoc function in the eclass, or more generically doapidoc?

It could be something like:
doapidoc() {
     local orig_dir=${1}
     local api_dir=${orig_dir}
     if [[ $(basename ${orig_dir}) != api ]]; then
         api_dir=${T}/api
         cp -r ${orig_dir} ${api_dir}
    fi
    dohtml -r ${api_dir}
}
(Sorry if its a little rough, just wanted to get the idea out).

> Note that I plan to write another Ebuild for a Java-based framework
> (XINS) that would come with both Javadoc API documentation and log
> documentation, so in that case I wonder which function I should use
> for the latter. Should it be java-pkg_dohtml or just dohtml ?
>   
It probably doesn't matter which you use for installing the log 
documentation, although I would personally use java-pkg_dohtml to be on 
the safe side.

I also suggest you create a new bug over at bugs.gentoo.org, so that 
others can contribute, provide feedback, and monitor the progress. 
Additionally, you may want to lurk around #gentoo-java on 
irc.freenode.net for ebuild pointers.

--

Josh
-- 
gentoo-java@gentoo.org mailing list

Re: [gentoo-java] Re: Installing Javadoc documentation with java-pkg_dohtml

[Ernst de Haan]

> Please don't send tarballs to this mailing list. Just simple plain text

Will do. Thanks for the pointer.


Ernst de Haan

-- 
gentoo-java@gentoo.org mailing list

[gentoo-java] Re: Installing Javadoc documentation with java-pkg_dohtml

[Ernst de Haan]

[-- Attachment #1: Type: text/plain, Size: 236 bytes --]

> While I'm at it, attached is the current version of my xmlenc ebuild.
> As this is my very first Ebuild, feedback is highly appreciated.

This time as a plain text .ebuild file. Comments are highly appreciated!


Ernst de Haan

[-- Attachment #2: xmlenc-0.51.ebuild.txt --]
[-- Type: text/plain, Size: 1042 bytes --]

# Copyright 1999-2005 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: /cvsroot/xins/xins-ebuild/xins-1.3.0.ebuild,v 1.1 2005/12/16 13:03:19 znerd Exp $

inherit java-pkg eutils

DESCRIPTION="Performance-optimized XML output library for Java"
HOMEPAGE="http://xmlenc.sourceforge.net/"
SRC_URI="mirror://sourceforge/xmlenc/${P}.tgz"

LICENSE="BSD"
SLOT="0"
KEYWORDS="~x86 ~ppc ~sparc ~amd64"
IUSE="debug doc jikes source"

RDEPEND=">=virtual/jre-1.3"

DEPEND=">=virtual/jdk-1.3
	>=dev-java/ant-core-1.6
	jikes? ( dev-java/jikes )
	source? ( app-arch/zip )"

src_compile() {
	local antflags="jar"
	use debug && antflags="-Djavac.debug=true ${antflags}"
	use jikes && antflags="-Dbuild.compiler=jikes ${antflags}"
	einfo "Ant flags: ${antflags}"
	ant ${antflags} || die "Compilation failed."
	use doc && ( ant javadoc || die "Javadoc generation failed." )
}

src_install() {
	java-pkg_dojar build/xmlenc.jar
	use doc && java-pkg_dohtml -r build/javadoc/*
	use source && java-pkg_dosrc src/main/*
}

Re: [gentoo-java] Re: Installing Javadoc documentation with java-pkg_dohtml

[Petteri Räty]

[-- Attachment #1: Type: text/plain, Size: 1427 bytes --]

Ernst de Haan wrote:
>>While I'm at it, attached is the current version of my xmlenc ebuild.
>>As this is my very first Ebuild, feedback is highly appreciated.
> 
> 
> This time as a plain text .ebuild file. Comments are highly appreciated!
> 

Here we go.

> KEYWORDS="~x86 ~ppc ~sparc ~amd64"

Do you have all these arches to test with?
http://dev.gentoo.org/~plasmaroo/devmanual/keywording/

> src_compile() {
> 	local antflags="jar"
> 	use debug && antflags="-Djavac.debug=true ${antflags}"
> 	use jikes && antflags="-Dbuild.compiler=jikes ${antflags}"
> 	einfo "Ant flags: ${antflags}"

We don't einfo the antflags like this because there is nothing of
interest to the user. Feel free to use them for debugging but don't
leave them to the final ebuild.

> 	ant ${antflags} || die "Compilation failed."
> 	use doc && ( ant javadoc || die "Javadoc generation failed." )

Using parenthesis like this makes a subshell ( see man bash ). dieing
inside a subshell will not quit like you expect it to. Why not just add
javadoc to antflags?

> }
> 
> src_install() {
> 	java-pkg_dojar build/xmlenc.jar

java-pkd_dojar build/*.jar is probably more future proof so when version
bumping new jars are not missed.

Please note that these comments are only based on looking at the code. I
might find more if I ever get to actually testing it.

Thanks for the work so far.
http://www.gentoo.org/doc/en/ebuild-submit.xml

Regards,
Petteri

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 256 bytes --]

Re: [gentoo-java] Re: Installing Javadoc documentation with java-pkg_dohtml

[Ernst de Haan]

> > KEYWORDS="~x86 ~ppc ~sparc ~amd64"
>
> Do you have all these arches to test with?
> http://dev.gentoo.org/~plasmaroo/devmanual/keywording/

Thanks for the pointer. Changed to ~x86.

Is there any way to test on Gentoo systems on the other platforms? Are
there any environments dedicated to this? If so, are they available
only to Gentoo committers or also to regular contributors?

I do have access to Linux 2.6/PPC and Solaris/Sparc systems and I did
test xmlenc on them, but these systems were not running Gentoo. So I
tested the original software and the Gentoo ebuild. So in principle
the ebuild /should/ work on other architectures that support Java.

> We don't einfo the antflags like this because there is nothing of
> interest to the user. Feel free to use them for debugging but don't
> leave them to the final ebuild.

Indeed I only put it in for my own interest. I've removed it now.

> Using parenthesis like this makes a subshell ( see man bash ). dieing
> inside a subshell will not quit like you expect it to. Why not just add
> javadoc to antflags?

Oops. That would be unexpected behaviour to me, indeed. The reason I
split the two is so that the info in the die would be more precise.
I've combined them again.

> java-pkd_dojar build/*.jar is probably more future proof so when version
> bumping new jars are not missed.

Sounds good. Made the change.

> Please note that these comments are only based on looking at the code. I
> might find more if I ever get to actually testing it.

As I said, I would indeed be very interested in testers, mostly for
non-x86 platforms.

> http://www.gentoo.org/doc/en/ebuild-submit.xml

I will submit it ASAP.


Ernst

-- 
gentoo-java@gentoo.org mailing list

Re: [gentoo-java] Re: Installing Javadoc documentation with java-pkg_dohtml

[Ernst de Haan]

> As I said, I would indeed be very interested in testers, mostly for
> non-x86 platforms.
>
> > http://www.gentoo.org/doc/en/ebuild-submit.xml
>
> I will submit it ASAP.

It has been submitted:
http://bugs.gentoo.org/show_bug.cgi?id=116489

Feedback is still highly appreciated.


Ernst

-- 
gentoo-java@gentoo.org mailing list

[gentoo-java] Re: Installing Javadoc documentation with java-pkg_dohtml

[Wiktor Wandachowicz]

Ernst de Haan wrote:

> While new to writing Ebuilds, I'm creating one for 'xmlenc', a
> Java-based XML output library. I'm using the information I find in the
> Gentoo Java Developer Guide (
> http://www.gentoo.org/proj/en/java/java-devel.xml )
> 
> In the section "Directory Names" it says:
> "Javadoc documentation is installed in /usr/share/doc/${PF}/html/api/"
> 
> Then further down it says:
> "If the program provides documentation, in particular API
> documentation, make certain your ebuild runs javadoc and installs the
> documentation using java-pkg_dohtml."

And while the java-pkg_dohtml is discussed, it's worth to mention
that there is a bug (http://bugs.gentoo.org/show_bug.cgi?id=114831)
concerning exactly this function.

The reporter points out that there is no documentation for java-pkg_dohtml.
A single paragraph with conclusions from this thread would be sufficient
to close the bug IMHO.

Regards,


-- 
gentoo-java@gentoo.org mailing list

Re: [gentoo-java] Re: Installing Javadoc documentation with java-pkg_dohtml

[Ernst de Haan]

Unless java-pkg_dohtml either serves a specific function or is planned
to serve a specific function, it should be considered for deprecation
and removal, IMHO.

Currently it serves no function other than calling dohtml, so is there
any plan to make it implement a certain Java-specific function?

Ernst

-- 
gentoo-java@gentoo.org mailing list