You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Wendy Smoak <ja...@wendysmoak.com> on 2005/01/17 18:03:19 UTC
[digester] Problem building javadoc w/ Ant on Windows
I'm getting an error when building the Digester Javadoc locally with Java
1.5 on XP Pro (SP2):
javadoc:
[javadoc] Generating Javadoc
[javadoc] Javadoc execution
[javadoc] javadoc: error - Illegal package name: "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. -->"
It seems to be related to the single/double quotes around the <javadoc
bottom= ... > attribute. Simon Kitching said he cannot reproduce it on
JDK1.5/Linux (http://issues.apache.org/bugzilla/show_bug.cgi?id=33129#c3) so
it appears to be a Windows-only thing.
--
Wendy Smoak
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [digester] Problem building javadoc w/ Ant on Windows
Posted by robert burrell donkin <ro...@blueyonder.co.uk>.
On 18 Jan 2005, at 08:53, Simon Kitching wrote:
<snip>
> Well, I think I'll raise a bugzilla entry with this info, as a reminder
> to think about this further. But for the moment, I'm inclined to leave
> digester as it is, until Robert Donkin reappears and lets us know why
> this was added in the first place.
<IANAL>
my level of legal paranoia is higher than some other committers. at the
time, we needed *everything* licensed with ASL2.0 ASAP. (there are some
jurisdictions which may - in theory - require explicit - rather than
implied - licenses for anything and everything.) so, i added them
everywhere i could including the documentation.
i've never actually been convinced by the prevailing copyright theories
around apache concerning documentation (these are that implied
copyright is sufficient). so, if it's causing problems, i'd be happy
for the license to be removed.
</IANAL>
- robert
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [digester] Problem building javadoc w/ Ant on Windows
Posted by Simon Kitching <sk...@apache.org>.
On Tue, 2005-01-18 at 08:40 +0100, Dennis Lundberg wrote:
> 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.
That's very useful indeed.
So "escaping" of quotes in the "bottom" text for javadoc is necessary on
Windows but not on Linux or Mac. And escaping the quotes can be done
with backslashes, but if you do that then those come through to the
generated html page on Linux. Yecch.
Well, I think I'll raise a bugzilla entry with this info, as a reminder
to think about this further. But for the moment, I'm inclined to leave
digester as it is, until Robert Donkin reappears and lets us know why
this was added in the first place.
Maybe a comment in the build.xml would be useful too...
Anyone got any alternative suggestions?
Regards,
Simon
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [digester] Problem building javadoc w/ Ant on Windows
Posted by Dennis Lundberg <de...@mdh.se>.
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" <si...@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 <!--
>> 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.
>> -->'>
>>
>>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 "?
>>
>>Using "AS IS" 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
Re: [digester] Problem building javadoc w/ Ant on Windows
Posted by Simon Kitching <sk...@apache.org>.
On Mon, 2005-01-17 at 19:06 -0700, Wendy Smoak wrote:
> From: "simon" <si...@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 <!--
> 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.
> -->'>
>
> 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 "?
>
> Using "AS IS" 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
Re: [digester] Problem building javadoc w/ Ant on Windows
Posted by Wendy Smoak <ja...@wendysmoak.com>.
From: "simon" <si...@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 <!--
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.
-->'>
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?
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.
> Ok, so can this be fixed by escaping the quotes in the problem text, eg
> using "?
Using "AS IS" 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.
--
Wendy Smoak
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [digester] Problem building javadoc w/ Ant on Windows
Posted by simon <si...@xtra.co.nz>.
On Mon, 2005-01-17 at 21:55 +0100, Dennis Lundberg wrote:
> Wendy Smoak wrote:
> > I'm getting an error when building the Digester Javadoc locally with
> > Java 1.5 on XP Pro (SP2):
> >
> > javadoc:
> > [javadoc] Generating Javadoc
> > [javadoc] Javadoc execution
> > [javadoc] javadoc: error - Illegal package name: "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. -->"
> >
> > It seems to be related to the single/double quotes around the <javadoc
> > bottom= ... > attribute. Simon Kitching said he cannot reproduce it on
> > JDK1.5/Linux
> > (http://issues.apache.org/bugzilla/show_bug.cgi?id=33129#c3) so it
> > appears to be a Windows-only thing.
>
> I ran into this when we were working on commons-logging 1.0.4. We came
> to the conclusion back then that it seems to be a Windows issue. I had
> problems with 1.4.2.
Ok, so can this be fixed by escaping the quotes in the problem text, eg
using "?
Obviously, the testing will have to be done by someone working on
Windows :-)
Trying to create a minimal testcase would also be useful. I imagine it
should be possible to duplicate this with an ant build file of a dozen
lines and one .java file (or maybe even zero .java files). 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..
Would you mind having a go at this, Wendy? If it is shown to be a
windows problem, and a reasonable workaround can be found I would be
happy to commit it; we really should be able to do complete builds on
Windows as well as proper operating systems :-)
Regards,
Simon
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org
Re: [digester] Problem building javadoc w/ Ant on Windows
Posted by Dennis Lundberg <de...@mdh.se>.
Wendy Smoak wrote:
> I'm getting an error when building the Digester Javadoc locally with
> Java 1.5 on XP Pro (SP2):
>
> javadoc:
> [javadoc] Generating Javadoc
> [javadoc] Javadoc execution
> [javadoc] javadoc: error - Illegal package name: "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. -->"
>
> It seems to be related to the single/double quotes around the <javadoc
> bottom= ... > attribute. Simon Kitching said he cannot reproduce it on
> JDK1.5/Linux
> (http://issues.apache.org/bugzilla/show_bug.cgi?id=33129#c3) so it
> appears to be a Windows-only thing.
I ran into this when we were working on commons-logging 1.0.4. We came
to the conclusion back then that it seems to be a Windows issue. I had
problems with 1.4.2.
--
Dennis Lundberg
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org