diff --git a/.gitignore b/.gitignore index 11cd5f6c..0485cea2 100644 --- a/.gitignore +++ b/.gitignore @@ -22,7 +22,7 @@ /doc/*.toc /doc/*.txt /doc/*Bib.xml -/doc/*Bib.xml.bib +/doc/*.xml.bib /doc/AutoDoc.xml /doc/_AutoDocMainFile.xml /doc/_Chapter*xml diff --git a/doc/Comments.autodoc b/doc/Comments.autodoc new file mode 100644 index 00000000..281d6a9a --- /dev/null +++ b/doc/Comments.autodoc @@ -0,0 +1,173 @@ +@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: + +@BeginLogSession +#! +DeclareOperation( "AnOperation", + [ IsList ] ); +@EndLogSession + +This will produce a manual entry for the operation `AnOperation`. +

+ +Inside of &AutoDoc; comments, **&AutoDoc; commands** +starting with `@` can be used to control the output &AutoDoc; produces. + + +@Section Declarations +@SectionTitle 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: + +@InsertChunk documenting_declaration_commands + 
 
+As an example, a full &AutoDoc; comment with all the most common options could +look like this: + +@BeginLogSession +#! @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 +#! @FunctionLabel chardegblocks +#! @ChapterInfo Blocks, Attributes +DeclareAttribute( "CharacterDegreesOfBlocks", + IsBrauerTable ); +@EndLogSession + +@Section Recognized declarations +@InsertChunk recognized_declarators + +Note that in the particular case of `DeclareSynonym`, &AutoDoc; has no way to +infer the argument list, so when documenting such a declaration, you must use +the `@Arguments` command to supply that information. + +@Section Others +@SectionTitle Other documentation comments + +There are also some commands which can be used in &AutoDoc; comments +that are not associated to any one particular declaration. This is useful for +additional text in your documentation, examples, mathematical chapters, etc.. + +@InsertChunk other_commands +@EndSection + +@InsertChunk titlepage_commands + +@Section PlainText +@SectionLabel Plain +@SectionTitle 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 regions in other files which +should be regarded as plain text &AutoDoc; parts. All commands can be used +in a plain text section of a file, without the leading `#!`. + +@Section Groups +@SectionLabel Groups +@SectionTitle 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. + +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 +@BeginLogSession +#! @BeginGroup Group1 + +#! @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 ); +@EndLogSession + +produces the following: + + + + + + + + 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. + +@BeginLogSession +#! 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. +@EndLogSession + +@Section MarkdownExtension +@SectionTitle 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 the Markdown-like +conventions that may be used. + +@InsertChunk markdown_conventions + +@EndSection diff --git a/doc/Comments.xml b/doc/Comments.xml deleted file mode 100644 index 5d738e54..00000000 --- a/doc/Comments.xml +++ /dev/null @@ -1,728 +0,0 @@ - -&AutoDoc; documentation comments - -You can document declarations of global functions and variables, operations, -attributes etc. by inserting &AutoDoc; comments into your sources before these declaration. -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. -

- -Inside of &AutoDoc; comments, &AutoDoc; commands -starting with @ can be used to control the output &AutoDoc; produces. - - -

-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 -@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 -@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 retuned by the documented function. - - - -@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 ⪆ options are used, this can be followed by a colon : -and one or more assignments, like n[, r]: tries := 100. - - - -@Group -@Group grpname -Adds the following method to a group with the given name. -See section for more information about groups. - - - -@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 - - - - -while - -leads to this: - - - true or false - - - - - - - -@ChapterInfo -@ChapterInfo chapter, section -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: - -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 -#! @FunctionLabel chardegblocks -#! @ChapterInfo Blocks, Attributes -DeclareAttribute( "CharacterDegreesOfBlocks", - IsBrauerTable ); -]]> - -
- -
-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 -@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 wil 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 -@SectionLabel -@SectionTitle -@Section name -Sets an active section like @Chapter sets an active chapter. - - - -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. - - - -@EndSection -@EndSection -Closes the current section. Please be careful here. Closing a section before -opening it might cause unexpected errors. - - - - - -@Subsection -@SubsectionLabel -@SubsectionTitle -@Subsection name -Sets an active subsection like @Chapter sets an active chapter. - - - -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. - - - -@EndSubsection -@EndSubsection -Closes the current subsection. Please be careful here. Closing a subsection before -opening it might cause unexpected errors. - - - - -@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 affect 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] -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. - - - -@EndGroup -@EndGroup -Ends the current group. - -

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

- -See section for more information about groups. - - - -@ResetLevel -@ResetLevel -Resets the current level to 0. -

- - - - -@BeginExample and @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, -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. -

-The &AutoDoc; command @Example is an alias of @BeginExample. - - - - -@BeginExampleSession and @EndExampleSession -@BeginExampleSession and @EndExampleSession -@ExampleSession 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 @ExampleSession: - S5 := SymmetricGroup(5); -#! Sym( [ 1 .. 5 ] ) -#! gap> Order(S5); -#! 120 -#! @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. - - - - - -@BeginLog and @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 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. - - - -@DoNotReadRestOfFile -@DoNotReadRestOfFile -Prevents the rest of the file from being read by the parser. Useful for -not finished or temporary files. - - - - - -@BeginChunk, @EndChunk, and @InsertChunk -@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. - - -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: - - - - - - -@BeginSystem, @EndSystem, and @InsertSystem -@BeginSystem name, @EndSystem, and @InsertSystem name -Same as @BeginChunk etc. This command is deprecated. Please use chunk instead. - - - -@BeginCode, @EndCode, and @InsertCode -@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. - - - - -@@LatexOnly, @BeginLatexOnly, and @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. - - - -
- - -
-Title page commands - -The following commands can be used to add the corresponding parts to the title page of -the document, in case the scaffolding is enabled. - - - @Title - - - @Subtitle - - - @Version - - - @TitleComment - - - @Author - - - @Date - - - @Address - - - @Abstract - - - @Copyright - - - @Acknowledgements - - - @Colophon - - -Those add the following lines at the corresponding point of the title page. Please note that many of those -things can be (better) extracted from the PackageInfo.g. In case you set some of those, -the extracted or in scaffold defined items will be overwritten. While this is not very useful for -documenting packages, they are necessary for worksheets created with , -since they do not have a PackageInfo to extract those information. -
- -
- 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. - -
- -
-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. -

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

- -produces the following: - - - - - - - - First sentence. - Second sentence. - Third sentence. - - - -
- -
-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. - - -
- -
-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 - - 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 - - -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;. - - - - 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 - 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. - - -
- - diff --git a/doc/Tutorials.xml b/doc/Tutorials.xml index a03fccca..5ba6a900 100644 --- a/doc/Tutorials.xml +++ b/doc/Tutorials.xml @@ -122,7 +122,7 @@ DeclareOperation( "ToricVariety", [ IsConvexObject ] ); ]]> For a thorough description of what you can do with &AutoDoc; -documentation comments, please refer to chapter . +documentation comments, please refer to chapter .

+ +AutoDoc + +

+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 ⪆. 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. + +gapdoc_latex_options + +Must be a record with entries which can be understood by 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. + + + +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 + + +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" ]. + +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

+ + + +maketest + +The maketest item can be true or a record. When it is true, +a simple maketest.g 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. + + + + + + +

+ + + + +

+ + +
+Examples + +

+Some basic examples for using AutoDoc were already shown in +Chapter . +

+ + + + diff --git a/tst/_Chapter_AutoDoc_worksheets.reference b/tst/_Chapter_AutoDoc_worksheets.reference new file mode 100644 index 00000000..f1cebfdc --- /dev/null +++ b/tst/_Chapter_AutoDoc_worksheets.reference @@ -0,0 +1,28 @@ +Intentional difference + + + + +AutoDoc worksheets + +
+Worksheets + + + + +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 --git a/tst/_Chapter_Comments.reference b/tst/_Chapter_Comments.reference new file mode 100644 index 00000000..ad726c4a --- /dev/null +++ b/tst/_Chapter_Comments.reference @@ -0,0 +1,1125 @@ +Intentional difference + + + + +&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. +

+

+Inside of &AutoDoc; comments, &AutoDoc; commands +starting with @ can be used to control the output &AutoDoc; produces. +

+

+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 + + +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 + + +The string ret_val is added to the documentation of the +declaration, 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 + + +The string args contains a description of the arguments +the declared 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 ⪆ options are +used, this can be followed by a colon : and one or more +assignments, like n[, r]: tries := 100. + + + + +@Group grpname + +@Group + + +Adds the following declaration to a group named grpname. +See section for more information +about groups. + + + + +@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 + + + + + 
+while + + + +leads to this: + + + true or false + + + + + +@ChapterInfo chapter, section + +@ChapterInfo + + +Adds the entry to the given chapter and section. Here, +chapter and section are the respective names. + + + + +@ItemType type [stream] + +@ItemType + + +Normally &AutoDoc; is able to infer whether a declaration is for +a global function, method, operator, filter, attribute, property, +etc. However, in some cases it cannot, for example in the case +of a DeclareSynonym declaration, or in some +InstallOtherMethod cases. In such cases, you can use the +@ItemType command to supply that information. The first +argument type specifies the type of the item; +it must be the name of the &GAPDoc; +entity corresponding to the desired type, e.g. Filt for +filters, Func for functions, and so on. See the &GAPDoc; +documentation for a full list. The optional second argument +stream specifies the default documentation stream of +&AutoDoc; in which the documentation will be emitted if no +section is specified. + + + + +@Level lvl + +@Level + + +Sets the level of documentation of this declaration. (Note that +this same command can also set the level of the current section or +chapter.) Levels are used to selectively prune portions of the +documentation, only level 0 (the default) documentation is +generated by default, but higher-level documentation can be +generated on request. See section +for more information about levels. + + + + + 
 
+As an example, a full &AutoDoc; comment with all the most common options could +look like this: +

+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 +#! @FunctionLabel chardegblocks +#! @ChapterInfo Blocks, Attributes +DeclareAttribute( "CharacterDegreesOfBlocks", + IsBrauerTable ); +]]> + + +

+

+ + +
+Recognized declarations + +The ⪆ declarations recognized by &AutoDoc; consist of the +following: +DeclareCategoryCollections +, DeclareCategory +, DeclareRepresentation +, DeclareAttribute +, DeclareProperty +, DeclareOperation +, DeclareFilter +, DeclareGlobalFunction +, KeyDependentOperation +, DeclareSynonym +, DeclareGlobalVariable +, DeclareInfoClass +, DeclareConstructor +, InstallMethod, and InstallOtherMethod. + +

+Note that in the particular case of DeclareSynonym, &AutoDoc; has no way to +infer the argument list, so when documenting such a declaration, you must use +the @Arguments command to supply that information. +

+

+ + +
+Other documentation comments + +

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

+ +@Chapter name + +@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 chapter's label wil +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 + + +Sets an active section like @Chapter sets an active chapter. + + + +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. + + + + +@EndSection + +@EndSection + + +Closes the current section. Please be careful here. Closing a +section before opening it might cause unexpected errors. + + + + + + + +@Subsection name + +@Subsection + + +@SubsectionLabel + + +@SubsectionTitle + + +Sets an active subsection like @Chapter sets an active +chapter. + + + +Analogous to @SectionLabel, 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. + + + + +@EndSubsection + +@EndSubsection + + +Closes the current subsection. Please be careful here. Closing a +subsection before opening it might cause unexpected errors. + + + + + + + +@BeginAutoDoc + +@BeginAutoDoc + + +Causes all subsequent declarations (until the next @EndAutoDoc +command) to be documented in the manual regardless of whether +they have any &AutoDoc; comment immediately preceding them. + + + + +@EndAutoDoc + +@EndAutoDoc + + +Ends any @BeginAutoDoc in effect. So from here on, again only +declarations with an explicit &AutoDoc; comment immediately +preceding them are added to the manual. + + + +Both of Operation1 and IsProperty would appear in the manual, +but Operation2 would not. + + + + +@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 generated. The effect of this command is ended when an +@EndGroup command is reached. +

+See section for more information +about groups. + + + + +@Endgroup + +@EndGroup + + +Ends the current group. + + + +See section for more information +about groups. + + + + +@SetLevel lvl + +@SetLevel + + +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. + + + + +@ResetLevel + +@ResetLevel + + +Resets the current documentation level to 0; +it is simply an alias for @SetLevel 0. + + + + +@BeginExample and @EndExample + +@BeginExample / @EndExample + + +@BeginExample inserts an example into the manual. The syntax +for examples is different from &GAPDoc;'s example syntax in +order to have a file that contains the example and is ⪆ +readable. To achieve this, ⪆ 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. + + + +The &AutoDoc; command @Example is an alias of @BeginExample. + + + + +@BeginExampleSession and @EndExampleSession + +@BeginExampleSession / @EndExampleSession + + +@BeginExampleSession inserts an example into the manual, but +in a different syntax. To understand the motivation, 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: + S5 := SymmetricGroup(5); +#! Sym( [ 1 .. 5 ] ) +#! gap> Order(S5); +#! 120 +#! @EndExampleSession +]]> + + +It inserts an example into the manual just as @BeginExample +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. + + + + +@BeginLog and @EndLog + +@BeginLog / @EndLog + + +This pair of commands works just like the @BeginExample and +@EndExample commands, but the example will not be tested. See +the &GAPDoc; manual for more information. The &AutoDoc; +command @Log is an alias for @BeginLog. + + + + +@BeginLogSession and @EndLogSession + +@BeginLogSession / @EndLogSession + + +This pair of commands works just like the @BeginExampleSession +and @EndExampleSession commands, 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 for @BeginLogSession. + + + + +@DoNotReadRestOfFile + +@DoNotReadRestOfFile + + +Prevents the rest of the file from being read by the +&AutoDoc; parser. Useful for unfinished or temporary files. + + + + + + + +@BeginChunk name, @EndChunk, and @InsertChunk name + +@BeginChunk / @EndChunk / @InsertChunk + + +Text inside a @BeginChunk / @EndChunk pair 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. Note that a chunk may +contain any autodoc components (text, examples, sections, etc.) +except for chapters. (To control the overall order of chapters, +you may want to arrange for a file declaring all of the +chapters to be processed early in &AutoDoc;'s operation, for +example by using the files entry of the autodoc record in the +invocation of &AutoDoc;, see +.) +

+If you do not provide an @EndChunk, the chunk ends at the end of +the file. + + + +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: + + + +The &AutoDoc; commands @BeginSystem, @EndSystem, and +@InsertSystem are deprecated aliases for these "chunk" +commands. Please use the "chunk" versions instead. + + + + +@BeginCode name, @EndCode, @InsertCode, @HereCode name + +@BeginCode / @EndCode / @InsertCode / @HereCode + + +The text between @BeginCode name and @EndCode is +inserted verbatim at the point where @InsertCode is called. +This is useful to insert code excerpts directly into the manual. +If you want to insert code immediately at the current point +in the documentation, use @HereCode rather than @BeginCode; +it still matches with @EndCode, but no name or +@InsertCode is necessary. + + + + + + + +@Index key [entry] + +@Index + + +Inserts an entry in the index sorted by key with written +entry entry (which defaults to key if entry +is omitted. The index entry refers to the point in the manual at +which the @Index command occurs. Note that documented +declarations generate index entries automatically, you don't +need to use an @Index call for each one. + + + + +@LatexOnly text, @BeginLatexOnly, and @EndLatexOnly + +@LatexOnly / @BeginLatexOnly / @EndLatexOnly + + +Code inserted between @BeginLatexOnly and @EndLatexOnly or +after @LatexOnly on a line is only inserted +in the PDF version of the manual or worksheet. It can hold +arbitrary LaTeX commands. + + + + + + + +@BeginAutoDocPlainText and @EndAutoDocPlainText + +@BeginAutoDocPlainText / @EndAutoDocPlainText + + +@BeginAutoDocPlainText mode turns on plain text mode, in which +#! comment characters are not needed for a line to be +processed by &AutoDoc; -- or, equivalently, in which every line +treated as if it were preceded by a #!. +@EndAutoDocPlainText reverts to ordinary mode, in which the +#! comment characters are necessary for a line to be processed +by &AutoDoc;. For more information on plain text mode, see +. + + + + +

+ + +

+

+Title page commands + +@Title + + +@Subtitle + + +@Version + + +@TitleComment + + +@Author + + +@Date + + +@Address + + +@Abstract + + +@Copyright + + +@Acknowledgements + + +@Colophon + + +The following commands can be used to add the corresponding parts to +the title page of the document, in case the scaffolding is +enabled. + + +@Title + + +@Subtitle + + +@Version + + +@TitleComment + + +@Author + + +@Date + + +@Address + + +@Abstract + + +@Copyright + + +@Acknowledgements + + +@Colophon + + +

+These commands add the following lines at the corresponding point of +the title page. Please note that many of those things can be (better) +extracted from the PackageInfo.g. In case you use the above commands, +the extracted or in-scaffold-defined items will be overwritten. While +this is not very useful for documenting packages, they are necessary +for worksheets created with , +since they do not have a PackageInfo.g from which to extract any of +this information. +

+ + + +

+

+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 regions in other files which +should be regarded as plain text &AutoDoc; parts. All commands can be used +in a plain text section of a file, without the leading #!. +

+

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

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

+produces the following: +

+ + + + + + +First sentence. +Second sentence. +Third sentence. + + +

+

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

+ + + +

+

+ + +
+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 the Markdown-like +conventions that may be used. +

+ +Paragraph breaks + +Paragraph breaks in Markdown style + + +An empty line between blocks of &AutoDoc; text (that is to say, text +processed by &AutoDoc; that is being inserted into the current +chapter, section, description, etc.) is converted into a paragraph +break. + + + + + + + +Lists + +Lists in Markdown style + + +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 + + +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 + +Math in Markdown Style + + +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;. If you need to produce a single $ in your +documentation, you can escape it with a backslash, i.e. \$ +produces a $. + + + +produces the following output:
+This is an inline formula: 1+1 = 2. +This is a display formula: + \sum_{i=1}^n i. +You can have this package for $0. + + + + +Emphasize + +Emphasizing text in Markdown style + + +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. + + + + +Code + +Code quotations in Markdown Style + + +One can include arbitrary characters in a font suggestive of source +code by preceding and following the code snippet with a single +backtick character (`). Any special meaning to &AutoDoc; +of the characters inside the backticked string is suppressed; +it may include &AutoDoc; commands, but they will not be executed. Note +however that currently, the matching beginning and ending backicks +must occur on the same source line. If you need to produce a +backtick character in your documentation, you can escape it with a +backslash, i.e. \` produces a single backtick. + + + + +

+

+ + + + diff --git a/tst/dogfood.tst b/tst/dogfood.tst new file mode 100644 index 00000000..608d6c8e --- /dev/null +++ b/tst/dogfood.tst @@ -0,0 +1,61 @@ +############################################################################# +## +## AutoDoc package +## +## Test the behavior of AutoDoc by generating its own manual +## +## Copyright 2018 +## Contributed by Glen Whitney, studioinfinity.org +## +## Licensed under the GPL 2 or later. +## +############################################################################# +#### Note: we set InfoWarning to 0 temporarily below because we have to +#### suppress a message from GAPDocManualLabFromSixFile +#### (which function is in the core lib/package.gi, so was hard to track down) + +gap> START_TEST( "AutoDoc package: dogfood.tst" ); +gap> tmpdir := DirectoryTemporary();; +gap> SetInfoLevel( InfoGAPDoc, 0 ); +gap> AutoDoc_just_a_test := true; +true +gap> Read("makedoc.g"); +gap> autodoc_args_rec.dir := tmpdir;; +gap> pkgdir := DirectoryCurrent();; +gap> tutfile := Filename(pkgdir, "doc/Tutorials.xml");; +gap> tutcontents := ReadAll(InputTextFile(tutfile));; +gap> tutcopy := Filename(tmpdir, "Tutorials.xml");; +gap> WriteAll(OutputTextFile(tutcopy,false), tutcontents); +true +gap> bibfile := Filename(pkgdir, "doc/bib.xml");; +gap> bibcontents := ReadAll(InputTextFile(bibfile));; +gap> bibcopy := Filename(tmpdir, "bib.xml");; +gap> WriteAll(OutputTextFile(bibcopy,false), bibcontents); +true +gap> SetInfoLevel( InfoWarning, 0 ); +gap> AutoDoc(autodoc_args_rec); +true +gap> SetInfoLevel( InfoWarning, 1 ); +gap> chap2 := Filename( tmpdir, "_Chapter_Comments.xml" );; +gap> chap2ref := Filename( pkgdir, "tst/_Chapter_Comments.reference" );; +gap> chap2diff := Filename( tmpdir, "chap2.diff");; +gap> command := Concatenation( "diff ", chap2ref, " ", chap2, " > ", chap2diff );; +gap> Exec( command ); +gap> ReadAll(InputTextFile(chap2diff)); +"1d0\n< Intentional difference\n" +gap> chap3 := Filename( Directory(tmpdir), "_Chapter_AutoDoc_worksheets.xml" );; +gap> chap3ref := Filename( pkgdir, "tst/_Chapter_AutoDoc_worksheets.reference" );; +gap> chap3diff := Filename( tmpdir, "chap3.diff");; +gap> command := Concatenation( "diff ", chap3ref, " ", chap3, " > ", chap3diff );; +gap> Exec( command ); +gap> ReadAll(InputTextFile(chap3diff)); +"1d0\n< Intentional difference\n" +gap> chap4 := Filename( Directory(tmpdir), "_Chapter_AutoDoc.xml" );; +gap> chap4ref := Filename( pkgdir, "tst/_Chapter_AutoDoc.reference" );; +gap> chap4diff := Filename( tmpdir, "chap4.diff");; +gap> command := Concatenation( "diff ", chap4ref, " ", chap4, " > ", chap4diff );; +gap> Exec( command ); +gap> ReadAll(InputTextFile(chap4diff)); +"1d0\n< Intentional difference\n" +gap> STOP_TEST( "dogfood.tst", 10000 ); +## No point in testing chapter 1 unless/until it is converted to autodoc diff --git a/tst/plaintextmode.tst b/tst/plaintextmode.tst new file mode 100644 index 00000000..89087054 --- /dev/null +++ b/tst/plaintextmode.tst @@ -0,0 +1,48 @@ +############################################################################# +## +## AutoDoc package +## +## Test the behavior of AutoDoc in plain text mode +## +## Copyright 2018 +## Contributed by Glen Whitney, studioinfinity.org +## +## Licensed under the GPL 2 or later. +## +############################################################################# + +gap> START_TEST( "AutoDoc package: plaintextmode.tst" ); +gap> tmpdir := DirectoryTemporary();; +gap> SetInfoLevel( InfoGAPDoc, 0 ); +gap> AutoDocWorksheet( "tst/plaintextmode.tst", rec( dir := tmpdir ) ); +gap> chap1 := Filename(tmpdir, "_Chapter_Test.xml");; +gap> IsReadableFile(chap1); +true +gap> ReadAll(InputTextFile(chap1)); +"\n\n\n\nTest\ +\n\nThis is dummy text\n S5 := SymmetricGroup(5);\nSym\ +( [ 1 .. 5 ] )\ngap> Size(S5);\n120\n\n# This next command is present to preve\ +nt Test() from\n# being misled by the remaining AutoDoc markup.\ngap> STOP_TES\ +T( \"dummy.tst\", 10000 );\n]]>\n\n\nAnd we wrap up with some dummy \ +text\nBut this should produce more text.\n\n\n" +gap> STOP_TEST( "plaintextmode.tst", 10000 ); +#! @AutoDocPlainText +@Title Plain Text Mode Test +@Date 2018/08/17 +@Chapter Test +This is dummy text +@BeginExampleSession +gap> S5 := SymmetricGroup(5); +Sym( [ 1 .. 5 ] ) +gap> Size(S5); +120 + +# This next command is present to prevent Test() from +# being misled by the remaining AutoDoc markup. +gap> STOP_TEST( "dummy.tst", 10000 ); +@EndExampleSession +And we wrap up with some dummy text +@EndAutoDocPlainText +This line in the file should be completely ignored. +#! But this should produce more text. diff --git a/tst/testall.g b/tst/testall.g new file mode 100644 index 00000000..382c48a4 --- /dev/null +++ b/tst/testall.g @@ -0,0 +1,18 @@ +############################################################################# +## +## AutoDoc package +## +## Copyright 2018 +## Contributed by Glen Whitney, studioinfinity.org +## +## Licensed under the GPL 2 or later. +## +############################################################################# + +LoadPackage( "AutoDoc" ); + +TestDirectory( DirectoriesPackageLibrary( "AutoDoc", "tst" ), + rec( exitGAP := true ) + ); + +FORCE_QUIT_GAP(1); # should only be reached in case of error diff --git a/tst/worksheet.tst b/tst/worksheet.tst new file mode 100644 index 00000000..47e9839f --- /dev/null +++ b/tst/worksheet.tst @@ -0,0 +1,85 @@ +############################################################################# +## +## AutoDoc package +## +## Test the behavior of AutoDocWorksheet +## +## Copyright 2018 +## Contributed by Glen Whitney, studioinfinity.org +## +## Licensed under the GPL 2 or later. +## +############################################################################# + +gap> START_TEST( "AutoDoc package: worksheet.tst" ); +gap> tmpdir := DirectoryTemporary();; +gap> SetInfoLevel( InfoGAPDoc, 0 ); +gap> AutoDocWorksheet( "tst/worksheet.tst", rec( dir := tmpdir ) ); +gap> chap1 := Filename( Directory(tmpdir), "_Chapter_Test.xml" );; +gap> IsReadableFile(chap1); +true +gap> ReadAll(InputTextFile(chap1)); +"\n\n\n\nTest\ +\n\nThis is dummy text\n S5 := SymmetricGroup(5);\nSym\ +( [ 1 .. 5 ] )\ngap> Size(S5);\n120\n]]>\n\n\nAnd we wrap up with so\ +me dummy text\n
\nSome categories\n\nIntro text\n\n \n true or false\ +\n\n \n

\n \n\n\n\n\n \n t\ +rue or false\n\n \n

\n \n\n\n\nAnd now we can test a variety of features of AutoDoc\ +\nwhich are not tested by processing the main manual.\n\ +\n \n \nThis ca\ +tegory is implemented via a DeclareSynonym.\nYet it will show up properly\n \n\n\n\nTo see how this works, examine the following \ +code\n

\n\nWe can also specify the \ +type of methods\n\n \n \nThis is a special metho\ +d for handling tough cases.\n \n\n\n\nThe coverage \ +of this test file could be extended further\n
\n\n\n\n\n" +gap> STOP_TEST( "worksheet.tst", 10000 ); +#! @Title Worksheet Test +#! @Date 2018/08/20 +#! @Chapter Test +#! This is dummy text +#! @BeginExampleSession +#! gap> S5 := SymmetricGroup(5); +#! Sym( [ 1 .. 5 ] ) +#! gap> Size(S5); +#! 120 +#! @EndExampleSession +#! And we wrap up with some dummy text +#! @Section Some categories +#! Intro text +DeclareCategory("MyThings", IsObject); +DeclareCategoryCollections("MyThings"); +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. +#! And now we can test a variety of features of AutoDoc +#! which are not tested by processing the main manual. +#! @Description This category is implemented via a DeclareSynonym. +#! Yet it will show up properly +#! @ItemType Filt +#! @Arguments obj +DeclareSynonym( "IsMyIntersectionObj", IsMyFirstObj and IsMySecondObj ); +#! To see how this works, examine the following code +#! @HereCode +a := MyFirstObj( gens ); +if IsMySecondObj( a ) then + b := IsMyIntersectionObj( a ); +fi; +### b will only ever be set to true, if it is set at all. +#! @EndCode +#! We can also specify the type of methods +#! @Description This is a special method for handling tough cases. +#! @ItemType Meth +InstallOtherMethod( GeneralOp, "for the tough cases", + IsIdenticalObj, + [IsAToughie, IsEvenWorse], + function (t, w) return DoStuff(t, w); +end ); +#! The coverage of this test file could be extended further