Allow entities in headings

CHANGES.md

@@ -25,6 +25,9 @@ This file describes changes in the AutoDoc package.
   - Relax filtering for auto-generated chapter and section labels and
     chapter XML filenames, preserving more punctuation while still
     stripping characters that are known to cause trouble
+  - Strip XML-special characters from generated chapter, section, and
+    subsection labels so entity names in headings no longer produce
+    invalid XML
   - Greatly improve the package manual.
   - Convert the hand-written manual chapters from XML to `.autodoc`
   - Fix an unexpected and confusing error when mixing explicit

gap/DocumentationTree.gi

@@ -14,7 +14,13 @@ BindGlobal( "AUTODOC_IsSafeGeneratedLabelCharacter",
     local code;
 
     code := IntChar( c );
-    return code >= 32 and code <> 127 and not c in "/\\";
+    return code >= 32 and code <> 127 and not c in "/\\&<>\";";
+end );
+
+BindGlobal( "AUTODOC_NormalizeGeneratedLabel",
+  function( label )
+    return Filtered( ReplacedString( label, " ", "_" ),
+                     AUTODOC_IsSafeGeneratedLabelCharacter );
 end );
 
 BindGlobal( "AUTODOC_IsSafeGeneratedFilenameCharacter",
@@ -156,8 +162,7 @@ InstallGlobalFunction( AUTODOC_LABEL_OF_CONTEXT,
     else
         Error( "wrong type of context" );
     fi;
-    label := Filtered( label, AUTODOC_IsSafeGeneratedLabelCharacter );
-    return label;
+    return AUTODOC_NormalizeGeneratedLabel( label );
 end );
 
 ###################################

gap/Parser.gi

@@ -725,7 +725,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
             if not IsBound( chapter_info[ 1 ] ) then
                 ErrorWithPos( "found @ChapterLabel with no active chapter" );
             fi;
-            label_name := ReplacedString( current_command[ 2 ], " ", "_" );
+            label_name := AUTODOC_NormalizeGeneratedLabel( current_command[ 2 ] );
             scope_chapter := ChapterInTree( tree, chapter_info[ 1 ] );
             SetLabel( scope_chapter, Concatenation( "Chapter_", label_name ) );
         end,
@@ -753,7 +753,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
             if not IsBound( chapter_info[ 2 ] ) then
                 ErrorWithPos( "found @SectionLabel with no active section" );
             fi;
-            label_name := ReplacedString( current_command[ 2 ], " ", "_" );
+            label_name := AUTODOC_NormalizeGeneratedLabel( current_command[ 2 ] );
             scope_section := SectionInTree( tree, chapter_info[ 1 ], chapter_info[ 2 ] );
             SetLabel( scope_section, Concatenation( "Section_", label_name ) );
         end,
@@ -780,7 +780,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
             if not IsBound( chapter_info[ 3 ] ) then
                 ErrorWithPos( "found @SubsectionLabel with no active subsection" );
             fi;
-            label_name := ReplacedString( current_command[ 2 ], " ", "_" );
+            label_name := AUTODOC_NormalizeGeneratedLabel( current_command[ 2 ] );
             scope_subsection := SubsectionInTree( tree, chapter_info[ 1 ], chapter_info[ 2 ], chapter_info[ 3 ] );
             SetLabel( scope_subsection, Concatenation( "Subsection_", label_name ) );
         end,

tst/worksheets.tst

@@ -19,6 +19,13 @@ gap> AUTODOC_TestWorkSheet("autoplain");
 #I  Chapter 1...
 #I  extracted 3 examples
 
+#
+gap> AUTODOC_TestWorkSheet("label-entities");
+#I  Extracting manual examples for Label Entities Test package ...
+#I  1 chapters detected
+#I  Chapter 1...
+#I  no examples
+
 #
 gap> AUTODOC_TestWorkSheet("paired-structure");
 #I  Extracting manual examples for Paired Structure Test package ...

tst/worksheets/label-entities.expected/_AutoDocMainFile.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<#Include SYSTEM "_Chapter_Introduction.xml">

tst/worksheets/label-entities.expected/_Chapter_Introduction.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<Chapter Label="Chapter_Introduction">
+<Heading>Introduction</Heading>
+
+<P/>
+<Section Label="Chapter_Introduction_Section_What_is_GAP?">
+<Heading>What is &GAP;?</Heading>
+
+<P/>
+Entity-driven heading text should stay unchanged.
+<P/>
+</Section>
+
+<Section Label="Section_AB_C_D">
+<Heading>Explicit label section</Heading>
+
+<P/>
+Explicit label text should also stay unchanged.
+</Section>
+
+</Chapter>
+

tst/worksheets/label-entities.expected/_entities.xml

@@ -0,0 +1 @@
+<!ENTITY Label_Entities_Test '<Package>Label_Entities_Test</Package>'>

tst/worksheets/label-entities.expected/title.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<TitlePage>
+  <Title>
+    Label Entities Test
+  </Title>
+  <Date>
+    11 March 2026
+  </Date>
+  </TitlePage>

tst/worksheets/label-entities.sheet/plain.autodoc

@@ -0,0 +1,13 @@
+@Title Label Entities Test
+@Date 2026-03-11
+
+@Chapter Introduction
+
+@Section What is ⪆?
+
+Entity-driven heading text should stay unchanged.
+
+@Section Explicit label section
+@SectionLabel A&B <C> "D"
+
+Explicit label text should also stay unchanged.