GAP 4.8.9 installation with standard packages -- copy to your CoCalc project to get it

1
  
2
  2 AutoDoc documentation comments
3
  
4
  You can document declarations of global functions and variables, operations,
5
  attributes etc. by inserting AutoDoc comments into your sources before these
6
  declaration.  An  AutoDoc  comment  always  starts with #!. This is also the
7
  smallest  possible AutoDoc command. If you want your declaration documented,
8
  just write #! at the line before the documentation. For example:
9
  
10
  
11
    #!
12
    DeclareOperation( "AnOperation",
13
                      [ IsList ] );
14
  
15
  
16
  This will produce a manual entry for the operation AnOperation.
17
  
18
  Inside  of AutoDoc comments, AutoDoc commands starting with @ can be used to
19
  control the output AutoDoc produces.
20
  
21
  
22
  2.1 Documenting declarations
23
  
24
  In  the  bare  form above, the manual entry for AnOperation will not contain
25
  much more than the name of the operation. In order to change this, there are
26
  several   commands   you  can  put  into  the  AutoDoc  comment  before  the
27
  declaration. Currently, the following commands are provided:
28
  
29
  
30
  2.1-1 @Description descr
31
  
32
  Adds  the  text  in the following lines of the AutoDoc to the description of
33
  the  declaration  in the manual. Lines are until the next AutoDoc command or
34
  until the declaration is reached.
35
  
36
  
37
  2.1-2 @Returns ret_val
38
  
39
  The  string  ret_val  is added to the documentation, with the text Returns: 
40
  put  in front of it. This should usually give a brief hint about the type or
41
  meaning of the value retuned by the documented function.
42
  
43
  
44
  2.1-3 @Arguments args
45
  
46
  The  string  args  contains  a  description  of  the  arguments the function
47
  expects, including optional parts, which are denoted by square brackets. The
48
  argument names can be separated by whitespace, commas or square brackets for
49
  the  optional  arguments,  like  grp[, elm] or xx[y[z] ]. If GAP options are
50
  used,  this  can  be followed by a colon : and one or more assignments, like
51
  n[, r]: tries := 100.
52
  
53
  
54
  2.1-4 @Group grpname
55
  
56
  Adds  the  following  method to a group with the given name. See section 2.5
57
  for more information about groups.
58
  
59
  
60
  2.1-5 @Label label
61
  
62
  Adds  label  to  the  function  as label. If this is not specified, then for
63
  declarations  that  involve  a  list  of  input  filters (as is the case for
64
  DeclareOperation, DeclareAttribute, etc.), a default label is generated from
65
  this filter list.
66
  
67
  
68
    #! @Label testlabel
69
    DeclareProperty( "AProperty",
70
                     IsObject );
71
  
72
  
73
  leads to this:
74
  
75
  2.1-6 AProperty
76
  
77
  AProperty( arg )  property
78
  Returns:  true or false
79
  
80
  while
81
  
82
  
83
    #!
84
    DeclareProperty( "AProperty",
85
                     IsObject );
86
  
87
  
88
  leads to this:
89
  
90
  2.1-7 AProperty
91
  
92
  AProperty( arg )  property
93
  Returns:  true or false
94
  
95
  
96
  2.1-8 @ChapterInfo chapter, section
97
  
98
  Adds  the  entry to the given chapter and section. Here, chapter and section
99
  are the respective titles.
100
  
101
  As  an  example, a full AutoDoc comment for with all options could look like
102
  this:
103
  
104
  
105
    #! @Description
106
    #! Computes the list of lists of degrees of ordinary characters
107
    #! associated to the <A>p</A>-blocks of the group <A>G</A>
108
    #! with <A>p</A>-modular character table <A>modtbl</A>
109
    #! and underlying ordinary character table <A>ordtbl</A>.
110
    #! @Returns a list
111
    #! @Arguments modtbl
112
    #! @Group CharacterDegreesOfBlocks
113
    #! @FunctionLabel chardegblocks
114
    #! @ChapterInfo Blocks, Attributes
115
    DeclareAttribute( "CharacterDegreesOfBlocks",
116
            IsBrauerTable );
117
  
118
  
119
  
120
  2.2 Other documentation comments
121
  
122
  There  are also some commands which can be used in AutoDoc comments that are
123
  not  associated  to  any  declaration. This is useful for additional text in
124
  your documentation, examples, mathematical chapters, etc..
125
  
126
  
127
  2.2-1 @Chapter name
128
  
129
  Sets  a  chapter,  all functions without separate info will be added to this
130
  chapter.  Also  all  text  comments, i.e. lines that begin with #! without a
131
  command,  and  which  do not follow after @description, will be added to the
132
  chapter as regular text. Example:
133
  
134
  
135
    #! @Chapter My chapter
136
    #!  This is my chapter.
137
    #!  I document my stuff in it.
138
  
139
  
140
  The  @ChapterLabel label command can be used to set the label of the chapter
141
  to   Chapter_label.   Additionally,   the   chapter   will   be   stored  as
142
  _Chapter_label.xml.
143
  
144
  
145
  2.2-2 @Section name
146
  
147
  Sets a section like chapter sets a chapter.
148
  
149
  
150
    #! @Section My first manual section
151
    #!  In this section I am going to document my first method.
152
  
153
  
154
  The  @SectionLabel label command can be used to set the label of the section
155
  to Section_label.
156
  
157
  
158
  2.2-3 @EndSection
159
  
160
  Closes the current section. Please be careful here. Closing a section before
161
  opening it might cause unexpected errors.
162
  
163
  
164
    #! @EndSection
165
    #### The following text again belongs to the chapter
166
    #! Now we could start a second section if we want to.
167
  
168
  
169
  
170
  2.2-4 @Subsection name
171
  
172
  Sets a subsection like chapter sets a chapter.
173
  
174
  
175
    #! @Subsection My first manual subsection
176
    #!  In this subsection I am going to document my first example.
177
  
178
  
179
  The  @SubsectionLabel  label  command  can  be  used to set the label of the
180
  subsection to Subsection_label.
181
  
182
  
183
  2.2-5 @EndSubsection
184
  
185
  Closes  the current subsection. Please be careful here. Closing a subsection
186
  before opening it might cause unexpected errors.
187
  
188
  
189
    #! @EndSubsection
190
    #### The following text again belongs to the section
191
    #! Now we are in the section again
192
  
193
  
194
  
195
  2.2-6 @BeginAutoDoc
196
  
197
  Causes   all  subsequent  declarations  to  be  documented  in  the  manual,
198
  regardless of whether they have an AutoDoc comment in front of them or not.
199
  
200
  
201
  2.2-7 @EndAutoDoc
202
  
203
  Ends  the  affect of @BeginAutoDoc. So from here on, again only declarations
204
  with an explicit AutoDoc comment in front are added to the manual.
205
  
206
  
207
    #! @BeginAutoDoc
208
    
209
    DeclareOperation( "Operation1", [ IsList ] );
210
    
211
    DeclareProperty( "IsProperty", IsList );
212
    
213
    #! @EndAutoDoc
214
  
215
  
216
  Both, Operation1 and IsProperty would appear in the manual.
217
  
218
  
219
  2.2-8 @BeginGroup [grpname]
220
  
221
  Starts  a  group.  All following documented declarations without an explicit
222
  @Group  command  are grouped together in the same group with the given name.
223
  If  no  name is given, then a new nameless group is generated. The effect of
224
  this command is ended when an @EndGroup command is reached.
225
  
226
  See section 2.5 for more information about groups.
227
  
228
  
229
  2.2-9 @EndGroup
230
  
231
  Ends the current group.
232
  
233
  
234
    #! @BeginGroup MyGroup
235
    #!
236
    DeclareAttribute( "GroupedAttribute",
237
                      IsList );
238
    
239
    DeclareOperation( "NonGroupedOperation",
240
                      [ IsObject ] );
241
    
242
    #!
243
    DeclareOperation( "GroupedOperation",
244
                      [ IsList, IsRubbish ] );
245
    #! @EndGroup
246
  
247
  
248
  
249
  2.2-10 @Level lvl
250
  
251
  Sets  the  current level of the documentation. All items created after this,
252
  chapters,   sections,  and  items,  are  given  the  level  lvl,  until  the
253
  @ResetLevel command resets the level to 0 or another level is set.
254
  
255
  See section 2.6 for more information about groups.
256
  
257
  
258
  2.2-11 @ResetLevel
259
  
260
  Resets the current level to 0.
261
  
262
  
263
  2.2-12 @BeginExample and @EndExample
264
  
265
  @BeginExample inserts an example into the manual. The syntax for examples is
266
  different  from GAPDocs example syntax in order to have a file that contains
267
  the  example  and  is  GAP  readable.  To achieve this, GAP commands are not
268
  preceded  by  a  comment,  while  output  has  to  be preceded by an AutoDoc
269
  comment.  The  GAP prompt for the display in the manual is added by AutoDoc.
270
  @EndExample ends the example block.
271
  
272
  
273
    #! @BeginExample
274
    S5 := SymmetricGroup(5);
275
    #! Sym( [ 1 .. 5 ] )
276
    Order(S5);
277
    #! 120
278
    #! @EndExample
279
  
280
  
281
  
282
  2.2-13 @ExampleSession and @EndExampleSession
283
  
284
  @ExampleSession  inserts  an  example  into  the  manual, but in a different
285
  syntax. For example, consider
286
  
287
  
288
    #! @BeginExample
289
    S5 := SymmetricGroup(5);
290
    #! Sym( [ 1 .. 5 ] )
291
    Order(S5);
292
    #! 120
293
    #! @EndExample
294
  
295
  
296
  As  you  can see, the commands are not commented and hence are executed when
297
  the  file  containing the example block is read. To insert examples directly
298
  into source code files, one can instead use @ExampleSession:
299
  
300
  
301
    #! @ExampleSession
302
    #! gap> S5 := SymmetricGroup(5);
303
    #! Sym( [ 1 .. 5 ] )
304
    #! gap> Order(S5);
305
    #! 120
306
    #! @EndExampleSession
307
  
308
  
309
  It  inserts  an  example  into the manual just as @Example would do, but all
310
  lines are commented and therefore not executed when the file is read.
311
  
312
  
313
  2.2-14 @BeginLog and @EndLog
314
  
315
  Works  just  like  the  @BeginExample  command,  but the example will not be
316
  tested. See the GAPDoc manual for more information.
317
  
318
  
319
  2.2-15 @BeginLogSession and @EndLogSession
320
  
321
  Works  just  like the @BeginExampleSession command, but the example will not
322
  be  tested  if  manual  examples  are  run.  See  the GAPDoc manual for more
323
  information.
324
  
325
  
326
  2.2-16 @DoNotReadRestOfFile
327
  
328
  Prevents  the rest of the file from being read by the parser. Useful for not
329
  finished or temporary files.
330
  
331
  
332
    #! This will appear in the manual
333
    
334
    #! @DoNotReadRestOfFile
335
    
336
    #! This will not appear in the manual.
337
  
338
  
339
  
340
  2.2-17 @BeginChunk name, @EndChunk, and @InsertChunk name
341
  
342
  Text insider of a @BeginChunk / @EndChunk part will not be inserted into the
343
  final  documentation  directly.  Instead,  the text is stored in an internal
344
  buffer.  That chunk of text can then later on be inserted in any other place
345
  by  using the @InsertChunk name command. If you do not provide an @EndChunk,
346
  the chunk ends at the end of the file.
347
  
348
  
349
    #! @BeginChunk MyChunk
350
    #! Hello, world.
351
    #! @EndChunk
352
    
353
    #! @InsertChunk MyChunk
354
    ## The text "Hello, world." is inserted right before this.
355
  
356
  
357
  You can use this to define an example like this in one file:
358
  
359
  
360
    #! @BeginChunk Example_Symmetric_Group
361
    #! @BeginExample
362
    S5 := SymmetricGroup(5);
363
    #! Sym( [ 1 .. 5 ] )
364
    Order(S5);
365
    #! 120
366
    #! @EndExample
367
    #! @EndChunk
368
  
369
  
370
  And then later, insert the example in a different file, like this:
371
  
372
  
373
    #! @InsertChunk Example_Symmetric_Group
374
  
375
  
376
  
377
  2.2-18 @BeginSystem name, @EndSystem, and @InsertSystem name
378
  
379
  Same  as  @BeginChunk  etc.  This  command  is  deprecated. Please use chunk
380
  instead.
381
  
382
  
383
  2.2-19 @BeginCode name, @EndCode, and @InsertCode name
384
  
385
  Inserts the text between @BeginCode and @EndCode verbatim at the point where
386
  @InsertCode  is called. This is useful to insert code excerpts directly into
387
  the manual.
388
  
389
  
390
    #! @BeginCode Increment
391
    i := i + 1;
392
    #! @EndCode
393
    
394
    #! @InsertCode Increment
395
    ## Code is inserted here.
396
  
397
  
398
  
399
  2.2-20 @LatexOnly text, @BeginLatexOnly , and @EndLatexOnly
400
  
401
  Code  inserted between @BeginLatexOnly and @EndLatexOnly or after @LatexOnly
402
  is  only inserted in the PDF version of the manual or worksheet. It can hold
403
  arbitrary LaTeX-commands.
404
  
405
  
406
    #! @BeginLatexOnly
407
    #! \include{picture.tex}
408
    #! @EndLatexOnly
409
    
410
    #! @LatexOnly \include{picture.tex}
411
  
412
  
413
  
414
  2.3 Title page commands
415
  
416
  The  following  commands  can  be used to add the corresponding parts to the
417
  title page of the document, in case the scaffolding is enabled.
418
  
419
      @Title
420
  
421
      @Subtitle
422
  
423
      @Version
424
  
425
      @TitleComment
426
  
427
      @Author
428
  
429
      @Date
430
  
431
      @Address
432
  
433
      @Abstract
434
  
435
      @Copyright
436
  
437
      @Acknowledgements
438
  
439
      @Colophon
440
  
441
  Those  add the following lines at the corresponding point of the title page.
442
  Please  note  that  many  of those things can be (better) extracted from the
443
  PackageInfo.g.  In  case you set some of those, the extracted or in scaffold
444
  defined  items  will  be  overwritten.  While  this  is  not very useful for
445
  documenting  packages,  they  are  necessary  for  worksheets  created  with
446
  AutoDocWorksheet  (3.1-1),  since  they do not have a PackageInfo to extract
447
  those information.
448
  
449
  
450
  2.4 Plain text files
451
  
452
  AutoDoc plain text files work exactly like AutoDoc comments, except that the
453
  #!  is  unnecessary  at  the beginning of a line which should be documented.
454
  Files  that  have  the  suffix .autodoc will automatically regarded as plain
455
  text  files  while  the  commands @AutoDocPlainText and @EndAutoDocPlainText
456
  mark  parts  in  plain text files which should be regarded as AutoDoc parts.
457
  All commands can be used like before.
458
  
459
  
460
  2.5 Grouping
461
  
462
  In GAPDoc, it is possible to make groups of ManItems, i.e., when documenting
463
  a  function,  operation,  etc.,  it  is possible to group them into suitable
464
  chunks.  This can be particularly useful if there are several definitions of
465
  an  operation  with several different argument types, all doing more or less
466
  the  same  to the arguments. Then their manual items can be grouped, sharing
467
  the  same description and return type information. Note that it is currently
468
  not  possible to give a header to the Group in the manual, but the generated
469
  ManItem heading of the first entry will be used.
470
  
471
  Note  that group names are globally unique throughout the whole manual. That
472
  is,  groups  with the same name are in fact merged into a single group, even
473
  if  they were declared in different source files. Thus you can have multiple
474
  @BeginGroup  /  @EndGroup  pairs  using  the  same  group name, in different
475
  places, and these all will refer to the same group.
476
  
477
  Moreover,  this  means  that  you  can  add  items to a group via the @Group
478
  command in the AutoDoc comment of an arbitrary declaration, at any time. The
479
  following code
480
  
481
  
482
    #! @BeginGroup Group1
483
    
484
    #! @Description
485
    #!  First sentence.
486
    DeclareOperation( "FirstOperation", [ IsInt ] );
487
    
488
    #! @Description
489
    #!  Second sentence.
490
    DeclareOperation( "SecondOperation", [ IsInt, IsGroup ] );
491
    
492
    #! @EndGroup
493
    
494
    ## .. Stuff ..
495
    
496
    #! @Description
497
    #!  Third sentence.
498
    #! @Group Group1
499
    KeyDependentOperation( "ThirdOperation", IsGroup, IsInt, "prime );
500
  
501
  
502
  produces the following:
503
  
504
  2.5-1 FirstOperation
505
  
506
  FirstOperation( arg )  operation
507
  SecondOperation( arg1, arg2 )  operation
508
  ThirdOperation( arg1, arg2 )  operation
509
  
510
  First sentence. Second sentence. Third sentence.
511
  
512
  
513
  2.6 Level
514
  
515
  Levels can be set to not write certain parts in the manual by default. Every
516
  entry  has by default the level 0. The command @Level can be used to set the
517
  level of the following part to a higher level, for example 1, and prevent it
518
  from  being printed to the manual by default. However, if one sets the level
519
  to  a  higher  value  in  the  autodoc  option of AutoDoc, the parts will be
520
  included in the manual at the specific place.
521
  
522
  
523
    #! This text will be printed to the manual.
524
    #! @Level 1
525
    #! This text will be printed to the manual if created with level 1 or higher.
526
    #! @Level 2
527
    #! This text will be printed to the manual if created with level 2 or higher.
528
    #! @ResetLevel
529
    #! This text will be printed to the manual.
530
  
531
  
532
  
533
  2.7 Markdown-like formatting of text in AutoDoc
534
  
535
  AutoDoc  has  some  convenient ways to insert special format into text, like
536
  math  formulas  and  lists. The syntax for them are inspired by Markdown and
537
  LaTeX,  but  do  not  follow  them strictly. Neither are all features of the
538
  Markdown  language  supported.  The  following  subsections describe what is
539
  possible.
540
  
541
  
542
  2.7-1 Lists
543
  
544
  One can create lists of items by beginning a new line with *, +, -, followed
545
  by one space. The first item starts the list. When items are longer than one
546
  line,  the  following  lines have to be indented by at least two spaces. The
547
  list ends when a line which does not start a new item is not indented by two
548
  spaces. Of course lists can be nested. Here is an example:
549
  
550
  
551
    #! The list starts in the next line
552
    #! * item 1
553
    #! * item 2
554
    #!   which is a bit longer
555
    #!   * and also contains a nested list
556
    #!   * with two items
557
    #! * item 3 of the outer list
558
    #! This does not belong to the list anymore.
559
  
560
  
561
  This is the output:
562
  The list starts in the next line
563
  
564
      item 1
565
  
566
      item 2 which is a bit longer
567
  
568
            and also contains a nested list
569
  
570
            with two items
571
  
572
      item 3 of the outer list
573
  
574
  This does not belong to the list anymore.
575
  The  *,  -,  and + are fully interchangeable and can even be used mixed, but
576
  this is not recommended.
577
  
578
  
579
  2.7-2 Math modes
580
  
581
  One  can start an inline formula with a $, and also end it with $, just like
582
  in  LaTeX.  This  will  translate  into GAPDocs inline math environment. For
583
  display mode one can use $$, also like LaTeX.
584
  
585
  
586
    #! This is an inline formula: $1+1 = 2$.
587
    #! This is a display formula:
588
    #! $$ \sum_{i=1}^n i. $$
589
  
590
  
591
  produces the following output:
592
  This is an inline formula: 1+1 = 2. This is a display formula:
593
  
594
  
595
        \sum_{i=1}^n i. 
596
  
597
  
598
  
599
  2.7-3 Emphasize
600
  
601
  One  can  emphasize text by using two asterisks (**) or two underscores (__)
602
  at  the  beginning  and  the  end  of  the  text which should be emphasized.
603
  Example:
604
  
605
  
606
    #! **This** is very important.
607
    #! This is __also important__.
608
    #! **Naturally, more than one line
609
    #! can be important.**
610
  
611
  
612
  This produces the following output:
613
  This  is  very  important.  This is also important. Naturally, more than one
614
  line can be important.
615
  
616

617