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

[Jeff Fearn]

Jonathan Robie wrote:
> 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:

For me this is an excellent example of the type of content a reviewer might like to see when reviewing a document, which would fit better with a remark than a comment.

Given that no one has supported excluding comments I will add support for them.


---snip---

> 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.

CDATA is an evil, dirty hack that only existed because there wasn't a way to cleanly handle un-escaped textual content.

If the only options were CDATA or escaped textual content, then I too would probably choose CDATA.

There is a third option which allows clean handling of un-escaped textual content, publican encourages this third option.

This third option is particularly useful when you are getting code examples from developers. It allows developers to give you examples in the format they work with. A java programmer could supply you with .java files that you would not have to edit. They could test these in their proper environment and just email or check in the .java files. If they updated their examples they could simply supply an updated .java file. Your XML never needs to be updated once the .java file is included!

>From the publican users guide, faq chapter (http://jfearn.fedorapeople.org/Publican/chap-Publican-Frequently_Asked_Questions.html)

Q:

I have extensive code samples for my book, how can I include them without having to xml escape everything?

A:

The best way to do this is to create a directory named extras in your source language directory and use an xi:include to pull in the code file.

Procedure 5.1. Including code samples

   1.

      Create the extras directory

      mkdir en-US/extras

   2.

      Copy the code file to the extras directory

      cp ~/samples/foo.c en-US/extras/.

   3.

      xi:include the sample file in your xml file

      <programlisting>
      <xi:include parse="text" href="extras/foo.c" xmlns:xi="http://www.w3.org/2001/XInclude" />
      </programlisting>

   4.

      You can now edit en-US/extras/foo.c in your favorite editor without having to be concerned about how it will affect the XML. 


IMHO this is a _much_ cleaner way of handling un-escaped textual content.

Cheers, Jeff.

-- 
Jeff Fearn <jfearn at redhat.com>
Software Engineer
Engineering Operations
Red Hat, Inc
Freedom ... courage ... Commitment ... ACCOUNTABILITY