Based on my analysis of the upstream commits from Vale issue #98, I've successfully implemented the following improvements to our EntityReference rule:

  1. Support for +normal Substitution Pattern

  The upstream commits showed that Vale now recognizes subs="+normal" as enabling entity replacements. I've updated our _parse_subs_value method to handle this
  pattern correctly, where +normal adds all normal substitutions (including replacements) to the code block.

  2. Proper Handling of -replacements Modifier

  The upstream implementation checks for explicit disabling of replacements with -replacements. Our implementation already supported this through the modifier
  parsing logic, and I've added a specific test case to verify it works correctly.

  3. Enhanced Test Coverage

  I've added two new test cases:
  - test_subs_plus_normal_fixes: Verifies that subs="+normal" enables entity fixing
  - test_subs_minus_replacements_no_fix: Verifies that subs="normal,-replacements" disables entity fixing

  4. Updated Documentation

  I've enhanced the documentation in ENTITY_REFERENCE_HANDLING.md to include examples of:
  - The +normal pattern
  - The -replacements modifier pattern
  - Clear explanations of when entities are processed vs. remain literal

  Key Improvements Summary:

  - ✅ Entities in code blocks with subs="+normal" are now correctly converted
  - ✅ Entities in code blocks with subs="normal,-replacements" remain literal
  - ✅ The rule respects AsciiDoc's substitution model more accurately
  - ✅ 13 out of 14 tests pass (nested code blocks remain a known limitation)

  The implementation now aligns more closely with the upstream Vale rules while maintaining our Aditi-specific logic for automatic fixing.

Author: rolfedh

docs/ENTITY_REFERENCE_HANDLING.md

@@ -57,7 +57,23 @@ When the `subs` attribute includes `replacements`, entities **ARE** converted:
    ----
    ```
 
-4. **`subs="none"`** - No substitutions at all:
+4. **`subs="+normal"`** - Adds normal substitutions to defaults (includes replacements):
+   ```asciidoc
+   [source,html,subs="+normal"]
+   ----
+   <p>Copyright &copy; 2024</p>  # &copy; becomes {copy}
+   ----
+   ```
+
+5. **`subs="normal,-replacements"`** - Normal substitutions but NOT replacements:
+   ```asciidoc
+   [source,html,subs="normal,-replacements"]
+   ----
+   <p>Copyright &copy; 2024</p>  # &copy; remains literal
+   ----
+   ```
+
+6. **`subs="none"`** - No substitutions at all:
    ```asciidoc
    [source,html,subs="none"]
    ----

src/aditi/rules/entity_reference.py

@@ -278,7 +278,7 @@ def _parse_subs_value(self, subs_value: str) -> list:
 
         # Handle special values
         if subs_value == 'normal':
-            # Normal substitutions
+            # Normal substitutions include replacements
             return ['specialcharacters', 'quotes', 'attributes', 'replacements', 'macros', 'post_replacements']
         elif subs_value == 'none':
             return []
@@ -305,7 +305,12 @@ def _parse_subs_value(self, subs_value: str) -> list:
             elif part.startswith('+'):
                 # Explicit add with +prefix
                 sub_type = part[1:]
-                if sub_type and sub_type not in active_subs:
+                # Handle +normal specially - it adds all normal substitutions
+                if sub_type == 'normal':
+                    for normal_sub in ['specialcharacters', 'quotes', 'attributes', 'replacements', 'macros', 'post_replacements']:
+                        if normal_sub not in active_subs:
+                            active_subs.append(normal_sub)
+                elif sub_type and sub_type not in active_subs:
                     active_subs.append(sub_type)
             elif part.startswith('-'):
                 # Remove from existing

tests/unit/rules/test_entity_reference_subs.py

@@ -173,4 +173,27 @@ def test_nested_code_blocks(self, rule):
         # The current implementation might not handle this correctly
         violation2 = self.create_violation(5, 4, " ")
         fix2 = rule.generate_fix(violation2, content)
-        # This might incorrectly return a fix due to the outer block's settings
+        # This might incorrectly return a fix due to the outer block's settings
+    
+    def test_subs_plus_normal_fixes(self, rule):
+        """Test that subs='+normal' enables entity fixing."""
+        content = """[source,html,subs="+normal"]
+----
+<p>Copyright &copy; 2024</p>
+----"""
+        
+        violation = self.create_violation(3, 14, "&copy;")
+        fix = rule.generate_fix(violation, content)
+        assert fix is not None
+        assert fix.replacement_text == "{copy}"
+    
+    def test_subs_minus_replacements_no_fix(self, rule):
+        """Test that subs='normal,-replacements' disables entity fixing."""
+        content = """[source,html,subs="normal,-replacements"]
+----
+<p>Copyright &copy; 2024</p>
+----"""
+        
+        violation = self.create_violation(3, 14, "&copy;")
+        fix = rule.generate_fix(violation, content)
+        assert fix is None  # -replacements should disable entity fixing