commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dennis Lundberg <dennis.lundb...@mdh.se>
Subject Re: [digester] Problem building javadoc w/ Ant on Windows
Date Tue, 18 Jan 2005 07:40:12 GMT
I did some digging in the mail-archives and found the thread I was 
talking about earlier. It can be found here:

http://mail-archives.apache.org/eyebrowse/BrowseList?listName=commons-dev@jakarta.apache.org&by=thread&from=666491

Note that eyebrowse sorts the e-mails with newest-first, so start 
reading from the bottom up...

Let me know if there's anything I can do to help.

-- 
Dennis Lundberg

Simon Kitching wrote:
> On Mon, 2005-01-17 at 19:06 -0700, Wendy Smoak wrote:
> 
>>From: "simon" <simon.kitching@xtra.co.nz>
>>
>>>It does seem
>>>weird that this doesn't work on Windows, as the xml spec is *very* clear
>>>about the fact that xml attributes can be quoted using '...' or "...",
>>>so having a simple testcase that shows the problem would reassure me
>>>that the problem really is what we think it is..
>>
>>We're talking about this section of build.xml:
>>
>>                 bottom='Copyright (c) 2001-2004 - Apache Software 
>>Foundation &lt;!-- 
>>   Licensed under the Apache License, Version 2.0 (the "License");
>>   you may not use this file except in compliance with the License.
>>   You may obtain a copy of the License at
>>
>>       http://www.apache.org/licenses/LICENSE-2.0
>>
>>   Unless required by applicable law or agreed to in writing, software
>>   distributed under the License is distributed on an "AS IS" BASIS,
>>   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
>>   See the License for the specific language governing permissions and
>>   limitations under the License.
>>                 --&gt;'>
>>
>>First, without the quotes around "AS IS", the generated HTML source has only 
>>one line for me when viewed with FireFox and IE, so all the white space and 
>>formatting doesn't seem useful.  The quotes around the word "License" do not 
>>cause a problem, *but* they do not make it into the generated HTML either.
>>
>>Can someone build the docs with Linux and confirm that the formatting and 
>>the quotes around "License" and "AS IS" actually make it into the generated 
>>HTML?  Because if not, the quotes can be removed from build.xml without 
>>affecting the output.
>>
>>Given that this build.xml isn't actually used to build the documentation 
>>that goes on the website, and that the HTML comment that's causing the 
>>problem doesn't even appear in the current Javadoc (such as 
>>http://jakarta.apache.org/commons/digester/apidocs/org/apache/commons/digester/Digester.html
)
>>how important are those quotes?
> 
> 
> In versions prior to 1.53, the "bottom" text was just a simple copyright
> statement. In 1.53.2.3, Robert Donkin added the extra text to this
> attribute.
> 
> As you can see, all the additional text is actually wrapped within xml
> <!-- comments -->, so it isn't visible when viewing the javadoc from a
> browser. But it is visible if you use "view frame source", or load
> the .html file in an editor.
> 
> And for me, the quotes present in the text are preserved. The formatting
> isn't, but that isn't really important. The important point is,
> presumably, to ensure a proper licence statement is present in each
> generated javadoc page.
> 
> See the source for this page:
> http://jakarta.apache.org/commons/digester/commons-digester-1.6/docs/api/overview-summary.html
> for an example of what I get when generating the javadoc.
> 
> 
>>Attempting to fix the problem, once I get rid of the quotes around "AS IS" 
>>then I start getting these warnings:
>>  [javadoc] Constructing Javadoc information...
>>  [javadoc] javadoc: warning - Multiple sources of package comments found 
>>for package "org.apache.commons.digester"
>>  [javadoc] javadoc: warning - Multiple sources of package comments found 
>>for package "org.apache.commons.digester.parser"
>>  [javadoc] javadoc: warning - Multiple sources of package comments found 
>>for package "org.apache.commons.digester.plugins"
>>  [javadoc] javadoc: warning - Multiple sources of package comments found 
>>for package "org.apache.commons.digester.plugins.strategies"
>>  [javadoc] javadoc: warning - Multiple sources of package comments found 
>>for package "org.apache.commons.digester.substitution"
>>  [javadoc] javadoc: warning - Multiple sources of package comments found 
>>for package "org.apache.commons.digester.xmlrules"
>>  [javadoc] javadoc: warning - Multiple sources of package comments found 
>>for package "org.apache.commons"
>>  [javadoc] javadoc: warning - Multiple sources of package comments found 
>>for package "org.apache"
>>  [javadoc] javadoc: warning - Multiple sources of package comments found 
>>for package "org"
>>  [javadoc] Standard Doclet version 1.5.0_01
>>
>>I have no idea what it's talking about.
> 
> 
> I'm not sure what the "multiple sources" messages are either. But they
> don't seem to cause any problems, so I have just been ignoring them.
> 
> 
>>>Ok, so can this be fixed by escaping the quotes in the problem text, eg 
>>>using &quot;?
>>
>>Using &quot;AS IS&quot; doesn't work, I get the same error as with the 
>>original "AS IS".
>>
>>Chalk this one up to annoying but easily fixable.  Other than deleting the 
>>quotes around "AS IS" (which might annoy the lawyer types) I don't see what 
>>else to do with it.
>>
> 
> 
> First up, I guess the question is whether this extra text *needs* to be
> present at all. I'm no lawyer, but it seems rather redundant to me,
> given it has been generated from a source that does have copyright info
> on it, that the javadoc is not useful as a stand-alone product, and that
> APIs can't be copyrighted. None of the following projects have such
> text:
>  * commons-collections
>  * commons-configuration
>  * commons-lang
> 
> Robert, can you tell us what prompted you to add this extra info?
> 
> If I don't hear from Robert soon, I'll check with apache legal.
> 
> Secondly, if it is required, then perhaps some other form like "See <a
> href="{@docroot}/copyright.html">Apache Licence</a>" would be
> acceptable.
> 
> And lastly, I see that the javadoc documentation
> http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html#bottom
> has the vague weasel-words:
> "Any internal quotation marks within text may have to be escaped."
> Lovely, isn't it? They don't even know if the text *does* have to be
> escaped. And if it is, they don't say how. But presumably there *is* a
> way, as it is mentioned. 
> 
> 
> Regards,
> 
> Simon
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> 

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message