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@g.o mailing list