Nic Ferrier wrote: > But none of that is really important. The bottom line is: you will > never get all the authors of source code to write well-formed XHTML, > you're always going to miss something. That's why it sucks.
OK if this is the problem, let me put it that way: If we _aim_ towards having 100% well-formed XHTML comments, by asking developers to close their open tags etc., the XML doclet would have less trouble outputting valid XML code, which in turn would lead to a higher-quality HTML documentation (and other documentation generated via XSLT.) Besides, as I mentioned before it would be quiet easy to write a doclet which checks every comment for well-formedness. Actually, XML doclet is already quiet tolerant and with a few added out.printlns could provide you with information like e.g. this: WARNING: in java.lang.Number.compareTo(Object) comment (near line 123): (comment line 5) '<' taken as literal - tag looks like email address. WARNING: in java.lang.String class comment (near line 42): (comment line 7) Unclosed <li> tag (comment line 8) Unclosed <li> tag So "missing something" would only be possible when ignoring these warnings. WRT the readability issue: actually, a good deal of Classpath javadoc comments completely lack any HTML tags and are only formatted using indentation and line breaks. While this is of course very legible when looking at the code, and may produce good-looking (though non-standard) Info output, the XML/XSLT solution will not be able to produce good-looking HTML code from this (or any structured output other than plain text-based formats). I find this issue not paramount but in order to offer high-quality documentation in various formats, I think we should propose some guidelines for contributors, including the advice to structure comments using (correct) HTML tags where necessary. Reduces inline readability but enhances output readability, integrity, portability and transformability. Wow!! ;) Other opinions are very welcome. _______________________________________________ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath