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 <!-- > 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="[EMAIL PROTECTED]/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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
