[publican-list] Comments in XML files, good, bad, or ugly?

[Jonathan Robie]

I really  wish comments were kept by default, and I'd like CDATA 
sections to be preserved by default. A target that strips comments and 
replaces CDATAsections using character entities woujld be fine.

I like comments to embed version history in files:

<!--
====================================================================
 $Log: expressions.xml,v $
 Revision 1.25  2008/10/01 21:40:10  jrobie3
 Made the following changes:

 (1) XQuery 1.1: Try/catch
 JR try/catch proposal in Query/2008Jun/0170. Group approved the
 proposal, with minor revisions, to be added to XQuery 1.1. Text and
 examples relating to updates and/or scripting should be changed to
 non-normative notes (or deleted) since XQuery 1.1 does not include
 updates or scripting. Approved in F2F at Edinburgh, week of 6/23/08.

 (2) XQuery 1.1: Bug 5472
 M.Kay proposal to extend the "validate" expression to add
 optional ("as" typename)? following ValidationMode. As now, the operand
 expression must return exactly one document or element node.
 Approved in F2F at Oracle, week of 3/31/08.

 (3) XQuery 1.1: Nondeterministic Functions
 DC proposal in Query/2008Mar/0084, as amended: Allow keywords
 on external function decls only. Support both "deterministic" and
 "nondeterministic". Default is nondeterministic. The compiler infers
 the property of internal functions by static analysis.
 Approved in F2F at Oracle, week of 3/31/08.

-->

These comments automatically register the changes from the change logs, 
which makes it easier to write the revision logs at the end of the process.

I use comments for todo-lists within the text;

<!-- ### TODO:
    Provide some good examples in C++. We may not get this done by the 
first release -->

<!--### TODO:
   Agree with Lana on the spelling of "colour" -->

I like them in the text where they don't get lost, and I don't see a lot 
of reason to mark these up. They do need to be cleaned up or stripped 
before delevering the source, though.


For code examples, I find it useful to be able to drop source code 
chunks into CDATA sections and immediately see that they look like the 
original text:
<eg><![CDATA[<bib>
  <book>
    <title>TCP/IP Illustrated</title>
    <author>Stevens</author>
    <publisher>Addison-Wesley</publisher>
  </book>
  <book>
    <title>Advanced Programming in the Unix Environment</title>
    <author>Stevens</author>
    <publisher>Addison-Wesley</publisher>
  </book>
  <book>
    <title>Data on the Web</title>
    <author>Abiteboul</author>
    <author>Buneman</author>
    <author>Suciu</author>
  </book>
</bib>]]></eg>

I can just look at that and know it's an example with well-formed XML. I 
can't do that if you remove the CDATA section and use character entities.

Jonathan