From 581c269ca1653e44c973d9cc0b3c99476a64c404 Mon Sep 17 00:00:00 2001 From: Torben Wiedemann <7226617+TWiedemann@users.noreply.github.com> Date: Tue, 29 Sep 2026 09:39:15 +0200 Subject: [PATCH 1/2] Minor improvements to documentation --- doc/Tutorials.autodoc | 8 +++++--- gap/Magic.gd | 30 ++++++++++++++++++++---------- 2 files changed, 25 insertions(+), 13 deletions(-) diff --git a/doc/Tutorials.autodoc b/doc/Tutorials.autodoc index 9988999c..f25d5168 100644 --- a/doc/Tutorials.autodoc +++ b/doc/Tutorials.autodoc @@ -614,7 +614,10 @@ and text versions of the manual. AutoDoc This record controls extra settings used by &AutoDoc; while generating the -manual. In particular, PkgInfo.AutoDoc.TitlePage lets you add or +manual. +Specifically, its entries are used as default values for the entries of +optrec.scaffold in . +In particular, PkgInfo.AutoDoc.TitlePage lets you add or override title-page elements coming from package metadata. Typical fields you may set there include TitleComment, @@ -663,5 +666,4 @@ from makedoc.g take precedence when both define the same key. For stand-alone documents that are not tied to a package, use . Its documentation and examples are in -Section of chapter -. +Section . diff --git a/gap/Magic.gd b/gap/Magic.gd index f6122396..cd822f11 100644 --- a/gap/Magic.gd +++ b/gap/Magic.gd @@ -46,7 +46,10 @@ #! little of &AutoDoc; as your package currently needs. #! For more information and some examples, please refer to Chapter . #!

-#! The parameters have the following meanings: +#! If exactly one parameter is given, it is interpreted as optrec if it is a record, +#! and as pkgdir otherwise. +#!

+#! The parameters have the following meaning: #! #! #! pkgdir @@ -85,9 +88,9 @@ #! dir #! #! This should either be a string, in which case it must be a path -#! relative to the specified package directory, or a -#! Directory() object. (Thus, the only way to designate an -#! absolute directory is with a Directory() object.) This +#! relative to the specified package directory, or an +#! IsDirectory object. (Thus, the only way to designate an +#! absolute directory is with an IsDirectory object.) This #! option specifies where the package documentation #! (e.g. the &GAPDoc; XML or the manual PDF, etc.) files are stored #! and/or will be generated. @@ -102,23 +105,24 @@ #! The value should be either true, false or a #! record. If it is a record or true (the latter is #! equivalent to specifying an empty record), then this feature is -#! enabled. It is also enabled if opt.scaffold is missing but the +#! enabled. It is also enabled if optrec.scaffold is missing but the #! package's info record in PackageInfo.g has an AutoDoc entry. -#! In all other cases (in particular if opt.scaffold is +#! In all other cases (in particular if optrec.scaffold is #! false), scaffolding is disabled. #!

-#! If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is +#! If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is #! assumed to be a record, and its contents are used as default values for #! the scaffold settings. #!

#! -#! If opt.scaffold is a record, it may contain the following entries. +#! If optrec.scaffold is a record, it may contain the following entries. #! #! #! #! includes #! #! A list of XML files to be included in the body of the main XML file. +#! They are included in the order in which they are given. #! If you specify this list and also are using &AutoDoc; to document #! your operations with &AutoDoc; comments, #! you can add _AutoDocMainFile.xml to this list @@ -254,7 +258,10 @@ #! #! A list of files (given by paths relative to the package directory) #! to be scanned for &AutoDoc; documentation comments. -#! Usually it is more convenient to use autodoc.scan_dirs, see below. +#! They are scanned in the order in which they are given, and always +#! before the files scanned by autodoc.scan_dirs. +#! Unless the order of files is important, +#! it is usually more convenient to use autodoc.scan_dirs, see below. #! #! #! scan_dirs @@ -262,7 +269,10 @@ #! A list of subdirectories of the package directory (given as relative paths) #! which &AutoDoc; then scans recursively for .gi, .gd, .g, and #! .autodoc files; all of these files are then scanned for -#! &AutoDoc; documentation comments. The special entries "." +#! &AutoDoc; documentation comments. +#! The directories are scanned in the order in which they are given, +#! and the files in each directory are scanned in lexicographic order. +#! The special entries "." #! and "" still only scan the package root itself. #! This controls where &AutoDoc; looks for source comments beginning with #! #! and for standalone .autodoc files. From 7d5deb4dfcd519fb921baeba61a2d2def2ffc2d9 Mon Sep 17 00:00:00 2001 From: Torben Wiedemann <7226617+TWiedemann@users.noreply.github.com> Date: Tue, 29 Sep 2026 13:44:02 +0200 Subject: [PATCH 2/2] Update tests --- tst/manual.expected/_Chapter_Reference.xml | 30 ++++++++++++++-------- tst/manual.expected/_Chapter_Tutorials.xml | 8 +++--- 2 files changed, 25 insertions(+), 13 deletions(-) diff --git a/tst/manual.expected/_Chapter_Reference.xml b/tst/manual.expected/_Chapter_Reference.xml index 0ee14f2b..62638aa0 100644 --- a/tst/manual.expected/_Chapter_Reference.xml +++ b/tst/manual.expected/_Chapter_Reference.xml @@ -124,7 +124,10 @@ little of &AutoDoc; as your package currently needs. For more information and some examples, please refer to Chapter .

- The parameters have the following meanings: + If exactly one parameter is given, it is interpreted as optrec if it is a record, + and as pkgdir otherwise. +

+ The parameters have the following meaning: pkgdir @@ -160,9 +163,9 @@ dir This should either be a string, in which case it must be a path - relative to the specified package directory, or a - Directory() object. (Thus, the only way to designate an - absolute directory is with a Directory() object.) This + relative to the specified package directory, or an + IsDirectory object. (Thus, the only way to designate an + absolute directory is with an IsDirectory object.) This option specifies where the package documentation (e.g. the &GAPDoc; XML or the manual PDF, etc.) files are stored and/or will be generated. @@ -177,22 +180,23 @@ The value should be either true, false or a record. If it is a record or true (the latter is equivalent to specifying an empty record), then this feature is - enabled. It is also enabled if opt.scaffold is missing but the + enabled. It is also enabled if optrec.scaffold is missing but the package's info record in PackageInfo.g has an AutoDoc entry. - In all other cases (in particular if opt.scaffold is + In all other cases (in particular if optrec.scaffold is false), scaffolding is disabled.

- If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is + If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is assumed to be a record, and its contents are used as default values for the scaffold settings.

- If opt.scaffold is a record, it may contain the following entries. + If optrec.scaffold is a record, it may contain the following entries.

includes A list of XML files to be included in the body of the main XML file. + They are included in the order in which they are given. If you specify this list and also are using &AutoDoc; to document your operations with &AutoDoc; comments, you can add _AutoDocMainFile.xml to this list @@ -318,14 +322,20 @@ A list of files (given by paths relative to the package directory) to be scanned for &AutoDoc; documentation comments. - Usually it is more convenient to use autodoc.scan_dirs, see below. + They are scanned in the order in which they are given, and always + before the files scanned by autodoc.scan_dirs. + Unless the order of files is important, + it is usually more convenient to use autodoc.scan_dirs, see below. scan_dirs A list of subdirectories of the package directory (given as relative paths) which &AutoDoc; then scans recursively for .gi, .gd, .g, and .autodoc files; all of these files are then scanned for - &AutoDoc; documentation comments. The special entries "." + &AutoDoc; documentation comments. + The directories are scanned in the order in which they are given, + and the files in each directory are scanned in lexicographic order. + The special entries "." and "" still only scan the package root itself. This controls where &AutoDoc; looks for source comments beginning with #! and for standalone .autodoc files. diff --git a/tst/manual.expected/_Chapter_Tutorials.xml b/tst/manual.expected/_Chapter_Tutorials.xml index bd782c1b..dbf6b84e 100644 --- a/tst/manual.expected/_Chapter_Tutorials.xml +++ b/tst/manual.expected/_Chapter_Tutorials.xml @@ -645,7 +645,10 @@ and text versions of the manual. AutoDoc This record controls extra settings used by &AutoDoc; while generating the -manual. In particular, PkgInfo.AutoDoc.TitlePage lets you add or +manual. +Specifically, its entries are used as default values for the entries of +optrec.scaffold in . +In particular, PkgInfo.AutoDoc.TitlePage lets you add or override title-page elements coming from package metadata.

Typical fields you may set there include TitleComment, @@ -701,8 +704,7 @@ from makedoc.g take precedence when both define the same key.

For stand-alone documents that are not tied to a package, use . Its documentation and examples are in -Section of chapter -. +Section .