From 0e8882a79c746482341770646f603fbecd0f572c Mon Sep 17 00:00:00 2001 From: Max Horn Date: Wed, 11 Mar 2026 14:14:49 +0100 Subject: [PATCH] Relax generated chapter names Preserve more punctuation in auto-generated chapter and section labels and in chapter XML filenames, while still stripping characters that are known to cause trouble for generated paths. AI-assisted by Codex for implementation and changelog updates. Co-authored-by: Codex --- CHANGES.md | 3 +++ gap/DocumentationTree.gi | 25 ++++++++++++++++--- tst/manual.expected/_Chapter_Reference.xml | 2 +- tst/worksheets.tst | 7 ++++++ .../Punctuated_Filenames_Test.xml | 15 +++++++++++ .../_AutoDocMainFile.xml | 4 +++ ...Chapter_Alpha+Beta.GammaDeltaSlashBack.xml | 15 +++++++++++ .../punctuated-filenames.expected/_Chunks.xml | 0 .../_entities.xml | 1 + .../punctuated-filenames.expected/title.xml | 17 +++++++++++++ .../punctuated-filenames.sheet/worksheet.g | 9 +++++++ 11 files changed, 93 insertions(+), 5 deletions(-) create mode 100644 tst/worksheets/punctuated-filenames.expected/Punctuated_Filenames_Test.xml create mode 100644 tst/worksheets/punctuated-filenames.expected/_AutoDocMainFile.xml create mode 100644 tst/worksheets/punctuated-filenames.expected/_Chapter_Alpha+Beta.GammaDeltaSlashBack.xml create mode 100644 tst/worksheets/punctuated-filenames.expected/_Chunks.xml create mode 100644 tst/worksheets/punctuated-filenames.expected/_entities.xml create mode 100644 tst/worksheets/punctuated-filenames.expected/title.xml create mode 100644 tst/worksheets/punctuated-filenames.sheet/worksheet.g diff --git a/CHANGES.md b/CHANGES.md index 7b2a9d6f..9e55cb74 100644 --- 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 index ccb5be7e..070caaef 100644 --- 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 index 92c17994..16ff71d1 100644 --- a/tst/manual.expected/_Chapter_Reference.xml +++ b/tst/manual.expected/_Chapter_Reference.xml @@ -33,7 +33,7 @@ -
+
The AutoDoc() function diff --git a/tst/worksheets.tst b/tst/worksheets.tst index a5c8f961..79de0088 100644 --- 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 new file mode 100644 index 00000000..86248049 --- /dev/null +++ b/tst/worksheets/punctuated-filenames.expected/Punctuated_Filenames_Test.xml @@ -0,0 +1,15 @@ + + + + +] +> + +<#Include SYSTEM "title.xml"> + + +<#Include SYSTEM "_AutoDocMainFile.xml"> + + diff --git a/tst/worksheets/punctuated-filenames.expected/_AutoDocMainFile.xml b/tst/worksheets/punctuated-filenames.expected/_AutoDocMainFile.xml new file mode 100644 index 00000000..6adb4cb2 --- /dev/null +++ b/tst/worksheets/punctuated-filenames.expected/_AutoDocMainFile.xml @@ -0,0 +1,4 @@ + + + +<#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 new file mode 100644 index 00000000..9856cc8f --- /dev/null +++ b/tst/worksheets/punctuated-filenames.expected/_Chapter_Alpha+Beta.GammaDeltaSlashBack.xml @@ -0,0 +1,15 @@ + + + + +Alpha+Beta.Gamma:Delta/Slash\Back + + Chapter text for generated chapter filenames. +
+Section+Part.One:Two/Three\Four + + Section text for generated labels. +
+ + + diff --git a/tst/worksheets/punctuated-filenames.expected/_Chunks.xml b/tst/worksheets/punctuated-filenames.expected/_Chunks.xml new file mode 100644 index 00000000..e69de29b diff --git a/tst/worksheets/punctuated-filenames.expected/_entities.xml b/tst/worksheets/punctuated-filenames.expected/_entities.xml new file mode 100644 index 00000000..03bb3ce9 --- /dev/null +++ b/tst/worksheets/punctuated-filenames.expected/_entities.xml @@ -0,0 +1 @@ +Punctuated_Filenames_Test'> diff --git a/tst/worksheets/punctuated-filenames.expected/title.xml b/tst/worksheets/punctuated-filenames.expected/title.xml new file mode 100644 index 00000000..02d7a691 --- /dev/null +++ b/tst/worksheets/punctuated-filenames.expected/title.xml @@ -0,0 +1,17 @@ + + + + + + Punctuated Filenames Test + + + Relax generated chapter filenames + + + 1.2 + + + 11 March 2026 + + \ No newline at end of file diff --git a/tst/worksheets/punctuated-filenames.sheet/worksheet.g b/tst/worksheets/punctuated-filenames.sheet/worksheet.g new file mode 100644 index 00000000..ff7d60f8 --- /dev/null +++ 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.