From e4a9426b400f0611ac230519570dea5b9b407ebb Mon Sep 17 00:00:00 2001
From: Max Horn <max@quendi.de>
Date: Sun, 3 May 2026 13:21:11 +0200
Subject: [PATCH] Clarify AutoDocWorksheet docs

---
 gap/AutoDocMainFunction.gd                 | 16 ++++++++++++----
 tst/manual.expected/_Chapter_Reference.xml | 16 ++++++++++++----
 2 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/gap/AutoDocMainFunction.gd b/gap/AutoDocMainFunction.gd
index ae6ad5a8..cbf1cc6b 100644
--- a/gap/AutoDocMainFunction.gd
+++ b/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,11 @@ 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.
+#! @Arguments [filenames,] [optrec]
 DeclareGlobalFunction( "AutoDocWorksheet" );
diff --git a/tst/manual.expected/_Chapter_Reference.xml b/tst/manual.expected/_Chapter_Reference.xml
index 9faf6370..71c14bc5 100644
--- a/tst/manual.expected/_Chapter_Reference.xml
+++ b/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,12 @@
   <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.
  </Description>
 </ManSection>