Remove or deprecate various legacy feature

- Remove the undocumented AutoDoc package-name invocation.
- Stop honoring GAP global options as overrides for normal AutoDoc options.
- Keep worksheet compatibility, with a warning for legacy ':' syntax.

Co-authored-by: Codex <codex@openai.com>

Author: fingolfin

CHANGES.md

@@ -1,5 +1,19 @@
 This file describes changes in the AutoDoc package.
 
+## 2026.MM.DD
+
++ **Breaking changes**
+  - Remove support for calling `AutoDoc()` with a package name argument
+  - Remove support for controlling `AutoDoc()` via GAP global options
+    corresponding to regular option-record entries such as `dir`,
+    `scaffold`, `autodoc`, `gapdoc`, and `extract_examples`
+  - Remove support for implicitly enabling `opt.autodoc` when a
+    package merely declares a dependency on AutoDoc
+  - Keep the documented `relativePath` and `nopdf` global options,
+    and keep the legacy option-record override syntax for
+    `AutoDocWorksheet()` for backwards compatibility while no longer
+    recommending it
+
 ## 2026.03.18
   - Fix running the test suite via `TestPackage("AutoDoc")` when the
     current working directory is not the package root

gap/AutoDocMainFunction.gd

@@ -51,9 +51,11 @@ DeclareGlobalFunction( "ExtractTitleInfoFromPackageInfo" );
 #!  The purpose of this function is to create stand-alone PDF and HTML files
 #!  using &AutoDoc; without associating them with a package.
 #!  <P/>
-#!  It uses the same optional record entries as <Ref Func="AutoDoc"/>, but
-#!  instead of a package name, you pass one filename or a list of filenames
-#!  containing &AutoDoc; text from which the document is created.
+#!  Instead of a package directory, you pass one filename or a list of
+#!  filenames containing &AutoDoc; text from which the document is created.
+#!  Settings are supplied via an optional record using the same entries as
+#!  the <A>optrec</A> argument of <Ref Func="AutoDoc"/>. Alternatively, you may
+#!  omit <A>filenames</A> and specify the files via <C>optrec.autodoc.files</C>.
 #!  <P/>
 #!  A simple worksheet file can define title-page information and chapter
 #!  content directly in the source file, including example blocks.
@@ -65,5 +67,18 @@ DeclareGlobalFunction( "ExtractTitleInfoFromPackageInfo" );
 #!  <P/>
 #!  Since worksheets do not have a <F>PackageInfo.g</F>, title-page fields are
 #!  specified directly in the worksheet file.
-#! @Arguments list_of_filenames : options
+#!  <P/>
+#!  For backwards compatibility, worksheet calls still accept GAP global
+#!  options for specifying the option-record entries such as
+#!  <C>dir</C>, <C>scaffold</C>, <C>autodoc</C>, <C>gapdoc</C>, and
+#!  <C>extract_examples</C>.
+#!  However, this feature is deprecated. If its use is detected, &AutoDoc;
+#!  prints a warning recommending the explicit options record instead.
+#!  For example:
+#!  @BeginLogSession
+#!  gap> AutoDocWorksheet( : autodoc := rec( files := ["worksheet.g"] ) );
+#!  #W AutoDocWorksheet: legacy ':' syntax is deprecated; use optrec instead
+#!  ...
+#!  @EndLogSession
+#! @Arguments [filenames,] [optrec]
 DeclareGlobalFunction( "AutoDocWorksheet" );

gap/AutoDocMainFunction.gi

@@ -323,37 +323,52 @@ end );
 ##
 InstallGlobalFunction( AutoDocWorksheet,
   function( arg )
-    local autodoc_rec, scaffold_rec;
-
-    if Length( arg ) = 1 then
-        arg[ 2 ] := rec( );
-    fi;
-
-    scaffold_rec := ValueOption( "scaffold" );
-    if scaffold_rec = fail then
-        scaffold_rec := rec( );
-    fi;
-    AUTODOC_SetIfMissing( scaffold_rec, "index", false );
-
-    if Length( arg ) = 2 then
-        autodoc_rec := ValueOption( "autodoc" );
-        if autodoc_rec = fail then
-            autodoc_rec := rec( );
+    local filenames, opt, key, val, used_legacy_value_options;
+
+    filenames := [ ];
+    opt := rec( );
+
+    if Length( arg ) > 2 then
+        Error("too many arguments");
+    elif Length( arg ) > 0 then
+        if IsString( First( arg ) ) then
+            filenames := [ First( arg ) ];
+        elif IsList( First( arg ) ) then
+            filenames := First( arg );
         fi;
-        if IsString( arg[ 1 ] ) then
-            arg[ 1 ] := [ arg[ 1 ] ];
+        if IsRecord( Last( arg ) ) then
+            opt := StructuralCopy( Last( arg ) );
         fi;
-        if IsBound( autodoc_rec.files ) then
-            Append( autodoc_rec.files, arg[ 1 ] );
-        else
-            autodoc_rec.files := arg[ 1 ];
+    fi;
+
+    # Backwards compatibility: worksheet callers historically passed the
+    # normal AutoDoc option-record entries via GAP value options.
+    used_legacy_value_options := false;
+    for key in [ "dir", "scaffold", "autodoc", "gapdoc", "extract_examples" ] do
+        val := ValueOption( key );
+        if val <> fail then
+            opt.( key ) := val;
+            used_legacy_value_options := true;
         fi;
-        AutoDoc( "AutoDocWorksheet", arg[ 2 ] : autodoc := autodoc_rec, scaffold := scaffold_rec );
+    od;
+
+    if used_legacy_value_options then
+        Print(
+            "#W AutoDocWorksheet: legacy ':' syntax is deprecated; ",
+            "use optrec instead\n"
+        );
     fi;
 
-    if Length( arg ) = 0 then
-        AutoDoc( "AutoDocWorksheet" : scaffold := scaffold_rec );
+    AUTODOC_SetIfMissing( opt, "scaffold", rec( ) );
+    AUTODOC_SetIfMissing( opt.scaffold, "index", false );
+
+    if Length( filenames ) > 0 then
+        AUTODOC_SetIfMissing( opt, "autodoc", rec( ) );
+        AUTODOC_SetIfMissing( opt.autodoc, "files", [ ] );
+        Append( opt.autodoc.files, filenames );
     fi;
+
+    AutoDoc( "AutoDocWorksheet", opt );
 end );
 
 # The following function is based on code by Alexander Konovalov

gap/Magic.gd

@@ -53,19 +53,16 @@
 #! <Item>
 #!     The purpose of this parameter is twofold: to determine the package
 #!     directory in which &AutoDoc; will operate, and to find the metadata
-#!     concerning the package being documented. The parameter is either a
-#!     string, an <C>IsDirectory</C> object, or omitted.
-#!     If it is a string, &AutoDoc; interprets it as the name of a
-#!     package, uses the metadata of the first package known to &GAP;
-#!     with that name, and uses the <C>InstallationPath</C> specified in that
-#!     metadata as the package directory. If <A>packageOrDirectory</A> is
-#!     an <C>IsDirectory</C> object, this is used as package directory;
-#!     if the argument is omitted, then the current directory is used.
-#!     In the last two cases, the specified directory must contain a
+#!     concerning the package being documented. The parameter is either an
+#!     <C>IsDirectory</C> object or omitted. If
+#!     <A>packageOrDirectory</A> is an <C>IsDirectory</C> object, this is used
+#!     as package directory; if the argument is omitted, then the current
+#!     directory is used. In both cases, the specified directory must contain a
 #!     <F>PackageInfo.g</F> file, and &AutoDoc; extracts all needed metadata
 #!     from that. The <C>IsDirectory</C> form is for example useful if you
 #!     have multiple versions of the package around and want to make sure the
 #!     documentation of the correct version is built.
+#!     Passing a package name string is no longer supported.
 #!     <P/>
 #!     Note that when using <C>AutoDocWorksheet</C> (see
 #!     <Ref Sect='Section_AutoDocWorksheet'/>), there is
@@ -238,9 +235,7 @@
 #!         The value should be either <K>true</K>, <K>false</K> or a
 #!         record. If it is a record or <K>true</K> (the latter is
 #!         equivalent to specifying an empty record), then this feature is
-#!         enabled. It is also enabled if <A>opt.autodoc</A> is missing but the
-#!         package depends (directly) on the &AutoDoc; package.
-#!         In all other cases (in particular if <A>opt.autodoc</A> is
+#!         enabled. In all other cases (in particular if <A>opt.autodoc</A> is
 #!         <K>false</K>), this feature is disabled.
 #!         <P/>
 #!

gap/Magic.gi

@@ -67,28 +67,9 @@ function( arg )
         pkgdir := DirectoryCurrent( );
 
     else
-        is_worksheet := false;
-        pkginfo := PackageInfo( pkgname );
-        if IsEmpty( pkginfo ) then
-            Error( "Could not find package ", pkgname );
-        elif Length( pkginfo ) > 1 then
-            Info( InfoWarning, 1, "multiple versions of package ", pkgname, " are present, using the first one" );
-        fi;
-        pkginfo := pkginfo[ 1 ];
-        pkgdir := Directory( pkginfo.InstallationPath );
+        Error("Invoking 'AutoDoc' with a package name as argument is no longer supported");
     fi;
 
-    #
-    # Check for user supplied options. If present, they take
-    # precedence over any defaults as well as the opt record.
-    #
-    for key in [ "dir", "scaffold", "autodoc", "gapdoc", "extract_examples" ] do
-        val := ValueOption( key );
-        if val <> fail then
-            opt.(key) := val;
-        fi;
-    od;
-
     #
     # Setup the output directory
     #
@@ -173,18 +154,9 @@ function( arg )
     #
     # Extract AutoDoc settings
     #
-    if not IsBound(opt.autodoc) and not is_worksheet then
-        # Enable AutoDoc support if the package depends on AutoDoc.
-        tmp := Concatenation( pkginfo.Dependencies.NeededOtherPackages,
-                              pkginfo.Dependencies.SuggestedOtherPackages );
-        ## Empty entries are allowed in Dependencies
-        tmp := Filtered( tmp, i -> i <> [ ] );
-        if ForAny( tmp, x -> LowercaseString(x[1]) = "autodoc" ) then
-            autodoc := rec();
-        fi;
-    elif IsRecord(opt.autodoc) then
+    if IsBound( opt.autodoc ) and IsRecord( opt.autodoc ) then
         autodoc := opt.autodoc;
-    elif IsBool(opt.autodoc) and opt.autodoc = true then
+    elif IsBound( opt.autodoc ) and IsBool( opt.autodoc ) and opt.autodoc = true then
         autodoc := rec();
     fi;
 

tst/AutoDocTest/makedoc-no-autodoc.g

@@ -0,0 +1,13 @@
+LoadPackage("AutoDoc");
+
+AutoDoc(rec(
+  gapdoc := rec(
+    files := [ "gap/AutoDocTest.gd", "gap/AutoDocTest.gi" ],
+  ),
+  scaffold := rec(
+    includes := [ "chapter1.xml" ],
+    appendix := [ "appendix1.xml" ],
+    bib := "AutoDocTest.bib",
+    bibstyle := "alphaurl",
+  ),
+));

tst/autodoctest-manual.tst

@@ -35,6 +35,26 @@ gap> AUTODOC_RunPackageScenario( pkgdir, olddir, rec(
 >   makedoc := "makedoc.g",
 >   doc_expected := "tst/manual.expected",
 > ) );
+gap> AUTODOC_RunPackageScenario( pkgdir, olddir, rec(
+>   name := "no-autodoc-dependency-fallback",
+>   makedoc := "makedoc-no-autodoc.g",
+>   stub_gapdoc := true,
+>   prepare := function( tempdir )
+>     local file, text, out;
+>     file := Concatenation( tempdir, "/PackageInfo.g" );
+>     text := StringFile( file );
+>     text := ReplacedString(
+>       text,
+>       "  NeededOtherPackages := [ ],",
+>       "  NeededOtherPackages := [ [ \"AutoDoc\", \">= 0\" ] ],"
+>     );
+>     out := OutputTextFile( file, false );
+>     WriteAll( out, text );
+>     CloseStream( out );
+>   end,
+>   doc_present := [ "_entities.xml", "_main.xml", "title.xml" ],
+>   doc_absent := [ "_Chapter_SourceAPI.xml", "_Chapter_PlainTextFixture.xml", "_Chunks.xml" ],
+> ) );
 
 # entities option variants
 gap> AUTODOC_RunPackageScenario( pkgdir, olddir, rec(

tst/manual.expected/_Chapter_Reference.xml

@@ -8,14 +8,16 @@
 <Heading>AutoDoc worksheets</Heading>
 
 <ManSection>
-  <Func Arg="list_of_filenames : options" Name="AutoDocWorksheet" />
+  <Func Arg="[filenames,] [optrec]" Name="AutoDocWorksheet" />
  <Description>
   The purpose of this function is to create stand-alone PDF and HTML files
   using &AutoDoc; without associating them with a package.
   <P/>
-  It uses the same optional record entries as <Ref Func="AutoDoc"/>, but
-  instead of a package name, you pass one filename or a list of filenames
-  containing &AutoDoc; text from which the document is created.
+  Instead of a package directory, you pass one filename or a list of
+  filenames containing &AutoDoc; text from which the document is created.
+  Settings are supplied via an optional record using the same entries as
+  the <A>optrec</A> argument of <Ref Func="AutoDoc"/>. Alternatively, you may
+  omit <A>filenames</A> and specify the files via <C>optrec.autodoc.files</C>.
   <P/>
   A simple worksheet file can define title-page information and chapter
   content directly in the source file, including example blocks.
@@ -28,6 +30,20 @@
   <P/>
   Since worksheets do not have a <F>PackageInfo.g</F>, title-page fields are
   specified directly in the worksheet file.
+  <P/>
+  For backwards compatibility, worksheet calls still accept GAP global
+  options for specifying the option-record entries such as
+  <C>dir</C>, <C>scaffold</C>, <C>autodoc</C>, <C>gapdoc</C>, and
+  <C>extract_examples</C>.
+  However, this feature is deprecated. If its use is detected, &AutoDoc;
+  prints a warning recommending the explicit options record instead.
+  For example:
+<Log><![CDATA[
+ gap> AutoDocWorksheet( : autodoc := rec( files := ["worksheet.g"] ) );
+ #W AutoDocWorksheet: legacy ':' syntax is deprecated; use optrec instead
+ ...
+]]></Log>
+
  </Description>
 </ManSection>
 
@@ -83,19 +99,16 @@
  <Item>
      The purpose of this parameter is twofold: to determine the package
      directory in which &AutoDoc; will operate, and to find the metadata
-     concerning the package being documented. The parameter is either a
-     string, an <C>IsDirectory</C> object, or omitted.
-     If it is a string, &AutoDoc; interprets it as the name of a
-     package, uses the metadata of the first package known to &GAP;
-     with that name, and uses the <C>InstallationPath</C> specified in that
-     metadata as the package directory. If <A>packageOrDirectory</A> is
-     an <C>IsDirectory</C> object, this is used as package directory;
-     if the argument is omitted, then the current directory is used.
-     In the last two cases, the specified directory must contain a
+     concerning the package being documented. The parameter is either an
+     <C>IsDirectory</C> object or omitted. If
+     <A>packageOrDirectory</A> is an <C>IsDirectory</C> object, this is used
+     as package directory; if the argument is omitted, then the current
+     directory is used. In both cases, the specified directory must contain a
      <F>PackageInfo.g</F> file, and &AutoDoc; extracts all needed metadata
      from that. The <C>IsDirectory</C> form is for example useful if you
      have multiple versions of the package around and want to make sure the
      documentation of the correct version is built.
+     Passing a package name string is no longer supported.
      <P/>
      Note that when using <C>AutoDocWorksheet</C> (see
      <Ref Sect='Section_AutoDocWorksheet'/>), there is
@@ -256,9 +269,7 @@
          The value should be either <K>true</K>, <K>false</K> or a
          record. If it is a record or <K>true</K> (the latter is
          equivalent to specifying an empty record), then this feature is
-         enabled. It is also enabled if <A>opt.autodoc</A> is missing but the
-         package depends (directly) on the &AutoDoc; package.
-         In all other cases (in particular if <A>opt.autodoc</A> is
+         enabled. In all other cases (in particular if <A>opt.autodoc</A> is
          <K>false</K>), this feature is disabled.
          <P/>
 <P/>

tst/utils.g

@@ -31,6 +31,10 @@ AUTODOC_RunPackageScenario := function( pkgdir, olddir, scenario )
     Exec( Concatenation( "cp -R \"", pkgdir, "\" \"", tempdir, "\"" ) );
     ChangeDirectoryCurrent( tempdir );
 
+    if IsBound( scenario.prepare ) then
+        scenario.prepare( tempdir );
+    fi;
+
     docdir := Directory( Concatenation( tempdir, "/doc" ) );
     # Keep only handwritten fixture inputs in doc/. Any pre-existing generated
     # output would otherwise make presence/absence checks depend on stale files