Nic Ferrier wrote: > I do agree that XML is the way forward (docbook might make a good > replacement for texinfo when it has widespread support like texinfo) > but the issue of in-source readable comments will need to be solved > before it is a really practical option.
It seems to boil down to inline readability and easy comment maintenance on one hand, and full XHTML compliance for enabling arbitrary XSLT conversions on the other. I agree that strictly applying the XHTML standard will degrade readability and add an additional burden for documentation writers/maintainers, but for that you gain 100% XML compliance with all eventual benefits. I'll leave that for discussion. My opinion is: make comments XHTML compliant and ease the task for writers/maintainers by supplying appropriate (XHTML checking, and perhaps fixing) tools. Live with degraded readability, or better: view the documentation generated by Texinfo doclet instead of consulting inline comments. (Most of the time, you will be looking up docs for a method different from that you are currently working on, so in terms of keystrokes it isn't a big difference whether you open another file and browse to the method definition, or you open the info docs for that method - provided you are using something like jtxd.el for quick access to generated documentation.) > Can't you intelligently escape such things? for example if they don't > turn out to be valid xml. As I said, XML doclet already does something like this. It even tries to guess where unclosed tags are ending and inserts appropriate closing tags, to some extent. But this is more of a hack and quiet error prone - after all, it involves a lot of guessing if you have input whose format is not defined umambigiously. Julian _______________________________________________ Classpath mailing list [EMAIL PROTECTED] http://mail.gnu.org/mailman/listinfo/classpath
