Skip to content

Commit cbc40d9

Browse files
author
Glen Whitney
committed
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.
1 parent 300385e commit cbc40d9

2 files changed

Lines changed: 80 additions & 31 deletions

File tree

‎gap/Parser.gi‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,15 @@ InstallGlobalFunction( AutoDoc_Type_Of_Item,
4747
function( current_item, type, default_chapter_data )
4848
local item_rec, entries, has_filters, ret_val;
4949
item_rec := current_item;
50-
if PositionSublist( type, "DeclareCategory" ) <> fail then
50+
if PositionSublist( type, "DeclareCategoryCollections") <> fail then
51+
entries := [ "Filt", "categories" ];
52+
ret_val := "<C>true</C> or <C>false</C>";
53+
has_filters := "No";
54+
if not IsBound( item_rec!.arguments ) then
55+
item_rec!.arguments := "obj";
56+
fi;
57+
item_rec!.coll_suffix := true;
58+
elif PositionSublist( type, "DeclareCategory" ) <> fail then
5159
entries := [ "Filt", "categories" ];
5260
ret_val := "<C>true</C> or <C>false</C>";
5361
has_filters := 1;
@@ -205,7 +213,7 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
205213
return false;
206214
fi;
207215
current_line := current_line{ [ position_parentesis + 1 .. Length( current_line ) ] };
208-
## Not the funny part begins:
216+
## Now the funny part begins:
209217
## try fetching the name:
210218
## Assuming the name is in the same line as its
211219
while PositionSublist( current_line, "," ) = fail and PositionSublist( current_line, ");" ) = fail do
@@ -214,6 +222,19 @@ InstallGlobalFunction( AutoDoc_Parser_ReadFiles,
214222
current_line := StripBeginEnd( current_line, " " );
215223
current_item!.name := current_line{ [ 1 .. Minimum( [ PositionSublist( current_line, "," ), PositionSublist( current_line, ");" ) ] ) - 1 ] };
216224
current_item!.name := StripBeginEnd( ReplacedString( current_item!.name, "\"", "" ), " " );
225+
if IsBound(current_item!.coll_suffix) then
226+
if EndsWith(current_item!.name, "Collection") then
227+
current_item!.name :=
228+
current_item!.name{[1..Length(current_item!.name)-6]};
229+
fi;
230+
if EndsWith(current_item!.name, "Coll") then
231+
current_item!.coll_suffix := "Coll";
232+
else
233+
current_item!.coll_suffix := "Collection";
234+
fi;
235+
current_item!.name := Concatenation(current_item!.name,
236+
current_item!.coll_suffix);
237+
fi;
217238
current_line := current_line{ [ Minimum( [ PositionSublist( current_line, "," ), PositionSublist( current_line, ");" ) ] ) + 1 .. Length( current_line ) ] };
218239
filter_string := "for ";
219240
## FIXME: The next two if's can be merged at some point

‎tst/worksheet.tst‎

Lines changed: 57 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -22,35 +22,55 @@ gap> ReadAll(InputTextFile(chap1));
2222
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\n<!DOCTYPE html PUBLIC \"-//W3C/\
2323
/DTD XHTML 1.0 Strict//EN\"\n \"http://www.w3.org/TR/xhtml1/DTD/xhtml1\
2424
-strict.dtd\">\n\n<html xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"en\"\
25-
>\n<head>\n<title>GAP (Plain_Text_Mode_Test) - Chapter 1: Test</title>\n<meta \
26-
http-equiv=\"content-type\" content=\"text/html; charset=UTF-8\" />\n<meta nam\
27-
e=\"generator\" content=\"GAPDoc2HTML\" />\n<link rel=\"stylesheet\" type=\"te\
28-
xt/css\" href=\"manual.css\" />\n<script src=\"manual.js\" type=\"text/javascr\
29-
ipt\"></script>\n<script type=\"text/javascript\">overwriteStyle();</script>\n\
30-
</head>\n<body class=\"chap1\" onload=\"jscontent()\">\n\n\n<div class=\"chli\
31-
nktop\"><span class=\"chlink1\">Goto Chapter: </span><a href=\"chap0.html\">To\
32-
p</a> <a href=\"chap1.html\">1</a> </div>\n\n<div class=\"chlinkprevnexttop\
33-
\">&nbsp;<a href=\"chap0.html\">[Top of Book]</a>&nbsp; <a href=\"chap0.html#\
34-
contents\">[Contents]</a>&nbsp; &nbsp;<a href=\"chap0.html\">[Previous Chapte\
35-
r]</a>&nbsp; </div>\n\n<p id=\"mathjaxlink\" class=\"pcenter\"><a href=\"chap\
36-
1_mj.html\">[MathJax on]</a></p>\n<p><a id=\"X87712F9D8732193C\" name=\"X87712\
37-
F9D8732193C\"></a></p>\n<div class=\"ChapSects\"><a href=\"chap1.html#X87712F9\
38-
D8732193C\">1 <span class=\"Heading\">Test</span></a>\n</div>\n\n<h3>1 <span c\
39-
lass=\"Heading\">Test</span></h3>\n\n<p>This is dummy text</p>\n\n\n<div class\
40-
=\"example\"><pre>\n<span class=\"GAPprompt\">gap&gt;</span> <span class=\"GAP\
41-
input\">S5 := SymmetricGroup(5);</span>\nSym( [ 1 .. 5 ] )\n<span class=\"GAPp\
42-
rompt\">gap&gt;</span> <span class=\"GAPinput\">Size(S5);</span>\n120\n</pre><\
43-
/div>\n\n<p>And we wrap up with some dummy text</p>\n\n\n<div class=\"chlinkpr\
44-
evnextbot\">&nbsp;<a href=\"chap0.html\">[Top of Book]</a>&nbsp; <a href=\"ch\
45-
ap0.html#contents\">[Contents]</a>&nbsp; &nbsp;<a href=\"chap0.html\">[Previo\
46-
us Chapter]</a>&nbsp; </div>\n\n\n<div class=\"chlinkbot\"><span class=\"chli\
47-
nk1\">Goto Chapter: </span><a href=\"chap0.html\">Top</a> <a href=\"chap1.htm\
48-
l\">1</a> </div>\n\n<hr />\n<p class=\"foot\">generated by <a href=\"http://w\
49-
ww.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc\">GAPDoc2HTML</a></p>\n</body>\n<\
50-
/html>\n"
51-
gap> STOP_TEST( "plaintextmode.tst", 10000 );
52-
#! @Title Plain Text Mode Test
53-
#! @Date 2018/08/17
25+
>\n<head>\n<title>GAP (Worksheet_Test) - Chapter 1: Test</title>\n<meta http-e\
26+
quiv=\"content-type\" content=\"text/html; charset=UTF-8\" />\n<meta name=\"ge\
27+
nerator\" content=\"GAPDoc2HTML\" />\n<link rel=\"stylesheet\" type=\"text/css\
28+
\" href=\"manual.css\" />\n<script src=\"manual.js\" type=\"text/javascript\">\
29+
</script>\n<script type=\"text/javascript\">overwriteStyle();</script>\n</head\
30+
>\n<body class=\"chap1\" onload=\"jscontent()\">\n\n\n<div class=\"chlinktop\
31+
\"><span class=\"chlink1\">Goto Chapter: </span><a href=\"chap0.html\">Top</a>\
32+
<a href=\"chap1.html\">1</a> </div>\n\n<div class=\"chlinkprevnexttop\">&nb\
33+
sp;<a href=\"chap0.html\">[Top of Book]</a>&nbsp; <a href=\"chap0.html#conten\
34+
ts\">[Contents]</a>&nbsp; &nbsp;<a href=\"chap0.html\">[Previous Chapter]</a>\
35+
&nbsp; </div>\n\n<p id=\"mathjaxlink\" class=\"pcenter\"><a href=\"chap1_mj.h\
36+
tml\">[MathJax on]</a></p>\n<p><a id=\"X87712F9D8732193C\" name=\"X87712F9D873\
37+
2193C\"></a></p>\n<div class=\"ChapSects\"><a href=\"chap1.html#X87712F9D87321\
38+
93C\">1 <span class=\"Heading\">Test</span></a>\n<div class=\"ContSect\"><span\
39+
class=\"tocline\"><span class=\"nocss\">&nbsp;</span><a href=\"chap1.html#X85\
40+
A5CE927A4B0C7E\">1.1 <span class=\"Heading\">Some categories</span></a>\n</spa\
41+
n>\n<div class=\"ContSSBlock\">\n<span class=\"ContSS\"><br /><span class=\"no\
42+
css\">&nbsp;&nbsp;</span><a href=\"chap1.html#X7BEDB3017D85F39C\">1.1-1 MyThin\
43+
gs</a></span>\n<span class=\"ContSS\"><br /><span class=\"nocss\">&nbsp;&nbsp;\
44+
</span><a href=\"chap1.html#X79F067727A23E8F8\">1.1-2 MyThingsCollection</a></\
45+
span>\n</div></div>\n</div>\n\n<h3>1 <span class=\"Heading\">Test</span></h3>\
46+
\n\n<p>This is dummy text</p>\n\n\n<div class=\"example\"><pre>\n<span class=\
47+
\"GAPprompt\">gap&gt;</span> <span class=\"GAPinput\">S5 := SymmetricGroup(5);\
48+
</span>\nSym( [ 1 .. 5 ] )\n<span class=\"GAPprompt\">gap&gt;</span> <span cla\
49+
ss=\"GAPinput\">Size(S5);</span>\n120\n</pre></div>\n\n<p>And we wrap up with \
50+
some dummy text</p>\n\n<p><a id=\"X85A5CE927A4B0C7E\" name=\"X85A5CE927A4B0C7E\
51+
\"></a></p>\n\n<h4>1.1 <span class=\"Heading\">Some categories</span></h4>\n\n\
52+
<p>Intro text</p>\n\n<p><a id=\"X7BEDB3017D85F39C\" name=\"X7BEDB3017D85F39C\"\
53+
></a></p>\n\n<h5>1.1-1 MyThings</h5>\n\n<div class=\"func\"><table class=\"fun\
54+
c\" width=\"100%\"><tr><td class=\"tdleft\"><code class=\"func\">&#8227; MyThi\
55+
ngs</code>( <var class=\"Arg\">arg</var> )</td><td class=\"tdright\">(&nbsp;fi\
56+
lter&nbsp;)</td></tr></table></div>\n<p>Returns: <code class=\"code\">true</co\
57+
de> or <code class=\"code\">false</code></p>\n\n<p><a id=\"X79F067727A23E8F8\"\
58+
name=\"X79F067727A23E8F8\"></a></p>\n\n<h5>1.1-2 MyThingsCollection</h5>\n\n<\
59+
div class=\"func\"><table class=\"func\" width=\"100%\"><tr><td class=\"tdleft\
60+
\"><code class=\"func\">&#8227; MyThingsCollection</code>( <var class=\"Arg\">\
61+
obj</var> )</td><td class=\"tdright\">(&nbsp;filter&nbsp;)</td></tr></table></\
62+
div>\n<p>Returns: <code class=\"code\">true</code> or <code class=\"code\">fal\
63+
se</code></p>\n\n<p>Let's wrap up with something, though.</p>\n\n\n<div class=\
64+
\"chlinkprevnextbot\">&nbsp;<a href=\"chap0.html\">[Top of Book]</a>&nbsp; <a\
65+
href=\"chap0.html#contents\">[Contents]</a>&nbsp; &nbsp;<a href=\"chap0.html\
66+
\">[Previous Chapter]</a>&nbsp; </div>\n\n\n<div class=\"chlinkbot\"><span cl\
67+
ass=\"chlink1\">Goto Chapter: </span><a href=\"chap0.html\">Top</a> <a href=\
68+
\"chap1.html\">1</a> </div>\n\n<hr />\n<p class=\"foot\">generated by <a href\
69+
=\"http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc\">GAPDoc2HTML</a></p>\
70+
\n</body>\n</html>\n"
71+
gap> STOP_TEST( "worksheet.tst", 10000 );
72+
#! @Title Worksheet Test
73+
#! @Date 2018/08/20
5474
#! @Chapter Test
5575
#! This is dummy text
5676
#! @BeginExampleSession
@@ -60,3 +80,11 @@ gap> STOP_TEST( "plaintextmode.tst", 10000 );
6080
#! 120
6181
#! @EndExampleSession
6282
#! And we wrap up with some dummy text
83+
#! @Section Some categories
84+
#! Intro text
85+
DeclareCategory("MyThings", IsObject);
86+
DeclareCategoryCollections("MyThings");
87+
Now here is some text with a bunch of &!$%*!/ weird things in it. But that
88+
should be OK, nothing should end up in a weird place.
89+
#! Let's wrap up with something, though.
90+

0 commit comments

Comments
 (0)