gap-packages · fingolfin · Mar 11, 2026 · Mar 11, 2026
diff --git a/CHANGES.md b/CHANGES.md
@@ -22,6 +22,9 @@ This file describes changes in the AutoDoc package.
     commands such as `@Title`, `@Subtitle`, `@Version`, `@Author`, and
     `@Date`, and trim trailing blank lines from generated title-page
     content so they no longer leak into filenames or empty author entries
+  - 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
   - Greatly improve the package manual.
   - Convert the hand-written manual chapters from XML to `.autodoc`
   - Fix an unexpected and confusing error when mixing explicit

diff --git a/gap/DocumentationTree.gi b/gap/DocumentationTree.gi
@@ -9,6 +9,22 @@
 BindGlobal( "AUTODOC_IdentifierLetters",
             "+-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz" );
 
+BindGlobal( "AUTODOC_IsSafeGeneratedLabelCharacter",
+  function( c )
+    local code;
+
+    code := IntChar( c );
+    return code >= 32 and code <> 127 and not c in "/\\";
+end );
+
+BindGlobal( "AUTODOC_IsSafeGeneratedFilenameCharacter",
+  function( c )
+    local code;
+
+    code := IntChar( c );
+    return code >= 32 and code <> 127 and not c in "/\\:";
+end );
+
 DeclareRepresentation( "IsTreeForDocumentationRep",
         IsAttributeStoringRep and IsTreeForDocumentation,
         [ ] );
@@ -140,7 +156,7 @@ InstallGlobalFunction( AUTODOC_LABEL_OF_CONTEXT,
     else
         Error( "wrong type of context" );
     fi;
-    label := Filtered(label, x -> x in AUTODOC_IdentifierLetters);
+    label := Filtered( label, AUTODOC_IsSafeGeneratedLabelCharacter );
     return label;
 end );
 
@@ -405,9 +421,10 @@ BindGlobal( "AUTODOC_ChapterFilename",
   function( node )
     local filename;
 
-    # Remove any characters outside of A-Za-z0-9 and -, +, _ from the filename.
-    # See issues #77 and #78
-    filename := Filtered( Label( node ), x -> x in AUTODOC_IdentifierLetters );
+    # Strip characters that are known to cause trouble in generated filenames.
+    # In particular, GAP rejects ':', '\' and '/' as they are potentially path
+    # separators.
+    filename := Filtered( Label( node ), AUTODOC_IsSafeGeneratedFilenameCharacter );
     return Concatenation( "_", filename, ".xml" );
 end );
 

diff --git a/tst/manual.expected/_Chapter_Reference.xml b/tst/manual.expected/_Chapter_Reference.xml
@@ -33,7 +33,7 @@
 
 </Section>
 
-<Section Label="Chapter_Reference_Section_The_AutoDoc_function">
+<Section Label="Chapter_Reference_Section_The_AutoDoc()_function">
 <Heading>The AutoDoc() function</Heading>
 
 <ManSection>

diff --git a/tst/worksheets.tst b/tst/worksheets.tst
@@ -75,6 +75,13 @@ gap> AUTODOC_TestWorkSheet("paired-titlepage-autoplain");
 #I  Chapter 1...
 #I  no examples
 
+#
+gap> AUTODOC_TestWorkSheet("punctuated-filenames");
+#I  Extracting manual examples for Punctuated Filenames Test package ...
+#I  1 chapters detected
+#I  Chapter 1...
+#I  no examples
+
 #
 #
 gap> STOP_TEST( "worksheets.tst" );
diff --git a/tst/worksheets/punctuated-filenames.expected/Punctuated_Filenames_Test.xml b/tst/worksheets/punctuated-filenames.expected/Punctuated_Filenames_Test.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<!DOCTYPE Book SYSTEM "gapdoc.dtd"
+[
+    <#Include SYSTEM "_entities.xml">
+]
+>
+<Book Name="Punctuated_Filenames_Test">
+<#Include SYSTEM "title.xml">
+<TableOfContents/>
+<Body>
+<#Include SYSTEM "_AutoDocMainFile.xml">
+</Body>
+</Book>
diff --git a/tst/worksheets/punctuated-filenames.expected/_AutoDocMainFile.xml b/tst/worksheets/punctuated-filenames.expected/_AutoDocMainFile.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<#Include SYSTEM "_Chapter_Alpha+Beta.GammaDeltaSlashBack.xml">
diff --git a/tst/worksheets/punctuated-filenames.expected/_Chapter_Alpha+Beta.GammaDeltaSlashBack.xml b/tst/worksheets/punctuated-filenames.expected/_Chapter_Alpha+Beta.GammaDeltaSlashBack.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<Chapter Label="Chapter_Alpha+Beta.Gamma:DeltaSlashBack">
+<Heading>Alpha+Beta.Gamma:Delta/Slash\Back</Heading>
+
+ Chapter text for generated chapter filenames.
+<Section Label="Chapter_Alpha+Beta.Gamma:DeltaSlashBack_Section_Section+Part.One:TwoThreeFour">
+<Heading>Section+Part.One:Two/Three\Four</Heading>
+
+ Section text for generated labels.
+</Section>
+
+</Chapter>
+
diff --git a/tst/worksheets/punctuated-filenames.expected/_Chunks.xml b/tst/worksheets/punctuated-filenames.expected/_Chunks.xml
diff --git a/tst/worksheets/punctuated-filenames.expected/_entities.xml b/tst/worksheets/punctuated-filenames.expected/_entities.xml
@@ -0,0 +1 @@
+<!ENTITY Punctuated_Filenames_Test '<Package>Punctuated_Filenames_Test</Package>'>
diff --git a/tst/worksheets/punctuated-filenames.expected/title.xml b/tst/worksheets/punctuated-filenames.expected/title.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<TitlePage>
+  <Title>
+    Punctuated Filenames Test
+  </Title>
+  <Subtitle>
+    Relax generated chapter filenames
+  </Subtitle>
+  <Version>
+    1.2
+  </Version>
+  <Date>
+    11 March 2026
+  </Date>
+  </TitlePage>
diff --git a/tst/worksheets/punctuated-filenames.sheet/worksheet.g b/tst/worksheets/punctuated-filenames.sheet/worksheet.g
@@ -0,0 +1,9 @@
+#! @Title Punctuated Filenames Test
+#! @Subtitle Relax generated chapter filenames
+#! @Version 1.2
+#! @Date 2026-03-11
+
+#! @Chapter Alpha+Beta.Gamma:Delta/Slash\Back
+#! Chapter text for generated chapter filenames.
+#! @Section Section+Part.One:Two/Three\Four
+#! Section text for generated labels.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		<!ENTITY Punctuated_Filenames_Test '<Package>Punctuated_Filenames_Test</Package>'>