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

[Lana Brindley]

Jeff Fearn wrote:
> Currently when you run `make clean_ids` any comments using the <!-- ... 
> --> format get removed.
> 
> This was left in place as in some circumstances inline comments break 
> translations as the merging process does not match the msgid.
> Is removing the comments the correct behaviour?
> 
> I have no strong feelings on the subject and it is a fairly simple fix 
> from publicans perspective. The translation issue is a problem with 
> either po2xml or msgmerge and would need to be fixed upstream, assuing 
> it hasn't already been fixed.
> 
> Cheers, Jeff.
> 

Oh, are we re-opening this old <strike>argument</strike> discussion??

I was originally an advocate for keeping comments, this was because I 
lost a chunk of data through the make clean_ids behaviour, and got a 
little ... errr ... annoyed ;-)

That said, over time (and with a bit of mellowing) it doesn't seem to me 
to be such a bad thing after all. The point has been raised that 
commenting is a standard function of any code, but the fact remains 
that, while we do indeed use a programming language (of sorts) to write 
our books, what we're doing is not coding, it's writing. We simply use 
the tags to define what our books look like (not how the books perform 
tasks, or complete functions, as does a program).

Do comments belong in books? They certainly have their uses - we can use 
them to leave notes for ourselves (and any reviewers who prefer to 
review the source, rather than the output - whoever they are), but this 
can also be achieved through <remark> - the behaviour of which has 
changed now so that it doesn't print, which is great.

What else are comments good for? Is there anything that can be achieved 
with comments that _can't_ be achieved through the use of another tag 
(like <remark>)?

I personally can't find any good reason to keep them in, despite my best 
efforts. Perhaps that's just because I'm used to the behaviour now, and 
it's a case of better the devil you know? If anyone can come up with a 
compelling reason for changing the behaviour, I'd like to hear it :)

L
-------------- next part --------------
A non-text attachment was scrubbed...
Name: lbrindle.vcf
Type: text/x-vcard
Size: 976 bytes
Desc: not available
URL: <http://listman.redhat.com/archives/publican-list/attachments/20081015/0818df53/attachment.vcf>