Annotations can not be displayed on content generated by the HTML macro

Annotations can be added, however they can not be displayed because the AnnotationGeneratorChainingListener (that generates annotation rendering events and maps annotations) and AnnotationXHTMLChainingRenderer (that prints the annotation spans using the previous events and mapping) simply can not work with what the HTML macro rendering produces, namely "raw html text" (RAW_TEXT event).

There would be some options here:

1. The AnnotationGeneratorChainingListener could try to render the HTML macro's raw text (using some HTMLRenderingContentAlterer that would need implementing) as HTML so that it can improve its chances of matching what the user actually selects from the browser (i.e. rendered plaintext instead of raw html). On the other side, the AnnotationXHTMLChainingRenderer would have to parse the html raw text in order to make sure that it produces valid HTML when adding the annotaton spans.
In other words, we want to avoid cases like:

<p>He<span class="annotation">llo </p><p>Wo</span>rld</p>

...that would occur if the HTML would not be parsed and treated like plaintext. A correctly parsed output should instead look like:

<p>He<span class="annotation">llo </span></p><p><span class="annotation">Wo</span>rld</p>

• This would work nicely but only if the html macro is clean="true". If it is clean="false" we can not properly parse it and if we try, we will never obtain the same HTML that the user sees in his browser (because that is obtained by joining with the next html macros that might ensure its validity, but we don't have that information at this point in the renderer)

1.1 In an attempt to fix the clean="false" problem, we could decide to re-render the output of the first rendering run. That is: content -> XDOM -> XHTML -> XHTML. We would move the annotation handling in this second rendering and there we would benefit from the part that all HTML macros were executed and we now have the final and valid HTML (assuming there are no real validity problems caused by sloppy devs). At this point we should be safe to apply method 1. since the HTML is parsable.

• The downside of this solution is that (a) it is still a bit fragile to sloppy devs (but that should not be a bit problem), however (b) we would need a full rewriting of the annotation rendering code and (b) we would lose the flexibility of the current implementation that works with XDOM and is not dependent on any output syntax; we would become only able to render XHTML and other use cases like rendering a PDF with annotations would not be possible any more.

2. The cleanest and long-term solution would be to have the HTML macro treated accordingly by the XRENDERING project and have it output proper XDOM events for its content instead of dumping its entire content as raw text. In this case, the current annotation rendering implementation would be able to read the content of HTML macros and handle it properly, like a regular XDOM.

• The problem with this is that the HTML macro is seen as "the elephant in room" by the XRENDERING project, and the aim is to replace it completely in the future by proper wiki syntax for form elements (the main reason why the HTML macro is still kept), its usage being highly advised against and should be limited only to when no other choice exists cases.

Workaround: As it can be seen in the Blog's case (XWIKI-6328), the usual workaround for this problem is to limit the usage of the HTML macro as much as possible, so that annotatable content is never present inside HTML macro blocks.