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
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
|
<?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 (GAPDoc) - Chapter 3: The Document Type Definition</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="chap3" 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="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chap7.html">7</a> <a href="chapA.html">A</a> <a href="chapB.html">B</a> <a href="chapC.html">C</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="chap2.html">[Previous Chapter]</a> <a href="chap4.html">[Next Chapter]</a> </div>
<p id="mathjaxlink" class="pcenter"><a href="chap3_mj.html">[MathJax on]</a></p>
<p><a id="X7859CFF180D52D49" name="X7859CFF180D52D49"></a></p>
<div class="ChapSects"><a href="chap3.html#X7859CFF180D52D49">3 <span class="Heading">The Document Type Definition</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X7B76F6F786521F6B">3.1 <span class="Heading">What is a DTD?</span></a>
</span>
</div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X7DB0F9E57879CC76">3.2 <span class="Heading">Overall Document Structure</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7C7258A57B831934">3.2-1 <span class="Heading"><code class="code"><Book></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X842B421A7FBCDD2C">3.2-2 <span class="Heading"><code class="code"><TitlePage></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7BCC8E6F79021294">3.2-3 <span class="Heading"><code class="code"><Title></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X82E82AF48217CC14">3.2-4 <span class="Heading"><code class="code"><Subtitle></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X876962807DCC52B3">3.2-5 <span class="Heading"><code class="code"><Version></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X87E7CD5B79230B90">3.2-6 <span class="Heading"><code class="code"><TitleComment></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X8731459C7E4C56DA">3.2-7 <span class="Heading"><code class="code"><Author></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X8264A69D7DCDD773">3.2-8 <span class="Heading"><code class="code"><Date></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7EEF65A07A094F65">3.2-9 <span class="Heading"><code class="code"><Address></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X833110FE79628313">3.2-10 <span class="Heading"><code class="code"><Abstract></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X84BBD8307E08E62F">3.2-11 <span class="Heading"><code class="code"><Copyright></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X8143972D7C17838E">3.2-12 <span class="Heading"><code class="code"><Acknowledgements></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7C09A3398059D18C">3.2-13 <span class="Heading"><code class="code"><Colophon></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7E97263A83DC26E9">3.2-14 <span class="Heading"><code class="code"><TableOfContents></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X84F3DF21786A8751">3.2-15 <span class="Heading"><code class="code"><Bibliography></code>
</span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7C53615A8477F1E5">3.2-16 <span class="Heading"><code class="code"><TheIndex></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X80E2AD7481DD69D9">3.3 <span class="Heading">Sectioning Elements</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7B38415687510D0A">3.3-1 <span class="Heading"><code class="code"><Body></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7A86B2BA7D688B6B">3.3-2 <span class="Heading"><code class="code"><Chapter></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X79825E1C821D0B79">3.3-3 <span class="Heading"><code class="code"><Heading></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7C701B2779767556">3.3-4 <span class="Heading"><code class="code"><Appendix></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X844DC2B47FB37339">3.3-5 <span class="Heading"><code class="code"><Section></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X803ACA187E292969">3.3-6 <span class="Heading"><code class="code"><Subsection></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X877B8B7C7EDD09E9">3.4 <span class="Heading">ManSection–a special kind of subsection</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X8375D9CC8672A1D5">3.4-1 <span class="Heading"><code class="code"><ManSection></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7C41A7B5845205C4">3.4-2 <span class="Heading"><code class="code"><Func></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7A15825E818A81CD">3.4-3 <span class="Heading"><code class="code"><Oper></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7FBFD7A3786C7CAB">3.4-4 <span class="Heading"><code class="code"><Constr></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X81196E2B7F286A01">3.4-5 <span class="Heading"><code class="code"><Meth></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7D8D2C38828D5854">3.4-6 <span class="Heading"><code class="code"><Filt></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7D6400A67C30B752">3.4-7 <span class="Heading"><code class="code"><Prop></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X78CEEC5986987A97">3.4-8 <span class="Heading"><code class="code"><Attr></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7C3AACBE7BC6AABF">3.4-9 <span class="Heading"><code class="code"><Var></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X85EE992E7FED2FE6">3.4-10 <span class="Heading"><code class="code"><Fam></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X78F0D4D1811E5BAE">3.4-11 <span class="Heading"><code class="code"><InfoClass></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X78595FB585569617">3.5 <span class="Heading">Cross Referencing and Citations</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X8656F2338007406E">3.5-1 <span class="Heading"><code class="code"><Ref></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7C85CA5484344DB5">3.5-2 <span class="Heading"><code class="code"><Label></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X851DE9D279D8FB04">3.5-3 <span class="Heading"><code class="code"><Cite></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X811042BA78843777">3.5-4 <span class="Heading"><code class="code"><Index></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X81B3E46F839E1C5B">3.5-5 <span class="Heading"><code class="code"><URL></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X8310C4F084CD9DB9">3.5-6 <span class="Heading"><code class="code"><Email></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7D5CC4267D04D7E7">3.5-7 <span class="Heading"><code class="code"><Homepage></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X840099DF83823686">3.6 <span class="Heading">Structural Elements like Lists</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X785183F67DA402A0">3.6-1 <span class="Heading"><code class="code"><List></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7B1545A9797442DC">3.6-2 <span class="Heading"><code class="code"><Mark></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X86C204987AB4B13D">3.6-3 <span class="Heading"><code class="code"><Item></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X78A52B00846562DE">3.6-4 <span class="Heading"><code class="code"><Enum></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7F9CAA577EB4070B">3.6-5 <span class="Heading"><code class="code"><Table></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X7CA1E1327AFBA578">3.7 <span class="Heading">Types of Text</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7B15C428861749FD">3.7-1 <span class="Heading"><code class="code"><Emph></code> and <code class="code"><E></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X80028C2483C9467E">3.7-2 <span class="Heading"><code class="code"><Quoted></code> and <code class="code"><Q></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X867BB95E7DC87014">3.7-3 <span class="Heading"><code class="code"><Keyword></code> and <code class="code"><K></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X86FD4CCA7F98351F">3.7-4 <span class="Heading"><code class="code"><Arg></code> and
<code class="code"><A></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X8400998B7B3A4379">3.7-5 <span class="Heading"><code class="code"><Code></code> and
<code class="code"><C></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X875AF9B4812C5249">3.7-6 <span class="Heading"><code class="code"><File></code> and <code class="code"><F></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7929BA7D78A977FF">3.7-7 <span class="Heading"><code class="code"><Button></code> and <code class="code"><B></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7F4FFA877B775188">3.7-8 <span class="Heading"><code class="code"><Package></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7F531B157D656836">3.7-9 <span class="Heading"><code class="code"><Listing></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X810DEA1E83A57CFE">3.7-10 <span class="Heading"><code class="code"><Log></code> and
<code class="code"><Example></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7F8C4D018346B2CF">3.7-11 <span class="Heading"><code class="code"><Verb></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X8145F6B37C04AA0A">3.8 <span class="Heading">Elements for Mathematical Formulae</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7AA02845868AA533">3.8-1 <span class="Heading"><code class="code"><Math></code>
and <code class="code"><Display></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7ABF42328467E966">3.8-2 <span class="Heading"><code class="code"><M></code></span></a>
</span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap3.html#X7A0D26B180BEDE37">3.9 <span class="Heading">Everything else</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X850E69017945AE3E">3.9-1 <span class="Heading"><code class="code"><Alt></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X85D23A648444069F">3.9-2 <span class="Heading"><code class="code"><Par></code> and
<code class="code"><P></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7A3EF0647B10C1EC">3.9-3 <span class="Heading"><code class="code"><Br></code></span></a>
</span>
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap3.html#X7A81FB717A30B485">3.9-4 <span class="Heading"><code class="code"><Ignore></code></span></a>
</span>
</div></div>
</div>
<h3>3 <span class="Heading">The Document Type Definition</span></h3>
<p>In this chapter we first explain what a <q>document type definition</q> is and then describe <code class="file">gapdoc.dtd</code> in detail. That file together with the current chapter define how a <strong class="pkg">GAPDoc</strong> document has to look like. It can be found in the main directory of the <strong class="pkg">GAPDoc</strong> package and it is reproduced in Appendix <a href="chapB.html#X85366C6480D58C51"><span class="RefLink">B</span></a>.</p>
<p>We do not give many examples in this chapter which is more intended as a formal reference for all <strong class="pkg">GAPDoc</strong> elements. Instead, we provide a separate help book, see <a href="../../../pkg/GAPDoc-1.6.7/example/chap2.html#X7A480B9A795EF264"><span class="RefLink">GAPDoc Example: Various types of text</span></a>. This uses all the constructs introduced in this chapter and you can easily compare the source code and how it looks like in the different output formats. Furthermore recall that many basic things about XML markup were already explained by example in the introductory chapter <a href="chap1.html#X7D4EE663818DA109"><span class="RefLink">1</span></a>.</p>
<p><a id="X7B76F6F786521F6B" name="X7B76F6F786521F6B"></a></p>
<h4>3.1 <span class="Heading">What is a DTD?</span></h4>
<p>A document type definition (DTD) is a formal declaration of how an XML document has to be structured. It is itself structured such that programs that handle documents can read it and treat the documents accordingly. There are for example parsers and validity checkers that use the DTD to validate an XML document, see <a href="chap2.html#X8561F07A81CABDD6"><span class="RefLink">2.1-14</span></a>.</p>
<p>The main thing a DTD does is to specify which elements may occur in documents of a certain document type, how they can be nested, and what attributes they can or must have. So, for each element there is a rule.</p>
<p>Note that a DTD can <em>not</em> ensure that a document which is <q>valid</q> also makes sense to the converters! It only says something about the formal structure of the document.</p>
<p>For the remaining part of this chapter we have divided the elements of <strong class="pkg">GAPDoc</strong> documents into several subsets, each of which will be discussed in one of the next sections.</p>
<p>See the following three subsections to learn by example, how a DTD works. We do not want to be too formal here, but just enable the reader to understand the declarations in <code class="file">gapdoc.dtd</code>. For precise descriptions of the syntax of DTD's see again the official standard in:</p>
<p> <span class="URL"><a href="https://www.xml.com/axml/axml.html">https://www.xml.com/axml/axml.html</a></span></p>
<p><a id="X7DB0F9E57879CC76" name="X7DB0F9E57879CC76"></a></p>
<h4>3.2 <span class="Heading">Overall Document Structure</span></h4>
<p>A <strong class="pkg">GAPDoc</strong> document contains on its top level exactly one element with name <code class="code">Book</code>. This element is declared in the DTD as follows:</p>
<p><a id="X7C7258A57B831934" name="X7C7258A57B831934"></a></p>
<h5>3.2-1 <span class="Heading"><code class="code"><Book></code></span></h5>
<div class="example"><pre>
<!ELEMENT Book (TitlePage,
TableOfContents?,
Body,
Appendix*,
Bibliography?,
TheIndex?)>
<!ATTLIST Book Name CDATA #REQUIRED>
</pre></div>
<p>After the keyword <code class="code">ELEMENT</code> and the name <code class="code">Book</code> there is a list in parentheses. This is a comma separated list of names of elements which can occur (in the given order) in the content of a <code class="code">Book</code> element. Each name in such a list can be followed by one of the characters <q><code class="code">?</code></q>, <q><code class="code">*</code></q> or <q><code class="code">+</code></q>, meaning that the corresponding element can occur zero or one time, an arbitrary number of times, or at least once, respectively. Without such an extra character the corresponding element must occur exactly once. Instead of one name in this list there can also be a list of elements names separated by <q><code class="code">|</code></q> characters, this denotes any element with one of the names (i.e., <q><code class="code">|</code></q> means <q>or</q>).</p>
<p>So, the <code class="code">Book</code> element must contain first a <code class="code">TitlePage</code> element, then an optional <code class="code">TableOfContents</code> element, then a <code class="code">Body</code> element, then zero or more elements of type <code class="code">Appendix</code>, then an optional <code class="code">Bibliography</code> element, and finally an optional element of type <code class="code">TheIndex</code>.</p>
<p>Note that <em>only</em> these elements are allowed in the content of the <code class="code">Book</code> element. No other elements or text is allowed in between. An exception of this is that there may be whitespace between the end tag of one and the start tag of the next element - this should be ignored when the document is processed to some output format. An element like this is called an element with <q>element content</q>.</p>
<p>The second declaration starts with the keyword <code class="code">ATTLIST</code> and the element name <code class="code">Book</code>. After that there is a triple of whitespace separated parameters (in general an arbitrary number of such triples, one for each allowed attribute name). The first (<code class="code">Name</code>) is the name of an attribute for a <code class="code">Book</code> element. The second (<code class="code">CDATA</code>) is always the same for all of our declarations, it means that the value of the attribute consists of <q>character data</q>. The third parameter <code class="code">#REQUIRED</code> means that this attribute must be specified with any <code class="code">Book</code> element. Later we will also see optional attributes which are declared as <code class="code">#IMPLIED</code>.</p>
<p><a id="X842B421A7FBCDD2C" name="X842B421A7FBCDD2C"></a></p>
<h5>3.2-2 <span class="Heading"><code class="code"><TitlePage></code></span></h5>
<div class="example"><pre>
<!ELEMENT TitlePage (Title, Subtitle?, Version?, TitleComment?,
Author+, Date?, Address?, Abstract?, Copyright?,
Acknowledgements? , Colophon? )>
</pre></div>
<p>Within this element information for the title page is collected. Note that more than one author can be specified. The elements must appear in this order because there is no sensible way to specify in a DTD something like <q>the following elements may occur in any order but each exactly once</q>.</p>
<p>Before going on with the other elements inside the <code class="code">Book</code> element we explain the elements for the title page.</p>
<p><a id="X7BCC8E6F79021294" name="X7BCC8E6F79021294"></a></p>
<h5>3.2-3 <span class="Heading"><code class="code"><Title></code></span></h5>
<div class="example"><pre>
<!ELEMENT Title (%Text;)*>
</pre></div>
<p>Here is the last construct you need to understand for reading <code class="file">gapdoc.dtd</code>. The expression <q><code class="code">%Text;</code></q> is a so-called <q>parameter entity</q>. It is something like a macro within the DTD. It is defined as follows:</p>
<div class="example"><pre>
<!ENTITY % Text "%InnerText; | List | Enum | Table">
</pre></div>
<p>This means, that every occurrence of <q><code class="code">%Text;</code></q> in the DTD is replaced by the expression</p>
<div class="example"><pre>%InnerText; | List | Enum | Table
</pre></div>
<p>which is then expanded further because of the following definition:</p>
<div class="example"><pre>
<!ENTITY % InnerText "#PCDATA |
Alt |
Emph | E |
Par | P | Br |
Keyword | K | Arg | A | Quoted | Q | Code | C |
File | F | Button | B | Package |
M | Math | Display |
Example | Listing | Log | Verb |
URL | Email | Homepage | Address | Cite | Label |
Ref | Index" >
</pre></div>
<p>These are the only two parameter entities we are using. They expand to lists of element names which are explained in the sequel <em>and</em> the keyword <code class="code">#PCDATA</code> (concatenated with the <q>or</q> character <q><code class="code">|</code></q>).</p>
<p>So, the element (<code class="code">Title</code>) is of so-called <q>mixed content</q>: It can contain <em>parsed character data</em> which does not contain further markup (<code class="code">#PCDATA</code>) or any of the other above mentioned elements. Mixed content must always have the asterisk qualifier (like in <code class="code">Title</code>) such that any sequence of elements (of the above list) and character data can be contained in a <code class="code">Title</code> element.</p>
<p>The <code class="code">%Text;</code> parameter entity is used in all places in the DTD, where <q>normal text</q> should be allowed, including lists, enumerations, and tables, but <em>no</em> sectioning elements.</p>
<p>The <code class="code">%InnerText;</code> parameter entity is used in all places in the DTD, where <q>inner text</q> should be allowed. This means, that no structures like lists, enumerations, and tables are allowed. This is used for example in headings.</p>
<p><a id="X82E82AF48217CC14" name="X82E82AF48217CC14"></a></p>
<h5>3.2-4 <span class="Heading"><code class="code"><Subtitle></code></span></h5>
<div class="example"><pre>
<!ELEMENT Subtitle (%Text;)*>
</pre></div>
<p>Contains the subtitle of the document.</p>
<p><a id="X876962807DCC52B3" name="X876962807DCC52B3"></a></p>
<h5>3.2-5 <span class="Heading"><code class="code"><Version></code></span></h5>
<div class="example"><pre>
<!ELEMENT Version (#PCDATA|Alt)*>
</pre></div>
<p>Note that the version can only contain character data and no further markup elements (except for <code class="code">Alt</code>, which is necessary to resolve the entities described in <a href="chap2.html#X7BDFF6D37FBED400"><span class="RefLink">2.2-3</span></a>). The converters will <em>not</em> put the word <q>Version</q> in front of the text in this element.</p>
<p><a id="X87E7CD5B79230B90" name="X87E7CD5B79230B90"></a></p>
<h5>3.2-6 <span class="Heading"><code class="code"><TitleComment></code></span></h5>
<div class="example"><pre>
<!ELEMENT TitleComment (%Text;)*>
</pre></div>
<p>Sometimes a title and subtitle are not sufficient to give a rough idea about the content of a package. In this case use this optional element to specify an additional text for the front page of the book. This text should be short, use the <code class="code">Abstract</code> element (see <a href="chap3.html#X833110FE79628313"><span class="RefLink">3.2-10</span></a>) for longer explanations.</p>
<p><a id="X8731459C7E4C56DA" name="X8731459C7E4C56DA"></a></p>
<h5>3.2-7 <span class="Heading"><code class="code"><Author></code></span></h5>
<div class="example"><pre>
<!ELEMENT Author (%Text;)*> <!-- There may be more than one Author! -->
</pre></div>
<p>As noted in the comment there may be more than one element of this type. This element should contain the name of an author and probably an <code class="code">Email</code>-address and/or WWW-<code class="code">Homepage</code> element for this author, see <a href="chap3.html#X8310C4F084CD9DB9"><span class="RefLink">3.5-6</span></a> and <a href="chap3.html#X7D5CC4267D04D7E7"><span class="RefLink">3.5-7</span></a>. You can also specify an individual postal address here, instead of using the <code class="code">Address</code> element described below, see <a href="chap3.html#X7EEF65A07A094F65"><span class="RefLink">3.2-9</span></a>.</p>
<p><a id="X8264A69D7DCDD773" name="X8264A69D7DCDD773"></a></p>
<h5>3.2-8 <span class="Heading"><code class="code"><Date></code></span></h5>
<div class="example"><pre>
<!ELEMENT Date (#PCDATA)>
</pre></div>
<p>Only character data is allowed in this element which gives a date for the document. No automatic formatting is done.</p>
<p><a id="X7EEF65A07A094F65" name="X7EEF65A07A094F65"></a></p>
<h5>3.2-9 <span class="Heading"><code class="code"><Address></code></span></h5>
<div class="example"><pre>
<!ELEMENT Address (#PCDATA|Alt|Br)*>
</pre></div>
<p>This optional element can be used to specify a postal address of the author or the authors. If there are several authors with different addresses then put the <code class="code">Address</code> elements inside the <code class="code">Author</code> elements.</p>
<p>Use the <code class="code">Br</code> element (see <a href="chap3.html#X7A3EF0647B10C1EC"><span class="RefLink">3.9-3</span></a>) to mark the line breaks in the usual formatting of the address on a letter.</p>
<p>Note that often it is not necessary to use this element because a postal address is easy to find via a link to a personal web page.</p>
<p><a id="X833110FE79628313" name="X833110FE79628313"></a></p>
<h5>3.2-10 <span class="Heading"><code class="code"><Abstract></code></span></h5>
<div class="example"><pre>
<!ELEMENT Abstract (%Text;)*>
</pre></div>
<p>This element contains an abstract of the whole book.</p>
<p><a id="X84BBD8307E08E62F" name="X84BBD8307E08E62F"></a></p>
<h5>3.2-11 <span class="Heading"><code class="code"><Copyright></code></span></h5>
<div class="example"><pre>
<!ELEMENT Copyright (%Text;)*>
</pre></div>
<p>This element is used for the copyright notice. Note the <code class="code">&copyright;</code> entity as described in section <a href="chap2.html#X7BDFF6D37FBED400"><span class="RefLink">2.2-3</span></a>.</p>
<p><a id="X8143972D7C17838E" name="X8143972D7C17838E"></a></p>
<h5>3.2-12 <span class="Heading"><code class="code"><Acknowledgements></code></span></h5>
<div class="example"><pre>
<!ELEMENT Acknowledgements (%Text;)*>
</pre></div>
<p>This element contains the acknowledgements.</p>
<p><a id="X7C09A3398059D18C" name="X7C09A3398059D18C"></a></p>
<h5>3.2-13 <span class="Heading"><code class="code"><Colophon></code></span></h5>
<div class="example"><pre>
<!ELEMENT Colophon (%Text;)*>
</pre></div>
<p>The <q>colophon</q> page is used to say something about the history of a document.</p>
<p><a id="X7E97263A83DC26E9" name="X7E97263A83DC26E9"></a></p>
<h5>3.2-14 <span class="Heading"><code class="code"><TableOfContents></code></span></h5>
<div class="example"><pre>
<!ELEMENT TableOfContents EMPTY>
</pre></div>
<p>This element may occur in the <code class="code">Book</code> element after the <code class="code">TitlePage</code> element. If it is present, a table of contents is generated and inserted into the document. Note that because this element is declared to be <code class="code">EMPTY</code> one can use the abbreviation</p>
<div class="example"><pre>
<TableOfContents/>
</pre></div>
<p>to denote this empty element.</p>
<p><a id="X84F3DF21786A8751" name="X84F3DF21786A8751"></a></p>
<h5>3.2-15 <span class="Heading"><code class="code"><Bibliography></code>
</span></h5>
<div class="example"><pre>
<!ELEMENT Bibliography EMPTY>
<!ATTLIST Bibliography Databases CDATA #REQUIRED
Style CDATA #IMPLIED>
</pre></div>
<p>This element may occur in the <code class="code">Book</code> element after the last <code class="code">Appendix</code> element. If it is present, a bibliography section is generated and inserted into the document. The attribute <code class="code">Databases</code> must be specified, the names of several data files can be specified, separated by commas.</p>
<p>Two kinds of files can be specified in <code class="code">Databases</code>: The first are BibTeX files as defined in <a href="chapBib.html#biBLa85">[Lam85, Appendix B]</a>. Such files must have a name with extension <code class="file">.bib</code>, and in <code class="code">Databases</code> the name must be given <em>without</em> this extension. Note that such <code class="file">.bib</code>-files should be in latin1-encoding (or ASCII-encoding). The second are files in BibXMLext format as defined in Section <a href="chap7.html#X7FB8F6BD80D859D1"><span class="RefLink">7.2</span></a>. These files must have an extension <code class="file">.xml</code> and in <code class="code">Databases</code> the <em>full</em> name must be specified.</p>
<p>We suggest to use the BibXMLext format because it allows to produce potentially nicer bibliography entries in text and HTML documents.</p>
<p>A bibliography style may be specified with the <code class="code">Style</code> attribute. The optional <code class="code">Style</code> attribute (for LaTeX output of the document) must also be specified without the <code class="file">.bst</code> extension (the default is <code class="code">alpha</code>). See also section <a href="chap3.html#X851DE9D279D8FB04"><span class="RefLink">3.5-3</span></a> for a description of the <code class="code">Cite</code> element which is used to include bibliography references into the text.</p>
<p><a id="X7C53615A8477F1E5" name="X7C53615A8477F1E5"></a></p>
<h5>3.2-16 <span class="Heading"><code class="code"><TheIndex></code></span></h5>
<div class="example"><pre><!ELEMENT TheIndex EMPTY></pre></div>
<p>This element may occur in the <code class="code">Book</code> element after the <code class="code">Bibliography</code> element. If it is present, an index is generated and inserted into the document. There are elements in <strong class="pkg">GAPDoc</strong> which implicitly generate index entries (e.g., <code class="code">Func</code> (<a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>)) and there is an element <code class="code">Index</code> (<a href="chap3.html#X811042BA78843777"><span class="RefLink">3.5-4</span></a>) for explicitly adding index entries.</p>
<p><a id="X80E2AD7481DD69D9" name="X80E2AD7481DD69D9"></a></p>
<h4>3.3 <span class="Heading">Sectioning Elements</span></h4>
<p>A <strong class="pkg">GAPDoc</strong> book is divided into <em>chapters</em>, <em>sections</em>, and <em>subsections</em>. The idea is of course, that a chapter consists of sections, which in turn consist of subsections. However for the sake of flexibility, the rules are not too restrictive. Firstly, text is allowed everywhere in the body of the document (and not only within sections). Secondly, the chapter level may be omitted. The exact rules are described below.</p>
<p><em>Appendices</em> are a flavor of chapters, occurring after all regular chapters. There is a special type of subsection called <q><code class="code">ManSection</code></q>. This is a subsection devoted to the description of a function, operation or variable. It is analogous to a manpage in the UNIX environment. Usually each function, operation, method, and so on should have its own <code class="code">ManSection</code>.</p>
<p>Cross referencing is done on the level of <code class="code">Subsection</code>s, respectively <code class="code">ManSection</code>s. The topics in <strong class="pkg">GAP</strong>'s online help are also pointing to subsections. So, they should not be too long.</p>
<p>We start our description of the sectioning elements <q>top-down</q>:</p>
<p><a id="X7B38415687510D0A" name="X7B38415687510D0A"></a></p>
<h5>3.3-1 <span class="Heading"><code class="code"><Body></code></span></h5>
<p>The <code class="code">Body</code> element marks the main part of the document. It must occur after the <code class="code">TableOfContents</code> element. There is a big difference between <em>inside</em> and <em>outside</em> of this element: Whereas regular text is allowed nearly everywhere in the <code class="code">Body</code> element and its subelements, this is not true for the <em>outside</em>. This has also implications on the handling of whitespace. <em>Outside</em> superfluous whitespace is usually ignored when it occurs between elements. <em>Inside</em> of the <code class="code">Body</code> element whitespace matters because character data is allowed nearly everywhere. Here is the definition in the DTD:</p>
<div class="example"><pre>
<!ELEMENT Body ( %Text;| Chapter | Section )*>
</pre></div>
<p>The fact that <code class="code">Chapter</code> and <code class="code">Section</code> elements are allowed here leads to the possibility to omit the chapter level entirely in the document. For a description of <code class="code">%Text;</code> see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>.</p>
<p>(Remark: The purpose of this element is to make sure that a <em>valid</em> <strong class="pkg">GAPDoc</strong> document has a correct overall structure, which is only possible when the top element <code class="code">Book</code> has element content.)</p>
<p><a id="X7A86B2BA7D688B6B" name="X7A86B2BA7D688B6B"></a></p>
<h5>3.3-2 <span class="Heading"><code class="code"><Chapter></code></span></h5>
<div class="example"><pre>
<!ELEMENT Chapter (%Text;| Heading | Section)*>
<!ATTLIST Chapter Label CDATA #IMPLIED> <!-- For reference purposes -->
</pre></div>
<p>A <code class="code">Chapter</code> element can have a <code class="code">Label</code> attribute, such that this chapter can be referenced later on with a <code class="code">Ref</code> element (see section <a href="chap3.html#X8656F2338007406E"><span class="RefLink">3.5-1</span></a>). Note that you have to specify a label to reference the chapter as there is no automatic labelling!</p>
<p><code class="code">Chapter</code> elements can contain text (for a description of <code class="code">%Text;</code> see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>), <code class="code">Section</code> elements, and <code class="code">Heading</code> elements.</p>
<p>The following <em>additional</em> rule cannot be stated in the DTD because we want a <code class="code">Chapter</code> element to have mixed content. There must be <em>exactly one</em> <code class="code">Heading</code> element in the <code class="code">Chapter</code> element, containing the heading of the chapter. Here is its definition:</p>
<p><a id="X79825E1C821D0B79" name="X79825E1C821D0B79"></a></p>
<h5>3.3-3 <span class="Heading"><code class="code"><Heading></code></span></h5>
<div class="example"><pre>
<!ELEMENT Heading (%InnerText;)*>
</pre></div>
<p>This element is used for headings in <code class="code">Chapter</code>, <code class="code">Section</code>, <code class="code">Subsection</code>, and <code class="code">Appendix</code> elements. It may only contain <code class="code">%InnerText;</code> (for a description see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>).</p>
<p>Each of the mentioned sectioning elements must contain exactly one direct <code class="code">Heading</code> element (i.e., one which is not contained in another sectioning element).</p>
<p><a id="X7C701B2779767556" name="X7C701B2779767556"></a></p>
<h5>3.3-4 <span class="Heading"><code class="code"><Appendix></code></span></h5>
<div class="example"><pre>
<!ELEMENT Appendix (%Text;| Heading | Section)*>
<!ATTLIST Appendix Label CDATA #IMPLIED> <!-- For reference purposes -->
</pre></div>
<p>The <code class="code">Appendix</code> element behaves exactly like a <code class="code">Chapter</code> element (see <a href="chap3.html#X7A86B2BA7D688B6B"><span class="RefLink">3.3-2</span></a>) except for the position within the document and the numbering. While chapters are counted with numbers (1., 2., 3., ...) the appendices are counted with capital letters (A., B., ...).</p>
<p>Again there is an optional <code class="code">Label</code> attribute used for references.</p>
<p><a id="X844DC2B47FB37339" name="X844DC2B47FB37339"></a></p>
<h5>3.3-5 <span class="Heading"><code class="code"><Section></code></span></h5>
<div class="example"><pre>
<!ELEMENT Section (%Text;| Heading | Subsection | ManSection)*>
<!ATTLIST Section Label CDATA #IMPLIED> <!-- For reference purposes -->
</pre></div>
<p>A <code class="code">Section</code> element can have a <code class="code">Label</code> attribute, such that this section can be referenced later on with a <code class="code">Ref</code> element (see section <a href="chap3.html#X8656F2338007406E"><span class="RefLink">3.5-1</span></a>). Note that you have to specify a label to reference the section as there is no automatic labelling!</p>
<p><code class="code">Section</code> elements can contain text (for a description of <code class="code">%Text;</code> see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>), <code class="code">Heading</code> elements, and subsections.</p>
<p>There must be exactly one direct <code class="code">Heading</code> element in a <code class="code">Section</code> element, containing the heading of the section.</p>
<p>Note that a subsection is either a <code class="code">Subsection</code> element or a <code class="code">ManSection</code> element.</p>
<p><a id="X803ACA187E292969" name="X803ACA187E292969"></a></p>
<h5>3.3-6 <span class="Heading"><code class="code"><Subsection></code></span></h5>
<div class="example"><pre>
<!ELEMENT Subsection (%Text;| Heading)*>
<!ATTLIST Subsection Label CDATA #IMPLIED> <!-- For reference purposes -->
</pre></div>
<p>The <code class="code">Subsection</code> element can have a <code class="code">Label</code> attribute, such that this subsection can be referenced later on with a <code class="code">Ref</code> element (see section <a href="chap3.html#X8656F2338007406E"><span class="RefLink">3.5-1</span></a>). Note that you have to specify a label to reference the subsection as there is no automatic labelling!</p>
<p><code class="code">Subsection</code> elements can contain text (for a description of <code class="code">%Text;</code> see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>), and <code class="code">Heading</code> elements.</p>
<p>There must be exactly one <code class="code">Heading</code> element in a <code class="code">Subsection</code> element, containing the heading of the subsection.</p>
<p>Another type of subsection is a <code class="code">ManSection</code>, explained now:</p>
<p><a id="X877B8B7C7EDD09E9" name="X877B8B7C7EDD09E9"></a></p>
<h4>3.4 <span class="Heading">ManSection–a special kind of subsection</span></h4>
<p><code class="code">ManSection</code>s are intended to describe a function, operation, method, variable, or some other technical instance. It is analogous to a manpage in the UNIX environment.</p>
<p><a id="X8375D9CC8672A1D5" name="X8375D9CC8672A1D5"></a></p>
<h5>3.4-1 <span class="Heading"><code class="code"><ManSection></code></span></h5>
<div class="example"><pre>
<!ELEMENT ManSection ( Heading?,
((Func, Returns?) | (Oper, Returns?) |
(Meth, Returns?) | (Filt, Returns?) |
(Prop, Returns?) | (Attr, Returns?) |
(Constr, Returns?) |
Var | Fam | InfoClass)+, Description )>
<!ATTLIST ManSection Label CDATA #IMPLIED> <!-- For reference purposes -->
<!ELEMENT Returns (%Text;)*>
<!ELEMENT Description (%Text;)*>
</pre></div>
<p>The <code class="code">ManSection</code> element can have a <code class="code">Label</code> attribute, such that this subsection can be referenced later on with a <code class="code">Ref</code> element (see section <a href="chap3.html#X8656F2338007406E"><span class="RefLink">3.5-1</span></a>). But this is probably rarely necessary because the elements <code class="code">Func</code> and so on (explained below) generate automatically labels for cross referencing.</p>
<p>The content of a <code class="code">ManSection</code> element is one or more elements describing certain items in <strong class="pkg">GAP</strong>, each of them optionally followed by a <code class="code">Returns</code> element, followed by a <code class="code">Description</code> element, which contains <code class="code">%Text;</code> (see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>) describing it. (Remember to include examples in the description as often as possible, see <a href="chap3.html#X810DEA1E83A57CFE"><span class="RefLink">3.7-10</span></a>). The classes of items <strong class="pkg">GAPDoc</strong> knows of are: functions (<code class="code">Func</code>), operations (<code class="code">Oper</code>), constructors (<code class="code">Constr</code>), methods (<code class="code">Meth</code>), filters (<code class="code">Filt</code>), properties (<code class="code">Prop</code>), attributes (<code class="code">Attr</code>), variables (<code class="code">Var</code>), families (<code class="code">Fam</code>), and info classes (<code class="code">InfoClass</code>). One <code class="code">ManSection</code> should only describe several of such items when these are very closely related.</p>
<p>Each element for an item corresponding to a <strong class="pkg">GAP</strong> function can be followed by a <code class="code">Returns</code> element. In output versions of the document the string <q>Returns: </q> will be put in front of the content text. The text in the <code class="code">Returns</code> element should usually be a short hint about the type of object returned by the function. This is intended to give a good mnemonic for the use of a function (together with a good choice of names for the formal arguments).</p>
<p><code class="code">ManSection</code>s are also sectioning elements which count as subsections. Usually there should be no <code class="code">Heading</code>-element in a <code class="code">ManSection</code>, in that case a heading is generated automatically from the first <code class="code">Func</code>-like element. Sometimes this default behaviour does not look appropriate, for example when there are several <code class="code">Func</code>-like elements. For such cases an optional <code class="code">Heading</code> is allowed.</p>
<p><a id="X7C41A7B5845205C4" name="X7C41A7B5845205C4"></a></p>
<h5>3.4-2 <span class="Heading"><code class="code"><Func></code></span></h5>
<div class="example"><pre>
<!ELEMENT Func EMPTY>
<!ATTLIST Func Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
</pre></div>
<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of a function. The <code class="code">Name</code> attribute is required and its value is the name of the function. The value of the <code class="code">Arg</code> attribute (also required) contains the full list of arguments including optional parts, which are denoted by square brackets. The argument names can be separated by whitespace, commas or the square brackets for the optional arguments, like <code class="code">"grp[, elm]"</code> or <code class="code">"xx[y[z] ]"</code>. If <strong class="pkg">GAP</strong> options are used, this can be followed by a colon <code class="code">:</code> and one or more assignments, like <code class="code">"n[, r]: tries := 100"</code>.</p>
<p>The name of the function is also used as label for cross referencing. When the name of the function appears in the text of the document it should <em>always</em> be written with the <code class="code">Ref</code> element, see <a href="chap3.html#X8656F2338007406E"><span class="RefLink">3.5-1</span></a>. This allows to use a unique typesetting style for function names and automatic cross referencing.</p>
<p>If the optional <code class="code">Label</code> attribute is given, it is appended (with a colon <code class="code">:</code> in between) to the name of the function for cross referencing purposes. The text of the label can also appear in the document text. So, it should be a kind of short explanation.</p>
<div class="example"><pre>
<Func Arg="x[, y]" Name="LibFunc" Label="for my objects"/>
</pre></div>
<p>The optional <code class="code">Comm</code> attribute should be a short description of the function, usually at most one line long (this is currently nowhere used).</p>
<p>This element automatically produces an index entry with the name of the function and, if present, the text of the <code class="code">Label</code> attribute as subentry (see also <a href="chap3.html#X7C53615A8477F1E5"><span class="RefLink">3.2-16</span></a> and <a href="chap3.html#X811042BA78843777"><span class="RefLink">3.5-4</span></a>).</p>
<p><a id="X7A15825E818A81CD" name="X7A15825E818A81CD"></a></p>
<h5>3.4-3 <span class="Heading"><code class="code"><Oper></code></span></h5>
<div class="example"><pre>
<!ELEMENT Oper EMPTY>
<!ATTLIST Oper Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
</pre></div>
<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of an operation. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>).</p>
<p>Note that multiple descriptions of the same operation may occur in a document because there may be several declarations in <strong class="pkg">GAP</strong>. Furthermore there may be several <code class="code">ManSection</code>s for methods of this operation (see <a href="chap3.html#X81196E2B7F286A01"><span class="RefLink">3.4-5</span></a>) which also use the same name. For reference purposes these must be distinguished by different <code class="code">Label</code> attributes.</p>
<p><a id="X7FBFD7A3786C7CAB" name="X7FBFD7A3786C7CAB"></a></p>
<h5>3.4-4 <span class="Heading"><code class="code"><Constr></code></span></h5>
<div class="example"><pre>
<!ELEMENT Constr EMPTY>
<!ATTLIST Constr Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
</pre></div>
<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of a constructor. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>).</p>
<p>Note that multiple descriptions of the same constructor may occur in a document because there may be several declarations in <strong class="pkg">GAP</strong>. Furthermore there may be several <code class="code">ManSection</code>s for methods of this constructor (see <a href="chap3.html#X81196E2B7F286A01"><span class="RefLink">3.4-5</span></a>) which also use the same name. For reference purposes these must be distinguished by different <code class="code">Label</code> attributes.</p>
<p><a id="X81196E2B7F286A01" name="X81196E2B7F286A01"></a></p>
<h5>3.4-5 <span class="Heading"><code class="code"><Meth></code></span></h5>
<div class="example"><pre>
<!ELEMENT Meth EMPTY>
<!ATTLIST Meth Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
</pre></div>
<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of a method. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>).</p>
<p>Frequently, an operation is implemented by several different methods. Therefore it seems to be interesting to document them independently. This is possible by using the same method name in different <code class="code">ManSection</code>s. It is however required that these subsections and those describing the corresponding operation are distinguished by different <code class="code">Label</code> attributes.</p>
<p><a id="X7D8D2C38828D5854" name="X7D8D2C38828D5854"></a></p>
<h5>3.4-6 <span class="Heading"><code class="code"><Filt></code></span></h5>
<div class="example"><pre>
<!ELEMENT Filt EMPTY>
<!ATTLIST Filt Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #IMPLIED
Comm CDATA #IMPLIED
Type CDATA #IMPLIED>
</pre></div>
<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of a filter. The first four attributes are used in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>), except that the <code class="code">Arg</code> attribute is optional.</p>
<p>The <code class="code">Type</code> attribute can be any string, but it is thought to be something like <q><code class="code">Category</code></q> or <q><code class="code">Representation</code></q>.</p>
<p><a id="X7D6400A67C30B752" name="X7D6400A67C30B752"></a></p>
<h5>3.4-7 <span class="Heading"><code class="code"><Prop></code></span></h5>
<div class="example"><pre>
<!ELEMENT Prop EMPTY>
<!ATTLIST Prop Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
</pre></div>
<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of a property. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>).</p>
<p><a id="X78CEEC5986987A97" name="X78CEEC5986987A97"></a></p>
<h5>3.4-8 <span class="Heading"><code class="code"><Attr></code></span></h5>
<div class="example"><pre>
<!ELEMENT Attr EMPTY>
<!ATTLIST Attr Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
</pre></div>
<p>This element is used within a <code class="code">ManSection</code> element to specify the usage of an attribute (in <strong class="pkg">GAP</strong>). The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>).</p>
<p><a id="X7C3AACBE7BC6AABF" name="X7C3AACBE7BC6AABF"></a></p>
<h5>3.4-9 <span class="Heading"><code class="code"><Var></code></span></h5>
<div class="example"><pre>
<!ELEMENT Var EMPTY>
<!ATTLIST Var Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>
</pre></div>
<p>This element is used within a <code class="code">ManSection</code> element to document a global variable. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>) except that there is no <code class="code">Arg</code> attribute.</p>
<p><a id="X85EE992E7FED2FE6" name="X85EE992E7FED2FE6"></a></p>
<h5>3.4-10 <span class="Heading"><code class="code"><Fam></code></span></h5>
<div class="example"><pre>
<!ELEMENT Fam EMPTY>
<!ATTLIST Fam Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>
</pre></div>
<p>This element is used within a <code class="code">ManSection</code> element to document a family. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>) except that there is no <code class="code">Arg</code> attribute.</p>
<p><a id="X78F0D4D1811E5BAE" name="X78F0D4D1811E5BAE"></a></p>
<h5>3.4-11 <span class="Heading"><code class="code"><InfoClass></code></span></h5>
<div class="example"><pre>
<!ELEMENT InfoClass EMPTY>
<!ATTLIST InfoClass Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>
</pre></div>
<p>This element is used within a <code class="code">ManSection</code> element to document an info class. The attributes are used exactly in the same way as in the <code class="code">Func</code> element (see <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>) except that there is no <code class="code">Arg</code> attribute.</p>
<p><a id="X78595FB585569617" name="X78595FB585569617"></a></p>
<h4>3.5 <span class="Heading">Cross Referencing and Citations</span></h4>
<p>Cross referencing in the <strong class="pkg">GAPDoc</strong> system is somewhat different to the usual LaTeX cross referencing in so far, that a reference knows <q>which type of object</q> it is referencing. For example a <q>reference to a function</q> is distinguished from a <q>reference to a chapter</q>. The idea of this is, that the markup must contain this information such that the converters can produce better output. The HTML converter can for example typeset a function reference just as the name of the function with a link to the description of the function, or a chapter reference as a number with a link in the other case.</p>
<p>Referencing is done with the <code class="code">Ref</code> element:</p>
<p><a id="X8656F2338007406E" name="X8656F2338007406E"></a></p>
<h5>3.5-1 <span class="Heading"><code class="code"><Ref></code></span></h5>
<div class="example"><pre>
<!ELEMENT Ref EMPTY>
<!ATTLIST Ref Func CDATA #IMPLIED
Oper CDATA #IMPLIED
Constr CDATA #IMPLIED
Meth CDATA #IMPLIED
Filt CDATA #IMPLIED
Prop CDATA #IMPLIED
Attr CDATA #IMPLIED
Var CDATA #IMPLIED
Fam CDATA #IMPLIED
InfoClass CDATA #IMPLIED
Chap CDATA #IMPLIED
Sect CDATA #IMPLIED
Subsect CDATA #IMPLIED
Appendix CDATA #IMPLIED
Text CDATA #IMPLIED
Label CDATA #IMPLIED
BookName CDATA #IMPLIED
Style (Text | Number) #IMPLIED> <!-- normally automatic -->
</pre></div>
<p>The <code class="code">Ref</code> element is defined to be <code class="code">EMPTY</code>. If one of the attributes <code class="code">Func</code>, <code class="code">Oper</code>, <code class="code">Constr</code>, <code class="code">Meth</code>, <code class="code">Prop</code>, <code class="code">Attr</code>, <code class="code">Var</code>, <code class="code">Fam</code>, <code class="code">InfoClass</code>, <code class="code">Chap</code>, <code class="code">Sect</code>, <code class="code">Subsect</code>, <code class="code">Appendix</code> is given then there must be exactly one of these, making the reference one to the corresponding object. The <code class="code">Label</code> attribute can be specified in addition to make the reference unique, for example if more than one method with a given name is present. (Note that there is no way to specify in the DTD that exactly one of the first listed attributes must be given, this is an additional rule.)</p>
<p>A reference to a <code class="code">Label</code> element defined below (see <a href="chap3.html#X7C85CA5484344DB5"><span class="RefLink">3.5-2</span></a>) is done by giving the <code class="code">Label</code> attribute and optionally the <code class="code">Text</code> attribute. If the <code class="code">Text</code> attribute is present its value is typeset in place of the <code class="code">Ref</code> element, if linking is possible (for example in HTML). If this is not possible, the section number is typeset. This type of reference is also used for references to tables (see <a href="chap3.html#X7F9CAA577EB4070B"><span class="RefLink">3.6-5</span></a>).</p>
<p>An external reference into another book can be specified by using the <code class="code">BookName</code> attribute. In this case the <code class="code">Label</code> attribute or, if this is not given, the function or section like attribute, is used to resolve the reference. The generated reference points to the first hit when asking <q>?book name: label</q> inside <strong class="pkg">GAP</strong>.</p>
<p>The optional attribute <code class="code">Style</code> can take only the values <code class="code">Text</code> and <code class="code">Number</code>. It can be used with references to sectioning units and it gives a hint to the converter programs, whether an explicit section number is generated or text. Normally all references to sections generate numbers and references to a <strong class="pkg">GAP</strong> object generate the name of the corresponding object with some additional link or sectioning information, which is the behavior of <code class="code">Style="Text"</code>. In case <code class="code">Style="Number"</code> in all cases an explicit section number is generated. So</p>
<div class="example"><pre>
<Ref Subsect="Func" Style="Text"/> described in section
<Ref Subsect="Func" Style="Number"/>
</pre></div>
<p>produces: <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink"><span class="Heading"><code class="code"><Func></code></span></span></a> described in section <a href="chap3.html#X7C41A7B5845205C4"><span class="RefLink">3.4-2</span></a>.</p>
<p><a id="X7C85CA5484344DB5" name="X7C85CA5484344DB5"></a></p>
<h5>3.5-2 <span class="Heading"><code class="code"><Label></code></span></h5>
<div class="example"><pre>
<!ELEMENT Label EMPTY>
<!ATTLIST Label Name CDATA #REQUIRED>
</pre></div>
<p>This element is used to define a label for referencing a certain position in the document, if this is possible. If an exact reference is not possible (like in a printed version of the document) a reference to the corresponding subsection is generated. The value of the <code class="code">Name</code> attribute must be unique under all <code class="code">Label</code> elements.</p>
<p><a id="X851DE9D279D8FB04" name="X851DE9D279D8FB04"></a></p>
<h5>3.5-3 <span class="Heading"><code class="code"><Cite></code></span></h5>
<div class="example"><pre>
<!ELEMENT Cite EMPTY>
<!ATTLIST Cite Key CDATA #REQUIRED
Where CDATA #IMPLIED>
</pre></div>
<p>This element is for bibliography citations. It is <code class="code">EMPTY</code> by definition. The attribute <code class="code">Key</code> is the key for a lookup in a BibTeX database that has to be specified in the <code class="code">Bibliography</code> element (see <a href="chap3.html#X84F3DF21786A8751"><span class="RefLink">3.2-15</span></a>). The value of the <code class="code">Where</code> attribute specifies the position in the document as in the corresponding LaTeX syntax <code class="code">\cite[Where value]{Key value}</code>.</p>
<p><a id="X811042BA78843777" name="X811042BA78843777"></a></p>
<h5>3.5-4 <span class="Heading"><code class="code"><Index></code></span></h5>
<div class="example"><pre>
<!ELEMENT Index (%InnerText;|Subkey)*>
<!ATTLIST Index Key CDATA #IMPLIED
Subkey CDATA #IMPLIED>
<!ELEMENT Subkey (%InnerText;)*>
</pre></div>
<p>This element generates an index entry. The content of the element is typeset in the index. It can optionally contain a <code class="code">Subkey</code> element. If one or both of the attributes <code class="code">Key</code> and <code class="code">Subkey</code> are given, then the attribute values are used for sorting the index entries. Otherwise the content itself is used for sorting. The attributes should be used when the content contains markup. Note that all <code class="code">Func</code> and similar elements automatically generate index entries. If the <code class="code">TheIndex</code> element (<a href="chap3.html#X7C53615A8477F1E5"><span class="RefLink">3.2-16</span></a>) is not present in the document all <code class="code">Index</code> elements are ignored.</p>
<p><a id="X81B3E46F839E1C5B" name="X81B3E46F839E1C5B"></a></p>
<h5>3.5-5 <span class="Heading"><code class="code"><URL></code></span></h5>
<div class="example"><pre>
<!ELEMENT URL (#PCDATA|Alt|Link|LinkText)*> <!-- Link, LinkText
variant for case where text needs further markup -->
<!ATTLIST URL Text CDATA #IMPLIED> <!-- This is for output formats
that have links like HTML -->
<!ELEMENT Link (%InnerText;)*> <!-- the URL -->
<!ELEMENT LinkText (%InnerText;)*> <!-- text for links, can contain markup -->
</pre></div>
<p>This element is for references into the internet. It specifies an URL and optionally a text which can be used for a link (like in HTML or PDF versions of the document). This can be specified in two ways: Either the URL is given as element content and the text is given in the optional <code class="code">Text</code> attribute (in this case the text cannot contain further markup), or the element contains the two elements <code class="code">Link</code> and <code class="code">LinkText</code> which in turn contain the URL and the text, respectively. The default value for the text is the URL itself.</p>
<p><a id="X8310C4F084CD9DB9" name="X8310C4F084CD9DB9"></a></p>
<h5>3.5-6 <span class="Heading"><code class="code"><Email></code></span></h5>
<div class="example"><pre>
<!ELEMENT Email (#PCDATA|Alt|Link|LinkText)*>
</pre></div>
<p>This element type is the special case of an URL specifying an email address. The content of the element should be the email address without any prefix like <q><code class="code">mailto:</code></q>. This address is typeset by all converters, also without any prefix. In the case of an output document format like HTML the converter can produce a link with a <q><code class="code">mailto:</code></q> prefix.</p>
<p><a id="X7D5CC4267D04D7E7" name="X7D5CC4267D04D7E7"></a></p>
<h5>3.5-7 <span class="Heading"><code class="code"><Homepage></code></span></h5>
<div class="example"><pre>
<!ELEMENT Homepage (#PCDATA|Alt|Link|LinkText)*>
</pre></div>
<p>This element type is the special case of an URL specifying a WWW-homepage.</p>
<p><a id="X840099DF83823686" name="X840099DF83823686"></a></p>
<h4>3.6 <span class="Heading">Structural Elements like Lists</span></h4>
<p>The <strong class="pkg">GAPDoc</strong> system offers some limited access to structural elements like lists, enumerations, and tables. Although it is possible to use all LaTeX constructs one always has to think about other output formats. The elements in this section are guaranteed to produce something reasonable in all output formats.</p>
<p><a id="X785183F67DA402A0" name="X785183F67DA402A0"></a></p>
<h5>3.6-1 <span class="Heading"><code class="code"><List></code></span></h5>
<div class="example"><pre>
<!ELEMENT List ( ((Mark,Item)|Item)+ )>
<!ATTLIST List Only CDATA #IMPLIED
Not CDATA #IMPLIED>
</pre></div>
<p>This element produces a list. Each item in the list corresponds to an <code class="code">Item</code> element. Every <code class="code">Item</code> element is optionally preceded by a <code class="code">Mark</code> element. The content of this is used as a marker for the item. Note that this marker can be a whole word or even a sentence. It will be typeset in some emphasized fashion and most converters will provide some indentation for the rest of the item.</p>
<p>The <code class="code">Only</code> and <code class="code">Not</code> attributes can be used to specify, that the list is included into the output by only one type of converter (<code class="code">Only</code>) or all but one type of converter (<code class="code">Not</code>). Of course at most one of the two attributes may occur in one element. The following values are allowed as of now: <q><code class="code">LaTeX</code></q>, <q><code class="code">HTML</code></q>, and <q><code class="code">Text</code></q>. See also the <code class="code">Alt</code> element in <a href="chap3.html#X850E69017945AE3E"><span class="RefLink">3.9-1</span></a> for more about text alternatives for certain converters.</p>
<p><a id="X7B1545A9797442DC" name="X7B1545A9797442DC"></a></p>
<h5>3.6-2 <span class="Heading"><code class="code"><Mark></code></span></h5>
<div class="example"><pre>
<!ELEMENT Mark ( %InnerText;)*>
</pre></div>
<p>This element is used in the <code class="code">List</code> element to mark items. See <a href="chap3.html#X785183F67DA402A0"><span class="RefLink">3.6-1</span></a> for an explanation.</p>
<p><a id="X86C204987AB4B13D" name="X86C204987AB4B13D"></a></p>
<h5>3.6-3 <span class="Heading"><code class="code"><Item></code></span></h5>
<div class="example"><pre>
<!ELEMENT Item ( %Text;)*>
</pre></div>
<p>This element is used in the <code class="code">List</code>, <code class="code">Enum</code>, and <code class="code">Table</code> elements to specify the items. See sections <a href="chap3.html#X785183F67DA402A0"><span class="RefLink">3.6-1</span></a>, <a href="chap3.html#X78A52B00846562DE"><span class="RefLink">3.6-4</span></a>, and <a href="chap3.html#X7F9CAA577EB4070B"><span class="RefLink">3.6-5</span></a> for further information.</p>
<p><a id="X78A52B00846562DE" name="X78A52B00846562DE"></a></p>
<h5>3.6-4 <span class="Heading"><code class="code"><Enum></code></span></h5>
<div class="example"><pre>
<!ELEMENT Enum ( Item+ )>
<!ATTLIST Enum Only CDATA #IMPLIED
Not CDATA #IMPLIED>
</pre></div>
<p>This element is used like the <code class="code">List</code> element (see <a href="chap3.html#X785183F67DA402A0"><span class="RefLink">3.6-1</span></a>) except that the items must not have marks attached to them. Instead, the items are numbered automatically. The same comments about the <code class="code">Only</code> and <code class="code">Not</code> attributes as above apply.</p>
<p><a id="X7F9CAA577EB4070B" name="X7F9CAA577EB4070B"></a></p>
<h5>3.6-5 <span class="Heading"><code class="code"><Table></code></span></h5>
<div class="example"><pre>
<!ELEMENT Table ( Caption?, (Row | HorLine)+ )>
<!ATTLIST Table Label CDATA #IMPLIED
Only CDATA #IMPLIED
Not CDATA #IMPLIED
Align CDATA #REQUIRED>
<!-- We allow | and l,c,r, nothing else -->
<!ELEMENT Row ( Item+ )>
<!ELEMENT HorLine EMPTY>
<!ELEMENT Caption ( %InnerText;)*>
</pre></div>
<p>A table in <strong class="pkg">GAPDoc</strong> consists of an optional <code class="code">Caption</code> element followed by a sequence of <code class="code">Row</code> and <code class="code">HorLine</code> elements. A <code class="code">HorLine</code> element produces a horizontal line in the table. A <code class="code">Row</code> element consists of a sequence of <code class="code">Item</code> elements as they also occur in <code class="code">List</code> and <code class="code">Enum</code> elements. The <code class="code">Only</code> and <code class="code">Not</code> attributes have the same functionality as described in the <code class="code">List</code> element in <a href="chap3.html#X785183F67DA402A0"><span class="RefLink">3.6-1</span></a>.</p>
<p>The <code class="code">Align</code> attribute is written like a LaTeX tabular alignment specifier but only the letters <q><code class="code">l</code></q>, <q><code class="code">r</code></q>, <q><code class="code">c</code></q>, and <q><code class="code">|</code></q> are allowed meaning left alignment, right alignment, centered alignment, and a vertical line as delimiter between columns respectively.</p>
<p>If the <code class="code">Label</code> attribute is there, one can reference the table with the <code class="code">Ref</code> element (see <a href="chap3.html#X8656F2338007406E"><span class="RefLink">3.5-1</span></a>) using its <code class="code">Label</code> attribute.</p>
<p>Usually only simple tables should be used. If you want a complicated table in the LaTeX output you should provide alternatives for text and HTML output. Note that in HTML-4.0 there is no possibility to interpret the <q><code class="code">|</code></q> column separators and <code class="code">HorLine</code> elements as intended. There are lines between all columns and rows or no lines at all.</p>
<p><a id="X7CA1E1327AFBA578" name="X7CA1E1327AFBA578"></a></p>
<h4>3.7 <span class="Heading">Types of Text</span></h4>
<p>This section covers the markup of text. Various types of <q>text</q> exist. The following elements are used in the <strong class="pkg">GAPDoc</strong> system to mark them. They mostly come in pairs, one long name which is easier to remember and a shortcut to make the markup <q>lighter</q>.</p>
<p>Most of the following elements are thought to contain only character data and no further markup elements. It is however necessary to allow <code class="code">Alt</code> elements to resolve the entities described in section <a href="chap2.html#X7BDFF6D37FBED400"><span class="RefLink">2.2-3</span></a>.</p>
<p><a id="X7B15C428861749FD" name="X7B15C428861749FD"></a></p>
<h5>3.7-1 <span class="Heading"><code class="code"><Emph></code> and <code class="code"><E></code></span></h5>
<div class="example"><pre>
<!ELEMENT Emph (%InnerText;)*> <!-- Emphasize something -->
<!ELEMENT E (%InnerText;)*> <!-- the same as shortcut -->
</pre></div>
<p>This element is used to emphasize some piece of text. It may contain <code class="code">%InnerText;</code> (see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>).</p>
<p><a id="X80028C2483C9467E" name="X80028C2483C9467E"></a></p>
<h5>3.7-2 <span class="Heading"><code class="code"><Quoted></code> and <code class="code"><Q></code></span></h5>
<div class="example"><pre>
<!ELEMENT Quoted (%InnerText;)*> <!-- Quoted (in quotes) text -->
<!ELEMENT Q (%InnerText;)*> <!-- Quoted text (shortcut) -->
</pre></div>
<p>This element is used to put some piece of text into <q> </q>-quotes. It may contain <code class="code">%InnerText;</code> (see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>).</p>
<p><a id="X867BB95E7DC87014" name="X867BB95E7DC87014"></a></p>
<h5>3.7-3 <span class="Heading"><code class="code"><Keyword></code> and <code class="code"><K></code></span></h5>
<div class="example"><pre>
<!ELEMENT Keyword (#PCDATA|Alt)*> <!-- Keyword -->
<!ELEMENT K (#PCDATA|Alt)*> <!-- Keyword (shortcut) -->
</pre></div>
<p>This element is used to mark something as a <em>keyword</em>. Usually this will be a <strong class="pkg">GAP</strong> keyword such as <q><code class="keyw">if</code></q> or <q><code class="keyw">for</code></q>. No further markup elements are allowed within this element except for the <code class="code">Alt</code> element, which is necessary.</p>
<p><a id="X86FD4CCA7F98351F" name="X86FD4CCA7F98351F"></a></p>
<h5>3.7-4 <span class="Heading"><code class="code"><Arg></code> and
<code class="code"><A></code></span></h5>
<div class="example"><pre>
<!ELEMENT Arg (#PCDATA|Alt)*> <!-- Argument -->
<!ELEMENT A (#PCDATA|Alt)*> <!-- Argument (shortcut) -->
</pre></div>
<p>This element is used inside <code class="code">Description</code>s in <code class="code">ManSection</code>s to mark something as an <em>argument</em> (of a function, operation, or such). It is guaranteed that the converters typeset those exactly as in the definition of functions. No further markup elements are allowed within this element.</p>
<p><a id="X8400998B7B3A4379" name="X8400998B7B3A4379"></a></p>
<h5>3.7-5 <span class="Heading"><code class="code"><Code></code> and
<code class="code"><C></code></span></h5>
<div class="example"><pre>
<!ELEMENT Code (#PCDATA|Arg|Alt)*> <!-- GAP code -->
<!ELEMENT C (#PCDATA|Arg|Alt)*> <!-- GAP code (shortcut) -->
</pre></div>
<p>This element is used to mark something as a piece of <em>code</em> like for example a <strong class="pkg">GAP</strong> expression. It is guaranteed that the converters typeset this exactly as in the <code class="code">Listing</code> element (compare section <a href="chap3.html#X7F531B157D656836"><span class="RefLink">3.7-9</span></a>). The only further markup elements allowed within this element are <code class="code"><Arg></code> elements (see <a href="chap3.html#X86FD4CCA7F98351F"><span class="RefLink">3.7-4</span></a>).</p>
<p><a id="X875AF9B4812C5249" name="X875AF9B4812C5249"></a></p>
<h5>3.7-6 <span class="Heading"><code class="code"><File></code> and <code class="code"><F></code></span></h5>
<div class="example"><pre>
<!ELEMENT File (#PCDATA|Alt)*> <!-- Filename -->
<!ELEMENT F (#PCDATA|Alt)*> <!-- Filename (shortcut) -->
</pre></div>
<p>This element is used to mark something as a <em>filename</em> or a <em>pathname</em> in the file system. No further markup elements are allowed within this element.</p>
<p><a id="X7929BA7D78A977FF" name="X7929BA7D78A977FF"></a></p>
<h5>3.7-7 <span class="Heading"><code class="code"><Button></code> and <code class="code"><B></code></span></h5>
<div class="example"><pre>
<!ELEMENT Button (#PCDATA|Alt)*> <!-- "Button" (also Menu, Key, ...) -->
<!ELEMENT B (#PCDATA|Alt)*> <!-- "Button" (shortcut) -->
</pre></div>
<p>This element is used to mark something as a <em>button</em>. It can also be used for other items in a graphical user interface like <em>menus</em>, <em>menu entries</em>, or <em>keys</em>. No further markup elements are allowed within this element.</p>
<p><a id="X7F4FFA877B775188" name="X7F4FFA877B775188"></a></p>
<h5>3.7-8 <span class="Heading"><code class="code"><Package></code></span></h5>
<div class="example"><pre>
<!ELEMENT Package (#PCDATA|Alt)*> <!-- A package name -->
</pre></div>
<p>This element is used to mark something as a name of a <em>package</em>. This is for example used to define the entities <strong class="pkg">GAP</strong>, <strong class="pkg">XGAP</strong> or <strong class="pkg">GAPDoc</strong> (see section <a href="chap2.html#X7BDFF6D37FBED400"><span class="RefLink">2.2-3</span></a>). No further markup elements are allowed within this element.</p>
<p><a id="X7F531B157D656836" name="X7F531B157D656836"></a></p>
<h5>3.7-9 <span class="Heading"><code class="code"><Listing></code></span></h5>
<div class="example"><pre>
<!ELEMENT Listing (#PCDATA)> <!-- This is just for GAP code listings -->
<!ATTLIST Listing Type CDATA #IMPLIED> <!-- a comment about the type of
listed code, may appear in
output -->
</pre></div>
<p>This element is used to embed listings of programs into the document. Only character data and no other elements are allowed in the content. You should <em>not</em> use the character entities described in section <a href="chap2.html#X7BDFF6D37FBED400"><span class="RefLink">2.2-3</span></a> but instead type the characters directly. Only the general XML rules from section <a href="chap2.html#X7B3A544986A1A9EA"><span class="RefLink">2.1</span></a> apply. Note especially the usage of <code class="code"><![CDATA[</code> sections described there. It is guaranteed that all converters use a fixed width font for typesetting <code class="code">Listing</code> elements. Compare also the usage of the <code class="code">Code</code> and <code class="code">C</code> elements in <a href="chap3.html#X8400998B7B3A4379"><span class="RefLink">3.7-5</span></a>.</p>
<p>The <code class="code">Type</code> attribute contains a comment about the type of listed code. It may appear in the output.</p>
<p><a id="X810DEA1E83A57CFE" name="X810DEA1E83A57CFE"></a></p>
<h5>3.7-10 <span class="Heading"><code class="code"><Log></code> and
<code class="code"><Example></code></span></h5>
<div class="example"><pre>
<!ELEMENT Example (#PCDATA)> <!-- This is subject to the automatic
example checking mechanism -->
<!ELEMENT Log (#PCDATA)> <!-- This not -->
</pre></div>
<p>These two elements behave exactly like the <code class="code">Listing</code> element (see <a href="chap3.html#X7F531B157D656836"><span class="RefLink">3.7-9</span></a>). They are thought for protocols of <strong class="pkg">GAP</strong> sessions. The only difference between the two is that <code class="code">Example</code> sections are intended to be subject to an automatic manual checking mechanism used to ensure the correctness of the <strong class="pkg">GAP</strong> manual whereas <code class="code">Log</code> is not touched by this (see section <a href="chap5.html#X800299827B88ABBE"><span class="RefLink">5.4</span></a> for checking tools).</p>
<p>To get a good layout of the examples for display in a standard terminal we suggest to use <code class="code">SizeScreen([72]);</code> (see <code class="func">SizeScreen</code> (<a href="../../../doc/ref/chap6.html#X8723E0A1837894F3"><span class="RefLink">Reference: SizeScreen</span></a>)) in your <strong class="pkg">GAP</strong> session before producing the content of <code class="code">Example</code> elements.</p>
<p><a id="X7F8C4D018346B2CF" name="X7F8C4D018346B2CF"></a></p>
<h5>3.7-11 <span class="Heading"><code class="code"><Verb></code></span></h5>
<p>There is one further type of verbatim-like element.</p>
<div class="example"><pre>
<!ELEMENT Verb (#PCDATA)>
</pre></div>
<p>The content of such an element is guaranteed to be put into an output version exactly as it is using some fixed width font. Before the content a new line is started. If the line after the end of the start tag consists of whitespace only then this part of the content is skipped.</p>
<p>This element is intended to be used together with the <code class="code">Alt</code> element to specify pre-formatted ASCII alternatives for complicated <code class="code">Display</code> formulae or <code class="code">Table</code>s.</p>
<p><a id="X8145F6B37C04AA0A" name="X8145F6B37C04AA0A"></a></p>
<h4>3.8 <span class="Heading">Elements for Mathematical Formulae</span></h4>
<p><a id="X7AA02845868AA533" name="X7AA02845868AA533"></a></p>
<h5>3.8-1 <span class="Heading"><code class="code"><Math></code>
and <code class="code"><Display></code></span></h5>
<div class="example"><pre>
<!-- Normal TeX math mode formula -->
<!ELEMENT Math (#PCDATA|A|Arg|Alt)*>
<!-- TeX displayed math mode formula -->
<!ELEMENT Display (#PCDATA|A|Arg|Alt)*>
<!-- Mode="M" causes <M>-style formatting -->
<!ATTLIST Display Mode CDATA #IMPLIED>
</pre></div>
<p>These elements are used for mathematical formulae. As described in section <a href="chap2.html#X7EAE0C5A835F126F"><span class="RefLink">2.2-2</span></a> they correspond to LaTeX's math and display math mode respectively.</p>
<p>The formulae are typed in as in LaTeX, <em>except</em> that the standard XML entities, see <a href="chap2.html#X78FB56C77B1F391A"><span class="RefLink">2.1-9</span></a> (in particular the characters <code class="code"><</code> and <code class="code">&</code>), must be escaped - either by using the corresponding entities or by enclosing the formula between <q><code class="code"><![CDATA[</code></q> and <q><code class="code">]]></code></q>. (The main reference for LaTeX is <a href="chapBib.html#biBLa85">[Lam85]</a>.)</p>
<p>It is also possible to use some unicode characters for mathematical symbols directly, provided that it can be translated by <code class="func">Encode</code> (<a href="chap6.html#X818A31567EB30A39"><span class="RefLink">6.2-2</span></a>) into <code class="code">"LaTeX"</code> encoding and that <code class="func">SimplifiedUnicodeString</code> (<a href="chap6.html#X818A31567EB30A39"><span class="RefLink">6.2-2</span></a>) with arguments <code class="code">"latin1"</code> and <code class="code">"single"</code> returns something sensible. Currently, we support entities <code class="code">&CC;</code>, <code class="code">&ZZ;</code>, <code class="code">&NN;</code>, <code class="code">&PP;</code>, <code class="code">&QQ;</code>, <code class="code">&HH;</code>, <code class="code">&RR;</code> for the corresponding black board bold letters ℂ, ℤ, ℕ, ℙ, ℚ, ℍ and ℝ, respectively.</p>
<p>The only element type that is allowed within the formula elements is the <code class="code">Arg</code> or <code class="code">A</code> element (see <a href="chap3.html#X86FD4CCA7F98351F"><span class="RefLink">3.7-4</span></a>), which is used to typeset identifiers that are arguments to <strong class="pkg">GAP</strong> functions or operations.</p>
<p>If a <code class="code">Display</code> element has an attribute <code class="code">Mode</code> with value <code class="code">"M"</code>, then the formula is formatted as in <code class="code">M</code> elements (see <a href="chap3.html#X7ABF42328467E966"><span class="RefLink">3.8-2</span></a>). Otherwise in text and HTML output the formula is shown as LaTeX source code.</p>
<p>For simple formulae (and you should try to make all your formulae simple!) attempt to use the <code class="code">M</code> element or the <code class="code">Mode="M"</code> attribute in <code class="code">Display</code> for which there is a well defined translation into text, which can be used for text and HTML output versions of the document. So, if possible try to avoid the <code class="code">Math</code> elements and <code class="code">Display</code> elements without attribute or provide useful text substitutes for complicated formulae via <code class="code">Alt</code> elements (see <a href="chap3.html#X850E69017945AE3E"><span class="RefLink">3.9-1</span></a> and <a href="chap3.html#X7F8C4D018346B2CF"><span class="RefLink">3.7-11</span></a>).</p>
<p><a id="X7ABF42328467E966" name="X7ABF42328467E966"></a></p>
<h5>3.8-2 <span class="Heading"><code class="code"><M></code></span></h5>
<div class="example"><pre>
<!-- Math with well defined translation to text output -->
<!ELEMENT M (#PCDATA|A|Arg|Alt)*>
</pre></div>
<p>The <q><code class="code">M</code></q> element type is intended for formulae in the running text for which there is a sensible text version. For the LaTeX version of a <strong class="pkg">GAPDoc</strong> document the <code class="code">M</code> and <code class="code">Math</code> elements are equivalent. The remarks in <a href="chap3.html#X7AA02845868AA533"><span class="RefLink">3.8-1</span></a> about special characters and the <code class="code">Arg</code> element apply here as well. A document which has all formulae enclosed in <code class="code">M</code> elements can be well readable in text terminal output and printed output versions.</p>
<p>Compared to former versions of <strong class="pkg">GAPDoc</strong> many more formulae can be put into <code class="code">M</code> elements. Most modern terminal emulations support unicode characters and many mathematical symbols can now be represented by such characters. But even if a terminal can only display ASCII characters, the user will see some not too bad representation of a formula.</p>
<p>As examples, here are some LaTeX macros which have a sensible ASCII translation and are guaranteed to be translated accordingly by text (and HTML) converters (for a full list of handled Macros see <code class="code">RecNames(TEXTMTRANSLATIONS)</code>):</p>
<div class="pcenter"><table class="GAPDocTable">
<caption class="GAPDocTable"><b>Table: </b>LaTeX macros with special text translation</caption>
<tr>
<td class="tdleft">\ast</td>
<td class="tdleft"><code class="code">*</code></td>
</tr>
<tr>
<td class="tdleft">\bf</td>
<td class="tdleft"><code class="code"></code></td>
</tr>
<tr>
<td class="tdleft">\bmod</td>
<td class="tdleft"><code class="code">mod</code></td>
</tr>
<tr>
<td class="tdleft">\cdot</td>
<td class="tdleft"><code class="code">*</code></td>
</tr>
<tr>
<td class="tdleft">\colon</td>
<td class="tdleft"><code class="code">:</code></td>
</tr>
<tr>
<td class="tdleft">\equiv</td>
<td class="tdleft"><code class="code">=</code></td>
</tr>
<tr>
<td class="tdleft">\geq</td>
<td class="tdleft"><code class="code">>=</code></td>
</tr>
<tr>
<td class="tdleft">\germ</td>
<td class="tdleft"><code class="code"></code></td>
</tr>
<tr>
<td class="tdleft">\hookrightarrow</td>
<td class="tdleft"><code class="code">-></code></td>
</tr>
<tr>
<td class="tdleft">\iff</td>
<td class="tdleft"><code class="code"><=></code></td>
</tr>
<tr>
<td class="tdleft">\langle</td>
<td class="tdleft"><code class="code"><</code></td>
</tr>
<tr>
<td class="tdleft">\ldots</td>
<td class="tdleft"><code class="code">...</code></td>
</tr>
<tr>
<td class="tdleft">\left</td>
<td class="tdleft"><code class="code"> </code></td>
</tr>
<tr>
<td class="tdleft">\leq</td>
<td class="tdleft"><code class="code"><=</code></td>
</tr>
<tr>
<td class="tdleft">\leftarrow</td>
<td class="tdleft"><code class="code"><-</code></td>
</tr>
<tr>
<td class="tdleft">\Leftarrow</td>
<td class="tdleft"><code class="code"><=</code></td>
</tr>
<tr>
<td class="tdleft">\limits</td>
<td class="tdleft"><code class="code"> </code></td>
</tr>
<tr>
<td class="tdleft">\longrightarrow</td>
<td class="tdleft"><code class="code">--></code></td>
</tr>
<tr>
<td class="tdleft">\Longrightarrow</td>
<td class="tdleft"><code class="code">==></code></td>
</tr>
<tr>
<td class="tdleft">\mapsto</td>
<td class="tdleft"><code class="code">-></code></td>
</tr>
<tr>
<td class="tdleft">\mathbb</td>
<td class="tdleft"><code class="code"> </code></td>
</tr>
<tr>
<td class="tdleft">\mathop</td>
<td class="tdleft"><code class="code"> </code></td>
</tr>
<tr>
<td class="tdleft">\mid</td>
<td class="tdleft"><code class="code">|</code></td>
</tr>
<tr>
<td class="tdleft">\pmod</td>
<td class="tdleft"><code class="code">mod</code></td>
</tr>
<tr>
<td class="tdleft">\prime</td>
<td class="tdleft"><code class="code">'</code></td>
</tr>
<tr>
<td class="tdleft">\rangle</td>
<td class="tdleft"><code class="code">></code></td>
</tr>
<tr>
<td class="tdleft">\right</td>
<td class="tdleft"><code class="code"> </code></td>
</tr>
<tr>
<td class="tdleft">\rightarrow</td>
<td class="tdleft"><code class="code">-></code></td>
</tr>
<tr>
<td class="tdleft">\Rightarrow</td>
<td class="tdleft"><code class="code">=></code></td>
</tr>
<tr>
<td class="tdleft">\rm, \sf, \textrm, \text</td>
<td class="tdleft"><code class="code"></code></td>
</tr>
<tr>
<td class="tdleft">\setminus</td>
<td class="tdleft"><code class="code">\</code></td>
</tr>
<tr>
<td class="tdleft">\thinspace</td>
<td class="tdleft"><code class="code"> </code></td>
</tr>
<tr>
<td class="tdleft">\times</td>
<td class="tdleft"><code class="code">x</code></td>
</tr>
<tr>
<td class="tdleft">\to</td>
<td class="tdleft"><code class="code">-></code></td>
</tr>
<tr>
<td class="tdleft">\vert</td>
<td class="tdleft"><code class="code">|</code></td>
</tr>
<tr>
<td class="tdleft">\!</td>
<td class="tdleft"><code class="code"></code></td>
</tr>
<tr>
<td class="tdleft">\,</td>
<td class="tdleft"><code class="code"></code></td>
</tr>
<tr>
<td class="tdleft">\;</td>
<td class="tdleft"><code class="code"> </code></td>
</tr>
<tr>
<td class="tdleft">\{</td>
<td class="tdleft"><code class="code">{</code></td>
</tr>
<tr>
<td class="tdleft">\}</td>
<td class="tdleft"><code class="code">}</code></td>
</tr>
</table><br />
</div>
<p>In all other macros only the backslash is removed (except for some macros describing more exotic symbols). Whitespace is normalized (to one blank) but not removed. Note that whitespace is not added, so you may want to add a few more spaces than you usually do in your LaTeX documents.</p>
<p>Braces <code class="code">{}</code> are removed in general, however pairs of double braces are converted to one pair of braces. This can be used to write <code class="code"><M>x^{12}</M></code> for <code class="code">x^12</code> and <code class="code"><M>x_{{i+1}}</M></code> for <code class="code">x_{i+1}</code>.</p>
<p><a id="X7A0D26B180BEDE37" name="X7A0D26B180BEDE37"></a></p>
<h4>3.9 <span class="Heading">Everything else</span></h4>
<p><a id="X850E69017945AE3E" name="X850E69017945AE3E"></a></p>
<h5>3.9-1 <span class="Heading"><code class="code"><Alt></code></span></h5>
<p>This element is used to specify alternatives for different output formats within normal text. See also sections <a href="chap3.html#X785183F67DA402A0"><span class="RefLink">3.6-1</span></a>, <a href="chap3.html#X78A52B00846562DE"><span class="RefLink">3.6-4</span></a>, and <a href="chap3.html#X7F9CAA577EB4070B"><span class="RefLink">3.6-5</span></a> for alternatives in lists and tables.</p>
<div class="example"><pre>
<!ELEMENT Alt (%InnerText;)*> <!-- This is only to allow "Only" and
"Not" attributes for normal text -->
<!ATTLIST Alt Only CDATA #IMPLIED
Not CDATA #IMPLIED>
</pre></div>
<p>Of course exactly one of the two attributes must occur in one element. The attribute values must be one word or a list of words, separated by spaces or commas. The words which are currently recognized by the converter programs contained in <strong class="pkg">GAPDoc</strong> are: <q><code class="code">LaTeX</code></q>, <q><code class="code">HTML</code></q>, and <q><code class="code">Text</code></q>. If the <code class="code">Only</code> attribute is specified then only the corresponding converter will include the content of the element into the output document. If the <code class="code">Not</code> attribute is specified the corresponding converter will ignore the content of the element. You can use other words to specify special alternatives for other converters of <strong class="pkg">GAPDoc</strong> documents.</p>
<p>In the case of <q><code class="code">HTML</code></q> there is a second word which is recognized and this can either be <q><code class="code">MathJax</code></q> or <q><code class="code">noMathJax</code></q>. For example a pair of <code class="code">Alt</code> elements with <code class="code"><Alt Only="HTML noMathJax">...</code> and <code class="code"><Alt Not="HTML noMathJax">...</code> could provide special content for the case of HTML output without use of <strong class="pkg">MathJax</strong> and every other output.</p>
<p>We fix a rule for handling the content of an <code class="code">Alt</code> element with <code class="code">Only</code> attribute. In their content code for the corresponding output format is included directly. So, in case of HTML the content is HTML code, in case of LaTeX the content is LaTeX code. The converters don't apply any handling of special characters to this content. In the case of LaTeX the formatting of the code is not changed.</p>
<p>Within the element only <code class="code">%InnerText;</code> (see <a href="chap3.html#X7BCC8E6F79021294"><span class="RefLink">here</span></a>) is allowed. This is to ensure that the same set of chapters, sections, and subsections show up in all output formats.</p>
<p><a id="X85D23A648444069F" name="X85D23A648444069F"></a></p>
<h5>3.9-2 <span class="Heading"><code class="code"><Par></code> and
<code class="code"><P></code></span></h5>
<div class="example"><pre>
<!ELEMENT Par EMPTY> <!-- this is intentionally empty! -->
<!ELEMENT P EMPTY> <!-- the same as shortcut -->
</pre></div>
<p>This <code class="code">EMPTY</code> element marks the boundary of paragraphs. Note that an empty line in the input does not mark a new paragraph as opposed to the LaTeX convention.</p>
<p>(Remark: it would be much easier to parse a document and to understand its sectioning and paragraph structure when there was an element whose <em>content</em> is the text of a paragraph. But in practice many paragraph boundaries are implicitly clear which would make it somewhat painful to enclose each paragraph in extra tags. The introduction of the <code class="code">P</code> or <code class="code">Par</code> elements as above delegates this pain to the writer of a conversion program for <strong class="pkg">GAPDoc</strong> documents.)</p>
<p><a id="X7A3EF0647B10C1EC" name="X7A3EF0647B10C1EC"></a></p>
<h5>3.9-3 <span class="Heading"><code class="code"><Br></code></span></h5>
<div class="example"><pre>
<!ELEMENT Br EMPTY> <!-- a forced line break -->
</pre></div>
<p>This element can be used to force a line break in the output versions of a <strong class="pkg">GAPDoc</strong> element, it does not start a new paragraph. Please, do not use this instead of a <code class="code">Par</code> element, this would often lead to ugly output versions of your document.</p>
<p><a id="X7A81FB717A30B485" name="X7A81FB717A30B485"></a></p>
<h5>3.9-4 <span class="Heading"><code class="code"><Ignore></code></span></h5>
<div class="example"><pre>
<!ELEMENT Ignore (%Text;| Chapter | Section | Subsection | ManSection |
Heading)*>
<!ATTLIST Ignore Remark CDATA #IMPLIED>
</pre></div>
<p>This element can appear anywhere. Its content is ignored by the standard converters. It can be used, for example, to include data which are not part of the actual <strong class="pkg">GAPDoc</strong> document, like source code, or to make not finished parts of the document invisible.</p>
<p>Of course, one can use special converter programs which extract the contents of <code class="code">Ignore</code> elements. Information on the type of the content can be stored in the optional attribute <code class="code">Remark</code>.</p>
<div class="chlinkprevnextbot"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap2.html">[Previous Chapter]</a> <a href="chap4.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="chap5.html">5</a> <a href="chap6.html">6</a> <a href="chap7.html">7</a> <a href="chapA.html">A</a> <a href="chapB.html">B</a> <a href="chapC.html">C</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<hr />
<p class="foot">generated by <a href="https://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>
|
