From 903db4055d1ca96a3521c51567623e472b3ac98d Mon Sep 17 00:00:00 2001 From: Max Horn Date: Mon, 16 Mar 2026 23:50:28 +0100 Subject: [PATCH] Support $...$ math in headings Fixes #127 Co-authored-by: Codex --- CHANGES.md | 2 ++ gap/DocumentationTree.gi | 15 +++++++++++++++ .../_Chapter_structure-chapter.xml | 6 +++--- .../plain.autodoc | 6 +++--- .../_Chapter_structure-chapter.xml | 6 +++--- tst/worksheets/paired-structure.sheet/worksheet.g | 6 +++--- 6 files changed, 29 insertions(+), 12 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index e602b588..8efa6a35 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -70,6 +70,8 @@ This file describes changes in the AutoDoc package. - Document `InstallMethod` support in declaration comments - Fix legacy list-style `scaffold.entities` handling so it receives the standard default entities and works end-to-end again + - Convert Markdown-style math in chapter, section, and subsection + headings to the corresponding GAPDoc math markup - Loosen requirements on `@Date` command: this used to allow free form, but in recent versions was restricted to dates of the form YYYY-MM-DD or DD/MM/YYYY; now we again allow any text, but text in those specific diff --git a/gap/DocumentationTree.gi b/gap/DocumentationTree.gi index afb00090..b54f43b2 100644 --- a/gap/DocumentationTree.gi +++ b/gap/DocumentationTree.gi @@ -413,6 +413,20 @@ end ); ## ############################################# +BindGlobal( "AUTODOC_ConvertHeadingToGAPDocXML", + function( heading ) + local converted_heading; + + converted_heading := + AUTODOC_ConvertMarkdownToGAPDocXML( [ NormalizedWhitespace( heading ) ] ); + if not ForAll( converted_heading, IsString ) then + Error( "headings must convert to inline GAPDoc XML" ); + fi; + converted_heading := Filtered( converted_heading, + piece -> piece <> "" and piece <> "

" ); + return JoinStringsWithSeparator( converted_heading, "" ); +end ); + BindGlobal( "AUTODOC_WriteStructuralNode", function( node, element_name, stream ) local heading; @@ -426,6 +440,7 @@ BindGlobal( "AUTODOC_WriteStructuralNode", else heading := ReplacedString( node!.name, "_", " " ); fi; + heading := AUTODOC_ConvertHeadingToGAPDocXML( heading ); AppendTo( stream, "<", element_name, " Label=\"", Label( node ), "\">\n" ); AppendTo( stream, "", heading, "\n\n" ); diff --git a/tst/worksheets/paired-structure-autoplain.expected/_Chapter_structure-chapter.xml b/tst/worksheets/paired-structure-autoplain.expected/_Chapter_structure-chapter.xml index 7cf82cad..d919d06e 100644 --- a/tst/worksheets/paired-structure-autoplain.expected/_Chapter_structure-chapter.xml +++ b/tst/worksheets/paired-structure-autoplain.expected/_Chapter_structure-chapter.xml @@ -2,18 +2,18 @@ -Structure Chapter Title +Structure Chapter Title a^2 This chapter text uses bold, emphasis, and inline code. Chapter index entry with true

-Structure Section Title +Structure Section Title b^2 Section text mentions * plain prose and keywords.

-Structure Subsection Title +Structure Subsection Title c^2 Subsection text keeps the paired worksheet content aligned. diff --git a/tst/worksheets/paired-structure-autoplain.sheet/plain.autodoc b/tst/worksheets/paired-structure-autoplain.sheet/plain.autodoc index d8a89487..17c6bac1 100644 --- a/tst/worksheets/paired-structure-autoplain.sheet/plain.autodoc +++ b/tst/worksheets/paired-structure-autoplain.sheet/plain.autodoc @@ -5,16 +5,16 @@ @Chapter Structure Chapter @ChapterLabel structure-chapter -@ChapterTitle Structure Chapter Title +@ChapterTitle Structure Chapter Title $a^2$ This chapter text uses **bold**, __emphasis__, and `inline code`. @Index "Paired structure chapter" Chapter index entry with `true` @Section Structure Section @SectionLabel structure-section -@SectionTitle Structure Section Title +@SectionTitle Structure Section Title $b^2$ Section text mentions * plain prose and `keywords`. @Subsection Structure Subsection @SubsectionLabel structure-subsection -@SubsectionTitle Structure Subsection Title +@SubsectionTitle Structure Subsection Title $c^2$ Subsection text keeps the paired worksheet content aligned. diff --git a/tst/worksheets/paired-structure.expected/_Chapter_structure-chapter.xml b/tst/worksheets/paired-structure.expected/_Chapter_structure-chapter.xml index 3c634b4c..c83b078a 100644 --- a/tst/worksheets/paired-structure.expected/_Chapter_structure-chapter.xml +++ b/tst/worksheets/paired-structure.expected/_Chapter_structure-chapter.xml @@ -2,16 +2,16 @@ -Structure Chapter Title +Structure Chapter Title a^2 This chapter text uses bold, emphasis, and inline code. Chapter index entry with true

-Structure Section Title +Structure Section Title b^2 Section text mentions * plain prose and keywords. -Structure Subsection Title +Structure Subsection Title c^2 Subsection text keeps the paired worksheet content aligned. diff --git a/tst/worksheets/paired-structure.sheet/worksheet.g b/tst/worksheets/paired-structure.sheet/worksheet.g index 86ea806a..63db3fcd 100644 --- a/tst/worksheets/paired-structure.sheet/worksheet.g +++ b/tst/worksheets/paired-structure.sheet/worksheet.g @@ -5,16 +5,16 @@ #! @Chapter Structure Chapter #! @ChapterLabel structure-chapter -#! @ChapterTitle Structure Chapter Title +#! @ChapterTitle Structure Chapter Title $a^2$ #! This chapter text uses **bold**, __emphasis__, and `inline code`. #! @Index "Paired structure chapter" Chapter index entry with `true` #! @Section Structure Section #! @SectionLabel structure-section -#! @SectionTitle Structure Section Title +#! @SectionTitle Structure Section Title $b^2$ #! Section text mentions * plain prose and `keywords`. #! @Subsection Structure Subsection #! @SubsectionLabel structure-subsection -#! @SubsectionTitle Structure Subsection Title +#! @SubsectionTitle Structure Subsection Title $c^2$ #! Subsection text keeps the paired worksheet content aligned.