Add @Appendix command similar to @Chapter

CHANGES.md

@@ -19,6 +19,7 @@ This file describes changes in the AutoDoc package.
     environment variable and `relativePath` global option
   - Add Markdown-style headings `#`/`##`/`###` as aliases for
     `@Chapter`/`@Section`/`@Subsection` in `.autodoc` files and doc comments
+  - Add `@Appendix` for generating appendix XML from `.autodoc` input
   - Add support for documenting `DeclareSynonym` and
     `DeclareSynonymAttr` declarations
   - Add `@ItemType` to override the type of a declaration, which is

doc/Comments.autodoc

@@ -243,6 +243,23 @@ If you use all three commands, i.e.,
 <C>title</C> is used for the headline, <C>label</C> for cross-referencing, and <C>name</C>
 for setting the same chapter as active chapter again.
 
+@Subsection <C>@Appendix <A>name</A></C>
+@SubsectionLabel @Appendix
+
+@Index "@Appendix" `@Appendix`
+This is analogous to <C>@Chapter</C>, but generates `Appendix`
+elements instead of `Chapter` elements. When scaffolding generates the main
+XML file, appendices created this way are included automatically after any
+files listed in `scaffold.appendix`.
+
+Example:
+
+```@listing
+@Appendix Supplementary material
+
+@Section Additional tables
+```
+
 @Subsection <C>@Section <A>name</A></C>
 @SubsectionLabel @Section
 

gap/AutoDocMainFunction.gi

@@ -155,6 +155,10 @@ InstallGlobalFunction( CreateMainPage,
             AppendTo( filestream, "<#Include SYSTEM \"", i, "\">\n" );
         od;
     fi;
+    if IsBound( opt.autodoc_appendix_file ) and
+       ( not IsBound( opt.appendix ) or not opt.autodoc_appendix_file in opt.appendix ) then
+        AppendTo( filestream, "<#Include SYSTEM \"", opt.autodoc_appendix_file, "\">\n" );
+    fi;
 
     if IsBound( opt.bib ) and opt.bib <> false then
         AppendTo( filestream, "<Bibliography Databases=\"", opt.bib, "\"/>\n" );

gap/DocumentationTree.gd

@@ -45,6 +45,7 @@ DeclareAttribute( "GroupName", IsTreeForDocumentationNode );
 DeclareOperation( "DocumentationTree", [ ] );
 DeclareOperation( "StructurePartInTree", [ IsTreeForDocumentation, IsList ] );
 DeclareOperation( "ChapterInTree", [ IsTreeForDocumentation, IsString ] );
+DeclareOperation( "AppendixInTree", [ IsTreeForDocumentation, IsString ] );
 DeclareOperation( "SectionInTree", [ IsTreeForDocumentation, IsString, IsString ] );
 DeclareOperation( "SubsectionInTree", [ IsTreeForDocumentation, IsString, IsString, IsString ] );
 DeclareOperation( "DocumentationExample", [ IsString ] );

gap/DocumentationTree.gi

@@ -377,12 +377,24 @@ end );
 ##
 ####################################
 
-## 
+##
 InstallMethod( ChapterInTree, [ IsTreeForDocumentation, IsString ],
   function( tree, name )
     return StructurePartInTree( tree, [ name ] );
 end );
 
+##
+InstallMethod( AppendixInTree, [ IsTreeForDocumentation, IsString ],
+  function( tree, name )
+    local node;
+
+    node := ChapterInTree( tree, name );
+    node!.is_appendix := true;
+    SetLabel( node,
+        Concatenation( "Appendix_", AUTODOC_NormalizeGeneratedLabel( name ) ) );
+    return node;
+end );
+
 ##
 InstallMethod( SectionInTree, [ IsTreeForDocumentation, IsString, IsString ],
   function( tree, chapter_name, section_name )
@@ -476,17 +488,32 @@ end );
 ##
 InstallMethod( WriteDocumentation, [ IsTreeForDocumentation, IsDirectory ],
   function( tree, path_to_xmlfiles )
-    local stream, i;
+    local stream, appendix_stream, i;
 
     stream := AUTODOC_OutputTextFile( path_to_xmlfiles, _AUTODOC_GLOBAL_OPTION_RECORD.AutoDocMainFile );
     AppendTo( stream, AUTODOC_XML_HEADER );
+    appendix_stream := fail;
     for i in tree!.content do
-        if not IsTreeForDocumentationNodeForChapterRep( i ) then
+        if IsTreeForDocumentationNodeForChapterRep( i ) then
+            if IsBound( i!.is_appendix ) and i!.is_appendix = true then
+                if appendix_stream = fail then
+                    appendix_stream := AUTODOC_OutputTextFile(
+                        path_to_xmlfiles,
+                        "_AutoDocAppendicesMainFile.xml"
+                    );
+                    AppendTo( appendix_stream, AUTODOC_XML_HEADER );
+                fi;
+                WriteDocumentation( i, appendix_stream, path_to_xmlfiles );
+            else
+                WriteDocumentation( i, stream, path_to_xmlfiles );
+            fi;
+        else
             Error( "this should never happen" );
         fi;
-        ## FIXME: If there is anything else than a chapter, this will break!
-        WriteDocumentation( i, stream, path_to_xmlfiles );
     od;
+    if appendix_stream <> fail then
+        CloseStream( appendix_stream );
+    fi;
 
     WriteChunks( tree, path_to_xmlfiles );
 
@@ -500,7 +527,7 @@ end );
 ##
 InstallMethod( WriteDocumentation, [ IsTreeForDocumentationNodeForChapterRep, IsStream, IsDirectory ],
   function( node, stream, path_to_xmlfiles )
-    local filename, chapter_stream;
+    local filename, chapter_stream, element_name;
 
     if ForAll( node!.content, IsEmptyNode ) then
         return;
@@ -510,7 +537,11 @@ InstallMethod( WriteDocumentation, [ IsTreeForDocumentationNodeForChapterRep, Is
     chapter_stream := AUTODOC_OutputTextFile( path_to_xmlfiles, filename );
     AppendTo( stream, "<#Include SYSTEM \"", filename, "\">\n" );
     AppendTo( chapter_stream, AUTODOC_XML_HEADER );
-    AUTODOC_WriteStructuralNode( node, "Chapter", chapter_stream );
+    element_name := "Chapter";
+    if IsBound( node!.is_appendix ) and node!.is_appendix = true then
+        element_name := "Appendix";
+    fi;
+    AUTODOC_WriteStructuralNode( node, element_name, chapter_stream );
     CloseStream( chapter_stream );
 end );
 

gap/Magic.gd

@@ -136,7 +136,9 @@
 #!         <Item>
 #!             This entry is similar to <A>opt.scaffold.includes</A> but is used
 #!             to specify files to include after the main body of the manual,
-#!             i.e. typically appendices.
+#!             i.e. typically appendices written directly in &GAPDoc; XML.
+#!             Appendices created with <C>@Appendix</C> are included automatically
+#!             after these files when scaffolding generates the main XML file.
 #!         </Item>
 #!
 #!         <Mark><A>bib</A></Mark>

gap/Magic.gi

@@ -510,6 +510,10 @@ function( arg )
         CreateEntitiesPage( gapdoc.bookname, doc_dir, scaffold );
 
         if IsBound( scaffold.MainPage ) and scaffold.MainPage <> false then
+            if ForAny( tree!.content,
+                       node -> IsBound( node!.is_appendix ) and node!.is_appendix = true ) then
+                scaffold.autodoc_appendix_file := "_AutoDocAppendicesMainFile.xml";
+            fi;
             CreateMainPage( gapdoc.bookname, doc_dir, scaffold );
         fi;
     fi;

gap/Parser.gi

@@ -800,8 +800,18 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
             local scope_chapter;
             scope_chapter := ReplacedString( current_command[ 2 ], " ", "_" );
             SetCurrentItem( ChapterInTree( tree, scope_chapter ) );
+            Unbind( chapter_info[ 2 ] );
+            Unbind( chapter_info[ 3 ] );
             chapter_info[ 1 ] := scope_chapter;
         end,
+        @Appendix := function()
+            local scope_appendix;
+            scope_appendix := ReplacedString( current_command[ 2 ], " ", "_" );
+            SetCurrentItem( AppendixInTree( tree, scope_appendix ) );
+            Unbind( chapter_info[ 2 ] );
+            Unbind( chapter_info[ 3 ] );
+            chapter_info[ 1 ] := scope_appendix;
+        end,
         @ChapterLabel := function()
             local scope_chapter, label_name;
             if not IsBound( chapter_info[ 1 ] ) then

tst/AutoDocTest/doc/appendix.autodoc

@@ -0,0 +1,4 @@
+@Appendix Plain-text appendix
+
+This appendix is written in `.autodoc` format and is expected to be included
+through <C>scaffold.appendix</C>.

tst/AutoDocTest/doc/appendix1.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<Appendix Label="Appendix_XMLFixture">
+  <Heading>XML fixture appendix</Heading>
+  <P/>
+  This hand-written XML appendix exercises the existing
+  <C>scaffold.appendix</C> hook alongside generated <C>@Appendix</C>
+  content.
+</Appendix>

tst/AutoDocTest/gap/AutoDocTest.gd

@@ -25,3 +25,8 @@ DeclareAttribute( "AutoDocTest_Attribute", IsGroup );
 #!
 #! `AutoDocTest_Property` is a tiny property used to exercise method docs.
 DeclareProperty( "AutoDocTest_Property", IsGroup );
+
+#!
+#! `AutoDocTest_Method` is declared separately so the fixture package loads
+#! cleanly when building its manual.
+DeclareOperation( "AutoDocTest_Method", [ IsGroup ] );

tst/AutoDocTest/makedoc.g

@@ -3,13 +3,14 @@ LoadPackage("AutoDocTest");
 
 AutoDoc(rec(
   autodoc := rec(
-    files := [ "doc/chapter2.autodoc" ],
+    files := [ "doc/chapter2.autodoc", "doc/appendix.autodoc" ],
   ),
   gapdoc := rec(
     files := [ "gap/AutoDocTest.gd", "gap/AutoDocTest.gi" ],
   ),
   scaffold := rec(
     includes := [ "chapter1.xml" ],
+    appendix := [ "appendix1.xml" ],
     bib := "AutoDocTest.bib",
   ),
 ));

tst/AutoDocTest/tst/manual.expected/_Appendix_Plain-text_appendix.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!-- This is an automatically generated file. -->
+<Appendix Label="Appendix_Plain-text_appendix">
+<Heading>Plain-text appendix</Heading>
+
+<P/>
+This appendix is written in <Code>.autodoc</Code> format and is expected to be included
+through <C>scaffold.appendix</C>.
+</Appendix>
+

tst/AutoDocTest/tst/manual.expected/_AutoDocAppendicesMainFile.xml

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

tst/AutoDocTest/tst/manual.expected/_Chapter_SourceAPI.xml

@@ -46,6 +46,16 @@
  </Description>
 </ManSection>
 
+<P/>
+ <Code>AutoDocTest_Method</Code> is declared separately so the fixture package loads
+ cleanly when building its manual.
+<ManSection>
+  <Oper Arg="arg" Name="AutoDocTest_Method" Label="for IsGroup"/>
+ <Description>
+<P/>
+ </Description>
+</ManSection>
+
 </Section>
 
 <Section Label="Section_SourceImplementations">

tst/manual.expected/_Chapter_Comments.xml

@@ -274,6 +274,26 @@ for setting the same chapter as active chapter again.
 <P/>
 </Subsection>
 
+<Subsection Label="Subsection_@Appendix">
+<Heading><C>@Appendix <A>name</A></C></Heading>
+
+<P/>
+<Index Key="@Appendix"><Code>@Appendix</Code></Index>
+This is analogous to <C>@Chapter</C>, but generates <Code>Appendix</Code>
+elements instead of <Code>Chapter</Code> elements. When scaffolding generates the main
+XML file, appendices created this way are included automatically after any
+files listed in <Code>scaffold.appendix</Code>.
+<P/>
+Example:
+<P/>
+<Listing><![CDATA[
+@Appendix Supplementary material
+
+@Section Additional tables
+]]></Listing>
+<P/>
+</Subsection>
+
 <Subsection Label="Subsection_@Section">
 <Heading><C>@Section <A>name</A></C></Heading>
 

tst/manual.expected/_Chapter_Reference.xml

@@ -161,7 +161,9 @@
          <Item>
              This entry is similar to <A>opt.scaffold.includes</A> but is used
              to specify files to include after the main body of the manual,
-             i.e. typically appendices.
+             i.e. typically appendices written directly in &GAPDoc; XML.
+             Appendices created with <C>@Appendix</C> are included automatically
+             after these files when scaffolding generates the main XML file.
          </Item>
          <Mark><A>bib</A></Mark>
          <Item>