2.2-21 @NotLatex text
, @BeginNotLatex
, and @EndNotLatex
+
2.2-17 @NotLatex text
, @BeginNotLatex
, and @EndNotLatex
+
3 AutoDoc worksheets
3.1 Worksheets
diff -Nru gap-autodoc-2019.05.20/doc/chap0_mj.html gap-autodoc-2019.09.04/doc/chap0_mj.html
--- gap-autodoc-2019.05.20/doc/chap0_mj.html 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chap0_mj.html 2020-03-02 09:35:41.000000000 +0000
@@ -32,10 +32,10 @@
Generate documentation from GAP source code
- 2019.05.20
+ 2019.09.04
- 20 May 2019
+ 4 September 2019
@@ -139,43 +139,35 @@
2.2-2 @Section name
-
2.2-3 @EndSection
+
2.2-3 @Subsection name
-
2.2-4 @Subsection name
+
2.2-4 @BeginGroup [grpname]
-
2.2-5 @EndSubsection
+
2.2-5 @EndGroup
-
2.2-6 @BeginAutoDoc
+
2.2-6 @GroupTitle title
-
2.2-7 @EndAutoDoc
+
2.2-7 @Level lvl
-
2.2-8 @BeginGroup [grpname]
+
2.2-8 @ResetLevel
-
2.2-9 @EndGroup
+
2.2-9 @BeginExample
and @EndExample
-
2.2-10 @Level lvl
+
2.2-10 @BeginExampleSession
and @EndExampleSession
-
2.2-11 @ResetLevel
+
2.2-11 @BeginLog
and @EndLog
-
2.2-12 @BeginExample
and @EndExample
+
2.2-12 @BeginLogSession
and @EndLogSession
-
2.2-13 @BeginExampleSession
and @EndExampleSession
+
2.2-13 @DoNotReadRestOfFile
-
2.2-14 @BeginLog
and @EndLog
+
2.2-14 @BeginChunk name
, @EndChunk
, and @InsertChunk name
-
2.2-15 @BeginLogSession
and @EndLogSession
+
2.2-15 @BeginCode name
, @EndCode, and @InsertCode name
-
2.2-16 @DoNotReadRestOfFile
+
2.2-16 @LatexOnly text
, @BeginLatexOnly
, and @EndLatexOnly
-
2.2-17 @BeginChunk name
, @EndChunk
, and @InsertChunk name
-
-
2.2-18 @BeginSystem name
, @EndSystem
, and @InsertSystem name
-
-
2.2-19 @BeginCode name
, @EndCode, and @InsertCode name
-
-
2.2-20 @LatexOnly text
, @BeginLatexOnly
, and @EndLatexOnly
-
-
2.2-21 @NotLatex text
, @BeginNotLatex
, and @EndNotLatex
+
2.2-17 @NotLatex text
, @BeginNotLatex
, and @EndNotLatex
+
3 AutoDoc worksheets
3.1 Worksheets
diff -Nru gap-autodoc-2019.05.20/doc/chap0.txt gap-autodoc-2019.09.04/doc/chap0.txt
--- gap-autodoc-2019.05.20/doc/chap0.txt 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chap0.txt 2020-03-02 09:35:41.000000000 +0000
@@ -6,10 +6,10 @@
[1X Generate documentation from [5XGAP[105X source code [101X
- 2019.05.20
+ 2019.09.04
- 20 May 2019
+ 4 September 2019
Sebastian Gutsche
@@ -88,35 +88,32 @@
2.2 [33X[0;0YOther documentation comments[133X
2.2-1 [33X[0;0Y[10X@Chapter [3Xname[103X[10X[110X[133X
2.2-2 [33X[0;0Y[10X@Section [3Xname[103X[10X[110X[133X
- 2.2-3 [33X[0;0Y[10X@EndSection[110X[133X
- 2.2-4 [33X[0;0Y[10X@Subsection [3Xname[103X[10X[110X[133X
- 2.2-5 [33X[0;0Y[10X@EndSubsection[110X[133X
- 2.2-6 [33X[0;0Y[10X@BeginAutoDoc[110X[133X
- 2.2-7 [33X[0;0Y[10X@EndAutoDoc[110X[133X
- 2.2-8 [33X[0;0Y[10X@BeginGroup [3X[grpname][103X[10X[110X[133X
- 2.2-9 [33X[0;0Y[10X@EndGroup[110X[133X
- 2.2-10 [33X[0;0Y[10X@Level [3Xlvl[103X[10X[110X[133X
- 2.2-11 [33X[0;0Y[10X@ResetLevel[110X[133X
- 2.2-12 [33X[0;0Y[10X@BeginExample[110X and [10X@EndExample[110X[133X
- 2.2-13 [33X[0;0Y[10X@BeginExampleSession[110X and [10X@EndExampleSession[110X[133X
- 2.2-14 [33X[0;0Y[10X@BeginLog[110X and [10X@EndLog[110X[133X
- 2.2-15 [33X[0;0Y[10X@BeginLogSession[110X and [10X@EndLogSession[110X[133X
- 2.2-16 [33X[0;0Y[10X@DoNotReadRestOfFile[110X[133X
- 2.2-17 [33X[0;0Y[10X@BeginChunk [3Xname[103X[10X[110X, [10X@EndChunk[110X, and [10X@InsertChunk [3Xname[103X[10X[110X[133X
- 2.2-18 [33X[0;0Y[10X@BeginSystem [3Xname[103X[10X[110X, [10X@EndSystem[110X, and [10X@InsertSystem [3Xname[103X[10X[110X[133X
- 2.2-19 [33X[0;0Y[10X@BeginCode [3Xname[103X[10X[110X, @EndCode, and [10X@InsertCode [3Xname[103X[10X[110X[133X
- 2.2-20 [33X[0;0Y[10X@LatexOnly [3Xtext[103X[10X[110X, [10X@BeginLatexOnly[110X, and [10X@EndLatexOnly[110X[133X
- 2.2-21 [33X[0;0Y[10X@NotLatex [3Xtext[103X[10X[110X, [10X@BeginNotLatex[110X, and [10X@EndNotLatex[110X[133X
+ 2.2-3 [33X[0;0Y[10X@Subsection [3Xname[103X[10X[110X[133X
+ 2.2-4 [33X[0;0Y[10X@BeginGroup [3X[grpname][103X[10X[110X[133X
+ 2.2-5 [33X[0;0Y[10X@EndGroup[110X[133X
+ 2.2-6 [33X[0;0Y@GroupTitle [3Xtitle[103X[133X
+ 2.2-7 [33X[0;0Y[10X@Level [3Xlvl[103X[10X[110X[133X
+ 2.2-8 [33X[0;0Y[10X@ResetLevel[110X[133X
+ 2.2-9 [33X[0;0Y[10X@BeginExample[110X and [10X@EndExample[110X[133X
+ 2.2-10 [33X[0;0Y[10X@BeginExampleSession[110X and [10X@EndExampleSession[110X[133X
+ 2.2-11 [33X[0;0Y[10X@BeginLog[110X and [10X@EndLog[110X[133X
+ 2.2-12 [33X[0;0Y[10X@BeginLogSession[110X and [10X@EndLogSession[110X[133X
+ 2.2-13 [33X[0;0Y[10X@DoNotReadRestOfFile[110X[133X
+ 2.2-14 [33X[0;0Y[10X@BeginChunk [3Xname[103X[10X[110X, [10X@EndChunk[110X, and [10X@InsertChunk [3Xname[103X[10X[110X[133X
+ 2.2-15 [33X[0;0Y[10X@BeginCode [3Xname[103X[10X[110X, @EndCode, and [10X@InsertCode [3Xname[103X[10X[110X[133X
+ 2.2-16 [33X[0;0Y[10X@LatexOnly [3Xtext[103X[10X[110X, [10X@BeginLatexOnly[110X, and [10X@EndLatexOnly[110X[133X
+ 2.2-17 [33X[0;0Y[10X@NotLatex [3Xtext[103X[10X[110X, [10X@BeginNotLatex[110X, and [10X@EndNotLatex[110X[133X
2.3 [33X[0;0YTitle page commands[133X
2.4 [33X[0;0YPlain text files[133X
2.5 [33X[0;0YGrouping[133X
- 2.5-1 FirstOperation
+ 2.5-1 [33X[0;0YA family of operations[133X
2.6 [33X[0;0YLevel[133X
2.7 [33X[0;0YMarkdown-like formatting of text in [5XAutoDoc[105X[133X
2.7-1 [33X[0;0YLists[133X
2.7-2 [33X[0;0YMath modes[133X
2.7-3 [33X[0;0YEmphasize[133X
2.7-4 [33X[0;0YInline code[133X
+ 2.8 [33X[0;0YDeprecated commands[133X
3 [33X[0;0YAutoDoc worksheets[133X
3.1 [33X[0;0YWorksheets[133X
3.1-1 AutoDocWorksheet
diff -Nru gap-autodoc-2019.05.20/doc/chap1.html gap-autodoc-2019.09.04/doc/chap1.html
--- gap-autodoc-2019.05.20/doc/chap1.html 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chap1.html 2020-03-02 09:35:41.000000000 +0000
@@ -57,7 +57,7 @@
1 Getting started using AutoDoc
-AutoDoc is a GAP package which is meant to aid GAP package authors in creating and maintaining the documentation of their packages. In this capacity it builds upon GAPDoc, and is not a replacement for GAPDoc, but rather complements it.
+AutoDoc is a GAP package which is meant to aid GAP package authors in creating and maintaining the documentation of their packages. In this capacity it builds upon the GAPDoc package (see https://www.gap-system.org/Packages/gapdoc.html). As such, it is not a replacement for GAPDoc, but rather complements it.
In this chapter we describe how to get started using AutoDoc for your package. First, we explain in Section 1.1 how to write a new package manual from scratch.
@@ -97,7 +97,7 @@
Congratulations, your package now has a minimal working manual. Of course it will be mostly empty for now, but it already should contain some useful information, based on the data in your PackageInfo.g
. This includes your package's name, version and description as well as information about its authors. And if you ever change the package data, (e.g. because your email address changed), just re-run the above command to regenerate the two main XML files with the latest information.
-Next of course you need to provide actual content (unfortunately, we were not yet able to automate that for you, more research on artificial intelligence is required). To add more content, you have several options: You could add further GAPDoc XML files containing extra chapters, sections and so on. Or you could use classic GAPDoc source comments (in either case, see Section 1.3 on how to teach the AutoDoc
(4.1-1) command to include this extra documentation). Or you could use the special documentation facilities AutoDoc provides (see Section 1.2).
+Next of course you need to provide actual content (unfortunately, we were not yet able to automate that for you, more research on artificial intelligence is required). To add more content, you have several options: You could add further GAPDoc XML files containing extra chapters, sections and so on. Or you could use classic GAPDoc source comments. For details on either, please refer to GAPDoc: Distributing a Document into Several Files, as well as Section 1.3 of this manual on how to teach the AutoDoc
(4.1-1) command to include this extra documentation. Or you could use the special documentation facilities AutoDoc provides (see Section 1.2).
You will probably want to re-run the AutoDoc
(4.1-1) command frequently, e.g. whenever you modified your documentation or your PackageInfo.g
. To make this more convenient and reproducible, we recommend putting its invocation into a file makedoc.g
in your package directory, with content based on the following example:
@@ -154,7 +154,7 @@
-#Include SYSTEM "_AutoDocMainFile.xml"
+<#Include SYSTEM "_AutoDocMainFile.xml">
in a suitable place. This means that you can mix AutoDoc documentation comment freely with your existing documentation; you can even still make use of any existing GAPDoc documentation comments in your code. The following command should be useful for you in this case; it still scans the package code for AutoDoc documentation comments and the runs GAPDoc to produce HTML and PDF output, but does not touch your documentation XML files otherwise.
@@ -181,7 +181,7 @@
1.3-1 Using AutoDoc on a complete GAPDoc manual
-Suppose you already have a complete XML manual, with some main and title XML files and some documentation for operations distributed over all your .g
, .gd
, and .gi
files. Suppose the main XML file is named PACKAGENAME.xml
and is in the /doc
subdirectory of your package. Then you can rebuild your manual by executing the following two GAP commands from a GAP sessions started started in the root directory of your package:
+Suppose you already have a complete XML manual, with some main and title XML files and some documentation for operations distributed over all your .g
, .gd
, and .gi
files. Suppose the main XML file is named PACKAGENAME.xml
and is in the /doc
subdirectory of your package. Then you can rebuild your manual by executing the following two GAP commands from a GAP sessions started started in the root directory of your package:
@@ -453,7 +453,7 @@
#! @EndExample
-Now, one can create a PDF and HTML document, like a package documentation out of it. Suppose the document above is saved as worksheet.g
. Then, when GAP is started in the directory of this file, the command
+Now, one can create a PDF and HTML document, like a package documentation out of it. Suppose the document above is saved as worksheet.g
. Then, when GAP is started in the directory of this file, the command
diff -Nru gap-autodoc-2019.05.20/doc/chap1_mj.html gap-autodoc-2019.09.04/doc/chap1_mj.html
--- gap-autodoc-2019.05.20/doc/chap1_mj.html 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chap1_mj.html 2020-03-02 09:35:41.000000000 +0000
@@ -60,7 +60,7 @@
1 Getting started using AutoDoc
-AutoDoc is a GAP package which is meant to aid GAP package authors in creating and maintaining the documentation of their packages. In this capacity it builds upon GAPDoc, and is not a replacement for GAPDoc, but rather complements it.
+AutoDoc is a GAP package which is meant to aid GAP package authors in creating and maintaining the documentation of their packages. In this capacity it builds upon the GAPDoc package (see https://www.gap-system.org/Packages/gapdoc.html). As such, it is not a replacement for GAPDoc, but rather complements it.
In this chapter we describe how to get started using AutoDoc for your package. First, we explain in Section 1.1 how to write a new package manual from scratch.
@@ -100,7 +100,7 @@
Congratulations, your package now has a minimal working manual. Of course it will be mostly empty for now, but it already should contain some useful information, based on the data in your PackageInfo.g
. This includes your package's name, version and description as well as information about its authors. And if you ever change the package data, (e.g. because your email address changed), just re-run the above command to regenerate the two main XML files with the latest information.
-Next of course you need to provide actual content (unfortunately, we were not yet able to automate that for you, more research on artificial intelligence is required). To add more content, you have several options: You could add further GAPDoc XML files containing extra chapters, sections and so on. Or you could use classic GAPDoc source comments (in either case, see Section 1.3 on how to teach the AutoDoc
(4.1-1) command to include this extra documentation). Or you could use the special documentation facilities AutoDoc provides (see Section 1.2).
+Next of course you need to provide actual content (unfortunately, we were not yet able to automate that for you, more research on artificial intelligence is required). To add more content, you have several options: You could add further GAPDoc XML files containing extra chapters, sections and so on. Or you could use classic GAPDoc source comments. For details on either, please refer to GAPDoc: Distributing a Document into Several Files, as well as Section 1.3 of this manual on how to teach the AutoDoc
(4.1-1) command to include this extra documentation. Or you could use the special documentation facilities AutoDoc provides (see Section 1.2).
You will probably want to re-run the AutoDoc
(4.1-1) command frequently, e.g. whenever you modified your documentation or your PackageInfo.g
. To make this more convenient and reproducible, we recommend putting its invocation into a file makedoc.g
in your package directory, with content based on the following example:
@@ -157,7 +157,7 @@
-#Include SYSTEM "_AutoDocMainFile.xml"
+<#Include SYSTEM "_AutoDocMainFile.xml">
in a suitable place. This means that you can mix AutoDoc documentation comment freely with your existing documentation; you can even still make use of any existing GAPDoc documentation comments in your code. The following command should be useful for you in this case; it still scans the package code for AutoDoc documentation comments and the runs GAPDoc to produce HTML and PDF output, but does not touch your documentation XML files otherwise.
@@ -184,7 +184,7 @@
1.3-1 Using AutoDoc on a complete GAPDoc manual
-Suppose you already have a complete XML manual, with some main and title XML files and some documentation for operations distributed over all your .g
, .gd
, and .gi
files. Suppose the main XML file is named PACKAGENAME.xml
and is in the /doc
subdirectory of your package. Then you can rebuild your manual by executing the following two GAP commands from a GAP sessions started started in the root directory of your package:
+Suppose you already have a complete XML manual, with some main and title XML files and some documentation for operations distributed over all your .g
, .gd
, and .gi
files. Suppose the main XML file is named PACKAGENAME.xml
and is in the /doc
subdirectory of your package. Then you can rebuild your manual by executing the following two GAP commands from a GAP sessions started started in the root directory of your package:
@@ -456,7 +456,7 @@
#! @EndExample
-Now, one can create a PDF and HTML document, like a package documentation out of it. Suppose the document above is saved as worksheet.g
. Then, when GAP is started in the directory of this file, the command
+Now, one can create a PDF and HTML document, like a package documentation out of it. Suppose the document above is saved as worksheet.g
. Then, when GAP is started in the directory of this file, the command
diff -Nru gap-autodoc-2019.05.20/doc/chap1.txt gap-autodoc-2019.09.04/doc/chap1.txt
--- gap-autodoc-2019.05.20/doc/chap1.txt 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chap1.txt 2020-03-02 09:35:41.000000000 +0000
@@ -3,8 +3,9 @@
[33X[0;0Y[5XAutoDoc[105X is a [5XGAP[105X package which is meant to aid [5XGAP[105X package authors in
creating and maintaining the documentation of their packages. In this
- capacity it builds upon [5XGAPDoc[105X, and is not a replacement for [5XGAPDoc[105X, but
- rather complements it.[133X
+ capacity it builds upon the [5XGAPDoc[105X package (see
+ [7Xhttps://www.gap-system.org/Packages/gapdoc.html[107X). As such, it is not a
+ replacement for [5XGAPDoc[105X, but rather complements it.[133X
[33X[0;0YIn this chapter we describe how to get started using [5XAutoDoc[105X for your
package. First, we explain in Section [14X1.1[114X how to write a new package manual
@@ -65,10 +66,11 @@
not yet able to automate [13Xthat[113X for you, more research on artificial
intelligence is required). To add more content, you have several options:
You could add further [5XGAPDoc[105X XML files containing extra chapters, sections
- and so on. Or you could use classic [5XGAPDoc[105X source comments (in either case,
- see Section [14X1.3[114X on how to teach the [2XAutoDoc[102X ([14X4.1-1[114X) command to include this
- extra documentation). Or you could use the special documentation facilities
- [5XAutoDoc[105X provides (see Section [14X1.2[114X).[133X
+ and so on. Or you could use classic [5XGAPDoc[105X source comments. For details on
+ either, please refer to [14X'GAPDoc: Distributing a Document into Several
+ Files'[114X, as well as Section [14X1.3[114X of this manual on how to teach the [2XAutoDoc[102X
+ ([14X4.1-1[114X) command to include this extra documentation. Or you could use the
+ special documentation facilities [5XAutoDoc[105X provides (see Section [14X1.2[114X).[133X
[33X[0;0YYou will probably want to re-run the [2XAutoDoc[102X ([14X4.1-1[114X) command frequently,
e.g. whenever you modified your documentation or your [11XPackageInfo.g[111X. To make
@@ -134,7 +136,7 @@
your documentation, and insert the line[133X
[4X[32X[104X
- [4X#Include SYSTEM "_AutoDocMainFile.xml"[104X
+ [4X<#Include SYSTEM "_AutoDocMainFile.xml">[104X
[4X[32X[104X
[33X[0;0Yin a suitable place. This means that you can mix [5XAutoDoc[105X documentation
@@ -173,7 +175,7 @@
files and some documentation for operations distributed over all your [11X.g[111X,
[11X.gd[111X, and [11X.gi[111X files. Suppose the main XML file is named [11XPACKAGENAME.xml[111X and
is in the [11X/doc[111X subdirectory of your package. Then you can rebuild your
- manual by executing the following two GAP commands from a GAP sessions
+ manual by executing the following two [5XGAP[105X commands from a [5XGAP[105X sessions
started started in the root directory of your package:[133X
[4X[32X[104X
@@ -490,7 +492,7 @@
[33X[0;0YNow, one can create a PDF and HTML document, like a package documentation
out of it. Suppose the document above is saved as [11Xworksheet.g[111X. Then, when
- GAP is started in the directory of this file, the command[133X
+ [5XGAP[105X is started in the directory of this file, the command[133X
[4X[32X[104X
[4XAutoDocWorksheet( "worksheet.g" );[104X
diff -Nru gap-autodoc-2019.05.20/doc/chap2.html gap-autodoc-2019.09.04/doc/chap2.html
--- gap-autodoc-2019.05.20/doc/chap2.html 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chap2.html 2020-03-02 09:35:41.000000000 +0000
@@ -47,43 +47,35 @@
2.2-2 @Section name
-
2.2-3 @EndSection
+
2.2-3 @Subsection name
-
2.2-4 @Subsection name
+
2.2-4 @BeginGroup [grpname]
-
2.2-5 @EndSubsection
+
2.2-5 @EndGroup
-
2.2-6 @BeginAutoDoc
+
2.2-6 @GroupTitle title
-
2.2-7 @EndAutoDoc
+
2.2-7 @Level lvl
-
2.2-8 @BeginGroup [grpname]
+
2.2-8 @ResetLevel
-
2.2-9 @EndGroup
+
2.2-9 @BeginExample
and @EndExample
-
2.2-10 @Level lvl
+
2.2-10 @BeginExampleSession
and @EndExampleSession
-
2.2-11 @ResetLevel
+
2.2-11 @BeginLog
and @EndLog
-
2.2-12 @BeginExample
and @EndExample
+
2.2-12 @BeginLogSession
and @EndLogSession
-
2.2-13 @BeginExampleSession
and @EndExampleSession
+
2.2-13 @DoNotReadRestOfFile
-
2.2-14 @BeginLog
and @EndLog
+
2.2-14 @BeginChunk name
, @EndChunk
, and @InsertChunk name
-
2.2-15 @BeginLogSession
and @EndLogSession
+
2.2-15 @BeginCode name
, @EndCode, and @InsertCode name
-
2.2-16 @DoNotReadRestOfFile
+
2.2-16 @LatexOnly text
, @BeginLatexOnly
, and @EndLatexOnly
-
2.2-17 @BeginChunk name
, @EndChunk
, and @InsertChunk name
-
-
2.2-18 @BeginSystem name
, @EndSystem
, and @InsertSystem name
-
-
2.2-19 @BeginCode name
, @EndCode, and @InsertCode name
-
-
2.2-20 @LatexOnly text
, @BeginLatexOnly
, and @EndLatexOnly
-
-
2.2-21 @NotLatex text
, @BeginNotLatex
, and @EndNotLatex
+
2.2-17 @NotLatex text
, @BeginNotLatex
, and @EndNotLatex
+
2 AutoDoc documentation comments
@@ -217,7 +213,7 @@
#! @Returns a list
#! @Arguments modtbl
#! @Group CharacterDegreesOfBlocks
-#! @FunctionLabel chardegblocks
+#! @Label chardegblocks
#! @ChapterInfo Blocks, Attributes
DeclareAttribute( "CharacterDegreesOfBlocks",
IsBrauerTable );
@@ -267,15 +263,9 @@
The @SectionLabel
label command can be used to set the label of the section to Section_
label instead of Chapter_chaptername_Section_
name. The @SectionTitle
title command can be used to set a heading for the section that is different from name.
-
-
-
2.2-3 @EndSection
-
-
This command is deprecated. You can simply remove any use of it.
-
-
2.2-4 @Subsection name
+
2.2-3 @Subsection name
Sets an active subsection like @Section
sets an active section. The subsection automatically ends with the next @Subsection
, @Section
or @Chapter
command. It also ends with the next documented function. Indeed, internally each function "manpage" is treated like a subsection.
@@ -287,40 +277,9 @@
The @SubsectionLabel
label command can be used to set the label of the subsection to Subsection_
label instead of Chapter_chaptername_Section_sectionname_Subsection_
name. The @SubsectionTitle
title command can be used to set a heading for the subsection that is different from name.
-
-
-
2.2-5 @EndSubsection
-
-
This command is deprecated. You can simply remove any use of it.
-
-
-
-
2.2-6 @BeginAutoDoc
-
-
Causes all subsequent declarations to be documented in the manual, regardless of whether they have an AutoDoc comment in front of them or not.
-
-
-
-
2.2-7 @EndAutoDoc
-
-
Ends the effect of @BeginAutoDoc
. So from here on, again only declarations with an explicit AutoDoc comment in front are added to the manual.
-
-
-
-#! @BeginAutoDoc
-
-DeclareOperation( "Operation1", [ IsList ] );
-
-DeclareProperty( "IsProperty", IsList );
-
-#! @EndAutoDoc
-
-
-
Both, Operation1
and IsProperty
would appear in the manual.
-
-
2.2-8 @BeginGroup [grpname]
+
2.2-4 @BeginGroup [grpname]
Starts a group. All following documented declarations without an explicit @Group
command are grouped together in the same group with the given name. If no name is given, then a new nameless group is generated. The effect of this command is ended when an @EndGroup
command is reached.
@@ -328,7 +287,7 @@
-
2.2-9 @EndGroup
+
2.2-5 @EndGroup
Ends the current group.
@@ -348,9 +307,15 @@
#! @EndGroup
+
+
+2.2-6 @GroupTitle title
+
+Sets the subsection heading for the current group to title. In the absence of any @GroupTitle
command, the heading will be the name of the first entry in the group. See 2.5 for more information.
+
-2.2-10 @Level lvl
+2.2-7 @Level lvl
Sets the current level of the documentation. All items created after this, chapters, sections, and items, are given the level lvl, until the @ResetLevel
command resets the level to 0 or another level is set.
@@ -358,15 +323,17 @@
-2.2-11 @ResetLevel
+2.2-8 @ResetLevel
Resets the current level to 0.
-2.2-12 @BeginExample
and @EndExample
+2.2-9 @BeginExample
and @EndExample
-@BeginExample
inserts an example into the manual. The syntax for examples is different from GAPDocs example syntax in order to have a file that contains the example and is GAP readable. To achieve this, GAP commands are not preceded by a comment, while output has to be preceded by an AutoDoc comment. The GAP prompt for the display in the manual is added by AutoDoc. @EndExample
ends the example block.
+@BeginExample
marks the start of an example to be put into the manual. It differs from GAPDoc's <Example>
(see GAPDoc: Log), in that it expects actual code (not in a comment) interspersed with comments, to allow for examples files that can be both executed by GAP, and parsed by AutoDoc. To achieve this, GAP commands are not preceded by a comment, while output has to be preceded by an AutoDoc comment. The gap>
prompt for the display in the manual is added by AutoDoc. @EndExample
ends the example block.
+
+To illustrate this command, consider this input:
@@ -378,25 +345,25 @@
#! @EndExample
-The AutoDoc command @Example
is an alias of @BeginExample
.
+This results in the following output:
-
-2.2-13 @BeginExampleSession
and @EndExampleSession
+
+gap> S5 := SymmetricGroup(5);
+Sym( [ 1 .. 5 ] )
+gap> Order(S5);
+120
+
-@BeginExampleSession
inserts an example into the manual, but in a different syntax. For example, consider
+The AutoDoc command @Example
is an alias of @BeginExample
.
+
-
-#! @BeginExample
-S5 := SymmetricGroup(5);
-#! Sym( [ 1 .. 5 ] )
-Order(S5);
-#! 120
-#! @EndExample
-
+2.2-10 @BeginExampleSession
and @EndExampleSession
+
+@BeginExampleSession
marks the start of an example to be put into the manual, while @EndExampleSession
ends the example block. It is the direct analog of GAPDoc's <Example>
(see GAPDoc: Log).
-As you can see, the commands are not commented and hence are executed when the file containing the example block is read. To insert examples directly into source code files, one can instead use @BeginExampleSession
:
+To illustrate this command, consider this input:
@@ -408,25 +375,35 @@
#! @EndExampleSession
-It inserts an example into the manual just as @Example
would do, but all lines are commented and therefore not executed when the file is read. All lines that should be part of the example displayed in the manual have to start with an AutoDoc comment (#!
). The comment will be removed, and, if the following character is a space, this space will also be removed. There is never more than one space removed. To ensure examples are correctly colored in the manual, there should be exactly one space between #!
and the gap
prompt. The AutoDoc command @ExampleSession
is an alias of @BeginExampleSession
.
+This results in the following output:
+
+
+
+gap> S5 := SymmetricGroup(5);
+Sym( [ 1 .. 5 ] )
+gap> Order(S5);
+120
+
+
+It inserts an example into the manual just as @Example
would do, but all lines are commented and therefore not executed when the file is read. All lines that should be part of the example displayed in the manual have to start with an AutoDoc comment (#!
). The comment will be removed, and, if the following character is a space, this space will also be removed. There is never more than one space removed. To ensure examples are correctly colored in the manual, there should be exactly one space between #!
and the gap>
prompt. The AutoDoc command @ExampleSession
is an alias of @BeginExampleSession
.
-2.2-14 @BeginLog
and @EndLog
+2.2-11 @BeginLog
and @EndLog
-Works just like the @BeginExample
command, but the example will not be tested. See the GAPDoc manual for more information. The AutoDoc command @Log
is an alias of @BeginLog
.
+Works just like the @BeginExample
command, but the example will not be tested. See the GAPDoc manual for more information. The AutoDoc command @Log
is an alias of @BeginLog
.
-2.2-15 @BeginLogSession
and @EndLogSession
+2.2-12 @BeginLogSession
and @EndLogSession
-Works just like the @BeginExampleSession
command, but the example will not be tested if manual examples are run. See the GAPDoc manual for more information. The AutoDoc command @LogSession
is an alias of @BeginLogSession
.
+Works just like the @BeginExampleSession
command, but the example will not be tested if manual examples are run. It is the direct analog of GAPDoc's <Log>
(see GAPDoc: Log). The AutoDoc command @LogSession
is an alias of @BeginLogSession
.
-2.2-16 @DoNotReadRestOfFile
+2.2-13 @DoNotReadRestOfFile
-Prevents the rest of the file from being read by the parser. Useful for not finished or temporary files.
+Prevents the rest of the file from being read by the parser. Useful for unfinished or temporary files.
@@ -439,7 +416,7 @@
-2.2-17 @BeginChunk name
, @EndChunk
, and @InsertChunk name
+2.2-14 @BeginChunk name
, @EndChunk
, and @InsertChunk name
Text inside a @BeginChunk
/ @EndChunk
part will not be inserted into the final documentation directly. Instead, the text is stored in an internal buffer. That chunk of text can then later on be inserted in any other place by using the @InsertChunk name
command. If you do not provide an @EndChunk
, the chunk ends at the end of the file.
@@ -474,15 +451,9 @@
#! @InsertChunk Example_Symmetric_Group
-
-
-2.2-18 @BeginSystem name
, @EndSystem
, and @InsertSystem name
-
-These command are deprecated. Please use the chunk commands from subsection 2.2-19 instead.
-
-2.2-19 @BeginCode name
, @EndCode, and @InsertCode name
+2.2-15 @BeginCode name
, @EndCode, and @InsertCode name
Inserts the text between @BeginCode
and @EndCode
verbatim at the point where @InsertCode
is called. This is useful to insert code excerpts directly into the manual.
@@ -498,7 +469,7 @@
-2.2-20 @LatexOnly text
, @BeginLatexOnly
, and @EndLatexOnly
+2.2-16 @LatexOnly text
, @BeginLatexOnly
, and @EndLatexOnly
Code inserted between @BeginLatexOnly
and @EndLatexOnly
or after @LatexOnly
is only inserted in the PDF version of the manual or worksheet. It can hold arbitrary LaTeX-commands.
@@ -513,7 +484,7 @@
-2.2-21 @NotLatex text
, @BeginNotLatex
, and @EndNotLatex
+2.2-17 @NotLatex text
, @BeginNotLatex
, and @EndNotLatex
Code inserted between @BeginNotLatex
and @EndNotLatex
or after @NotLatex
is inserted in the HTML and text versions of the manual or worksheet, but not in the PDF version.
@@ -574,21 +545,24 @@
2.4 Plain text files
-AutoDoc plain text files work exactly like AutoDoc comments, except that the #!
is unnecessary at the beginning of a line which should be documented. Files that have the suffix .autodoc
will automatically regarded as plain text files while the commands @AutoDocPlainText
and @EndAutoDocPlainText
mark parts in plain text files which should be regarded as AutoDoc parts. All commands can be used like before.
+Files that have the suffix .autodoc
and are listed in the autodoc.files
option of AutoDoc
(4.1-1), resp. are contained in one of the directories listed in autodoc.scan_dirs
, are treated as AutoDoc plain text files. These work exactly like AutoDoc comments, except that lines do not need to (and in fact, should not) start with #!
.
2.5 Grouping
-In GAPDoc, it is possible to make groups of ManItems, i.e., when documenting a function, operation, etc., it is possible to group them into suitable chunks. This can be particularly useful if there are several definitions of an operation with several different argument types, all doing more or less the same to the arguments. Then their manual items can be grouped, sharing the same description and return type information. Note that it is currently not possible to give a header to the Group in the manual, but the generated ManItem heading of the first entry will be used.
+In GAPDoc, it is possible to make groups of manual items, i.e., when documenting a function, operation, etc., it is possible to group them into suitable chunks. This can be particularly useful if there are several definitions of an operation with several different argument types, all doing more or less the same to the arguments. Then their manual items can be grouped, sharing the same description and return type information. You can give a heading to the group in the manual with the @GroupTitle
command; if that is not supplied, then the heading of the first manual item in the group will be used as the heading.
Note that group names are globally unique throughout the whole manual. That is, groups with the same name are in fact merged into a single group, even if they were declared in different source files. Thus you can have multiple @BeginGroup
/ @EndGroup
pairs using the same group name, in different places, and these all will refer to the same group.
-Moreover, this means that you can add items to a group via the @Group
command in the AutoDoc comment of an arbitrary declaration, at any time. The following code
+Moreover, this means that you can add items to a group via the @Group
command in the AutoDoc comment of an arbitrary declaration, at any time.
+
+The following code
#! @BeginGroup Group1
+#! @GroupTitle A family of operations
#! @Description
#! First sentence.
@@ -610,9 +584,9 @@
produces the following:
-
+
-2.5-1 FirstOperation
+2.5-1 A family of operations
‣ FirstOperation ( arg ) | ( operation ) |
‣ SecondOperation ( arg1, arg2 ) | ( operation ) |
@@ -731,6 +705,35 @@
This produces the following output:
Call function foobar()
at the start.
+
+
+2.8 Deprecated commands
+
+The following commands used to be supported, but should not generally be used anymore. They will be removed in a future version of AutoDoc.
+
+
+
+@EndSection
+You can simply remove any use of this, AutoDoc ends sections automatically at the start of any new section or chapter.
+
+
+@EndSubsection
+You can simply remove any use of this, AutoDoc ends subsections automatically at the start of any new subsection, section or chapter.
+
+
+@BeginAutoDoc
and @EndAutoDoc
+It suffices to prepend each declaration that is meant to be appear in the manual with a minimal AutoDoc comment #!
.
+
+
+@BeginSystem name
, @EndSystem
, and @InsertSystem name
+Please use the chunk commands from subsection 2.2-14 instead.
+
+
+@AutoDocPlainText
and @EndAutoDocPlainText
+Use .autodoc
files or AutoDoc comments instead.
+
+
+
diff -Nru gap-autodoc-2019.05.20/doc/chap2_mj.html gap-autodoc-2019.09.04/doc/chap2_mj.html
--- gap-autodoc-2019.05.20/doc/chap2_mj.html 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chap2_mj.html 2020-03-02 09:35:41.000000000 +0000
@@ -50,43 +50,35 @@
2.2-2 @Section name
-
2.2-3 @EndSection
+
2.2-3 @Subsection name
-
2.2-4 @Subsection name
+
2.2-4 @BeginGroup [grpname]
-
2.2-5 @EndSubsection
+
2.2-5 @EndGroup
-
2.2-6 @BeginAutoDoc
+
2.2-6 @GroupTitle title
-
2.2-7 @EndAutoDoc
+
2.2-7 @Level lvl
-
2.2-8 @BeginGroup [grpname]
+
2.2-8 @ResetLevel
-
2.2-9 @EndGroup
+
2.2-9 @BeginExample
and @EndExample
-
2.2-10 @Level lvl
+
2.2-10 @BeginExampleSession
and @EndExampleSession
-
2.2-11 @ResetLevel
+
2.2-11 @BeginLog
and @EndLog
-
2.2-12 @BeginExample
and @EndExample
+
2.2-12 @BeginLogSession
and @EndLogSession
-
2.2-13 @BeginExampleSession
and @EndExampleSession
+
2.2-13 @DoNotReadRestOfFile
-
2.2-14 @BeginLog
and @EndLog
+
2.2-14 @BeginChunk name
, @EndChunk
, and @InsertChunk name
-
2.2-15 @BeginLogSession
and @EndLogSession
+
2.2-15 @BeginCode name
, @EndCode, and @InsertCode name
-
2.2-16 @DoNotReadRestOfFile
+
2.2-16 @LatexOnly text
, @BeginLatexOnly
, and @EndLatexOnly
-
2.2-17 @BeginChunk name
, @EndChunk
, and @InsertChunk name
-
-
2.2-18 @BeginSystem name
, @EndSystem
, and @InsertSystem name
-
-
2.2-19 @BeginCode name
, @EndCode, and @InsertCode name
-
-
2.2-20 @LatexOnly text
, @BeginLatexOnly
, and @EndLatexOnly
-
-
2.2-21 @NotLatex text
, @BeginNotLatex
, and @EndNotLatex
+
2.2-17 @NotLatex text
, @BeginNotLatex
, and @EndNotLatex
+
2 AutoDoc documentation comments
@@ -220,7 +216,7 @@
#! @Returns a list
#! @Arguments modtbl
#! @Group CharacterDegreesOfBlocks
-#! @FunctionLabel chardegblocks
+#! @Label chardegblocks
#! @ChapterInfo Blocks, Attributes
DeclareAttribute( "CharacterDegreesOfBlocks",
IsBrauerTable );
@@ -270,15 +266,9 @@
The @SectionLabel
label command can be used to set the label of the section to Section_
label instead of Chapter_chaptername_Section_
name. The @SectionTitle
title command can be used to set a heading for the section that is different from name.
-
-
-2.2-3 @EndSection
-
-This command is deprecated. You can simply remove any use of it.
-
-2.2-4 @Subsection name
+2.2-3 @Subsection name
Sets an active subsection like @Section
sets an active section. The subsection automatically ends with the next @Subsection
, @Section
or @Chapter
command. It also ends with the next documented function. Indeed, internally each function "manpage" is treated like a subsection.
@@ -290,40 +280,9 @@
The @SubsectionLabel
label command can be used to set the label of the subsection to Subsection_
label instead of Chapter_chaptername_Section_sectionname_Subsection_
name. The @SubsectionTitle
title command can be used to set a heading for the subsection that is different from name.
-
-
-2.2-5 @EndSubsection
-
-This command is deprecated. You can simply remove any use of it.
-
-
-
-2.2-6 @BeginAutoDoc
-
-Causes all subsequent declarations to be documented in the manual, regardless of whether they have an AutoDoc comment in front of them or not.
-
-
-
-2.2-7 @EndAutoDoc
-
-Ends the effect of @BeginAutoDoc
. So from here on, again only declarations with an explicit AutoDoc comment in front are added to the manual.
-
-
-
-#! @BeginAutoDoc
-
-DeclareOperation( "Operation1", [ IsList ] );
-
-DeclareProperty( "IsProperty", IsList );
-
-#! @EndAutoDoc
-
-
-Both, Operation1
and IsProperty
would appear in the manual.
-
-2.2-8 @BeginGroup [grpname]
+2.2-4 @BeginGroup [grpname]
Starts a group. All following documented declarations without an explicit @Group
command are grouped together in the same group with the given name. If no name is given, then a new nameless group is generated. The effect of this command is ended when an @EndGroup
command is reached.
@@ -331,7 +290,7 @@
-2.2-9 @EndGroup
+2.2-5 @EndGroup
Ends the current group.
@@ -351,9 +310,15 @@
#! @EndGroup
+
+
+2.2-6 @GroupTitle title
+
+Sets the subsection heading for the current group to title. In the absence of any @GroupTitle
command, the heading will be the name of the first entry in the group. See 2.5 for more information.
+
-2.2-10 @Level lvl
+2.2-7 @Level lvl
Sets the current level of the documentation. All items created after this, chapters, sections, and items, are given the level lvl, until the @ResetLevel
command resets the level to 0 or another level is set.
@@ -361,15 +326,17 @@
-2.2-11 @ResetLevel
+2.2-8 @ResetLevel
Resets the current level to 0.
-2.2-12 @BeginExample
and @EndExample
+2.2-9 @BeginExample
and @EndExample
-@BeginExample
inserts an example into the manual. The syntax for examples is different from GAPDocs example syntax in order to have a file that contains the example and is GAP readable. To achieve this, GAP commands are not preceded by a comment, while output has to be preceded by an AutoDoc comment. The GAP prompt for the display in the manual is added by AutoDoc. @EndExample
ends the example block.
+@BeginExample
marks the start of an example to be put into the manual. It differs from GAPDoc's <Example>
(see GAPDoc: Log), in that it expects actual code (not in a comment) interspersed with comments, to allow for examples files that can be both executed by GAP, and parsed by AutoDoc. To achieve this, GAP commands are not preceded by a comment, while output has to be preceded by an AutoDoc comment. The gap>
prompt for the display in the manual is added by AutoDoc. @EndExample
ends the example block.
+
+To illustrate this command, consider this input:
@@ -381,25 +348,25 @@
#! @EndExample
-The AutoDoc command @Example
is an alias of @BeginExample
.
+This results in the following output:
-
-2.2-13 @BeginExampleSession
and @EndExampleSession
+
+gap> S5 := SymmetricGroup(5);
+Sym( [ 1 .. 5 ] )
+gap> Order(S5);
+120
+
-@BeginExampleSession
inserts an example into the manual, but in a different syntax. For example, consider
+The AutoDoc command @Example
is an alias of @BeginExample
.
+
-
-#! @BeginExample
-S5 := SymmetricGroup(5);
-#! Sym( [ 1 .. 5 ] )
-Order(S5);
-#! 120
-#! @EndExample
-
+2.2-10 @BeginExampleSession
and @EndExampleSession
+
+@BeginExampleSession
marks the start of an example to be put into the manual, while @EndExampleSession
ends the example block. It is the direct analog of GAPDoc's <Example>
(see GAPDoc: Log).
-As you can see, the commands are not commented and hence are executed when the file containing the example block is read. To insert examples directly into source code files, one can instead use @BeginExampleSession
:
+To illustrate this command, consider this input:
@@ -411,25 +378,35 @@
#! @EndExampleSession
-It inserts an example into the manual just as @Example
would do, but all lines are commented and therefore not executed when the file is read. All lines that should be part of the example displayed in the manual have to start with an AutoDoc comment (#!
). The comment will be removed, and, if the following character is a space, this space will also be removed. There is never more than one space removed. To ensure examples are correctly colored in the manual, there should be exactly one space between #!
and the gap
prompt. The AutoDoc command @ExampleSession
is an alias of @BeginExampleSession
.
+This results in the following output:
+
+
+
+gap> S5 := SymmetricGroup(5);
+Sym( [ 1 .. 5 ] )
+gap> Order(S5);
+120
+
+
+It inserts an example into the manual just as @Example
would do, but all lines are commented and therefore not executed when the file is read. All lines that should be part of the example displayed in the manual have to start with an AutoDoc comment (#!
). The comment will be removed, and, if the following character is a space, this space will also be removed. There is never more than one space removed. To ensure examples are correctly colored in the manual, there should be exactly one space between #!
and the gap>
prompt. The AutoDoc command @ExampleSession
is an alias of @BeginExampleSession
.
-2.2-14 @BeginLog
and @EndLog
+2.2-11 @BeginLog
and @EndLog
-Works just like the @BeginExample
command, but the example will not be tested. See the GAPDoc manual for more information. The AutoDoc command @Log
is an alias of @BeginLog
.
+Works just like the @BeginExample
command, but the example will not be tested. See the GAPDoc manual for more information. The AutoDoc command @Log
is an alias of @BeginLog
.
-2.2-15 @BeginLogSession
and @EndLogSession
+2.2-12 @BeginLogSession
and @EndLogSession
-Works just like the @BeginExampleSession
command, but the example will not be tested if manual examples are run. See the GAPDoc manual for more information. The AutoDoc command @LogSession
is an alias of @BeginLogSession
.
+Works just like the @BeginExampleSession
command, but the example will not be tested if manual examples are run. It is the direct analog of GAPDoc's <Log>
(see GAPDoc: Log). The AutoDoc command @LogSession
is an alias of @BeginLogSession
.
-2.2-16 @DoNotReadRestOfFile
+2.2-13 @DoNotReadRestOfFile
-Prevents the rest of the file from being read by the parser. Useful for not finished or temporary files.
+Prevents the rest of the file from being read by the parser. Useful for unfinished or temporary files.
@@ -442,7 +419,7 @@
-2.2-17 @BeginChunk name
, @EndChunk
, and @InsertChunk name
+2.2-14 @BeginChunk name
, @EndChunk
, and @InsertChunk name
Text inside a @BeginChunk
/ @EndChunk
part will not be inserted into the final documentation directly. Instead, the text is stored in an internal buffer. That chunk of text can then later on be inserted in any other place by using the @InsertChunk name
command. If you do not provide an @EndChunk
, the chunk ends at the end of the file.
@@ -477,15 +454,9 @@
#! @InsertChunk Example_Symmetric_Group
-
-
-2.2-18 @BeginSystem name
, @EndSystem
, and @InsertSystem name
-
-These command are deprecated. Please use the chunk commands from subsection 2.2-19 instead.
-
-2.2-19 @BeginCode name
, @EndCode, and @InsertCode name
+2.2-15 @BeginCode name
, @EndCode, and @InsertCode name
Inserts the text between @BeginCode
and @EndCode
verbatim at the point where @InsertCode
is called. This is useful to insert code excerpts directly into the manual.
@@ -501,7 +472,7 @@
-2.2-20 @LatexOnly text
, @BeginLatexOnly
, and @EndLatexOnly
+2.2-16 @LatexOnly text
, @BeginLatexOnly
, and @EndLatexOnly
Code inserted between @BeginLatexOnly
and @EndLatexOnly
or after @LatexOnly
is only inserted in the PDF version of the manual or worksheet. It can hold arbitrary LaTeX-commands.
@@ -516,7 +487,7 @@
-2.2-21 @NotLatex text
, @BeginNotLatex
, and @EndNotLatex
+2.2-17 @NotLatex text
, @BeginNotLatex
, and @EndNotLatex
Code inserted between @BeginNotLatex
and @EndNotLatex
or after @NotLatex
is inserted in the HTML and text versions of the manual or worksheet, but not in the PDF version.
@@ -577,21 +548,24 @@
2.4 Plain text files
-AutoDoc plain text files work exactly like AutoDoc comments, except that the #!
is unnecessary at the beginning of a line which should be documented. Files that have the suffix .autodoc
will automatically regarded as plain text files while the commands @AutoDocPlainText
and @EndAutoDocPlainText
mark parts in plain text files which should be regarded as AutoDoc parts. All commands can be used like before.
+Files that have the suffix .autodoc
and are listed in the autodoc.files
option of AutoDoc
(4.1-1), resp. are contained in one of the directories listed in autodoc.scan_dirs
, are treated as AutoDoc plain text files. These work exactly like AutoDoc comments, except that lines do not need to (and in fact, should not) start with #!
.
2.5 Grouping
-In GAPDoc, it is possible to make groups of ManItems, i.e., when documenting a function, operation, etc., it is possible to group them into suitable chunks. This can be particularly useful if there are several definitions of an operation with several different argument types, all doing more or less the same to the arguments. Then their manual items can be grouped, sharing the same description and return type information. Note that it is currently not possible to give a header to the Group in the manual, but the generated ManItem heading of the first entry will be used.
+In GAPDoc, it is possible to make groups of manual items, i.e., when documenting a function, operation, etc., it is possible to group them into suitable chunks. This can be particularly useful if there are several definitions of an operation with several different argument types, all doing more or less the same to the arguments. Then their manual items can be grouped, sharing the same description and return type information. You can give a heading to the group in the manual with the @GroupTitle
command; if that is not supplied, then the heading of the first manual item in the group will be used as the heading.
Note that group names are globally unique throughout the whole manual. That is, groups with the same name are in fact merged into a single group, even if they were declared in different source files. Thus you can have multiple @BeginGroup
/ @EndGroup
pairs using the same group name, in different places, and these all will refer to the same group.
-Moreover, this means that you can add items to a group via the @Group
command in the AutoDoc comment of an arbitrary declaration, at any time. The following code
+Moreover, this means that you can add items to a group via the @Group
command in the AutoDoc comment of an arbitrary declaration, at any time.
+
+The following code
#! @BeginGroup Group1
+#! @GroupTitle A family of operations
#! @Description
#! First sentence.
@@ -613,9 +587,9 @@
produces the following:
-
+
-2.5-1 FirstOperation
+2.5-1 A family of operations
‣ FirstOperation ( arg ) | ( operation ) |
‣ SecondOperation ( arg1, arg2 ) | ( operation ) |
@@ -734,6 +708,35 @@
This produces the following output:
Call function foobar()
at the start.
+
+
+2.8 Deprecated commands
+
+The following commands used to be supported, but should not generally be used anymore. They will be removed in a future version of AutoDoc.
+
+
+
+@EndSection
+You can simply remove any use of this, AutoDoc ends sections automatically at the start of any new section or chapter.
+
+
+@EndSubsection
+You can simply remove any use of this, AutoDoc ends subsections automatically at the start of any new subsection, section or chapter.
+
+
+@BeginAutoDoc
and @EndAutoDoc
+It suffices to prepend each declaration that is meant to be appear in the manual with a minimal AutoDoc comment #!
.
+
+
+@BeginSystem name
, @EndSystem
, and @InsertSystem name
+Please use the chunk commands from subsection 2.2-14 instead.
+
+
+@AutoDocPlainText
and @EndAutoDocPlainText
+Use .autodoc
files or AutoDoc comments instead.
+
+
+
diff -Nru gap-autodoc-2019.05.20/doc/chap2.txt gap-autodoc-2019.09.04/doc/chap2.txt
--- gap-autodoc-2019.05.20/doc/chap2.txt 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chap2.txt 2020-03-02 09:35:41.000000000 +0000
@@ -109,7 +109,7 @@
[4X#! @Returns a list[104X
[4X#! @Arguments modtbl[104X
[4X#! @Group CharacterDegreesOfBlocks[104X
- [4X#! @FunctionLabel chardegblocks[104X
+ [4X#! @Label chardegblocks[104X
[4X#! @ChapterInfo Blocks, Attributes[104X
[4XDeclareAttribute( "CharacterDegreesOfBlocks",[104X
[4X IsBrauerTable );[104X
@@ -170,12 +170,7 @@
that is different from [3Xname[103X.[133X
- [1X2.2-3 [33X[0;0Y[10X@EndSection[110X[101X[1X[133X[101X
-
- [33X[0;0Y[13XThis command is deprecated.[113X You can simply remove any use of it.[133X
-
-
- [1X2.2-4 [33X[0;0Y[10X@Subsection [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
+ [1X2.2-3 [33X[0;0Y[10X@Subsection [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
[33X[0;0YSets an active subsection like [10X@Section[110X sets an active section. The
subsection automatically ends with the next [10X@Subsection[110X, [10X@Section[110X or
@@ -194,36 +189,7 @@
subsection that is different from [3Xname[103X.[133X
- [1X2.2-5 [33X[0;0Y[10X@EndSubsection[110X[101X[1X[133X[101X
-
- [33X[0;0Y[13XThis command is deprecated.[113X You can simply remove any use of it.[133X
-
-
- [1X2.2-6 [33X[0;0Y[10X@BeginAutoDoc[110X[101X[1X[133X[101X
-
- [33X[0;0YCauses all subsequent declarations to be documented in the manual,
- regardless of whether they have an [5XAutoDoc[105X comment in front of them or not.[133X
-
-
- [1X2.2-7 [33X[0;0Y[10X@EndAutoDoc[110X[101X[1X[133X[101X
-
- [33X[0;0YEnds the effect of [10X@BeginAutoDoc[110X. So from here on, again only declarations
- with an explicit [5XAutoDoc[105X comment in front are added to the manual.[133X
-
- [4X[32X[104X
- [4X#! @BeginAutoDoc[104X
- [4X[104X
- [4XDeclareOperation( "Operation1", [ IsList ] );[104X
- [4X[104X
- [4XDeclareProperty( "IsProperty", IsList );[104X
- [4X[104X
- [4X#! @EndAutoDoc[104X
- [4X[32X[104X
-
- [33X[0;0YBoth, [10XOperation1[110X and [10XIsProperty[110X would appear in the manual.[133X
-
-
- [1X2.2-8 [33X[0;0Y[10X@BeginGroup [3X[grpname][103X[101X[1X[10X[110X[101X[1X[133X[101X
+ [1X2.2-4 [33X[0;0Y[10X@BeginGroup [3X[grpname][103X[101X[1X[10X[110X[101X[1X[133X[101X
[33X[0;0YStarts a group. All following documented declarations without an explicit
[10X@Group[110X command are grouped together in the same group with the given name.
@@ -233,7 +199,7 @@
[33X[0;0YSee section [14X2.5[114X for more information about groups.[133X
- [1X2.2-9 [33X[0;0Y[10X@EndGroup[110X[101X[1X[133X[101X
+ [1X2.2-5 [33X[0;0Y[10X@EndGroup[110X[101X[1X[133X[101X
[33X[0;0YEnds the current group.[133X
@@ -253,7 +219,14 @@
[4X[32X[104X
- [1X2.2-10 [33X[0;0Y[10X@Level [3Xlvl[103X[101X[1X[10X[110X[101X[1X[133X[101X
+ [1X2.2-6 [33X[0;0Y@GroupTitle [3Xtitle[103X[101X[1X[133X[101X
+
+ [33X[0;0YSets the subsection heading for the current group to [3Xtitle[103X. In the absence
+ of any [10X@GroupTitle[110X command, the heading will be the name of the first entry
+ in the group. See [14X2.5[114X for more information.[133X
+
+
+ [1X2.2-7 [33X[0;0Y[10X@Level [3Xlvl[103X[101X[1X[10X[110X[101X[1X[133X[101X
[33X[0;0YSets the current level of the documentation. All items created after this,
chapters, sections, and items, are given the level [3Xlvl[103X, until the
@@ -262,19 +235,22 @@
[33X[0;0YSee section [14X2.6[114X for more information about levels.[133X
- [1X2.2-11 [33X[0;0Y[10X@ResetLevel[110X[101X[1X[133X[101X
+ [1X2.2-8 [33X[0;0Y[10X@ResetLevel[110X[101X[1X[133X[101X
[33X[0;0YResets the current level to 0.[133X
- [1X2.2-12 [33X[0;0Y[10X@BeginExample[110X[101X[1X and [10X@EndExample[110X[101X[1X[133X[101X
+ [1X2.2-9 [33X[0;0Y[10X@BeginExample[110X[101X[1X and [10X@EndExample[110X[101X[1X[133X[101X
+
+ [33X[0;0Y[10X@BeginExample[110X marks the start of an example to be put into the manual. It
+ differs from [5XGAPDoc[105X's [10X
[110X (see [14X'GAPDoc: Log'[114X), in that it expects
+ actual code (not in a comment) interspersed with comments, to allow for
+ examples files that can be both executed by [5XGAP[105X, and parsed by [5XAutoDoc[105X. To
+ achieve this, [5XGAP[105X commands are not preceded by a comment, while output has
+ to be preceded by an [5XAutoDoc[105X comment. The [10Xgap>[110X prompt for the display in the
+ manual is added by [5XAutoDoc[105X. [10X@EndExample[110X ends the example block.[133X
- [33X[0;0Y[10X@BeginExample[110X inserts an example into the manual. The syntax for examples is
- different from GAPDocs example syntax in order to have a file that contains
- the example and is GAP readable. To achieve this, GAP commands are not
- preceded by a comment, while output has to be preceded by an [5XAutoDoc[105X
- comment. The GAP prompt for the display in the manual is added by [5XAutoDoc[105X.
- [10X@EndExample[110X ends the example block.[133X
+ [33X[0;0YTo illustrate this command, consider this input:[133X
[4X[32X[104X
[4X#! @BeginExample[104X
@@ -285,26 +261,25 @@
[4X#! @EndExample[104X
[4X[32X[104X
- [33X[0;0YThe [5XAutoDoc[105X command [10X@Example[110X is an alias of [10X@BeginExample[110X.[133X
+ [33X[0;0YThis results in the following output:[133X
+ [4X[32X Example [32X[104X
+ [4X[25Xgap>[125X [27XS5 := SymmetricGroup(5);[127X[104X
+ [4X[28XSym( [ 1 .. 5 ] )[128X[104X
+ [4X[25Xgap>[125X [27XOrder(S5);[127X[104X
+ [4X[28X120[128X[104X
+ [4X[32X[104X
- [1X2.2-13 [33X[0;0Y[10X@BeginExampleSession[110X[101X[1X and [10X@EndExampleSession[110X[101X[1X[133X[101X
+ [33X[0;0YThe [5XAutoDoc[105X command [10X@Example[110X is an alias of [10X@BeginExample[110X.[133X
- [33X[0;0Y[10X@BeginExampleSession[110X inserts an example into the manual, but in a different
- syntax. For example, consider[133X
- [4X[32X[104X
- [4X#! @BeginExample[104X
- [4XS5 := SymmetricGroup(5);[104X
- [4X#! Sym( [ 1 .. 5 ] )[104X
- [4XOrder(S5);[104X
- [4X#! 120[104X
- [4X#! @EndExample[104X
- [4X[32X[104X
+ [1X2.2-10 [33X[0;0Y[10X@BeginExampleSession[110X[101X[1X and [10X@EndExampleSession[110X[101X[1X[133X[101X
+
+ [33X[0;0Y[10X@BeginExampleSession[110X marks the start of an example to be put into the
+ manual, while [10X@EndExampleSession[110X ends the example block. It is the direct
+ analog of [5XGAPDoc[105X's [10X[110X (see [14X'GAPDoc: Log'[114X).[133X
- [33X[0;0YAs you can see, the commands are not commented and hence are executed when
- the file containing the example block is read. To insert examples directly
- into source code files, one can instead use [10X@BeginExampleSession[110X:[133X
+ [33X[0;0YTo illustrate this command, consider this input:[133X
[4X[32X[104X
[4X#! @BeginExampleSession[104X
@@ -315,36 +290,45 @@
[4X#! @EndExampleSession[104X
[4X[32X[104X
+ [33X[0;0YThis results in the following output:[133X
+
+ [4X[32X Example [32X[104X
+ [4X[25Xgap>[125X [27XS5 := SymmetricGroup(5);[127X[104X
+ [4X[28XSym( [ 1 .. 5 ] )[128X[104X
+ [4X[25Xgap>[125X [27XOrder(S5);[127X[104X
+ [4X[28X120[128X[104X
+ [4X[32X[104X
+
[33X[0;0YIt inserts an example into the manual just as [10X@Example[110X would do, but all
lines are commented and therefore not executed when the file is read. All
lines that should be part of the example displayed in the manual have to
start with an [5XAutoDoc[105X comment ([10X#![110X). The comment will be removed, and, if the
following character is a space, this space will also be removed. There is
never more than one space removed. To ensure examples are correctly colored
- in the manual, there should be exactly one space between [10X#![110X and the [10Xgap[110X
+ in the manual, there should be exactly one space between [10X#![110X and the [10Xgap>[110X
prompt. The [5XAutoDoc[105X command [10X@ExampleSession[110X is an alias of
[10X@BeginExampleSession[110X.[133X
- [1X2.2-14 [33X[0;0Y[10X@BeginLog[110X[101X[1X and [10X@EndLog[110X[101X[1X[133X[101X
+ [1X2.2-11 [33X[0;0Y[10X@BeginLog[110X[101X[1X and [10X@EndLog[110X[101X[1X[133X[101X
[33X[0;0YWorks just like the [10X@BeginExample[110X command, but the example will not be
- tested. See the GAPDoc manual for more information. The [5XAutoDoc[105X command [10X@Log[110X
+ tested. See the [5XGAPDoc[105X manual for more information. The [5XAutoDoc[105X command [10X@Log[110X
is an alias of [10X@BeginLog[110X.[133X
- [1X2.2-15 [33X[0;0Y[10X@BeginLogSession[110X[101X[1X and [10X@EndLogSession[110X[101X[1X[133X[101X
+ [1X2.2-12 [33X[0;0Y[10X@BeginLogSession[110X[101X[1X and [10X@EndLogSession[110X[101X[1X[133X[101X
[33X[0;0YWorks just like the [10X@BeginExampleSession[110X command, but the example will not
- be tested if manual examples are run. See the GAPDoc manual for more
- information. The [5XAutoDoc[105X command [10X@LogSession[110X is an alias of
+ be tested if manual examples are run. It is the direct analog of [5XGAPDoc[105X's
+ [10X[110X (see [14X'GAPDoc: Log'[114X). The [5XAutoDoc[105X command [10X@LogSession[110X is an alias of
[10X@BeginLogSession[110X.[133X
- [1X2.2-16 [33X[0;0Y[10X@DoNotReadRestOfFile[110X[101X[1X[133X[101X
+ [1X2.2-13 [33X[0;0Y[10X@DoNotReadRestOfFile[110X[101X[1X[133X[101X
- [33X[0;0YPrevents the rest of the file from being read by the parser. Useful for not
- finished or temporary files.[133X
+ [33X[0;0YPrevents the rest of the file from being read by the parser. Useful for
+ unfinished or temporary files.[133X
[4X[32X[104X
[4X#! This will appear in the manual[104X
@@ -355,7 +339,7 @@
[4X[32X[104X
- [1X2.2-17 [33X[0;0Y[10X@BeginChunk [3Xname[103X[101X[1X[10X[110X[101X[1X, [10X@EndChunk[110X[101X[1X, and [10X@InsertChunk [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
+ [1X2.2-14 [33X[0;0Y[10X@BeginChunk [3Xname[103X[101X[1X[10X[110X[101X[1X, [10X@EndChunk[110X[101X[1X, and [10X@InsertChunk [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
[33X[0;0YText inside a [10X@BeginChunk[110X / [10X@EndChunk[110X part will not be inserted into the
final documentation directly. Instead, the text is stored in an internal
@@ -392,13 +376,7 @@
[4X[32X[104X
- [1X2.2-18 [33X[0;0Y[10X@BeginSystem [3Xname[103X[101X[1X[10X[110X[101X[1X, [10X@EndSystem[110X[101X[1X, and [10X@InsertSystem [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
-
- [33X[0;0Y[13XThese command are deprecated.[113X Please use the chunk commands from subsection
- [14X2.2-19[114X instead.[133X
-
-
- [1X2.2-19 [33X[0;0Y[10X@BeginCode [3Xname[103X[101X[1X[10X[110X[101X[1X, @EndCode, and [10X@InsertCode [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
+ [1X2.2-15 [33X[0;0Y[10X@BeginCode [3Xname[103X[101X[1X[10X[110X[101X[1X, @EndCode, and [10X@InsertCode [3Xname[103X[101X[1X[10X[110X[101X[1X[133X[101X
[33X[0;0YInserts the text between [10X@BeginCode[110X and [10X@EndCode[110X verbatim at the point where
[10X@InsertCode[110X is called. This is useful to insert code excerpts directly into
@@ -414,7 +392,7 @@
[4X[32X[104X
- [1X2.2-20 [33X[0;0Y[10X@LatexOnly [3Xtext[103X[101X[1X[10X[110X[101X[1X, [10X@BeginLatexOnly[110X[101X[1X, and [10X@EndLatexOnly[110X[101X[1X[133X[101X
+ [1X2.2-16 [33X[0;0Y[10X@LatexOnly [3Xtext[103X[101X[1X[10X[110X[101X[1X, [10X@BeginLatexOnly[110X[101X[1X, and [10X@EndLatexOnly[110X[101X[1X[133X[101X
[33X[0;0YCode inserted between [10X@BeginLatexOnly[110X and [10X@EndLatexOnly[110X or after [10X@LatexOnly[110X
is only inserted in the PDF version of the manual or worksheet. It can hold
@@ -429,7 +407,7 @@
[4X[32X[104X
- [1X2.2-21 [33X[0;0Y[10X@NotLatex [3Xtext[103X[101X[1X[10X[110X[101X[1X, [10X@BeginNotLatex[110X[101X[1X, and [10X@EndNotLatex[110X[101X[1X[133X[101X
+ [1X2.2-17 [33X[0;0Y[10X@NotLatex [3Xtext[103X[101X[1X[10X[110X[101X[1X, [10X@BeginNotLatex[110X[101X[1X, and [10X@EndNotLatex[110X[101X[1X[133X[101X
[33X[0;0YCode inserted between [10X@BeginNotLatex[110X and [10X@EndNotLatex[110X or after [10X@NotLatex[110X is
inserted in the HTML and text versions of the manual or worksheet, but not
@@ -483,24 +461,24 @@
[1X2.4 [33X[0;0YPlain text files[133X[101X
- [33X[0;0Y[5XAutoDoc[105X plain text files work exactly like [5XAutoDoc[105X comments, except that the
- [10X#![110X is unnecessary at the beginning of a line which should be documented.
- Files that have the suffix [10X.autodoc[110X will automatically regarded as plain
- text files while the commands [10X@AutoDocPlainText[110X and [10X@EndAutoDocPlainText[110X
- mark parts in plain text files which should be regarded as [5XAutoDoc[105X parts.
- All commands can be used like before.[133X
+ [33X[0;0YFiles that have the suffix [10X.autodoc[110X and are listed in the [10Xautodoc.files[110X
+ option of [2XAutoDoc[102X ([14X4.1-1[114X), resp. are contained in one of the directories
+ listed in [10Xautodoc.scan_dirs[110X, are treated as [5XAutoDoc[105X plain text files. These
+ work exactly like [5XAutoDoc[105X comments, except that lines do not need to (and in
+ fact, should not) start with [10X#![110X.[133X
[1X2.5 [33X[0;0YGrouping[133X[101X
- [33X[0;0YIn [5XGAPDoc[105X, it is possible to make groups of ManItems, i.e., when documenting
- a function, operation, etc., it is possible to group them into suitable
- chunks. This can be particularly useful if there are several definitions of
- an operation with several different argument types, all doing more or less
- the same to the arguments. Then their manual items can be grouped, sharing
- the same description and return type information. Note that it is currently
- not possible to give a header to the Group in the manual, but the generated
- ManItem heading of the first entry will be used.[133X
+ [33X[0;0YIn [5XGAPDoc[105X, it is possible to make groups of manual items, i.e., when
+ documenting a function, operation, etc., it is possible to group them into
+ suitable chunks. This can be particularly useful if there are several
+ definitions of an operation with several different argument types, all doing
+ more or less the same to the arguments. Then their manual items can be
+ grouped, sharing the same description and return type information. You can
+ give a heading to the group in the manual with the [10X@GroupTitle[110X command; if
+ that is not supplied, then the heading of the first manual item in the group
+ will be used as the heading.[133X
[33X[0;0YNote that group names are globally unique throughout the whole manual. That
is, groups with the same name are in fact merged into a single group, even
@@ -509,11 +487,13 @@
places, and these all will refer to the same group.[133X
[33X[0;0YMoreover, this means that you can add items to a group via the [10X@Group[110X
- command in the [5XAutoDoc[105X comment of an arbitrary declaration, at any time. The
- following code[133X
+ command in the [5XAutoDoc[105X comment of an arbitrary declaration, at any time.[133X
+
+ [33X[0;0YThe following code[133X
[4X[32X[104X
[4X#! @BeginGroup Group1[104X
+ [4X#! @GroupTitle A family of operations[104X
[4X[104X
[4X#! @Description[104X
[4X#! First sentence.[104X
@@ -535,7 +515,8 @@
[33X[0;0Yproduces the following:[133X
- [1X2.5-1 FirstOperation[101X
+
+ [1X2.5-1 [33X[0;0YA family of operations[133X[101X
[33X[1;0Y[29X[2XFirstOperation[102X( [3Xarg[103X ) [32X operation[133X
[33X[1;0Y[29X[2XSecondOperation[102X( [3Xarg1[103X, [3Xarg2[103X ) [32X operation[133X
@@ -661,3 +642,27 @@
[33X[0;0YThis produces the following output:[133X
[33X[0;0YCall function [10Xfoobar()[110X at the start.[133X
+
+ [1X2.8 [33X[0;0YDeprecated commands[133X[101X
+
+ [33X[0;0YThe following commands used to be supported, but should not generally be
+ used anymore. They will be removed in a future version of [5XAutoDoc[105X.[133X
+
+ [8X[10X@EndSection[110X[8X[108X
+ [33X[0;6YYou can simply remove any use of this, [5XAutoDoc[105X ends sections
+ automatically at the start of any new section or chapter.[133X
+
+ [8X[10X@EndSubsection[110X[8X[108X
+ [33X[0;6YYou can simply remove any use of this, [5XAutoDoc[105X ends subsections
+ automatically at the start of any new subsection, section or chapter.[133X
+
+ [8X[10X@BeginAutoDoc[110X[8X and [10X@EndAutoDoc[110X[8X[108X
+ [33X[0;6YIt suffices to prepend each declaration that is meant to be appear in
+ the manual with a minimal [5XAutoDoc[105X comment [10X#![110X.[133X
+
+ [8X[10X@BeginSystem [3Xname[103X[8X[10X[110X[8X, [10X@EndSystem[110X[8X, and [10X@InsertSystem [3Xname[103X[8X[10X[110X[8X[108X
+ [33X[0;6YPlease use the chunk commands from subsection [14X2.2-14[114X instead.[133X
+
+ [8X[10X@AutoDocPlainText[110X[8X and [10X@EndAutoDocPlainText[110X[8X[108X
+ [33X[0;6YUse [10X.autodoc[110X files or [5XAutoDoc[105X comments instead.[133X
+
diff -Nru gap-autodoc-2019.05.20/doc/chap4.html gap-autodoc-2019.09.04/doc/chap4.html
--- gap-autodoc-2019.05.20/doc/chap4.html 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chap4.html 2020-03-02 09:35:41.000000000 +0000
@@ -42,10 +42,10 @@
4.1-1 AutoDoc
-‣ AutoDoc ( [package[, optrec]] ) | ( function ) |
+‣ AutoDoc ( [packageOrDirectory, ][optrec] ) | ( function ) |
Returns: nothing
-This is the main function of the AutoDoc package. It can perform any combination of the following three tasks:
+This is the main function of the AutoDoc package. It can perform any combination of the following tasks:
It can (re)generate a scaffold for your package manual. That is, it can produce two XML files in GAPDoc format to be used as part of your manual: First, a file named doc/PACKAGENAME.xml
(with your package's name substituted) which is used as main XML file for the package manual, i.e. this file sets the XML doctype and defines various XML entities, includes other XML files (both those generated by AutoDoc as well as additional files created by other means), tells GAPDoc to generate a table of content and an index, and more. Secondly, it creates a file doc/title.xml
containing a title page for your documentation, with information about your package (name, description, version), its authors and more, based on the data in your PackageInfo.g
.
@@ -54,7 +54,7 @@
It can scan your package for AutoDoc based documentation (by using AutoDoc tags and the Autodoc command. This will produce further XML files to be used as part of the package manual.
-It can use GAPDoc to generate PDF, text and HTML (with MathJaX enabled) documentation from the GAPDoc XML files it generated as well as additional such files provided by you. For this, it invokes MakeGAPDocDoc
(GAPDoc: MakeGAPDocDoc) to convert the XML sources, and it also instructs GAPDoc to copy supplementary files (such as CSS style files) into your doc directory (see CopyHTMLStyleFiles
(GAPDoc: CopyHTMLStyleFiles)).
+It can use GAPDoc to generate PDF, text and HTML (with MathJaX enabled) documentation from the GAPDoc XML files it generated as well as additional such files provided by you. For this, it invokes MakeGAPDocDoc
(GAPDoc: MakeGAPDocDoc) to convert the XML sources, and it also instructs GAPDoc to copy supplementary files (such as CSS style files) into your doc directory (see CopyHTMLStyleFiles
(GAPDoc: CopyHTMLStyleFiles)).
@@ -64,10 +64,10 @@
-- package
-This is either the name of package, or an IsDirectory
object. In the former case, AutoDoc uses the metadata of the first package with that name known to GAP. In the latter case, it checks whether the given directory contains a PackageInfo.g
file, and extracts all needed metadata from that. This 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.
+- packageOrDirectory
+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 IsDirectory
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 InstallationPath
specified in that metadata as the package directory. If packageOrDirectory is an 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 PackageInfo.g
file, and AutoDoc extracts all needed metadata from that. The 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.
-If this argument is omitted, AutoDoc uses the DirectoryCurrent()
.
+Note that when using AutoDocWorksheet
(see 3.1), there is no parameter corresponding to packageOrDirectory and so the "package directory" is always the current directory, and there is no metadata.
- optrec
@@ -76,7 +76,7 @@
- dir
-This should be a string containing a (relative) path or a Directory() object specifying where the package documentation (i.e. the GAPDoc XML files) are stored.
Default value: "doc/"
.
+This should either be a string, in which case it must be a path relative to the specified package directory, or a Directory()
object. (Thus, the only way to designate an absolute directory is with a Directory()
object.) This option specifies where the package documentation (e.g. the GAPDoc XML or the manual PDF, etc.) files are stored and/or will be generated.
Default value: "doc/"
.
- scaffold
@@ -111,14 +111,14 @@
-rec( SomePackage := "<Package>SomePackage</Package>",
-RELEASEYEAR := "2015" )
+ rec( SomePackage := "<Package>SomePackage</Package>",
+ RELEASEYEAR := "2015" )
then the following entity definitions are added to the XML preamble:
<!ENTITY SomePackage '<Package>SomePackage</Package>'>
-<!ENTITY RELEASEYEAR '2015'>
+ <!ENTITY RELEASEYEAR '2015'>
This allows you to write "&SomePackage;" and "&RELEASEYEAR;" in your documentation, which will be replaced by respective values specified in the entities definition.
@@ -128,9 +128,9 @@
-rec( Acknowledgements := "Many thanks to ..." )
+ rec( Acknowledgements := "Many thanks to ..." )
-For a list of valid entries in the title page, please refer to the GAPDoc manual, specifically section GAPDoc: TitlePage.
+For a list of valid entries in the title page, please refer to the GAPDoc manual, specifically section GAPDoc: TitlePage.
MainPage
@@ -142,13 +142,13 @@
latex_header_file
-Replaces the standard header from GAPDoc completely with the header in this LaTeX file. Please be careful here, and look at GAPDoc's latexheader.tex file for an example.
+Replaces the standard header from GAPDoc completely with the header in this LaTeX file. Please be careful here, and look at GAPDoc's latexheader.tex
file for an example.
autodoc
-This controls whether and how to generate addition XML documentation files by scanning for AutoDoc documentation comments.
+This controls whether and how to generate additional XML documentation files by scanning for AutoDoc documentation comments.
The value should be either true
, false
or a record. If it is a record or true
(the latter is equivalent to specifying an empty record), then this feature is enabled. It is also enabled if opt.autodoc is missing but the package depends (directly) on the AutoDoc package. In all other cases (in particular if opt.autodoc is false
), this feature is disabled.
@@ -192,13 +192,13 @@
LaTeXOptions
-Must be a record with entries which can be understood by SetGapDocLaTeXOptions
(GAPDoc: SetGapDocLaTeXOptions). Each entry can be a string, which will be given to GAPDoc directly, or a list containing of two entries: The first one must be the string "file", the second one a filename. This file will be read and then its content is passed to GAPDoc as option with the name of the entry.
+Must be a record with entries which can be understood by SetGapDocLaTeXOptions
(GAPDoc: SetGapDocLaTeXOptions). Each entry can be a string, which will be given to GAPDoc directly, or a list containing of two entries: The first one must be the string "file", the second one a filename. This file will be read and then its content is passed to GAPDoc as option with the name of the entry.
gap_root_relative_path
-Either a boolean, or a string containing a relative path. By default (if this option is not set, or is set to false
), references in the generated documentation referring to external documentation (such as the GAP manual) are encoded using absolute paths. This is fine as long as the documentation stays on only a single computer, but is problematic when preparing documentation that should be used on multiple computers, e.g., when creating a distribution archive of a GAP package.
Thus, if a relative path is provided via this option (or if it is set to true
, in which case the relative path ../../..
is used), then AutoDoc and GAPDoc attempt to replace all absolute paths in references to GAP manuals by paths based on this relative path.
+Either a boolean, or a string containing a relative path. By default (if this option is not set, or is set to false
), references in the generated documentation referring to external documentation (such as the GAP manual) are encoded using absolute paths. This is fine as long as the documentation stays on only a single computer, but is problematic when preparing documentation that should be used on multiple computers, e.g., when creating a distribution archive of a GAP package.
Thus, if a relative path is provided via this option (or if it is set to true
, in which case the relative path ../../..
is used), then AutoDoc and GAPDoc attempt to replace all absolute paths in references to GAP manuals by paths based on this relative path.
-On a technical level, AutoDoc passes the relative path to the gaproot parameter of MakeGAPDocDoc
(GAPDoc: MakeGAPDocDoc)
+On a technical level, AutoDoc passes the relative path to the gaproot parameter of MakeGAPDocDoc
(GAPDoc: MakeGAPDocDoc)
@@ -211,7 +211,7 @@
units
This controls how examples are grouped into files. Recognized values are "Chapter" (default), "Section", "Subsection" or "Single". Depending on the value, one file is created for each chapter, each section, each subsection or each example. For all other values only a single file is created.
-On a technical level, AutoDoc passes the value to the units parameter of ExtractExamples
(GAPDoc: ExtractExamples).
+On a technical level, AutoDoc passes the value to the units parameter of ExtractExamples
(GAPDoc: ExtractExamples).
diff -Nru gap-autodoc-2019.05.20/doc/chap4_mj.html gap-autodoc-2019.09.04/doc/chap4_mj.html
--- gap-autodoc-2019.05.20/doc/chap4_mj.html 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chap4_mj.html 2020-03-02 09:35:41.000000000 +0000
@@ -45,10 +45,10 @@
4.1-1 AutoDoc
-‣ AutoDoc ( [package[, optrec]] ) | ( function ) |
+‣ AutoDoc ( [packageOrDirectory, ][optrec] ) | ( function ) |
Returns: nothing
-This is the main function of the AutoDoc package. It can perform any combination of the following three tasks:
+This is the main function of the AutoDoc package. It can perform any combination of the following tasks:
It can (re)generate a scaffold for your package manual. That is, it can produce two XML files in GAPDoc format to be used as part of your manual: First, a file named doc/PACKAGENAME.xml
(with your package's name substituted) which is used as main XML file for the package manual, i.e. this file sets the XML doctype and defines various XML entities, includes other XML files (both those generated by AutoDoc as well as additional files created by other means), tells GAPDoc to generate a table of content and an index, and more. Secondly, it creates a file doc/title.xml
containing a title page for your documentation, with information about your package (name, description, version), its authors and more, based on the data in your PackageInfo.g
.
@@ -57,7 +57,7 @@
It can scan your package for AutoDoc based documentation (by using AutoDoc tags and the Autodoc command. This will produce further XML files to be used as part of the package manual.
-It can use GAPDoc to generate PDF, text and HTML (with MathJaX enabled) documentation from the GAPDoc XML files it generated as well as additional such files provided by you. For this, it invokes MakeGAPDocDoc
(GAPDoc: MakeGAPDocDoc) to convert the XML sources, and it also instructs GAPDoc to copy supplementary files (such as CSS style files) into your doc directory (see CopyHTMLStyleFiles
(GAPDoc: CopyHTMLStyleFiles)).
+It can use GAPDoc to generate PDF, text and HTML (with MathJaX enabled) documentation from the GAPDoc XML files it generated as well as additional such files provided by you. For this, it invokes MakeGAPDocDoc
(GAPDoc: MakeGAPDocDoc) to convert the XML sources, and it also instructs GAPDoc to copy supplementary files (such as CSS style files) into your doc directory (see CopyHTMLStyleFiles
(GAPDoc: CopyHTMLStyleFiles)).
@@ -67,10 +67,10 @@
-- package
-This is either the name of package, or an IsDirectory
object. In the former case, AutoDoc uses the metadata of the first package with that name known to GAP. In the latter case, it checks whether the given directory contains a PackageInfo.g
file, and extracts all needed metadata from that. This 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.
+- packageOrDirectory
+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 IsDirectory
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 InstallationPath
specified in that metadata as the package directory. If packageOrDirectory is an 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 PackageInfo.g
file, and AutoDoc extracts all needed metadata from that. The 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.
-If this argument is omitted, AutoDoc uses the DirectoryCurrent()
.
+Note that when using AutoDocWorksheet
(see 3.1), there is no parameter corresponding to packageOrDirectory and so the "package directory" is always the current directory, and there is no metadata.
- optrec
@@ -79,7 +79,7 @@
- dir
-This should be a string containing a (relative) path or a Directory() object specifying where the package documentation (i.e. the GAPDoc XML files) are stored.
Default value: "doc/"
.
+This should either be a string, in which case it must be a path relative to the specified package directory, or a Directory()
object. (Thus, the only way to designate an absolute directory is with a Directory()
object.) This option specifies where the package documentation (e.g. the GAPDoc XML or the manual PDF, etc.) files are stored and/or will be generated.
Default value: "doc/"
.
- scaffold
@@ -114,14 +114,14 @@
-rec( SomePackage := "<Package>SomePackage</Package>",
-RELEASEYEAR := "2015" )
+ rec( SomePackage := "<Package>SomePackage</Package>",
+ RELEASEYEAR := "2015" )
then the following entity definitions are added to the XML preamble:
<!ENTITY SomePackage '<Package>SomePackage</Package>'>
-<!ENTITY RELEASEYEAR '2015'>
+ <!ENTITY RELEASEYEAR '2015'>
This allows you to write "&SomePackage;" and "&RELEASEYEAR;" in your documentation, which will be replaced by respective values specified in the entities definition.
@@ -131,9 +131,9 @@
-rec( Acknowledgements := "Many thanks to ..." )
+ rec( Acknowledgements := "Many thanks to ..." )
-For a list of valid entries in the title page, please refer to the GAPDoc manual, specifically section GAPDoc: TitlePage.
+For a list of valid entries in the title page, please refer to the GAPDoc manual, specifically section GAPDoc: TitlePage.
- MainPage
@@ -145,13 +145,13 @@
- latex_header_file
-Replaces the standard header from GAPDoc completely with the header in this LaTeX file. Please be careful here, and look at GAPDoc's latexheader.tex file for an example.
+Replaces the standard header from GAPDoc completely with the header in this LaTeX file. Please be careful here, and look at GAPDoc's latexheader.tex
file for an example.
- autodoc
-This controls whether and how to generate addition XML documentation files by scanning for AutoDoc documentation comments.
+This controls whether and how to generate additional XML documentation files by scanning for AutoDoc documentation comments.
The value should be either true
, false
or a record. If it is a record or true
(the latter is equivalent to specifying an empty record), then this feature is enabled. It is also enabled if opt.autodoc is missing but the package depends (directly) on the AutoDoc package. In all other cases (in particular if opt.autodoc is false
), this feature is disabled.
@@ -195,13 +195,13 @@
- LaTeXOptions
-Must be a record with entries which can be understood by SetGapDocLaTeXOptions
(GAPDoc: SetGapDocLaTeXOptions). Each entry can be a string, which will be given to GAPDoc directly, or a list containing of two entries: The first one must be the string "file", the second one a filename. This file will be read and then its content is passed to GAPDoc as option with the name of the entry.
+Must be a record with entries which can be understood by SetGapDocLaTeXOptions
(GAPDoc: SetGapDocLaTeXOptions). Each entry can be a string, which will be given to GAPDoc directly, or a list containing of two entries: The first one must be the string "file", the second one a filename. This file will be read and then its content is passed to GAPDoc as option with the name of the entry.
- gap_root_relative_path
-Either a boolean, or a string containing a relative path. By default (if this option is not set, or is set to false
), references in the generated documentation referring to external documentation (such as the GAP manual) are encoded using absolute paths. This is fine as long as the documentation stays on only a single computer, but is problematic when preparing documentation that should be used on multiple computers, e.g., when creating a distribution archive of a GAP package.
Thus, if a relative path is provided via this option (or if it is set to true
, in which case the relative path ../../..
is used), then AutoDoc and GAPDoc attempt to replace all absolute paths in references to GAP manuals by paths based on this relative path.
+Either a boolean, or a string containing a relative path. By default (if this option is not set, or is set to false
), references in the generated documentation referring to external documentation (such as the GAP manual) are encoded using absolute paths. This is fine as long as the documentation stays on only a single computer, but is problematic when preparing documentation that should be used on multiple computers, e.g., when creating a distribution archive of a GAP package.
Thus, if a relative path is provided via this option (or if it is set to true
, in which case the relative path ../../..
is used), then AutoDoc and GAPDoc attempt to replace all absolute paths in references to GAP manuals by paths based on this relative path.
-On a technical level, AutoDoc passes the relative path to the gaproot parameter of MakeGAPDocDoc
(GAPDoc: MakeGAPDocDoc)
+On a technical level, AutoDoc passes the relative path to the gaproot parameter of MakeGAPDocDoc
(GAPDoc: MakeGAPDocDoc)
@@ -214,7 +214,7 @@
units
This controls how examples are grouped into files. Recognized values are "Chapter" (default), "Section", "Subsection" or "Single". Depending on the value, one file is created for each chapter, each section, each subsection or each example. For all other values only a single file is created.
-On a technical level, AutoDoc passes the value to the units parameter of ExtractExamples
(GAPDoc: ExtractExamples).
+On a technical level, AutoDoc passes the value to the units parameter of ExtractExamples
(GAPDoc: ExtractExamples).
diff -Nru gap-autodoc-2019.05.20/doc/chap4.txt gap-autodoc-2019.09.04/doc/chap4.txt
--- gap-autodoc-2019.05.20/doc/chap4.txt 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chap4.txt 2020-03-02 09:35:41.000000000 +0000
@@ -6,11 +6,11 @@
[1X4.1-1 AutoDoc[101X
- [33X[1;0Y[29X[2XAutoDoc[102X( [[3Xpackage[103X[, [3Xoptrec[103X]] ) [32X function[133X
+ [33X[1;0Y[29X[2XAutoDoc[102X( [[3XpackageOrDirectory[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
- combination of the following three tasks:[133X
+ combination of the following tasks:[133X
[31X1[131X [33X[0;6YIt can (re)generate a scaffold for your package manual. That is, it
can produce two XML files in [5XGAPDoc[105X format to be used as part of your
@@ -41,25 +41,37 @@
[33X[0;0YThe parameters have the following meanings:[133X
- [8X[3Xpackage[103X[8X[108X
- [33X[0;6YThis is either the name of package, or an [10XIsDirectory[110X object. In the
- former case, [5XAutoDoc[105X uses the metadata of the first package with that
- name known to [5XGAP[105X. In the latter case, it checks whether the given
- directory contains a [11XPackageInfo.g[111X file, and extracts all needed
- metadata from that. This is for example useful if you have multiple
+ [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
- [33X[0;6YIf this argument is omitted, [5XAutoDoc[105X uses the [10XDirectoryCurrent()[110X.[133X
+ [33X[0;6YNote that when using [10XAutoDocWorksheet[110X (see [14X3.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
[8X[3Xoptrec[103X[8X[108X
[33X[0;6Y[3Xoptrec[103X can be a record with some additional options. The following are
currently supported:[133X
[8X[3Xdir[103X[8X[108X
- [33X[0;12YThis should be a string containing a (relative) path or a
- Directory() object specifying where the package documentation
- (i.e. the [5XGAPDoc[105X XML files) are stored.[133X
+ [33X[0;12YThis should either be a string, in which case it must be a path
+ [13Xrelative[113X to the specified package directory, or a [10XDirectory()[110X
+ object. (Thus, the only way to designate an absolute directory
+ is with a [10XDirectory()[110X object.) This option specifies where the
+ package documentation (e.g. the [5XGAPDoc[105X XML or the manual PDF,
+ etc.) files are stored and/or will be generated.[133X
[33X[0;12Y[13XDefault value: [10X"doc/"[110X.[113X[133X
[8X[3Xscaffold[103X[8X[108X
@@ -110,8 +122,8 @@
the record [21XSomePackage[121X,[133X
[4X [32X[104X
- [4Xrec( SomePackage := "SomePackage",[104X
- [4XRELEASEYEAR := "2015" )[104X
+ [4X rec( SomePackage := "SomePackage",[104X
+ [4X RELEASEYEAR := "2015" )[104X
[4X[32X[104X
[33X[0;18Ythen the following entity definitions are added to the XML
@@ -119,7 +131,7 @@
[4X [32X[104X
[4XSomePackage'>[104X
- [4X[104X
+ [4X [104X
[4X[32X[104X
[33X[0;18YThis allows you to write [21X&SomePackage;[121X and [21X&RELEASEYEAR;[121X
@@ -137,7 +149,7 @@
acknowledgements text:[133X
[4X [32X[104X
- [4Xrec( Acknowledgements := "Many thanks to ..." )[104X
+ [4X rec( Acknowledgements := "Many thanks to ..." )[104X
[4X[32X[104X
[33X[0;18YFor a list of valid entries in the title page, please
@@ -163,10 +175,10 @@
[8X[3Xlatex_header_file[103X[8X[108X
[33X[0;18YReplaces the standard header from [5XGAPDoc[105X completely with
the header in this LaTeX file. Please be careful here, and
- look at GAPDoc's latexheader.tex file for an example.[133X
+ look at [5XGAPDoc[105X's [11Xlatexheader.tex[111X file for an example.[133X
[8X[3Xautodoc[103X[8X[108X
- [33X[0;12YThis controls whether and how to generate addition XML
+ [33X[0;12YThis controls whether and how to generate additional XML
documentation files by scanning for [5XAutoDoc[105X documentation
comments.[133X
@@ -247,16 +259,16 @@
[33X[0;18YEither a boolean, or a string containing a relative path.
By default (if this option is not set, or is set to
[9Xfalse[109X), references in the generated documentation
- referring to external documentation (such as the GAP
+ referring to external documentation (such as the [5XGAP[105X
manual) are encoded using absolute paths. This is fine as
long as the documentation stays on only a single computer,
but is problematic when preparing documentation that
should be used on multiple computers, e.g., when creating
- a distribution archive of a GAP package.[133X
+ a distribution archive of a [5XGAP[105X package.[133X
[33X[0;18YThus, if a relative path is provided via this option (or
if it is set to [9Xtrue[109X, in which case the relative path
[11X../../..[111X is used), then [5XAutoDoc[105X and [5XGAPDoc[105X attempt to
- replace all absolute paths in references to GAP manuals by
+ replace all absolute paths in references to [5XGAP[105X manuals by
paths based on this relative path.[133X
[33X[0;18YOn a technical level, [5XAutoDoc[105X passes the relative path to
diff -Nru gap-autodoc-2019.05.20/doc/chapInd.html gap-autodoc-2019.09.04/doc/chapInd.html
--- gap-autodoc-2019.05.20/doc/chapInd.html 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chapInd.html 2020-03-02 09:35:41.000000000 +0000
@@ -26,64 +26,58 @@
Index
@Arguments args
2.1-3
-@BeginAutoDoc
2.2-6
-@BeginChunk name
2.2-17
-@BeginCode name
2.2-19
-@BeginExample
2.2-12
-@BeginExampleSession
2.2-13
-@BeginGroup
2.2-8
-@BeginLatexOnly
2.2-20
-@BeginLog
2.2-14
-@BeginLogSession
2.2-15
-@BeginNotLatex
2.2-21
-@BeginSystem name
2.2-18
+@BeginChunk name
2.2-14
+@BeginCode name
2.2-15
+@BeginExample
2.2-9
+@BeginExampleSession
2.2-10
+@BeginGroup
2.2-4
+@BeginLatexOnly
2.2-16
+@BeginLog
2.2-11
+@BeginLogSession
2.2-12
+@BeginNotLatex
2.2-17
@Chapter
2.2-1
@ChapterInfo
2.1-8
@ChapterLabel
2.2-1
@ChapterTitle
2.2-1
@Description descr
2.1-1
-@DoNotReadRestOfFile
2.2-16
-@EndAutoDoc
2.2-7
-@InsertChunk name
2.2-17
-@EndChunk
2.2-17
-@EndCode
2.2-19
-@EndExample
2.2-12
-@EndExampleSession
2.2-13
-@EndGroup
2.2-9
-@EndLatexOnly
2.2-20
-@EndLog
2.2-14
-@EndLogSession
2.2-15
-@EndNotLatex
2.2-21
-@EndSection
2.2-3
-@EndSubsection
2.2-5
-@EndSystem
2.2-18
+@DoNotReadRestOfFile
2.2-13
+@InsertChunk name
2.2-14
+@EndChunk
2.2-14
+@EndCode
2.2-15
+@EndExample
2.2-9
+@EndExampleSession
2.2-10
+@EndGroup
2.2-5
+@EndLatexOnly
2.2-16
+@EndLog
2.2-11
+@EndLogSession
2.2-12
+@EndNotLatex
2.2-17
@Group grpname
2.1-4
-@InsertCode name
2.2-19
-@InsertSystem name
2.2-18
+@GroupTitle
2.2-6
+@InsertCode name
2.2-15
@Label label
2.1-5
-@LatexOnly text
2.2-20
-@Level
2.2-10
-@NotLatex text
2.2-21
-@ResetLevel
2.2-11
+@LatexOnly text
2.2-16
+@Level
2.2-7
+@NotLatex text
2.2-17
+@ResetLevel
2.2-8
@Returns ret_val
2.1-2
@Section
2.2-2
@SectionLabel
2.2-2
@SectionTitle
2.2-2
-@Subsection
2.2-4
-@SubsectionLabel
2.2-4
-@SubsectionTitle
2.2-4
+@Subsection
2.2-3
+@SubsectionLabel
2.2-3
+@SubsectionTitle
2.2-3
1.3-3 1.3-3
AProperty
, for IsObject 2.1-7
testlabel 2.1-6
AutoDoc
4.1-1
AutoDocWorksheet
3.1-1
1.3-3 1.3-3 1.3-3
-FirstOperation
, for IsInt 2.5-1
+FirstOperation
, for IsInt 2.5-1
1.3-3
makedoc.g
1.1
1.3-3
-SecondOperation
, for IsInt, IsGroup 2.5-1
-ThirdOperation
, for IsGroup, IsInt 2.5-1
+SecondOperation
, for IsInt, IsGroup 2.5-1
+ThirdOperation
, for IsGroup, IsInt 2.5-1
diff -Nru gap-autodoc-2019.05.20/doc/chapInd_mj.html gap-autodoc-2019.09.04/doc/chapInd_mj.html
--- gap-autodoc-2019.05.20/doc/chapInd_mj.html 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chapInd_mj.html 2020-03-02 09:35:41.000000000 +0000
@@ -29,64 +29,58 @@
Index
@Arguments args
2.1-3
-@BeginAutoDoc
2.2-6
-@BeginChunk name
2.2-17
-@BeginCode name
2.2-19
-@BeginExample
2.2-12
-@BeginExampleSession
2.2-13
-@BeginGroup
2.2-8
-@BeginLatexOnly
2.2-20
-@BeginLog
2.2-14
-@BeginLogSession
2.2-15
-@BeginNotLatex
2.2-21
-@BeginSystem name
2.2-18
+@BeginChunk name
2.2-14
+@BeginCode name
2.2-15
+@BeginExample
2.2-9
+@BeginExampleSession
2.2-10
+@BeginGroup
2.2-4
+@BeginLatexOnly
2.2-16
+@BeginLog
2.2-11
+@BeginLogSession
2.2-12
+@BeginNotLatex
2.2-17
@Chapter
2.2-1
@ChapterInfo
2.1-8
@ChapterLabel
2.2-1
@ChapterTitle
2.2-1
@Description descr
2.1-1
-@DoNotReadRestOfFile
2.2-16
-@EndAutoDoc
2.2-7
-@InsertChunk name
2.2-17
-@EndChunk
2.2-17
-@EndCode
2.2-19
-@EndExample
2.2-12
-@EndExampleSession
2.2-13
-@EndGroup
2.2-9
-@EndLatexOnly
2.2-20
-@EndLog
2.2-14
-@EndLogSession
2.2-15
-@EndNotLatex
2.2-21
-@EndSection
2.2-3
-@EndSubsection
2.2-5
-@EndSystem
2.2-18
+@DoNotReadRestOfFile
2.2-13
+@InsertChunk name
2.2-14
+@EndChunk
2.2-14
+@EndCode
2.2-15
+@EndExample
2.2-9
+@EndExampleSession
2.2-10
+@EndGroup
2.2-5
+@EndLatexOnly
2.2-16
+@EndLog
2.2-11
+@EndLogSession
2.2-12
+@EndNotLatex
2.2-17
@Group grpname
2.1-4
-@InsertCode name
2.2-19
-@InsertSystem name
2.2-18
+@GroupTitle
2.2-6
+@InsertCode name
2.2-15
@Label label
2.1-5
-@LatexOnly text
2.2-20
-@Level
2.2-10
-@NotLatex text
2.2-21
-@ResetLevel
2.2-11
+@LatexOnly text
2.2-16
+@Level
2.2-7
+@NotLatex text
2.2-17
+@ResetLevel
2.2-8
@Returns ret_val
2.1-2
@Section
2.2-2
@SectionLabel
2.2-2
@SectionTitle
2.2-2
-@Subsection
2.2-4
-@SubsectionLabel
2.2-4
-@SubsectionTitle
2.2-4
+@Subsection
2.2-3
+@SubsectionLabel
2.2-3
+@SubsectionTitle
2.2-3
1.3-3 1.3-3
AProperty
, for IsObject 2.1-7
testlabel 2.1-6
AutoDoc
4.1-1
AutoDocWorksheet
3.1-1
1.3-3 1.3-3 1.3-3
-FirstOperation
, for IsInt 2.5-1
+FirstOperation
, for IsInt 2.5-1
1.3-3
makedoc.g
1.1
1.3-3
-SecondOperation
, for IsInt, IsGroup 2.5-1
-ThirdOperation
, for IsGroup, IsInt 2.5-1
+SecondOperation
, for IsInt, IsGroup 2.5-1
+ThirdOperation
, for IsGroup, IsInt 2.5-1
diff -Nru gap-autodoc-2019.05.20/doc/chapInd.txt gap-autodoc-2019.09.04/doc/chapInd.txt
--- gap-autodoc-2019.05.20/doc/chapInd.txt 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/chapInd.txt 2020-03-02 09:35:41.000000000 +0000
@@ -3,52 +3,46 @@
[1XIndex[101X
[10X@Arguments [3Xargs[103X[10X[110X 2.1-3
- [10X@BeginAutoDoc[110X 2.2-6
- [10X@BeginChunk [3Xname[103X[10X[110X 2.2-17
- [10X@BeginCode [3Xname[103X[10X[110X 2.2-19
- [10X@BeginExample[110X 2.2-12
- [10X@BeginExampleSession[110X 2.2-13
- [10X@BeginGroup[110X 2.2-8
- [10X@BeginLatexOnly[110X 2.2-20
- [10X@BeginLog[110X 2.2-14
- [10X@BeginLogSession[110X 2.2-15
- [10X@BeginNotLatex[110X 2.2-21
- [10X@BeginSystem [3Xname[103X[10X[110X 2.2-18
+ [10X@BeginChunk [3Xname[103X[10X[110X 2.2-14
+ [10X@BeginCode [3Xname[103X[10X[110X 2.2-15
+ [10X@BeginExample[110X 2.2-9
+ [10X@BeginExampleSession[110X 2.2-10
+ [10X@BeginGroup[110X 2.2-4
+ [10X@BeginLatexOnly[110X 2.2-16
+ [10X@BeginLog[110X 2.2-11
+ [10X@BeginLogSession[110X 2.2-12
+ [10X@BeginNotLatex[110X 2.2-17
[10X@Chapter[110X 2.2-1
[10X@ChapterInfo[110X 2.1-8
[10X@ChapterLabel[110X 2.2-1
[10X@ChapterTitle[110X 2.2-1
[10X@Description [3Xdescr[103X[10X[110X 2.1-1
- [10X@DoNotReadRestOfFile[110X 2.2-16
- [10X@EndAutoDoc[110X 2.2-7
- [10X@InsertChunk [3Xname[103X[10X[110X 2.2-17
- [10X@EndChunk[110X 2.2-17
- [10X@EndCode[110X 2.2-19
- [10X@EndExample[110X 2.2-12
- [10X@EndExampleSession[110X 2.2-13
- [10X@EndGroup[110X 2.2-9
- [10X@EndLatexOnly[110X 2.2-20
- [10X@EndLog[110X 2.2-14
- [10X@EndLogSession[110X 2.2-15
- [10X@EndNotLatex[110X 2.2-21
- [10X@EndSection[110X 2.2-3
- [10X@EndSubsection[110X 2.2-5
- [10X@EndSystem[110X 2.2-18
+ [10X@DoNotReadRestOfFile[110X 2.2-13
+ [10X@InsertChunk [3Xname[103X[10X[110X 2.2-14
+ [10X@EndChunk[110X 2.2-14
+ [10X@EndCode[110X 2.2-15
+ [10X@EndExample[110X 2.2-9
+ [10X@EndExampleSession[110X 2.2-10
+ [10X@EndGroup[110X 2.2-5
+ [10X@EndLatexOnly[110X 2.2-16
+ [10X@EndLog[110X 2.2-11
+ [10X@EndLogSession[110X 2.2-12
+ [10X@EndNotLatex[110X 2.2-17
[10X@Group [3Xgrpname[103X[10X[110X 2.1-4
- [10X@InsertCode [3Xname[103X[10X[110X 2.2-19
- [10X@InsertSystem [3Xname[103X[10X[110X 2.2-18
+ [10X@GroupTitle[110X 2.2-6
+ [10X@InsertCode [3Xname[103X[10X[110X 2.2-15
[10X@Label [3Xlabel[103X[10X[110X 2.1-5
- [10X@LatexOnly [3Xtext[103X[10X[110X 2.2-20
- [10X@Level[110X 2.2-10
- [10X@NotLatex [3Xtext[103X[10X[110X 2.2-21
- [10X@ResetLevel[110X 2.2-11
+ [10X@LatexOnly [3Xtext[103X[10X[110X 2.2-16
+ [10X@Level[110X 2.2-7
+ [10X@NotLatex [3Xtext[103X[10X[110X 2.2-17
+ [10X@ResetLevel[110X 2.2-8
[10X@Returns [3Xret_val[103X[10X[110X 2.1-2
[10X@Section[110X 2.2-2
[10X@SectionLabel[110X 2.2-2
[10X@SectionTitle[110X 2.2-2
- [10X@Subsection[110X 2.2-4
- [10X@SubsectionLabel[110X 2.2-4
- [10X@SubsectionTitle[110X 2.2-4
+ [10X@Subsection[110X 2.2-3
+ [10X@SubsectionLabel[110X 2.2-3
+ [10X@SubsectionTitle[110X 2.2-3
1.3-3 1.3-3
[2XAProperty[102X, for IsObject 2.1-7
testlabel 2.1-6
diff -Nru gap-autodoc-2019.05.20/doc/_Chapter_AutoDoc_worksheets.xml gap-autodoc-2019.09.04/doc/_Chapter_AutoDoc_worksheets.xml
--- gap-autodoc-2019.05.20/doc/_Chapter_AutoDoc_worksheets.xml 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/_Chapter_AutoDoc_worksheets.xml 2020-03-02 09:35:41.000000000 +0000
@@ -10,12 +10,12 @@
-The intention of these function is to create stand-alone pdf and html files
-using AutoDoc without having them associated to a package.
-It uses the same optional records as the &AutoDoc; command itself, but instead of
-a package name there should be a filename or a list of filenames containing AutoDoc
-text from which the documents are created. Please see the &AutoDoc; command for more
-information about this and have a look at for a simple worksheet example.
+ The intention of these function is to create stand-alone pdf and html files
+ using AutoDoc without having them associated to a package.
+ It uses the same optional records as the &AutoDoc; command itself, but instead of
+ a package name there should be a filename or a list of filenames containing AutoDoc
+ text from which the documents are created. Please see the &AutoDoc; command for more
+ information about this and have a look at for a simple worksheet example.
diff -Nru gap-autodoc-2019.05.20/doc/_Chapter_AutoDoc.xml gap-autodoc-2019.09.04/doc/_Chapter_AutoDoc.xml
--- gap-autodoc-2019.05.20/doc/_Chapter_AutoDoc.xml 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/_Chapter_AutoDoc.xml 2020-03-02 09:35:41.000000000 +0000
@@ -8,323 +8,338 @@
The AutoDoc() function
-
+
nothing
-This is the main function of the &AutoDoc; package. It can perform
-any combination of the following three tasks:
-
--
-It can (re)generate a scaffold for your package manual.
-That is, it can produce two XML files in &GAPDoc; format to be used as part
-of your manual: First, a file named doc/PACKAGENAME.xml
-(with your package's name substituted) which is used as
-main XML file for the package manual, i.e. this file sets the
-XML doctype and defines various XML entities, includes
-other XML files (both those generated by &AutoDoc; as well
-as additional files created by other means), tells &GAPDoc;
-to generate a table of content and an index, and more.
-Secondly, it creates a file doc/title.xml containing a title
-page for your documentation, with information about your package
-(name, description, version), its authors and more, based
-on the data in your PackageInfo.g.
-
--
-It can scan your package for &AutoDoc; based documentation (by using &AutoDoc;
-tags and the Autodoc command.
-This will
-produce further XML files to be used as part of the package manual.
-
--
-It can use &GAPDoc; to generate PDF, text and HTML (with
-MathJaX enabled) documentation from the &GAPDoc; XML files it
-generated as well as additional such files provided by you. For
-this, it invokes
-to convert the XML sources, and it also instructs &GAPDoc; to copy
-supplementary files (such as CSS style files) into your doc directory
-(see ).
-
-
-For more information and some examples, please refer to Chapter .
-
-The parameters have the following meanings:
-
-package
--
-This is either the name of package, or an IsDirectory object.
-In the former case, &AutoDoc; uses the metadata of the first package
-with that name known to &GAP;. In the latter case, it checks whether
-the given directory contains a PackageInfo.g file, and extracts
-all needed metadata from that. This 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.
-
-If this argument is omitted, &AutoDoc; uses the DirectoryCurrent().
-
-optrec
--
-optrec can be a record with some additional options.
-The following are currently supported:
-
-dir
--
-This should be a string containing a (relative) path or a
-Directory() object specifying where the package documentation
-(i.e. the &GAPDoc; XML files) are stored.
-
-Default value: "doc/".
-
-scaffold
--
-This controls whether and how to generate scaffold XML files
-for the package documentation.
-
-The value should be either true, false or a
-record. If it is a record or true (the latter is
-equivalent to specifying an empty record), then this feature is
-enabled. It is also enabled if opt.scaffold is missing but the
-package's info record in PackageInfo.g has an AutoDoc entry.
-In all other cases (in particular if opt.scaffold is
-false), scaffolding is disabled.
-
-If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is
-assumed to be a record, and its contents are used as default values for
-the scaffold settings.
-
-
-If opt.scaffold is a record, it may contain the following entries.
-
-
-includes
--
-A list of XML files to be included in the body of the main XML file.
-If you specify this list and also are using &AutoDoc; to document
-your operations with &AutoDoc; comments,
-you can add _AutoDocMainFile.xml to this list
-to control at which point the documentation produced by &AutoDoc;
-is inserted. If you do not do this, it will be added after the last
-of your own XML files.
-
-index
--
-By default, the scaffold creates an index. If you do not want an index,
-set this to false.
-
-appendix
--
-This entry is similar to opt.scaffold.includes but is used
-to specify files to include after the main body of the manual,
-i.e. typically appendices.
-
-bib
--
-The name of a bibliography file, in BibTeX or XML format.
-If this key is not set, but there is a file doc/PACKAGENAME.bib
-then it is assumed that you want to use this as your bibliography.
-
-entities
--
-A record whose keys are taken as entity names, set to the corresponding
-(string) values. For example, if you pass the record
SomePackage
,
-SomePackage",
-RELEASEYEAR := "2015" )]]>
-then the following entity definitions are added to the XML preamble:
-SomePackage'>
-]]>
-This allows you to write &SomePackage;
and &RELEASEYEAR;
-in your documentation, which will be replaced by respective values specified
-in the entities definition.
-
-TitlePage
--
-A record whose entries are used to embellish the generated title page
-for the package manual with extra information, such as a copyright
-statement or acknowledgments. To this end, the names of the record
-components are used as XML element names, and the values of the
-components are outputted as content of these XML elements. For
-example, you could pass the following record to set a custom
-acknowledgements text:
-
-For a list of valid entries in the title page, please refer to the
-&GAPDoc; manual, specifically section
.
-
-MainPage
--
-If scaffolding is enabled, by default a main XML file is generated (this
-is the file which contains the XML doctype and more). If you do not
-want this (e.g. because you have a handwritten main XML file), but
-still want &AutoDoc; to generate a title page for you, you can set this
-option to false
-
-document_class
--
-Sets the document class of the resulting PDF. The value can either be a string
-which has to be the name of the new document class, a list containing this string, or
-a list of two strings. Then the first one has to be the document class name, the second one
-the option string ( contained in [ ] ) in LaTeX.
-
-latex_header_file
--
-Replaces the standard header from &GAPDoc; completely with the header in this LaTeX file.
-Please be careful here, and look at GAPDoc's latexheader.tex file for an example.
-
-
-
-autodoc
--
-This controls whether and how to generate addition XML documentation files
-by scanning for &AutoDoc; documentation comments.
-
-The value should be either true, false or a
-record. If it is a record or true (the latter is
-equivalent to specifying an empty record), then this feature is
-enabled. It is also enabled if opt.autodoc is missing but the
-package depends (directly) on the &AutoDoc; package.
-In all other cases (in particular if opt.autodoc is
-false), this feature is disabled.
-
-
-If opt.autodoc is a record, it may contain the following entries.
-
-
-files
--
-A list of files (given by paths relative to the package directory)
-to be scanned for &AutoDoc; documentation comments.
-Usually it is more convenient to use autodoc.scan_dirs, see below.
-
-scan_dirs
--
-A list of subdirectories of the package directory (given as relative paths)
-which &AutoDoc; then scans for .gi, .gd, .g, and .autodoc files; all of these files
-are then scanned for &AutoDoc; documentation comments.
-
-Default value: [ ".", "gap", "lib", "examples", "examples/doc" ].
-
-level
--
-This defines the level of the created documentation. The default value is 0.
-When parts of the manual are declared with a higher value
-they will not be printed into the manual.
-
-
-
-gapdoc
--
-This controls whether and how to invoke &GAPDoc; to create HTML, PDF and text
-files from your various XML files.
-
-The value should be either true, false or a
-record. If it is a record or true (the latter is
-equivalent to specifying an empty record), then this feature is
-enabled. It is also enabled if opt.gapdoc is missing.
-In all other cases (in particular if opt.gapdoc is
-false), this feature is disabled.
-
-
-If opt.gapdoc is a record, it may contain the following entries.
-
-
-main
--
-The name of the main XML file of the package manual.
-This exists primarily to support packages with existing manual
-which use a filename here which differs from the default.
-In particular, specifying this is unnecessary when using scaffolding.
-
-Default value: PACKAGENAME.xml.
-
-files
--
-A list of files (given by paths relative to the package directory)
-to be scanned for &GAPDoc; documentation comments.
-Usually it is more convenient to use gapdoc.scan_dirs, see below.
-
-scan_dirs
--
-A list of subdirectories of the package directory (given as relative paths)
-which &AutoDoc; then scans for .gi, .gd and .g files; all of these files
-are then scanned for &GAPDoc; documentation comments.
-
-Default value: [ ".", "gap", "lib", "examples", "examples/doc" ].
-
-LaTeXOptions
--
-Must be a record with entries which can be understood by
-
. Each entry can be a
-string, which will be given to &GAPDoc; directly, or a list containing of
-two entries: The first one must be the string "file", the second one a
-filename. This file will be read and then its content is passed to &GAPDoc;
-as option with the name of the entry.
-
-gap_root_relative_path
--
-Either a boolean, or a string containing a relative path.
-By default (if this option is not set, or is set to false),
-references in the generated documentation referring to external documentation
-(such as the GAP manual) are encoded using absolute paths.
-This is fine as long as the documentation stays on only a single
-computer, but is problematic when preparing documentation that should be
-used on multiple computers, e.g., when creating a distribution archive of
-a GAP package.
-Thus, if a relative path is provided via this option (or if it is set to true,
-in which case the relative path ../../.. is used), then &AutoDoc;
-and &GAPDoc; attempt to replace all absolute paths in references to GAP
-manuals by paths based on this relative path.
-
-On a technical level, &AutoDoc; passes the relative path to the
-gaproot parameter of
-
-
-
-extract_examples
--
-Either true or a record.
-If set to true, then all manual examples are extracted and placed
-into files tst/PACKAGENAME01.tst, tst/PACKAGENAME02.tst, ...
-and so on, with one file for each chapter.
-As a record, the entry can have the following entries itself, to specify some options.
-
-units
--
-This controls how examples are grouped into files. Recognized values are
-"Chapter" (default), "Section", "Subsection" or "Single". Depending on the value,
-one file is created for each chapter, each section, each subsection or each example.
-For all other values only a single file is created.
-
-On a technical level, &AutoDoc; passes the value to the
-units parameter of
.
-
-
-
-maketest
--
-This option is deprecated. Please use extract_examples instead.
-
-Either true or a record. When it is true,
-a simple maketest.g file is created in the main package directory,
-which can be used to test the examples from the manual. As a record,
-the entry can have the following entries itself, to specify some options.
-
-filename
--
-Sets the name of the test file.
-
-commands
--
-A list of strings, each one a command, which
-will be executed at the beginning of the test file.
-
-
-
-
-
-
+ This is the main function of the &AutoDoc; package. It can perform
+ any combination of the following tasks:
+
+ -
+ It can (re)generate a scaffold for your package manual.
+ That is, it can produce two XML files in &GAPDoc; format to be used as part
+ of your manual: First, a file named doc/PACKAGENAME.xml
+ (with your package's name substituted) which is used as
+ main XML file for the package manual, i.e. this file sets the
+ XML doctype and defines various XML entities, includes
+ other XML files (both those generated by &AutoDoc; as well
+ as additional files created by other means), tells &GAPDoc;
+ to generate a table of content and an index, and more.
+ Secondly, it creates a file doc/title.xml containing a title
+ page for your documentation, with information about your package
+ (name, description, version), its authors and more, based
+ on the data in your PackageInfo.g.
+
+ -
+ It can scan your package for &AutoDoc; based documentation (by using &AutoDoc;
+ tags and the Autodoc command.
+ This will
+ produce further XML files to be used as part of the package manual.
+
+ -
+ It can use &GAPDoc; to generate PDF, text and HTML (with
+ MathJaX enabled) documentation from the &GAPDoc; XML files it
+ generated as well as additional such files provided by you. For
+ this, it invokes
+ to convert the XML sources, and it also instructs &GAPDoc; to copy
+ supplementary files (such as CSS style files) into your doc directory
+ (see ).
+
+
+ For more information and some examples, please refer to Chapter .
+
+ The parameters have the following meanings:
+
+ packageOrDirectory
+ -
+ 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 IsDirectory 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 InstallationPath specified in that
+ metadata as the package directory. If packageOrDirectory is
+ an 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
+ PackageInfo.g file, and &AutoDoc; extracts all needed metadata
+ from that. The 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 AutoDocWorksheet (see
+
), there is
+ no parameter corresponding to packageOrDirectory and so the
+ package directory
is always the current directory, and
+ there is no metadata.
+
+ optrec
+ -
+ optrec can be a record with some additional options.
+ The following are currently supported:
+
+ dir
+ -
+ This should either be a string, in which case it must be a path
+ relative to the specified package directory, or a
+ Directory() object. (Thus, the only way to designate an
+ absolute directory is with a Directory() object.) This
+ option specifies where the package documentation
+ (e.g. the &GAPDoc; XML or the manual PDF, etc.) files are stored
+ and/or will be generated.
+
+ Default value: "doc/".
+
+ scaffold
+ -
+ This controls whether and how to generate scaffold XML files
+ for the package documentation.
+
+ The value should be either true, false or a
+ record. If it is a record or true (the latter is
+ equivalent to specifying an empty record), then this feature is
+ enabled. It is also enabled if opt.scaffold is missing but the
+ package's info record in PackageInfo.g has an AutoDoc entry.
+ In all other cases (in particular if opt.scaffold is
+ false), scaffolding is disabled.
+
+ If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is
+ assumed to be a record, and its contents are used as default values for
+ the scaffold settings.
+
+
+ If opt.scaffold is a record, it may contain the following entries.
+
+
+ includes
+ -
+ A list of XML files to be included in the body of the main XML file.
+ If you specify this list and also are using &AutoDoc; to document
+ your operations with &AutoDoc; comments,
+ you can add _AutoDocMainFile.xml to this list
+ to control at which point the documentation produced by &AutoDoc;
+ is inserted. If you do not do this, it will be added after the last
+ of your own XML files.
+
+ index
+ -
+ By default, the scaffold creates an index. If you do not want an index,
+ set this to false.
+
+ appendix
+ -
+ This entry is similar to opt.scaffold.includes but is used
+ to specify files to include after the main body of the manual,
+ i.e. typically appendices.
+
+ bib
+ -
+ The name of a bibliography file, in BibTeX or XML format.
+ If this key is not set, but there is a file doc/PACKAGENAME.bib
+ then it is assumed that you want to use this as your bibliography.
+
+ entities
+ -
+ A record whose keys are taken as entity names, set to the corresponding
+ (string) values. For example, if you pass the record
SomePackage
,
+ SomePackage",
+ RELEASEYEAR := "2015" )]]>
+ then the following entity definitions are added to the XML preamble:
+ SomePackage'>
+ ]]>
+ This allows you to write &SomePackage;
and &RELEASEYEAR;
+ in your documentation, which will be replaced by respective values specified
+ in the entities definition.
+
+ TitlePage
+ -
+ A record whose entries are used to embellish the generated title page
+ for the package manual with extra information, such as a copyright
+ statement or acknowledgments. To this end, the names of the record
+ components are used as XML element names, and the values of the
+ components are outputted as content of these XML elements. For
+ example, you could pass the following record to set a custom
+ acknowledgements text:
+
+ For a list of valid entries in the title page, please refer to the
+ &GAPDoc; manual, specifically section
.
+
+ MainPage
+ -
+ If scaffolding is enabled, by default a main XML file is generated (this
+ is the file which contains the XML doctype and more). If you do not
+ want this (e.g. because you have a handwritten main XML file), but
+ still want &AutoDoc; to generate a title page for you, you can set this
+ option to false
+
+ document_class
+ -
+ Sets the document class of the resulting PDF. The value can either be a string
+ which has to be the name of the new document class, a list containing this string, or
+ a list of two strings. Then the first one has to be the document class name, the second one
+ the option string ( contained in [ ] ) in &LaTeX;.
+
+ latex_header_file
+ -
+ Replaces the standard header from &GAPDoc; completely with the header in this &LaTeX; file.
+ Please be careful here, and look at &GAPDoc;'s latexheader.tex file for an example.
+
+
+
+ autodoc
+ -
+ This controls whether and how to generate additional XML documentation files
+ by scanning for &AutoDoc; documentation comments.
+
+ The value should be either true, false or a
+ record. If it is a record or true (the latter is
+ equivalent to specifying an empty record), then this feature is
+ enabled. It is also enabled if opt.autodoc is missing but the
+ package depends (directly) on the &AutoDoc; package.
+ In all other cases (in particular if opt.autodoc is
+ false), this feature is disabled.
+
+
+ If opt.autodoc is a record, it may contain the following entries.
+
+
+ files
+ -
+ A list of files (given by paths relative to the package directory)
+ to be scanned for &AutoDoc; documentation comments.
+ Usually it is more convenient to use autodoc.scan_dirs, see below.
+
+ scan_dirs
+ -
+ A list of subdirectories of the package directory (given as relative paths)
+ which &AutoDoc; then scans for .gi, .gd, .g, and .autodoc files; all of these files
+ are then scanned for &AutoDoc; documentation comments.
+
+ Default value: [ ".", "gap", "lib", "examples", "examples/doc" ].
+
+ level
+ -
+ This defines the level of the created documentation. The default value is 0.
+ When parts of the manual are declared with a higher value
+ they will not be printed into the manual.
+
+
+
+ gapdoc
+ -
+ This controls whether and how to invoke &GAPDoc; to create HTML, PDF and text
+ files from your various XML files.
+
+ The value should be either true, false or a
+ record. If it is a record or true (the latter is
+ equivalent to specifying an empty record), then this feature is
+ enabled. It is also enabled if opt.gapdoc is missing.
+ In all other cases (in particular if opt.gapdoc is
+ false), this feature is disabled.
+
+
+ If opt.gapdoc is a record, it may contain the following entries.
+
+
+ main
+ -
+ The name of the main XML file of the package manual.
+ This exists primarily to support packages with existing manual
+ which use a filename here which differs from the default.
+ In particular, specifying this is unnecessary when using scaffolding.
+
+ Default value: PACKAGENAME.xml.
+
+ files
+ -
+ A list of files (given by paths relative to the package directory)
+ to be scanned for &GAPDoc; documentation comments.
+ Usually it is more convenient to use gapdoc.scan_dirs, see below.
+
+ scan_dirs
+ -
+ A list of subdirectories of the package directory (given as relative paths)
+ which &AutoDoc; then scans for .gi, .gd and .g files; all of these files
+ are then scanned for &GAPDoc; documentation comments.
+
+ Default value: [ ".", "gap", "lib", "examples", "examples/doc" ].
+
+ LaTeXOptions
+ -
+ Must be a record with entries which can be understood by
+
. Each entry can be a
+ string, which will be given to &GAPDoc; directly, or a list containing of
+ two entries: The first one must be the string "file", the second one a
+ filename. This file will be read and then its content is passed to &GAPDoc;
+ as option with the name of the entry.
+
+ gap_root_relative_path
+ -
+ Either a boolean, or a string containing a relative path.
+ By default (if this option is not set, or is set to false),
+ references in the generated documentation referring to external documentation
+ (such as the &GAP; manual) are encoded using absolute paths.
+ This is fine as long as the documentation stays on only a single
+ computer, but is problematic when preparing documentation that should be
+ used on multiple computers, e.g., when creating a distribution archive of
+ a &GAP; package.
+ Thus, if a relative path is provided via this option (or if it is set to true,
+ in which case the relative path ../../.. is used), then &AutoDoc;
+ and &GAPDoc; attempt to replace all absolute paths in references to &GAP;
+ manuals by paths based on this relative path.
+
+ On a technical level, &AutoDoc; passes the relative path to the
+ gaproot parameter of
+
+
+
+ extract_examples
+ -
+ Either true or a record.
+ If set to true, then all manual examples are extracted and placed
+ into files tst/PACKAGENAME01.tst, tst/PACKAGENAME02.tst, ...
+ and so on, with one file for each chapter.
+ As a record, the entry can have the following entries itself, to specify some options.
+
+ units
+ -
+ This controls how examples are grouped into files. Recognized values are
+ "Chapter" (default), "Section", "Subsection" or "Single". Depending on the value,
+ one file is created for each chapter, each section, each subsection or each example.
+ For all other values only a single file is created.
+
+ On a technical level, &AutoDoc; passes the value to the
+ units parameter of
.
+
+
+
+ maketest
+ -
+ This option is deprecated. Please use extract_examples instead.
+
+ Either true or a record. When it is true,
+ a simple maketest.g file is created in the main package directory,
+ which can be used to test the examples from the manual. As a record,
+ the entry can have the following entries itself, to specify some options.
+
+ filename
+ -
+ Sets the name of the test file.
+
+ commands
+ -
+ A list of strings, each one a command, which
+ will be executed at the beginning of the test file.
+
+
+
+
+
+
@@ -337,8 +352,8 @@
Examples
-Some basic examples for using AutoDoc were already shown in
-Chapter .
+ Some basic examples for using AutoDoc were already shown in
+ Chapter .
diff -Nru gap-autodoc-2019.05.20/doc/Comments.xml gap-autodoc-2019.09.04/doc/Comments.xml
--- gap-autodoc-2019.05.20/doc/Comments.xml 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/Comments.xml 2020-03-02 09:35:41.000000000 +0000
@@ -122,7 +122,7 @@
#! @Returns a list
#! @Arguments modtbl
#! @Group CharacterDegreesOfBlocks
-#! @FunctionLabel chardegblocks
+#! @Label chardegblocks
#! @ChapterInfo Blocks, Attributes
DeclareAttribute( "CharacterDegreesOfBlocks",
IsBrauerTable );
@@ -197,12 +197,6 @@
can be used to set a heading for the section that is different from name.
-
-@EndSection
-@EndSection
-This command is deprecated. You can simply remove any use of it.
-
-
@Subsection
@SubsectionLabel
@@ -227,38 +221,6 @@
can be used to set a heading for the subsection that is different from name.
-
-@EndSubsection
-@EndSubsection
-This command is deprecated. You can simply remove any use of it.
-
-
-
-@BeginAutoDoc
-@BeginAutoDoc
-Causes all subsequent declarations to be documented in the manual,
-regardless of whether they have an &AutoDoc; comment in front of
-them or not.
-
-
-
-@EndAutoDoc
-@EndAutoDoc
-Ends the effect of @BeginAutoDoc. So from here on, again only declarations
-with an explicit &AutoDoc; comment in front are added to the manual.
-
-
-Both, Operation1 and IsProperty would appear in the manual.
-
-
@BeginGroup
@BeginGroup [grpname]
@@ -294,6 +256,14 @@
]]>
+
+@GroupTitle
+@GroupTitle title
+Sets the subsection heading for the current group to title. In the
+absence of any @GroupTitle command, the heading will be the name of the
+first entry in the group. See for more information.
+
+
@Level
@Level lvl
@@ -318,12 +288,17 @@
@BeginExample
@EndExample
@BeginExample and @EndExample
-@BeginExample inserts an example into the manual. The syntax for examples is different from
-GAPDocs example syntax in order to have a
-file that contains the example and is GAP readable. To achieve this, GAP commands are not preceded by a comment,
+@BeginExample marks the start of an example to be put into the manual.
+It differs from &GAPDoc;'s <Example> (see ),
+in that it expects actual code (not in a comment) interspersed with comments,
+to allow for examples files that can be both executed by &GAP;, and parsed
+by &AutoDoc;. To achieve this, &GAP; commands are not preceded by a comment,
while output has to be preceded by an &AutoDoc; comment.
-The GAP prompt for the display in the manual is added by &AutoDoc;.
+The gap> prompt for the display in the manual is added by &AutoDoc;.
@EndExample ends the example block.
+
+
+To illustrate this command, consider this input:
+This results in the following output:
+
+gap> S5 := SymmetricGroup(5);
+Sym( [ 1 .. 5 ] )
+gap> Order(S5);
+120
+
The &AutoDoc; command @Example is an alias of @BeginExample.
@@ -340,19 +322,12 @@
@BeginExampleSession
@EndExampleSession
@BeginExampleSession and @EndExampleSession
-@BeginExampleSession inserts an example into the manual, but in a different syntax.
-For example, consider
-
-As you can see, the commands are not commented and hence are executed when the file containing
-the example block is read. To insert examples directly into source code files, one can instead
-use @BeginExampleSession:
+@BeginExampleSession marks the start of an example to be put into the manual,
+while @EndExampleSession ends the example block.
+It is the direct analog of &GAPDoc;'s <Example> (see ).
+
+
+To illustrate this command, consider this input:
S5 := SymmetricGroup(5);
@@ -361,6 +336,14 @@
#! 120
#! @EndExampleSession
]]>
+This results in the following output:
+
+gap> S5 := SymmetricGroup(5);
+Sym( [ 1 .. 5 ] )
+gap> Order(S5);
+120
+
+
It inserts an example into the manual just as @Example would do, but all lines are commented
and therefore not executed when the file is read.
All lines that should be part of the example displayed in the manual
@@ -368,18 +351,17 @@
The comment will be removed, and, if the following character is a space,
this space will also be removed. There is never more than one space removed.
To ensure examples are correctly colored in the manual,
-there should be exactly one space between #! and the gap prompt.
+there should be exactly one space between #! and the gap> prompt.
The &AutoDoc; command @ExampleSession is an alias of @BeginExampleSession.
-
@BeginLog
@EndLog
@BeginLog and @EndLog
Works just like the @BeginExample command, but the example
-will not be tested. See the GAPDoc manual for more information.
+will not be tested. See the &GAPDoc; manual for more information.
The &AutoDoc; command @Log is an alias of @BeginLog.
@@ -388,7 +370,8 @@
@EndLogSession
@BeginLogSession and @EndLogSession
Works just like the @BeginExampleSession command, but the example
-will not be tested if manual examples are run. See the GAPDoc manual for more information.
+will not be tested if manual examples are run. It is the direct analog of
+&GAPDoc;'s <Log> (see ).
The &AutoDoc; command @LogSession is an alias of @BeginLogSession.
@@ -396,7 +379,7 @@
@DoNotReadRestOfFile
@DoNotReadRestOfFile
Prevents the rest of the file from being read by the parser. Useful for
-not finished or temporary files.
+unfinished or temporary files.
-
-@BeginSystem name
-@EndSystem
-@InsertSystem name
-@BeginSystem name, @EndSystem, and @InsertSystem name
-These command are deprecated. Please use the chunk commands from subsection
- instead.
-
-
@BeginCode name
@EndCode
@@ -482,7 +456,7 @@
@EndLatexOnly
@LatexOnly text, @BeginLatexOnly, and @EndLatexOnly
Code inserted between @BeginLatexOnly and @EndLatexOnly or after @LatexOnly is only inserted
-in the PDF version of the manual or worksheet. It can hold arbitrary LaTeX-commands.
+in the PDF version of the manual or worksheet. It can hold arbitrary &LaTeX;-commands.
Plain text files
-&AutoDoc; plain text files work exactly like &AutoDoc; comments, except that
-the #! is unnecessary at the beginning of a line which should be
-documented. Files that have the suffix .autodoc will automatically
-regarded as plain text files while the commands @AutoDocPlainText and
-@EndAutoDocPlainText mark parts in plain text files which should be
-regarded as &AutoDoc; parts. All commands can be used like before.
-
+Files that have the suffix .autodoc and are listed in the
+autodoc.files option of , resp. are contained in
+one of the directories listed in autodoc.scan_dirs, are treated as
+&AutoDoc; plain text files. These work exactly like &AutoDoc; comments, except
+that lines do not need to (and in fact, should not) start with #!.
Grouping
-In &GAPDoc;, it is possible to make groups of ManItems, i.e., when documenting
+In &GAPDoc;, it is possible to make groups of manual items, i.e., when documenting
a function, operation, etc., it is possible to group them into suitable chunks.
This can be particularly useful if there are several definitions of an operation
with several different argument types, all doing more or less the same to the arguments.
Then their manual items can be grouped, sharing the same description and return type information.
-Note that it is currently not possible to give a header to the Group in the manual,
-but the generated ManItem heading of the first entry will be used.
+You can give a heading to the group in the manual with the @GroupTitle
+command; if that is not supplied, then the heading of the first manual item
+in the group will be used as the heading.
Note that group names are globally unique throughout the whole manual.
@@ -592,9 +565,12 @@
Moreover, this means that you can add items to a group via the @Group command
in the &AutoDoc; comment of an arbitrary declaration, at any time.
+
+
The following code
+A family of operations
-
- First sentence.
- Second sentence.
- Third sentence.
+First sentence.
+Second sentence.
+Third sentence.
@@ -654,7 +630,7 @@
Markdown-like formatting of text in &AutoDoc;
&AutoDoc; has some convenient ways to insert special format into text, like
-math formulas and lists. The syntax for them are inspired by Markdown and LaTeX,
+math formulas and lists. The syntax for them are inspired by Markdown and &LaTeX;,
but do not follow them strictly. Neither are all features of the Markdown language
supported. The following subsections describe what is possible.
@@ -763,4 +739,28 @@
+
+Deprecated commands
+
+The following commands used to be supported, but should not generally be used anymore.
+They will be removed in a future version of &AutoDoc;.
+
+
+@EndSection
+- You can simply remove any use of this, &AutoDoc; ends sections automatically
+at the start of any new section or chapter.
+@EndSubsection
+- You can simply remove any use of this, &AutoDoc; ends subsections automatically
+at the start of any new subsection, section or chapter.
+@BeginAutoDoc and @EndAutoDoc
+- It suffices to prepend each declaration that is meant to be appear in the
+ manual with a minimal &AutoDoc; comment #!.
+@BeginSystem name, @EndSystem, and @InsertSystem name
+- Please use the chunk commands from subsection
instead.
+@AutoDocPlainText and @EndAutoDocPlainText
+- Use .autodoc files or &AutoDoc; comments instead.
+
+
+
+
Binary files /tmp/tmppIgIdg/h_iTXladRH/gap-autodoc-2019.05.20/doc/manual.pdf and /tmp/tmppIgIdg/pIStm1uT7E/gap-autodoc-2019.09.04/doc/manual.pdf differ
diff -Nru gap-autodoc-2019.05.20/doc/manual.six gap-autodoc-2019.09.04/doc/manual.six
--- gap-autodoc-2019.05.20/doc/manual.six 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/manual.six 2020-03-02 09:35:41.000000000 +0000
@@ -16,47 +16,47 @@
"getting started using autodoc", "X7A0D7AA484F466E1" ],
[
"\033[1X\033[33X\033[0;-2YCreating a package manual from scratch\033[133X\\
-033[101X", "1.1", [ 1, 1, 0 ], 22, 4, "creating a package manual from scratch"
+033[101X", "1.1", [ 1, 1, 0 ], 23, 4, "creating a package manual from scratch"
, "X7BFBC6907B26AA95" ],
[
"\033[1X\033[33X\033[0;-2YDocumenting code with \033[5XAutoDoc\033[105X\\
-033[101X\027\033[1X\027\033[133X\033[101X", "1.2", [ 1, 2, 0 ], 92, 5,
+033[101X\027\033[1X\027\033[133X\033[101X", "1.2", [ 1, 2, 0 ], 94, 5,
"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", "1.3", [ 1, 3, 0 ], 152, 6,
+133X\033[101X", "1.3", [ 1, 3, 0 ], 154, 6,
"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", "1.3-1", [ 1, 3, 1 ], 169, 6,
+33X\033[101X", "1.3-1", [ 1, 3, 1 ], 171, 6,
"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", "1.3-2", [ 1, 3, 2 ], 223, 7,
+\027\033[1X\027 options\033[133X\033[101X", "1.3-2", [ 1, 3, 2 ], 225, 7,
"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", "1.3-3", [ 1, 3, 3 ], 285, 8,
+01X\027\033[1X\027\033[133X\033[101X", "1.3-3", [ 1, 3, 3 ], 287, 8,
"checklist for converting an existing gapdoc manual to use autodoc",
"X83448D91868D7994" ],
[ "\033[1X\033[33X\033[0;-2YScaffolds\033[133X\033[101X", "1.4",
- [ 1, 4, 0 ], 353, 9, "scaffolds", "X8524193D824CDE0D" ],
+ [ 1, 4, 0 ], 355, 9, "scaffolds", "X8524193D824CDE0D" ],
[ "\033[1X\033[33X\033[0;-2YGenerating a title page\033[133X\033[101X",
- "1.4-1", [ 1, 4, 1 ], 356, 9, "generating a title page",
+ "1.4-1", [ 1, 4, 1 ], 358, 9, "generating a title page",
"X7CF22DE28478316F" ],
[ "\033[1X\033[33X\033[0;-2YGenerating the main XML file\033[133X\033[101X",
- "1.4-2", [ 1, 4, 2 ], 405, 10, "generating the main xml file",
+ "1.4-2", [ 1, 4, 2 ], 407, 10, "generating the main xml file",
"X7CD72CC780874FD5" ],
[
"\033[1X\033[33X\033[0;-2YWhat data is extracted from \033[11XPackageInfo.g\
\033[111X\033[101X\027\033[1X\027?\033[133X\033[101X", "1.4-3", [ 1, 4, 3 ],
- 432, 10, "what data is extracted from packageinfo.g?",
+ 434, 10, "what data is extracted from packageinfo.g?",
"X7A3C8A34806ACF30" ],
[ "\033[1X\033[33X\033[0;-2YAutoDoc worksheets\033[133X\033[101X", "1.5",
- [ 1, 5, 0 ], 471, 11, "autodoc worksheets", "X80ED3C2A78146AD1" ],
+ [ 1, 5, 0 ], 473, 11, "autodoc worksheets", "X80ED3C2A78146AD1" ],
[
"\033[1X\033[33X\033[0;-2Y\033[5XAutoDoc\033[105X\033[101X\027\033[1X\027 d\
ocumentation comments\033[133X\033[101X", "2", [ 2, 0, 0 ], 1, 13,
@@ -104,119 +104,104 @@
, "2.2-2", [ 2, 2, 2 ], 156, 15, "section name", "X78AA98BA7E0635D0" ]
,
[
- "\033[1X\033[33X\033[0;-2Y\033[10X@EndSection\033[110X\033[101X\027\033[1X\\
-027\033[133X\033[101X", "2.2-3", [ 2, 2, 3 ], 172, 15, "endsection",
- "X852C1B327A127225" ],
- [
"\033[1X\033[33X\033[0;-2Y\033[10X@Subsection \033[3Xname\033[103X\033[101X\
\027\033[1X\027\033[10X\027\033[110X\033[101X\027\033[1X\027\033[133X\033[101X\
-", "2.2-4", [ 2, 2, 4 ], 177, 16, "subsection name", "X7FD77434802A3580" ],
- [
- "\033[1X\033[33X\033[0;-2Y\033[10X@EndSubsection\033[110X\033[101X\027\033[\
-1X\027\033[133X\033[101X", "2.2-5", [ 2, 2, 5 ], 196, 16, "endsubsection",
- "X83F70B0F85628361" ],
- [
- "\033[1X\033[33X\033[0;-2Y\033[10X@BeginAutoDoc\033[110X\033[101X\027\033[1\
-X\027\033[133X\033[101X", "2.2-6", [ 2, 2, 6 ], 201, 16, "beginautodoc",
- "X7D22AA4485535112" ],
- [
- "\033[1X\033[33X\033[0;-2Y\033[10X@EndAutoDoc\033[110X\033[101X\027\033[1X\\
-027\033[133X\033[101X", "2.2-7", [ 2, 2, 7 ], 207, 16, "endautodoc",
- "X782E748B82E264EB" ],
+", "2.2-3", [ 2, 2, 3 ], 172, 16, "subsection name", "X7FD77434802A3580" ],
[
"\033[1X\033[33X\033[0;-2Y\033[10X@BeginGroup \033[3X[grpname]\033[103X\\
033[101X\027\033[1X\027\033[10X\027\033[110X\033[101X\027\033[1X\027\033[133X\
-\033[101X", "2.2-8", [ 2, 2, 8 ], 225, 16, "begingroup [grpname]",
+\033[101X", "2.2-4", [ 2, 2, 4 ], 191, 16, "begingroup [grpname]",
"X7D3060C17EDBCED1" ],
[
"\033[1X\033[33X\033[0;-2Y\033[10X@EndGroup\033[110X\033[101X\027\033[1X\\
-027\033[133X\033[101X", "2.2-9", [ 2, 2, 9 ], 235, 16, "endgroup",
+027\033[133X\033[101X", "2.2-5", [ 2, 2, 5 ], 201, 16, "endgroup",
"X7C17EB007FD42C87" ],
[
+ "\033[1X\033[33X\033[0;-2Y@GroupTitle \033[3Xtitle\033[103X\033[101X\027\\
+033[1X\027\033[133X\033[101X", "2.2-6", [ 2, 2, 6 ], 221, 16,
+ "grouptitle title", "X82FB96F37FAE8167" ],
+ [
"\033[1X\033[33X\033[0;-2Y\033[10X@Level \033[3Xlvl\033[103X\033[101X\027\\
033[1X\027\033[10X\027\033[110X\033[101X\027\033[1X\027\033[133X\033[101X",
- "2.2-10", [ 2, 2, 10 ], 255, 17, "level lvl", "X7BF81EAF80D1A4B5" ],
+ "2.2-7", [ 2, 2, 7 ], 228, 16, "level lvl", "X7BF81EAF80D1A4B5" ],
[
"\033[1X\033[33X\033[0;-2Y\033[10X@ResetLevel\033[110X\033[101X\027\033[1X\\
-027\033[133X\033[101X", "2.2-11", [ 2, 2, 11 ], 264, 17, "resetlevel",
+027\033[133X\033[101X", "2.2-8", [ 2, 2, 8 ], 237, 17, "resetlevel",
"X7C6723D57F424215" ],
[
"\033[1X\033[33X\033[0;-2Y\033[10X@BeginExample\033[110X\033[101X\027\033[1\
X\027 and \033[10X@EndExample\033[110X\033[101X\027\033[1X\027\033[133X\033[10\
-1X", "2.2-12", [ 2, 2, 12 ], 269, 17, "beginexample and endexample",
+1X", "2.2-9", [ 2, 2, 9 ], 242, 17, "beginexample and endexample",
"X83D6DA3B83D3436C" ],
[
"\033[1X\033[33X\033[0;-2Y\033[10X@BeginExampleSession\033[110X\033[101X\\
027\033[1X\027 and \033[10X@EndExampleSession\033[110X\033[101X\027\033[1X\027\
-\033[133X\033[101X", "2.2-13", [ 2, 2, 13 ], 290, 17,
+\033[133X\033[101X", "2.2-10", [ 2, 2, 10 ], 275, 17,
"beginexamplesession and endexamplesession", "X861E2E778510CAF7" ],
[
"\033[1X\033[33X\033[0;-2Y\033[10X@BeginLog\033[110X\033[101X\027\033[1X\\
027 and \033[10X@EndLog\033[110X\033[101X\027\033[1X\027\033[133X\033[101X",
- "2.2-14", [ 2, 2, 14 ], 328, 18, "beginlog and endlog",
+ "2.2-11", [ 2, 2, 11 ], 312, 18, "beginlog and endlog",
"X81A2D44D834C0A17" ],
[
"\033[1X\033[33X\033[0;-2Y\033[10X@BeginLogSession\033[110X\033[101X\027\\
033[1X\027 and \033[10X@EndLogSession\033[110X\033[101X\027\033[1X\027\033[133\
-X\033[101X", "2.2-15", [ 2, 2, 15 ], 335, 18,
+X\033[101X", "2.2-12", [ 2, 2, 12 ], 319, 18,
"beginlogsession and endlogsession", "X7BADE876794FF309" ],
[
"\033[1X\033[33X\033[0;-2Y\033[10X@DoNotReadRestOfFile\033[110X\033[101X\\
-027\033[1X\027\033[133X\033[101X", "2.2-16", [ 2, 2, 16 ], 343, 18,
+027\033[1X\027\033[133X\033[101X", "2.2-13", [ 2, 2, 13 ], 327, 18,
"donotreadrestoffile", "X78DC644E8519280C" ],
[
"\033[1X\033[33X\033[0;-2Y\033[10X@BeginChunk \033[3Xname\033[103X\033[101X\
\027\033[1X\027\033[10X\027\033[110X\033[101X\027\033[1X\027, \033[10X@EndChun\
k\033[110X\033[101X\027\033[1X\027, and \033[10X@InsertChunk \033[3Xname\033[1\
03X\033[101X\027\033[1X\027\033[10X\027\033[110X\033[101X\027\033[1X\027\033[1\
-33X\033[101X", "2.2-17", [ 2, 2, 17 ], 357, 18,
+33X\033[101X", "2.2-14", [ 2, 2, 14 ], 341, 18,
"beginchunk name endchunk and insertchunk name", "X83C01F9B7FA1C973" ],
- [ "\033[1X\033[33X\033[0;-2Y\033[10X@BeginSystem \033[3Xname\033[103X\033[10\
-1X\027\033[1X\027\033[10X\027\033[110X\033[101X\027\033[1X\027, \033[10X@EndSy\
-stem\033[110X\033[101X\027\033[1X\027, and \033[10X@InsertSystem \033[3Xname\
-\033[103X\033[101X\027\033[1X\027\033[10X\027\033[110X\033[101X\027\033[1X\027\
-\033[133X\033[101X", "2.2-18", [ 2, 2, 18 ], 394, 19,
- "beginsystem name endsystem and insertsystem name", "X7A4DD4A079F58118"
- ],
- [
- "\033[1X\033[33X\033[0;-2Y\033[10X@BeginCode \033[3Xname\033[103X\033[101X\\
-027\033[1X\027\033[10X\027\033[110X\033[101X\027\033[1X\027, @EndCode, and \
+ [ "\033[1X\033[33X\033[0;-2Y\033[10X@BeginCode \033[3Xname\033[103X\033[101X\
+\027\033[1X\027\033[10X\027\033[110X\033[101X\027\033[1X\027, @EndCode, and \
\033[10X@InsertCode \033[3Xname\033[103X\033[101X\027\033[1X\027\033[10X\027\
-\033[110X\033[101X\027\033[1X\027\033[133X\033[101X", "2.2-19", [ 2, 2, 19 ],
- 400, 19, "begincode name endcode and insertcode name",
+\033[110X\033[101X\027\033[1X\027\033[133X\033[101X", "2.2-15", [ 2, 2, 15 ],
+ 378, 19, "begincode name endcode and insertcode name",
"X7D3671AF86B995B9" ],
[
"\033[1X\033[33X\033[0;-2Y\033[10X@LatexOnly \033[3Xtext\033[103X\033[101X\\
027\033[1X\027\033[10X\027\033[110X\033[101X\027\033[1X\027, \033[10X@BeginLat\
exOnly\033[110X\033[101X\027\033[1X\027, and \033[10X@EndLatexOnly\033[110X\
-\033[101X\027\033[1X\027\033[133X\033[101X", "2.2-20", [ 2, 2, 20 ], 416, 19,
+\033[101X\027\033[1X\027\033[133X\033[101X", "2.2-16", [ 2, 2, 16 ], 394, 19,
"latexonly text beginlatexonly and endlatexonly", "X8033B34F80A12A10" ],
[ "\033[1X\033[33X\033[0;-2Y\033[10X@NotLatex \033[3Xtext\033[103X\033[101X\
\027\033[1X\027\033[10X\027\033[110X\033[101X\027\033[1X\027, \033[10X@BeginNo\
tLatex\033[110X\033[101X\027\033[1X\027, and \033[10X@EndNotLatex\033[110X\033\
-[101X\027\033[1X\027\033[133X\033[101X", "2.2-21", [ 2, 2, 21 ], 431, 20,
+[101X\027\033[1X\027\033[133X\033[101X", "2.2-17", [ 2, 2, 17 ], 409, 19,
"notlatex text beginnotlatex and endnotlatex", "X7EF303147F1BCC22" ],
[ "\033[1X\033[33X\033[0;-2YTitle page commands\033[133X\033[101X", "2.3",
- [ 2, 3, 0 ], 446, 20, "title page commands", "X841E3AD584F5385C" ],
+ [ 2, 3, 0 ], 424, 19, "title page commands", "X841E3AD584F5385C" ],
[ "\033[1X\033[33X\033[0;-2YPlain text files\033[133X\033[101X", "2.4",
- [ 2, 4, 0 ], 483, 20, "plain text files", "X828AE38F80CB02E7" ],
+ [ 2, 4, 0 ], 461, 20, "plain text files", "X828AE38F80CB02E7" ],
[ "\033[1X\033[33X\033[0;-2YGrouping\033[133X\033[101X", "2.5",
- [ 2, 5, 0 ], 493, 21, "grouping", "X7D7A38F87BC40C48" ],
+ [ 2, 5, 0 ], 470, 20, "grouping", "X7D7A38F87BC40C48" ],
+ [ "\033[1X\033[33X\033[0;-2YA family of operations\033[133X\033[101X",
+ "2.5-1", [ 2, 5, 1 ], 518, 21, "a family of operations",
+ "X79BF060F8436C586" ],
[ "\033[1X\033[33X\033[0;-2YLevel\033[133X\033[101X", "2.6", [ 2, 6, 0 ],
- 546, 21, "level", "X8209AFDE8209AFDE" ],
+ 527, 21, "level", "X8209AFDE8209AFDE" ],
[
"\033[1X\033[33X\033[0;-2YMarkdown-like formatting of text in \033[5XAutoDo\
c\033[105X\033[101X\027\033[1X\027\033[133X\033[101X", "2.7", [ 2, 7, 0 ],
- 566, 22, "markdown-like formatting of text in autodoc",
+ 547, 22, "markdown-like formatting of text in autodoc",
"X79558A2F7FE187B4" ],
[ "\033[1X\033[33X\033[0;-2YLists\033[133X\033[101X", "2.7-1", [ 2, 7, 1 ],
- 575, 22, "lists", "X7B256AE5780F140A" ],
+ 556, 22, "lists", "X7B256AE5780F140A" ],
[ "\033[1X\033[33X\033[0;-2YMath modes\033[133X\033[101X", "2.7-2",
- [ 2, 7, 2 ], 612, 23, "math modes", "X871412737A0E12E2" ],
+ [ 2, 7, 2 ], 593, 22, "math modes", "X871412737A0E12E2" ],
[ "\033[1X\033[33X\033[0;-2YEmphasize\033[133X\033[101X", "2.7-3",
- [ 2, 7, 3 ], 633, 23, "emphasize", "X7ED0330479146EFC" ],
+ [ 2, 7, 3 ], 614, 23, "emphasize", "X7ED0330479146EFC" ],
[ "\033[1X\033[33X\033[0;-2YInline code\033[133X\033[101X", "2.7-4",
- [ 2, 7, 4 ], 651, 23, "inline code", "X838CCDEB7E0ECEE2" ],
+ [ 2, 7, 4 ], 632, 23, "inline code", "X838CCDEB7E0ECEE2" ],
+ [ "\033[1X\033[33X\033[0;-2YDeprecated commands\033[133X\033[101X", "2.8",
+ [ 2, 8, 0 ], 645, 23, "deprecated commands", "X78CA9E5C7F494C19" ],
[ "\033[1X\033[33X\033[0;-2YAutoDoc worksheets\033[133X\033[101X", "3",
[ 3, 0, 0 ], 1, 24, "autodoc worksheets", "X80ED3C2A78146AD1" ],
[ "\033[1X\033[33X\033[0;-2YWorksheets\033[133X\033[101X", "3.1",
@@ -226,21 +211,21 @@
[ "\033[1X\033[33X\033[0;-2YThe AutoDoc() function\033[133X\033[101X",
"4.1", [ 4, 1, 0 ], 4, 25, "the autodoc function", "X863584DB8497D8BA" ]
, [ "\033[1X\033[33X\033[0;-2YExamples\033[133X\033[101X", "4.2",
- [ 4, 2, 0 ], 300, 29, "examples", "X7A489A5D79DA9E5C" ],
+ [ 4, 2, 0 ], 312, 29, "examples", "X7A489A5D79DA9E5C" ],
[ "Bibliography", "bib", [ "Bib", 0, 0 ], 1, 30, "bibliography",
"X7A6F98FD85F02BFE" ],
[ "References", "bib", [ "Bib", 0, 0 ], 1, 30, "references",
"X7A6F98FD85F02BFE" ],
[ "Index", "ind", [ "Ind", 0, 0 ], 1, 31, "index", "X83A0356F839C696F" ],
- [ "\033[11Xmakedoc.g\033[111X", "1.1", [ 1, 1, 0 ], 22, 4, "makedoc.g",
+ [ "\033[11Xmakedoc.g\033[111X", "1.1", [ 1, 1, 0 ], 23, 4, "makedoc.g",
"X7BFBC6907B26AA95" ],
- [ "", "1.3-3", [ 1, 3, 3 ], 285, 8, "", "X83448D91868D7994" ],
- [ "", "1.3-3", [ 1, 3, 3 ], 285, 8, "", "X83448D91868D7994" ],
- [ "", "1.3-3", [ 1, 3, 3 ], 285, 8, "", "X83448D91868D7994" ],
- [ "", "1.3-3", [ 1, 3, 3 ], 285, 8, "", "X83448D91868D7994" ],
- [ "", "1.3-3", [ 1, 3, 3 ], 285, 8, "", "X83448D91868D7994" ],
- [ "", "1.3-3", [ 1, 3, 3 ], 285, 8, "", "X83448D91868D7994" ],
- [ "", "1.3-3", [ 1, 3, 3 ], 285, 8, "", "X83448D91868D7994" ],
+ [ "", "1.3-3", [ 1, 3, 3 ], 287, 8, "", "X83448D91868D7994" ],
+ [ "", "1.3-3", [ 1, 3, 3 ], 287, 8, "", "X83448D91868D7994" ],
+ [ "", "1.3-3", [ 1, 3, 3 ], 287, 8, "", "X83448D91868D7994" ],
+ [ "", "1.3-3", [ 1, 3, 3 ], 287, 8, "", "X83448D91868D7994" ],
+ [ "", "1.3-3", [ 1, 3, 3 ], 287, 8, "", "X83448D91868D7994" ],
+ [ "", "1.3-3", [ 1, 3, 3 ], 287, 8, "", "X83448D91868D7994" ],
+ [ "", "1.3-3", [ 1, 3, 3 ], 287, 8, "", "X83448D91868D7994" ],
[ "\033[10X@Description \033[3Xdescr\033[103X\033[10X\027\033[110X",
"2.1-1", [ 2, 1, 1 ], 29, 13, "description descr", "X7F1D85188262A827" ]
, [ "\033[10X@Returns \033[3Xret_val\033[103X\033[10X\027\033[110X",
@@ -269,87 +254,73 @@
"sectionlabel", "X78AA98BA7E0635D0" ],
[ "\033[10X@SectionTitle\033[110X", "2.2-2", [ 2, 2, 2 ], 156, 15,
"sectiontitle", "X78AA98BA7E0635D0" ],
- [ "\033[10X@EndSection\033[110X", "2.2-3", [ 2, 2, 3 ], 172, 15,
- "endsection", "X852C1B327A127225" ],
- [ "\033[10X@Subsection\033[110X", "2.2-4", [ 2, 2, 4 ], 177, 16,
+ [ "\033[10X@Subsection\033[110X", "2.2-3", [ 2, 2, 3 ], 172, 16,
"subsection", "X7FD77434802A3580" ],
- [ "\033[10X@SubsectionLabel\033[110X", "2.2-4", [ 2, 2, 4 ], 177, 16,
+ [ "\033[10X@SubsectionLabel\033[110X", "2.2-3", [ 2, 2, 3 ], 172, 16,
"subsectionlabel", "X7FD77434802A3580" ],
- [ "\033[10X@SubsectionTitle\033[110X", "2.2-4", [ 2, 2, 4 ], 177, 16,
+ [ "\033[10X@SubsectionTitle\033[110X", "2.2-3", [ 2, 2, 3 ], 172, 16,
"subsectiontitle", "X7FD77434802A3580" ],
- [ "\033[10X@EndSubsection\033[110X", "2.2-5", [ 2, 2, 5 ], 196, 16,
- "endsubsection", "X83F70B0F85628361" ],
- [ "\033[10X@BeginAutoDoc\033[110X", "2.2-6", [ 2, 2, 6 ], 201, 16,
- "beginautodoc", "X7D22AA4485535112" ],
- [ "\033[10X@EndAutoDoc\033[110X", "2.2-7", [ 2, 2, 7 ], 207, 16,
- "endautodoc", "X782E748B82E264EB" ],
- [ "\033[10X@BeginGroup\033[110X", "2.2-8", [ 2, 2, 8 ], 225, 16,
+ [ "\033[10X@BeginGroup\033[110X", "2.2-4", [ 2, 2, 4 ], 191, 16,
"begingroup", "X7D3060C17EDBCED1" ],
- [ "\033[10X@EndGroup\033[110X", "2.2-9", [ 2, 2, 9 ], 235, 16, "endgroup",
+ [ "\033[10X@EndGroup\033[110X", "2.2-5", [ 2, 2, 5 ], 201, 16, "endgroup",
"X7C17EB007FD42C87" ],
- [ "\033[10X@Level\033[110X", "2.2-10", [ 2, 2, 10 ], 255, 17, "level",
+ [ "\033[10X@GroupTitle\033[110X", "2.2-6", [ 2, 2, 6 ], 221, 16,
+ "grouptitle", "X82FB96F37FAE8167" ],
+ [ "\033[10X@Level\033[110X", "2.2-7", [ 2, 2, 7 ], 228, 16, "level",
"X7BF81EAF80D1A4B5" ],
- [ "\033[10X@ResetLevel\033[110X", "2.2-11", [ 2, 2, 11 ], 264, 17,
+ [ "\033[10X@ResetLevel\033[110X", "2.2-8", [ 2, 2, 8 ], 237, 17,
"resetlevel", "X7C6723D57F424215" ],
- [ "\033[10X@BeginExample\033[110X", "2.2-12", [ 2, 2, 12 ], 269, 17,
+ [ "\033[10X@BeginExample\033[110X", "2.2-9", [ 2, 2, 9 ], 242, 17,
"beginexample", "X83D6DA3B83D3436C" ],
- [ "\033[10X@EndExample\033[110X", "2.2-12", [ 2, 2, 12 ], 269, 17,
+ [ "\033[10X@EndExample\033[110X", "2.2-9", [ 2, 2, 9 ], 242, 17,
"endexample", "X83D6DA3B83D3436C" ],
- [ "\033[10X@BeginExampleSession\033[110X", "2.2-13", [ 2, 2, 13 ], 290, 17,
+ [ "\033[10X@BeginExampleSession\033[110X", "2.2-10", [ 2, 2, 10 ], 275, 17,
"beginexamplesession", "X861E2E778510CAF7" ],
- [ "\033[10X@EndExampleSession\033[110X", "2.2-13", [ 2, 2, 13 ], 290, 17,
+ [ "\033[10X@EndExampleSession\033[110X", "2.2-10", [ 2, 2, 10 ], 275, 17,
"endexamplesession", "X861E2E778510CAF7" ],
- [ "\033[10X@BeginLog\033[110X", "2.2-14", [ 2, 2, 14 ], 328, 18,
+ [ "\033[10X@BeginLog\033[110X", "2.2-11", [ 2, 2, 11 ], 312, 18,
"beginlog", "X81A2D44D834C0A17" ],
- [ "\033[10X@EndLog\033[110X", "2.2-14", [ 2, 2, 14 ], 328, 18, "endlog",
+ [ "\033[10X@EndLog\033[110X", "2.2-11", [ 2, 2, 11 ], 312, 18, "endlog",
"X81A2D44D834C0A17" ],
- [ "\033[10X@BeginLogSession\033[110X", "2.2-15", [ 2, 2, 15 ], 335, 18,
+ [ "\033[10X@BeginLogSession\033[110X", "2.2-12", [ 2, 2, 12 ], 319, 18,
"beginlogsession", "X7BADE876794FF309" ],
- [ "\033[10X@EndLogSession\033[110X", "2.2-15", [ 2, 2, 15 ], 335, 18,
+ [ "\033[10X@EndLogSession\033[110X", "2.2-12", [ 2, 2, 12 ], 319, 18,
"endlogsession", "X7BADE876794FF309" ],
- [ "\033[10X@DoNotReadRestOfFile\033[110X", "2.2-16", [ 2, 2, 16 ], 343, 18,
+ [ "\033[10X@DoNotReadRestOfFile\033[110X", "2.2-13", [ 2, 2, 13 ], 327, 18,
"donotreadrestoffile", "X78DC644E8519280C" ],
[ "\033[10X@BeginChunk \033[3Xname\033[103X\033[10X\027\033[110X",
- "2.2-17", [ 2, 2, 17 ], 357, 18, "beginchunk name", "X83C01F9B7FA1C973"
- ], [ "\033[10X@EndChunk\033[110X", "2.2-17", [ 2, 2, 17 ], 357, 18,
+ "2.2-14", [ 2, 2, 14 ], 341, 18, "beginchunk name", "X83C01F9B7FA1C973"
+ ], [ "\033[10X@EndChunk\033[110X", "2.2-14", [ 2, 2, 14 ], 341, 18,
"endchunk", "X83C01F9B7FA1C973" ],
[ "\033[10X@InsertChunk \033[3Xname\033[103X\033[10X\027\033[110X",
- "2.2-17", [ 2, 2, 17 ], 357, 18, "insertchunk name",
+ "2.2-14", [ 2, 2, 14 ], 341, 18, "insertchunk name",
"X83C01F9B7FA1C973" ],
- [ "\033[10X@BeginSystem \033[3Xname\033[103X\033[10X\027\033[110X",
- "2.2-18", [ 2, 2, 18 ], 394, 19, "beginsystem name",
- "X7A4DD4A079F58118" ],
- [ "\033[10X@EndSystem\033[110X", "2.2-18", [ 2, 2, 18 ], 394, 19,
- "endsystem", "X7A4DD4A079F58118" ],
- [ "\033[10X@InsertSystem \033[3Xname\033[103X\033[10X\027\033[110X",
- "2.2-18", [ 2, 2, 18 ], 394, 19, "insertsystem name",
- "X7A4DD4A079F58118" ],
- [ "\033[10X@BeginCode \033[3Xname\033[103X\033[10X\027\033[110X", "2.2-19",
- [ 2, 2, 19 ], 400, 19, "begincode name", "X7D3671AF86B995B9" ],
- [ "\033[10X@EndCode\033[110X", "2.2-19", [ 2, 2, 19 ], 400, 19, "endcode",
+ [ "\033[10X@BeginCode \033[3Xname\033[103X\033[10X\027\033[110X", "2.2-15",
+ [ 2, 2, 15 ], 378, 19, "begincode name", "X7D3671AF86B995B9" ],
+ [ "\033[10X@EndCode\033[110X", "2.2-15", [ 2, 2, 15 ], 378, 19, "endcode",
"X7D3671AF86B995B9" ],
[ "\033[10X@InsertCode \033[3Xname\033[103X\033[10X\027\033[110X",
- "2.2-19", [ 2, 2, 19 ], 400, 19, "insertcode name", "X7D3671AF86B995B9"
+ "2.2-15", [ 2, 2, 15 ], 378, 19, "insertcode name", "X7D3671AF86B995B9"
], [ "\033[10X@LatexOnly \033[3Xtext\033[103X\033[10X\027\033[110X",
- "2.2-20", [ 2, 2, 20 ], 416, 19, "latexonly text", "X8033B34F80A12A10" ]
- , [ "\033[10X@BeginLatexOnly\033[110X", "2.2-20", [ 2, 2, 20 ], 416, 19,
+ "2.2-16", [ 2, 2, 16 ], 394, 19, "latexonly text", "X8033B34F80A12A10" ]
+ , [ "\033[10X@BeginLatexOnly\033[110X", "2.2-16", [ 2, 2, 16 ], 394, 19,
"beginlatexonly", "X8033B34F80A12A10" ],
- [ "\033[10X@EndLatexOnly\033[110X", "2.2-20", [ 2, 2, 20 ], 416, 19,
+ [ "\033[10X@EndLatexOnly\033[110X", "2.2-16", [ 2, 2, 16 ], 394, 19,
"endlatexonly", "X8033B34F80A12A10" ],
- [ "\033[10X@NotLatex \033[3Xtext\033[103X\033[10X\027\033[110X", "2.2-21",
- [ 2, 2, 21 ], 431, 20, "notlatex text", "X7EF303147F1BCC22" ],
- [ "\033[10X@BeginNotLatex\033[110X", "2.2-21", [ 2, 2, 21 ], 431, 20,
+ [ "\033[10X@NotLatex \033[3Xtext\033[103X\033[10X\027\033[110X", "2.2-17",
+ [ 2, 2, 17 ], 409, 19, "notlatex text", "X7EF303147F1BCC22" ],
+ [ "\033[10X@BeginNotLatex\033[110X", "2.2-17", [ 2, 2, 17 ], 409, 19,
"beginnotlatex", "X7EF303147F1BCC22" ],
- [ "\033[10X@EndNotLatex\033[110X", "2.2-21", [ 2, 2, 21 ], 431, 20,
+ [ "\033[10X@EndNotLatex\033[110X", "2.2-17", [ 2, 2, 17 ], 409, 19,
"endnotlatex", "X7EF303147F1BCC22" ],
- [ "\033[2XFirstOperation\033[102X for isint", "2.5-1", [ 2, 5, 1 ], 538,
- 21, "firstoperation for isint", "X859517FC87560167" ],
+ [ "\033[2XFirstOperation\033[102X for isint", "2.5-1", [ 2, 5, 1 ], 518,
+ 21, "firstoperation for isint", "X79BF060F8436C586" ],
[ "\033[2XSecondOperation\033[102X for isint, isgroup", "2.5-1",
- [ 2, 5, 1 ], 538, 21, "secondoperation for isint isgroup",
- "X859517FC87560167" ],
+ [ 2, 5, 1 ], 518, 21, "secondoperation for isint isgroup",
+ "X79BF060F8436C586" ],
[ "\033[2XThirdOperation\033[102X for isgroup, isint", "2.5-1",
- [ 2, 5, 1 ], 538, 21, "thirdoperation for isgroup isint",
- "X859517FC87560167" ],
+ [ 2, 5, 1 ], 518, 21, "thirdoperation for isgroup isint",
+ "X79BF060F8436C586" ],
[ "\033[2XAutoDocWorksheet\033[102X", "3.1-1", [ 3, 1, 1 ], 7, 24,
"autodocworksheet", "X809FE4137C08B28D" ],
[ "\033[2XAutoDoc\033[102X", "4.1-1", [ 4, 1, 1 ], 7, 25, "autodoc",
diff -Nru gap-autodoc-2019.05.20/doc/title.xml gap-autodoc-2019.09.04/doc/title.xml
--- gap-autodoc-2019.05.20/doc/title.xml 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/title.xml 2020-03-02 09:35:41.000000000 +0000
@@ -9,7 +9,7 @@
Generate documentation from &GAP; source code
- 2019.05.20
+ 2019.09.04
Sebastian Gutsche
@@ -38,7 +38,7 @@
- 20 May 2019
+ 4 September 2019
&AutoDoc; is a &GAP; package whose purpose is to aid &GAP; package authors in creating and maintaining the documentation of their packages.
diff -Nru gap-autodoc-2019.05.20/doc/Tutorials.xml gap-autodoc-2019.09.04/doc/Tutorials.xml
--- gap-autodoc-2019.05.20/doc/Tutorials.xml 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/doc/Tutorials.xml 2020-03-02 09:35:41.000000000 +0000
@@ -3,8 +3,9 @@
&AutoDoc; is a &GAP; package which is meant to aid &GAP; package
authors in creating and maintaining the documentation of their packages.
-In this capacity it builds upon &GAPDoc;, and is not a replacement
-for &GAPDoc;, but rather complements it.
+In this capacity it builds upon the &GAPDoc; package (see
+https://www.gap-system.org/Packages/gapdoc.html).
+As such, it is not a replacement for &GAPDoc;, but rather complements it.
In this chapter we describe how to get started using &AutoDoc; for your
package. First, we explain in Section how to write a
@@ -70,11 +71,13 @@
not yet able to automate that for you, more research on artificial intelligence
is required).
To add more content, you have several options: You could add further &GAPDoc;
-XML files containing extra chapters, sections and so on. Or you could use classic &GAPDoc;
-source comments (in either case, see Section on
-how to teach the command to include this extra documentation).
-Or you could use the special documentation facilities &AutoDoc; provides (see Section
-).
+XML files containing extra chapters, sections and so on. Or you could use
+classic &GAPDoc; source comments. For details on either, please refer to
+, as well as Section
+ of this manual on how to teach the
+ command to include this extra documentation.
+Or you could use the special documentation facilities &AutoDoc; provides
+(see Section ).
You will probably want to re-run the command
@@ -166,7 +169,7 @@
documentation comments. Just make sure to first edit the main XML
file of your documentation, and insert the line
-#Include SYSTEM "_AutoDocMainFile.xml"
+<#Include SYSTEM "_AutoDocMainFile.xml">
in a suitable place. This means that you can mix &AutoDoc; documentation
comment freely with your existing documentation; you can even still make
@@ -216,7 +219,7 @@
all your .g, .gd, and .gi files.
Suppose the main XML file is named PACKAGENAME.xml and is in the
/doc subdirectory of your package. Then you can rebuild your manual
-by executing the following two GAP commands from a GAP sessions started
+by executing the following two &GAP; commands from a &GAP; sessions started
started in the root directory of your package:
LoadPackage( "AutoDoc" );
@@ -584,7 +587,7 @@
#! @EndExample
Now, one can create a PDF and HTML document, like a package documentation out of it. Suppose the document above
-is saved as worksheet.g. Then, when GAP is started in the directory of this file, the command
+is saved as worksheet.g. Then, when &GAP; is started in the directory of this file, the command
AutoDocWorksheet( "worksheet.g" );
diff -Nru gap-autodoc-2019.05.20/gap/AutoDocMainFunction.gi gap-autodoc-2019.09.04/gap/AutoDocMainFunction.gi
--- gap-autodoc-2019.05.20/gap/AutoDocMainFunction.gi 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/gap/AutoDocMainFunction.gi 2020-03-02 09:35:41.000000000 +0000
@@ -79,53 +79,48 @@
fi;
if not IsBound( opt.entities ) then
- opt.entities := rec();
+ entities := rec();
+ elif IsList( opt.entities ) then
+ entities := rec();
+ for i in opt.entities do
+ if IsString( i ) then
+ ent := i;
+ val := Concatenation("", ent, "");
+ else
+ ent := i[2];
+ val := Concatenation("<", i[1], ">", ent, "", i[1], ">");
+ fi;
+ entities.(ent) := val;
+ od;
+ elif IsRecord( opt.entities ) then
+ entities := opt.entities;
+ else
+ Error("CreateMainPage: must be a list or a record");
fi;
# add book_name unconditionally to the list of entities
- if IsRecord( opt.entities ) then
- if not IsBound(opt.entities.(book_name)) then
- opt.entities.(book_name) := Concatenation( "", book_name, "" );
- fi;
- else
- Add( opt.entities, book_name );
+ if not IsBound(entities.(book_name)) then
+ entities.(book_name) := Concatenation( "", book_name, "" );
fi;
+ # for backwards compatibility: add &see; entity
+ if not IsBound(entities.see) then
+ entities.see := """$\to$-->""";
+ fi;
+
+ # open the target XML file
if IsBound( opt.main_xml_file ) then
filename := opt.main_xml_file;
else
filename := Concatenation( book_name, ".xml" );
fi;
-
filestream := AUTODOC_OutputTextFile( dir, filename );
+ # output the initial file header
AppendTo( filestream, AUTODOC_XML_HEADER );
AppendTo( filestream, "$\to$-->'>\n" );
-
- if IsList( opt.entities ) then
- entities := rec();
- for i in opt.entities do
- ## allow generic entities.
- if IsString( i ) and PositionSublist( i, "!ENTITY" ) <> fail then
- AppendTo( filestream, i );
- AppendTo( filestream, "\n" );
- continue;
- fi;
-
- if IsString( i ) then
- ent := i;
- val := Concatenation("", ent, "");
- else
- ent := i[2];
- val := Concatenation("<", i[1], ">", ent, "", i[1], ">");
- fi;
- entities.(ent) := val;
- od;
- else
- entities := opt.entities;
- fi;
+ # output all entities
for ent in RecNames(entities) do
val := String(entities.(ent));
@@ -136,8 +131,9 @@
AppendTo( filestream, "\n" );
od;
-
AppendTo( filestream, "]\n>\n" );
+
+ # now start the actual book
AppendTo( filestream, "\n" );
AppendTo( filestream, "<#Include SYSTEM \"title.xml\">\n" );
if not IsBound( opt.table_of_contents ) or opt.table_of_contents <> false then
@@ -279,14 +275,24 @@
fi;
if IsBound( argument_rec.Date ) then
- # try to parse the date in format DD/MM/YYYY
+ # try to parse the date in format DD/MM/YYYY (we also accept single
+ # digit day or month, which is formally not allowed in PackageInfo.g,
+ # but happens in a few legacy packages)
+ argument_rec.Date := Chomp( argument_rec.Date ); # remove trailing newlines, if present
i := SplitString( argument_rec.Date, "/" );
if Length( argument_rec.Date ) in [8..10] and Length( i ) = 3 then
i := List(i, Int);
OutWithTag( "Date", AUTODOC_FormatDate(i[3], i[2], i[1]) );
else
- Print("Warning: could not parse package date '", argument_rec.Date, "\n");
- OutWithTag( "Date", argument_rec.Date );
+ # try to parse the date in ISO8601 format YYYY-MM-DD (here we are strict)
+ i := SplitString( argument_rec.Date, "-" );
+ if Length( argument_rec.Date ) = 10 and Length( i ) = 3 then
+ i := List(i, Int);
+ OutWithTag( "Date", AUTODOC_FormatDate(i[1], i[2], i[3]) );
+ else
+ Print("Warning: could not parse package date '", argument_rec.Date, "'\n");
+ OutWithTag( "Date", argument_rec.Date );
+ fi;
fi;
fi;
@@ -464,7 +470,7 @@
# from some other input.
#
""");
- AppendTo(output, "gap> START_TEST( \"", basename, "\");\n");
+ AppendTo(output, "gap> START_TEST( \"", basename, "\");\n\n");
for a in ch do
location := a[2][1];
if StartsWith(location, pkgdirString) then
@@ -482,8 +488,17 @@
fi;
fi;
fi;
- AppendTo(output, "\n# ", comment, ":", a[2][2], "-", a[2][3], a[1]);
+ AppendTo(output, "# ", comment, ":", a[2][2], "-", a[2][3]);
+ if not StartsWith(a[1], "\n") then
+ AppendTo(output, "\n");
+ fi;
+ if not EndsWith(a[1], "\n") then
+ AppendTo(output, a[1], "\n\n");
+ else
+ AppendTo(output, a[1], "\n");
+ fi;
od;
+ AppendTo(output, "#\n");
AppendTo(output, "gap> STOP_TEST(\"", basename, "\", 1 );\n");
Print("extracted ", Length(ch), " examples\n");
od;
diff -Nru gap-autodoc-2019.05.20/gap/DocumentationTree.gd gap-autodoc-2019.09.04/gap/DocumentationTree.gd
--- gap-autodoc-2019.05.20/gap/DocumentationTree.gd 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/gap/DocumentationTree.gd 2020-03-02 09:35:41.000000000 +0000
@@ -34,7 +34,6 @@
DeclareOperation( "IsEmptyNode", [ IsString ] );
DeclareAttribute( "Label", IsTreeForDocumentationNode );
DeclareAttribute( "ChapterInfo", IsTreeForDocumentationNode );
-DeclareAttribute( "DummyName", IsTreeForDocumentationNode );
DeclareAttribute( "GroupName", IsTreeForDocumentationNode );
######################################
@@ -48,12 +47,8 @@
DeclareOperation( "ChapterInTree", [ IsTreeForDocumentation, IsString ] );
DeclareOperation( "SectionInTree", [ IsTreeForDocumentation, IsString, IsString ] );
DeclareOperation( "SubsectionInTree", [ IsTreeForDocumentation, IsString, IsString, IsString ] );
-DeclareOperation( "DocumentationExample", [ IsTreeForDocumentation, IsList ] );
DeclareOperation( "DocumentationExample", [ IsTreeForDocumentation ] );
-DeclareOperation( "DocumentationDummy", [ IsTreeForDocumentation, IsString, IsList ] );
-DeclareOperation( "DocumentationDummy", [ IsTreeForDocumentation, IsString ] );
-DeclareOperation( "DocumentationCode", [ IsTreeForDocumentation, IsString, IsList ] );
-DeclareOperation( "DocumentationCode", [ IsTreeForDocumentation, IsString ] );
+DeclareOperation( "DocumentationChunk", [ IsTreeForDocumentation, IsString ] );
DeclareOperation( "DocumentationManItem", [ IsTreeForDocumentation ] );
DeclareOperation( "SetManItemToDescription", [ IsTreeForDocumentationNode ] );
DeclareOperation( "SetManItemToReturnValue", [ IsTreeForDocumentationNode ] );
@@ -73,7 +68,7 @@
##
#######################################
-DeclareOperation( "WriteDocumentation", [ IsTreeForDocumentation, IsDirectory ] );
-DeclareOperation( "WriteDocumentation", [ IsTreeForDocumentationNode, IsStream ] );
-DeclareOperation( "WriteDocumentation", [ IsList, IsStream ] );
-DeclareOperation( "WriteDocumentation", [ IsTreeForDocumentationNode, IsStream, IsDirectory ] );
+DeclareOperation( "WriteDocumentation", [ IsTreeForDocumentation, IsDirectory, IsInt ] );
+DeclareOperation( "WriteDocumentation", [ IsTreeForDocumentationNode, IsStream, IsInt ] );
+DeclareOperation( "WriteDocumentation", [ IsList, IsStream, IsInt ] );
+DeclareOperation( "WriteDocumentation", [ IsTreeForDocumentationNode, IsStream, IsDirectory, IsInt ] );
diff -Nru gap-autodoc-2019.05.20/gap/DocumentationTree.gi gap-autodoc-2019.09.04/gap/DocumentationTree.gi
--- gap-autodoc-2019.05.20/gap/DocumentationTree.gi 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/gap/DocumentationTree.gi 2020-03-02 09:35:41.000000000 +0000
@@ -87,13 +87,13 @@
IsTreeForDocumentationNodeForGroupRep ) );
## DeclareRepresentation
-DeclareRepresentation( "IsTreeForDocumentationDummyNodeRep",
+DeclareRepresentation( "IsTreeForDocumentationChunkNodeRep",
IsTreeForDocumentationNodeRep,
[ ] );
-BindGlobal( "TheTypeOfDocumentationTreeDummyNodes",
+BindGlobal( "TheTypeOfDocumentationTreeChunkNodes",
NewType( TheFamilyOfDocumentationTreeNodes,
- IsTreeForDocumentationDummyNodeRep ) );
+ IsTreeForDocumentationChunkNodeRep ) );
## DeclareRepresentation
DeclareRepresentation( "IsTreeForDocumentationExampleNodeRep",
@@ -104,14 +104,6 @@
NewType( TheFamilyOfDocumentationTreeNodes,
IsTreeForDocumentationExampleNodeRep ) );
-DeclareRepresentation( "IsTreeForDocumentationCodeNodeRep",
- IsTreeForDocumentationNodeRep,
- [ ] );
-
-BindGlobal( "TheTypeOfDocumentationTreeCodeNodes",
- NewType( TheFamilyOfDocumentationTreeNodes,
- IsTreeForDocumentationCodeNodeRep ) );
-
###################################
##
## Tools
@@ -166,7 +158,8 @@
nodes_by_label := rec( ),
node_name_iterator := 0,
current_level := 0,
- TitlePage := rec( )
+ TitlePage := rec( ),
+ chunks := rec( ),
);
ObjectifyWithAttributes( tree, TheTypeOfDocumentationTrees );
return tree;
@@ -208,16 +201,6 @@
end );
##
-InstallMethod( DocumentationExample, [ IsTreeForDocumentation, IsList ],
- function( tree, context )
- local node;
-
- node := DocumentationExample( tree );
- Add( tree, node, context );
- return node;
-end );
-
-##
InstallMethod( DocumentationExample, [ IsTreeForDocumentation ],
function( tree )
local node, label;
@@ -232,60 +215,18 @@
end );
##
-InstallMethod( DocumentationDummy, [ IsTreeForDocumentation, IsString, IsList ],
- function( tree, name, context )
- local node;
-
- node := DocumentationDummy( tree, name );
- Add( tree, node, context );
- return node;
-end );
-
-##
-InstallMethod( DocumentationDummy, [ IsTreeForDocumentation, IsString ],
+InstallMethod( DocumentationChunk, [ IsTreeForDocumentation, IsString ],
function( tree, name )
local node;
- name := Concatenation( "System_", name );
- if IsBound( tree!.nodes_by_label.( name ) ) then
- return tree!.nodes_by_label.( name );
+ if IsBound( tree!.chunks.( name ) ) then
+ return tree!.chunks.( name );
fi;
node := rec( content := [ ],
level := tree!.current_level );
- ObjectifyWithAttributes( node, TheTypeOfDocumentationTreeDummyNodes,
+ ObjectifyWithAttributes( node, TheTypeOfDocumentationTreeChunkNodes,
Label, name );
- tree!.nodes_by_label.( name ) := node;
- return node;
-end );
-
-##
-InstallMethod( DocumentationCode, [ IsTreeForDocumentation, IsString, IsList ],
- function( tree, name, context )
- local node;
-
- node := DocumentationGroup( tree, name );
- Add( tree, node, context );
- return node;
-end );
-
-##
-InstallMethod( DocumentationCode, [ IsTreeForDocumentation, IsString ],
- function( tree, name )
- local node;
-
- name := Concatenation( "System_", name );
-
- node := rec( content := [ ],
- level := tree!.current_level );
-
- ObjectifyWithAttributes( node, TheTypeOfDocumentationTreeCodeNodes,
- Label, name );
-
- if IsBound( tree!.nodes_by_label.( name ) ) then
- Add( tree!.nodes_by_label.( name )!.content, node );
- fi;
-
- tree!.nodes_by_label.( name ) := node;
+ tree!.chunks.( name ) := node;
return node;
end );
@@ -449,9 +390,32 @@
##
#############################################
+BindGlobal( "WriteChunks",
+ function( tree, path_to_xmlfiles, level_value )
+ local chunks_stream, filename, chunk_names, current_chunk_name,
+ current_chunk;
+
+ filename := "_Chunks.xml";
+
+ chunks_stream := AUTODOC_OutputTextFile( path_to_xmlfiles, filename );
+ chunk_names := RecNames( tree!.chunks );
+
+ for current_chunk_name in chunk_names do
+ current_chunk := tree!.chunks.( current_chunk_name );
+ AppendTo( chunks_stream, "<#GAPDoc Label=\"", current_chunk_name, "\">\n" );
+ if IsBound( current_chunk!.content ) then
+ WriteDocumentation( current_chunk!.content, chunks_stream, level_value );
+ fi;
+ AppendTo( chunks_stream, "\n<#/GAPDoc>\n" );
+ od;
+
+ CloseStream( chunks_stream );
+
+end );
+
##
-InstallMethod( WriteDocumentation, [ IsTreeForDocumentation, IsDirectory ],
- function( tree, path_to_xmlfiles )
+InstallMethod( WriteDocumentation, [ IsTreeForDocumentation, IsDirectory, IsInt ],
+ function( tree, path_to_xmlfiles, level_value )
local stream, i;
stream := AUTODOC_OutputTextFile( path_to_xmlfiles, _AUTODOC_GLOBAL_OPTION_RECORD.AutoDocMainFile );
@@ -461,8 +425,11 @@
Error( "this should never happen" );
fi;
## FIXME: If there is anything else than a chapter, this will break!
- WriteDocumentation( i, stream, path_to_xmlfiles );
+ WriteDocumentation( i, stream, path_to_xmlfiles, level_value );
od;
+
+ WriteChunks( tree, path_to_xmlfiles, level_value );
+
# Workaround for issue #65
if IsEmpty( tree!.content ) then
AppendTo( stream, " \n" );
@@ -471,11 +438,11 @@
end );
##
-InstallMethod( WriteDocumentation, [ IsTreeForDocumentationNodeForChapterRep, IsStream, IsDirectory ],
- function( node, stream, path_to_xmlfiles )
+InstallMethod( WriteDocumentation, [ IsTreeForDocumentationNodeForChapterRep, IsStream, IsDirectory, IsInt ],
+ function( node, stream, path_to_xmlfiles, level_value )
local filename, chapter_stream, label, replaced_name, additional_label;
- if node!.level > ValueOption( "level_value" ) then
+ if node!.level > level_value then
return;
fi;
if ForAll( node!.content, IsEmptyNode ) then
@@ -504,14 +471,14 @@
AppendTo( chapter_stream, AUTODOC_XML_HEADER );
AppendTo( chapter_stream, "\n" );
AppendTo( chapter_stream, Concatenation( [ "", replaced_name, "\n\n" ] ) );
- WriteDocumentation( node!.content, chapter_stream );
+ WriteDocumentation( node!.content, chapter_stream, level_value );
AppendTo( chapter_stream, "\n\n" );
CloseStream( chapter_stream );
end );
##
-InstallMethod( WriteDocumentation, [ IsList, IsStream ],
- function( node_list, filestream )
+InstallMethod( WriteDocumentation, [ IsList, IsStream, IsInt ],
+ function( node_list, filestream, level_value )
local current_string_list, i, last_position;
i := 1;
@@ -522,38 +489,38 @@
else
if current_string_list <> [ ] then
current_string_list := CONVERT_LIST_OF_STRINGS_IN_MARKDOWN_TO_GAPDOC_XML( current_string_list );
- Perform( current_string_list, function( i ) WriteDocumentation( i, filestream ); end );
+ Perform( current_string_list, function( i ) WriteDocumentation( i, filestream, level_value ); end );
current_string_list := [ ];
fi;
- WriteDocumentation( node_list[ i ], filestream );
+ WriteDocumentation( node_list[ i ], filestream, level_value );
AppendTo( filestream, "\n" );
fi;
od;
if current_string_list <> [ ] then
current_string_list := CONVERT_LIST_OF_STRINGS_IN_MARKDOWN_TO_GAPDOC_XML( current_string_list );
- Perform( current_string_list, function( i ) WriteDocumentation( i, filestream ); end );
+ Perform( current_string_list, function( i ) WriteDocumentation( i, filestream, level_value ); end );
fi;
end );
##
-InstallMethod( WriteDocumentation, [ IsString, IsStream ],
- function( text, filestream )
+InstallMethod( WriteDocumentation, [ IsString, IsStream, IsInt ],
+ function( text, filestream, level_value )
## In case the list is empty, do nothing.
## Once the empty string = empty list bug is fixed,
## this could be removed.
- text := NormalizedWhitespace( text );
- if text = "" then
+ text := Chomp( text );
+ if NormalizedWhitespace( text ) = "" then
return;
fi;
AppendTo( filestream, text, "\n" );
end );
##
-InstallMethod( WriteDocumentation, [ IsTreeForDocumentationNodeForSectionRep, IsStream ],
- function( node, filestream )
+InstallMethod( WriteDocumentation, [ IsTreeForDocumentationNodeForSectionRep, IsStream, IsInt ],
+ function( node, filestream, level_value )
local replaced_name, label, additional_label;
- if node!.level > ValueOption( "level_value" ) then
+ if node!.level > level_value then
return;
fi;
if ForAll( node!.content, IsEmptyNode ) then
@@ -573,16 +540,16 @@
AppendTo( filestream, "\n" );
AppendTo( filestream, Concatenation( [ "", replaced_name, "\n\n" ] ) );
- WriteDocumentation( node!.content, filestream );
+ WriteDocumentation( node!.content, filestream, level_value );
AppendTo( filestream, "\n\n" );
end );
##
-InstallMethod( WriteDocumentation, [ IsTreeForDocumentationNodeForSubsectionRep, IsStream ],
- function( node, filestream )
+InstallMethod( WriteDocumentation, [ IsTreeForDocumentationNodeForSubsectionRep, IsStream, IsInt ],
+ function( node, filestream, level_value )
local replaced_name, label, additional_label;
- if node!.level > ValueOption( "level_value" ) then
+ if node!.level > level_value then
return;
fi;
if ForAll( node!.content, IsEmptyNode ) then
@@ -602,42 +569,48 @@
AppendTo( filestream, "\n" );
AppendTo( filestream, Concatenation( [ "", replaced_name, "\n\n" ] ) );
- WriteDocumentation( node!.content, filestream );
+ WriteDocumentation( node!.content, filestream, level_value );
AppendTo( filestream, "\n\n" );
end );
##
-InstallMethod( WriteDocumentation, [ IsTreeForDocumentationNodeForManItemRep, IsStream ],
- function( node, filestream )
- if node!.level > ValueOption( "level_value" ) then
+InstallMethod( WriteDocumentation, [ IsTreeForDocumentationNodeForManItemRep, IsStream, IsInt ],
+ function( node, filestream, level_value )
+ if node!.level > level_value then
return;
fi;
- AutoDoc_WriteDocEntry( filestream, [ node ] );
+ AutoDoc_WriteDocEntry( filestream, [ node ], fail, level_value );
end );
##
-InstallMethod( WriteDocumentation, [ IsTreeForDocumentationNodeForGroupRep, IsStream ],
- function( node, filestream )
- if node!.level > ValueOption( "level_value" ) then
+InstallMethod( WriteDocumentation, [ IsTreeForDocumentationNodeForGroupRep, IsStream, IsInt ],
+ function( node, filestream, level_value )
+ local heading;
+ if node!.level > level_value then
return;
fi;
- AutoDoc_WriteDocEntry( filestream, node!.content );
+ heading := fail;
+ if IsBound( node!.title_string ) then
+ heading := node!.title_string;
+ fi;
+ AutoDoc_WriteDocEntry( filestream, node!.content, heading, level_value );
end );
##
-InstallMethod( WriteDocumentation, [ IsTreeForDocumentationDummyNodeRep, IsStream ],
- function( node, filestream )
- if IsBound( node!.content ) then
- WriteDocumentation( node!.content, filestream );
+InstallMethod( WriteDocumentation, [ IsTreeForDocumentationChunkNodeRep, IsStream, IsInt ],
+ function( node, filestream, level_value )
+ if node!.level > level_value then
+ return;
fi;
+ WriteDocumentation( Concatenation( "<#Include Label=\"", Label( node ), "\">" ), filestream, level_value );
end );
##
-InstallMethod( WriteDocumentation, [ IsTreeForDocumentationExampleNodeRep, IsStream ],
- function( node, filestream )
+InstallMethod( WriteDocumentation, [ IsTreeForDocumentationExampleNodeRep, IsStream, IsInt ],
+ function( node, filestream, level_value )
local contents, i, tested, inserted_string;
- if node!.level > ValueOption( "level_value" ) then
+ if node!.level > level_value then
return;
fi;
contents := node!.content;
@@ -655,25 +628,3 @@
od;
AppendTo( filestream, "]]>", inserted_string, ">\n\n" );
end );
-
-##
-InstallMethod( WriteDocumentation, [ IsTreeForDocumentationCodeNodeRep, IsStream ],
- function( node, filestream )
- local content, i;
-
- if node!.level > ValueOption( "level_value" ) then
- return;
- fi;
-
- content := node!.content;
-
- if content = [ ] then
- return;
- fi;
-
- AppendTo( filestream, "\n" );
-end );
diff -Nru gap-autodoc-2019.05.20/gap/Magic.gd gap-autodoc-2019.09.04/gap/Magic.gd
--- gap-autodoc-2019.05.20/gap/Magic.gd 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/gap/Magic.gd 2020-03-02 09:35:41.000000000 +0000
@@ -11,7 +11,7 @@
#! @Description
#! This is the main function of the &AutoDoc; package. It can perform
-#! any combination of the following three tasks:
+#! any combination of the following tasks:
#!
#! -
#! It can (re)generate a scaffold for your package manual.
@@ -49,17 +49,29 @@
#! The parameters have the following meanings:
#!
#!
-#! package
+#! packageOrDirectory
#! -
-#! This is either the name of package, or an IsDirectory object.
-#! In the former case, &AutoDoc; uses the metadata of the first package
-#! with that name known to &GAP;. In the latter case, it checks whether
-#! the given directory contains a PackageInfo.g file, and extracts
-#! all needed metadata from that. This is for example useful if you have
-#! multiple versions of the package around and want to make sure the
+#! 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 IsDirectory 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 InstallationPath specified in that
+#! metadata as the package directory. If packageOrDirectory is
+#! an 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
+#! PackageInfo.g file, and &AutoDoc; extracts all needed metadata
+#! from that. The 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.
#!
-#! If this argument is omitted, &AutoDoc; uses the DirectoryCurrent().
+#! Note that when using AutoDocWorksheet (see
+#!
), there is
+#! no parameter corresponding to packageOrDirectory and so the
+#! package directory
is always the current directory, and
+#! there is no metadata.
#!
#!
#!
@@ -70,9 +82,13 @@
#!
#! dir
#! -
-#! This should be a string containing a (relative) path or a
-#! Directory() object specifying where the package documentation
-#! (i.e. the &GAPDoc; XML files) are stored.
+#! This should either be a string, in which case it must be a path
+#! relative to the specified package directory, or a
+#! Directory() object. (Thus, the only way to designate an
+#! absolute directory is with a Directory() object.) This
+#! option specifies where the package documentation
+#! (e.g. the &GAPDoc; XML or the manual PDF, etc.) files are stored
+#! and/or will be generated.
#!
#! Default value: "doc/".
#!
@@ -171,12 +187,12 @@
#! Sets the document class of the resulting PDF. The value can either be a string
#! which has to be the name of the new document class, a list containing this string, or
#! a list of two strings. Then the first one has to be the document class name, the second one
-#! the option string ( contained in [ ] ) in LaTeX.
+#! the option string ( contained in [ ] ) in &LaTeX;.
#!
#! latex_header_file
#! -
-#! Replaces the standard header from &GAPDoc; completely with the header in this LaTeX file.
-#! Please be careful here, and look at GAPDoc's latexheader.tex file for an example.
+#! Replaces the standard header from &GAPDoc; completely with the header in this &LaTeX; file.
+#! Please be careful here, and look at &GAPDoc;'s latexheader.tex file for an example.
#!
#!
#!
@@ -185,7 +201,7 @@
#!
#! autodoc
#! -
-#! This controls whether and how to generate addition XML documentation files
+#! This controls whether and how to generate additional XML documentation files
#! by scanning for &AutoDoc; documentation comments.
#!
#! The value should be either true, false or a
@@ -305,14 +321,14 @@
#! Either a boolean, or a string containing a relative path.
#! By default (if this option is not set, or is set to false),
#! references in the generated documentation referring to external documentation
-#! (such as the GAP manual) are encoded using absolute paths.
+#! (such as the &GAP; manual) are encoded using absolute paths.
#! This is fine as long as the documentation stays on only a single
#! computer, but is problematic when preparing documentation that should be
#! used on multiple computers, e.g., when creating a distribution archive of
-#! a GAP package.
+#! a &GAP; package.
#! Thus, if a relative path is provided via this option (or if it is set to true,
#! in which case the relative path ../../.. is used), then &AutoDoc;
-#! and &GAPDoc; attempt to replace all absolute paths in references to GAP
+#! and &GAPDoc; attempt to replace all absolute paths in references to &GAP;
#! manuals by paths based on this relative path.
#!
#! On a technical level, &AutoDoc; passes the relative path to the
@@ -338,8 +354,7 @@
#! For all other values only a single file is created.
#!
#! On a technical level, &AutoDoc; passes the value to the
-#! units parameter of .
+#! units parameter of .
#!
#!
#!
@@ -369,7 +384,7 @@
#!
#!
#! @Returns nothing
-#! @Arguments [package[, optrec ]]
+#! @Arguments [packageOrDirectory], [optrec]
DeclareGlobalFunction( "AutoDoc" );
diff -Nru gap-autodoc-2019.05.20/gap/Magic.gi gap-autodoc-2019.09.04/gap/Magic.gi
--- gap-autodoc-2019.05.20/gap/Magic.gi 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/gap/Magic.gi 2020-03-02 09:35:41.000000000 +0000
@@ -270,10 +270,6 @@
if not IsBound( autodoc.level ) then
autodoc.level := 0;
fi;
-
- # This causes a bug. If a new layer is pushed to the option stack in a function that is called with options,
- # this layer will be deleted at the end of the method, not the layer which was created when the method was called.
-# PushOptions( rec( level_value := autodoc.level ) );
fi;
#
@@ -322,7 +318,7 @@
gapdoc.files := [];
elif not IsList( gapdoc.files ) then
Error("gapdoc.files must be a list");
- elif Length(gapdoc.files) >0 and IsString( gapdoc.files ) then
+ elif not ForAll( gapdoc.files, IsString ) then
Error("gapdoc.files must be a list of strings, not a string");
fi;
@@ -348,6 +344,7 @@
tmp := Number( Filename( doc_dir_rel, "" ), x -> x = '/' );
tmp := Concatenation( ListWithIdenticalEntries(tmp, "../") );
gapdoc.files := List( gapdoc.files, f -> Concatenation( tmp, f ) );
+ Add( gapdoc.files, "_Chunks.xml" );
else
# Here presumably the doc_dir was given by an absolute path that
# does not lie below the package dir. In that case, we can't make
@@ -355,6 +352,7 @@
# choice but to make them absolute, which MakeGAPDocDoc can handle,
# even if perhaps less gracefully/portably.
gapdoc.files := List( gapdoc.files, f -> Filename( pkgdir, f ) );
+ Add( gapdoc.files, Filename( doc_dir, "_Chunks.xml" ) );
fi;
fi;
@@ -488,7 +486,6 @@
if IsBound( scaffold.TitlePage ) and scaffold.TitlePage <> false then
title_page := ShallowCopy( scaffold.TitlePage );
- AUTODOC_SetIfMissing( title_page, "dir", doc_dir );
AUTODOC_MergeRecords( title_page, tree!.TitlePage );
if not is_worksheet then
@@ -512,7 +509,7 @@
# Write AutoDoc XML files
#
if IsBound( autodoc ) then
- WriteDocumentation( tree, doc_dir : level_value := autodoc.level );
+ WriteDocumentation( tree, doc_dir, autodoc.level );
fi;
diff -Nru gap-autodoc-2019.05.20/gap/Parser.gi gap-autodoc-2019.09.04/gap/Parser.gi
--- gap-autodoc-2019.05.20/gap/Parser.gi 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/gap/Parser.gi 2020-03-02 09:35:41.000000000 +0000
@@ -63,7 +63,15 @@
function( current_item, type, default_chapter_data )
local item_rec, entries, has_filters, ret_val;
item_rec := current_item;
- if PositionSublist( type, "DeclareCategory" ) <> fail then
+ if PositionSublist( type, "DeclareCategoryCollections") <> fail then
+ entries := [ "Filt", "categories" ];
+ ret_val := "true or false";
+ has_filters := "No";
+ if not IsBound( item_rec!.arguments ) then
+ item_rec!.arguments := "obj";
+ fi;
+ item_rec!.coll_suffix := true;
+ elif PositionSublist( type, "DeclareCategory" ) <> fail then
entries := [ "Filt", "categories" ];
ret_val := "true or false";
has_filters := 1;
@@ -117,7 +125,6 @@
return fail;
fi;
item_rec!.item_type := entries[ 1 ];
- item_rec!.doc_stream_type := entries[ 2 ];
if not IsBound( item_rec!.chapter_info ) or item_rec!.chapter_info = [ ] then
item_rec!.chapter_info := default_chapter_data.( entries[ 2 ] );
fi;
@@ -133,7 +140,7 @@
local current_item, flush_and_recover, chapter_info, current_string_list,
Scan_for_Declaration_part, flush_and_prepare_for_item, current_line, filestream,
level_scope, scope_group, read_example, command_function_record, autodoc_read_line,
- current_command, was_declaration, filename, system_scope, groupnumber, chunk_list, rest_of_file_skipped,
+ current_command, was_declaration, filename, system_scope, groupnumber, rest_of_file_skipped,
context_stack, new_man_item, add_man_item, Reset, read_code, title_item, title_item_list, plain_text_mode,
current_line_unedited, deprecated,
ReadLineWithLineCount, Normalized_ReadLine, line_number, ErrorWithPos, create_title_item_function,
@@ -211,25 +218,25 @@
end;
Scan_for_Declaration_part := function()
local declare_position, current_type, filter_string, has_filters,
- position_parentesis, nr_of_attr_loops, i;
+ position_parenthesis, nr_of_attr_loops, i;
## fail is bigger than every integer
declare_position := Minimum( [ PositionSublist( current_line, "Declare" ), PositionSublist( current_line, "KeyDependentOperation" ) ] );
if declare_position <> fail then
current_item := new_man_item();
current_line := current_line{[ declare_position .. Length( current_line ) ]};
- position_parentesis := PositionSublist( current_line, "(" );
- if position_parentesis = fail then
+ position_parenthesis := PositionSublist( current_line, "(" );
+ if position_parenthesis = fail then
ErrorWithPos( "Something went wrong" );
fi;
- current_type := current_line{ [ 1 .. position_parentesis - 1 ] };
+ current_type := current_line{ [ 1 .. position_parenthesis - 1 ] };
has_filters := AutoDoc_Type_Of_Item( current_item, current_type, default_chapter_data );
if has_filters = fail then
ErrorWithPos( "Unrecognized scan type" );
return false;
fi;
- current_line := current_line{ [ position_parentesis + 1 .. Length( current_line ) ] };
- ## Not the funny part begins:
+ current_line := current_line{ [ position_parenthesis + 1 .. Length( current_line ) ] };
+ ## Now the funny part begins:
## try fetching the name:
## Assuming the name is in the same line as its
while PositionSublist( current_line, "," ) = fail and PositionSublist( current_line, ");" ) = fail do
@@ -238,6 +245,27 @@
current_line := StripBeginEnd( current_line, " " );
current_item!.name := current_line{ [ 1 .. Minimum( [ PositionSublist( current_line, "," ), PositionSublist( current_line, ");" ) ] ) - 1 ] };
current_item!.name := StripBeginEnd( ReplacedString( current_item!.name, "\"", "" ), " " );
+
+ # Deal with DeclareCategoryCollections: this has some special
+ # rules on how the name of a new category is derived from the
+ # string given to it. Since the code for that is not available in
+ # a separate GAP function, we have to replicate this logic here.
+ # To understand what's going on, please refer to the
+ # DeclareCategoryCollections documentation and implementation.
+ if IsBound(current_item!.coll_suffix) then
+ if EndsWith(current_item!.name, "Collection") then
+ current_item!.name :=
+ current_item!.name{[1..Length(current_item!.name)-6]};
+ fi;
+ if EndsWith(current_item!.name, "Coll") then
+ current_item!.coll_suffix := "Coll";
+ else
+ current_item!.coll_suffix := "Collection";
+ fi;
+ current_item!.name := Concatenation(current_item!.name,
+ current_item!.coll_suffix);
+ fi;
+
current_line := current_line{ [ Minimum( [ PositionSublist( current_line, "," ), PositionSublist( current_line, ");" ) ] ) + 1 .. Length( current_line ) ] };
filter_string := "for ";
## FIXME: The next two if's can be merged at some point
@@ -315,33 +343,32 @@
## Fail is larger than every integer.
if declare_position <> fail then
current_item := new_man_item();
- current_item!.item_type := "Func";
- current_item!.doc_stream_type := "operations";
+ current_item!.item_type := "Oper";
##Find name
- position_parentesis := PositionSublist( current_line, "(" );
- current_line := current_line{ [ position_parentesis + 1 .. Length( current_line ) ] };
+ position_parenthesis := PositionSublist( current_line, "(" );
+ current_line := current_line{ [ position_parenthesis + 1 .. Length( current_line ) ] };
## find next colon
current_item!.name := "";
while PositionSublist( current_line, "," ) = fail do
Append( current_item!.name, current_line );
current_line := Normalized_ReadLine( filestream );
od;
- position_parentesis := PositionSublist( current_line, "," );
- Append( current_item!.name, current_line{[ 1 .. position_parentesis - 1 ]} );
+ position_parenthesis := PositionSublist( current_line, "," );
+ Append( current_item!.name, current_line{[ 1 .. position_parenthesis - 1 ]} );
NormalizeWhitespace( current_item!.name );
current_item!.name := StripBeginEnd( current_item!.name, " " );
while AUTODOC_PositionElementIfNotAfter( current_line, '[', '\\' ) = fail do
current_line := Normalized_ReadLine( filestream );
od;
- position_parentesis := AUTODOC_PositionElementIfNotAfter( current_line, '[', '\\' );
- current_line := current_line{[ position_parentesis + 1 .. Length( current_line ) ]};
+ position_parenthesis := AUTODOC_PositionElementIfNotAfter( current_line, '[', '\\' );
+ current_line := current_line{[ position_parenthesis + 1 .. Length( current_line ) ]};
filter_string := "for ";
while PositionSublist( current_line, "]" ) = fail do
Append( filter_string, current_line );
od;
- position_parentesis := AUTODOC_PositionElementIfNotAfter( current_line, ']', '\\' );
- Append( filter_string, current_line{[ 1 .. position_parentesis - 1 ]} );
- current_line := current_line{[ position_parentesis + 1 .. Length( current_line )]};
+ position_parenthesis := AUTODOC_PositionElementIfNotAfter( current_line, ']', '\\' );
+ Append( filter_string, current_line{[ 1 .. position_parenthesis - 1 ]} );
+ current_line := current_line{[ position_parenthesis + 1 .. Length( current_line )]};
NormalizeWhitespace( filter_string );
if IsString( filter_string ) then
filter_string := ReplacedString( filter_string, "\"", "" );
@@ -354,17 +381,17 @@
while PositionSublist( current_line, "function(" ) = fail and PositionSublist( current_line, ");" ) = fail do
current_line := Normalized_ReadLine( filestream );
od;
- position_parentesis := PositionSublist( current_line, "function(" );
- if position_parentesis <> fail then
- current_line := current_line{[ position_parentesis + 9 .. Length( current_line ) ]};
+ position_parenthesis := PositionSublist( current_line, "function(" );
+ if position_parenthesis <> fail then
+ current_line := current_line{[ position_parenthesis + 9 .. Length( current_line ) ]};
filter_string := "";
while PositionSublist( current_line, ")" ) = fail do;
current_line := StripBeginEnd( current_line, " " );
Append( filter_string, current_line );
current_line := Normalized_ReadLine( current_line );
od;
- position_parentesis := PositionSublist( current_line, ")" );
- Append( filter_string, current_line{[ 1 .. position_parentesis - 1 ]} );
+ position_parenthesis := PositionSublist( current_line, ")" );
+ Append( filter_string, current_line{[ 1 .. position_parenthesis - 1 ]} );
NormalizeWhitespace( filter_string );
filter_string := StripBeginEnd( filter_string, " " );
current_item!.arguments := filter_string;
@@ -381,7 +408,7 @@
end;
read_code := function( )
local code, temp_curr_line, comment_pos, before_comment;
- code := [ ];
+ code := [ "\n" );
return code;
end;
read_example := function( is_tested_example )
@@ -445,14 +473,12 @@
od;
return example_node;
end;
- read_session_example := function( is_tested_example )
- local temp_string_list, temp_curr_line, temp_pos_comment, is_following_line, item_temp, example_node;
+ read_session_example := function( is_tested_example, plain_text_mode )
+ local temp_string_list, temp_curr_line, temp_pos_comment,
+ is_following_line, item_temp, example_node,
+ incorporate_this_line;
example_node := DocumentationExample( tree );
- if is_tested_example = false then
- example_node!.is_tested_example := false;
- else
- example_node!.is_tested_example := true;
- fi;
+ example_node!.is_tested_example := is_tested_example;
temp_string_list := example_node!.content;
while true do
temp_curr_line := ReadLineWithLineCount( filestream );
@@ -463,13 +489,19 @@
or PositionSublist( temp_curr_line, "@EndLogSession" ) <> fail then
break;
fi;
- #! @DONT_SCAN_NEXT_LINE
- temp_pos_comment := PositionSublist( temp_curr_line, "#!" );
- if temp_pos_comment <> fail then
- temp_curr_line := temp_curr_line{[ temp_pos_comment + 2 .. Length( temp_curr_line ) ]};
- if Length( temp_curr_line ) >= 1 and temp_curr_line[ 1 ] = ' ' then
- Remove( temp_curr_line, 1 );
+ incorporate_this_line := plain_text_mode;
+ if not plain_text_mode then
+ #! @DONT_SCAN_NEXT_LINE
+ temp_pos_comment := PositionSublist( temp_curr_line, "#!" );
+ if temp_pos_comment <> fail then
+ incorporate_this_line := true;
+ temp_curr_line := temp_curr_line{[ temp_pos_comment + 2 .. Length( temp_curr_line ) ]};
+ if Length( temp_curr_line ) >= 1 and temp_curr_line[ 1 ] = ' ' then
+ Remove( temp_curr_line, 1 );
+ fi;
fi;
+ fi;
+ if incorporate_this_line then
Add( temp_string_list, temp_curr_line );
fi;
od;
@@ -494,13 +526,14 @@
Reset();
rest_of_file_skipped := true;
end,
- @BeginAutoDoc := function()
+ @BeginAutoDoc := deprecated("@BeginAutoDoc", function()
autodoc_read_line := fail;
- end,
+ end),
@AutoDoc := ~.@BeginAutoDoc,
- @EndAutoDoc := function()
+ @EndAutoDoc := deprecated("@EndAutoDoc", function()
autodoc_read_line := false;
- end,
+ end),
+
@Chapter := function()
local scope_chapter;
scope_chapter := ReplacedString( current_command[ 2 ], " ", "_" );
@@ -524,6 +557,7 @@
scope_chapter := ChapterInTree( tree, chapter_info[ 1 ] );
scope_chapter!.title_string := current_command[ 2 ];
end,
+
@Section := function()
local scope_section;
if not IsBound( chapter_info[ 1 ] ) then
@@ -552,10 +586,14 @@
scope_section!.title_string := current_command[ 2 ];
end,
@EndSection := deprecated("@EndSection", function()
+ if not IsBound( chapter_info[ 2 ] ) then
+ ErrorWithPos( "found @EndSection with no active section" );
+ fi;
Unbind( chapter_info[ 2 ] );
Unbind( chapter_info[ 3 ] );
current_item := ChapterInTree( tree, chapter_info[ 1 ] );
end),
+
@Subsection := function()
local scope_subsection;
if not IsBound( chapter_info[ 1 ] ) or not IsBound( chapter_info[ 2 ] ) then
@@ -568,7 +606,7 @@
@SubsectionLabel := function()
local scope_subsection, label_name;
if not IsBound( chapter_info[ 3 ] ) then
- ErrorWithPos( "found @SubsectionLabel with no active Subsection" );
+ ErrorWithPos( "found @SubsectionLabel with no active subsection" );
fi;
label_name := ReplacedString( current_command[ 2 ], " ", "_" );
scope_subsection := SubsectionInTree( tree, chapter_info[ 1 ], chapter_info[ 2 ], chapter_info[ 3 ] );
@@ -577,15 +615,19 @@
@SubsectionTitle := function()
local scope_subsection;
if not IsBound( chapter_info[ 3 ] ) then
- ErrorWithPos( "found @SubsectionTitle with no active section" );
+ ErrorWithPos( "found @SubsectionTitle with no active subsection" );
fi;
scope_subsection := SubsectionInTree( tree, chapter_info[ 1 ], chapter_info[ 2 ], chapter_info[ 3 ] );
scope_subsection!.title_string := current_command[ 2 ];
end,
@EndSubsection := deprecated("@EndSubsection", function()
+ if not IsBound( chapter_info[ 3 ] ) then
+ ErrorWithPos( "found @EndSubsection with no active subsection" );
+ fi;
Unbind( chapter_info[ 3 ] );
current_item := SectionInTree( tree, chapter_info[ 1 ], chapter_info[ 2 ] );
end),
+
@BeginGroup := function()
local grp;
if current_command[ 2 ] = "" then
@@ -626,6 +668,28 @@
group_name := ReplacedString( current_command[ 2 ], " ", "_" );
SetGroupName( current_item, group_name );
end,
+ @GroupTitle := function()
+ local group_name, chap_info, group_obj;
+ current_item := new_man_item();
+ if not HasGroupName( current_item ) then
+ ErrorWithPos( "found @GroupTitle with no Group set" );
+ fi;
+ group_name := GroupName( current_item );
+ chap_info := fail;
+ if HasChapterInfo( current_item ) then
+ chap_info := ChapterInfo( current_item );
+ elif IsBound( current_item!.chapter_info ) then
+ chap_info := current_item!.chapter_info;
+ fi;
+ if chap_info = fail or Length( chap_info ) = 0 then
+ chap_info := chapter_info;
+ fi;
+ if Length( chap_info ) <> 2 then
+ ErrorWithPos( "can only set @GroupTitle within a Chapter and Section.");
+ fi;
+ group_obj := DocumentationGroup( tree, group_name, chap_info );
+ group_obj!.title_string := current_command[ 2 ];
+ end,
@ChapterInfo := function()
local current_chapter_info;
current_item := new_man_item();
@@ -647,13 +711,17 @@
end,
@InsertChunk := function()
- Add( current_item, DocumentationDummy( tree, current_command[ 2 ] ) );
+ local label_name;
+ label_name := ReplacedString( current_command[ 2 ], " ", "_" );
+ Add( current_item, DocumentationChunk( tree, label_name ) );
end,
@BeginChunk := function()
+ local label_name;
if IsBound( current_item ) then
Add( context_stack, current_item );
fi;
- current_item := DocumentationDummy( tree, current_command[ 2 ] );
+ label_name := ReplacedString( current_command[ 2 ], " ", "_" );
+ current_item := DocumentationChunk( tree, label_name );
end,
@Chunk := ~.@BeginChunk,
@EndChunk := function()
@@ -673,8 +741,9 @@
@EndSystem := deprecated("@EndSystem", ~.@EndChunk),
@BeginCode := function()
- local tmp_system;
- tmp_system := DocumentationCode( tree, current_command[ 2 ] );
+ local label_name, tmp_system;
+ label_name := ReplacedString( current_command[ 2 ], " ", "_" );
+ tmp_system := DocumentationChunk( tree, label_name );
Append( tmp_system!.content, read_code() );
end,
@Code := ~.@BeginCode,
@@ -746,22 +815,22 @@
NormalizeWhitespace( current_command[ 2 ] );
Add( tree!.worksheet_dependencies, SplitString( current_command[ 2 ], " " ) );
end,
- @BeginAutoDocPlainText := function()
+ @BeginAutoDocPlainText := deprecated("@BeginAutoDocPlainText", function()
plain_text_mode := true;
- end,
+ end),
@AutoDocPlainText := ~.@BeginAutoDocPlainText,
- @EndAutoDocPlainText := function()
+ @EndAutoDocPlainText := deprecated("@EndAutoDocPlainText", function()
plain_text_mode := false;
- end,
+ end),
@ExampleSession := function()
local example_node;
- example_node := read_session_example( true );
+ example_node := read_session_example( true, plain_text_mode );
Add( current_item, example_node );
end,
@BeginExampleSession := ~.@ExampleSession,
@LogSession := function()
local example_node;
- example_node := read_session_example( false );
+ example_node := read_session_example( false, plain_text_mode );
Add( current_item, example_node );
end,
@BeginLogSession := ~.@LogSession
diff -Nru gap-autodoc-2019.05.20/gap/ToolFunctions.gi gap-autodoc-2019.09.04/gap/ToolFunctions.gi
--- gap-autodoc-2019.05.20/gap/ToolFunctions.gi 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/gap/ToolFunctions.gi 2020-03-02 09:35:41.000000000 +0000
@@ -49,7 +49,7 @@
##
InstallGlobalFunction( AutoDoc_WriteDocEntry,
- function( filestream, list_of_records )
+ function( filestream, list_of_records, heading, level_value )
local return_value, description, current_description, labels, i;
# look for a good return value (it should be the same everywhere)
@@ -102,7 +102,12 @@
od;
AppendTo( filestream, ">\n" );
- # Function heades
+ # Next possibly the heading for the entry
+ if IsString( heading ) then
+ AppendTo( filestream, "", heading, "\n" );
+ fi;
+
+ # Function headers
for i in list_of_records do
AppendTo( filestream, " <", i!.item_type, " " );
if i!.arguments <> fail and i!.item_type <> "Var" then
@@ -120,12 +125,12 @@
return_value := [ return_value ];
fi;
AppendTo( filestream, " " );
- WriteDocumentation( return_value, filestream );
+ WriteDocumentation( return_value, filestream, level_value );
AppendTo( filestream, "\n" );
fi;
AppendTo( filestream, " \n" );
- WriteDocumentation( description, filestream );
+ WriteDocumentation( description, filestream, level_value );
AppendTo( filestream, " \n" );
AppendTo( filestream, "\n\n" );
diff -Nru gap-autodoc-2019.05.20/.mailmap gap-autodoc-2019.09.04/.mailmap
--- gap-autodoc-2019.05.20/.mailmap 1970-01-01 00:00:00.000000000 +0000
+++ gap-autodoc-2019.09.04/.mailmap 2020-03-02 09:35:41.000000000 +0000
@@ -0,0 +1 @@
+Sebastian Gutsche
diff -Nru gap-autodoc-2019.05.20/PackageInfo.g gap-autodoc-2019.09.04/PackageInfo.g
--- gap-autodoc-2019.05.20/PackageInfo.g 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/PackageInfo.g 2020-03-02 09:35:41.000000000 +0000
@@ -10,7 +10,7 @@
PackageName := "AutoDoc",
Subtitle := "Generate documentation from GAP source code",
-Version := "2019.05.20",
+Version := "2019.09.04",
Date := ~.Version{[ 1 .. 10 ]},
Date := Concatenation( ~.Date{[ 9, 10 ]}, "/", ~.Date{[ 6, 7 ]}, "/", ~.Date{[ 1 .. 4 ]} ),
diff -Nru gap-autodoc-2019.05.20/README.md gap-autodoc-2019.09.04/README.md
--- gap-autodoc-2019.05.20/README.md 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/README.md 2020-03-02 09:35:41.000000000 +0000
@@ -1,3 +1,6 @@
+[![Build Status](https://travis-ci.org/gap-packages/AutoDoc.svg?branch=master)](https://travis-ci.org/gap-packages/AutoDoc)
+[![Code Coverage](https://codecov.io/github/gap-packages/AutoDoc/coverage.svg?branch=master&token=)](https://codecov.io/gh/gap-packages/AutoDoc)
+
# AutoDoc: A GAP package to help creating a GAPDoc documentation.
AutoDoc is a package for the [GAP](https://www.gap-system.org) computer
diff -Nru gap-autodoc-2019.05.20/tst/manual.expected/_Chapter_AutoDoc_worksheets.xml gap-autodoc-2019.09.04/tst/manual.expected/_Chapter_AutoDoc_worksheets.xml
--- gap-autodoc-2019.05.20/tst/manual.expected/_Chapter_AutoDoc_worksheets.xml 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/manual.expected/_Chapter_AutoDoc_worksheets.xml 2020-03-02 09:35:41.000000000 +0000
@@ -10,12 +10,12 @@
-The intention of these function is to create stand-alone pdf and html files
-using AutoDoc without having them associated to a package.
-It uses the same optional records as the &AutoDoc; command itself, but instead of
-a package name there should be a filename or a list of filenames containing AutoDoc
-text from which the documents are created. Please see the &AutoDoc; command for more
-information about this and have a look at for a simple worksheet example.
+ The intention of these function is to create stand-alone pdf and html files
+ using AutoDoc without having them associated to a package.
+ It uses the same optional records as the &AutoDoc; command itself, but instead of
+ a package name there should be a filename or a list of filenames containing AutoDoc
+ text from which the documents are created. Please see the &AutoDoc; command for more
+ information about this and have a look at for a simple worksheet example.
diff -Nru gap-autodoc-2019.05.20/tst/manual.expected/_Chapter_AutoDoc.xml gap-autodoc-2019.09.04/tst/manual.expected/_Chapter_AutoDoc.xml
--- gap-autodoc-2019.05.20/tst/manual.expected/_Chapter_AutoDoc.xml 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/manual.expected/_Chapter_AutoDoc.xml 2020-03-02 09:35:41.000000000 +0000
@@ -8,323 +8,338 @@
The AutoDoc() function
-
+
nothing
-This is the main function of the &AutoDoc; package. It can perform
-any combination of the following three tasks:
-
--
-It can (re)generate a scaffold for your package manual.
-That is, it can produce two XML files in &GAPDoc; format to be used as part
-of your manual: First, a file named doc/PACKAGENAME.xml
-(with your package's name substituted) which is used as
-main XML file for the package manual, i.e. this file sets the
-XML doctype and defines various XML entities, includes
-other XML files (both those generated by &AutoDoc; as well
-as additional files created by other means), tells &GAPDoc;
-to generate a table of content and an index, and more.
-Secondly, it creates a file doc/title.xml containing a title
-page for your documentation, with information about your package
-(name, description, version), its authors and more, based
-on the data in your PackageInfo.g.
-
--
-It can scan your package for &AutoDoc; based documentation (by using &AutoDoc;
-tags and the Autodoc command.
-This will
-produce further XML files to be used as part of the package manual.
-
--
-It can use &GAPDoc; to generate PDF, text and HTML (with
-MathJaX enabled) documentation from the &GAPDoc; XML files it
-generated as well as additional such files provided by you. For
-this, it invokes
-to convert the XML sources, and it also instructs &GAPDoc; to copy
-supplementary files (such as CSS style files) into your doc directory
-(see ).
-
-
-For more information and some examples, please refer to Chapter .
-
-The parameters have the following meanings:
-
-package
--
-This is either the name of package, or an IsDirectory object.
-In the former case, &AutoDoc; uses the metadata of the first package
-with that name known to &GAP;. In the latter case, it checks whether
-the given directory contains a PackageInfo.g file, and extracts
-all needed metadata from that. This 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.
-
-If this argument is omitted, &AutoDoc; uses the DirectoryCurrent().
-
-optrec
--
-optrec can be a record with some additional options.
-The following are currently supported:
-
-dir
--
-This should be a string containing a (relative) path or a
-Directory() object specifying where the package documentation
-(i.e. the &GAPDoc; XML files) are stored.
-
-Default value: "doc/".
-
-scaffold
--
-This controls whether and how to generate scaffold XML files
-for the package documentation.
-
-The value should be either true, false or a
-record. If it is a record or true (the latter is
-equivalent to specifying an empty record), then this feature is
-enabled. It is also enabled if opt.scaffold is missing but the
-package's info record in PackageInfo.g has an AutoDoc entry.
-In all other cases (in particular if opt.scaffold is
-false), scaffolding is disabled.
-
-If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is
-assumed to be a record, and its contents are used as default values for
-the scaffold settings.
-
-
-If opt.scaffold is a record, it may contain the following entries.
-
-
-includes
--
-A list of XML files to be included in the body of the main XML file.
-If you specify this list and also are using &AutoDoc; to document
-your operations with &AutoDoc; comments,
-you can add _AutoDocMainFile.xml to this list
-to control at which point the documentation produced by &AutoDoc;
-is inserted. If you do not do this, it will be added after the last
-of your own XML files.
-
-index
--
-By default, the scaffold creates an index. If you do not want an index,
-set this to false.
-
-appendix
--
-This entry is similar to opt.scaffold.includes but is used
-to specify files to include after the main body of the manual,
-i.e. typically appendices.
-
-bib
--
-The name of a bibliography file, in BibTeX or XML format.
-If this key is not set, but there is a file doc/PACKAGENAME.bib
-then it is assumed that you want to use this as your bibliography.
-
-entities
--
-A record whose keys are taken as entity names, set to the corresponding
-(string) values. For example, if you pass the record
SomePackage
,
-SomePackage",
-RELEASEYEAR := "2015" )]]>
-then the following entity definitions are added to the XML preamble:
-SomePackage'>
-]]>
-This allows you to write &SomePackage;
and &RELEASEYEAR;
-in your documentation, which will be replaced by respective values specified
-in the entities definition.
-
-TitlePage
--
-A record whose entries are used to embellish the generated title page
-for the package manual with extra information, such as a copyright
-statement or acknowledgments. To this end, the names of the record
-components are used as XML element names, and the values of the
-components are outputted as content of these XML elements. For
-example, you could pass the following record to set a custom
-acknowledgements text:
-
-For a list of valid entries in the title page, please refer to the
-&GAPDoc; manual, specifically section
.
-
-MainPage
--
-If scaffolding is enabled, by default a main XML file is generated (this
-is the file which contains the XML doctype and more). If you do not
-want this (e.g. because you have a handwritten main XML file), but
-still want &AutoDoc; to generate a title page for you, you can set this
-option to false
-
-document_class
--
-Sets the document class of the resulting PDF. The value can either be a string
-which has to be the name of the new document class, a list containing this string, or
-a list of two strings. Then the first one has to be the document class name, the second one
-the option string ( contained in [ ] ) in LaTeX.
-
-latex_header_file
--
-Replaces the standard header from &GAPDoc; completely with the header in this LaTeX file.
-Please be careful here, and look at GAPDoc's latexheader.tex file for an example.
-
-
-
-autodoc
--
-This controls whether and how to generate addition XML documentation files
-by scanning for &AutoDoc; documentation comments.
-
-The value should be either true, false or a
-record. If it is a record or true (the latter is
-equivalent to specifying an empty record), then this feature is
-enabled. It is also enabled if opt.autodoc is missing but the
-package depends (directly) on the &AutoDoc; package.
-In all other cases (in particular if opt.autodoc is
-false), this feature is disabled.
-
-
-If opt.autodoc is a record, it may contain the following entries.
-
-
-files
--
-A list of files (given by paths relative to the package directory)
-to be scanned for &AutoDoc; documentation comments.
-Usually it is more convenient to use autodoc.scan_dirs, see below.
-
-scan_dirs
--
-A list of subdirectories of the package directory (given as relative paths)
-which &AutoDoc; then scans for .gi, .gd, .g, and .autodoc files; all of these files
-are then scanned for &AutoDoc; documentation comments.
-
-Default value: [ ".", "gap", "lib", "examples", "examples/doc" ].
-
-level
--
-This defines the level of the created documentation. The default value is 0.
-When parts of the manual are declared with a higher value
-they will not be printed into the manual.
-
-
-
-gapdoc
--
-This controls whether and how to invoke &GAPDoc; to create HTML, PDF and text
-files from your various XML files.
-
-The value should be either true, false or a
-record. If it is a record or true (the latter is
-equivalent to specifying an empty record), then this feature is
-enabled. It is also enabled if opt.gapdoc is missing.
-In all other cases (in particular if opt.gapdoc is
-false), this feature is disabled.
-
-
-If opt.gapdoc is a record, it may contain the following entries.
-
-
-main
--
-The name of the main XML file of the package manual.
-This exists primarily to support packages with existing manual
-which use a filename here which differs from the default.
-In particular, specifying this is unnecessary when using scaffolding.
-
-Default value: PACKAGENAME.xml.
-
-files
--
-A list of files (given by paths relative to the package directory)
-to be scanned for &GAPDoc; documentation comments.
-Usually it is more convenient to use gapdoc.scan_dirs, see below.
-
-scan_dirs
--
-A list of subdirectories of the package directory (given as relative paths)
-which &AutoDoc; then scans for .gi, .gd and .g files; all of these files
-are then scanned for &GAPDoc; documentation comments.
-
-Default value: [ ".", "gap", "lib", "examples", "examples/doc" ].
-
-LaTeXOptions
--
-Must be a record with entries which can be understood by
-
. Each entry can be a
-string, which will be given to &GAPDoc; directly, or a list containing of
-two entries: The first one must be the string "file", the second one a
-filename. This file will be read and then its content is passed to &GAPDoc;
-as option with the name of the entry.
-
-gap_root_relative_path
--
-Either a boolean, or a string containing a relative path.
-By default (if this option is not set, or is set to false),
-references in the generated documentation referring to external documentation
-(such as the GAP manual) are encoded using absolute paths.
-This is fine as long as the documentation stays on only a single
-computer, but is problematic when preparing documentation that should be
-used on multiple computers, e.g., when creating a distribution archive of
-a GAP package.
-Thus, if a relative path is provided via this option (or if it is set to true,
-in which case the relative path ../../.. is used), then &AutoDoc;
-and &GAPDoc; attempt to replace all absolute paths in references to GAP
-manuals by paths based on this relative path.
-
-On a technical level, &AutoDoc; passes the relative path to the
-gaproot parameter of
-
-
-
-extract_examples
--
-Either true or a record.
-If set to true, then all manual examples are extracted and placed
-into files tst/PACKAGENAME01.tst, tst/PACKAGENAME02.tst, ...
-and so on, with one file for each chapter.
-As a record, the entry can have the following entries itself, to specify some options.
-
-units
--
-This controls how examples are grouped into files. Recognized values are
-"Chapter" (default), "Section", "Subsection" or "Single". Depending on the value,
-one file is created for each chapter, each section, each subsection or each example.
-For all other values only a single file is created.
-
-On a technical level, &AutoDoc; passes the value to the
-units parameter of
.
-
-
-
-maketest
--
-This option is deprecated. Please use extract_examples instead.
-
-Either true or a record. When it is true,
-a simple maketest.g file is created in the main package directory,
-which can be used to test the examples from the manual. As a record,
-the entry can have the following entries itself, to specify some options.
-
-filename
--
-Sets the name of the test file.
-
-commands
--
-A list of strings, each one a command, which
-will be executed at the beginning of the test file.
-
-
-
-
-
-
+ This is the main function of the &AutoDoc; package. It can perform
+ any combination of the following tasks:
+
+ -
+ It can (re)generate a scaffold for your package manual.
+ That is, it can produce two XML files in &GAPDoc; format to be used as part
+ of your manual: First, a file named doc/PACKAGENAME.xml
+ (with your package's name substituted) which is used as
+ main XML file for the package manual, i.e. this file sets the
+ XML doctype and defines various XML entities, includes
+ other XML files (both those generated by &AutoDoc; as well
+ as additional files created by other means), tells &GAPDoc;
+ to generate a table of content and an index, and more.
+ Secondly, it creates a file doc/title.xml containing a title
+ page for your documentation, with information about your package
+ (name, description, version), its authors and more, based
+ on the data in your PackageInfo.g.
+
+ -
+ It can scan your package for &AutoDoc; based documentation (by using &AutoDoc;
+ tags and the Autodoc command.
+ This will
+ produce further XML files to be used as part of the package manual.
+
+ -
+ It can use &GAPDoc; to generate PDF, text and HTML (with
+ MathJaX enabled) documentation from the &GAPDoc; XML files it
+ generated as well as additional such files provided by you. For
+ this, it invokes
+ to convert the XML sources, and it also instructs &GAPDoc; to copy
+ supplementary files (such as CSS style files) into your doc directory
+ (see ).
+
+
+ For more information and some examples, please refer to Chapter .
+
+ The parameters have the following meanings:
+
+ packageOrDirectory
+ -
+ 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 IsDirectory 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 InstallationPath specified in that
+ metadata as the package directory. If packageOrDirectory is
+ an 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
+ PackageInfo.g file, and &AutoDoc; extracts all needed metadata
+ from that. The 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 AutoDocWorksheet (see
+
), there is
+ no parameter corresponding to packageOrDirectory and so the
+ package directory
is always the current directory, and
+ there is no metadata.
+
+ optrec
+ -
+ optrec can be a record with some additional options.
+ The following are currently supported:
+
+ dir
+ -
+ This should either be a string, in which case it must be a path
+ relative to the specified package directory, or a
+ Directory() object. (Thus, the only way to designate an
+ absolute directory is with a Directory() object.) This
+ option specifies where the package documentation
+ (e.g. the &GAPDoc; XML or the manual PDF, etc.) files are stored
+ and/or will be generated.
+
+ Default value: "doc/".
+
+ scaffold
+ -
+ This controls whether and how to generate scaffold XML files
+ for the package documentation.
+
+ The value should be either true, false or a
+ record. If it is a record or true (the latter is
+ equivalent to specifying an empty record), then this feature is
+ enabled. It is also enabled if opt.scaffold is missing but the
+ package's info record in PackageInfo.g has an AutoDoc entry.
+ In all other cases (in particular if opt.scaffold is
+ false), scaffolding is disabled.
+
+ If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is
+ assumed to be a record, and its contents are used as default values for
+ the scaffold settings.
+
+
+ If opt.scaffold is a record, it may contain the following entries.
+
+
+ includes
+ -
+ A list of XML files to be included in the body of the main XML file.
+ If you specify this list and also are using &AutoDoc; to document
+ your operations with &AutoDoc; comments,
+ you can add _AutoDocMainFile.xml to this list
+ to control at which point the documentation produced by &AutoDoc;
+ is inserted. If you do not do this, it will be added after the last
+ of your own XML files.
+
+ index
+ -
+ By default, the scaffold creates an index. If you do not want an index,
+ set this to false.
+
+ appendix
+ -
+ This entry is similar to opt.scaffold.includes but is used
+ to specify files to include after the main body of the manual,
+ i.e. typically appendices.
+
+ bib
+ -
+ The name of a bibliography file, in BibTeX or XML format.
+ If this key is not set, but there is a file doc/PACKAGENAME.bib
+ then it is assumed that you want to use this as your bibliography.
+
+ entities
+ -
+ A record whose keys are taken as entity names, set to the corresponding
+ (string) values. For example, if you pass the record
SomePackage
,
+ SomePackage",
+ RELEASEYEAR := "2015" )]]>
+ then the following entity definitions are added to the XML preamble:
+ SomePackage'>
+ ]]>
+ This allows you to write &SomePackage;
and &RELEASEYEAR;
+ in your documentation, which will be replaced by respective values specified
+ in the entities definition.
+
+ TitlePage
+ -
+ A record whose entries are used to embellish the generated title page
+ for the package manual with extra information, such as a copyright
+ statement or acknowledgments. To this end, the names of the record
+ components are used as XML element names, and the values of the
+ components are outputted as content of these XML elements. For
+ example, you could pass the following record to set a custom
+ acknowledgements text:
+
+ For a list of valid entries in the title page, please refer to the
+ &GAPDoc; manual, specifically section
.
+
+ MainPage
+ -
+ If scaffolding is enabled, by default a main XML file is generated (this
+ is the file which contains the XML doctype and more). If you do not
+ want this (e.g. because you have a handwritten main XML file), but
+ still want &AutoDoc; to generate a title page for you, you can set this
+ option to false
+
+ document_class
+ -
+ Sets the document class of the resulting PDF. The value can either be a string
+ which has to be the name of the new document class, a list containing this string, or
+ a list of two strings. Then the first one has to be the document class name, the second one
+ the option string ( contained in [ ] ) in &LaTeX;.
+
+ latex_header_file
+ -
+ Replaces the standard header from &GAPDoc; completely with the header in this &LaTeX; file.
+ Please be careful here, and look at &GAPDoc;'s latexheader.tex file for an example.
+
+
+
+ autodoc
+ -
+ This controls whether and how to generate additional XML documentation files
+ by scanning for &AutoDoc; documentation comments.
+
+ The value should be either true, false or a
+ record. If it is a record or true (the latter is
+ equivalent to specifying an empty record), then this feature is
+ enabled. It is also enabled if opt.autodoc is missing but the
+ package depends (directly) on the &AutoDoc; package.
+ In all other cases (in particular if opt.autodoc is
+ false), this feature is disabled.
+
+
+ If opt.autodoc is a record, it may contain the following entries.
+
+
+ files
+ -
+ A list of files (given by paths relative to the package directory)
+ to be scanned for &AutoDoc; documentation comments.
+ Usually it is more convenient to use autodoc.scan_dirs, see below.
+
+ scan_dirs
+ -
+ A list of subdirectories of the package directory (given as relative paths)
+ which &AutoDoc; then scans for .gi, .gd, .g, and .autodoc files; all of these files
+ are then scanned for &AutoDoc; documentation comments.
+
+ Default value: [ ".", "gap", "lib", "examples", "examples/doc" ].
+
+ level
+ -
+ This defines the level of the created documentation. The default value is 0.
+ When parts of the manual are declared with a higher value
+ they will not be printed into the manual.
+
+
+
+ gapdoc
+ -
+ This controls whether and how to invoke &GAPDoc; to create HTML, PDF and text
+ files from your various XML files.
+
+ The value should be either true, false or a
+ record. If it is a record or true (the latter is
+ equivalent to specifying an empty record), then this feature is
+ enabled. It is also enabled if opt.gapdoc is missing.
+ In all other cases (in particular if opt.gapdoc is
+ false), this feature is disabled.
+
+
+ If opt.gapdoc is a record, it may contain the following entries.
+
+
+ main
+ -
+ The name of the main XML file of the package manual.
+ This exists primarily to support packages with existing manual
+ which use a filename here which differs from the default.
+ In particular, specifying this is unnecessary when using scaffolding.
+
+ Default value: PACKAGENAME.xml.
+
+ files
+ -
+ A list of files (given by paths relative to the package directory)
+ to be scanned for &GAPDoc; documentation comments.
+ Usually it is more convenient to use gapdoc.scan_dirs, see below.
+
+ scan_dirs
+ -
+ A list of subdirectories of the package directory (given as relative paths)
+ which &AutoDoc; then scans for .gi, .gd and .g files; all of these files
+ are then scanned for &GAPDoc; documentation comments.
+
+ Default value: [ ".", "gap", "lib", "examples", "examples/doc" ].
+
+ LaTeXOptions
+ -
+ Must be a record with entries which can be understood by
+
. Each entry can be a
+ string, which will be given to &GAPDoc; directly, or a list containing of
+ two entries: The first one must be the string "file", the second one a
+ filename. This file will be read and then its content is passed to &GAPDoc;
+ as option with the name of the entry.
+
+ gap_root_relative_path
+ -
+ Either a boolean, or a string containing a relative path.
+ By default (if this option is not set, or is set to false),
+ references in the generated documentation referring to external documentation
+ (such as the &GAP; manual) are encoded using absolute paths.
+ This is fine as long as the documentation stays on only a single
+ computer, but is problematic when preparing documentation that should be
+ used on multiple computers, e.g., when creating a distribution archive of
+ a &GAP; package.
+ Thus, if a relative path is provided via this option (or if it is set to true,
+ in which case the relative path ../../.. is used), then &AutoDoc;
+ and &GAPDoc; attempt to replace all absolute paths in references to &GAP;
+ manuals by paths based on this relative path.
+
+ On a technical level, &AutoDoc; passes the relative path to the
+ gaproot parameter of
+
+
+
+ extract_examples
+ -
+ Either true or a record.
+ If set to true, then all manual examples are extracted and placed
+ into files tst/PACKAGENAME01.tst, tst/PACKAGENAME02.tst, ...
+ and so on, with one file for each chapter.
+ As a record, the entry can have the following entries itself, to specify some options.
+
+ units
+ -
+ This controls how examples are grouped into files. Recognized values are
+ "Chapter" (default), "Section", "Subsection" or "Single". Depending on the value,
+ one file is created for each chapter, each section, each subsection or each example.
+ For all other values only a single file is created.
+
+ On a technical level, &AutoDoc; passes the value to the
+ units parameter of
.
+
+
+
+ maketest
+ -
+ This option is deprecated. Please use extract_examples instead.
+
+ Either true or a record. When it is true,
+ a simple maketest.g file is created in the main package directory,
+ which can be used to test the examples from the manual. As a record,
+ the entry can have the following entries itself, to specify some options.
+
+ filename
+ -
+ Sets the name of the test file.
+
+ commands
+ -
+ A list of strings, each one a command, which
+ will be executed at the beginning of the test file.
+
+
+
+
+
+
@@ -337,8 +352,8 @@
Examples
-Some basic examples for using AutoDoc were already shown in
-Chapter .
+ Some basic examples for using AutoDoc were already shown in
+ Chapter .
diff -Nru gap-autodoc-2019.05.20/tst/worksheets/autoplain.expected/_AutoDocMainFile.xml gap-autodoc-2019.09.04/tst/worksheets/autoplain.expected/_AutoDocMainFile.xml
--- gap-autodoc-2019.05.20/tst/worksheets/autoplain.expected/_AutoDocMainFile.xml 1970-01-01 00:00:00.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets/autoplain.expected/_AutoDocMainFile.xml 2020-03-02 09:35:41.000000000 +0000
@@ -0,0 +1,4 @@
+
+
+
+<#Include SYSTEM "_Chapter_Test.xml">
diff -Nru gap-autodoc-2019.05.20/tst/worksheets/autoplain.expected/_Chapter_Test.xml gap-autodoc-2019.09.04/tst/worksheets/autoplain.expected/_Chapter_Test.xml
--- gap-autodoc-2019.05.20/tst/worksheets/autoplain.expected/_Chapter_Test.xml 1970-01-01 00:00:00.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets/autoplain.expected/_Chapter_Test.xml 2020-03-02 09:35:41.000000000 +0000
@@ -0,0 +1,28 @@
+
+
+
+
+Test
+
+Does AutoDoc have a way to allow that header block not to appear in
+the documentation generated from a .autodoc file like this?
+ S5 := SymmetricGroup(5);
+Sym( [ 1 .. 5 ] )
+gap> Size(S5);
+120
+]]>
+
+
+Some text between two examples
+ A5 := AlternatingGroup(5);
+Alt( [ 1 .. 5 ] )
+gap> Size(A5);
+60
+]]>
+
+
+And we wrap up with some dummy text
+
+
diff -Nru gap-autodoc-2019.05.20/tst/worksheets/autoplain.expected/Plain_file.autodoc_Test.xml gap-autodoc-2019.09.04/tst/worksheets/autoplain.expected/Plain_file.autodoc_Test.xml
--- gap-autodoc-2019.05.20/tst/worksheets/autoplain.expected/Plain_file.autodoc_Test.xml 1970-01-01 00:00:00.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets/autoplain.expected/Plain_file.autodoc_Test.xml 2020-03-02 09:35:41.000000000 +0000
@@ -0,0 +1,16 @@
+
+
+
+$\to$-->'>
+Plain_file.autodoc_Test'>
+]
+>
+
+<#Include SYSTEM "title.xml">
+
+
+<#Include SYSTEM "_AutoDocMainFile.xml">
+
+
diff -Nru gap-autodoc-2019.05.20/tst/worksheets/autoplain.expected/title.xml gap-autodoc-2019.09.04/tst/worksheets/autoplain.expected/title.xml
--- gap-autodoc-2019.05.20/tst/worksheets/autoplain.expected/title.xml 1970-01-01 00:00:00.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets/autoplain.expected/title.xml 2020-03-02 09:35:41.000000000 +0000
@@ -0,0 +1,11 @@
+
+
+
+
+
+ Plain file.autodoc Test
+
+
+ 30 August 2018
+
+
\ No newline at end of file
diff -Nru gap-autodoc-2019.05.20/tst/worksheets/autoplain.expected/tst/plain_file.autodoc_test01.tst gap-autodoc-2019.09.04/tst/worksheets/autoplain.expected/tst/plain_file.autodoc_test01.tst
--- gap-autodoc-2019.05.20/tst/worksheets/autoplain.expected/tst/plain_file.autodoc_test01.tst 1970-01-01 00:00:00.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets/autoplain.expected/tst/plain_file.autodoc_test01.tst 2020-03-02 09:35:41.000000000 +0000
@@ -0,0 +1,26 @@
+# Plain file.autodoc Test, chapter 1
+#
+# DO NOT EDIT THIS FILE - EDIT EXAMPLES IN THE SOURCE INSTEAD!
+#
+# This file has been generated by AutoDoc. It contains examples extracted from
+# the package documentation. Each example is preceded by a comment which gives
+# the name of a GAPDoc XML file and a line range from which the example were
+# taken. Note that the XML file in turn may have been generated by AutoDoc
+# from some other input.
+#
+gap> START_TEST( "plain_file.autodoc_test01.tst");
+
+# _Chapter_Test.xml:9-14
+gap> S5 := SymmetricGroup(5);
+Sym( [ 1 .. 5 ] )
+gap> Size(S5);
+120
+
+# _Chapter_Test.xml:18-23
+gap> A5 := AlternatingGroup(5);
+Alt( [ 1 .. 5 ] )
+gap> Size(A5);
+60
+
+#
+gap> STOP_TEST("plain_file.autodoc_test01.tst", 1 );
diff -Nru gap-autodoc-2019.05.20/tst/worksheets/autoplain.sheet/plain.autodoc gap-autodoc-2019.09.04/tst/worksheets/autoplain.sheet/plain.autodoc
--- gap-autodoc-2019.05.20/tst/worksheets/autoplain.sheet/plain.autodoc 1970-01-01 00:00:00.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets/autoplain.sheet/plain.autodoc 2020-03-02 09:35:41.000000000 +0000
@@ -0,0 +1,20 @@
+@Title Plain file.autodoc Test
+@Date 2018-08-30
+
+@Chapter Test
+Does AutoDoc have a way to allow that header block not to appear in
+the documentation generated from a .autodoc file like this?
+@BeginExampleSession
+gap> S5 := SymmetricGroup(5);
+Sym( [ 1 .. 5 ] )
+gap> Size(S5);
+120
+@EndExampleSession
+Some text between two examples
+@BeginExampleSession
+gap> A5 := AlternatingGroup(5);
+Alt( [ 1 .. 5 ] )
+gap> Size(A5);
+60
+@EndExampleSession
+And we wrap up with some dummy text
diff -Nru gap-autodoc-2019.05.20/tst/worksheets/general.expected/_Chapter_SomeChapter.xml gap-autodoc-2019.09.04/tst/worksheets/general.expected/_Chapter_SomeChapter.xml
--- gap-autodoc-2019.05.20/tst/worksheets/general.expected/_Chapter_SomeChapter.xml 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets/general.expected/_Chapter_SomeChapter.xml 2020-03-02 09:35:41.000000000 +0000
@@ -4,7 +4,7 @@
SomeChapter
-This is dummy text
+ This is dummy text
S5 := SymmetricGroup(5);
Sym( [ 1 .. 5 ] )
@@ -13,11 +13,80 @@
]]>
-And we wrap up with some dummy text
+ Some text between two examples
+ A5 := AlternatingGroup(5);
+Alt( [ 1 .. 5 ] )
+gap> Size(A5);
+60
+]]>
+
+
+ And we wrap up with some dummy text
+
+Some categories
+
+ Intro text
+
+
+ true or false
+
+
+
+
+
+
+
+
+
+ true or false
+
+
+
+
+
+
+
+
+
+ true or false
+
+
+
+
+
+
+
+
+
+ true or false
+
+
+
+
+
+
+
+ Let's wrap up with something, though.
+
+
+
SomeSection
-Some test just inside a section. We can use test some markdown features here:
+ Some test just inside a section.
+
+SomeSubsection
+
+ This is a subsection!
+
+
+
+
+MarkDown support
+
+
+ We can use test some markdown features here:
-
This is a list item.
@@ -41,11 +110,14 @@
-All of this can also be used outside of a list
.
+ All of this can also be used outside of a list
.
+
+
+
-An info class
+ An info class
@@ -54,16 +126,55 @@
This text will only appear in the \LaTeX version.
]]>
+
+Testing the group commands
+
+
+A family of operations
+
+
+
+
+ First sentence.
+ Second sentence.
+ Third sentence.
+
+
+
+
+
+
+
+
+Testing chunks
+
+ This test comes after the chunk is declared, but before it is inserted.
+<#Include Label="MyChunk">
+
+ The text "Hello, world." is inserted right before this.
+
+
+
+
+Testing code chunks
+
+ This test comes after the code chunk is declared, but before it is inserted.
+<#Include Label="MyCode">
+
+ The text "Hello, world." is inserted right before this.
+
+
+
diff -Nru gap-autodoc-2019.05.20/tst/worksheets/general.expected/_Chunks.xml gap-autodoc-2019.09.04/tst/worksheets/general.expected/_Chunks.xml
--- gap-autodoc-2019.05.20/tst/worksheets/general.expected/_Chunks.xml 1970-01-01 00:00:00.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets/general.expected/_Chunks.xml 2020-03-02 09:35:41.000000000 +0000
@@ -0,0 +1,17 @@
+<#GAPDoc Label="MyChunk">
+ Hello, world.
+ This line is indented!
+
+<#/GAPDoc>
+<#GAPDoc Label="MyCode">
+ 2");
+fi;
+]]>
+
+<#/GAPDoc>
diff -Nru gap-autodoc-2019.05.20/tst/worksheets/general.expected/General_Test.xml gap-autodoc-2019.09.04/tst/worksheets/general.expected/General_Test.xml
--- gap-autodoc-2019.05.20/tst/worksheets/general.expected/General_Test.xml 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets/general.expected/General_Test.xml 2020-03-02 09:35:41.000000000 +0000
@@ -3,7 +3,7 @@
$ o$-->'>
+$\to$-->'>
General_Test'>
]
>
diff -Nru gap-autodoc-2019.05.20/tst/worksheets/general.expected/tst/general_test01.tst gap-autodoc-2019.09.04/tst/worksheets/general.expected/tst/general_test01.tst
--- gap-autodoc-2019.05.20/tst/worksheets/general.expected/tst/general_test01.tst 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets/general.expected/tst/general_test01.tst 2020-03-02 09:35:41.000000000 +0000
@@ -15,4 +15,12 @@
Sym( [ 1 .. 5 ] )
gap> Size(S5);
120
+
+# _Chapter_SomeChapter.xml:17-22
+gap> A5 := AlternatingGroup(5);
+Alt( [ 1 .. 5 ] )
+gap> Size(A5);
+60
+
+#
gap> STOP_TEST("general_test01.tst", 1 );
diff -Nru gap-autodoc-2019.05.20/tst/worksheets/general.sheet/worksheet.g gap-autodoc-2019.09.04/tst/worksheets/general.sheet/worksheet.g
--- gap-autodoc-2019.05.20/tst/worksheets/general.sheet/worksheet.g 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets/general.sheet/worksheet.g 2020-03-02 09:35:41.000000000 +0000
@@ -2,16 +2,12 @@
##
## AutoDoc package
##
-## Copyright 2018
-## Contributed by Glen Whitney, studioinfinity.org
-##
-## Licensed under the GPL 2 or later.
-##
#############################################################################
Print( "Pretend this is a code file.\n" );
Print( "(Even though we never use it that way.\n" );
#! @Title General Test
#! @Date 30/08/2018
+
#! @Chapter SomeChapter
#! This is dummy text
#! @BeginExampleSession
@@ -20,11 +16,37 @@
#! gap> Size(S5);
#! 120
#! @EndExampleSession
+#! Some text between two examples
+#! @BeginExampleSession
+#! gap> A5 := AlternatingGroup(5);
+#! Alt( [ 1 .. 5 ] )
+#! gap> Size(A5);
+#! 60
+#! @EndExampleSession
#! And we wrap up with some dummy text
+#############################################################################
+#! @Section Some categories
+#! Intro text
+DeclareCategory("MyThings", IsObject);
+DeclareCategoryCollections("MyThings");
+DeclareCategoryCollections("MyThingsColl");
+DeclareCategoryCollections("MyThingsCollection");
+Now here is some text with a bunch of &!$%*!/ weird things in it. But that
+should be OK, nothing should end up in a weird place.
+#! Let's wrap up with something, though.
+
+#############################################################################
#! @Section SomeSection
-#! Some test just inside a section. We can use test some markdown features here:
+#! Some test just inside a section.
+
+#! @Subsection SomeSubsection
+#! This is a subsection!
+
+#! @Subsection MarkDown support
+#!
+#! We can use test some markdown features here:
#! * This is a list item.
#! * This is a subitem
#! * We can also use math mode here: $a^2+b^2=c^2$.
@@ -47,3 +69,59 @@
#! @BeginNotLatex
#! This text will only appear in the HTML version and the text version, too.
#! @EndNotLatex
+
+#############################################################################
+#! @Section Testing the group commands
+
+#! @BeginGroup Group1
+#! @GroupTitle A family of operations
+
+#! @Description
+#! First sentence.
+DeclareOperation( "FirstOperation", [ IsInt ] );
+
+#! @Description
+#! Second sentence.
+DeclareOperation( "SecondOperation", [ IsInt, IsGroup ] );
+
+#! @EndGroup
+
+## .. Stuff ..
+
+#! @Description
+#! Third sentence.
+#! @Group Group1
+KeyDependentOperation( "ThirdOperation", IsGroup, IsInt, "prime );
+
+#############################################################################
+#! @Section Testing chunks
+
+#! @BeginChunk MyChunk
+#! Hello, world.
+#! This line is indented!
+#! @EndChunk
+
+#! This test comes after the chunk is declared, but before it is inserted.
+
+#! @InsertChunk MyChunk
+
+#! The text "Hello, world." is inserted right before this.
+
+#############################################################################
+#! @Section Testing code chunks
+
+#! @BeginCode MyCode
+#! Hello, world.
+x := 1 + 1;
+if x = 2 then
+ Print("1 + 1 = 2 holds, all is good\n");
+else
+ Error("1+1 <> 2");
+fi;
+#! @EndCode
+
+#! This test comes after the code chunk is declared, but before it is inserted.
+
+#! @InsertCode MyCode
+
+#! The text "Hello, world." is inserted right before this.
diff -Nru gap-autodoc-2019.05.20/tst/worksheets/update.sh gap-autodoc-2019.09.04/tst/worksheets/update.sh
--- gap-autodoc-2019.05.20/tst/worksheets/update.sh 1970-01-01 00:00:00.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets/update.sh 2020-03-02 09:35:41.000000000 +0000
@@ -0,0 +1,13 @@
+#!/bin/sh
+
+# This script copies actual files over to the expected files;
+# this is useful when adding new tests.
+
+for actual in *.actual ; do
+ expected="$(basename $actual .actual).expected"
+ rm -rf $expected
+ mkdir $expected
+ cp $actual/*.xml $expected/
+ mkdir $expected/tst
+ cp $actual/tst/*.tst $expected/tst/
+done
diff -Nru gap-autodoc-2019.05.20/tst/worksheets.tst gap-autodoc-2019.09.04/tst/worksheets.tst
--- gap-autodoc-2019.05.20/tst/worksheets.tst 2019-06-21 15:10:38.000000000 +0000
+++ gap-autodoc-2019.09.04/tst/worksheets.tst 2020-03-02 09:35:41.000000000 +0000
@@ -7,7 +7,14 @@
gap> AUTODOC_TestWorkSheet("general");
Extracting manual examples for General Test package ...
1 chapters detected
-Chapter 1 : extracted 1 examples
+Chapter 1 : extracted 2 examples
#
+gap> AUTODOC_TestWorkSheet("autoplain");
+Extracting manual examples for Plain file.autodoc Test package ...
+1 chapters detected
+Chapter 1 : extracted 2 examples
+
+#
+#
gap> STOP_TEST( "worksheets.tst" );