From 300385e97986c6be4c2c98bc641d26c777b6a4e7 Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Mon, 20 Aug 2018 03:24:01 -0700 Subject: [PATCH 1/4] Handle absolute directories for doc_dir in AutoDoc() Allow AutoDoc() to succeed with a dir entry in the options record which consists of an IsDirectory() object with an absolute path. There are two steps to this change: First, some effort must be made to correctly compute doc_dir_rel under such a circumstance. This commit uses the approach that if the pkgdir is a prefix of the doc_dir, then doc_dir_rel is the remainder of the doc_dir when the pkgdir is eliminated. If doc_dir is absolute and pkgdir is not a prefix thereof, then there is no sensible value for doc_dir_rel. Therefore, the second step of this change must be to handle downstream the case that doc_dir_rel is not set. This commit attempts to do so by presuming in such a case that there is no way to convert the gapdoc.files to paths relative to the doc_dir, and instead converts them to absolute paths. It may be the case that this strategy produces non-portable documentation files, but at least MakeGAPDocDoc succeeds, and it seems to be the only alternative in such case. Finally, in my previous experience contributing to GAP there was a strong preference that all changes include tests for the new behavior. As there was no test harness for AutoDoc, this commit also adds a boilerplate tst/testall.g and a single new test, tst/worksheet.tst, which invokes AutoDoc with an absolutely specified doc_dir. --- gap/Magic.gi | 41 +++++++++++++++++++++++-------- tst/testall.g | 18 ++++++++++++++ tst/worksheet.tst | 62 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 111 insertions(+), 10 deletions(-) create mode 100644 tst/testall.g create mode 100644 tst/worksheet.tst diff --git a/gap/Magic.gi b/gap/Magic.gi index b3d54eaf..d02e7f48 100644 --- a/gap/Magic.gi +++ b/gap/Magic.gi @@ -104,6 +104,7 @@ function( arg ) local pkgname, pkginfo, pkgdir, opt, scaffold, gapdoc, maketest, autodoc, doc_dir, doc_dir_rel, tmp, key, val, file, + pkgdirstr, docdirstr, title_page, tree, is_worksheet, position_document_class, gapdoc_latex_option_record, makeDocFun, args; @@ -205,7 +206,16 @@ function( arg ) doc_dir := Directory(doc_dir); else - # TODO: doc_dir_rel = ... ? + # In this case, if doc_dir happens to lie below pkgdir, we want the + # doc_dir_rel to be the difference; if not we avoid binding doc_dir_rel + # and leave MakeGAPDocDoc to muddle through with absolute paths. + pkgdirstr := Filename(pkgdir, ""); + docdirstr := Filename(doc_dir, ""); + if Length(pkgdirstr) <= Length(docdirstr) and + docdirstr{[1..Length(pkgdirstr)]} = pkgdirstr then + doc_dir_rel := + Directory(docdirstr{[(Length(pkgdirstr)+1)..Length(docdirstr)]}); + fi; fi; # Ensure the output directory exists, create it if necessary @@ -215,7 +225,7 @@ function( arg ) # This helps diagnose problems where multiple instances of a package # are visible to GAP and the wrong one is used for generating the # documentation. - Print( "Generating documentation in ", doc_dir, "\n" ); + Info(InfoGAPDoc, 1, "Generating documentation in ", doc_dir, "\n" ); # # Extract scaffolding settings, which can be controlled via @@ -351,14 +361,25 @@ function( arg ) # will not work if there are any non-normalized paths in the list). gapdoc.files := Set( gapdoc.files ); - # Convert the file paths in gapdoc.files, which are relative to - # the package directory, to paths which are relative to the doc directory. - # For this, we assume that doc_dir_rel is normalized (e.g. - # it does not contains '//') and relative. - # FIXME: this is an ugly hack, can't we do something better? - tmp := Number( Filename( doc_dir_rel, "" ), x -> x = '/' ); - tmp := Concatenation( ListWithIdenticalEntries(tmp, "../") ); - gapdoc.files := List( gapdoc.files, f -> Concatenation( tmp, f ) ); + # If possible, convert the file paths in gapdoc.files, which are + # relative to the package directory, to paths which are relative to + # the doc directory. + + if IsBound( doc_dir_rel) then + # For this, we assume that doc_dir_rel is normalized (e.g. + # it does not contains '//') and relative. + # FIXME: this is an ugly hack, can't we do something better? + tmp := Number( Filename( doc_dir_rel, "" ), x -> x = '/' ); + tmp := Concatenation( ListWithIdenticalEntries(tmp, "../") ); + gapdoc.files := List( gapdoc.files, f -> Concatenation( tmp, f ) ); + else + # Here presumably the doc_dir was given by an absolute path that + # does not lie below the package dir. In that case, we can't make + # the gapdoc.files relative to the doc dir, but rather we have no + # choice but to make them absolute, which MakeGAPDocDoc can handle, + # even if perhaps less gracefully/portably. + gapdoc.files := List( gapdoc.files, f -> Filename( pkgdir, f ) ); + fi; fi; 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..d70841ad --- /dev/null +++ b/tst/worksheet.tst @@ -0,0 +1,62 @@ +############################################################################# +## +## 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), "chap1.html" );; +gap> IsReadableFile(chap1); +true +gap> ReadAll(InputTextFile(chap1)); +"\n\n\n\n\n\nGAP (Plain_Text_Mode_Test) - Chapter 1: Test\n\n\n\n\n\n\ +\n\n\n\n
Goto Chapter: To\ +p 1
\n\n
 [Top of Book]  [Contents]   [Previous Chapte\ +r] 
\n\n

[MathJax on]

\n

\n
1 Test\n
\n\n

1 Test

\n\n

This is dummy text

\n\n\n
\ngap> S5 := SymmetricGroup(5);\nSym( [ 1 .. 5 ] )\ngap> Size(S5);\n120\n
<\ +/div>\n\n

And we wrap up with some dummy text

\n\n\n
 [Top of Book]  [Contents]   [Previo\ +us Chapter] 
\n\n\n
Goto Chapter: Top 1
\n\n
\n

generated by GAPDoc2HTML

\n\n<\ +/html>\n" +gap> STOP_TEST( "plaintextmode.tst", 10000 ); +#! @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 +#! @EndExampleSession +#! And we wrap up with some dummy text From 473acb7a9b8c902f139caa03a09cd43f01959f60 Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Mon, 20 Aug 2018 09:28:06 -0700 Subject: [PATCH 2/4] Make @BeginExampleSession/@EndExampleSession respect plain_text_mode In order to uniformize the handling of `#!` prefixes in AutoDoc files, gap/Parser.gi is changed to pass lines between @BeginExampleSession and @EndExampleSession through unchanged when plain_text_mode is true. Note this commit also supplies a test file tst/plaintextmode.tst; that file will not have any effect unless/until a test harness such as the one supplied with pull request #166 is put in place. But it does at least serve as a self-documenting illustration of the intended behavior post this change, and should otherwise be innocuous. --- gap/Parser.gi | 26 +++++++++------ tst/plaintextmode.tst | 73 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 10 deletions(-) create mode 100644 tst/plaintextmode.tst diff --git a/gap/Parser.gi b/gap/Parser.gi index 5ea1fc50..fbb524db 100644 --- a/gap/Parser.gi +++ b/gap/Parser.gi @@ -420,8 +420,8 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, od; return example_node; end; - read_session_example := function( is_tested_example ) - local temp_string_list, temp_curr_line, temp_pos_comment, is_following_line, item_temp, example_node; + read_session_example := function( is_tested_example, pt_mode ) + local temp_string_list, temp_curr_line, temp_pos_comment, is_following_line, item_temp, example_node, incorporate_this_line; example_node := DocumentationExample( tree ); if is_tested_example = false then example_node!.is_tested_example := false; @@ -438,13 +438,19 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, or PositionSublist( temp_curr_line, "@EndLogSession" ) <> fail then break; fi; - #! @DONT_SCAN_NEXT_LINE - temp_pos_comment := PositionSublist( temp_curr_line, "#!" ); - if temp_pos_comment <> fail then - temp_curr_line := temp_curr_line{[ temp_pos_comment + 2 .. Length( temp_curr_line ) ]}; - if Length( temp_curr_line ) >= 1 and temp_curr_line[ 1 ] = ' ' then - Remove( temp_curr_line, 1 ); + incorporate_this_line := pt_mode; + if not pt_mode then + #! @DONT_SCAN_NEXT_LINE + temp_pos_comment := PositionSublist( temp_curr_line, "#!" ); + if temp_pos_comment <> fail then + incorporate_this_line := true; + temp_curr_line := temp_curr_line{[ temp_pos_comment + 2 .. Length( temp_curr_line ) ]}; + if Length( temp_curr_line ) >= 1 and temp_curr_line[ 1 ] = ' ' then + Remove( temp_curr_line, 1 ); + fi; fi; + fi; + if incorporate_this_line then Add( temp_string_list, temp_curr_line ); fi; od; @@ -699,13 +705,13 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, end, @ExampleSession := function() local example_node; - example_node := read_session_example( true ); + example_node := read_session_example( true, plain_text_mode ); Add( current_item, example_node ); end, @BeginExampleSession := ~.@ExampleSession, @LogSession := function() local example_node; - example_node := read_session_example( false ); + example_node := read_session_example( false, plain_text_mode ); Add( current_item, example_node ); end, @BeginLogSession := ~.@LogSession diff --git a/tst/plaintextmode.tst b/tst/plaintextmode.tst new file mode 100644 index 00000000..6363e0aa --- /dev/null +++ b/tst/plaintextmode.tst @@ -0,0 +1,73 @@ +############################################################################# +## +## 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, "chap1.html");; +gap> IsReadableFile(chap1); +true +gap> ReadAll(InputTextFile(chap1)); +"\n\n\n\n\n\nGAP (Plain_Text_Mode_Test) - Chapter 1: Test\n\n\n\n\n\n\ +\n\n\n\n
Goto Chapter: To\ +p 1
\n\n
 [Top of Book]  [Contents]   [Previous Chapte\ +r] 
\n\n

[MathJax on]

\n

\n
1 Test\n
\n\n

1 Test

\n\n

This is dummy text

\n\n\n
\ngap> S5 := SymmetricGroup(5);\nSym( [ 1 .. 5 ] )\ngap> Size(S5);\n120\n\n# Thi\
+s next command is present to prevent Test() from\n# being misled by the remain\
+ing AutoDoc markup.\ngap> STOP_TEST( \"dummy.tst\", 10000 );\n
\n\n

And we \ +wrap up with some dummy text But this should produce more text.

\n\n\n
 [Top of Book]&nbs\ +p; [Contents]   [Previous Chapter] 
\n\n\n
Goto Chapter: Top 1
\n\n
\n

generated by GAPDoc2HTML\ +

\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. From cbc40d92a85f10ccd571a901129db60e4163a3b2 Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Wed, 22 Aug 2018 19:55:10 -0700 Subject: [PATCH 3/4] Handle documentation of DeclareCategoryCollection declarations. Note that AutoDoc here duplicates logic in gap/lib/coll.gd to determine the actual name of the symbol being defined by the call (since that symbol is computed on the fly by the declaration and does not appear verbatim anywhere in the call). This is unfortunate, but I could not see any way to call the relevant code in the standard library, as the name computation of the collections category is not split out into a separately executable function. Also, modify the worksheet.tst to include an example of DeclareCategoryCollection to make sure the new capacity is tested. --- gap/Parser.gi | 25 ++++++++++++-- tst/worksheet.tst | 86 +++++++++++++++++++++++++++++++---------------- 2 files changed, 80 insertions(+), 31 deletions(-) diff --git a/gap/Parser.gi b/gap/Parser.gi index 5ea1fc50..d734bf03 100644 --- a/gap/Parser.gi +++ b/gap/Parser.gi @@ -47,7 +47,15 @@ InstallGlobalFunction( AutoDoc_Type_Of_Item, function( current_item, type, default_chapter_data ) local item_rec, entries, has_filters, ret_val; item_rec := current_item; - if PositionSublist( type, "DeclareCategory" ) <> fail then + if PositionSublist( type, "DeclareCategoryCollections") <> fail then + entries := [ "Filt", "categories" ]; + ret_val := "true or false"; + has_filters := "No"; + if not IsBound( item_rec!.arguments ) then + item_rec!.arguments := "obj"; + fi; + item_rec!.coll_suffix := true; + elif PositionSublist( type, "DeclareCategory" ) <> fail then entries := [ "Filt", "categories" ]; ret_val := "true or false"; has_filters := 1; @@ -205,7 +213,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, return false; fi; current_line := current_line{ [ position_parentesis + 1 .. Length( current_line ) ] }; - ## Not the funny part begins: + ## Now the funny part begins: ## try fetching the name: ## Assuming the name is in the same line as its while PositionSublist( current_line, "," ) = fail and PositionSublist( current_line, ");" ) = fail do @@ -214,6 +222,19 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles, current_line := StripBeginEnd( current_line, " " ); current_item!.name := current_line{ [ 1 .. Minimum( [ PositionSublist( current_line, "," ), PositionSublist( current_line, ");" ) ] ) - 1 ] }; current_item!.name := StripBeginEnd( ReplacedString( current_item!.name, "\"", "" ), " " ); + if IsBound(current_item!.coll_suffix) then + if EndsWith(current_item!.name, "Collection") then + current_item!.name := + current_item!.name{[1..Length(current_item!.name)-6]}; + fi; + if EndsWith(current_item!.name, "Coll") then + current_item!.coll_suffix := "Coll"; + else + current_item!.coll_suffix := "Collection"; + fi; + current_item!.name := Concatenation(current_item!.name, + current_item!.coll_suffix); + fi; current_line := current_line{ [ Minimum( [ PositionSublist( current_line, "," ), PositionSublist( current_line, ");" ) ] ) + 1 .. Length( current_line ) ] }; filter_string := "for "; ## FIXME: The next two if's can be merged at some point diff --git a/tst/worksheet.tst b/tst/worksheet.tst index d70841ad..1139ae81 100644 --- a/tst/worksheet.tst +++ b/tst/worksheet.tst @@ -22,35 +22,55 @@ gap> ReadAll(InputTextFile(chap1)); "\n\n\n\n\n\nGAP (Plain_Text_Mode_Test) - Chapter 1: Test\n\n\n\n\n\n\ -\n\n\n\n
Goto Chapter: To\ -p 1
\n\n
 [Top of Book]  [Contents]   [Previous Chapte\ -r] 
\n\n

[MathJax on]

\n

\n
1 Test\n
\n\n

1 Test

\n\n

This is dummy text

\n\n\n
\ngap> S5 := SymmetricGroup(5);\nSym( [ 1 .. 5 ] )\ngap> Size(S5);\n120\n
<\ -/div>\n\n

And we wrap up with some dummy text

\n\n\n
 [Top of Book]  [Contents]   [Previo\ -us Chapter] 
\n\n\n
Goto Chapter: Top 1
\n\n
\n

generated by GAPDoc2HTML

\n\n<\ -/html>\n" -gap> STOP_TEST( "plaintextmode.tst", 10000 ); -#! @Title Plain Text Mode Test -#! @Date 2018/08/17 +>\n\nGAP (Worksheet_Test) - Chapter 1: Test\n\n\n\n\n\n\n\n\n\n
Goto Chapter: Top\ + 1
\n\n
&nb\ +sp;[Top of Book]  [Contents]   [Previous Chapter]\ + 
\n\n

[MathJax on]

\n

\n
1 Test\n
 1.1 Some categories\n\n
\n
  1.1-1 MyThin\ +gs\n
  \ +1.1-2 MyThingsCollection\n
\n
\n\n

1 Test

\ +\n\n

This is dummy text

\n\n\n
\ngap> S5 := SymmetricGroup(5);\
+\nSym( [ 1 .. 5 ] )\ngap> Size(S5);\n120\n
\n\n

And we wrap up with \ +some dummy text

\n\n

\n\n

1.1 Some categories

\n\n\ +

Intro text

\n\n

\n\n
1.1-1 MyThings
\n\n
‣ MyThi\ +ngs( arg )( fi\ +lter )
\n

Returns: true or false

\n\n

\n\n
1.1-2 MyThingsCollection
\n\n<\ +div class=\"func\">
‣ MyThingsCollection( \ +obj )( filter )
\n

Returns: true or fal\ +se

\n\n

Let's wrap up with something, though.

\n\n\n
 [Top of Book]  [Contents]   [Previous Chapter] 
\n\n\n
Goto Chapter: Top 1
\n\n
\n

generated by GAPDoc2HTML

\ +\n\n\n" +gap> STOP_TEST( "worksheet.tst", 10000 ); +#! @Title Worksheet Test +#! @Date 2018/08/20 #! @Chapter Test #! This is dummy text #! @BeginExampleSession @@ -60,3 +80,11 @@ gap> STOP_TEST( "plaintextmode.tst", 10000 ); #! 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. +#! Let's wrap up with something, though. + From fd09712a5f5764730e4292a06e4da5e96b709263 Mon Sep 17 00:00:00 2001 From: Glen Whitney Date: Tue, 28 Aug 2018 01:13:31 -0700 Subject: [PATCH 4/4] Recognize DeclareSynonym, with cascade of related changes This change began with recognizing DeclareSynonym and cascaded to involve a number of related changes. First, in order for DeclareSynonym to be useful, there must be some way to specify the manual item type for the identifier being declared. Hence this change also implements a @ItemType command to allow that. (Adding @ItemType also achieves the main recommendaton in issue #74.) In documenting these two changes, it seemed best to have their documentation in gap/Parser.gi next to their implementation, on the general principle that documentation should be as close to the relevant code as possible. Further, in an effort at dogfooding, it seemed best for that documentation to be in AutoDoc format. This turned into a change in which doc/Comments.xml became doc/Comments.autodoc and became much smaller, as most of the documentation moved to gap/Parser.gi and gap/Markdown.gi. Being able to use Autodoc to document most of Autodoc then entailed a few other changes. First, Markdown-like syntax with backticks for code expressions that would suppress the AutoDoc behavior of the quoted items was essential. Second, it was useful to add an @Index command for generating the index entries. And third, reassembling Chapter 2 of the manual from portions in several files necessitated allowing sections and subsections inside a chunk to move with that chunk, and be inserted into the chapter or section at the point at which the chunk was inserted. (An implementation note on this last change. It was greatly facilitated by merging the current_item ambient variable with the context_stack. The current_item was in essence functioning as the top of the stack anyway. Having the top of the stack in one variable and the rest of the stack in another made some of the code a bit confusing. This change touched a large fraction of code in the Parser, but in the end improved the locality of reference in that code considerably, and I think made it clearer what is going on during parsing.) In the course of these changes, it was trivial to add the ability to have code blocks which add at the current location, with no @InsertCode necessary. So that change is included here as well. Finally, with so many changes, extensive testing was clearly critical. So this commit also beefs up the worksheet.tst, and adds a new test dogfood.tst which consists of generating the AutoDoc manual and verifying that it matches the expected contents of the manual. I do understand that this turned into more of a complex of changes than would ordinarily be packed into a single commit. But this portmanteau seemed a fairly natural stable point in which the motivating changes (DeclareSynonym/@ItemType) are made, documented, and tested in a cohesive way. I would be happy to do the work of separating this out into more than one successive change to AutoDoc if that would help advance these changes. Please just let me know what pieces you'd like it carved up into, and in what order. Thanks very much for your consideration. Resolves: #60, #74, #174, #175, #176, #177, #178. It also makes further progress on #48, in adding the backtick code quotes, and on the testing issues #57 and #152. It also touches on Issue #112, in that to use makedoc.g in testing, I needed to add a backdoor to prevent it from QUITting. Note also that the motivation in the original post for Issue #144 was the need to document DeclareSynonym. --- .gitignore | 2 +- doc/Comments.autodoc | 173 +++ doc/Comments.xml | 728 ------------ doc/Tutorials.xml | 4 +- gap/DocumentationTree.gd | 3 + gap/DocumentationTree.gi | 99 +- gap/Magic.gd | 11 + gap/Markdown.gi | 135 ++- gap/Parser.gd | 1 + gap/Parser.gi | 1249 ++++++++++++++++----- makedoc.g | 19 +- tst/_Chapter_AutoDoc.reference | 333 ++++++ tst/_Chapter_AutoDoc_worksheets.reference | 28 + tst/_Chapter_Comments.reference | 1125 +++++++++++++++++++ tst/dogfood.tst | 61 + tst/plaintextmode.tst | 41 +- tst/worksheet.tst | 99 +- 17 files changed, 2996 insertions(+), 1115 deletions(-) create mode 100644 doc/Comments.autodoc delete mode 100644 doc/Comments.xml create mode 100644 tst/_Chapter_AutoDoc.reference create mode 100644 tst/_Chapter_AutoDoc_worksheets.reference create mode 100644 tst/_Chapter_Comments.reference create mode 100644 tst/dogfood.tst 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 &GAP; 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 &GAP;. In the latter case, it checks whether +the given directory contains a PackageInfo.g file, and extracts +all needed metadata from that. This is for example useful if you have +multiple versions of the package around and want to make sure the +documentation of the correct version is built. +

+If this argument is omitted, &AutoDoc; uses the DirectoryCurrent(). + +optrec + +optrec can be a record with some additional options. +The following are currently supported: + +dir + +This should be a string containing a (relative) path or a +Directory() object specifying where the package documentation +(i.e. the &GAPDoc; XML files) are stored. +
+Default value: "doc/". + +scaffold + +This controls whether and how to generate scaffold XML files +for the package documentation. +

+The value should be either true, false or a +record. If it is a record or true (the latter is +equivalent to specifying an empty record), then this feature is +enabled. It is also enabled if opt.scaffold is missing but the +package's info record in PackageInfo.g has an AutoDoc entry. +In all other cases (in particular if opt.scaffold is +false), scaffolding is disabled. +

+If scaffolding is enabled, and PackageInfo.AutoDoc exists, then it is +assumed to be a record, and its contents are used as default values for +the scaffold settings. +

+

+If opt.scaffold is a record, it may contain the following entries. +

+ +includes + +A list of XML files to be included in the body of the main XML file. +If you specify this list and also are using &AutoDoc; to document +your operations with &AutoDoc; comments, +you can add _AutoDocMainFile.xml to this list +to control at which point the documentation produced by &AutoDoc; +is inserted. If you do not do this, it will be added after the last +of your own XML files. + +index + +By default, the scaffold creates an index. If you do not want an index, +set this to false. + +appendix + +This entry is similar to opt.scaffold.includes but is used +to specify files to include after the main body of the manual, +i.e. typically appendices. + +bib + +The name of a bibliography file, in BibTeX or XML format. +If this key is not set, but there is a file doc/PACKAGENAME.bib +then it is assumed that you want to use this as your bibliography. + +entities + +A record whose keys are taken as entity names, set to the corresponding +(string) values. For example, if you pass the record SomePackage, +

SomePackage", +RELEASEYEAR := "2015" )]]> +then the following entity definitions are added to the XML preamble: +SomePackage'> +]]> +This allows you to write &SomePackage; and &RELEASEYEAR; +in your documentation, which will be replaced by respective values specified +in the entities definition. + +TitlePage + +A record whose entries are used to embellish the generated title page +for the package manual with extra information, such as a copyright +statement or acknowledgments. To this end, the names of the record +components are used as XML element names, and the values of the +components are outputted as content of these XML elements. For +example, you could pass the following record to set a custom +acknowledgements text: + +For a list of valid entries in the title page, please refer to the +&GAPDoc; manual, specifically section . + +MainPage + +If scaffolding is enabled, by default a main XML file is generated (this +is the file which contains the XML doctype and more). If you do not +want this (e.g. because you have a handwritten main XML file), but +still want &AutoDoc; to generate a title page for you, you can set this +option to false + +document_class + +Sets the document class of the resulting PDF. The value can either be a string +which has to be the name of the new document class, a list containing this string, or +a list of two strings. Then the first one has to be the document class name, the second one +the option string ( contained in [ ] ) in LaTeX. + +latex_header_file + +Replaces the standard header from &GAPDoc; completely with the header in this LaTeX file. +Please be careful here, and look at GAPDoc's latexheader.tex file for an example. + +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 &GAP; 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 &GAP; 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 &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 / @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 index 6363e0aa..89087054 100644 --- a/tst/plaintextmode.tst +++ b/tst/plaintextmode.tst @@ -15,42 +15,17 @@ 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, "chap1.html");; +gap> chap1 := Filename(tmpdir, "_Chapter_Test.xml");; gap> IsReadableFile(chap1); true gap> ReadAll(InputTextFile(chap1)); -"\n\n\n\n\n\nGAP (Plain_Text_Mode_Test) - Chapter 1: Test\n\n\n\n\n\n\ -\n\n\n\n
Goto Chapter: To\ -p 1
\n\n
 [Top of Book]  [Contents]   [Previous Chapte\ -r] 
\n\n

[MathJax on]

\n

\n
1 Test\n
\n\n

1 Test

\n\n

This is dummy text

\n\n\n
\ngap> S5 := SymmetricGroup(5);\nSym( [ 1 .. 5 ] )\ngap> Size(S5);\n120\n\n# Thi\
-s next command is present to prevent Test() from\n# being misled by the remain\
-ing AutoDoc markup.\ngap> STOP_TEST( \"dummy.tst\", 10000 );\n
\n\n

And we \ -wrap up with some dummy text But this should produce more text.

\n\n\n\n\n\n
Goto Chapter: Top 1
\n\n
\n

generated by GAPDoc2HTML\ -

\n\n\n" +"\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 diff --git a/tst/worksheet.tst b/tst/worksheet.tst index 1139ae81..47e9839f 100644 --- a/tst/worksheet.tst +++ b/tst/worksheet.tst @@ -15,59 +15,32 @@ 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), "chap1.html" );; +gap> chap1 := Filename( Directory(tmpdir), "_Chapter_Test.xml" );; gap> IsReadableFile(chap1); true gap> ReadAll(InputTextFile(chap1)); -"\n\n\n\n\n\nGAP (Worksheet_Test) - Chapter 1: Test\n\n\n\n\n\n\n\n\n\n
Goto Chapter: Top\ - 1
\n\n
&nb\ -sp;[Top of Book]  [Contents]   [Previous Chapter]\ - 
\n\n

[MathJax on]

\n

\n
1 Test\n
 1.1 Some categories\n\n
\n
  1.1-1 MyThin\ -gs\n
  \ -1.1-2 MyThingsCollection\n
\n
\n\n

1 Test

\ -\n\n

This is dummy text

\n\n\n
\ngap> S5 := SymmetricGroup(5);\
-\nSym( [ 1 .. 5 ] )\ngap> Size(S5);\n120\n
\n\n

And we wrap up with \ -some dummy text

\n\n

\n\n

1.1 Some categories

\n\n\ -

Intro text

\n\n

\n\n
1.1-1 MyThings
\n\n
‣ MyThi\ -ngs( arg )( fi\ -lter )
\n

Returns: true or false

\n\n

\n\n
1.1-2 MyThingsCollection
\n\n<\ -div class=\"func\">
‣ MyThingsCollection( \ -obj )( filter )
\n

Returns: true or fal\ -se

\n\n

Let's wrap up with something, though.

\n\n\n
 [Top of Book]  [Contents]   [Previous Chapter] 
\n\n\n
Goto Chapter: Top 1
\n\n
\n

generated by GAPDoc2HTML

\ -\n\n\n" +"\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 @@ -86,5 +59,27 @@ 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. -#! Let's wrap up with something, though. - +#! 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