Details
-
Bug
-
Resolution: Done
-
Medium
-
None
-
None
-
Documentation (Ref Guide, User Guide, etc.)
-
Description
When exporting from docs.jboss to docbook, the escaping of special characters is currently problematic.
The following issues have been encountered:
- Extracted code samples are wrapped in a cdata tag. The angle-brackets in the cdata tag are then escaped, resulting in <![CDATA[. Build systems then render the tag as visible code rather than reading it as valid markup.
- Angle-brackets that have been converted to entities also their ampersand character escaped again, resulting in <TEXT> (rather than <TEXT>). A solution could be to escape any ampersand characters before escaping square-brackets. This solution was successful in the JIRA Output Tool (https://github.com/dmison/JOT/commit/a4c92913ab0c1372dc9dc0fa0609971a93a6b2b5).
- Instances of ampersand characters in URLs in code fragments are being converted to entities and then rendered by the build system in their escaped form, breaking the validity of the URL. Ampersand characters inside code samples need to be excluded from escaping rules (provided a cdata tag is being inserted) In most instances, this problem could probably be avoided by not putting URLs in code fragments, but there may be times when it's necessary.