Support for comment blocks

[pmkovar]

Commented out lines in DocBook XML seem to be dropped silently when converting a doc. It would be nice to either print a warning about this, or better, implement support for AsciiDoc comment blocks.

[mojavelinux]

I'm not convinced that these things really map. I guess it really depends on the nature of the original comment, to which we would have no way of knowing. For instance, is it a note to other authors or is it content that has been filtered out? There's also a big risk of breaking the AsciiDoc by introducing comments at an arbitrary location, since where comments can go in AsciiDoc is more restrictive.

My feeling about this is that comments aren't intended to be something that gets converted (just as we don't publish them). However, if I saw some examples, I might have a different perspective. Could you share some examples?

[pmkovar]

An example could be this file from a Fedora guide:

https://git.fedorahosted.org/cgit/docs/system-administrators-guide.git/tree/en-US/Automating_System_Tasks.xml#n204

Writers often put TODO and FIXME-style info there, though that kind of info should probably go into a remark (which is also unsupported).

However, you are making a very good point about the risks involved. Maybe printing a warning that comment lines are being dropped would prevent the user from assuming they are being converted?

[mojavelinux]

Okay, so I think it's reasonable to have a flag that enables comments to be migrated over. I would like it to be something that can be switched on and off though because this converter has been used to clean documents as well, so it depends on the goal.

[mojavelinux]

The flag could perhaps default to warning or something so that you know when they are being dropped. Having that information come across is important.

[mojavelinux]

To clarify, introduce flag with three states:

• drop
• warn
• port

(or however we name them)

[pmkovar]

Fwiw, sounds good to me. Thanks.