diff --git a/CHANGES.md b/CHANGES.md index 31752c0d..f2c9f48e 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -8,6 +8,7 @@ This file describes changes in the AutoDoc package. select the corresponding GAPDoc element - Allow XML-style comments in `.autodoc` files - Greatly improve the package manual. + - Convert the hand-written manual chapters from XML to `.autodoc` - Fix an unexpected and confusing error when mixing explicit `@Chapter`/`@Section` markup in one file with auto-generated chapter/section placement in another diff --git a/doc/Comments.autodoc b/doc/Comments.autodoc new file mode 100644 index 00000000..4c987e42 --- /dev/null +++ b/doc/Comments.autodoc @@ -0,0 +1,779 @@ +@Chapter Comments +@ChapterTitle &AutoDoc; documentation comments + + +You can document declarations of global functions and variables, operations, +attributes etc. by inserting &AutoDoc; comments into your sources before these declarations. +An &AutoDoc; comment always starts with #!. +This is also the smallest possible &AutoDoc; command. +If you want your declaration documented, just write +#! at the line before the documentation. For example: + +```@listing +#! +DeclareOperation( "AnOperation", + [ IsList ] ); +``` + +This will produce a manual entry for the operation AnOperation. + +For declaration documentation, the associated declaration must appear +immediately after the &AutoDoc; comment block. In particular, do not insert +other code (such as if false then or assignments) between the comment +block and the Declare... statement. + +Inside of &AutoDoc; comments, &AutoDoc; commands +starting with @ can be used to control the output &AutoDoc; produces. +Any comment line that does not start with an &AutoDoc; command is treated +as regular documentation text and may contain (almost) arbitrary &GAPDoc; XML +markup, such as <Ref>, <A>, <List>, and similar tags. +This lets you use the normal &GAPDoc; formatting toolbox directly inside +&AutoDoc; comments. + +For example: +```@listing +#! @Description +#! See for setup details. +#! The argument obj must satisfy IsObject. +``` + +As explained in chapter , you can combine &AutoDoc; +comments with hand-written XML and classic &GAPDoc; comments. For practical +setup and migration workflows, see chapter . + + +@Section Documenting declarations + +In the bare form above, the manual entry for AnOperation will not +contain much more than the name of the operation. In order to change +this, there are several commands you can put into the &AutoDoc; comment +before the declaration. Currently, the following commands are provided: + +@Subsection @Description descr +@SubsectionLabel @Description + +@Description descr +Adds the text in the following lines of the &AutoDoc; to the description +of the declaration in the manual. Lines are until the next &AutoDoc; command +or until the declaration is reached. + +@Subsection @Returns ret_val +@SubsectionLabel @Returns + +@Returns ret_val +The string ret_val is added to the documentation, with the text Returns: +put in front of it. This should usually give a brief hint about the type or meaning +of the value returned by the documented function. + +@Subsection @Arguments args +@SubsectionLabel @Arguments + +@Arguments args +The string args contains a description of the arguments the +function expects, including optional parts, which are denoted by square +brackets. The argument names can be separated by whitespace, commas or +square brackets for the optional arguments, like grp[, elm] or +xx[y[z] ]. If &GAP; options are used, this can be followed by a colon : +and one or more assignments, like n[, r]: tries := 100. + +@Subsection @Group grpname +@SubsectionLabel @Group + +@Group grpname +Adds the following method to a group with the given name. +See section for more information about groups. + +@Subsection @Label label +@SubsectionLabel @Label + +@Label label +Adds label to the function as label. + +If this is not specified, then for declarations that involve a list of input filters +(as is the case for DeclareOperation, DeclareAttribute, etc.), +a default label is generated from this filter list. +```@listing +#! @Label testlabel +DeclareProperty( "AProperty", + IsObject ); +``` +leads to this: +```@listing + + + true or false + + + + +``` +while +```@listing +#! +DeclareProperty( "AProperty", + IsObject ); +``` +leads to this: +```@listing + + + true or false + + + + +``` + + +@Subsection @ChapterInfo chapter, section +@SubsectionLabel @ChapterInfo + +@ChapterInfo +Adds the entry to the given chapter and section. Here, +chapter and section are the respective +titles. +As an example, a full &AutoDoc; comment with all options could look like this: + +```@listing +#! @Description +#! Computes the list of lists of degrees of ordinary characters +#! associated to the $p$-blocks of the group $G$ +#! with $p$-modular character table modtbl +#! and underlying ordinary character table `ordtbl`. +#! @Returns a list +#! @Arguments modtbl +#! @Group CharacterDegreesOfBlocks +#! @Label chardegblocks +#! @ChapterInfo Blocks, Attributes +DeclareAttribute( "CharacterDegreesOfBlocks", + IsBrauerTable ); +``` + +@Section Other documentation comments + +There are also some commands which can be used in &AutoDoc; comments +that are not associated to any declaration. This is useful for additional +text in your documentation, examples, mathematical chapters, etc. + +@Subsection @Chapter name +@SubsectionLabel @Chapter + +@Chapter +@ChapterLabel +@ChapterTitle +Sets the active chapter, all subsequent functions which do not have an explicit chapter +declared in their &AutoDoc; comment via @ChapterInfo will be added to this chapter. +Also all text comments, i.e. lines that begin with #! without a command, and which do not +follow after @Description, will be added to the chapter as regular text. Additionally, +the chapters label will be set to Chapter_name. + +Example: + +```@listing +#! @Chapter My chapter +#! This is my chapter. +#! I document my stuff in it. +``` + +The @ChapterLabel label command +can be used to set the label of the chapter to Chapter_label instead of +Chapter_name. + +Additionally, the chapter will be stored as _Chapter_label.xml. + +The @ChapterTitle title command +can be used to set a heading for the chapter that is different from name. +Note that the title does not affect the label. + +If you use all three commands, i.e., +```@listing +#! @Chapter name +#! @ChapterLabel label +#! @ChapterTitle title +``` +title is used for the headline, label for cross-referencing, and name +for setting the same chapter as active chapter again. + +@Subsection @Section name +@SubsectionLabel @Section + +@Section +@SectionLabel +@SectionTitle +Sets an active section like @Chapter sets an active chapter. +The section automatically ends with the next @Section or @Chapter command. + +```@listing +#! @Section My first manual section +#! In this section I am going to document my first method. +``` + +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. + +@Subsection @Subsection name +@SubsectionLabel @Subsection + +@Subsection +@SubsectionLabel +@SubsectionTitle +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. + +```@listing +#! @Subsection My first manual subsection +#! In this subsection I am going to document my first example. +``` + +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. + +@Subsection @BeginGroup [grpname] +@SubsectionLabel @BeginGroup + +@BeginGroup +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. + +See section for more information about groups. + +@Subsection @EndGroup +@SubsectionLabel @EndGroup + +@EndGroup +Ends the current group. + +```@listing +#! @BeginGroup MyGroup +#! +DeclareAttribute( "GroupedAttribute", + IsList ); + +DeclareOperation( "NonGroupedOperation", + [ IsObject ] ); + +#! +DeclareOperation( "GroupedOperation", + [ IsList, IsRubbish ] ); +#! @EndGroup +``` + +@Subsection @GroupTitle title +@SubsectionLabel @GroupTitle + +@GroupTitle +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. + +@Subsection @Level lvl +@SubsectionLabel @Level + +@Level +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. + +See section for more information about levels. + +@Subsection @ResetLevel +@SubsectionLabel @ResetLevel + +@ResetLevel +Resets the current level to 0. + +@Subsection @BeginExample and @EndExample +@SubsectionLabel @BeginExample + +@BeginExample +@EndExample +@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;. +@EndExample ends the example block. + +To illustrate this command, consider this input: +```@listing +#! @BeginExample +S5 := SymmetricGroup(5); +#! Sym( [ 1 .. 5 ] ) +Order(S5); +#! 120 +#! @EndExample +``` +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. +If you enable extract_examples := true when calling , +these examples can also be turned into .tst files (see +Section ). + +@Subsection @BeginExampleSession and @EndExampleSession +@SubsectionLabel @BeginExampleSession + +@BeginExampleSession +@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 ). + +To illustrate this command, consider this input: +```@listing +#! @BeginExampleSession +#! gap> S5 := SymmetricGroup(5); +#! Sym( [ 1 .. 5 ] ) +#! gap> Order(S5); +#! 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 +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. + +@Subsection @BeginLog and @EndLog +@SubsectionLabel @BeginLog + +@BeginLog +@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. + +@Subsection @BeginLogSession and @EndLogSession +@SubsectionLabel @BeginLogSession + +@BeginLogSession +@EndLogSession +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 ). +The &AutoDoc; command @LogSession is an alias of @BeginLogSession. + +@Subsection @DoNotReadRestOfFile +@SubsectionLabel @DoNotReadRestOfFile + +@DoNotReadRestOfFile +Prevents the rest of the file from being read by the parser. Useful for +unfinished or temporary files. + +```@listing +#! This will appear in the manual + +#! @DoNotReadRestOfFile + +#! This will not appear in the manual. +``` + +@Subsection @BeginChunk name, @EndChunk, and @InsertChunk name +@SubsectionLabel @BeginChunk + +@BeginChunk name +@EndChunk +@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. +```@listing +#! @BeginChunk MyChunk +#! Hello, world. +#! @EndChunk + +#! @InsertChunk MyChunk +## The text "Hello, world." is inserted right before this. +``` + +You can use this to define an example like this in one file: + +```@listing +#! @BeginChunk Example_Symmetric_Group +#! @BeginExample +S5 := SymmetricGroup(5); +#! Sym( [ 1 .. 5 ] ) +Order(S5); +#! 120 +#! @EndExample +#! @EndChunk +``` + +And then later, insert the example in a different file, like this: + +```@listing +#! @InsertChunk Example_Symmetric_Group +``` + +@Subsection @BeginCode name, @EndCode, and @InsertCode name +@SubsectionLabel @BeginCode + +@BeginCode name +@EndCode +@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. +```@listing +#! @BeginCode Increment +i := i + 1; +#! @EndCode + +#! @InsertCode Increment +## Code is inserted here. +``` + +@Subsection @LatexOnly text, @BeginLatexOnly, and @EndLatexOnly +@SubsectionLabel @LatexOnly + +@LatexOnly text +@BeginLatexOnly +@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. +```@listing +#! @BeginLatexOnly +#! \include{picture.tex} +#! @EndLatexOnly + +#! @LatexOnly \include{picture.tex} +``` + +@Subsection @NotLatex text, @BeginNotLatex, and @EndNotLatex +@SubsectionLabel @NotLatex + +@NotLatex text +@BeginNotLatex +@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. +```@listing +#! @BeginNotLatex +#! For further information see the PDF version of this manual. +#! @EndNotLatex + +#! @NotLatex For further information see the PDF version of this manual. +``` + +@Section Title page commands +@SectionLabel TitlepageCommands + +The following commands can be used to add corresponding parts to the +title page of a document generated by &AutoDoc;. + + + @Title + + + @Subtitle + + + @Version + + + @TitleComment + + + @Author + + + @Date + + + @Address + + + @Abstract + + + @Copyright + + + @Acknowledgements + + + @Colophon + + +Many of these values can (and for package manuals typically should) be +extracted from PackageInfo.g. If you set them explicitly in comments, +they override extracted or scaffold-defined values. This is usually most useful +for worksheets created with , +since worksheets do not have a PackageInfo.g file from which this information could be extracted. + +@Section Plain text files +@SectionLabel PlainText + +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 #!. + +@Section Grouping +@SectionLabel Groups + +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 +```@listing +#! @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 ); +``` + +produces the following: + +```@listing + +A family of operations + + + + +First sentence. +Second sentence. +Third sentence. + + +``` + +@Section Level +@SectionLabel Level + +Levels can be set to not write certain parts in the manual by default. + Every entry has by default the level 0. The command @Level can + be used to set the level of the following part to a higher level, for + example 1, and prevent it from being printed to the manual by default. + However, if one sets the level to a higher value in the autodoc option of + &AutoDoc;, the parts will be included in the manual at the specific place. + +```@listing +#! This text will be printed to the manual. +#! @Level 1 +#! This text will be printed to the manual if created with level 1 or higher. +#! @Level 2 +#! This text will be printed to the manual if created with level 2 or higher. +#! @ResetLevel +#! This text will be printed to the manual. +``` + +@Section Markdown-like formatting of text in &AutoDoc; +@SectionLabel MarkdownExtension + +&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;, +but do not follow them strictly. Neither are all features of the Markdown language +supported. The following subsections describe what is possible. + +@Subsection Lists +@SubsectionLabel MarkdownExtensionList + +One can create lists of items by beginning a new line with *, +, -, followed by one + space. The first item starts the list. When items are longer than one line, the following lines + have to be indented by at least two spaces. The list ends when a line which does not start a new + item is not indented by two spaces. Of course lists can be nested. Here is an example: + +```@listing +#! The list starts in the next line +#! * item 1 +#! * item 2 +#! which is a bit longer +#! * and also contains a nested list +#! * with two items +#! * item 3 of the outer list +#! This does not belong to the list anymore. +``` + +This is the output:
+The list starts in the next line +* item 1 +* item 2 + which is a bit longer + * and also contains a nested list + * with two items +* item 3 of the outer list +This does not belong to the list anymore.
+ +The *, -, and + are fully interchangeable and can even be used mixed, but this is not recommended. + +@Subsection Math modes +@SubsectionLabel MarkdownExtensionMath + +One can start an inline formula with a $, and also end it with $, just like in &LaTeX;. This will translate into + &GAPDoc;s inline math environment. For display mode one can use $$, also like &LaTeX;. + +```@listing +#! This is an inline formula: $1+1 = 2$. +#! This is a display formula: +#! $$ \sum_{i=1}^n i. $$ +``` + + produces the following output:
+ This is an inline formula: 1+1 = 2. + This is a display formula: + \sum_{i=1}^n i. + +@Subsection Emphasize +@SubsectionLabel MarkdownExtensionEmph + +One can emphasize text by using two asterisks (**) or two underscores (__) at the + beginning and the end of the text which should be emphasized. Example: + +```@listing +#! **This** is very important. +#! This is __also important__. +#! **Naturally, more than one line +#! can be important.** +``` + + This produces the following output:
+This is very important. +This is also important. +Naturally, more than one line +can be important. + +@Subsection Inline code +@SubsectionLabel MarkdownExtensionInlineCode + +One can mark inline code snippets by using backticks (`) at the + beginning and the end of the text which should be marked as code. Example: + +```@listing +#! Call function `foobar()` at the start. +``` + + This produces the following output:
+ Call function foobar() at the start. + +@Subsection Fenced code blocks +@SubsectionLabel MarkdownExtensionFencedCode + +One can insert verbatim code blocks by placing the code between lines + containing at least three backticks or at least three tildes. The opening + fence may optionally be followed by an info string. The values + @listing, @example, and @log select the corresponding + GAPDoc element; any other value is currently ignored. If nothing is specified + the default is to generate <Listing>. Example: + +````@listing +#! ```@listing +#! if x = 2 then +#! Print("1 + 1 = 2 holds, all is good\n"); +#! fi; +#! ``` +#! ~~~@example +#! gap> [ 1 .. 3 ] ^ 2; +#! [ 1, 4, 9 ] +#! ~~~ +#! ```@log +#! #I some log message +#! ``` +```` + + This produces the following output:
+```@listing +if x = 2 then + Print("1 + 1 = 2 holds, all is good\n"); +fi; +``` +~~~@example +gap> [ 1 .. 3 ] ^ 2; +[ 1, 4, 9 ] +~~~ +```@log +#I some log message +``` + + +@Section Deprecated commands +@SectionLabel Deprecated + +The following commands used to be supported, but are not supported anymore. + + +@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 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. + diff --git a/doc/Overview.autodoc b/doc/Overview.autodoc new file mode 100644 index 00000000..a3c854a2 --- /dev/null +++ b/doc/Overview.autodoc @@ -0,0 +1,48 @@ +@Chapter Overview +@ChapterTitle What &AutoDoc; offers + + +&AutoDoc; helps you create and maintain package manuals for &GAP;. +It is built on top of &GAPDoc; and generates the XML input that +&GAPDoc; consumes. +So &AutoDoc; complements &GAPDoc; instead of replacing it. + +The package is designed for a mix and match workflow: +you can adopt only the parts that help you today, and add more over time. + +@Section Core features +@SectionLabel Overview:Features + +- Build package manuals via one reproducible command, usually + gap makedoc.g. +- Generate and maintain a title page from metadata in + PackageInfo.g. +- Generate and maintain a main XML file that includes your chapters. +- Extract manual examples into .tst files via + extract_examples := true. +- Document declarations directly in source files via &AutoDoc; + comments beginning with #!. +- Combine &AutoDoc; comments, classic &GAPDoc; source comments, + and hand-written XML chapters in one manual. + +@Section Adopting &AutoDoc; incrementally +@SectionLabel Overview:MixAndMatch + +You do not have to switch everything at once. +Typical adoption paths include: +- Use only to rebuild an existing &GAPDoc; manual. +- Enable only title-page generation, while keeping your custom main XML. +- Keep your existing title page but use generated entities such as + &VERSION;, &RELEASEYEAR;, and &RELEASEDATE;. +- Add &AutoDoc; comments only for new code, and leave old documentation as-is. +- Later, gradually move chapters or source documentation to your preferred style. + +This flexibility is central: &AutoDoc; should make your current setup better, +without forcing a full rewrite first. + +@Section Where to continue +@SectionLabel Overview:WhereNext + +For practical setup and migration workflows, continue with chapter +. For the command reference of documentation comments, +see chapter . diff --git a/doc/Overview.xml b/doc/Overview.xml deleted file mode 100644 index 5279986b..00000000 --- a/doc/Overview.xml +++ /dev/null @@ -1,59 +0,0 @@ - -What &AutoDoc; offers - -&AutoDoc; helps you create and maintain package manuals for &GAP;. -It is built on top of &GAPDoc; and generates the XML input that -&GAPDoc; consumes. -So &AutoDoc; complements &GAPDoc; instead of replacing it. -

- -The package is designed for a mix and match workflow: -you can adopt only the parts that help you today, and add more over time. -

- -

-Core features - - -Build package manuals via one reproducible command, usually -gap makedoc.g. -Generate and maintain a title page from metadata in -PackageInfo.g. -Generate and maintain a main XML file that includes your chapters. -Extract manual examples into .tst files via -extract_examples := true. -Document declarations directly in source files via &AutoDoc; -comments beginning with #!. -Combine &AutoDoc; comments, classic &GAPDoc; source comments, -and hand-written XML chapters in one manual. - - -
- -
-Adopting &AutoDoc; incrementally - -You do not have to switch everything at once. -Typical adoption paths include: - -Use only to rebuild an existing &GAPDoc; manual. -Enable only title-page generation, while keeping your custom main XML. -Keep your existing title page but use generated entities such as -&VERSION;, &RELEASEYEAR;, and &RELEASEDATE;. -Add &AutoDoc; comments only for new code, and leave old documentation as-is. -Later, gradually move chapters or source documentation to your preferred style. - - -This flexibility is central: &AutoDoc; should make your current setup better, -without forcing a full rewrite first. -
- -
-Where to continue - -For practical setup and migration workflows, continue with chapter -. For the command reference of documentation comments, -see chapter . - -
- diff --git a/doc/Tutorials.autodoc b/doc/Tutorials.autodoc new file mode 100644 index 00000000..d7949211 --- /dev/null +++ b/doc/Tutorials.autodoc @@ -0,0 +1,575 @@ +@Chapter Tutorials +@ChapterTitle Getting started using &AutoDoc; + + +This chapter gives practical workflows for adding &AutoDoc; to a package. +For a high-level feature overview and adoption strategy, see +chapter . + +@Section Choose your workflow +@SectionLabel Tut:ChooseWorkflow + +You can use &AutoDoc; in several ways, and it is fine to combine them: +- Start a new package manual from scratch (Section ). +- Integrate &AutoDoc; into an existing &GAPDoc; manual + (Section ). +- Use only selected features, such as title-page generation or + example extraction, while keeping everything else unchanged. + +This incremental approach is encouraged: start with the smallest helpful step, +then adopt additional features when useful. +@Section Creating a package manual from scratch +@SectionLabel Tut:Scratch + +Suppose your package is already up and running, but so far has no +manual. Then you can rapidly generate a scaffold for a package manual +using the command like this, +while running &GAP; from within your package's directory (the +one containing the PackageInfo.g file): +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( rec( scaffold := true ) ); +``` +This first reads the PackageInfo.g file from the current +directory. It extracts information about the package from it +(such as its name and version, see Section ). +It then creates two XML files doc/NAME_OF_YOUR_PACKAGE.xml and +doc/title.xml inside the package directory. Finally, it runs +&GAPDoc; on them to produce a nice initial PDF and HTML version of your +fresh manual. + +To ensure that the &GAP; help system picks up your package manual, you +should also add something like the following to your +PackageInfo.g: +```@listing +PackageDoc := rec( + BookName := ~.PackageName, + ArchiveURLSubset := ["doc"], + HTMLStart := "doc/chap0.html", + PDFFile := "doc/manual.pdf", + SixFile := "doc/manual.six", + LongTitle := ~.Subtitle, +), +``` + +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. 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 +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 +makedoc.g +directory, with content based on the following example: +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( rec( autodoc := true ) ); +QUIT; +``` +Then you can regenerate the package manual from the command line with the +following command, executed from within the package directory: +```@listing +gap makedoc.g +``` + +If you also want regression tests from your manual examples, enable +extract_examples := true; this is explained in +Section . + +@Section Documenting code with &AutoDoc; +@SectionLabel Tut:AdvancedAutoDoc + +To get one of your global functions, operations, attributes +etc. to appear in the package manual, simply insert an &AutoDoc; comment +of the form #! directly in front of it. For example: +```@listing +#! +DeclareOperation( "ToricVariety", [ IsConvexObject ] ); +``` + +This tiny change is already sufficient to ensure that the operation +appears in the manual. In general, you will want to add further +information about the operation, such as in the following example: + +Important: the comment block must be immediately followed by the declaration +it documents. Do not place other code between the comment block and the +Declare... statement. + +```@listing +#! @Arguments conv +#! @Returns a toric variety +#! @Description +#! Creates a toric variety out +#! of the convex object conv. +DeclareOperation( "ToricVariety", [ IsConvexObject ] ); +``` + +In these comment lines, you can freely use normal &GAPDoc; XML markup +(with the usual exceptions for lines starting with @, which are +interpreted as &AutoDoc; commands). So, for instance, tags like +<Ref>, <A>, <K>, <List>, etc. can be written +directly in #! comment text. + +For a thorough description of what you can do with &AutoDoc; +documentation comments, please refer to chapter . + + + + + + +Suppose you have not been using &GAPDoc; before but instead used the process +described in section to create your manual. +Then the following &GAP; command will regenerate the manual and automatically +include all newly documented functions, operations etc.: + +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( rec( scaffold := true, + autodoc := true ) ); +``` + +If you are not using the scaffolding feature, e.g. because you already +have an existing &GAPDoc; based manual, then you can still use &AutoDoc; +documentation comments. Just make sure to first edit the main XML +file of your documentation, and insert the line +```@listing +<#Include SYSTEM "_AutoDocMainFile.xml"> +``` +in a suitable place. This means that you can mix &AutoDoc; documentation +comments 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 then runs &GAPDoc; to produce HTML and PDF output, but does not +touch your documentation XML files otherwise. +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( rec( autodoc := true ) ); +``` + + +@Section Using &AutoDoc; in an existing &GAPDoc; manual +@SectionLabel Tut:IntegrateExisting + +Even if you already have an existing &GAPDoc; manual, it might be +interesting for you to use &AutoDoc; for two purposes: + +First, with &AutoDoc; it is very convenient to regenerate your +documentation. + +Secondly, the scaffolding feature which generates a title page +with all the metadata of your package in a uniform way is very +handy. The somewhat tedious process of keeping your title page in +sync with your PackageInfo.g is fully automated this way +(including the correct version, release data, author information +and so on). + +There are various examples of packages using &AutoDoc; for +this purpose only, e.g. &io; and orb. + +In particular, this setup works well if you want to keep your existing manual +structure and only adopt selected &AutoDoc; features first; for example +automatic title-page data and predefined entities such as +&VERSION;, &RELEASEYEAR; and &RELEASEDATE; +(see Section ). + +@Subsection Using &AutoDoc; on a complete &GAPDoc; manual +@SubsectionLabel Tut:IntegrateExisting:EverythingThere + +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; session started +in the root directory of your package: +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( ); +``` +Note that in particular, you do not have to worry about keeping a list of your +implementation files up-to-date. + +But there is more. &AutoDoc; can create .tst files from the +examples in your manual to test your package. This can be achieved via +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( rec( extract_examples := true ) ); +``` +Now files PACKAGENAME01.tst, PACKAGENAME02.tst and so appear in the +tst/ subdirectory of your package, and can be tested as usual using + respectively . + +@Subsection Setting different &GAPDoc; options +@SubsectionLabel Tut:IntegrateExisting:GapDocOptions + +Sometimes, the default values for the &GAPDoc; command used by &AutoDoc; +may not be suitable for your manual. + + Suppose your main XML file is not named PACKAGENAME.xml, but rather something else, e.g. main.xml. +Then you can tell &AutoDoc; to use this file as the main XML file via +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( rec( gapdoc := rec( main := "main" ) ) ); +``` + +As explained above, by default &AutoDoc; scans all .g, .gd and .gi files +it can find inside of your package root directory, and in the subdirectories gap, +lib, examples and examples/doc as well. +If you keep source files with documentation in other directories, +you can adjust the list of directories AutoDoc scans via the scan_dirs option. +The following example illustrates this by instructing &AutoDoc; to only search in the subdirectory package_sources +of the package's root directory. +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( rec( gapdoc := rec( scan_dirs := [ "package_sources" ] ) ) ); +``` +You can also specify an explicit list of files containing documentation, +which will be searched in addition to any files located within the scan directories: +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( rec( gapdoc := rec( files := [ "path/to/some/hidden/file.gd" ] ) ) ); +``` +Giving such a file does not prevent the standard scan_dirs from being scanned for +other files. + +Next, &GAPDoc; supports the documentation to be built with relative paths. +This means, links to manuals of other packages or the &GAP; library will +not be absolute, but relative from your documentation. This can be particularly useful +if you want to build a release tarball or move your &GAP; installation around later. +Suppose you are starting &GAP; in the root path of your package as always, +and the standard call of will then build the documentation in the doc subdirectory of your package. +From this directory, the gap root directory has the relative path ../../... +Then you can enable the relative paths by +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( rec( gapdoc := rec( gap_root_relative_path := "../../.." ) ) ); +``` +or, since ../../.. is the standard option for gap_root_relative_path, by +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( rec( gapdoc := rec( gap_root_relative_path := true ) ) ); +``` + +@Subsection Checklist for converting an existing &GAPDoc; manual to use &AutoDoc; +@SubsectionLabel Tut:Checklist + +Here is a checklist for authors of a package &PackageName;, +which already has a &GAPDoc; based manual, who wish to use &AutoDoc; +to build the manual from now on. +We assume that the manual is currently built by reading a file +makedoc.g and that the main .xml file +is named manual.xml. + +The files PackageInfo.g, makedoc.g, +doc/title.xml and doc/PackageName.xml +(if it exists) will be altered by this procedure, +so it may be wise to keep backup copies. + +You should have copies of the &AutoDoc; files PackageInfo.g +and makedoc.g to hand when reading these instructions. + + + +Copy AutoDoc/makedoc.g to PackageName/makedoc.g. + + +Edit PackageName/makedoc.g as follows. + + + Change the header comment to match other files in your package. + + + After LoadPackage("AutoDoc"); + add LoadPackage("PackageName");. + + + In the AutoDoc record delete autodoc := true;. + + + + In the scaffold record change the includes list + to be the list of your .xml files that are contained in + manual.xml. + + + + If you do not have a bibliography you may delete the + bib := "bib.xml", field in the scaffold. + Otherwise, edit the file name if you have a different file. + If you only have a .bib file + (manual.bib or bib.xml.bib say) + you should rename this file PackageName.bib. + + + + In the LaTeXOptions record, + which is in the gapdoc record, enter any + &LaTeX; newcommands previously in manual.xml. + (If there are none you may safely delete this record.) + To illustrate this option, the &AutoDoc; file makedoc.g + defines the command \bbZ + by \newcommand{\bbZ}{\mathbb{Z}}, + which may be used to produce + the &LaTeX; formula f : \bbZ^2 \to \bbZ. + However, note that this only works in the PDF version of the file. + + + + +Now edit PackageName/PackageInfo.g as follows. + + + Delete any PKGVERSIONDATA chunk that may be there. + One reason for converting your manual to use &AutoDoc; is to stop + using entities such as PACKAGENAMEVERSION. + + + Copy the AutoDoc record from AutoDoc/PackageInfo.g + to the end of your file (just before the final "));". + + + + + + Replace the Copyright, Abstract and + Acknowledgements fields of the TitlePage + record with the corresponding material from your manual.xml. + (If you do not have an abstract, then delete the + Abstract field, etc.) + + + + + + In the entities record enter any entities + previously stored in your manual.xml. + (Again, if you have none, you may safely delete this record.) + To illustrate this option the &AutoDoc; file PackageInfo.g + defines entities for the names of packages &io; and &PackageName;. + + + + +If you are using a GitHub repository, as well as running +"git add" on files makedoc.g, +PackageInfo.g and doc/PackageName.bib, +you should run "git rm -f" on files doc/manual.xml, +and doc/title.xml. + + +You should now be ready to run &GAP; and Read("makedoc.g"); +in your package root directory. + +@Section Scaffolds +@SectionLabel Tut:Scaffolds + + + +@Subsection Generating a title page +@SubsectionLabel Tut:Scaffolds:Title + +For most (if not all) &GAP; packages, the title page of the package manual +lists information such as the release date, version, names and contact details +of the authors, and so on. + +All this data is also contained in your PackageInfo.g, and whenever +you make a change to that file, there is a risk that you forget to update +your manual to match. And even if you don't forget it, you of course +have to spend some time to adjust the manual. &GAPDoc; can help to a degree with +this via entities. Thus, you will sometimes see code like this in PackageInfo.g +files: +```@listing +Version := "1.2.3", +Date := "20/01/2015", +## <#GAPDoc Label="PKGVERSIONDATA"> +## +## +## +## <#/GAPDoc> +``` +However, it is still easy to forget both of these versions. And it doesn't +solve the problem of updating package authors addresses. Neither of these is a +big issue, of course, but there have been plenty examples in the past where +people forget either of these two things, and it can be slightly embarrassing. +It may even require you to make a new release just to fix the issue, which in +our opinion is a sad waste of your valuable time. + +So instead of worrying about manually synchronising these things, you can +instruct &AutoDoc; to generate a title page for your manual based on the +information in your PackageInfo.g. The following commands do just that +(in addition to building your manual), by generating a file called +doc/title.xml. +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( rec( scaffold := rec( MainPage := false ) ) ); +``` +Note that this only outputs doc/title.xml but does not +touch any other files of your documentation. In particular, you need +to explicitly include doc/title.xml from your main XML file. + +However, you can also tell &AutoDoc; to maintain the main XML file for you, +in which case this is automatic. In fact, this is the default if you +enable scaffolding; the above example command explicitly told &AutoDoc; +not to generate a main page. + +@Subsection Generating the main XML file +@SubsectionLabel Tut:Scaffolds:Main + +The following generates a main XML file for your documentation in +addition to the title page. The main XML file includes +the title page by default, as well as any documentation generated +from &AutoDoc; documentation comments. +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc( rec( scaffold := true ) ); +``` + +You can instruct &AutoDoc; to include additional XML files by giving it +a list of filenames, as in the following example: +```@listing +LoadPackage( "AutoDoc" ); +AutoDoc(rec( + scaffold := rec( + includes := [ "somefile.xml", "anotherfile.xml" ] + ) +)); +``` + +For more information, please consult the documentation +of the function. + +@Subsection What data is used from PackageInfo.g? +@SubsectionLabel Tut:PackageInfo + +&AutoDoc; can use data from PackageInfo.g in order to +generate a title page. Specifically, the following components +of the package info record are taken into account: + + + +PackageName +This is used to set the <Title> element of the +title page. + + +Subtitle +This is used to set the <Subtitle> element of the +title page. + + +Version +This is used to set the <Version> element of the +title page, with the string Version prepended. + + +Date +This is used to set the <Date> element of the +title page. + + +Persons +This is used to generate <Author> elements in the +generated title page. + + +PackageDoc +This is a record (or a list of records) which is used to tell the +&GAP; help system about the package manual. Currently &AutoDoc; +extracts the value of the PackageDoc.BookName component +and then passes that on to &GAPDoc; when creating the HTML, PDF +and text versions of the manual. + + +AutoDoc +This record controls extra settings used by &AutoDoc; while generating the +manual. In particular, PkgInfo.AutoDoc.TitlePage lets you add or +override title-page elements coming from package metadata. + +Typical fields you may set there include TitleComment, +Abstract, Copyright, Acknowledgements and Colophon. +For example, in PackageInfo.g: +```@listing +SetPackageInfo( rec( + ... + AutoDoc := rec( + TitlePage := rec( + Copyright := "(C) 2026 Jane Doe", + Acknowledgements := "Funded by Example Grant 1234." + ) + ) +) ); +``` +This inserts <Copyright> and <Acknowledgements> blocks into +the generated title.xml. + +PkgInfo.AutoDoc.TitlePage has exactly the same meaning as +scaffold.TitlePage in . The function documentation +for scaffold.TitlePage points back to this subsection. + + + + +@Subsection Entities from PackageInfo.g and scaffold options +@SubsectionLabel Tut:PackageInfo:Entities + +Besides title-page fields, you can define custom entities in +AutoDoc.entities inside PackageInfo.g. +They are written to doc/_entities.xml, so they can be used both by +generated main files and by hand-written main XML files. + +In addition, &AutoDoc; predefines the entities VERSION, +RELEASEYEAR and RELEASEDATE, derived from package metadata. +This is useful if you keep a custom title page or custom chapters and still +want release information to stay synchronized with PackageInfo.g. + +You can specify scaffold-related settings in PackageInfo.g and in your +makedoc.g call at the same time; both records are merged, and values +from makedoc.g take precedence when both define the same key. + +@Section Worksheets +@SectionLabel Tut:WorksheetsPointer + +For stand-alone documents that are not tied to a package, use +. Its documentation and examples are in +Section of chapter +. diff --git a/gap/AutoDocMainFunction.gi b/gap/AutoDocMainFunction.gi index c2721d7b..84bd0d6f 100644 --- a/gap/AutoDocMainFunction.gi +++ b/gap/AutoDocMainFunction.gi @@ -95,7 +95,8 @@ InstallGlobalFunction( CreateEntitiesPage, filestream := AUTODOC_OutputTextFile( dir, "_entities.xml" ); # output all entities - for ent in RecNames(entities) do + # (sort the key names to get stable order across all GAP versions) + for ent in Set(RecNames(entities)) do val := String(entities.(ent)); # escape single quotes, if any diff --git a/gap/Magic.gd b/gap/Magic.gd index 0c5e03d7..af4bb17d 100644 --- a/gap/Magic.gd +++ b/gap/Magic.gd @@ -45,7 +45,7 @@ #! #! These tasks can be enabled independently, so you can use as much or as #! little of &AutoDoc; as your package currently needs. -#! For more information and some examples, please refer to Chapter . +#! For more information and some examples, please refer to Chapter . #!

#! The parameters have the following meanings: #! @@ -189,8 +189,8 @@ #! rec( Acknowledgements := "Many thanks to ..." )]]> #! If this is set in PackageInfo.g as #! PkgInfo.AutoDoc.TitlePage, it has the same meaning as this -#! option; see subsection in chapter -#! for details and an example. +#! option; see subsection in chapter +#! for details and an example. #!

#! For the list of valid title-page elements, see the #! &GAPDoc; manual, specifically section . diff --git a/makedoc.g b/makedoc.g index 87944e71..e96df43b 100644 --- a/makedoc.g +++ b/makedoc.g @@ -8,7 +8,11 @@ LoadPackage("AutoDoc"); AutoDoc( rec( - autodoc := true, + autodoc := rec( + files := [ "doc/Overview.autodoc", + "doc/Tutorials.autodoc", + "doc/Comments.autodoc" ], + ), gapdoc := rec( LaTeXOptions := rec( EarlyExtraPreamble := """ \usepackage{a4wide} @@ -16,9 +20,6 @@ AutoDoc( rec( """ ) ), scaffold := rec( - includes := [ "Overview.xml", - "Tutorials.xml", - "Comments.xml" ], bib := "bib.xml", ) )); diff --git a/regen_tests.g b/regen_tests.g index 5260556b..2c651508 100644 --- a/regen_tests.g +++ b/regen_tests.g @@ -1,11 +1,12 @@ if fail = LoadPackage("AutoDoc") then Error("failed to load AutoDoc package"); fi; +LoadPackage("io", false); SetInfoLevel(InfoAutoDoc, 1); AUTODOC_RegenWorkSheetExpected := function(wsdir, ws) - local sheetdir, expecteddir, filenames, old; + local sheetdir, expecteddir, filenames, old, f, tstfiles, x; sheetdir := Filename(wsdir, Concatenation(ws, ".sheet")); if not IsString(sheetdir) or not IsDirectoryPath(sheetdir) then @@ -31,6 +32,25 @@ AUTODOC_RegenWorkSheetExpected := function(wsdir, ws) SetInfoLevel(InfoGAPDoc, 0); AutoDocWorksheet(filenames, rec(dir := expecteddir, extract_examples := true)); SetInfoLevel(InfoGAPDoc, old); + + # Keep only deterministic reference outputs. + filenames := DirectoryContents(expecteddir); + filenames := Filtered(filenames, f -> f <> "." and f <> ".."); + for f in filenames do + if f = "tst" then + tstfiles := DirectoryContents(Filename(expecteddir, "tst")); + tstfiles := Filtered(tstfiles, x -> x <> "." and x <> ".."); + for x in tstfiles do + if PositionSublist(x, ".tst") <> Length(x) - 3 then + RemoveFile(Filename(Filename(expecteddir, "tst"), x)); + fi; + od; + continue; + fi; + if PositionSublist(f, ".xml") <> Length(f) - 3 then + RemoveFile(Filename(expecteddir, f)); + fi; + od; end; AUTODOC_RegenAllWorkSheetExpected := function() @@ -46,5 +66,70 @@ AUTODOC_RegenAllWorkSheetExpected := function() od; end; +AUTODOC_RegenManualExpected := function() + local pkgdir, olddir, tempdir, expecteddir, files, old_gapdoc_level, + old_warning_level, file, docdir; + + pkgdir := DirectoriesPackageLibrary("AutoDoc", ""); + pkgdir := pkgdir[1]; + if not IsDirectoryPath(pkgdir) then + Error("could not access AutoDoc package directory"); + fi; + + olddir := AUTODOC_CurrentDirectory(); + tempdir := Filename(DirectoryTemporary(), "autodoc-manual-expected"); + if IsDirectoryPath(tempdir) then + RemoveDirectoryRecursively(tempdir); + fi; + + Exec(Concatenation("cp -R \"", Filename(pkgdir, ""), "\" \"", tempdir, "\"")); + if not IsDirectoryPath(tempdir) then + Error("failed to create temporary package copy"); + fi; + + docdir := Concatenation(tempdir, "/doc"); + files := DirectoryContents(docdir); + files := Filtered(files, + f -> f <> "." and f <> ".." and + Length(f) >= 6 and f[1] = '_' and + PositionSublist(f, ".xml") = Length(f) - 3); + for file in files do + RemoveFile(Concatenation(docdir, "/", file)); + od; + + old_gapdoc_level := InfoLevel(InfoGAPDoc); + old_warning_level := InfoLevel(InfoWarning); + SetInfoLevel(InfoGAPDoc, 0); + SetInfoLevel(InfoWarning, 0); + ChangeDirectoryCurrent(tempdir); + Read("makedoc.g"); + ChangeDirectoryCurrent(olddir); + SetInfoLevel(InfoGAPDoc, old_gapdoc_level); + SetInfoLevel(InfoWarning, old_warning_level); + + expecteddir := Filename(pkgdir, "tst/manual.expected"); + if IsDirectoryPath(expecteddir) then + RemoveDirectoryRecursively(expecteddir); + fi; + AUTODOC_CreateDirIfMissing(expecteddir); + + docdir := Concatenation(tempdir, "/doc"); + files := DirectoryContents(docdir); + files := Filtered(files, + f -> f <> "." and f <> ".." and + Length(f) >= 6 and f[1] = '_' and + PositionSublist(f, ".xml") = Length(f) - 3); + Sort(files); + for file in files do + Exec(Concatenation( + "cp \"", docdir, "/", file, "\" \"", + expecteddir, "/", file, "\"" + )); + od; + + RemoveDirectoryRecursively(tempdir); +end; + AUTODOC_RegenAllWorkSheetExpected(); +AUTODOC_RegenManualExpected(); QUIT_GAP(0); diff --git a/tst/dogfood.tst b/tst/dogfood.tst index 7ccf2e72..1b39c4f8 100644 --- a/tst/dogfood.tst +++ b/tst/dogfood.tst @@ -44,15 +44,24 @@ gap> ChangeDirectoryCurrent(olddir); true # prepare to compare the output to the reference output -# No point in testing chapters 1 or 2 unless/until they are converted to autodoc gap> docdir := Directory(Concatenation(tempdir, "/doc"));; gap> ex_dir := DirectoriesPackageLibrary( "AutoDoc", "tst/manual.expected" );; +gap> ex_dir := ex_dir[1];; -# check chapter 4 -gap> chap4 := Filename( docdir, "_Chapter_Reference.xml" );; -gap> chap4ref := Filename( ex_dir, "_Chapter_Reference.xml" );; -gap> AUTODOC_Diff("-u", chap4ref, chap4); -0 +# check all expected generated files +gap> files := DirectoryContents(ex_dir);; +gap> files := Filtered(files, f -> f <> "." and f <> "..");; +gap> Sort(files); +gap> for f in files do +> expected := Filename(ex_dir, f);; +> actual := Filename(docdir, f);; +> if not IsReadableFile(actual) then +> Error("missing generated file ", f); +> fi; +> if 0 <> AUTODOC_Diff("-u", expected, actual) then +> Error("diff detected in file ", f); +> fi; +> od; # gap> RemoveDirectoryRecursively(tempdir); diff --git a/tst/manual.expected/_AutoDocMainFile.xml b/tst/manual.expected/_AutoDocMainFile.xml index 0522a147..41994a72 100644 --- a/tst/manual.expected/_AutoDocMainFile.xml +++ b/tst/manual.expected/_AutoDocMainFile.xml @@ -1,4 +1,7 @@ +<#Include SYSTEM "_Chapter_Overview.xml"> +<#Include SYSTEM "_Chapter_Tutorials.xml"> +<#Include SYSTEM "_Chapter_Comments.xml"> <#Include SYSTEM "_Chapter_Reference.xml"> diff --git a/doc/Comments.xml b/tst/manual.expected/_Chapter_Comments.xml similarity index 85% rename from doc/Comments.xml rename to tst/manual.expected/_Chapter_Comments.xml index 9cf58bfd..b9a5dc77 100644 --- a/doc/Comments.xml +++ b/tst/manual.expected/_Chapter_Comments.xml @@ -1,28 +1,30 @@ - + + + + &AutoDoc; documentation comments +

You can document declarations of global functions and variables, operations, attributes etc. by inserting &AutoDoc; comments into your sources before these declarations. An &AutoDoc; comment always starts with #!. This is also the smallest possible &AutoDoc; command. If you want your declaration documented, just write #! at the line before the documentation. For example: - +

- +

This will produce a manual entry for the operation AnOperation.

- For declaration documentation, the associated declaration must appear immediately after the &AutoDoc; comment block. In particular, do not insert other code (such as if false then or assignments) between the comment block and the Declare... statement.

- Inside of &AutoDoc; comments, &AutoDoc; commands starting with @ can be used to control the output &AutoDoc; produces. Any comment line that does not start with an &AutoDoc; command is treated @@ -34,74 +36,90 @@ This lets you use the normal &GAPDoc; formatting toolbox directly inside For example:

for setup details. +#! See for setup details. #! The argument obj must satisfy IsObject. ]]> -

-As explained in chapter , you can combine &AutoDoc; +As explained in chapter , you can combine &AutoDoc; comments with hand-written XML and classic &GAPDoc; comments. For practical -setup and migration workflows, see chapter . - - -

+setup and migration workflows, see chapter . +

+

Documenting declarations +

In the bare form above, the manual entry for AnOperation will not contain much more than the name of the operation. In order to change this, there are several commands you can put into the &AutoDoc; comment before the declaration. Currently, the following commands are provided: +

+ +@Description descr - +

@Description descr -@Description descr Adds the text in the following lines of the &AutoDoc; to the description of the declaration in the manual. Lines are until the next &AutoDoc; command or until the declaration is reached. +

- + + +@Returns ret val + +

@Returns ret_val -@Returns ret_val The string ret_val is added to the documentation, with the text Returns: put in front of it. This should usually give a brief hint about the type or meaning of the value returned by the documented function. +

- -@Arguments args + + @Arguments args + +

+@Arguments args The string args contains a description of the arguments the function expects, including optional parts, which are denoted by square brackets. The argument names can be separated by whitespace, commas or square brackets for the optional arguments, like grp[, elm] or xx[y[z] ]. If &GAP; options are used, this can be followed by a colon : and one or more assignments, like n[, r]: tries := 100. +

- -@Group grpname + + @Group grpname + +

+@Group grpname Adds the following method to a group with the given name. -See section for more information about groups. +See section for more information about groups. +

- -@Label label + + @Label label -Adds label to the function as label. +

+@Label label +Adds label to the function as label. +

If this is not specified, then for declarations that involve a list of input filters (as is the case for DeclareOperation, DeclareAttribute, etc.), a default label is generated from this filter list. - -

leads to this: + true or false @@ -109,6 +127,7 @@ leads to this: +]]> while leads to this: + true or false @@ -123,19 +143,21 @@ leads to this: +]]> +

+ - -@ChapterInfo + @ChapterInfo chapter, section + +

+@ChapterInfo Adds the entry to the given chapter and section. Here, chapter and section are the respective titles. - - - As an example, a full &AutoDoc; comment with all options could look like this: - +

+

+ +

-
+ +
Other documentation comments +

There are also some commands which can be used in &AutoDoc; comments that are not associated to any declaration. This is useful for additional text in your documentation, examples, mathematical chapters, etc. +

+ +@Chapter name - +

@Chapter @ChapterLabel @ChapterTitle -@Chapter name Sets the active chapter, all subsequent functions which do not have an explicit chapter declared in their &AutoDoc; comment via @ChapterInfo will be added to this chapter. Also all text comments, i.e. lines that begin with #! without a command, and which do not follow after @Description, will be added to the chapter as regular text. Additionally, the chapters label will be set to Chapter_name. - +

Example: - +

- +

The @ChapterLabel label command can be used to set the label of the chapter to Chapter_label instead of Chapter_name. - +

Additionally, the chapter will be stored as _Chapter_label.xml. - +

The @ChapterTitle title command can be used to set a heading for the chapter that is different from name. Note that the title does not affect the label. - +

If you use all three commands, i.e.,

title is used for the headline, label for cross-referencing, and name for setting the same chapter as active chapter again. +

- + + +@Section name + +

@Section @SectionLabel @SectionTitle -@Section name Sets an active section like @Chapter sets an active chapter. The section automatically ends with the next @Section or @Chapter command. - +

- +

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. +

- + + +@Subsection name + +

@Subsection @SubsectionLabel @SubsectionTitle -@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. - +

- +

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. +

- -@BeginGroup + + @BeginGroup [grpname] + +

+@BeginGroup 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 @@ -254,63 +295,79 @@ generated. The effect of this command is ended when an @EndGroup command is reached.

- -See section for more information about groups. +See section for more information about groups. +

- -@EndGroup + + @EndGroup -Ends the current group. +

+@EndGroup +Ends the current group. +

DeclareOperation( "NonGroupedOperation", [ IsObject ] ); - +

#! DeclareOperation( "GroupedOperation", [ IsList, IsRubbish ] ); #! @EndGroup ]]>

 +

- -@GroupTitle + + @GroupTitle title + +

+@GroupTitle 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. +first entry in the group. See for more information. +

- -@Level + + @Level lvl + +

+@Level 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.

- -See section for more information about levels. +See section for more information about levels. +

- -@ResetLevel + + @ResetLevel + +

+@ResetLevel Resets the current level to 0.

- + +@BeginExample and @EndExample + +

@BeginExample @EndExample -@BeginExample and @EndExample @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, @@ -320,7 +377,6 @@ 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:

Order(S5); The &AutoDoc; command @Example is an alias of @BeginExample. If you enable extract_examples := true when calling , these examples can also be turned into .tst files (see -Section ). +Section ). +

- + +@BeginExampleSession and @EndExampleSession + +

@BeginExampleSession @EndExampleSession -@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 ).

- To illustrate this command, consider this input:

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 @@ -379,66 +437,81 @@ 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. +

- + +@BeginLog and @EndLog + +

@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. The &AutoDoc; command @Log is an alias of @BeginLog. +

- + + +@BeginLogSession and @EndLogSession + +

@BeginLogSession @EndLogSession -@BeginLogSession and @EndLogSession 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 ). The &AutoDoc; command @LogSession is an alias of @BeginLogSession. +

- -@DoNotReadRestOfFile + + @DoNotReadRestOfFile + +

+@DoNotReadRestOfFile Prevents the rest of the file from being read by the parser. Useful for unfinished or temporary files. - +

#! @DoNotReadRestOfFile - +

#! This will not appear in the manual. ]]>

 +

- + + +@BeginChunk name, @EndChunk, and @InsertChunk name + +

@BeginChunk name @EndChunk @InsertChunk name -@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.

#! @InsertChunk MyChunk ## The text "Hello, world." is inserted right before this. ]]> - +

You can use this to define an example like this in one file: - +

- +

And then later, insert the example in a different file, like this: - +

- +

- + + +@BeginCode name, @EndCode, and @InsertCode name + +

@BeginCode name @EndCode @InsertCode name -@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. @@ -470,50 +546,61 @@ directly into the manual. #! @BeginCode Increment i := i + 1; #! @EndCode - +

#! @InsertCode Increment ## Code is inserted here. ]]>

 +

- + + +@LatexOnly text, @BeginLatexOnly, and @EndLatexOnly + +

@LatexOnly text @BeginLatexOnly @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.

#! @LatexOnly \include{picture.tex} ]]> +

- + + +@NotLatex text, @BeginNotLatex, and @EndNotLatex + +

@NotLatex text @BeginNotLatex @EndNotLatex -@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.

#! @NotLatex For further information see the PDF version of this manual. ]]> +

+

-
+
Title page commands +

The following commands can be used to add corresponding parts to the title page of a document generated by &AutoDoc;. @@ -556,21 +643,27 @@ extracted from PackageInfo.g. If you set them explicitly in comments, they override extracted or scaffold-defined values. This is usually most useful for worksheets created with , since worksheets do not have a PackageInfo.g file from which this information could be extracted. +

-
+ +
Plain text files +

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 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 @@ -580,44 +673,41 @@ 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

#! @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 ); ]]>

 - +

produces the following: - +

+

A family of operations @@ -629,18 +719,22 @@ Second sentence. Third sentence. - +]]> +

-
+ +
Level - Levels can be set to not write certain parts in the manual by default. + +

+Levels can be set to not write certain parts in the manual by default. Every entry has by default the level 0. The command @Level can be used to set the level of the following part to a higher level, for example 1, and prevent it from being printed to the manual by default. However, if one sets the level to a higher value in the autodoc option of &AutoDoc;, the parts will be included in the manual at the specific place. - +

+

-
+ +
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;, but do not follow them strictly. Neither are all features of the Markdown language supported. The following subsections describe what is possible. +

+ +Lists - - Lists - - One can create lists of items by beginning a new line with *, +, -, followed by one +

+One can create lists of items by beginning a new line with *, +, -, followed by one space. The first item starts the list. When items are longer than one line, the following lines have to be indented by at least two spaces. The list ends when a line which does not start a new item is not indented by two spaces. Of course lists can be nested. Here is an example: - +

- +

This is the output:
The list starts in the next line - - - item 1 - - - item 2 - which is a bit longer - - - and also contains a nested list - - - with two items - - - - - item 3 of the outer list - - + + +item 1 + + +item 2 + which is a bit longer + + +and also contains a nested list + + +with two items + + + + +item 3 of the outer list + + This does not belong to the list anymore.
- - +

The *, -, and + are fully interchangeable and can even be used mixed, but this is not recommended. - +

- - Math modes - - One can start an inline formula with a $, and also end it with $, just like in &LaTeX;. This will translate into - &GAPDoc;s inline math environment. For display mode one can use $$, also like &LaTeX;. - + + +Math modes + +

+One can start an inline formula with a $, and also end it with $, just like in &LaTeX;. This will translate into + &GAPDoc;s inline math environment. For display mode one can use $$, also like &LaTeX;. +

- +

produces the following output:
This is an inline formula: 1+1 = 2. This is a display formula: \sum_{i=1}^n i. - +

- - Emphasize - - One can emphasize text by using two asterisks (**) or two underscores (__) at the + + +Emphasize + +

+One can emphasize text by using two asterisks (**) or two underscores (__) at the beginning and the end of the text which should be emphasized. Example: - +

- +

This produces the following output:
This is very important. This is also important. Naturally, more than one line can be important. - +

- - Inline code - One can mark inline code snippets by using backticks (`) at the - beginning and the end of the text which should be marked as code. Example: + +Inline code +

+One can mark inline code snippets by using backticks (`) at the + beginning and the end of the text which should be marked as code. Example: +

- +

This produces the following output:
Call function foobar() at the start. - +

- - Fenced code blocks - One can insert verbatim code blocks by placing the code between lines + +Fenced code blocks + +

+One can insert verbatim code blocks by placing the code between lines containing at least three backticks or at least three tildes. The opening fence may optionally be followed by an info string. The values @listing, @example, and @log select the corresponding GAPDoc element; any other value is currently ignored. If nothing is specified the default is to generate <Listing>. Example: - +

#! #I some log message #! ``` ]]> - +

This produces the following output:
-

- [ 1 .. 3 ] ^ 2; [ 1, 4, 9 ] ]]> - - +

+

-
+ +
Deprecated commands +

The following commands used to be supported, but are not supported anymore. - +

@EndSection You can simply remove any use of this, &AutoDoc; ends sections automatically @@ -822,11 +930,12 @@ at the start of any new subsection, section or chapter. It suffices to prepend each declaration that is meant to appear in the manual with a minimal &AutoDoc; comment #!. @BeginSystem name, @EndSystem, and @InsertSystem name -Please use the chunk commands from subsection instead. +Please use the chunk commands from subsection instead. @AutoDocPlainText and @EndAutoDocPlainText Use .autodoc files or &AutoDoc; comments instead. -

+ + diff --git a/tst/manual.expected/_Chapter_Overview.xml b/tst/manual.expected/_Chapter_Overview.xml new file mode 100644 index 00000000..3726076e --- /dev/null +++ b/tst/manual.expected/_Chapter_Overview.xml @@ -0,0 +1,91 @@ + + + + +What &AutoDoc; offers + +

+&AutoDoc; helps you create and maintain package manuals for &GAP;. +It is built on top of &GAPDoc; and generates the XML input that +&GAPDoc; consumes. +So &AutoDoc; complements &GAPDoc; instead of replacing it. +

+The package is designed for a mix and match workflow: +you can adopt only the parts that help you today, and add more over time. +

+

+Core features + +

+ + +Build package manuals via one reproducible command, usually + gap makedoc.g. + + +Generate and maintain a title page from metadata in + PackageInfo.g. + + +Generate and maintain a main XML file that includes your chapters. + + +Extract manual examples into .tst files via + extract_examples := true. + + +Document declarations directly in source files via &AutoDoc; + comments beginning with #!. + + +Combine &AutoDoc; comments, classic &GAPDoc; source comments, + and hand-written XML chapters in one manual. + + +

+

+ + +
+Adopting &AutoDoc; incrementally + +

+You do not have to switch everything at once. +Typical adoption paths include: + + +Use only to rebuild an existing &GAPDoc; manual. + + +Enable only title-page generation, while keeping your custom main XML. + + +Keep your existing title page but use generated entities such as + &VERSION;, &RELEASEYEAR;, and &RELEASEDATE;. + + +Add &AutoDoc; comments only for new code, and leave old documentation as-is. + + +Later, gradually move chapters or source documentation to your preferred style. + + +

+This flexibility is central: &AutoDoc; should make your current setup better, +without forcing a full rewrite first. +

+

+ + +
+Where to continue + +

+For practical setup and migration workflows, continue with chapter +. For the command reference of documentation comments, +see chapter . +

+ + + + diff --git a/tst/manual.expected/_Chapter_Reference.xml b/tst/manual.expected/_Chapter_Reference.xml index ae6fe0ea..7146c1ba 100644 --- a/tst/manual.expected/_Chapter_Reference.xml +++ b/tst/manual.expected/_Chapter_Reference.xml @@ -79,7 +79,7 @@ These tasks can be enabled independently, so you can use as much or as little of &AutoDoc; as your package currently needs. - For more information and some examples, please refer to Chapter . + For more information and some examples, please refer to Chapter .

The parameters have the following meanings: @@ -214,8 +214,8 @@ rec( Acknowledgements := "Many thanks to ..." )]]> If this is set in PackageInfo.g as PkgInfo.AutoDoc.TitlePage, it has the same meaning as this - option; see subsection in chapter - for details and an example. + option; see subsection in chapter + for details and an example.

For the list of valid title-page elements, see the &GAPDoc; manual, specifically section . diff --git a/doc/Tutorials.xml b/tst/manual.expected/_Chapter_Tutorials.xml similarity index 88% rename from doc/Tutorials.xml rename to tst/manual.expected/_Chapter_Tutorials.xml index d04176fc..318f9a9e 100644 --- a/doc/Tutorials.xml +++ b/tst/manual.expected/_Chapter_Tutorials.xml @@ -1,51 +1,63 @@ - + + + + Getting started using &AutoDoc; +

This chapter gives practical workflows for adding &AutoDoc; to a package. For a high-level feature overview and adoption strategy, see -chapter .

- -

+chapter . +

+

Choose your workflow +

You can use &AutoDoc; in several ways, and it is fine to combine them: -Start a new package manual from scratch (Section ). -Integrate &AutoDoc; into an existing &GAPDoc; manual -(Section ). -Use only selected features, such as title-page generation or -example extraction, while keeping everything else unchanged. + +Start a new package manual from scratch (Section ). + + +Integrate &AutoDoc; into an existing &GAPDoc; manual + (Section ). + + +Use only selected features, such as title-page generation or + example extraction, while keeping everything else unchanged. + - +

This incremental approach is encouraged: start with the smallest helpful step, then adopt additional features when useful.

-
+ +
Creating a package manual from scratch +

Suppose your package is already up and running, but so far has no manual. Then you can rapidly generate a scaffold for a package manual using the command like this, while running &GAP; from within your package's directory (the one containing the PackageInfo.g file): -

+ +]]> This first reads the PackageInfo.g file from the current directory. It extracts information about the package from it -(such as its name and version, see Section ). +(such as its name and version, see Section ). It then creates two XML files doc/NAME_OF_YOUR_PACKAGE.xml and doc/title.xml inside the package directory. Finally, it runs &GAPDoc; on them to produce a nice initial PDF and HTML version of your fresh manual.

- To ensure that the &GAP; help system picks up your package manual, you should also add something like the following to your PackageInfo.g: -

+ - +]]> +

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. @@ -64,7 +76,6 @@ 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). @@ -72,47 +83,47 @@ 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 , as well as Section - of this manual on how to teach the + 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 ). +(see Section ).

- You will probably want to re-run the 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 makedoc.g directory, with content based on the following example: -

+ +]]> Then you can regenerate the package manual from the command line with the following command, executed from within the package directory: -+ - +]]> +

If you also want regression tests from your manual examples, enable extract_examples := true; this is explained in -Section . - +Section . +

-
+
Documenting code with &AutoDoc; +

To get one of your global functions, operations, attributes etc. to appear in the package manual, simply insert an &AutoDoc; comment of the form #! directly in front of it. For example: -

+ - +]]> +

This tiny change is already sufficient to ensure that the operation appears in the manual. In general, you will want to add further information about the operation, such as in the following example: @@ -120,7 +131,7 @@ information about the operation, such as in the following example: Important: the comment block must be immediately followed by the declaration it documents. Do not place other code between the comment block and the Declare... statement. - +

conv. DeclareOperation( "ToricVariety", [ IsConvexObject ] ); ]]> - +

In these comment lines, you can freely use normal &GAPDoc; XML markup (with the usual exceptions for lines starting with @, which are interpreted as &AutoDoc; commands). So, for instance, tags like <Ref>, <A>, <K>, <List>, etc. can be written directly in #! comment text. - +

For a thorough description of what you can do with &AutoDoc; -documentation comments, please refer to chapter . +documentation comments, please refer to chapter .

- - +

- - +

Suppose you have not been using &GAPDoc; before but instead used the process -described in section to create your manual. +described in section to create your manual. Then the following &GAP; command will regenerate the manual and automatically include all newly documented functions, operations etc.: - -

+

+

- +]]> +

If you are not using the scaffolding feature, e.g. because you already have an existing &GAPDoc; based manual, then you can still use &AutoDoc; documentation comments. Just make sure to first edit the main XML file of your documentation, and insert the line -

+ - +]]> in a suitable place. This means that you can mix &AutoDoc; documentation comments 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 then runs &GAPDoc; to produce HTML and PDF output, but does not touch your documentation XML files otherwise. -

+ - - +]]> +

-
+
Using &AutoDoc; in an existing &GAPDoc; manual +

Even if you already have an existing &GAPDoc; manual, it might be interesting for you to use &AutoDoc; for two purposes:

- First, with &AutoDoc; it is very convenient to regenerate your documentation.

- Secondly, the scaffolding feature which generates a title page with all the metadata of your package in a uniform way is very handy. The somewhat tedious process of keeping your title page in @@ -218,21 +225,19 @@ sync with your PackageInfo.g is fully automated this way (including the correct version, release data, author information and so on).

- There are various examples of packages using &AutoDoc; for this purpose only, e.g. &io; and orb.

- In particular, this setup works well if you want to keep your existing manual structure and only adopt selected &AutoDoc; features first; for example automatic title-page data and predefined entities such as &VERSION;, &RELEASEYEAR; and &RELEASEDATE; -(see Section ). +(see Section ).

+ +Using &AutoDoc; on a complete &GAPDoc; manual - - 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. @@ -240,36 +245,39 @@ 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; session started in the root directory of your package: -

+ +]]> Note that in particular, you do not have to worry about keeping a list of your implementation files up-to-date.

But there is more. &AutoDoc; can create .tst files from the examples in your manual to test your package. This can be achieved via -

+ +]]> Now files PACKAGENAME01.tst, PACKAGENAME02.tst and so appear in the tst/ subdirectory of your package, and can be tested as usual using respectively . +

- + + Setting different &GAPDoc; options +

Sometimes, the default values for the &GAPDoc; command used by &AutoDoc; may not be suitable for your manual.

Suppose your main XML file is not named PACKAGENAME.xml, but rather something else, e.g. main.xml. Then you can tell &AutoDoc; to use this file as the main XML file via -

+ +]]>

As explained above, by default &AutoDoc; scans all .g, .gd and .gi files it can find inside of your package root directory, and in the subdirectories gap, @@ -278,16 +286,16 @@ If you keep source files with documentation in other directories, you can adjust the list of directories AutoDoc scans via the scan_dirs option. The following example illustrates this by instructing &AutoDoc; to only search in the subdirectory package_sources of the package's root directory. -

+ +]]> You can also specify an explicit list of files containing documentation, which will be searched in addition to any files located within the scan directories: -+ +]]> Giving such a file does not prevent the standard scan_dirs from being scanned for other files.

@@ -299,38 +307,38 @@ Suppose you are starting &GAP; in the root path of your package as always, and the standard call of will then build the documentation in the doc subdirectory of your package. From this directory, the gap root directory has the relative path ../../... Then you can enable the relative paths by -

+ +]]> or, since ../../.. is the standard option for gap_root_relative_path, by -+ - +]]> +

- - -Checklist for converting an existing &GAPDoc; manual to use &AutoDoc; - + +Checklist for converting an existing &GAPDoc; manual to use &AutoDoc; + +

Here is a checklist for authors of a package &PackageName;, which already has a &GAPDoc; based manual, who wish to use &AutoDoc; to build the manual from now on. We assume that the manual is currently built by reading a file makedoc.g and that the main .xml file is named manual.xml. -

+

The files PackageInfo.g, makedoc.g, doc/title.xml and doc/PackageName.xml (if it exists) will be altered by this procedure, so it may be wise to keep backup copies. -

+

You should have copies of the &AutoDoc; files PackageInfo.g and makedoc.g to hand when reading these instructions. -

+

Copy AutoDoc/makedoc.g to PackageName/makedoc.g. @@ -422,23 +430,27 @@ and doc/title.xml. You should now be ready to run &GAP; and Read("makedoc.g"); in your package root directory. +

+ -

-
+ +
Scaffolds +

- - +

+ Generating a title page +

For most (if not all) &GAP; packages, the title page of the package manual lists information such as the release date, version, names and contact details of the authors, and so on. - +

All this data is also contained in your PackageInfo.g, and whenever you make a change to that file, there is a risk that you forget to update your manual to match. And even if you don't forget it, you of course @@ -459,92 +471,88 @@ solve the problem of updating package authors addresses. Neither of these is a big issue, of course, but there have been plenty examples in the past where people forget either of these two things, and it can be slightly embarrassing. It may even require you to make a new release just to fix the issue, which in -our opinion is a sad waste of your valuable time.

- +our opinion is a sad waste of your valuable time. +

So instead of worrying about manually synchronising these things, you can instruct &AutoDoc; to generate a title page for your manual based on the information in your PackageInfo.g. The following commands do just that (in addition to building your manual), by generating a file called doc/title.xml. -

+ +]]> Note that this only outputs doc/title.xml but does not touch any other files of your documentation. In particular, you need -to explicitly include doc/title.xml from your main XML file.

- +to explicitly include doc/title.xml from your main XML file. +

However, you can also tell &AutoDoc; to maintain the main XML file for you, in which case this is automatic. In fact, this is the default if you enable scaffolding; the above example command explicitly told &AutoDoc; not to generate a main page. - +

- + + Generating the main XML file +

The following generates a main XML file for your documentation in addition to the title page. The main XML file includes the title page by default, as well as any documentation generated from &AutoDoc; documentation comments. -

+ - +]]> +

You can instruct &AutoDoc; to include additional XML files by giving it a list of filenames, as in the following example: -

+ - +]]> +

For more information, please consult the documentation of the function. - - +

- + What data is used from PackageInfo.g? +

&AutoDoc; can use data from PackageInfo.g in order to generate a title page. Specifically, the following components of the package info record are taken into account: - +

- PackageName This is used to set the <Title> element of the title page. - Subtitle This is used to set the <Subtitle> element of the title page. - Version This is used to set the <Version> element of the title page, with the string Version prepended. - Date This is used to set the <Date> element of the title page. - Persons This is used to generate <Author> elements in the generated title page. - PackageDoc This is a record (or a list of records) which is used to tell the &GAP; help system about the package manual. Currently &AutoDoc; @@ -552,12 +560,10 @@ extracts the value of the PackageDoc.BookName component and then passes that on to &GAPDoc; when creating the HTML, PDF and text versions of the manual. - AutoDoc This record controls extra settings used by &AutoDoc; while generating the manual. In particular, PkgInfo.AutoDoc.TitlePage lets you add or override title-page elements coming from package metadata. -

Typical fields you may set there include TitleComment, Abstract, Copyright, Acknowledgements and Colophon. @@ -575,45 +581,50 @@ SetPackageInfo( rec( ]]>

 This inserts <Copyright> and <Acknowledgements> blocks into the generated title.xml. -

PkgInfo.AutoDoc.TitlePage has exactly the same meaning as scaffold.TitlePage in . The function documentation for scaffold.TitlePage points back to this subsection. - - +

- + + Entities from PackageInfo.g and scaffold options +

Besides title-page fields, you can define custom entities in AutoDoc.entities inside PackageInfo.g. They are written to doc/_entities.xml, so they can be used both by generated main files and by hand-written main XML files.

- In addition, &AutoDoc; predefines the entities VERSION, RELEASEYEAR and RELEASEDATE, derived from package metadata. This is useful if you keep a custom title page or custom chapters and still want release information to stay synchronized with PackageInfo.g.

- You can specify scaffold-related settings in PackageInfo.g and in your makedoc.g call at the same time; both records are merged, and values from makedoc.g take precedence when both define the same key. +

+

-
+ +
Worksheets +

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

+ + + diff --git a/tst/manual.expected/_entities.xml b/tst/manual.expected/_entities.xml new file mode 100644 index 00000000..981cc39e --- /dev/null +++ b/tst/manual.expected/_entities.xml @@ -0,0 +1,6 @@ +AutoDoc'> +PackageName'> + + + +io'>