slachiewicz opened a new issue, #1140:
URL: https://github.com/apache/maven-doxia/issues/1140

   An entity declared in the DOCTYPE of an Xdoc page renders as empty text when 
its value is plain text. No warning is logged, with or without 
`-Dvalidate=true`. Character-reference values work.
   
   ```xml
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE document [
     <!ENTITY product "Acme Widget">
     <!ENTITY copyright "&#169;">
   ]>
   <document xmlns="http://maven.apache.org/XDOC/2.0";>
     <body>
       <section name="Entities">
         <p>Product: [&product;] Copyright: [&copyright;]</p>
       </section>
     </body>
   </document>
   ```
   
   `mvn site` renders:
   
   ```text
   Product: [] Copyright: [&#xa9;]
   ```
   
   The output is the same with maven-site-plugin 3.22.0 on Doxia 2.1.0, with 
Doxia 2.2.0 forced as a plugin dependency, and with maven-site-plugin 3.12.1 on 
Doxia 1.11.1, so this is not a 2.x regression.
   
   The cause is in 
[`AbstractXmlParser`](https://github.com/apache/maven-doxia/blob/master/doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractXmlParser.java):
 the DOCTYPE is read with two regular expressions, `PATTERN_ENTITY_1` and 
`PATTERN_ENTITY_2`, which accept a value that is a single named reference 
(`&alpha;`) or numeric character references (`&#169;`) only. Any other 
replacement text does not match, so the entity stays undefined and the 
reference is dropped. 
[DOXIA-250](https://issues.apache.org/jira/browse/DOXIA-250) (#891) and 
[DOXIA-314](https://issues.apache.org/jira/browse/DOXIA-314) (#322) covered 
character-reference values only. The XHTML5 parser extends the same class; I 
have not checked its output.
   
   Options:
   
   1. Accept plain-text replacement text (no markup) in `<!ENTITY name "...">` 
and pass it through as text. This covers the common use, a product name or 
version string, and stays clear of external entities.
   2. Keep the current scope, but log a warning naming the entity and the page 
when a DOCTYPE entity is not understood, and say in the [Doxia 
FAQ](https://maven.apache.org/doxia/faq.html#doxia-character-entities) that 
only character entities are supported.
   
   I recommend option 1, with option 2's warning for values that still do not 
match, such as values containing markup.
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to