diff --git a/CHANGES.md b/CHANGES.md index 62a73afc..83ef43b9 100644 --- a/CHANGES.md +++ b/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 diff --git a/doc/Tutorials.autodoc b/doc/Tutorials.autodoc index 9836d41a..339c1e8f 100644 --- a/doc/Tutorials.autodoc +++ b/doc/Tutorials.autodoc @@ -33,7 +33,7 @@ AutoDoc( rec( scaffold := true ) ); This first reads the PackageInfo.g file from the current directory. It extracts information about the package from it (such as its name and version, see Section ). -It then creates two XML files doc/NAME_OF_YOUR_PACKAGE.xml and +It then creates two XML files doc/_main.xml and doc/title.xml 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 manual.xml. The files PackageInfo.g, makedoc.g, -doc/title.xml and doc/PackageName.xml +doc/title.xml and doc/_main.xml (if it exists) will be altered by this procedure, so it may be wise to keep backup copies. diff --git a/doc/clean b/doc/clean index 1eb816cc..7bbbb6a8 100755 --- a/doc/clean +++ b/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 diff --git a/gap/AutoDocMainFunction.gi b/gap/AutoDocMainFunction.gi index 13856adf..a844ecab 100644 --- a/gap/AutoDocMainFunction.gi +++ b/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 ); diff --git a/gap/Magic.gd b/gap/Magic.gd index 4b5ceb3a..beaac504 100644 --- a/gap/Magic.gd +++ b/gap/Magic.gd @@ -16,9 +16,8 @@ #! #! 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 doc/PACKAGENAME.xml -#! (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 doc/_main.xml +#! 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. #!
-#! Default value: PACKAGENAME.xml. +#! Default value: _main.xml when scaffolding is enabled for +#! package manuals, otherwise PACKAGENAME.xml. #! #! #! files diff --git a/gap/Magic.gi b/gap/Magic.gi index 7164c3df..27a2b08c 100644 --- a/gap/Magic.gi +++ b/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; diff --git a/tst/AutoDocTest/tst/manual-entities-list.expected/AutoDocTest.xml b/tst/AutoDocTest/tst/manual-entities-list.expected/_main.xml similarity index 100% rename from tst/AutoDocTest/tst/manual-entities-list.expected/AutoDocTest.xml rename to tst/AutoDocTest/tst/manual-entities-list.expected/_main.xml diff --git a/tst/AutoDocTest/tst/manual-entities-record.expected/AutoDocTest.xml b/tst/AutoDocTest/tst/manual-entities-record.expected/_main.xml similarity index 100% rename from tst/AutoDocTest/tst/manual-entities-record.expected/AutoDocTest.xml rename to tst/AutoDocTest/tst/manual-entities-record.expected/_main.xml diff --git a/tst/AutoDocTest/tst/manual.expected/AutoDocTest.xml b/tst/AutoDocTest/tst/manual.expected/_main.xml similarity index 100% rename from tst/AutoDocTest/tst/manual.expected/AutoDocTest.xml rename to tst/AutoDocTest/tst/manual.expected/_main.xml diff --git a/tst/autodoctest-manual.tst b/tst/autodoctest-manual.tst index ff0b6fd1..381d3cdd 100644 --- a/tst/autodoctest-manual.tst +++ b/tst/autodoctest-manual.tst @@ -53,13 +53,13 @@ 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( @@ -67,14 +67,14 @@ gap> AUTODOC_RunPackageScenario( pkgdir, olddir, rec( > 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 diff --git a/tst/manual.expected/_Chapter_Reference.xml b/tst/manual.expected/_Chapter_Reference.xml index c0821166..681aaf97 100644 --- a/tst/manual.expected/_Chapter_Reference.xml +++ b/tst/manual.expected/_Chapter_Reference.xml @@ -47,9 +47,8 @@ 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 doc/PACKAGENAME.xml - (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 doc/_main.xml + 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.
- Default value: PACKAGENAME.xml. + Default value: _main.xml when scaffolding is enabled for + package manuals, otherwise PACKAGENAME.xml. files diff --git a/tst/manual.expected/_Chapter_Tutorials.xml b/tst/manual.expected/_Chapter_Tutorials.xml index 8af76c44..2108a631 100644 --- a/tst/manual.expected/_Chapter_Tutorials.xml +++ b/tst/manual.expected/_Chapter_Tutorials.xml @@ -48,7 +48,7 @@ AutoDoc( rec( scaffold := true ) ); This first reads the PackageInfo.g file from the current directory. It extracts information about the package from it (such as its name and version, see Section ). -It then creates two XML files doc/NAME_OF_YOUR_PACKAGE.xml and +It then creates two XML files doc/_main.xml and doc/title.xml 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 manual.xml.

The files PackageInfo.g, makedoc.g, -doc/title.xml and doc/PackageName.xml +doc/title.xml and doc/_main.xml (if it exists) will be altered by this procedure, so it may be wise to keep backup copies.

diff --git a/tst/manual.expected/AutoDoc.xml b/tst/manual.expected/_main.xml similarity index 100% rename from tst/manual.expected/AutoDoc.xml rename to tst/manual.expected/_main.xml