Support $...$ math in headings

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

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 <> "<P/>" );
+    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>", heading, "</Heading>\n\n" );

tst/worksheets/paired-structure-autoplain.expected/_Chapter_structure-chapter.xml

@@ -2,18 +2,18 @@
 
 <!-- This is an automatically generated file. -->
 <Chapter Label="Chapter_structure-chapter">
-<Heading>Structure Chapter Title</Heading>
+<Heading>Structure Chapter Title <Math>a^2</Math></Heading>
 
 This chapter text uses <Emph>bold</Emph>, <Emph>emphasis</Emph>, and <Code>inline code</Code>.
 <Index Key="Paired structure chapter">Chapter index entry with <Keyword>true</Keyword></Index>
 <P/>
 <Section Label="Section_structure-section">
-<Heading>Structure Section Title</Heading>
+<Heading>Structure Section Title <Math>b^2</Math></Heading>
 
 Section text mentions * plain prose and <Code>keywords</Code>.
 <P/>
 <Subsection Label="Subsection_structure-subsection">
-<Heading>Structure Subsection Title</Heading>
+<Heading>Structure Subsection Title <Math>c^2</Math></Heading>
 
 Subsection text keeps the paired worksheet content aligned.
 </Subsection>

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.

tst/worksheets/paired-structure.expected/_Chapter_structure-chapter.xml

@@ -2,16 +2,16 @@
 
 <!-- This is an automatically generated file. -->
 <Chapter Label="Chapter_structure-chapter">
-<Heading>Structure Chapter Title</Heading>
+<Heading>Structure Chapter Title <Math>a^2</Math></Heading>
 
  This chapter text uses <Emph>bold</Emph>, <Emph>emphasis</Emph>, and <Code>inline code</Code>.
 <Index Key="Paired structure chapter">Chapter index entry with <Keyword>true</Keyword></Index>
 <Section Label="Section_structure-section">
-<Heading>Structure Section Title</Heading>
+<Heading>Structure Section Title <Math>b^2</Math></Heading>
 
  Section text mentions * plain prose and <Code>keywords</Code>.
 <Subsection Label="Subsection_structure-subsection">
-<Heading>Structure Subsection Title</Heading>
+<Heading>Structure Subsection Title <Math>c^2</Math></Heading>
 
  Subsection text keeps the paired worksheet content aligned.
 </Subsection>

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.