Re: [digester] Problem building javadoc w/ Ant on Windows
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/[EMAIL PROTECTED]by=threadfrom=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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [digester] Problem building javadoc w/ Ant on Windows
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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
[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 andlimitations 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [digester] Problem building javadoc w/ Ant on Windows
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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [digester] Problem building javadoc w/ Ant on Windows
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 quot;? 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [digester] Problem building javadoc w/ Ant on Windows
From: simon [EMAIL PROTECTED] 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? 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 quot;? Using quot;AS ISquot; 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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: [digester] Problem building javadoc w/ Ant on Windows
On Mon, 2005-01-17 at 19:06 -0700, Wendy Smoak wrote: From: simon [EMAIL PROTECTED] 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 ISquot; 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 *
Re: [digester] Problem building javadoc w/ Ant on Windows
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/[EMAIL PROTECTED]by=threadfrom=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 [EMAIL PROTECTED] 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 ISquot; 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
