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

[Lana Brindley]

Yay for top posting! ;-)



Silas,

I guess I'm in a position where I don't use it, so I don't really mind 
if it's there or not. With that in mind, perhaps we should be looking at 
it like a choice matter. If we leave the ability out, then no one can 
use it. If we put it in, then writers can choose to use it or not, 
depending on how they work.

L

Douglas Silas Hensley wrote:
> Hi,
> 
> I'm definitely an advocate for retaining comments, which are
> obviously useful. Anything that helps the writers should be retained.
> 
> And I disagree that we're just writers and shouldn't be doing
> "coding/programming" :-) I know that I am, along with others, trying
> to write modular documentation with little duplication, because I
> don't want to have the same content in multiple places that will
> have to be updated separately in the future. Comments, for me, are a
> way to keep track, at the site, of what's going on and how I've
> structured the documentation, among other uses.
> 
> Also, I can comment in OpenOffice, so that's not a function that's
> just relegated to coding (apologies if I have asserted something not
> accurate here).
> 
> Also, maven-jdocbook shows the text of <remarks> by default, which
> could throw someone for a loop. I'm sure you can turn that off as
> well (not that finding out how will be easy), but I don't see the
> point of using <remarks> for comments (<remarks> could be reserved
> for other useful purposes).
> 
> And you might not miss something until it's gone... (plus, it truly
> can be useful for editors, even non-vim ones)
> 
> +1 pro-comment
> 
> Cheers,
> 
> Silas
> 
> Lana Brindley wrote:
>> 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
>>
>> _______________________________________________
>> publican-list mailing list
>> publican-list at redhat.com
>> https://www.redhat.com/mailman/listinfo/publican-list
>> Wiki: https://fedorahosted.org/publican
> 

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