Script 'mail_helper' called by obssrc Hello community, here is the log from the commit of package gap-autodoc for openSUSE:Factory checked in at 2026-05-04 14:42:04 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Comparing /work/SRC/openSUSE:Factory/gap-autodoc (Old) and /work/SRC/openSUSE:Factory/.gap-autodoc.new.30200 (New) ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Package is "gap-autodoc" Mon May 4 14:42:04 2026 rev:7 rq:1350647 version:2026.05.03 Changes: -------- --- /work/SRC/openSUSE:Factory/gap-autodoc/gap-autodoc.changes 2026-03-19 17:40:56.226659335 +0100 +++ /work/SRC/openSUSE:Factory/.gap-autodoc.new.30200/gap-autodoc.changes 2026-05-04 14:42:06.390471700 +0200 @@ -1,0 +2,11 @@ +Mon May 4 09:49:26 UTC 2026 - Jan Engelhardt <[email protected]> + +- Update to release 2026.05.03 + * Make `AutoDoc()` infer the package directory from + `INPUT_FILENAME()` when called from a `makedoc.g` file outside + the package root + * Deprecate calling `AutoDoc()` with a package name + * Deprecate using GAP global options to pass settings to + `AutoDoc()`, suggest using option records instead + +------------------------------------------------------------------- Old: ---- AutoDoc-2026.03.18.tar.gz New: ---- AutoDoc-2026.05.03.tar.gz ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Other differences: ------------------ ++++++ gap-autodoc.spec ++++++ --- /var/tmp/diff_new_pack.XEWqlz/_old 2026-05-04 14:42:07.134502269 +0200 +++ /var/tmp/diff_new_pack.XEWqlz/_new 2026-05-04 14:42:07.138502433 +0200 @@ -17,7 +17,7 @@ Name: gap-autodoc -Version: 2026.03.18 +Version: 2026.05.03 Release: 0 Summary: GAP: Tools for generating automatic GAPDoc documentations License: GPL-2.0-only ++++++ AutoDoc-2026.03.18.tar.gz -> AutoDoc-2026.05.03.tar.gz ++++++ diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/CHANGES.md new/AutoDoc-2026.05.03/CHANGES.md --- old/AutoDoc-2026.03.18/CHANGES.md 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/CHANGES.md 2026-05-03 02:00:00.000000000 +0200 @@ -1,5 +1,12 @@ This file describes changes in the AutoDoc package. +## 2026.05.03 + - Make `AutoDoc()` infer the package directory from `INPUT_FILENAME()` + when called from a `makedoc.g` file outside the package root + - Deprecate calling `AutoDoc()` with a package name + - Deprecate using GAP global options to pass settings to `AutoDoc()`, + suggest using option records instead + ## 2026.03.18 - Fix running the test suite via `TestPackage("AutoDoc")` when the current working directory is not the package root diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/Makefile new/AutoDoc-2026.05.03/Makefile --- old/AutoDoc-2026.03.18/Makefile 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/Makefile 2026-05-03 02:00:00.000000000 +0200 @@ -1,7 +1,11 @@ -.PHONY: doc html clean check regen +.PHONY: run doc html clean check regen GAP ?= gap -GAP_ARGS = -q --quitonbreak --packagedirs $(abspath .) +GAP_ARGS = -q --quitonbreak --packagedirs "$(abspath .);" + +# run GAP and load the package +run: + $(GAP) --packagedirs "$(abspath .);" -c 'LoadPackage("AutoDoc");' doc: $(GAP) $(GAP_ARGS) makedoc.g -c 'QUIT;' @@ -10,7 +14,7 @@ NOPDF=1 $(GAP) $(GAP_ARGS) makedoc.g -c 'QUIT;' clean: - cd doc && ./clean + cd doc && rm -f *.{aux,bbl,blg,brf,css,dvi,html,idx,ilg,ind,js,lab,log,out,pdf,pnr,ps,six,tex,toc,txt,xml.bib} _*.xml title.xml check: $(GAP) $(GAP_ARGS) tst/testall.g diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/PackageInfo.g new/AutoDoc-2026.05.03/PackageInfo.g --- old/AutoDoc-2026.03.18/PackageInfo.g 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/PackageInfo.g 2026-05-03 02:00:00.000000000 +0200 @@ -10,7 +10,7 @@ PackageName := "AutoDoc", Subtitle := "Generate documentation from GAP source code", -Version := "2026.03.18", +Version := "2026.05.03", Date := ~.Version{[ 1 .. 10 ]}, Date := Concatenation( ~.Date{[ 9, 10 ]}, "/", ~.Date{[ 6, 7 ]}, "/", ~.Date{[ 1 .. 4 ]} ), diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/Tutorials.autodoc new/AutoDoc-2026.05.03/doc/Tutorials.autodoc --- old/AutoDoc-2026.03.18/doc/Tutorials.autodoc 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/Tutorials.autodoc 2026-05-03 02:00:00.000000000 +0200 @@ -23,15 +23,16 @@ Suppose your package is already up and running, but so far has no manual. Then you can rapidly generate a <Q>scaffold</Q> for a package manual -using the <Ref Func="AutoDoc"/> command like this, -while running &GAP; from within your package's directory (the -one containing the <F>PackageInfo.g</F> file): +using the <Ref Func="AutoDoc"/> command like this: ```@listing LoadPackage( "AutoDoc" ); 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 +When called from a file such as <F>makedoc.g</F>, &AutoDoc; uses the +directory containing that file as the package directory. Otherwise, it +falls back to the current directory. In either case it then reads the +<F>PackageInfo.g</F> file from that package 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/_main.xml</F> and <F>doc/title.xml</F> inside the package directory. Finally, it runs @@ -84,7 +85,7 @@ QUIT; ``` Then you can regenerate the package manual from the command line with the -following command, executed from within the package directory: +following command: ```@listing gap makedoc.g ``` diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/_Chapter_Reference.xml new/AutoDoc-2026.05.03/doc/_Chapter_Reference.xml --- old/AutoDoc-2026.03.18/doc/_Chapter_Reference.xml 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/_Chapter_Reference.xml 2026-05-03 02:00:00.000000000 +0200 @@ -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> @@ -37,7 +45,7 @@ <Heading>The AutoDoc() function</Heading> <ManSection> - <Func Arg="[packageOrDirectory], [optrec]" Name="AutoDoc" /> + <Func Arg="[pkgdir], [optrec]" Name="AutoDoc" /> <Returns>nothing </Returns> <Description> @@ -79,27 +87,29 @@ <P/> The parameters have the following meanings: <List> - <Mark><A>packageOrDirectory</A></Mark> + <Mark><A>pkgdir</A></Mark> <Item> - The purpose of this parameter is twofold: to determine the package + This optional parameter is used 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. If given, it should be + an <C>IsDirectory</C> object. If the argument is omitted, then &AutoDoc; + checks if it was called from a <F>makedoc.g</F> file or similar, and if so, + uses the directory this is contained in. Otherwise 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. <P/> + For backwards compatibility, it is also possible to pass a package name + as this argument, which then is resolved to the package directory of + the first instance of this package &GAP; knows about. However, this is + deprecated, as it is unreliable in the presence of multiple copies of a + package. + <P/> Note that when using <C>AutoDocWorksheet</C> (see <Ref Sect='Section_AutoDocWorksheet'/>), there is - no parameter corresponding to <A>packageOrDirectory</A> and so the + no parameter corresponding to <A>pkgdir</A> and so the <Q>package directory</Q> is always the current directory, and there is no metadata. </Item> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/_Chapter_Tutorials.xml new/AutoDoc-2026.05.03/doc/_Chapter_Tutorials.xml --- old/AutoDoc-2026.03.18/doc/_Chapter_Tutorials.xml 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/_Chapter_Tutorials.xml 2026-05-03 02:00:00.000000000 +0200 @@ -38,15 +38,16 @@ <P/> Suppose your package is already up and running, but so far has no manual. Then you can rapidly generate a <Q>scaffold</Q> for a package manual -using the <Ref Func="AutoDoc"/> command like this, -while running &GAP; from within your package's directory (the -one containing the <F>PackageInfo.g</F> file): +using the <Ref Func="AutoDoc"/> command like this: <Listing><![CDATA[ LoadPackage( "AutoDoc" ); AutoDoc( rec( scaffold := true ) ); ]]></Listing> -This first reads the <F>PackageInfo.g</F> file from the current -directory. It extracts information about the package from it +When called from a file such as <F>makedoc.g</F>, &AutoDoc; uses the +directory containing that file as the package directory. Otherwise, it +falls back to the current directory. In either case it then reads the +<F>PackageInfo.g</F> file from that package 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/_main.xml</F> and <F>doc/title.xml</F> inside the package directory. Finally, it runs @@ -99,7 +100,7 @@ QUIT; ]]></Listing> Then you can regenerate the package manual from the command line with the -following command, executed from within the package directory: +following command: <Listing><![CDATA[ gap makedoc.g ]]></Listing> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/_entities.xml new/AutoDoc-2026.05.03/doc/_entities.xml --- old/AutoDoc-2026.03.18/doc/_entities.xml 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/_entities.xml 2026-05-03 02:00:00.000000000 +0200 @@ -1,6 +1,6 @@ <!ENTITY AutoDoc '<Package>AutoDoc</Package>'> <!ENTITY PackageName '<Package>PackageName</Package>'> -<!ENTITY RELEASEDATE '18 March 2026'> +<!ENTITY RELEASEDATE '3 May 2026'> <!ENTITY RELEASEYEAR '2026'> -<!ENTITY VERSION '2026.03.18'> +<!ENTITY VERSION '2026.05.03'> <!ENTITY io '<Package>io</Package>'> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/_main.tex new/AutoDoc-2026.05.03/doc/_main.tex --- old/AutoDoc-2026.03.18/doc/_main.tex 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/_main.tex 2026-05-03 02:00:00.000000000 +0200 @@ -101,8 +101,8 @@ {\Huge \textbf{ Generate documentation from \textsf{GAP} source code \mbox{}}}\\ \vfill -{\Huge 2026.03.18 \mbox{}}\\[1cm] -{ 18 March 2026 \mbox{}}\\[1cm] +{\Huge 2026.05.03 \mbox{}}\\[1cm] +{ 3 May 2026 \mbox{}}\\[1cm] \mbox{}\\[2cm] {\Large \textbf{ Sebastian Gutsche \mbox{}}}\\ {\Large \textbf{ Max Horn \mbox{}}}\\ @@ -267,12 +267,13 @@ Suppose your package is already up and running, but so far has no manual. Then -you can rapidly generate a ``scaffold'' for a package manual using the \texttt{AutoDoc} (\ref{AutoDoc}) command like this, while running \textsf{GAP} from within your package's directory (the one containing the \texttt{PackageInfo.g} file): +you can rapidly generate a ``scaffold'' for a package manual using the \texttt{AutoDoc} (\ref{AutoDoc}) command like this: \begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=] LoadPackage( "AutoDoc" ); AutoDoc( rec( scaffold := true ) ); \end{Verbatim} - This first reads the \texttt{PackageInfo.g} file from the current directory. It extracts information about the package + When called from a file such as \texttt{makedoc.g}, \textsf{AutoDoc} uses the directory containing that file as the package directory. Otherwise, +it falls back to the current directory. In either case it then reads the \texttt{PackageInfo.g} file from that package directory. It extracts information about the package from it (such as its name and version, see Section \ref{Subsection_Tut:Scaffolds:Title}). It then creates two XML files \texttt{doc/{\textunderscore}main.xml} and \texttt{doc/title.xml} inside the package directory. Finally, it runs \textsf{GAPDoc} on them to produce a nice initial PDF and HTML version of your fresh manual. To ensure that the \textsf{GAP} help system picks up your package manual, you should also add something like @@ -310,7 +311,7 @@ QUIT; \end{Verbatim} Then you can regenerate the package manual from the command line with the -following command, executed from within the package directory: +following command: \begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=] gap makedoc.g \end{Verbatim} @@ -1767,7 +1768,7 @@ \subsection{\textcolor{Chapter }{AutoDocWorksheet}} \logpage{[ 4, 1, 1 ]}\nobreak \hyperdef{L}{X809FE4137C08B28D}{} -{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AutoDocWorksheet({\mdseries\slshape list{\textunderscore}of{\textunderscore}filenames: options})\index{AutoDocWorksheet@\texttt{AutoDocWorksheet}} +{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AutoDocWorksheet({\mdseries\slshape [filenames][,] [optrec]})\index{AutoDocWorksheet@\texttt{AutoDocWorksheet}} \label{AutoDocWorksheet} }\hfill{\scriptsize (function)}}\\ @@ -1775,8 +1776,9 @@ The purpose of this function is to create stand\texttt{\symbol{45}}alone PDF and HTML files using \textsf{AutoDoc} without associating them with a package. - It uses the same optional record entries as \texttt{AutoDoc} (\ref{AutoDoc}), but instead of a package name, you pass one filename or a list of filenames -containing \textsf{AutoDoc} text from which the document is created. + Instead of a package directory, you pass one filename or a list of filenames +containing \textsf{AutoDoc} text from which the document is created. Settings are supplied via an optional +record using the same entries as the \mbox{\texttt{\mdseries\slshape optrec}} argument of \texttt{AutoDoc} (\ref{AutoDoc}). Alternatively, you may omit \mbox{\texttt{\mdseries\slshape filenames}} and specify the files via \texttt{optrec.autodoc.files}. A simple worksheet file can define title\texttt{\symbol{45}}page information and chapter content directly in the source file, including example blocks. If @@ -1787,7 +1789,10 @@ This creates documentation in a \texttt{doc} subdirectory of the current directory. Since worksheets do not have a \texttt{PackageInfo.g}, title\texttt{\symbol{45}}page fields are specified directly in the worksheet -file. } +file. + + For backwards compatibility, worksheet calls still accept GAP global options +for specifying the option\texttt{\symbol{45}}record entries such as \texttt{dir}, \texttt{scaffold}, \texttt{autodoc}, \texttt{gapdoc}, and \texttt{extract{\textunderscore}examples}. However, this feature is deprecated. } } @@ -1801,7 +1806,7 @@ \subsection{\textcolor{Chapter }{AutoDoc}} \logpage{[ 4, 2, 1 ]}\nobreak \hyperdef{L}{X7CBD8AAF7DCEF352}{} -{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AutoDoc({\mdseries\slshape [packageOrDirectory][,] [optrec]})\index{AutoDoc@\texttt{AutoDoc}} +{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AutoDoc({\mdseries\slshape [pkgdir][,] [optrec]})\index{AutoDoc@\texttt{AutoDoc}} \label{AutoDoc} }\hfill{\scriptsize (function)}}\\ \textbf{\indent Returns:\ } @@ -1830,15 +1835,18 @@ The parameters have the following meanings: \begin{description} -\item[{\mbox{\texttt{\mdseries\slshape packageOrDirectory}}}] The purpose of this parameter is twofold: to determine the package directory -in which \textsf{AutoDoc} will operate, and to find the metadata concerning the package being -documented. The parameter is either a string, an \texttt{IsDirectory} object, or omitted. If it is a string, \textsf{AutoDoc} interprets it as the name of a package, uses the metadata of the first package -known to \textsf{GAP} with that name, and uses the \texttt{InstallationPath} specified in that metadata as the package directory. If \mbox{\texttt{\mdseries\slshape packageOrDirectory}} is an \texttt{IsDirectory} 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 \texttt{PackageInfo.g} file, and \textsf{AutoDoc} extracts all needed metadata from that. The \texttt{IsDirectory} form is for example useful if you have multiple versions of the package around +\item[{\mbox{\texttt{\mdseries\slshape pkgdir}}}] This optional parameter is used to determine the package directory in which \textsf{AutoDoc} will operate, and to find the metadata concerning the package being +documented. If given, it should be an \texttt{IsDirectory} object. If the argument is omitted, then \textsf{AutoDoc} checks if it was called from a \texttt{makedoc.g} file or similar, and if so, uses the directory this is contained in. Otherwise +the current directory is used. In both cases, the specified directory must +contain a \texttt{PackageInfo.g} file, and \textsf{AutoDoc} extracts all needed metadata from that. The \texttt{IsDirectory} 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. - Note that when using \texttt{AutoDocWorksheet} (see \ref{Section_AutoDocWorksheet}), there is no parameter corresponding to \mbox{\texttt{\mdseries\slshape packageOrDirectory}} and so the ``package directory'' is always the current directory, and there is no metadata. + For backwards compatibility, it is also possible to pass a package name as +this argument, which then is resolved to the package directory of the first +instance of this package \textsf{GAP} knows about. However, this is deprecated, as it is unreliable in the presence +of multiple copies of a package. + + Note that when using \texttt{AutoDocWorksheet} (see \ref{Section_AutoDocWorksheet}), there is no parameter corresponding to \mbox{\texttt{\mdseries\slshape pkgdir}} and so the ``package directory'' is always the current directory, and there is no metadata. \item[{\mbox{\texttt{\mdseries\slshape optrec}}}] \mbox{\texttt{\mdseries\slshape optrec}} can be a record with some additional options. The following are currently supported: \begin{description} diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/chap0.html new/AutoDoc-2026.05.03/doc/chap0.html --- old/AutoDoc-2026.03.18/doc/chap0.html 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/chap0.html 2026-05-03 02:00:00.000000000 +0200 @@ -29,10 +29,10 @@ <h2>Generate documentation from <strong class="pkg">GAP</strong> source code</h2> <p> - 2026.03.18</p> + 2026.05.03</p> <p> - 18 March 2026 + 3 May 2026 </p> </div> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/chap0.txt new/AutoDoc-2026.05.03/doc/chap0.txt --- old/AutoDoc-2026.03.18/doc/chap0.txt 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/chap0.txt 2026-05-03 02:00:00.000000000 +0200 @@ -6,10 +6,10 @@ [1X Generate documentation from [5XGAP[105X source code [101X - 2026.03.18 + 2026.05.03 - 18 March 2026 + 3 May 2026 Sebastian Gutsche diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/chap0_mj.html new/AutoDoc-2026.05.03/doc/chap0_mj.html --- old/AutoDoc-2026.03.18/doc/chap0_mj.html 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/chap0_mj.html 2026-05-03 02:00:00.000000000 +0200 @@ -32,10 +32,10 @@ <h2>Generate documentation from <strong class="pkg">GAP</strong> source code</h2> <p> - 2026.03.18</p> + 2026.05.03</p> <p> - 18 March 2026 + 3 May 2026 </p> </div> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/chap2.html new/AutoDoc-2026.05.03/doc/chap2.html --- old/AutoDoc-2026.03.18/doc/chap2.html 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/chap2.html 2026-05-03 02:00:00.000000000 +0200 @@ -86,7 +86,7 @@ <h4>2.2 <span class="Heading">Creating a package manual from scratch</span></h4> -<p>Suppose your package is already up and running, but so far has no manual. Then you can rapidly generate a <q>scaffold</q> for a package manual using the <code class="func">AutoDoc</code> (<a href="chap4.html#X7CBD8AAF7DCEF352"><span class="RefLink">4.2-1</span></a>) command like this, while running <strong class="pkg">GAP</strong> from within your package's directory (the one containing the <code class="file">PackageInfo.g</code> file):</p> +<p>Suppose your package is already up and running, but so far has no manual. Then you can rapidly generate a <q>scaffold</q> for a package manual using the <code class="func">AutoDoc</code> (<a href="chap4.html#X7CBD8AAF7DCEF352"><span class="RefLink">4.2-1</span></a>) command like this:</p> <div class="example"><pre> @@ -94,7 +94,7 @@ AutoDoc( rec( scaffold := true ) ); </pre></div> -<p>This first reads the <code class="file">PackageInfo.g</code> file from the current directory. It extracts information about the package from it (such as its name and version, see Section <a href="chap2.html#X7CF22DE28478316F"><span class="RefLink">2.5-1</span></a>). It then creates two XML files <code class="file">doc/_main.xml</code> and <code class="file">doc/title.xml</code> inside the package directory. Finally, it runs <strong class="pkg">GAPDoc</strong> on them to produce a nice initial PDF and HTML version of your fresh manual.</p> +<p>When called from a file such as <code class="file">makedoc.g</code>, <strong class="pkg">AutoDoc</strong> uses the directory containing that file as the package directory. Otherwise, it falls back to the current directory. In either case it then reads the <code class="file">PackageInfo.g</code> file from that package directory. It extracts information about the package from it (such as its name and version, see Section <a href="chap2.html#X7CF22DE28478316F"><span class="RefLink">2.5-1</span></a>). It then creates two XML files <code class="file">doc/_main.xml</code> and <code class="file">doc/title.xml</code> inside the package directory. Finally, it runs <strong class="pkg">GAPDoc</strong> on them to produce a nice initial PDF and HTML version of your fresh manual.</p> <p>To ensure that the <strong class="pkg">GAP</strong> help system picks up your package manual, you should also add something like the following to your <code class="file">PackageInfo.g</code>:</p> @@ -123,7 +123,7 @@ QUIT; </pre></div> -<p>Then you can regenerate the package manual from the command line with the following command, executed from within the package directory:</p> +<p>Then you can regenerate the package manual from the command line with the following command:</p> <div class="example"><pre> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/chap2.txt new/AutoDoc-2026.05.03/doc/chap2.txt --- old/AutoDoc-2026.03.18/doc/chap2.txt 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/chap2.txt 2026-05-03 02:00:00.000000000 +0200 @@ -24,19 +24,21 @@ [33X[0;0YSuppose your package is already up and running, but so far has no manual. Then you can rapidly generate a [21Xscaffold[121X for a package manual using the - [2XAutoDoc[102X ([14X4.2-1[114X) command like this, while running [5XGAP[105X from within your - package's directory (the one containing the [11XPackageInfo.g[111X file):[133X + [2XAutoDoc[102X ([14X4.2-1[114X) command like this:[133X [4X[32X[104X [4XLoadPackage( "AutoDoc" );[104X [4XAutoDoc( rec( scaffold := true ) );[104X [4X[32X[104X - [33X[0;0YThis first reads the [11XPackageInfo.g[111X file from the current directory. It - extracts information about the package from it (such as its name and - version, see Section [14X2.5-1[114X). It then creates two XML files [11Xdoc/_main.xml[111X and - [11Xdoc/title.xml[111X inside the package directory. Finally, it runs [5XGAPDoc[105X on them - to produce a nice initial PDF and HTML version of your fresh manual.[133X + [33X[0;0YWhen called from a file such as [11Xmakedoc.g[111X, [5XAutoDoc[105X uses the directory + containing that file as the package directory. Otherwise, it falls back to + the current directory. In either case it then reads the [11XPackageInfo.g[111X file + from that package directory. It extracts information about the package from + it (such as its name and version, see Section [14X2.5-1[114X). It then creates two + XML files [11Xdoc/_main.xml[111X and [11Xdoc/title.xml[111X inside the package directory. + Finally, it runs [5XGAPDoc[105X on them to produce a nice initial PDF and HTML + version of your fresh manual.[133X [33X[0;0YTo ensure that the [5XGAP[105X help system picks up your package manual, you should also add something like the following to your [11XPackageInfo.g[111X:[133X @@ -83,7 +85,7 @@ [4X[32X[104X [33X[0;0YThen you can regenerate the package manual from the command line with the - following command, executed from within the package directory:[133X + following command:[133X [4X[32X[104X [4Xgap makedoc.g[104X diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/chap2_mj.html new/AutoDoc-2026.05.03/doc/chap2_mj.html --- old/AutoDoc-2026.03.18/doc/chap2_mj.html 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/chap2_mj.html 2026-05-03 02:00:00.000000000 +0200 @@ -89,7 +89,7 @@ <h4>2.2 <span class="Heading">Creating a package manual from scratch</span></h4> -<p>Suppose your package is already up and running, but so far has no manual. Then you can rapidly generate a <q>scaffold</q> for a package manual using the <code class="func">AutoDoc</code> (<a href="chap4_mj.html#X7CBD8AAF7DCEF352"><span class="RefLink">4.2-1</span></a>) command like this, while running <strong class="pkg">GAP</strong> from within your package's directory (the one containing the <code class="file">PackageInfo.g</code> file):</p> +<p>Suppose your package is already up and running, but so far has no manual. Then you can rapidly generate a <q>scaffold</q> for a package manual using the <code class="func">AutoDoc</code> (<a href="chap4_mj.html#X7CBD8AAF7DCEF352"><span class="RefLink">4.2-1</span></a>) command like this:</p> <div class="example"><pre> @@ -97,7 +97,7 @@ AutoDoc( rec( scaffold := true ) ); </pre></div> -<p>This first reads the <code class="file">PackageInfo.g</code> file from the current directory. It extracts information about the package from it (such as its name and version, see Section <a href="chap2_mj.html#X7CF22DE28478316F"><span class="RefLink">2.5-1</span></a>). It then creates two XML files <code class="file">doc/_main.xml</code> and <code class="file">doc/title.xml</code> inside the package directory. Finally, it runs <strong class="pkg">GAPDoc</strong> on them to produce a nice initial PDF and HTML version of your fresh manual.</p> +<p>When called from a file such as <code class="file">makedoc.g</code>, <strong class="pkg">AutoDoc</strong> uses the directory containing that file as the package directory. Otherwise, it falls back to the current directory. In either case it then reads the <code class="file">PackageInfo.g</code> file from that package directory. It extracts information about the package from it (such as its name and version, see Section <a href="chap2_mj.html#X7CF22DE28478316F"><span class="RefLink">2.5-1</span></a>). It then creates two XML files <code class="file">doc/_main.xml</code> and <code class="file">doc/title.xml</code> inside the package directory. Finally, it runs <strong class="pkg">GAPDoc</strong> on them to produce a nice initial PDF and HTML version of your fresh manual.</p> <p>To ensure that the <strong class="pkg">GAP</strong> help system picks up your package manual, you should also add something like the following to your <code class="file">PackageInfo.g</code>:</p> @@ -126,7 +126,7 @@ QUIT; </pre></div> -<p>Then you can regenerate the package manual from the command line with the following command, executed from within the package directory:</p> +<p>Then you can regenerate the package manual from the command line with the following command:</p> <div class="example"><pre> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/chap4.html new/AutoDoc-2026.05.03/doc/chap4.html --- old/AutoDoc-2026.03.18/doc/chap4.html 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/chap4.html 2026-05-03 02:00:00.000000000 +0200 @@ -45,10 +45,10 @@ <h5>4.1-1 AutoDocWorksheet</h5> -<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ AutoDocWorksheet</code>( <var class="Arg">list_of_filenames:</var> <var class="Arg">options</var> )</td><td class="tdright">( function )</td></tr></table></div> +<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ AutoDocWorksheet</code>( [<var class="Arg">filenames</var>][,] [<var class="Arg">optrec</var>] )</td><td class="tdright">( function )</td></tr></table></div> <p>The purpose of this function is to create stand-alone PDF and HTML files using <strong class="pkg">AutoDoc</strong> without associating them with a package.</p> -<p>It uses the same optional record entries as <code class="func">AutoDoc</code> (<a href="chap4.html#X7CBD8AAF7DCEF352"><span class="RefLink">4.2-1</span></a>), but instead of a package name, you pass one filename or a list of filenames containing <strong class="pkg">AutoDoc</strong> text from which the document is created.</p> +<p>Instead of a package directory, you pass one filename or a list of filenames containing <strong class="pkg">AutoDoc</strong> text from which the document is created. Settings are supplied via an optional record using the same entries as the <var class="Arg">optrec</var> argument of <code class="func">AutoDoc</code> (<a href="chap4.html#X7CBD8AAF7DCEF352"><span class="RefLink">4.2-1</span></a>). Alternatively, you may omit <var class="Arg">filenames</var> and specify the files via <code class="code">optrec.autodoc.files</code>.</p> <p>A simple worksheet file can define title-page information and chapter content directly in the source file, including example blocks. If this is stored in <code class="file">worksheet.g</code>, you can generate documentation via</p> @@ -61,6 +61,8 @@ <p>Since worksheets do not have a <code class="file">PackageInfo.g</code>, title-page fields are specified directly in the worksheet file.</p> +<p>For backwards compatibility, worksheet calls still accept GAP global options for specifying the option-record entries such as <code class="code">dir</code>, <code class="code">scaffold</code>, <code class="code">autodoc</code>, <code class="code">gapdoc</code>, and <code class="code">extract_examples</code>. However, this feature is deprecated.</p> + <p><a id="X863584DB8497D8BA" name="X863584DB8497D8BA"></a></p> <h4>4.2 <span class="Heading">The AutoDoc() function</span></h4> @@ -69,7 +71,7 @@ <h5>4.2-1 AutoDoc</h5> -<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ AutoDoc</code>( [<var class="Arg">packageOrDirectory</var>][,] [<var class="Arg">optrec</var>] )</td><td class="tdright">( function )</td></tr></table></div> +<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ AutoDoc</code>( [<var class="Arg">pkgdir</var>][,] [<var class="Arg">optrec</var>] )</td><td class="tdright">( function )</td></tr></table></div> <p>Returns: nothing</p> <p>This is the main function of the <strong class="pkg">AutoDoc</strong> package. It can perform any combination of the following tasks:</p> @@ -91,10 +93,12 @@ <dl> -<dt><strong class="Mark"><var class="Arg">packageOrDirectory</var></strong></dt> -<dd><p>The purpose of this parameter is twofold: to determine the package directory in which <strong class="pkg">AutoDoc</strong> will operate, and to find the metadata concerning the package being documented. The parameter is either a string, an <code class="code">IsDirectory</code> object, or omitted. If it is a string, <strong class="pkg">AutoDoc</strong> interprets it as the name of a package, uses the metadata of the first package known to <strong class="pkg">GAP</strong> with that name, and uses the <code class="code">InstallationPath</code> specified in that metadata as the package directory. If <var class="Arg">packageOrDirectory</var> is an <code class="code">IsDirectory</code> 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 <code class="file">PackageInfo.g</code> file, and <strong class="pkg">AutoDoc</strong> extracts all needed metadata from that. The < code class="code">IsDirectory</code> 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.</p> +<dt><strong class="Mark"><var class="Arg">pkgdir</var></strong></dt> +<dd><p>This optional parameter is used to determine the package directory in which <strong class="pkg">AutoDoc</strong> will operate, and to find the metadata concerning the package being documented. If given, it should be an <code class="code">IsDirectory</code> object. If the argument is omitted, then <strong class="pkg">AutoDoc</strong> checks if it was called from a <code class="file">makedoc.g</code> file or similar, and if so, uses the directory this is contained in. Otherwise the current directory is used. In both cases, the specified directory must contain a <code class="file">PackageInfo.g</code> file, and <strong class="pkg">AutoDoc</strong> extracts all needed metadata from that. The <code class="code">IsDirectory</code> 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.</p> + +<p>For backwards compatibility, it is also possible to pass a package name as this argument, which then is resolved to the package directory of the first instance of this package <strong class="pkg">GAP</strong> knows about. However, this is deprecated, as it is unreliable in the presence of multiple copies of a package.</p> -<p>Note that when using <code class="code">AutoDocWorksheet</code> (see <a href="chap4.html#X80ED3C2A78146AD1"><span class="RefLink">4.1</span></a>), there is no parameter corresponding to <var class="Arg">packageOrDirectory</var> and so the <q>package directory</q> is always the current directory, and there is no metadata.</p> +<p>Note that when using <code class="code">AutoDocWorksheet</code> (see <a href="chap4.html#X80ED3C2A78146AD1"><span class="RefLink">4.1</span></a>), there is no parameter corresponding to <var class="Arg">pkgdir</var> and so the <q>package directory</q> is always the current directory, and there is no metadata.</p> </dd> <dt><strong class="Mark"><var class="Arg">optrec</var></strong></dt> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/chap4.txt new/AutoDoc-2026.05.03/doc/chap4.txt --- old/AutoDoc-2026.03.18/doc/chap4.txt 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/chap4.txt 2026-05-03 02:00:00.000000000 +0200 @@ -6,14 +6,16 @@ [1X4.1-1 AutoDocWorksheet[101X - [33X[1;0Y[29X[2XAutoDocWorksheet[102X( [3Xlist_of_filenames:[103X [3Xoptions[103X ) [32X function[133X + [33X[1;0Y[29X[2XAutoDocWorksheet[102X( [[3Xfilenames[103X][,] [[3Xoptrec[103X] ) [32X function[133X [33X[0;0YThe purpose of this function is to create stand-alone PDF and HTML files using [5XAutoDoc[105X without associating them with a package.[133X - [33X[0;0YIt uses the same optional record entries as [2XAutoDoc[102X ([14X4.2-1[114X), but instead of - a package name, you pass one filename or a list of filenames containing - [5XAutoDoc[105X text from which the document is created.[133X + [33X[0;0YInstead of a package directory, you pass one filename or a list of filenames + containing [5XAutoDoc[105X text from which the document is created. Settings are + supplied via an optional record using the same entries as the [3Xoptrec[103X + argument of [2XAutoDoc[102X ([14X4.2-1[114X). Alternatively, you may omit [3Xfilenames[103X and + specify the files via [10Xoptrec.autodoc.files[110X.[133X [33X[0;0YA simple worksheet file can define title-page information and chapter content directly in the source file, including example blocks. If this is @@ -28,12 +30,16 @@ [33X[0;0YSince worksheets do not have a [11XPackageInfo.g[111X, title-page fields are specified directly in the worksheet file.[133X + [33X[0;0YFor backwards compatibility, worksheet calls still accept GAP global options + for specifying the option-record entries such as [10Xdir[110X, [10Xscaffold[110X, [10Xautodoc[110X, + [10Xgapdoc[110X, and [10Xextract_examples[110X. However, this feature is deprecated.[133X + [1X4.2 [33X[0;0YThe AutoDoc() function[133X[101X [1X4.2-1 AutoDoc[101X - [33X[1;0Y[29X[2XAutoDoc[102X( [[3XpackageOrDirectory[103X][,] [[3Xoptrec[103X] ) [32X function[133X + [33X[1;0Y[29X[2XAutoDoc[102X( [[3Xpkgdir[103X][,] [[3Xoptrec[103X] ) [32X function[133X [6XReturns:[106X [33X[0;10Ynothing[133X [33X[0;0YThis is the main function of the [5XAutoDoc[105X package. It can perform any @@ -69,25 +75,28 @@ [33X[0;0YThe parameters have the following meanings:[133X - [8X[3XpackageOrDirectory[103X[8X[108X - [33X[0;6YThe purpose of this parameter is twofold: to determine the package - directory in which [5XAutoDoc[105X will operate, and to find the metadata - concerning the package being documented. The parameter is either a - string, an [10XIsDirectory[110X object, or omitted. If it is a string, [5XAutoDoc[105X - interprets it as the name of a package, uses the metadata of the first - package known to [5XGAP[105X with that name, and uses the [10XInstallationPath[110X - specified in that metadata as the package directory. If - [3XpackageOrDirectory[103X is an [10XIsDirectory[110X 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 - [11XPackageInfo.g[111X file, and [5XAutoDoc[105X extracts all needed metadata from - that. The [10XIsDirectory[110X 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.[133X + [8X[3Xpkgdir[103X[8X[108X + [33X[0;6YThis optional parameter is used to determine the package directory in + which [5XAutoDoc[105X will operate, and to find the metadata concerning the + package being documented. If given, it should be an [10XIsDirectory[110X + object. If the argument is omitted, then [5XAutoDoc[105X checks if it was + called from a [11Xmakedoc.g[111X file or similar, and if so, uses the directory + this is contained in. Otherwise the current directory is used. In both + cases, the specified directory must contain a [11XPackageInfo.g[111X file, and + [5XAutoDoc[105X extracts all needed metadata from that. The [10XIsDirectory[110X 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.[133X + + [33X[0;6YFor backwards compatibility, it is also possible to pass a package + name as this argument, which then is resolved to the package directory + of the first instance of this package [5XGAP[105X knows about. However, this + is deprecated, as it is unreliable in the presence of multiple copies + of a package.[133X [33X[0;6YNote that when using [10XAutoDocWorksheet[110X (see [14X4.1[114X), there is no parameter - corresponding to [3XpackageOrDirectory[103X and so the [21Xpackage directory[121X is - always the current directory, and there is no metadata.[133X + corresponding to [3Xpkgdir[103X and so the [21Xpackage directory[121X is always the + current directory, and there is no metadata.[133X [8X[3Xoptrec[103X[8X[108X [33X[0;6Y[3Xoptrec[103X can be a record with some additional options. The following are diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/chap4_mj.html new/AutoDoc-2026.05.03/doc/chap4_mj.html --- old/AutoDoc-2026.03.18/doc/chap4_mj.html 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/chap4_mj.html 2026-05-03 02:00:00.000000000 +0200 @@ -48,10 +48,10 @@ <h5>4.1-1 AutoDocWorksheet</h5> -<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ AutoDocWorksheet</code>( <var class="Arg">list_of_filenames:</var> <var class="Arg">options</var> )</td><td class="tdright">( function )</td></tr></table></div> +<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ AutoDocWorksheet</code>( [<var class="Arg">filenames</var>][,] [<var class="Arg">optrec</var>] )</td><td class="tdright">( function )</td></tr></table></div> <p>The purpose of this function is to create stand-alone PDF and HTML files using <strong class="pkg">AutoDoc</strong> without associating them with a package.</p> -<p>It uses the same optional record entries as <code class="func">AutoDoc</code> (<a href="chap4_mj.html#X7CBD8AAF7DCEF352"><span class="RefLink">4.2-1</span></a>), but instead of a package name, you pass one filename or a list of filenames containing <strong class="pkg">AutoDoc</strong> text from which the document is created.</p> +<p>Instead of a package directory, you pass one filename or a list of filenames containing <strong class="pkg">AutoDoc</strong> text from which the document is created. Settings are supplied via an optional record using the same entries as the <var class="Arg">optrec</var> argument of <code class="func">AutoDoc</code> (<a href="chap4_mj.html#X7CBD8AAF7DCEF352"><span class="RefLink">4.2-1</span></a>). Alternatively, you may omit <var class="Arg">filenames</var> and specify the files via <code class="code">optrec.autodoc.files</code>.</p> <p>A simple worksheet file can define title-page information and chapter content directly in the source file, including example blocks. If this is stored in <code class="file">worksheet.g</code>, you can generate documentation via</p> @@ -64,6 +64,8 @@ <p>Since worksheets do not have a <code class="file">PackageInfo.g</code>, title-page fields are specified directly in the worksheet file.</p> +<p>For backwards compatibility, worksheet calls still accept GAP global options for specifying the option-record entries such as <code class="code">dir</code>, <code class="code">scaffold</code>, <code class="code">autodoc</code>, <code class="code">gapdoc</code>, and <code class="code">extract_examples</code>. However, this feature is deprecated.</p> + <p><a id="X863584DB8497D8BA" name="X863584DB8497D8BA"></a></p> <h4>4.2 <span class="Heading">The AutoDoc() function</span></h4> @@ -72,7 +74,7 @@ <h5>4.2-1 AutoDoc</h5> -<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ AutoDoc</code>( [<var class="Arg">packageOrDirectory</var>][,] [<var class="Arg">optrec</var>] )</td><td class="tdright">( function )</td></tr></table></div> +<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ AutoDoc</code>( [<var class="Arg">pkgdir</var>][,] [<var class="Arg">optrec</var>] )</td><td class="tdright">( function )</td></tr></table></div> <p>Returns: nothing</p> <p>This is the main function of the <strong class="pkg">AutoDoc</strong> package. It can perform any combination of the following tasks:</p> @@ -94,10 +96,12 @@ <dl> -<dt><strong class="Mark"><var class="Arg">packageOrDirectory</var></strong></dt> -<dd><p>The purpose of this parameter is twofold: to determine the package directory in which <strong class="pkg">AutoDoc</strong> will operate, and to find the metadata concerning the package being documented. The parameter is either a string, an <code class="code">IsDirectory</code> object, or omitted. If it is a string, <strong class="pkg">AutoDoc</strong> interprets it as the name of a package, uses the metadata of the first package known to <strong class="pkg">GAP</strong> with that name, and uses the <code class="code">InstallationPath</code> specified in that metadata as the package directory. If <var class="Arg">packageOrDirectory</var> is an <code class="code">IsDirectory</code> 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 <code class="file">PackageInfo.g</code> file, and <strong class="pkg">AutoDoc</strong> extracts all needed metadata from that. The < code class="code">IsDirectory</code> 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.</p> +<dt><strong class="Mark"><var class="Arg">pkgdir</var></strong></dt> +<dd><p>This optional parameter is used to determine the package directory in which <strong class="pkg">AutoDoc</strong> will operate, and to find the metadata concerning the package being documented. If given, it should be an <code class="code">IsDirectory</code> object. If the argument is omitted, then <strong class="pkg">AutoDoc</strong> checks if it was called from a <code class="file">makedoc.g</code> file or similar, and if so, uses the directory this is contained in. Otherwise the current directory is used. In both cases, the specified directory must contain a <code class="file">PackageInfo.g</code> file, and <strong class="pkg">AutoDoc</strong> extracts all needed metadata from that. The <code class="code">IsDirectory</code> 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.</p> + +<p>For backwards compatibility, it is also possible to pass a package name as this argument, which then is resolved to the package directory of the first instance of this package <strong class="pkg">GAP</strong> knows about. However, this is deprecated, as it is unreliable in the presence of multiple copies of a package.</p> -<p>Note that when using <code class="code">AutoDocWorksheet</code> (see <a href="chap4_mj.html#X80ED3C2A78146AD1"><span class="RefLink">4.1</span></a>), there is no parameter corresponding to <var class="Arg">packageOrDirectory</var> and so the <q>package directory</q> is always the current directory, and there is no metadata.</p> +<p>Note that when using <code class="code">AutoDocWorksheet</code> (see <a href="chap4_mj.html#X80ED3C2A78146AD1"><span class="RefLink">4.1</span></a>), there is no parameter corresponding to <var class="Arg">pkgdir</var> and so the <q>package directory</q> is always the current directory, and there is no metadata.</p> </dd> <dt><strong class="Mark"><var class="Arg">optrec</var></strong></dt> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/clean new/AutoDoc-2026.05.03/doc/clean --- old/AutoDoc-2026.03.18/doc/clean 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/clean 1970-01-01 01:00:00.000000000 +0100 @@ -1,3 +0,0 @@ -#!/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} _*.xml title.xml Binary files old/AutoDoc-2026.03.18/doc/manual.pdf and new/AutoDoc-2026.05.03/doc/manual.pdf differ diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/manual.six new/AutoDoc-2026.05.03/doc/manual.six --- old/AutoDoc-2026.03.18/doc/manual.six 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/manual.six 2026-05-03 02:00:00.000000000 +0200 @@ -37,47 +37,47 @@ , "X7BFBC6907B26AA95" ], [ "\033[1X\033[33X\033[0;-2YDocumenting code with \033[5XAutoDoc\033[105X\\ -033[101X\027\033[1X\027\033[133X\033[101X", "2.3", [ 2, 3, 0 ], 95, 7, +033[101X\027\033[1X\027\033[133X\033[101X", "2.3", [ 2, 3, 0 ], 97, 7, "documenting code with autodoc", "X87A00EED866E22E8" ], [ "\033[1X\033[33X\033[0;-2YUsing \033[5XAutoDoc\033[105X\033[101X\027\033[1X\ \027 in an existing \033[5XGAPDoc\033[105X\033[101X\027\033[1X\027 manual\033[\ -133X\033[101X", "2.4", [ 2, 4, 0 ], 188, 9, +133X\033[101X", "2.4", [ 2, 4, 0 ], 190, 9, "using autodoc in an existing gapdoc manual", "X7FA614637B807F4D" ], [ "\033[1X\033[33X\033[0;-2YUsing \033[5XAutoDoc\033[105X\033[101X\027\033[1X\ \027 on a complete \033[5XGAPDoc\033[105X\033[101X\027\033[1X\027 manual\033[1\ -33X\033[101X", "2.4-1", [ 2, 4, 1 ], 210, 9, +33X\033[101X", "2.4-1", [ 2, 4, 1 ], 212, 9, "using autodoc on a complete gapdoc manual", "X7F3CEB097AF47C1E" ], [ "\033[1X\033[33X\033[0;-2YSetting different \033[5XGAPDoc\033[105X\033[101X\ -\027\033[1X\027 options\033[133X\033[101X", "2.4-2", [ 2, 4, 2 ], 250, 10, +\027\033[1X\027 options\033[133X\033[101X", "2.4-2", [ 2, 4, 2 ], 252, 10, "setting different gapdoc options", "X7D0DDF2284F2D24A" ], [ "\033[1X\033[33X\033[0;-2YChecklist for converting an existing \033[5XGAPDo\ c\033[105X\033[101X\027\033[1X\027 manual to use \033[5XAutoDoc\033[105X\033[1\ -01X\027\033[1X\027\033[133X\033[101X", "2.4-3", [ 2, 4, 3 ], 362, 11, +01X\027\033[1X\027\033[133X\033[101X", "2.4-3", [ 2, 4, 3 ], 364, 11, "checklist for converting an existing gapdoc manual to use autodoc", "X83448D91868D7994" ], [ "\033[1X\033[33X\033[0;-2YScaffolds\033[133X\033[101X", "2.5", - [ 2, 5, 0 ], 431, 12, "scaffolds", "X8524193D824CDE0D" ], + [ 2, 5, 0 ], 433, 12, "scaffolds", "X8524193D824CDE0D" ], [ "\033[1X\033[33X\033[0;-2YGenerating a title page\033[133X\033[101X", - "2.5-1", [ 2, 5, 1 ], 434, 12, "generating a title page", + "2.5-1", [ 2, 5, 1 ], 436, 12, "generating a title page", "X7CF22DE28478316F" ], [ "\033[1X\033[33X\033[0;-2YGenerating the main XML file\033[133X\033[101X", - "2.5-2", [ 2, 5, 2 ], 485, 13, "generating the main xml file", + "2.5-2", [ 2, 5, 2 ], 487, 13, "generating the main xml file", "X7CD72CC780874FD5" ], [ "\033[1X\033[33X\033[0;-2YWhat data is used from \033[11XPackageInfo.g\033[\ -111X\033[101X\027\033[1X\027?\033[133X\033[101X", "2.5-3", [ 2, 5, 3 ], 512, +111X\033[101X\027\033[1X\027?\033[133X\033[101X", "2.5-3", [ 2, 5, 3 ], 514, 13, "what data is used from packageinfo.g?", "X799956EA85D3FC15" ], [ "\033[1X\033[33X\033[0;-2YEntities from \033[11XPackageInfo.g\033[111X\033[\ 101X\027\033[1X\027 and scaffold options\033[133X\033[101X", "2.5-4", - [ 2, 5, 4 ], 570, 14, "entities from packageinfo.g and scaffold options" + [ 2, 5, 4 ], 572, 14, "entities from packageinfo.g and scaffold options" , "X79EAEF277DD1FAE1" ], [ "\033[1X\033[33X\033[0;-2YWorksheets\033[133X\033[101X", "2.6", - [ 2, 6, 0 ], 587, 15, "worksheets", "X801D4A2F8292704C" ], + [ 2, 6, 0 ], 589, 15, "worksheets", "X801D4A2F8292704C" ], [ "\033[1X\033[33X\033[0;-2Y\033[5XAutoDoc\033[105X\033[101X\027\033[1X\027 d\ ocumentation comments\033[133X\033[101X", "3", [ 3, 0, 0 ], 1, 16, @@ -232,7 +232,7 @@ [ "\033[1X\033[33X\033[0;-2YAutoDoc worksheets\033[133X\033[101X", "4.1", [ 4, 1, 0 ], 4, 30, "autodoc worksheets", "X80ED3C2A78146AD1" ], [ "\033[1X\033[33X\033[0;-2YThe AutoDoc() function\033[133X\033[101X", - "4.2", [ 4, 2, 0 ], 31, 30, "the autodoc function", "X863584DB8497D8BA" + "4.2", [ 4, 2, 0 ], 37, 30, "the autodoc function", "X863584DB8497D8BA" ], [ "Bibliography", "bib", [ "Bib", 0, 0 ], 1, 37, "bibliography", "X7A6F98FD85F02BFE" ], [ "References", "bib", [ "Bib", 0, 0 ], 1, 37, "references", @@ -240,13 +240,13 @@ [ "Index", "ind", [ "Ind", 0, 0 ], 1, 38, "index", "X83A0356F839C696F" ], [ "\033[11Xmakedoc.g\033[111X", "2.2", [ 2, 2, 0 ], 22, 6, "makedoc.g", "X7BFBC6907B26AA95" ], - [ "", "2.4-3", [ 2, 4, 3 ], 362, 11, "", "X83448D91868D7994" ], - [ "", "2.4-3", [ 2, 4, 3 ], 362, 11, "", "X83448D91868D7994" ], - [ "", "2.4-3", [ 2, 4, 3 ], 362, 11, "", "X83448D91868D7994" ], - [ "", "2.4-3", [ 2, 4, 3 ], 362, 11, "", "X83448D91868D7994" ], - [ "", "2.4-3", [ 2, 4, 3 ], 362, 11, "", "X83448D91868D7994" ], - [ "", "2.4-3", [ 2, 4, 3 ], 362, 11, "", "X83448D91868D7994" ], - [ "", "2.4-3", [ 2, 4, 3 ], 362, 11, "", "X83448D91868D7994" ], + [ "", "2.4-3", [ 2, 4, 3 ], 364, 11, "", "X83448D91868D7994" ], + [ "", "2.4-3", [ 2, 4, 3 ], 364, 11, "", "X83448D91868D7994" ], + [ "", "2.4-3", [ 2, 4, 3 ], 364, 11, "", "X83448D91868D7994" ], + [ "", "2.4-3", [ 2, 4, 3 ], 364, 11, "", "X83448D91868D7994" ], + [ "", "2.4-3", [ 2, 4, 3 ], 364, 11, "", "X83448D91868D7994" ], + [ "", "2.4-3", [ 2, 4, 3 ], 364, 11, "", "X83448D91868D7994" ], + [ "", "2.4-3", [ 2, 4, 3 ], 364, 11, "", "X83448D91868D7994" ], [ "\033[10X@Description \033[3Xdescr\033[103X\033[10X\027\033[110X", "3.1-1", [ 3, 1, 1 ], 54, 17, "description descr", "X7F1D85188262A827" ] , [ "\033[10X@Returns \033[3Xret_val\033[103X\033[10X\027\033[110X", @@ -336,8 +336,8 @@ "index key [entry text]", "X82FD2EEB788E76F1" ], [ "\033[2XAutoDocWorksheet\033[102X", "4.1-1", [ 4, 1, 1 ], 7, 30, "autodocworksheet", "X809FE4137C08B28D" ], - [ "\033[2XAutoDoc\033[102X", "4.2-1", [ 4, 2, 1 ], 34, 30, "autodoc", + [ "\033[2XAutoDoc\033[102X", "4.2-1", [ 4, 2, 1 ], 40, 30, "autodoc", "X7CBD8AAF7DCEF352" ], - [ "\033[2XInfoAutoDoc\033[102X", "4.2-2", [ 4, 2, 2 ], 434, 36, + [ "\033[2XInfoAutoDoc\033[102X", "4.2-2", [ 4, 2, 2 ], 443, 36, "infoautodoc", "X81F946A785BA3D6E" ] ] ); diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/doc/title.xml new/AutoDoc-2026.05.03/doc/title.xml --- old/AutoDoc-2026.03.18/doc/title.xml 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/doc/title.xml 2026-05-03 02:00:00.000000000 +0200 @@ -9,7 +9,7 @@ Generate documentation from &GAP; source code </Subtitle> <Version> - 2026.03.18 + 2026.05.03 </Version> <Author> Sebastian Gutsche @@ -36,7 +36,7 @@ <Homepage>https://www.quendi.de/math</Homepage> </Author> <Date> - 18 March 2026 + 3 May 2026 </Date> <Abstract> &AutoDoc; is a &GAP; package whose purpose is to aid &GAP; package authors in creating and maintaining the documentation of their packages. diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/gap/AutoDocMainFunction.gd new/AutoDoc-2026.05.03/gap/AutoDocMainFunction.gd --- old/AutoDoc-2026.03.18/gap/AutoDocMainFunction.gd 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/gap/AutoDocMainFunction.gd 2026-05-03 02:00:00.000000000 +0200 @@ -51,9 +51,11 @@ #! 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 @@ #! <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 -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/gap/AutoDocMainFunction.gi new/AutoDoc-2026.05.03/gap/AutoDocMainFunction.gi --- old/AutoDoc-2026.03.18/gap/AutoDocMainFunction.gi 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/gap/AutoDocMainFunction.gi 2026-05-03 02:00:00.000000000 +0200 @@ -323,37 +323,39 @@ ## InstallGlobalFunction( AutoDocWorksheet, function( arg ) - local autodoc_rec, scaffold_rec; + local opt, val; - if Length( arg ) = 1 then - arg[ 2 ] := rec( ); + if Length( arg ) = 2 then + opt := Remove( arg ); + else + opt := rec( ); fi; - scaffold_rec := ValueOption( "scaffold" ); - if scaffold_rec = fail then - scaffold_rec := rec( ); + val := ValueOption( "scaffold" ); + if val <> fail then + opt.scaffold := val; + elif not IsBound(opt.scaffold) then + opt.scaffold := rec(); fi; - AUTODOC_SetIfMissing( scaffold_rec, "index", false ); + AUTODOC_SetIfMissing( opt.scaffold, "index", false ); - if Length( arg ) = 2 then - autodoc_rec := ValueOption( "autodoc" ); - if autodoc_rec = fail then - autodoc_rec := rec( ); + if Length( arg ) = 1 then + val := ValueOption( "autodoc" ); + if val <> fail then + opt.autodoc := val; + elif not IsBound(opt.autodoc) then + opt.autodoc := rec(); fi; if IsString( arg[ 1 ] ) then arg[ 1 ] := [ arg[ 1 ] ]; fi; - if IsBound( autodoc_rec.files ) then - Append( autodoc_rec.files, arg[ 1 ] ); + if IsBound( opt.autodoc.files ) then + Append( opt.autodoc.files, arg[ 1 ] ); else - autodoc_rec.files := arg[ 1 ]; + opt.autodoc.files := arg[ 1 ]; fi; - AutoDoc( "AutoDocWorksheet", arg[ 2 ] : autodoc := autodoc_rec, scaffold := scaffold_rec ); - fi; - - if Length( arg ) = 0 then - AutoDoc( "AutoDocWorksheet" : scaffold := scaffold_rec ); fi; + AutoDoc_INTERN( true, "AutoDocWorksheet", rec( ), DirectoryCurrent( ), opt ); end ); # The following function is based on code by Alexander Konovalov diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/gap/Magic.gd new/AutoDoc-2026.05.03/gap/Magic.gd --- old/AutoDoc-2026.03.18/gap/Magic.gd 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/gap/Magic.gd 2026-05-03 02:00:00.000000000 +0200 @@ -49,27 +49,29 @@ #! The parameters have the following meanings: #! <List> #! -#! <Mark><A>packageOrDirectory</A></Mark> +#! <Mark><A>pkgdir</A></Mark> #! <Item> -#! The purpose of this parameter is twofold: to determine the package +#! This optional parameter is used 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. If given, it should be +#! an <C>IsDirectory</C> object. If the argument is omitted, then &AutoDoc; +#! checks if it was called from a <F>makedoc.g</F> file or similar, and if so, +#! uses the directory this is contained in. Otherwise 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. #! <P/> +#! For backwards compatibility, it is also possible to pass a package name +#! as this argument, which then is resolved to the package directory of +#! the first instance of this package &GAP; knows about. However, this is +#! deprecated, as it is unreliable in the presence of multiple copies of a +#! package. +#! <P/> #! Note that when using <C>AutoDocWorksheet</C> (see #! <Ref Sect='Section_AutoDocWorksheet'/>), there is -#! no parameter corresponding to <A>packageOrDirectory</A> and so the +#! no parameter corresponding to <A>pkgdir</A> and so the #! <Q>package directory</Q> is always the current directory, and #! there is no metadata. #! </Item> @@ -461,9 +463,11 @@ #! <Ref Func="AutoDoc"/> call inside <F>makedoc.g</F>. #! #! @Returns nothing -#! @Arguments [packageOrDirectory], [optrec] +#! @Arguments [pkgdir], [optrec] DeclareGlobalFunction( "AutoDoc" ); +DeclareGlobalFunction( "AutoDoc_INTERN" ); + #! @Description #! Info class for the <Package>AutoDoc</Package> package. Set this to #! 0 to suppress info messages, 1 to allow most messages, and 2 to allow all diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/gap/Magic.gi new/AutoDoc-2026.05.03/gap/Magic.gi --- old/AutoDoc-2026.03.18/gap/Magic.gi 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/gap/Magic.gi 2026-05-03 02:00:00.000000000 +0200 @@ -8,13 +8,8 @@ # InstallGlobalFunction( AutoDoc, function( arg ) - local pkgname, pkginfo, pkgdir, - opt, scaffold, gapdoc, extract_examples, autodoc, i, - doc_dir, doc_dir_rel, tmp, key, val, file, - pkgdirstr, docdirstr, - title_page, tree, is_worksheet, - position_document_class, - args; + local pkgname, pkginfo, pkgdir, opt, file, + input_filename, path_positions; if Length( arg ) >= 3 then Error( "too many arguments" ); @@ -29,9 +24,24 @@ # check the first argument if Length(arg) = 0 then - pkgdir := DirectoryCurrent( ); + input_filename := INPUT_FILENAME(); + if IsString( input_filename ) and + input_filename <> "*stdin*" and + IsReadableFile( input_filename ) then + path_positions := PositionsProperty( input_filename, x -> x = '/' ); + if IsEmpty( path_positions ) then + pkgdir := DirectoryCurrent( ); + else + pkgdir := Directory( + input_filename{ [ 1 .. Last( path_positions ) - 1 ] } + ); + fi; + else + pkgdir := DirectoryCurrent( ); + fi; elif IsString( arg[1] ) then pkgname := Remove( arg, 1 ); + Print("#W AutoDoc: passing pkgname as first argument to AutoDoc is deprecated"); elif IsDirectory( arg[1] ) then pkgdir := Remove( arg, 1 ); fi; @@ -42,7 +52,6 @@ fi; if IsBound( pkgdir ) then - is_worksheet := false; file := Filename( pkgdir, "PackageInfo.g" ); if not IsExistingFile( file ) then Error( "no package name given and no PackageInfo.g file found" ); @@ -60,14 +69,7 @@ fi; pkgname := pkginfo.PackageName; - elif pkgname = "AutoDocWorksheet" then - # For internal use only -- for details, refer to the AutoDocWorksheet() function. - is_worksheet := true; - pkginfo := rec( ); - pkgdir := DirectoryCurrent( ); - else - is_worksheet := false; pkginfo := PackageInfo( pkgname ); if IsEmpty( pkginfo ) then Error( "Could not find package ", pkgname ); @@ -78,17 +80,35 @@ pkgdir := Directory( pkginfo.InstallationPath ); fi; + return AutoDoc_INTERN( false, pkgname, pkginfo, pkgdir, opt ); +end ); + +InstallGlobalFunction( AutoDoc_INTERN, +function( is_worksheet, pkgname, pkginfo, pkgdir, opt ) + local scaffold, gapdoc, extract_examples, autodoc, i, + doc_dir, doc_dir_rel, tmp, key, val, file, + pkgdirstr, docdirstr, + title_page, tree, + position_document_class, + args, used_legacy_value_options; + # - # Check for user supplied options. If present, they take - # precedence over any defaults as well as the opt record. + # Deprecated feature: Check for user supplied global options. If present, + # they take precedence over any defaults as well as the opt record. # + 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; od; + if used_legacy_value_options then + Print("#W passing options via GAP's global options system is deprecated; use an option record instead\n"); + fi; + # # Setup the output directory # diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/tst/autodoctest-manual.tst new/AutoDoc-2026.05.03/tst/autodoctest-manual.tst --- old/AutoDoc-2026.03.18/tst/autodoctest-manual.tst 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/tst/autodoctest-manual.tst 2026-05-03 02:00:00.000000000 +0200 @@ -35,6 +35,12 @@ > makedoc := "makedoc.g", > doc_expected := "tst/manual.expected", > ) ); +gap> AUTODOC_RunPackageScenario( pkgdir, olddir, rec( +> name := "manual-parent-relative", +> makedoc := "../../makedoc.g", +> workdir := "doc/build", +> doc_expected := "tst/manual.expected", +> ) ); # entities option variants gap> AUTODOC_RunPackageScenario( pkgdir, olddir, rec( diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/tst/manual.expected/_Chapter_Reference.xml new/AutoDoc-2026.05.03/tst/manual.expected/_Chapter_Reference.xml --- old/AutoDoc-2026.03.18/tst/manual.expected/_Chapter_Reference.xml 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/tst/manual.expected/_Chapter_Reference.xml 2026-05-03 02:00:00.000000000 +0200 @@ -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> @@ -37,7 +45,7 @@ <Heading>The AutoDoc() function</Heading> <ManSection> - <Func Arg="[packageOrDirectory], [optrec]" Name="AutoDoc" /> + <Func Arg="[pkgdir], [optrec]" Name="AutoDoc" /> <Returns>nothing </Returns> <Description> @@ -79,27 +87,29 @@ <P/> The parameters have the following meanings: <List> - <Mark><A>packageOrDirectory</A></Mark> + <Mark><A>pkgdir</A></Mark> <Item> - The purpose of this parameter is twofold: to determine the package + This optional parameter is used 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. If given, it should be + an <C>IsDirectory</C> object. If the argument is omitted, then &AutoDoc; + checks if it was called from a <F>makedoc.g</F> file or similar, and if so, + uses the directory this is contained in. Otherwise 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. <P/> + For backwards compatibility, it is also possible to pass a package name + as this argument, which then is resolved to the package directory of + the first instance of this package &GAP; knows about. However, this is + deprecated, as it is unreliable in the presence of multiple copies of a + package. + <P/> Note that when using <C>AutoDocWorksheet</C> (see <Ref Sect='Section_AutoDocWorksheet'/>), there is - no parameter corresponding to <A>packageOrDirectory</A> and so the + no parameter corresponding to <A>pkgdir</A> and so the <Q>package directory</Q> is always the current directory, and there is no metadata. </Item> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/tst/manual.expected/_Chapter_Tutorials.xml new/AutoDoc-2026.05.03/tst/manual.expected/_Chapter_Tutorials.xml --- old/AutoDoc-2026.03.18/tst/manual.expected/_Chapter_Tutorials.xml 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/tst/manual.expected/_Chapter_Tutorials.xml 2026-05-03 02:00:00.000000000 +0200 @@ -38,15 +38,16 @@ <P/> Suppose your package is already up and running, but so far has no manual. Then you can rapidly generate a <Q>scaffold</Q> for a package manual -using the <Ref Func="AutoDoc"/> command like this, -while running &GAP; from within your package's directory (the -one containing the <F>PackageInfo.g</F> file): +using the <Ref Func="AutoDoc"/> command like this: <Listing><![CDATA[ LoadPackage( "AutoDoc" ); AutoDoc( rec( scaffold := true ) ); ]]></Listing> -This first reads the <F>PackageInfo.g</F> file from the current -directory. It extracts information about the package from it +When called from a file such as <F>makedoc.g</F>, &AutoDoc; uses the +directory containing that file as the package directory. Otherwise, it +falls back to the current directory. In either case it then reads the +<F>PackageInfo.g</F> file from that package 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/_main.xml</F> and <F>doc/title.xml</F> inside the package directory. Finally, it runs @@ -99,7 +100,7 @@ QUIT; ]]></Listing> Then you can regenerate the package manual from the command line with the -following command, executed from within the package directory: +following command: <Listing><![CDATA[ gap makedoc.g ]]></Listing> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/tst/manual.expected/_entities.xml new/AutoDoc-2026.05.03/tst/manual.expected/_entities.xml --- old/AutoDoc-2026.03.18/tst/manual.expected/_entities.xml 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/tst/manual.expected/_entities.xml 2026-05-03 02:00:00.000000000 +0200 @@ -1,6 +1,6 @@ <!ENTITY AutoDoc '<Package>AutoDoc</Package>'> <!ENTITY PackageName '<Package>PackageName</Package>'> -<!ENTITY RELEASEDATE '18 March 2026'> +<!ENTITY RELEASEDATE '3 May 2026'> <!ENTITY RELEASEYEAR '2026'> -<!ENTITY VERSION '2026.03.18'> +<!ENTITY VERSION '2026.05.03'> <!ENTITY io '<Package>io</Package>'> diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/tst/manual.expected/title.xml new/AutoDoc-2026.05.03/tst/manual.expected/title.xml --- old/AutoDoc-2026.03.18/tst/manual.expected/title.xml 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/tst/manual.expected/title.xml 2026-05-03 02:00:00.000000000 +0200 @@ -9,7 +9,7 @@ Generate documentation from &GAP; source code </Subtitle> <Version> - 2026.03.18 + 2026.05.03 </Version> <Author> Sebastian Gutsche @@ -36,7 +36,7 @@ <Homepage>https://www.quendi.de/math</Homepage> </Author> <Date> - 18 March 2026 + 3 May 2026 </Date> <Abstract> &AutoDoc; is a &GAP; package whose purpose is to aid &GAP; package authors in creating and maintaining the documentation of their packages. diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/AutoDoc-2026.03.18/tst/utils.g new/AutoDoc-2026.05.03/tst/utils.g --- old/AutoDoc-2026.03.18/tst/utils.g 2026-03-18 23:56:19.000000000 +0100 +++ new/AutoDoc-2026.05.03/tst/utils.g 2026-05-03 02:00:00.000000000 +0200 @@ -7,6 +7,7 @@ # olddir caller's original working directory, restored on exit # scenario record describing the scenario to run; it must contain # `name` and `makedoc`, and may additionally specify: +# - `workdir := "subdir"` to run Read(makedoc) from a nested cwd # - `stub_gapdoc := true` to skip the expensive GAPDoc post-pass # - `doc_expected := "tst/...expected"` for full doc-file diffs # - `tst_expected := "tst/...expected"` for extracted-test diffs @@ -16,7 +17,7 @@ local tempdir, docdir, tstdir, ex_dir, files, expected, actual, old_makegapdocdoc, old_copyhtmlstylefiles, old_manuallab, old_autodoc_level, old_gapdoc_level, old_warning_level, f, - source_doc_files, source_tst_files; + source_doc_files, source_tst_files, workdir; tempdir := Filename( DirectoryTemporary(), @@ -88,6 +89,11 @@ SetInfoLevel( InfoAutoDoc, 0 ); SetInfoLevel( InfoGAPDoc, 0 ); SetInfoLevel( InfoWarning, 0 ); + if IsBound( scenario.workdir ) then + workdir := Filename( Directory( tempdir ), scenario.workdir ); + AUTODOC_CreateDirIfMissing( workdir ); + ChangeDirectoryCurrent( workdir ); + fi; Read( scenario.makedoc : nopdf ); SetInfoLevel( InfoAutoDoc, old_autodoc_level ); SetInfoLevel( InfoGAPDoc, old_gapdoc_level ); ++++++ _scmsync.obsinfo ++++++ --- /var/tmp/diff_new_pack.XEWqlz/_old 2026-05-04 14:42:07.494517061 +0200 +++ /var/tmp/diff_new_pack.XEWqlz/_new 2026-05-04 14:42:07.498517225 +0200 @@ -1,5 +1,5 @@ -mtime: 1773875290 -commit: c3dde868af11c2efbe07886a61c7eae738706032b86aa4bee02632ba4af0e1f2 +mtime: 1777888198 +commit: 90e347ac434906e21df30a6ce872e0517b95e78a89835b938d4877d673ff52a5 url: https://src.opensuse.org/jengelh/gap-autodoc revision: master ++++++ build.specials.obscpio ++++++ ++++++ build.specials.obscpio ++++++ diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn' '--exclude=.svnignore' old/.gitignore new/.gitignore --- old/.gitignore 1970-01-01 01:00:00.000000000 +0100 +++ new/.gitignore 2026-05-04 11:49:58.000000000 +0200 @@ -0,0 +1 @@ +.osc
