scaffold: default main file to _main.xml

CHANGES.md

@@ -39,6 +39,9 @@ This file describes changes in the AutoDoc package.
     nested source directories are picked up automatically
 
 + **Other Changes**
+  - Scaffold-generated package manual main files now default to
+    `_main.xml` instead of `PACKAGENAME.xml`; packages that need a
+    different name can continue to set `gapdoc.main`
   - Don't insert extra newlines after author names for the PDF title
     pages (this was a workaround for a GAPDoc issue; hopefully a
     future GAPDoc release will fix this properly; for details, see

doc/Tutorials.autodoc

@@ -33,7 +33,7 @@ AutoDoc( rec( scaffold := true ) );
 This first reads the <F>PackageInfo.g</F> file from the current
 directory. It extracts information about the package from it
 (such as its name and version, see Section <Ref Sect="Subsection_Tut:Scaffolds:Title"/>).
-It then creates two XML files <F>doc/NAME_OF_YOUR_PACKAGE.xml</F> and
+It then creates two XML files <F>doc/_main.xml</F> and
 <F>doc/title.xml</F> inside the package directory. Finally, it runs
 &GAPDoc; on them to produce a nice initial PDF and HTML version of your
 fresh manual.
@@ -377,7 +377,7 @@ We assume that the manual is currently built by reading a file
 is named <File>manual.xml</File>. 
 
 The files <File>PackageInfo.g</File>, <File>makedoc.g</File>, 
-<File>doc/title.xml</File> and <File>doc/PackageName.xml</File> 
+<File>doc/title.xml</File> and <File>doc/_main.xml</File>
 (if it exists) will be altered by this procedure, 
 so it may be wise to keep backup copies. 
 

doc/clean

@@ -1,4 +1,3 @@
 #!/bin/sh
 
-rm -f *.{aux,lab,log,dvi,ps,pdf,bbl,ilg,ind,idx,out,html,tex,pnr,txt,blg,toc,six,brf,css,js} _Chapter*.xml title.xml _AutoDocMainFile.xml AutoDoc.xml
-
+rm -f *.{aux,lab,log,dvi,ps,pdf,bbl,ilg,ind,idx,out,html,tex,pnr,txt,blg,toc,six,brf,css,js} _*.xml title.xml

gap/AutoDocMainFunction.gi

@@ -94,11 +94,15 @@ end );
 
 ##
 InstallGlobalFunction( CreateMainPage,
-  function( book_name, dir, opt )
+  function( book_name, main_xml_file, dir, opt )
     local filestream, i;
 
+    if not EndsWith( main_xml_file, ".xml" ) then
+        main_xml_file := Concatenation( main_xml_file, ".xml" );
+    fi;
+
     # open the target XML file
-    filestream := AUTODOC_OutputTextFile( dir, opt.main_xml_file );
+    filestream := AUTODOC_OutputTextFile( dir, main_xml_file );
 
     # output the initial file header
     AppendTo( filestream, AUTODOC_XML_HEADER );

gap/Magic.gd

@@ -16,9 +16,8 @@
 #! <Item>
 #!     It can (re)generate a scaffold for your package manual.
 #!     That is, it can produce two XML files in &GAPDoc; format to be used as part
-#!     of your manual: First, a file named <F>doc/PACKAGENAME.xml</F>
-#!     (with your package's name substituted) which is used as
-#!     main XML file for the package manual, i.e. this file sets the
+#!     of your manual: First, a file named <F>doc/_main.xml</F>
+#!     which is used as main XML file for the package manual, i.e. this file sets the
 #!     XML doctype and defines various XML entities, includes
 #!     other XML files (both those generated by &AutoDoc; as well
 #!     as additional files created by other means), tells &GAPDoc;
@@ -316,7 +315,8 @@
 #!             which use a filename here which differs from the default.
 #!             In particular, specifying this is unnecessary when using scaffolding.
 #!             <Br/>
-#!             <E>Default value: <C>PACKAGENAME.xml</C></E>.
+#!             <E>Default value: <C>_main.xml</C> when scaffolding is enabled for
+#!             package manuals, otherwise <C>PACKAGENAME.xml</C>.</E>
 #!         </Item>
 #!
 #!         <Mark><A>files</A></Mark>

gap/Magic.gi

@@ -299,8 +299,17 @@ function( arg )
     fi;
 
     if IsBound( gapdoc ) then
-
-        AUTODOC_SetIfMissing( gapdoc, "main", pkgname );
+        # When scaffolding also generates the main XML file, the default
+        # GAPDoc entry point must match that scaffolded filename. However,
+        # packages with scaffold.MainPage := false may rely on a handwritten
+        # PACKAGENAME.xml main file while still using scaffolded title pages,
+        # so in that case we keep the historical default.
+        if IsBound( scaffold ) and not is_worksheet and
+           ( not IsBound( scaffold.MainPage ) or scaffold.MainPage <> false ) then
+            AUTODOC_SetIfMissing( gapdoc, "main", "_main" );
+        else
+            AUTODOC_SetIfMissing( gapdoc, "main", pkgname );
+        fi;
 
         if IsBound( pkginfo.PackageDoc ) and not IsEmpty( pkginfo.PackageDoc ) then
             if Length( pkginfo.PackageDoc ) > 1 then
@@ -471,14 +480,6 @@ function( arg )
 
         AUTODOC_SetIfMissing( scaffold, "index", true );
 
-        if IsBound( gapdoc ) then
-            if AUTODOC_GetSuffix( gapdoc.main ) = "xml" then
-                scaffold.main_xml_file := gapdoc.main;
-            else
-                scaffold.main_xml_file := Concatenation( gapdoc.main, ".xml" );
-            fi;
-        fi;
-
         if IsBound( scaffold.TitlePage ) and scaffold.TitlePage <> false then
             title_page := ShallowCopy( scaffold.TitlePage );
 
@@ -530,7 +531,7 @@ function( arg )
                        node -> IsBound( node!.is_appendix ) and node!.is_appendix = true ) then
                 scaffold.autodoc_appendix_file := "_AutoDocAppendicesMainFile.xml";
             fi;
-            CreateMainPage( gapdoc.bookname, doc_dir, scaffold );
+            CreateMainPage( gapdoc.bookname, gapdoc.main, doc_dir, scaffold );
         fi;
     fi;
 

tst/autodoctest-manual.tst

@@ -53,28 +53,28 @@ gap> AUTODOC_RunPackageScenario( pkgdir, olddir, rec(
 >   name := "title-main",
 >   makedoc := "makedoc-title-main.g",
 >   stub_gapdoc := true,
->   doc_present := [ "_entities.xml", "AutoDocTest.xml", "title.xml" ],
+>   doc_present := [ "_entities.xml", "_main.xml", "title.xml" ],
 > ) );
 gap> AUTODOC_RunPackageScenario( pkgdir, olddir, rec(
 >   name := "notitle-main",
 >   makedoc := "makedoc-notitle-main.g",
 >   stub_gapdoc := true,
->   doc_present := [ "_entities.xml", "AutoDocTest.xml" ],
+>   doc_present := [ "_entities.xml", "_main.xml" ],
 >   doc_absent := [ "title.xml" ],
 > ) );
 gap> AUTODOC_RunPackageScenario( pkgdir, olddir, rec(
 >   name := "title-nomain",
 >   makedoc := "makedoc-title-nomain.g",
 >   stub_gapdoc := true,
 >   doc_present := [ "_entities.xml", "title.xml" ],
->   doc_absent := [ "AutoDocTest.xml" ],
+>   doc_absent := [ "_main.xml" ],
 > ) );
 gap> AUTODOC_RunPackageScenario( pkgdir, olddir, rec(
 >   name := "notitle-nomain",
 >   makedoc := "makedoc-notitle-nomain.g",
 >   stub_gapdoc := true,
 >   doc_present := [ "_entities.xml" ],
->   doc_absent := [ "AutoDocTest.xml", "title.xml" ],
+>   doc_absent := [ "_main.xml", "title.xml" ],
 > ) );
 
 # extract_examples variants

tst/manual.expected/_Chapter_Reference.xml

@@ -47,9 +47,8 @@
  <Item>
      It can (re)generate a scaffold for your package manual.
      That is, it can produce two XML files in &GAPDoc; format to be used as part
-     of your manual: First, a file named <F>doc/PACKAGENAME.xml</F>
-     (with your package's name substituted) which is used as
-     main XML file for the package manual, i.e. this file sets the
+     of your manual: First, a file named <F>doc/_main.xml</F>
+     which is used as main XML file for the package manual, i.e. this file sets the
      XML doctype and defines various XML entities, includes
      other XML files (both those generated by &AutoDoc; as well
      as additional files created by other means), tells &GAPDoc;
@@ -317,7 +316,8 @@
              which use a filename here which differs from the default.
              In particular, specifying this is unnecessary when using scaffolding.
              <Br/>
-             <E>Default value: <C>PACKAGENAME.xml</C></E>.
+             <E>Default value: <C>_main.xml</C> when scaffolding is enabled for
+             package manuals, otherwise <C>PACKAGENAME.xml</C>.</E>
          </Item>
          <Mark><A>files</A></Mark>
          <Item>

tst/manual.expected/_Chapter_Tutorials.xml

@@ -48,7 +48,7 @@ AutoDoc( rec( scaffold := true ) );
 This first reads the <F>PackageInfo.g</F> file from the current
 directory. It extracts information about the package from it
 (such as its name and version, see Section <Ref Sect="Subsection_Tut:Scaffolds:Title"/>).
-It then creates two XML files <F>doc/NAME_OF_YOUR_PACKAGE.xml</F> and
+It then creates two XML files <F>doc/_main.xml</F> and
 <F>doc/title.xml</F> inside the package directory. Finally, it runs
 &GAPDoc; on them to produce a nice initial PDF and HTML version of your
 fresh manual.
@@ -403,7 +403,7 @@ We assume that the manual is currently built by reading a file
 is named <File>manual.xml</File>. 
 <P/>
 The files <File>PackageInfo.g</File>, <File>makedoc.g</File>, 
-<File>doc/title.xml</File> and <File>doc/PackageName.xml</File> 
+<File>doc/title.xml</File> and <File>doc/_main.xml</File>
 (if it exists) will be altered by this procedure, 
 so it may be wise to keep backup copies. 
 <P/>