1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (AutoDoc) - Chapter 2: AutoDoc documentation comments</title>
<meta http-equiv="content-type" content="text/html; charset=UTF-8" />
<meta name="generator" content="GAPDoc2HTML" />
<link rel="stylesheet" type="text/css" href="manual.css" />
<script src="manual.js" type="text/javascript"></script>
<script type="text/javascript">overwriteStyle();</script>
</head>
<body class="chap2" onload="jscontent()">
<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<div class="chlinkprevnexttop"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap1.html">[Previous Chapter]</a> <a href="chap3.html">[Next Chapter]</a> </div>
<p id="mathjaxlink" class="pcenter"><a href="chap2_mj.html">[MathJax on]</a></p>
<p><a id="X87668C487B1A2094" name="X87668C487B1A2094"></a></p>
<div class="ChapSects"><a href="chap2.html#X87668C487B1A2094">2 <span class="Heading"><strong class="pkg">AutoDoc</strong> documentation comments</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap2.html#X871482CE838C68F6">2.1 <span class="Heading">Documenting declarations</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7F1D85188262A827">2.1-1 <span class="Heading"><code class="code">@Description <var class="Arg">descr</var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7DCAB2F87E8FAE90">2.1-2 <span class="Heading"><code class="code">@Returns <var class="Arg">ret_val</var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X81DAA454857F7971">2.1-3 <span class="Heading"><code class="code">@Arguments <var class="Arg">args</var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X8677FE8F80C00B14">2.1-4 <span class="Heading"><code class="code">@Group <var class="Arg">grpname</var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7B0E20A27D64DF6F">2.1-5 <span class="Heading"><code class="code">@Label <var class="Arg">label</var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X83B63B847B5199CF">2.1-6 AProperty</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X78A9022A7D5CB20E">2.1-7 AProperty</a></span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X78938EE37A532FFA">2.1-8 <span class="Heading"><code class="code">@ChapterInfo <var class="Arg">chapter</var>, <var class="Arg">section</var></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap2.html#X8152FEF9844B1ACD">2.2 <span class="Heading">Other documentation comments</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X823E613385D09F6F">2.2-1 <span class="Heading"><code class="code">@Chapter <var class="Arg">name</var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X78AA98BA7E0635D0">2.2-2 <span class="Heading"><code class="code">@Section <var class="Arg">name</var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7FD77434802A3580">2.2-3 <span class="Heading"><code class="code">@Subsection <var class="Arg">name</var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7D3060C17EDBCED1">2.2-4 <span class="Heading"><code class="code">@BeginGroup <var class="Arg">[grpname]</var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7C17EB007FD42C87">2.2-5 <span class="Heading"><code class="code">@EndGroup</code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X82FB96F37FAE8167">2.2-6 <span class="Heading">@GroupTitle <var class="Arg">title</var></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7BF81EAF80D1A4B5">2.2-7 <span class="Heading"><code class="code">@Level <var class="Arg">lvl</var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7C6723D57F424215">2.2-8 <span class="Heading"><code class="code">@ResetLevel</code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X83D6DA3B83D3436C">2.2-9 <span class="Heading"><code class="code">@BeginExample</code> and <code class="code">@EndExample</code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X861E2E778510CAF7">2.2-10 <span class="Heading"><code class="code">@BeginExampleSession</code> and <code class="code">@EndExampleSession</code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X81A2D44D834C0A17">2.2-11 <span class="Heading"><code class="code">@BeginLog</code> and <code class="code">@EndLog</code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7BADE876794FF309">2.2-12 <span class="Heading"><code class="code">@BeginLogSession</code> and <code class="code">@EndLogSession</code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X78DC644E8519280C">2.2-13 <span class="Heading"><code class="code">@DoNotReadRestOfFile</code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X83C01F9B7FA1C973">2.2-14 <span class="Heading"><code class="code">@BeginChunk <var class="Arg">name</var></code>, <code class="code">@EndChunk</code>, and <code class="code">@InsertChunk <var class="Arg">name</var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7D3671AF86B995B9">2.2-15 <span class="Heading"><code class="code">@BeginCode <var class="Arg">name</var></code>, @EndCode, and <code class="code">@InsertCode <var class="Arg">name</var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X8033B34F80A12A10">2.2-16 <span class="Heading"><code class="code">@LatexOnly <var class="Arg">text</var></code>, <code class="code">@BeginLatexOnly</code>, and <code class="code">@EndLatexOnly</code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7EF303147F1BCC22">2.2-17 <span class="Heading"><code class="code">@NotLatex <var class="Arg">text</var></code>, <code class="code">@BeginNotLatex</code>, and <code class="code">@EndNotLatex</code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap2.html#X841E3AD584F5385C">2.3 <span class="Heading">Title page commands</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap2.html#X828AE38F80CB02E7">2.4 <span class="Heading">Plain text files</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap2.html#X7D7A38F87BC40C48">2.5 <span class="Heading">Grouping</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X79BF060F8436C586">2.5-1 <span class="Heading">A family of operations</span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap2.html#X8209AFDE8209AFDE">2.6 <span class="Heading">Level</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap2.html#X79558A2F7FE187B4">2.7 <span class="Heading">Markdown-like formatting of text in <strong class="pkg">AutoDoc</strong></span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7B256AE5780F140A">2.7-1 <span class="Heading">Lists</span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X871412737A0E12E2">2.7-2 <span class="Heading">Math modes</span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X7ED0330479146EFC">2.7-3 <span class="Heading">Emphasize</span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap2.html#X838CCDEB7E0ECEE2">2.7-4 <span class="Heading">Inline code</span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap2.html#X78CA9E5C7F494C19">2.8 <span class="Heading">Deprecated commands</span></a>
</span>
</div>
</div>
<h3>2 <span class="Heading"><strong class="pkg">AutoDoc</strong> documentation comments</span></h3>
<p>You can document declarations of global functions and variables, operations, attributes etc. by inserting <em><strong class="pkg">AutoDoc</strong></em> comments into your sources before these declaration. An <strong class="pkg">AutoDoc</strong> comment always starts with <code class="code">#!</code>. This is also the smallest possible <strong class="pkg">AutoDoc</strong> command. If you want your declaration documented, just write <code class="code">#!</code> at the line before the documentation. For example:</p>
<div class="example"><pre>
#!
DeclareOperation( "AnOperation",
[ IsList ] );
</pre></div>
<p>This will produce a manual entry for the operation <code class="code">AnOperation</code>.</p>
<p>Inside of <strong class="pkg">AutoDoc</strong> comments, <em><strong class="pkg">AutoDoc</strong> commands</em> starting with <code class="code">@</code> can be used to control the output <strong class="pkg">AutoDoc</strong> produces.</p>
<p><a id="X871482CE838C68F6" name="X871482CE838C68F6"></a></p>
<h4>2.1 <span class="Heading">Documenting declarations</span></h4>
<p>In the bare form above, the manual entry for <code class="code">AnOperation</code> 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 <strong class="pkg">AutoDoc</strong> comment before the declaration. Currently, the following commands are provided:</p>
<p><a id="X7F1D85188262A827" name="X7F1D85188262A827"></a></p>
<h5>2.1-1 <span class="Heading"><code class="code">@Description <var class="Arg">descr</var></code></span></h5>
<p>Adds the text in the following lines of the <strong class="pkg">AutoDoc</strong> to the description of the declaration in the manual. Lines are until the next <strong class="pkg">AutoDoc</strong> command or until the declaration is reached.</p>
<p><a id="X7DCAB2F87E8FAE90" name="X7DCAB2F87E8FAE90"></a></p>
<h5>2.1-2 <span class="Heading"><code class="code">@Returns <var class="Arg">ret_val</var></code></span></h5>
<p>The string <var class="Arg">ret_val</var> is added to the documentation, with the text "Returns: " put in front of it. This should usually give a brief hint about the type or meaning of the value returned by the documented function.</p>
<p><a id="X81DAA454857F7971" name="X81DAA454857F7971"></a></p>
<h5>2.1-3 <span class="Heading"><code class="code">@Arguments <var class="Arg">args</var></code></span></h5>
<p>The string <var class="Arg">args</var> 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 <strong class="pkg">GAP</strong> options are used, this can be followed by a colon : and one or more assignments, like "n[, r]: tries := 100".</p>
<p><a id="X8677FE8F80C00B14" name="X8677FE8F80C00B14"></a></p>
<h5>2.1-4 <span class="Heading"><code class="code">@Group <var class="Arg">grpname</var></code></span></h5>
<p>Adds the following method to a group with the given name. See section <a href="chap2.html#X7D7A38F87BC40C48"><span class="RefLink">2.5</span></a> for more information about groups.</p>
<p><a id="X7B0E20A27D64DF6F" name="X7B0E20A27D64DF6F"></a></p>
<h5>2.1-5 <span class="Heading"><code class="code">@Label <var class="Arg">label</var></code></span></h5>
<p>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 <code class="code">DeclareOperation</code>, <code class="code">DeclareAttribute</code>, etc.), a default label is generated from this filter list.</p>
<div class="example"><pre>
#! @Label testlabel
DeclareProperty( "AProperty",
IsObject );
</pre></div>
<p>leads to this:</p>
<p><a id="X83B63B847B5199CF" name="X83B63B847B5199CF"></a></p>
<h5>2.1-6 AProperty</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ AProperty</code>( <var class="Arg">arg</var> )</td><td class="tdright">( property )</td></tr></table></div>
<p>Returns: <code class="keyw">true</code> or <code class="keyw">false</code></p>
<p>while</p>
<div class="example"><pre>
#!
DeclareProperty( "AProperty",
IsObject );
</pre></div>
<p>leads to this:</p>
<p><a id="X78A9022A7D5CB20E" name="X78A9022A7D5CB20E"></a></p>
<h5>2.1-7 AProperty</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ AProperty</code>( <var class="Arg">arg</var> )</td><td class="tdright">( property )</td></tr></table></div>
<p>Returns: <code class="keyw">true</code> or <code class="keyw">false</code></p>
<p><a id="X78938EE37A532FFA" name="X78938EE37A532FFA"></a></p>
<h5>2.1-8 <span class="Heading"><code class="code">@ChapterInfo <var class="Arg">chapter</var>, <var class="Arg">section</var></code></span></h5>
<p>Adds the entry to the given chapter and section. Here, <var class="Arg">chapter</var> and <var class="Arg">section</var> are the respective titles.</p>
<p>As an example, a full <strong class="pkg">AutoDoc</strong> comment with all options could look like this:</p>
<div class="example"><pre>
#! @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 <A>modtbl</A>
#! and underlying ordinary character table `ordtbl`.
#! @Returns a list
#! @Arguments modtbl
#! @Group CharacterDegreesOfBlocks
#! @Label chardegblocks
#! @ChapterInfo Blocks, Attributes
DeclareAttribute( "CharacterDegreesOfBlocks",
IsBrauerTable );
</pre></div>
<p><a id="X8152FEF9844B1ACD" name="X8152FEF9844B1ACD"></a></p>
<h4>2.2 <span class="Heading">Other documentation comments</span></h4>
<p>There are also some commands which can be used in <strong class="pkg">AutoDoc</strong> comments that are not associated to any declaration. This is useful for additional text in your documentation, examples, mathematical chapters, etc..</p>
<p><a id="X823E613385D09F6F" name="X823E613385D09F6F"></a></p>
<h5>2.2-1 <span class="Heading"><code class="code">@Chapter <var class="Arg">name</var></code></span></h5>
<p>Sets the active chapter, all subsequent functions which do not have an explicit chapter declared in their <strong class="pkg">AutoDoc</strong> comment via <code class="code">@ChapterInfo</code> 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 <code class="code">@Description</code>, will be added to the chapter as regular text. Additionally, the chapters label will be set to <code class="code">Chapter_</code><var class="Arg">name</var>. Example:</p>
<div class="example"><pre>
#! @Chapter My chapter
#! This is my chapter.
#! I document my stuff in it.
</pre></div>
<p>The <code class="code">@ChapterLabel</code> <var class="Arg">label</var> command can be used to set the label of the chapter to <code class="code">Chapter_</code><var class="Arg">label</var> instead of <code class="code">Chapter_</code><var class="Arg">name</var>. Additionally, the chapter will be stored as <code class="code">_Chapter_</code><var class="Arg">label</var><code class="code">.xml</code>. The <code class="code">@ChapterTitle</code> <var class="Arg">title</var> command can be used to set a heading for the chapter that is different from <var class="Arg">name</var>. Note that the title does not affect the label. If you use all three commands, i.e.,</p>
<div class="example"><pre>
#! @Chapter name
#! @ChapterLabel label
#! @ChapterTitle title
</pre></div>
<p><code class="code">title</code> is used for the headline, <code class="code">label</code> for cross-referencing, and <code class="code">name</code> for setting the same chapter as active chapter again.</p>
<p><a id="X78AA98BA7E0635D0" name="X78AA98BA7E0635D0"></a></p>
<h5>2.2-2 <span class="Heading"><code class="code">@Section <var class="Arg">name</var></code></span></h5>
<p>Sets an active section like <code class="code">@Chapter</code> sets an active chapter. The section automatically ends with the next <code class="code">@Section</code> or <code class="code">@Chapter</code> command.</p>
<div class="example"><pre>
#! @Section My first manual section
#! In this section I am going to document my first method.
</pre></div>
<p>The <code class="code">@SectionLabel</code> <var class="Arg">label</var> command can be used to set the label of the section to <code class="code">Section_</code><var class="Arg">label</var> instead of <code class="code">Chapter_chaptername_Section_</code><var class="Arg">name</var>. The <code class="code">@SectionTitle</code> <var class="Arg">title</var> command can be used to set a heading for the section that is different from <var class="Arg">name</var>.</p>
<p><a id="X7FD77434802A3580" name="X7FD77434802A3580"></a></p>
<h5>2.2-3 <span class="Heading"><code class="code">@Subsection <var class="Arg">name</var></code></span></h5>
<p>Sets an active subsection like <code class="code">@Section</code> sets an active section. The subsection automatically ends with the next <code class="code">@Subsection</code>, <code class="code">@Section</code> or <code class="code">@Chapter</code> command. It also ends with the next documented function. Indeed, internally each function "manpage" is treated like a subsection.</p>
<div class="example"><pre>
#! @Subsection My first manual subsection
#! In this subsection I am going to document my first example.
</pre></div>
<p>The <code class="code">@SubsectionLabel</code> <var class="Arg">label</var> command can be used to set the label of the subsection to <code class="code">Subsection_</code><var class="Arg">label</var> instead of <code class="code">Chapter_chaptername_Section_sectionname_Subsection_</code><var class="Arg">name</var>. The <code class="code">@SubsectionTitle</code> <var class="Arg">title</var> command can be used to set a heading for the subsection that is different from <var class="Arg">name</var>.</p>
<p><a id="X7D3060C17EDBCED1" name="X7D3060C17EDBCED1"></a></p>
<h5>2.2-4 <span class="Heading"><code class="code">@BeginGroup <var class="Arg">[grpname]</var></code></span></h5>
<p>Starts a group. All following documented declarations without an explicit <code class="code">@Group</code> 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 <code class="code">@EndGroup</code> command is reached.</p>
<p>See section <a href="chap2.html#X7D7A38F87BC40C48"><span class="RefLink">2.5</span></a> for more information about groups.</p>
<p><a id="X7C17EB007FD42C87" name="X7C17EB007FD42C87"></a></p>
<h5>2.2-5 <span class="Heading"><code class="code">@EndGroup</code></span></h5>
<p>Ends the current group.</p>
<div class="example"><pre>
#! @BeginGroup MyGroup
#!
DeclareAttribute( "GroupedAttribute",
IsList );
DeclareOperation( "NonGroupedOperation",
[ IsObject ] );
#!
DeclareOperation( "GroupedOperation",
[ IsList, IsRubbish ] );
#! @EndGroup
</pre></div>
<p><a id="X82FB96F37FAE8167" name="X82FB96F37FAE8167"></a></p>
<h5>2.2-6 <span class="Heading">@GroupTitle <var class="Arg">title</var></span></h5>
<p>Sets the subsection heading for the current group to <var class="Arg">title</var>. In the absence of any <code class="code">@GroupTitle</code> command, the heading will be the name of the first entry in the group. See <a href="chap2.html#X7D7A38F87BC40C48"><span class="RefLink">2.5</span></a> for more information.</p>
<p><a id="X7BF81EAF80D1A4B5" name="X7BF81EAF80D1A4B5"></a></p>
<h5>2.2-7 <span class="Heading"><code class="code">@Level <var class="Arg">lvl</var></code></span></h5>
<p>Sets the current level of the documentation. All items created after this, chapters, sections, and items, are given the level <var class="Arg">lvl</var>, until the <code class="code">@ResetLevel</code> command resets the level to 0 or another level is set.</p>
<p>See section <a href="chap2.html#X8209AFDE8209AFDE"><span class="RefLink">2.6</span></a> for more information about levels.</p>
<p><a id="X7C6723D57F424215" name="X7C6723D57F424215"></a></p>
<h5>2.2-8 <span class="Heading"><code class="code">@ResetLevel</code></span></h5>
<p>Resets the current level to 0.</p>
<p><a id="X83D6DA3B83D3436C" name="X83D6DA3B83D3436C"></a></p>
<h5>2.2-9 <span class="Heading"><code class="code">@BeginExample</code> and <code class="code">@EndExample</code></span></h5>
<p><code class="code">@BeginExample</code> marks the start of an example to be put into the manual. It differs from <strong class="pkg">GAPDoc</strong>'s <code class="code"><Example></code> (see <a href="../../../pkg/gapdoc/doc/chap3_mj.html#X810DEA1E83A57CFE"><span class="RefLink">GAPDoc: Log</span></a>), in that it expects actual code (not in a comment) interspersed with comments, to allow for examples files that can be both executed by <strong class="pkg">GAP</strong>, and parsed by <strong class="pkg">AutoDoc</strong>. To achieve this, <strong class="pkg">GAP</strong> commands are not preceded by a comment, while output has to be preceded by an <strong class="pkg">AutoDoc</strong> comment. The <code class="code">gap></code> prompt for the display in the manual is added by <strong class="pkg">AutoDoc</strong>. <code class="code">@EndExample</code> ends the example block.</p>
<p>To illustrate this command, consider this input:</p>
<div class="example"><pre>
#! @BeginExample
S5 := SymmetricGroup(5);
#! Sym( [ 1 .. 5 ] )
Order(S5);
#! 120
#! @EndExample
</pre></div>
<p>This results in the following output:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">S5 := SymmetricGroup(5);</span>
Sym( [ 1 .. 5 ] )
<span class="GAPprompt">gap></span> <span class="GAPinput">Order(S5);</span>
120
</pre></div>
<p>The <strong class="pkg">AutoDoc</strong> command <code class="code">@Example</code> is an alias of <code class="code">@BeginExample</code>.</p>
<p><a id="X861E2E778510CAF7" name="X861E2E778510CAF7"></a></p>
<h5>2.2-10 <span class="Heading"><code class="code">@BeginExampleSession</code> and <code class="code">@EndExampleSession</code></span></h5>
<p><code class="code">@BeginExampleSession</code> marks the start of an example to be put into the manual, while <code class="code">@EndExampleSession</code> ends the example block. It is the direct analog of <strong class="pkg">GAPDoc</strong>'s <code class="code"><Example></code> (see <a href="../../../pkg/gapdoc/doc/chap3_mj.html#X810DEA1E83A57CFE"><span class="RefLink">GAPDoc: Log</span></a>).</p>
<p>To illustrate this command, consider this input:</p>
<div class="example"><pre>
#! @BeginExampleSession
#! gap> S5 := SymmetricGroup(5);
#! Sym( [ 1 .. 5 ] )
#! gap> Order(S5);
#! 120
#! @EndExampleSession
</pre></div>
<p>This results in the following output:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">S5 := SymmetricGroup(5);</span>
Sym( [ 1 .. 5 ] )
<span class="GAPprompt">gap></span> <span class="GAPinput">Order(S5);</span>
120
</pre></div>
<p>It inserts an example into the manual just as <code class="code">@Example</code> 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 <strong class="pkg">AutoDoc</strong> comment (<code class="code">#!</code>). 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 <code class="code">#!</code> and the <code class="code">gap></code> prompt. The <strong class="pkg">AutoDoc</strong> command <code class="code">@ExampleSession</code> is an alias of <code class="code">@BeginExampleSession</code>.</p>
<p><a id="X81A2D44D834C0A17" name="X81A2D44D834C0A17"></a></p>
<h5>2.2-11 <span class="Heading"><code class="code">@BeginLog</code> and <code class="code">@EndLog</code></span></h5>
<p>Works just like the <code class="code">@BeginExample</code> command, but the example will not be tested. See the <strong class="pkg">GAPDoc</strong> manual for more information. The <strong class="pkg">AutoDoc</strong> command <code class="code">@Log</code> is an alias of <code class="code">@BeginLog</code>.</p>
<p><a id="X7BADE876794FF309" name="X7BADE876794FF309"></a></p>
<h5>2.2-12 <span class="Heading"><code class="code">@BeginLogSession</code> and <code class="code">@EndLogSession</code></span></h5>
<p>Works just like the <code class="code">@BeginExampleSession</code> command, but the example will not be tested if manual examples are run. It is the direct analog of <strong class="pkg">GAPDoc</strong>'s <code class="code"><Log></code> (see <a href="../../../pkg/gapdoc/doc/chap3_mj.html#X810DEA1E83A57CFE"><span class="RefLink">GAPDoc: Log</span></a>). The <strong class="pkg">AutoDoc</strong> command <code class="code">@LogSession</code> is an alias of <code class="code">@BeginLogSession</code>.</p>
<p><a id="X78DC644E8519280C" name="X78DC644E8519280C"></a></p>
<h5>2.2-13 <span class="Heading"><code class="code">@DoNotReadRestOfFile</code></span></h5>
<p>Prevents the rest of the file from being read by the parser. Useful for unfinished or temporary files.</p>
<div class="example"><pre>
#! This will appear in the manual
#! @DoNotReadRestOfFile
#! This will not appear in the manual.
</pre></div>
<p><a id="X83C01F9B7FA1C973" name="X83C01F9B7FA1C973"></a></p>
<h5>2.2-14 <span class="Heading"><code class="code">@BeginChunk <var class="Arg">name</var></code>, <code class="code">@EndChunk</code>, and <code class="code">@InsertChunk <var class="Arg">name</var></code></span></h5>
<p>Text inside a <code class="code">@BeginChunk</code> / <code class="code">@EndChunk</code> 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 <code class="code">@InsertChunk <var class="Arg">name</var></code> command. If you do not provide an <code class="code">@EndChunk</code>, the chunk ends at the end of the file.</p>
<div class="example"><pre>
#! @BeginChunk MyChunk
#! Hello, world.
#! @EndChunk
#! @InsertChunk MyChunk
## The text "Hello, world." is inserted right before this.
</pre></div>
<p>You can use this to define an example like this in one file:</p>
<div class="example"><pre>
#! @BeginChunk Example_Symmetric_Group
#! @BeginExample
S5 := SymmetricGroup(5);
#! Sym( [ 1 .. 5 ] )
Order(S5);
#! 120
#! @EndExample
#! @EndChunk
</pre></div>
<p>And then later, insert the example in a different file, like this:</p>
<div class="example"><pre>
#! @InsertChunk Example_Symmetric_Group
</pre></div>
<p><a id="X7D3671AF86B995B9" name="X7D3671AF86B995B9"></a></p>
<h5>2.2-15 <span class="Heading"><code class="code">@BeginCode <var class="Arg">name</var></code>, @EndCode, and <code class="code">@InsertCode <var class="Arg">name</var></code></span></h5>
<p>Inserts the text between <code class="code">@BeginCode</code> and <code class="code">@EndCode</code> verbatim at the point where <code class="code">@InsertCode</code> is called. This is useful to insert code excerpts directly into the manual.</p>
<div class="example"><pre>
#! @BeginCode Increment
i := i + 1;
#! @EndCode
#! @InsertCode Increment
## Code is inserted here.
</pre></div>
<p><a id="X8033B34F80A12A10" name="X8033B34F80A12A10"></a></p>
<h5>2.2-16 <span class="Heading"><code class="code">@LatexOnly <var class="Arg">text</var></code>, <code class="code">@BeginLatexOnly</code>, and <code class="code">@EndLatexOnly</code></span></h5>
<p>Code inserted between <code class="code">@BeginLatexOnly</code> and <code class="code">@EndLatexOnly</code> or after <code class="code">@LatexOnly</code> is only inserted in the PDF version of the manual or worksheet. It can hold arbitrary LaTeX-commands.</p>
<div class="example"><pre>
#! @BeginLatexOnly
#! \include{picture.tex}
#! @EndLatexOnly
#! @LatexOnly \include{picture.tex}
</pre></div>
<p><a id="X7EF303147F1BCC22" name="X7EF303147F1BCC22"></a></p>
<h5>2.2-17 <span class="Heading"><code class="code">@NotLatex <var class="Arg">text</var></code>, <code class="code">@BeginNotLatex</code>, and <code class="code">@EndNotLatex</code></span></h5>
<p>Code inserted between <code class="code">@BeginNotLatex</code> and <code class="code">@EndNotLatex</code> or after <code class="code">@NotLatex</code> is inserted in the HTML and text versions of the manual or worksheet, but not in the PDF version.</p>
<div class="example"><pre>
#! @BeginNotLatex
#! For further information see the PDF version of this manual.
#! @EndNotLatex
#! @NotLatex For further information see the PDF version of this manual.
</pre></div>
<p><a id="X841E3AD584F5385C" name="X841E3AD584F5385C"></a></p>
<h4>2.3 <span class="Heading">Title page commands</span></h4>
<p>The following commands can be used to add the corresponding parts to the title page of the document which generated by <strong class="pkg">AutoDoc</strong> if scaffolding is enabled.</p>
<ul>
<li><p><code class="code">@Title</code></p>
</li>
<li><p><code class="code">@Subtitle</code></p>
</li>
<li><p><code class="code">@Version</code></p>
</li>
<li><p><code class="code">@TitleComment</code></p>
</li>
<li><p><code class="code">@Author</code></p>
</li>
<li><p><code class="code">@Date</code></p>
</li>
<li><p><code class="code">@Address</code></p>
</li>
<li><p><code class="code">@Abstract</code></p>
</li>
<li><p><code class="code">@Copyright</code></p>
</li>
<li><p><code class="code">@Acknowledgements</code></p>
</li>
<li><p><code class="code">@Colophon</code></p>
</li>
</ul>
<p>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 <code class="file">PackageInfo.g</code>. 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 <code class="func">AutoDocWorksheet</code> (<a href="chap3.html#X809FE4137C08B28D"><span class="RefLink">3.1-1</span></a>), since worksheets do not have a <code class="file">PackageInfo.g</code> file from which this information could be extracted.</p>
<p><a id="X828AE38F80CB02E7" name="X828AE38F80CB02E7"></a></p>
<h4>2.4 <span class="Heading">Plain text files</span></h4>
<p>Files that have the suffix <code class="code">.autodoc</code> and are listed in the <code class="code">autodoc.files</code> option of <code class="func">AutoDoc</code> (<a href="chap4.html#X7CBD8AAF7DCEF352"><span class="RefLink">4.1-1</span></a>), resp. are contained in one of the directories listed in <code class="code">autodoc.scan_dirs</code>, are treated as <strong class="pkg">AutoDoc</strong> plain text files. These work exactly like <strong class="pkg">AutoDoc</strong> comments, except that lines do not need to (and in fact, should not) start with <code class="code">#!</code>.</p>
<p><a id="X7D7A38F87BC40C48" name="X7D7A38F87BC40C48"></a></p>
<h4>2.5 <span class="Heading">Grouping</span></h4>
<p>In <strong class="pkg">GAPDoc</strong>, it is possible to make groups of manual items, i.e., when documenting a function, operation, etc., it is possible to group them into suitable chunks. This can be particularly useful if there are several definitions of an operation with several different argument types, all doing more or less the same to the arguments. Then their manual items can be grouped, sharing the same description and return type information. You can give a heading to the group in the manual with the <code class="code">@GroupTitle</code> command; if that is not supplied, then the heading of the first manual item in the group will be used as the heading.</p>
<p>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 <code class="code">@BeginGroup</code> / <code class="code">@EndGroup</code> pairs using the same group name, in different places, and these all will refer to the same group.</p>
<p>Moreover, this means that you can add items to a group via the <code class="code">@Group</code> command in the <strong class="pkg">AutoDoc</strong> comment of an arbitrary declaration, at any time.</p>
<p>The following code</p>
<div class="example"><pre>
#! @BeginGroup Group1
#! @GroupTitle A family of operations
#! @Description
#! First sentence.
DeclareOperation( "FirstOperation", [ IsInt ] );
#! @Description
#! Second sentence.
DeclareOperation( "SecondOperation", [ IsInt, IsGroup ] );
#! @EndGroup
## .. Stuff ..
#! @Description
#! Third sentence.
#! @Group Group1
KeyDependentOperation( "ThirdOperation", IsGroup, IsInt, "prime );
</pre></div>
<p>produces the following:</p>
<p><a id="X79BF060F8436C586" name="X79BF060F8436C586"></a></p>
<h5>2.5-1 <span class="Heading">A family of operations</span></h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ FirstOperation</code>( <var class="Arg">arg</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ SecondOperation</code>( <var class="Arg">arg1</var>, <var class="Arg">arg2</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ ThirdOperation</code>( <var class="Arg">arg1</var>, <var class="Arg">arg2</var> )</td><td class="tdright">( operation )</td></tr></table></div>
<p>First sentence. Second sentence. Third sentence.</p>
<p><a id="X8209AFDE8209AFDE" name="X8209AFDE8209AFDE"></a></p>
<h4>2.6 <span class="Heading">Level</span></h4>
<p>Levels can be set to not write certain parts in the manual by default. Every entry has by default the level 0. The command <code class="code">@Level</code> 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 <strong class="pkg">AutoDoc</strong>, the parts will be included in the manual at the specific place.</p>
<div class="example"><pre>
#! 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.
</pre></div>
<p><a id="X79558A2F7FE187B4" name="X79558A2F7FE187B4"></a></p>
<h4>2.7 <span class="Heading">Markdown-like formatting of text in <strong class="pkg">AutoDoc</strong></span></h4>
<p><strong class="pkg">AutoDoc</strong> 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.</p>
<p><a id="X7B256AE5780F140A" name="X7B256AE5780F140A"></a></p>
<h5>2.7-1 <span class="Heading">Lists</span></h5>
<p>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:</p>
<div class="example"><pre>
#! 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.
</pre></div>
<p>This is the output:<br /> The list starts in the next line</p>
<ul>
<li><p>item 1</p>
</li>
<li><p>item 2 which is a bit longer</p>
<ul>
<li><p>and also contains a nested list</p>
</li>
<li><p>with two items</p>
</li>
</ul>
</li>
<li><p>item 3 of the outer list</p>
</li>
</ul>
<p>This does not belong to the list anymore.<br /> The *, -, and + are fully interchangeable and can even be used mixed, but this is not recommended.</p>
<p><a id="X871412737A0E12E2" name="X871412737A0E12E2"></a></p>
<h5>2.7-2 <span class="Heading">Math modes</span></h5>
<p>One can start an inline formula with a $, and also end it with $, just like in LaTeX. This will translate into <strong class="pkg">GAPDoc</strong>s inline math environment. For display mode one can use $$, also like LaTeX.</p>
<div class="example"><pre>
#! This is an inline formula: $1+1 = 2$.
#! This is a display formula:
#! $$ \sum_{i=1}^n i. $$
</pre></div>
<p>produces the following output:<br /> This is an inline formula: <span class="Math">1+1 = 2</span>. This is a display formula:</p>
<p class="pcenter"> \sum_{i=1}^n i. </p>
<p><a id="X7ED0330479146EFC" name="X7ED0330479146EFC"></a></p>
<h5>2.7-3 <span class="Heading">Emphasize</span></h5>
<p>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:</p>
<div class="example"><pre>
#! **This** is very important.
#! This is __also important__.
#! **Naturally, more than one line
#! can be important.**
</pre></div>
<p>This produces the following output:<br /> <em>This</em> is very important. This is <em>also important</em>. <em>Naturally, more than one line can be important.</em></p>
<p><a id="X838CCDEB7E0ECEE2" name="X838CCDEB7E0ECEE2"></a></p>
<h5>2.7-4 <span class="Heading">Inline code</span></h5>
<p>One can mark inline code snippets by using backticks (`) at the beginning and the end of the text which should be marked as code. Example:</p>
<div class="example"><pre>
#! Call function `foobar()` at the start.
</pre></div>
<p>This produces the following output:<br /> Call function <code class="code">foobar()</code> at the start.</p>
<p><a id="X78CA9E5C7F494C19" name="X78CA9E5C7F494C19"></a></p>
<h4>2.8 <span class="Heading">Deprecated commands</span></h4>
<p>The following commands used to be supported, but should not generally be used anymore. They will be removed in a future version of <strong class="pkg">AutoDoc</strong>.</p>
<dl>
<dt><strong class="Mark"><code class="code">@EndSection</code></strong></dt>
<dd><p>You can simply remove any use of this, <strong class="pkg">AutoDoc</strong> ends sections automatically at the start of any new section or chapter.</p>
</dd>
<dt><strong class="Mark"><code class="code">@EndSubsection</code></strong></dt>
<dd><p>You can simply remove any use of this, <strong class="pkg">AutoDoc</strong> ends subsections automatically at the start of any new subsection, section or chapter.</p>
</dd>
<dt><strong class="Mark"><code class="code">@BeginAutoDoc</code> and <code class="code">@EndAutoDoc</code></strong></dt>
<dd><p>It suffices to prepend each declaration that is meant to be appear in the manual with a minimal <strong class="pkg">AutoDoc</strong> comment <code class="code">#!</code>.</p>
</dd>
<dt><strong class="Mark"><code class="code">@BeginSystem <var class="Arg">name</var></code>, <code class="code">@EndSystem</code>, and <code class="code">@InsertSystem <var class="Arg">name</var></code></strong></dt>
<dd><p>Please use the chunk commands from subsection <a href="chap2.html#X83C01F9B7FA1C973"><span class="RefLink">2.2-14</span></a> instead.</p>
</dd>
<dt><strong class="Mark"><code class="code">@AutoDocPlainText</code> and <code class="code">@EndAutoDocPlainText</code></strong></dt>
<dd><p>Use <code class="code">.autodoc</code> files or <strong class="pkg">AutoDoc</strong> comments instead.</p>
</dd>
</dl>
<div class="chlinkprevnextbot"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap1.html">[Previous Chapter]</a> <a href="chap3.html">[Next Chapter]</a> </div>
<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<hr />
<p class="foot">generated by <a href="http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>
|
