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

[Murray McAllister]

Christopher Curran wrote:
> Murray McAllister wrote:
>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>>
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican
>>
>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>>
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican
>>
>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>>
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican
>>
>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>>
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican
>>
>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>>
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican
>>
>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>>
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican
>>
>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>>
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican
>>
>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>>
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican
>>
>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>>
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican
>>
>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>>
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican
>>
>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>>
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican
>>
>> Christopher Curran wrote:
>>> 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
>>>>
>>>>   
>>> +1 for comments
>>> No one writes self documenting anything. Nuf said.
>>>
>>>> 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
>>>>>     
>>>>
>>>>   
>>>
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican
>>
>>
>> Trimming posts takes too much effort.
>>> _______________________________________________
>>> publican-list mailing list
>>> publican-list at redhat.com
>>> https://www.redhat.com/mailman/listinfo/publican-list
>>> Wiki: https://fedorahosted.org/publican 
> I thought I could almost hear something off-list.
> 
> Chris
> 
pwned! ;)