db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rick Hillegas <Richard.Hille...@Sun.COM>
Subject Re: some comments on the 10.4 beta distribution
Date Wed, 02 Apr 2008 17:40:37 GMT
Dyre.Tjeldvoll@Sun.COM wrote:
> Rick Hillegas <Richard.Hillegas@Sun.COM> writes:
>> I have downloaded the source distribution of the 10.4 beta and have a
>> couple comments. After unpacking this distribution, I was able to
>> build the docs and I was able to generate a release. The links from
>> index.html worked. So the structure of the beta looks good to me. The
>> release notes looked sketchy, but I've already sent mail about
>> that. In addition, the following looked odd:
>> o In the user guides, should "Copyright 2004-2007" be changed to
>> "Copyright 2004-2008"?
> I can fix this.
>> o The version number in the user documentation is 10.3, not 10.4
> So I changed the *conrefs.dita files, but the version number in the pdfs
> still says 10.3 (I don't know where to find the version number in the
> html docs). What gives?
>> o In the JDBC3 public api, there's a spurious line just before the
>> title of the top-left frame. The line reads: 'Apache Derby 10.4 API
>> Documentation">'
> I wonder if this is somehow related to the <Doctitle> or
> <Windowtitle> tag, for the javadoc target? 
>     <javadoc sourcepath="${out.javadoc.dir}/sourcedir"
>              executable="${javadocTool}"
>              classpath="${compile.classpath};${osgi};${servlet24};${out.dir}"
>              breakiterator="true"
>              destdir="${public.api.dir}"
>              Overview="${basedir}/published_api_overview.html"
>              Windowtitle="Apache Derby ${major}.${minor} API Documentation"   
>              Header="Apache Derby ${major}.${minor}"
>              Footer="${javadoc.Footer}"
>              bottom="Apache Derby ${major}.${minor} API Documentation  -  &lt;i&
> gt;Copyright &amp;copy; 2004,2008 The Apache Software Foundation. All Rights Res
> erved.&lt;/i&gt;">   
>       <Doctitle><![CDATA[<img src="resources/derby_logo64.png" align="center">
> pache Derby ${major}.${minor} API Documentation]]></Doctitle>   
>       <fileset dir="${derby.engine.src.dir}"
> Any javadoc experts out there that would like to comment?
Well, I'm not going to present myself as a javadoc expert but here's my 
layman's theory: The exact same javadoc directive is used to build the 
jdbc3 and jdbc4 public apis. The spurious line turns up in the jdbc3 
javadoc but not the jdbc4 javadoc. The jdbc3 javadoc is built with the 
Java 5 javadoc tool and the jdbc4 javadoc is built with the Java 6 
javadoc tool. I think that the Java 5 javadoc tool may have a bug that 
was corrected in Java 6.

What we're trying to do in this <doctitle> element is a bit tricky. We 
are trying to generate javadoc whose overview page has a title 
consisting of the Derby logo followed by some useful text. The 
<doctitle> element does not allow nested image elements, and we appear 
to have hacked around this by stuffing the image and text into a CDATA 
section. That CDATA section survives the Java 6 javadoc tool but is 
munged by the Java 5 javadoc tool.

I can get rid of the spurious line at the cost of removing the Derby 
logo. That is, I get rid of the CDATA section and just put text inside 
the <doctitle> element like so:

<Doctitle> Apache Derby ${major}.${minor} API Documentation</Doctitle>  

I miss the pretty logo, but I think that the output without the logo 
looks better than the output with both the logo and the spurious line. I 
can commit this change unless someone wants to put some more time into 
this problem in order to preserve the logo.

>> o The NOTICE file says "Copyright 2004-2007". Should that be changed
>> to "Copyright 2004-2008"?
> Fixed by
> dt136804@khepri32~/derby/derby-scratch$ svn log -r 637190
> ------------------------------------------------------------------------
> r637190 | djd | 2008-03-14 19:09:16 +0100 (Fri, 14 Mar 2008) | 1 line
> Update the ASF collected works copyright to be 2004-2008 in NOTICE and for the javadoc
> ------------------------------------------------------------------------
> (merged to 10.4)

View raw message