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

[Douglas Silas Hensley]

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

-- 
Douglas Silas
Technical Writer | Red Hat, Inc.
Purkyňova 99 | Brno, Czech Republic
Office Direct Dial—62116
Brno Office—(+420) 532 294 116
dhensley at redhat.com



-- 
Douglas Silas
Technical Writer | Red Hat, Inc.
Purkyňova 99 | Brno, Czech Republic
Office Direct Dial—62116
Brno Office—(+420) 532 294 116
dhensley at redhat.com