[MCHANGES-466] Add optional parameter escapeText

[jira-importer]

Stefan Seifert opened MCHANGES-466 and commented

By default, all text read from changes.xml is interpreted as plaint text, and transferred 1:1 to the generated changes reports, which is most times HTML, but can also be other formats like PDF. Thus any HTML markup that is included in changes.xml is not treated as markup but as plain text, even if HTML output is generated.

Goal of this ticket is to introduced a new parameter escapeText for the changes goal which is true by default. If set to false the text contained in changes XML is passed as "raw text" to Doxia, allowing HTML markup contained in changes.xml to be transferred 1:1 to the output, thus being interpreted as HTML markup in HTML output. I has to be documented clearly to the user that setting this parameter to true will break any non-HTML output, so users should use it with care.

If disabled, and if only HTML output is used, setting the parameter to false allows to use advanced formatting/markup in the changes reports like:

• Links (anchor tags)
• Simple formatting like bold and italics to highlight important things in the changelog

—

This new feature is a replacement for the escapeHTML parameter, which was present in changes plugin version 2.x and was removed for 3.x as it was marked as deprecated a long time ago.

Technically, an implementation for this new feature is quite similar to reverting PRs #54 and #48, but using a different parameter name. An integration test should be added as well.

---

Issue Links:

• MCHANGES-465 Bring back parameter escapeHTML
  ("supercedes")

Remote Links:

• GitHub Pull Request #113
  

[jira-importer]

Elliotte Rusty Harold commented

 In general I'm very skeptical of copying markup from an XML document as plain text. There are about 1000 ways for this to go wrong and it usually does. Maybe this is one of the rare cases where this makes. However, I'd like to consider whether this might be adding one problem on top of another, rather than fixing the original problem.

Perhaps the changes plugin should be putting raw text into changes.xml instead of HTML or other markup. E.g. should it be writing <p> instead of <p>? They are not the same thing. If it writes the former. then this can be copied straight into a plain text document with the expected result.

[jira-importer]

Elliotte Rusty Harold commented

I also suspect bad use of namespaces is also contributing to this problem. If we're putting HTML elements in the http://maven.apache.org/changes/2.0.0 namespace, then that is a bug. Or maybe the bug is that we're not properly XML escaping the raw text we receive from some source.

The more I look at this the more I'm convinced there is a serious issue here. I just want to be careful that we fix the real problem rather papering over it.

[jira-importer]

Elliotte Rusty Harold commented

Also if we're putting HTML markup in changes.xml, then we're likely violating the schema at https://maven.apache.org/plugins/maven-changes-plugin/xsd/changes-2.0.0.xsd

[jira-importer]

Stefan Seifert commented

to make my example clear how we use the changes.xml in our projects with the changes plugin generating the changelog:

• example of changes.xml with HTML markup: https://github.com/wcm-io/io.wcm.handler.media/blob/ee2dbef7a1a60706106606579e1adf6cec35e187/changes.xml#L162-L197 contains some sections with CDATA to include HTML markup
• rendered report (not interpreting the markup as it was already migrated to changes plugin 3.x): https://wcm.io/handler/media/changes.html#release_2.0.0__2024-01-26

so we are not violating the schema as we put in the markup properly escaped using CDATA in changes.xml. we expect to put the text in without further escaping as raw text into doxia to be interpreted as HTML markup in the generated HTML report.

[jira-importer]

Elliotte Rusty Harold commented

OK, if it's in a CDATA section then it''s just text then it's just text and it's not violating the schema. You're passing this text into doxia and, and Doxia interprets it as text. You want the ability to call sink.rawText instead of sink.text for the specified content.

https://maven.apache.org/doxia/developers/sink.html#Avoid_sink.rawText.21

There's a very strong impedance mismatch between the APIs here that will make this very tricky to get right without unintended side effects. We need to tread carefully.

[jira-importer]

Stefan Seifert commented

i've provided a PR with implementation and integration tests: #113

[jira-importer]

Stefan Seifert commented

PR seems to be complete and approved - can it be merged?

[jira-importer]

Stefan Seifert commented

thanks for merging!