/usr/share/gap/etc/gapmacrodoc.tex is in gap-core 4r8p6-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W gapmacrodoc.tex GAP documentation Thomas Breuer
%W & Frank Celler
%W & Martin Schoenert
%W & Heiko Theissen
%W & Burkhard Höfling
%%
%%
%Y Copyright 1997, Lehrstuhl D fuer Mathematik, RWTH Aachen, Germany
%%
%% self-contained document with the former chapter
%% ``The gapmacro.tex Manual Format'' of ``Extending GAP''
%%
\input gapmacro
\BeginningOfBook{gapmacro}
\UseReferences{ref}
\TitlePage{
\centerline{\titlefont GAP}\bigskip
\centerline{\secfont Release 4.5}\medskip
\centerline{\secfont October 2011}\vfill
\centerline{\titlefont The gapmacro.tex}\bigskip\bigskip
\centerline{\titlefont Manual Format}\vfill
\centerline{\secfont The GAP Group}\bigskip
\centerline{\secfont http://www.gap-system.org}
}
\OneColumnTableOfContents
\FrontMatter
%\input ../doc/ref/copyrigh
\Chapters
\Chapter{The gapmacro.tex Manual Format}
This document describes a restricted {\TeX} format,
which is defined by the of macros in the file
\){\kernttindent GAPPATH/doc/gapmacro.tex}
and how to create the final documents (which can be printed or used by
{\GAP}'s online help) from it.
Some {\GAP}~4 package documentation is written in this format.
Up to version 4.4, the same was true for the main {\GAP} manuals.
See "TeX Macros" and "Examples, Lists, and Verbatim" for details on the
restricted set of available {\TeX} commands.
The first sections "The main file" and
"gapmacro:Structuring the text: Chapters and Sections" describe
the general layout of the files in case you need to write your own
package documentation.
If you are planning to write new documentation for a {\GAP} package,
one alternative to using the format described in this document
is to use the \package{GAPDoc} package,
see Chapter ``Introduction and Example''
in the \package{GAPDoc} manual,
for example type
\testexamplefalse
\beginexample
gap> ?GAPDoc:chapters
\endexample
in {\GAP}'s online help for a table of contents, or (if it is not
available in your installation) see:
\URL{http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc/}
If you want to use yet another document format you must provide certain
information to the interface of {\GAP}'s online help. This is described
in Chapter ``Interface to the GAP Help System'' of the
{\GAP} Reference Manual.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The Main File}
\indextt{gapmacro.tex}\indextt{\\BeginningOfBook}\indextt{\\UseReferences}
\indextt{\\UseGapDocReferences}
\indextt{\\TitlePage}\indextt{\\Colophon}\indextt{\\TableOfContents}
\indextt{\\OneColumnTableOfContents}
\indextt{\\FrontMatter}\indextt{\\Chapters}\indextt{\\Appendices}
\indextt{\\Bibliography}\indextt{\\Index}\indextt{\\EndOfBook}
\indextt{\\Package}\indextt{\\package}
The main {\TeX} file is called `manual.tex'.
This file should contain the following commands:
%\begintt
\){\kernttindent\\input ../gapmacro}
\){\kernttindent\ ... (gapmacro.tex options, see "Additional Typesetting Options" below)}
\){\kernttindent\\Package\{<package-name>\}}
\){\kernttindent\\BeginningOfBook\{<name-of-book>\}}
\){\kernttindent\ \ \\UseReferences\{<book1>\}}
\){\kernttindent\ \ ...}
\){\kernttindent\ \ \\UseReferences\{<bookn>\}}
\){\kernttindent\ \ \\TitlePage\{<title>\}}
\){\kernttindent\ \ \\Colophon\{<text>\}}
\){\kernttindent\ \ \\TableOfContents}
\){\kernttindent\ \ \\FrontMatter}
\){\kernttindent\ \ \ \ \\immediate\\write\\citeout\{\\bs bibdata\{<mybibliography>\}\}}
\){\kernttindent\ \ \ \ \\Input\{<file1>\}}
\){\kernttindent\ \ \ \ ...}
\){\kernttindent\ \ \ \ \\Input\{<filen>\}}
\){\kernttindent\ \ \\Chapters}
\){\kernttindent\ \ \ \ \\Input\{<file1>\}}
\){\kernttindent\ \ \ \ ...}
\){\kernttindent\ \ \ \ \\Input\{<filen>\}}
\){\kernttindent\ \ \\Appendices}
\){\kernttindent\ \ \ \ \\Input\{<file1>\}}
\){\kernttindent\ \ \ \ ...}
\){\kernttindent\ \ \ \ \\Input\{<filen>\}}
\){\kernttindent\ \ \ \ \\Bibliography}
\){\kernttindent\ \ \ \ \\Index}
\){\kernttindent\\EndOfBook}
%\endtt
Now we describe what these commands do:
\beginitems
`\\input <path>/gapmacro.tex'&
inputs the {\GAP} ``style'' and macros file `gapmacro.tex'. If you are
writing a {\GAP} package either copy this file or use a relative path.
The former method will always work but requires you to keep the file
consistent with the system while the latter forces users to change the
`manual.tex' file if they are installing a package in a private location.
See also Section ``GAP Root Directory'' in the {\GAP} Reference Manual.
\index{typesetting options}
\index{options!for gapmacro.tex}
\indextt{\\Package}
`\\Package\{<package-name>\}'&
defines a macro `\\<package-name>' so that when you type
`\{\\<package-name>\}' (please include the curly braces) the text
<package-name> is typeset in the right way for {\GAP} packages, e.g.~if
you are writing a package \package{MyPackage} then you should include the
line
\){\kernttindent\\Package\{MyPackage\}}
&
in your `manual.tex' file and then in your chapter files use
`\{\\MyPackage\}' when you refer to \package{MyPackage} by name. There is
also the command `\\package\{<pkg>\}' when you wish to refer to other
{\GAP} packages; don't confuse the two i.e.~`\\Package\{<package-name>\}'
defines a macro `\\<package-name>' but produces no text, and
`\\package\{<pkg>\}' produces <pkg> set in the font that is right for
{\GAP} packages.
\indextt{\\BeginningOfBook}
`\\BeginningOfBook\{<name-of-book>\}'&
starts the book <name-of-book>. It is used for cross-references, see
"Labels and References". If you are writing a {\GAP} package use the name
of your package here.
\indextt{\\UseReferences}\indextt{\\UseGapDocReferences}
`\\UseReferences\{<booki>\}', `\\UseGapDocReferences\{<booki>\}' &
If your manual cross-refers to another manual, `\\UseReferences' can be
used to load the labels of the other books in case cross-references
occur. <booki> should be the path of the directory containing the book
whose references you want to load. However, as said above this requires
changes to the `manual.tex' file if the package is not installed in the
standard location. `\\UseGapDocReferences' can also be used to load
\package{GAPDoc} style references, but this function exists only for backward
compatibility.
&
Just ensure you get the path to the
other manual's directory correct *relative* to the directory in which
your manual resides.
&
If your `manual.tex' file lives in `pkg/qwer/doc' and you want to use
references to the {\GAP} Tutorial use
\begintt
\UseGapDocReferences{../../../doc/tut}
\endtt
\indextt{\\TitlePage}
`\\TitlePage'&
produces a page containing the *title*. Please see the example.
\indextt{\\Colophon}
`\\Colophon'&
`\\Colophon' produces a page following the title that can be used for
more explicit author information, acknowledgements, dedications or
whatsoever.
\indextt{\\TableOfContents}\indextt{\\OneColumnTableOfContents}
`\\TableOfContents'&
produces a table of contents in double-column format. For short manuals,
the double-column format may be inappropriate; in this case, use
`\\OneColumnTableOfContents' instead.
\indextt{\\FrontMatter}
`\\FrontMatter'&
starts the front matter chapters such as a copyright notice or a preface.
&
The line
%\begintt
\){\kernttindent\\immediate\\write\\citeout\{\\bs bibdata\{<mybibliography>\}\}}
%\endtt
&
is for users of Bib{\TeX}. It will use the file `<mybibliography>.bib' to
fetch bibliography information.
\indextt{\\Chapters}
`\\Chapters'&
starts the chapters of the manual, which are included via `\\Input'.
`\\Input\{<filei>\}' inputs the file `<filei>.tex', i.e.~<filei> should
be the name of the file *without* the `.tex' extension. For the chapter
format, see Section~"gapmacro:Structuring the text: Chapters and Sections".
\indextt{\\Appendices}
`\\Appendices'&
starts the appendices, i.e.~it modifies the `\\Chapter' command to use
uppercase letters to number chapters.
%`\\Answers' produces an answers chapter, see "Exercises and Answers".
\indextt{\\Bibliography}
`\\Bibliography'&
produces a bibliography, i.e. it reads and typesets the `manual.bbl' file
produced by Bib{\TeX}.
\indextt{\\Index}
`\\Index'&
produces an index, i.e. it reads and typesets the `manual.ind' file
produced by the external `manualindex' program.
\indextt{\\EndOfBook}
`\\EndOfBook'&
Finally `\\EndOfBook' closes the book.
\enditems
*Example*
Assume you have a {\GAP} package `qwert' with two chapters `Qwert' and
`Extending Qwert', a copyright notice, and a preface, then your
`manual.tex' would basically look like:
\begintt
\input ../../../doc/gapmacro % The right path from pkg/qwert/doc
\Package{Qwert} % Defines macro {\Qwert}
\BeginningOfBook{qwert}
\TitlePage{
\centerline{\titlefont Qwert}\medskip % Package name
\centerline{\titlefont ---}\medskip
\centerline{\titlefont A GAP4 Package}\bigskip\bigskip
\centerline{\secfont Version 1.0}\medskip
% If the package interfaces with an external program ...
\centerline{\secfont Based on qwert Standalone Version 3.14}\vfill
\centerline{\secfont by}\vfill
\centerline{\secfont Q. Mustermensch}\medskip % Author
\centerline{Department of Mathematics}\medskip % Affiliation
\centerline{University of Erewhon}\medskip
\centerline{\secfont email: qmuster@erewhon.uxyz.edu.ut} % Email address
\vfill
\centerline{\secfont{\Month} \Year}
}
\TableOfContents
\FrontMatter
\Input{copyright}
\Input{preface}
\Chapters
\Input{qwert}
\Input{extend}
\Appendices
\Index
\EndOfBook
\endtt
\indextt{\\PseudoInput}\indextt{\\Day}\indextt{\\Month}\indextt{\\Year}
\indextt{\\Today}
Occasionally there will be the need for additional commands over and
above those shown above. The ones described below should be the *only*
exceptions.
\beginlist%unordered
\item{--}
There may be other packages that are referred to a lot, so that it's
worthwhile to add more `\\Package' commands. (There's nothing special
about `\\Package', you can use it to define macros for other packages
besides the package being documented.)
\item{--}
Besides the macros `\{\\Month\}' and `\{\\Year\}', which typeset the
current month (as an English word) and the year (all four digits),
respectively, there are also `\{\\Day\}' and `\{\\Today\}' which are
mainly intended for drafts. `\{\\Day\}' typesets the day of the month as
a number and `\{\\Today\}' is equivalent to: `\{\\Day\} \{\\Month\}
\{\\Year\}'.
\item{--}
Sometimes one desires a chapter to be unnumbered in the {\TeX}-produced
manuals, e.g.~the Tutorial manual has {\GAP}'s Copyright Notice as an
unnumbered chapter. To achieve this one inputs the file containing the
chapter via {\TeX}'s `\\input' command rather than `\\Input'. However,
neither the on-line help browser nor the HTML converter ``sees'' such
chapters. Thus if it is desired that the on-line help browser and the
HTML manuals should also have such chapters, they must be ``input'' again
via the `\\PseudoInput' command (not necessarily in the same manual).
\item{--}
For chapters that should only appear via the on-line help browser or in
the HTML manuals, one may use the `\\PseudoInput' command. Any
`\\PseudoInput' commands should come *after* all `\\Input' commands;
failure to do this will result in different numbering of `\\Input'
chapters for {\TeX}-produced and HTML manuals. The syntax of this command
is as follows:
\)\kernttindent\\PseudoInput\{<filename>\}\{<six-entry>\}\{<chaptername>\}
%display{tex}
\item{}
%enddisplay
where <filename> is the name of the file containing the chapter without
the `.tex' extension, as for the `\\Input' command, <six-entry> is the
section-index-entry for the chapter (written to the `manual.six' file)
and <chaptername> is the *actual* argument of the `\\Chapter' command
that appears at the beginning of `<filename>.tex'. The argument
<six-entry> enables the on-line text browser to reference the chapter by
a name other than <chaptername>. Thus a copyright chapter for the book
with name <name-of-book> might have <chaptername> ```Copyright Notice'''
but <six-entry> ```Copyright''', which would enable one to access the
chapter ```Copyright Notice''' via `?<name-of-book>:copyright' via the
on-line browser. The HTML converter adds an index entry for both
<six-entry> and <chaptername>.
\endlist
*Note*
Usage of the commands `\\input' and `\\PseudoInput' in the way described
above will necessitate special treatment of references to such chapters.
For such purposes, there is a special variant of the `\%display'
environment (see "Catering for Plain Text and HTML Formats"), e.g.~a
copyright notice appearing via `\\input' at the beginning of a
{\TeX}-produced manual and appearing in the non-{\TeX} manuals -- the
on-line help browser or HTML manual -- via a `\\PseudoInput' command as
described above, may be referenced via
\begintt
%display{tex}
See the copyright notice at the beginning of this book.
%display{nontex}
%See "Copyright".
%enddisplay
\endtt
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Additional Typesetting Options}
\label{options!for gapmacro.tex}
There are a number of additional options which you can activate/
deactivate by adding the following {\TeX} just after the line
\){\kernttindent\\input ../gapmacro}.
Of course, you need not set options which are marked as default.
\beginitems
`\\usepsfonts' & (default) use the standard Postscript fonts for typesetting
`\\usecmfonts' & use the TeX standard (Computer Modern) fonts (this was the
behaviour until {\GAP} 4.4).
`\\addlinks' & (default) This inserts pdf links within the document, so
that you can click on a reference or citation. This will only work
with pdftex, otherwise this has no effect.
`\\nolinks' & This switches off additional pdf links within the document (this was the
behaviour until {\GAP} 4.4.
`\\citebooksfalse' & (default) References to external books will just print the
chapter/section/subsection number(s).
`\\citebookstrue' & References to external books will be printed as
`GAP Reference Manual, 2.7.12' instead of just `2.7.12', similarly
for the GAP tutorial. If you cite other books, you have to define
for each book `XXX' a macro `\\xxxManual' which expands to the text
which you want to be inserted before the number for package `XXX'.
(Note that the `xxx' in `\\xxxManual' must always be lower case, regardless
of the actual package name `XXX'.)
&
If you want to cite from the manual of a package ``OtherPackage'', then you should
add the line
\begintt
\gdef\otherpackageManual{The OtherPackage Manual}
\endtt
& at the beginning of your main {\TeX} input file.
`\\biblitemfalse' & (default, same as in {\GAP} 4.4) In the bibliography,
print abbreviations for papers right-aligned
`\\biblitemtrue' & Print abbreviations left-aligned in the bibliography. d
Depending on the abbreviations you use, you may need more indentation.
You may set `\\bibindent' to another value (the present default is 3 pc)
if you get overfull `\\hbox'es. (This effect also exists if you use
`\\bibitemsfalse'
but there is not very obvious because long abbreviations will
protrude into the left margin only.)
`\\casesensitivefalse' & (default) labels are case insensitive
`\\casesensitivetrue' & makes labels case sensitive (this is still experimental
and not currently supported by the html converter)
\enditems
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Structuring the text: Chapters and Sections}
\indextt{\\Chapter}\indextt{\\Section}
The contents of each chapter must be in its *own* `.tex' file. The
command `\\Chapter\{<chaptername>\}' starts a new chapter named
<chaptername>; it should constitute the first non-comment (and non-blank)
line of the file containing a chapter. A chapter begins with an
introduction to the chapter and is followed by sections created with the
`\\Section\{<secname>\}' command. The strings <chaptername> and <secname>
are automatically available as references (see Section~"Labels and
References").
There must be *no further commands* on the same line as the `\\Chapter'
or `\\Section' line, and there *must* be an empty line after a
`\\Chapter' or `\\Section' command. This means that `\\index' commands
referring to the chapter or section can be placed only after this empty
line.
Finally, the HTML converter requires that each `\\Section' line is
preceded by a line starting with at least 16 percentage signs
(conventionally, one actually types a full line of percentage signs). The
HTML converter stops converting a section whenever it hits such a line;
therefore do not add lines starting with 16 or more \% signs which are
*not* just before a `\\Section' command. Failure to include the line of
percentage signs before a `\\Section' line will cause the converter to
crash, due to the discovery of what it sees as two `\\Section' commands
within the one section.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Suppressing Indexing and Labelling of a Section and Resolving
Label Clashes}
\indextt{\\null!use in index suppression}
Sometimes one does not wish a section to be indexed. To suppress the
indexing of a section, simply add the macro `\\null' after the
`\\Section' command, e.g.
\)\kernttindent\\Section\{<section-name>\}\\null
and then <section-name> will still generate a label (so that you can
still refer to it via `Section~\"<section-name>\"'), but <section-name>
will not appear in the index.
\indextt{\\nolabel!use in index and label suppression}
Occasionally, one has a dedicated section for the description of a single
function. If the label generated for the section coincides with the label
for a subsection (generated by a `\\>' command) a multiply defined label
results. In these cases, one would generally rather that the section did
not generate a label or an index entry. To suppress the generation of
both the label and the index entry of such a section, simply add the
macro `\\nolabel' immediately after the `\\Section' command, e.g.~for a
section dedicated to the function <func>:
\)\kernttindent\\Section\{<func>\}\\nolabel
*Note:* Labels are generated by converting to lowercase and removing
whitespace. So coincidences can occur when you might not have expected
it. An alternative to index suppression to resolve label clashes is to
include a sub-label for the function in the `\\>' command (see
Section~"TeX Macros").
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Labels and References}
Each `\\Chapter', `\\Section' and `\\>' command generates a (short) label
<label>, which is extended by <name-of-book> (the argument of
`\\BeginningOfBook' mentioned earlier in Section~"The Main File"), to
create a ``long label'' <long-label>, and emitted to a file `manual.lab'.
The construction of <long-label> is `<name-of-book>:<label>', where the
<label> generated by either of the commands `\\Chapter' or `\\Section' is
just its <chaptername> or <secname> argument. For `\\>', there are a few
cases to consider, and we'll consider them in Section~"TeX Macros", where
we meet the various forms of the `\\>' command. To see how to resolve
problems with label clashes see Section~"Suppressing Indexing and
Labelling of a Section and Resolving Label Clashes".
\index{reference to a label}
A reference to a label <any-label> (long or short) is made by enclosing
<any-label> in a pair of double quotation marks: `\"<any-label>\"'; it is
replaced by the number of the `\\Chapter', `\\Section' or `\\>' command
that generated <any-label> in the first place. Generally, one only needs
to make references to long labels when referring to other manuals. For
references within the same manual, short labels are sufficient, except
when the short label itself contains a colon.
*Example*
Since the `\\BeginningOfBook' command for this manual defines
<name-of-book> to be `gapmacro',
the long label for the current section is
`gapmacro:Labels and References'
and so a reference to this section within
this manual might be: `Section \"Labels and References\"' (which is
typeset as: Section "Labels and References"). From another manual, a long
label reference is required.
*Another example*
A section of this document has the title
``Structuring the text: Chapters and Sections'',
which contains a colon. Hence, to refer to that section, one *must* use a
long label:
\begintt
Section "gapmacro:Structuring the text: Chapters and Sections"
\endtt
produces: Section "gapmacro:Structuring the text: Chapters and Sections".
*Note*
In actual fact long labels are first sanitised by conversion to lower case
and removal of superfluous white space (multiple blanks and new lines are
converted to a single space). The same sanitisation process is applied to
references. Thus,
\begintt
Section "gapmacro:Structuring the text: Chapters
and Sections"
\endtt
also produces:
Section "gapmacro:Structuring the text: Chapters
and Sections".
So, don't worry about references to labels being broken over lines
and think of them as being case-insensitive, except that the HTML
converter requires that one respects case for the <name-of-book>
component of a long label.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{TeX Macros}
\indextt{\\lq}\indextt{\\pif}\indextt{\\rq}\indextt{\\accent127}
\indextt{\\>}\indextt{\\.}\indextt{.}\indextt{\\index}\indextt{\\indextt}
\indextt{\\atindex}\index{indexing commands}\index{command mark-up}
\index{subsection mark-up}\indextt{\\fmark}\indextt{\\kernttindent}
\indextt{\\URL}\indextt{\\Mailto}
\indextt{A!Attribute mark-up}\indextt{F!Function mark-up}
\indextt{P!Property mark-up}\indextt{O!Operation mark-up}
\indextt{C!Category mark-up}\indextt{R!Representation mark-up}
\indextt{V!(global) Variable mark-up}
\indextt{\\Package}\indextt{\\package}
As the manual pages are also used as on-line help, and are automatically
converted to HTML, the use of special {\TeX} commands should be avoided.
The following macros can be used to structure the text, the mentioned
fonts are used when printing the manual, however the on-line help and
HTML are free to use other fonts or even colour. Since, the plain text
on-line help, doesn't have special fonts, it leaves in much of the
markup, including the left and right quotes that surround something
intended to be displayed in typewriter type, the angle brackets that
surround something intended to appear in italics, and the dollar-signs
enclosing mathematics; you will need to keep that in mind when reading
the following section.
\beginitems
`\lq<text>\pif' &
sets <text> in `typewriter style'.
This is typically used to denote {\GAP} keywords such as `for' and
`false' or variables that are not arguments to a function, e.g.,
`{\lq}for\pif' produces `for'.
See also `\<<text>>'.
Use `\\\<' to get a ``less than'' sign.
`\lq\lq<text>\pif\pif' &
encloses <text> in double quotes,
e.g., `\lq{\lq}double-quoted text\pif\pif' produces
``double-quoted text''.
In particular, `\lq\lq<text>\pif\pif' does *not* set `\lq<text>\pif'
in typewriter style; use `{\lq\{{\lq}text\pif\}\pif}' to produce
`{`text'}'. Double quotes are mainly used to mark a phrase which will
be defined later or is used in an uncommon way.
`\\lq' &
sets a single left quote: `\lq'.
For a phrase <text> that is to be defined later or is used in an
uncommon way, please use `\lq\lq<text>\pif\pif' (which encloses <text>
in double quotes rather than single quotes).
`\\rq', `\\pif' &
each set a single apostrophe (right quote): `\pif'. For the HTML and
on-line manuals `\\accent19\{\}' also sets an apostrophe; however the
{\TeX}-derived manuals produce an acute-d blankspace (what it in fact
is).
`\\accent127' &
sets an umlaut, e.g. `\\accent127a' produces `\accent127a'. Do not
use the shorthand `\\\"' (otherwise the HTML converter will not
translate it properly).
`\<<text>>' &
sets <text> in italics. This can also be used inside `\$...\$' and
`{`...'}'. Use `\\\<' to get a ``less than'' sign. `\<...>' is used
to denote a variable which is an argument of a function; a typical
application is the description of a function:
\begintt
\>Group( <gens> ) F
The function `Group' constructs a group generated by <gens>.
\endtt
&
The `F' at the end of the first line in the above example indicates
that `Group' is a function (see the `\\>' entry, below).
`*<text>*' &
sets <text> in *emphasized style*.
`\$a.b\$' &
Inside math mode, you can use `.' instead of `\\cdot' (a centred
multiplication dot). Use `\\.' for a full stop inside math mode. For
example, `\$a.b\$' produces $a.b$ while `\$a\\.b\$' produces $a\.b$.
`\\cite\{...\}' &
produces a reference to a bibliography entry (the
`\\cite[...]\{...\}' option of La{\TeX} is *not* supported).
`"<label>"' &
produces a reference to <label>. Labels are generated by the commands
`\\Chapter', `\\Section' (see~"Labels and References"), and `\\>'
commands (see below).
`\\index\{<index-entry>\}' &
defines an index entry <index-entry>. Besides appearing in the index,
<index-entry> is also written to the section index file `manual.six'
used by the on-line help. An exclamation mark (`!'), if present, is
used to partition <index-entry> into main entry (left part) and
subentry (right part) components, in the index. {\TeX} converts
<index-entry> to lowercase and sets it in roman type, in the index.
The HTML converter respects case and uses the default font, in
producing the HTML manual index. <index-entry> must be completely
free of special characters and font changing commands; if you need
special fonts, characters or commands use one of `\\indextt' or
`\\atindex'.
& Note that for the HTML converter to process indexing commands
(`\\index', `\\indextt' and `\\atindex') correctly they *must* be on
lines of their own. There can be several indexing commands on the
same line, but there should be no horizontal whitespace before each
indexing command, and if an indexing command needs to be broken over
lines place a `\%' at the point of the break at the end of the line
to mark a ``continuation''.
& For the HTML converter it works best to put indexing commands all
together at the beginning of a paragraph, rather than strewn between
lines of a paragraph. However, for the {\TeX}-produced manuals after
a maths display one gets a rogue space if you do this (this is a
bug); you can work around the bug by putting at least one word of the
paragraph followed by your line(s) of indexing commands.
& *Note* also that indexing commands do *not* produce labels for
cross-references; they *only* produce entries for the index. Labels
are *only* produced by the chapter (`\\Chapter'), section
(`\\Section') and subsection (`\\>') commands.
`\\indextt\{<index-entry>\}' &
is the same as `\\index\{<index-entry>\}', except that <index-entry>
is set by {\TeX} in typewriter style, respecting case; the HTML
converter sets <index-entry> in the default font. Again,
<index-entry> should be completely free of special characters and
font changing commands, and `!' may be used for sub-entries in the
same way as for `\\index'. Note that a sub-entry component, if
present, is *not* set in typewriter style for the {\TeX}-produced
manuals; if you want that it is, use `\\atindex'.
`\\atindex\{<sort-entry>\}\{|indexit\}' &
is simply a special form of the `\\index' command that tells {\TeX}
to typeset the page number in italics.
`\\atindex\{<sort-entry>\}\{@<index-entry>\}' &
The HTML converter treats this command as if it was
`\\index\{<index-entry>\}', except that it strips out any font
information and sets it in the default font, but nevertheless
respects case. <index-entry> may have `|indexit' at the end which is
ignored by the HTML converter.
& The {\TeX}-produced manuals set the index entry as <index-entry>
respecting font and case, and list it according to <sort-entry>. If a
sub-entry is required then it should be present behind a `!' in
*both* the <sort-entry> and <index-entry>; the only difference
between the sub-entry in <sort-entry> and that in <index-entry>, is
that the <sort-entry> sub-entry should be stripped of mark-up and
font changing command. The <index-entry> component is ignored when
constructing the `manual.six' files, and is also ignored by the HTML
converter. Anything after an `!' in <sort-entry> is ignored when
constructing the `manual.idx' file that is processed by MakeIndex.
Macros like `\{\\GAP\}' are allowed in <index-entry>. However, any
`\lq' that appears in <index-entry> *must* be preceded by
`\\noexpand'; <sort-entry> must be completely free of special
characters and font changing commands.
& In general, one should make <sort-entry> the same as <index-entry>
modulo fonts and other mark-up, e.g.,
\begintt
\atindex{Fred!Nerk}{@\noexpand`Fred'!\noexpand`Nerk'}
\endtt
`\{\\GAP\}' &
typesets {\GAP}.
`\\package\{<pkg>\}' &
typesets <pkg> in the font correct for {\GAP} packages (respecting
case). This is intended for cross-referencing other {\GAP} packages.
There is also the command `\\Package\{<mypkg>\}' command which
defines a macro `\\<mypkg>' so that when you type `\{\\<mypkg>\}'
(please include the curly braces) the text <mypkg> is typeset in the
right way for {\GAP} packages. The `\\Package' command should normally
be included in one's `manual.tex' file (see~"The Main File") and just
allows one to type `\{\\<mypkg>\}' rather than the longer
`\\Package\{<mypkg>\}' as one is frequently likely to do when
formulating one's own {\GAP} package documentation. So, just to be
clear about the difference between `\\Package' and `\\package',
`\\Package\{<mypkg>\}' defines a macro `\\<mypkg>' but produces no
text, and `\\package\{<pkg>\}' produces <pkg> set in the font that is
right for {\GAP} packages.
`\\>' &
produces a subsection.
The line following the `\\>' entry must either contain another `\\>'
entry (in which case the further entries are assumed to be variants
and do not start a new subsection) or must be empty.
The description text will follow this empty line.
& There are several forms of the `\\>' command.
In all forms, a label and index entry are generated; the HTML
converter uses the label to form an index entry, respecting case
and setting in roman type.
If the next non-space character is not a left quote (`\lq') it is
assumed that the subsection is for a ``function''; we exhibit
these forms first.
`\\><func>' &
While this form is supported; it is discouraged. If <func> is a
0-argument function, <func> should be followed by an empty pair of
brackets (see `\\><func>(<args>)' below). If <func> is actually a
global variable then `\\>\lq<global-var>{\rq} V' should be used
instead (see below). In order for this form to be parsed correctly
the remainder of the line to the right of <func> must be empty. It
generates <func> as both a label and index entry; <func> appears as
is, in typewriter type in the {\TeX}-derived manual index.
`\\><func>(<args>)' &
The macro uses the brackets after <func> to parse the arguments
<args>. Thus, it is necessary for the function to use brackets and
for the arguments to have none. (We use the term ``function'' loosely
here to mean ``a {\GAP} command with arguments''; we really mean an
object that {\GAP} knows as a: ``Function'', ``Property'',
``Operation'', ``Category'', or ``Representation'' --- but not
``Variable'', since a ``Variable'' does not have arguments.) The
label and index entry generated consists of the text between the `>'
and opening bracket. The index entry is set as is (i.e.\ without
conversion to lowercase) in typewriter type in the {\TeX}-derived
manual index. Here is an example of how to use `\\>'; the index entry
is ```Size''' (in typewriter type, with mixed case preserved).
\begintt
\>Size( <obj> ) A
\endtt
& The `A' indicates that `Size' is an ``Attribute''. Instead of `A'
there can be `F', `P', `O', `C', or `R' which indicate that a command
is a ``Function'' (probably the most common), ``Property'',
``Operation'', ``Category'', or ``Representation'', respectively. For
the forms of the `\\>' command followed by a left quote, `V'
indicating ``Variable'' (an object without arguments), is also
possible. (See Section ``Manual Conventions'' and
Chapter ``Types of Objects'' in the {\GAP} Reference Manual).
`\\><func>(<args>)!\{<sub-entry>\}' &
This is a special form of the previous command, that forms a label
`<func>!<sub-entry>' and an index entry with main entry <func> (set
in typewriter type and respecting case) and sub-entry <sub-entry>
(set in roman type but also respecting case).
& The remaining forms of the command `\\>' expect to be followed by a
`\lq'.
`\\>\lq<command>\rq\{<label>\}' &
works as `\\>' without `\lq...\rq', but will not use bracket
matching; it simply displays <command> as a header, which appears in
typewriter type. It will use <label> as both the label and index
entry, and the index entry is set in roman type. Whenever <label>
contains a `!', it is used to partition <label> into main entry (left
part) and subentry (right part) components, in the index.
\begintt
\>`<a> + <b>'{addition}
\>`Size( <obj> )'{size} A
\endtt
& In the first of the examples immediately above, the first form of
`\\>' cannot be used because no brackets occur. Also, observe that
there is no command type (it's not appropriate here); {\TeX} does not
need it to correctly parse a `\\>' entry, in general. The second
example differs from our previous `Size' example, in that the index
entry will be typeset as ``size'' (in roman type), rather than
``{`Size'}''. Also, the index entry is always converted to lowercase,
no matter what case or mixed case was used.
`\\>\lq<command>\rq\{<label>\}!\{<sub-entry>\}' &
is equivalent to: `\\>\lq<command>\rq\{<label>!<sub-entry>\}'.
`\\>\lq<command>\rq\{<label>\}@\{<index-entry>\}' &
works as `\\>\lq<command>\rq\{<label>\}', except that it uses <label>
for sorting the index entry and the index entry itself is printed as
<index-entry>. References to the subsection use <label>. (Note that
the HTML converter ignores everything after an `@' symbol in these
commands, essentially treating the command as if it were
`\\>\lq<command>\rq\{<label>\}'. However, the HTML converter also
always preserves the case in a label. ) Here are two examples.
\begintt
\>`Size( <obj> )'{size}@{`Size'} A
\>`Size( GL( <n>, <q> ) )'{Size!GL( n, q )}@{`Size'! `GL'( \noexpand<n>, \noexpand<q> )} A
\endtt
& The first of these examples is equivalent to ``{`\\>Size( \<obj> )'}''.
For the second example, it was necessary to use `\lq' and `\rq',
since the argument contained brackets. Note that `\\noexpand' is
needed before `\<' here, but not needed before `\lq' in the
<index-entry> argument. Otherwise, the rules for sub-entries are the
same as for `\\atindex'.
`\\>\lq<global-var>{\rq} V' &
This is actually a short-hand for:
``{`\\>\lq<global-var>\rq\{<global-var>\}@\{\lq<global-var>\rq\} V'}''
to save you some typing when creating subsections for global
variables, i.e., <global-var> is the label and the index entry
appears in typewriter type, with mixed case preserved.
`\\)\{\\fmark ...\}' &
is like `\\>' except that it produces no label and index entry. It is
`\\fmark' that produces the filled in right arrow. Omitting it
produces a line in typewriter type.
`\\)\{\\kernttindent ...\}' &
is useful for producing a line in typewriter type, that you might
otherwise have typed between `\\begintt' and `\\endtt', but where you
actually want the {\TeX} macros and variables `\<...>' to be
interpreted.
`\\URL\{<url>\}' &
prints the WWW URL <url>. In the HTML version this will be a HREF link.
`\\Mailto\{<email>\}' &
prints the email address <email>. In the HTML version this will be a
`mailto' link.
\enditems
*Note:*
When a {\TeX} macro is followed by a space, {\TeX} generally swallows up
the space; one way, and it is the {\GAP}-preferred way, of preventing the
space being swallowed up, is by enclosing the macro in `\{...\}'. When a
macro is often followed by a space, it's a good habit to get into to
*always* enclose that macro in `\{...\}' (the braces do nothing when the
macro is not followed by a space, and prevent {\TeX} from swallowing up
the space, otherwise). Thus the macro for {\GAP} should *always* be typed
`\{\\GAP\}'. Similarly, macros like `\\lq', `\\rq' and `\\pif' should
probably always appear in braces; moreover the word ``don{\pif}t''
typeset via ``{`don\{\\pif\}t'}'' will actually be interpreted correctly
by the on-line browser.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{TeX Macros for Domains}
\indextt{\\N}\indextt{\\Z}\indextt{\\Q}\indextt{\\R}
\indextt{\\C}\indextt{\\F}\indextt{\\calR}
The following macros are required for the following common domains:
\beginlist
\item{`\\N'}
the natural numbers (you should probably indicate whether by your
convention $\N$ includes zero or not, when using this);
\item{`\\Z'}
the integers;
\item{`\\Q'}
the rational numbers;
\item{`\\R'}
the real numbers;
\item{`\\C'}
the complex numbers;
\item{`\\F'}
a field; and
\item{`\\calR'}
a general domain e.g.~a ring.
\endlist
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Examples, Lists, and Verbatim}
\index{list environment!description}
\indextt{\\beginitems}\indextt{\\enditems}
% produce itemized texts with 3pc hanging indentation
In order to produce a list of items with descriptions use the
`\\beginitems', `\\enditems' environment, i.e. this is a ``description''
environment in the parlance of La{\TeX} and HTML.
For example, the following list describes `base', `knownBase', and
`reduced'.
The different item/description pairs must be separated by blank lines.
\begintt
\beginitems
`base' &
must be a list of points ...
`knownBase' &
If a base for <G> is known in advance ...
`reduced' (default `true') &
If this is `true' the resulting stabilizer chain will be ...
\enditems
\endtt
This will be printed as
\beginitems
`base' &
must be a list of points ...
`knownBase' &
If a base for <G> is known in advance ...
`reduced' (default `true') &
If this is `true' the resulting stabilizer chain will be ...
\enditems
\index{list environment!compact description}
\indextt{\\beginlist}\indextt{\\endlist}\indextt{\\item}\indextt{\\itemitem}
In order to produce a list in a more compact format,
use the `\\beginlist', `\\endlist' environment.
An example is the following list.
\begintt
\beginlist
\item{(a)}
first entry
\item{(b)}
second entry
\itemitem{--}
a sub-item of the second entry
\itemitem{--}
another sub-item of the second entry
\item{(c)}
third entry
\endlist
\endtt
It is printed as follows.
\beginlist
\item{(a)}
first entry
\item{(b)}
second entry
\itemitem{--}
a sub-item of the second entry
\itemitem{--}
another sub-item of the second entry
\item{(c)}
third entry
\endlist
\index{list environment!unordered}\index{list environment!ordered}
The above example will take advantage of the ordered and unordered list
environments in the HTML version, with the addition of slightly more mark-up.
First, we present the example again with that additional mark-up, and then
we explain how it works.
\begintt
\beginlist%ordered{a}
\item{(a)}
first entry
\item{(b)}
second entry
\itemitem{--}%unordered
a sub-item of the second entry
\itemitem{--}
another sub-item of the second entry
\item{(c)}
third entry
\endlist
\endtt
It is printed as follows (of course, you should see no difference in the
{\TeX}-produced and on-line versions of this manual).
\beginlist%ordered{a}
\item{(a)}
first entry
\item{(b)}
second entry
\itemitem{--}%unordered
a sub-item of the second entry
\itemitem{--}
another sub-item of the second entry
\item{(c)}
third entry
\endlist
In the HTML version the above example is interpreted as a nested list. The
outer list is interpreted as an *ordered* list. The HTML standard provides
5 different types of ordered list, and these mirror the types provided by the
`enumerate' La{\TeX} package. To signify that the outer list was *ordered*
the comment `\%ordered' was added after `\\beginlist'. If there is no further
markup the list is numbered in the default manner, namely with integers.
Otherwise, following `\%ordered' there should be one of the following:
\beginlist
\item{`\{1\}'}
indicates the list should be numbered with integers (the default obtained
when there is nothing following `\%ordered');
\item{`\{a\}'}
indicates the list should be numbered with lowercase letters (`a', `b',
\dots);
\item{`\{A\}'}
indicates the list should be numbered with uppercase letters (`A', `B',
\dots);
\item{`\{i\}'}
indicates the list should be numbered with lowercase roman numerals (`i', `ii',
\dots); and finally
\item{`\{I\}'}
indicates the list should be numbered with uppercase roman numerals (`I', `II',
\dots).
\endlist
The `\\beginlist' of the above example was followed by `\%ordered\{a\}' and
so the list is numbered using lowercase letters in the HTML version and using
the ordered list environment (rather than the description environment).
Occasionally, it is necessary to break from a list, add some explanatory
text and then restart the list, and resume numbering the items from where
you left off. To do this follow the comment mark-up already mentioned by an
*integer* in curly braces, i.e.~if the outer list should actually start at
`c' then you would need to have `\%ordered\{a\}\{3\}' after `\\beginlist'
because `c' is the 3rd letter of our alphabet. Note that, for an
integer-numbered list not starting at 1, you must have the full markup; you
cannot omit the `\{1\}' after `\%ordered' in this case.
The inner list of the above example is an *unordered* list (this corresponds
to a plain `itemize' environment in La{\TeX}). To indicate this the first
`\\itemitem' above was followed by `\%unordered'.
Of course, to get an unordered outer list, one would start the list with
`\\beginlist\%ordered', and to get an ordered inner list numbered with
lowercase letters the first `\\itemitem' would need to be followed by
`\%ordered\{a\}', i.e.~the same syntax is used for the comment added after
a `\\beginlist' and after the first `\\itemitem' in a sequence of
`\\itemitem's.
*Notes*
\beginlist%ordered
\item{1.} Only lists to a maximum depth of two are supported.
\item{2.} You cannot change the type of a sublist halfway through. Only
the comment after the first `\\itemitem' in a sequence is interpreted.
\endlist
\index{verbatim environments}
\indextt{\\begintt}\indextt{\\endtt}
\indextt{\\beginexample}\indextt{\\endexample}
% verbatim text in typewriter style
There are two types of *verbatim* environments.
Example {\GAP} sessions are typeset in typewriter style
using the `\\beginexample', `\\endexample' environment.
Make sure that`\\beginexample', `\\endexample', `\\begintt'
and `\\endtt' are on lines of their own.
\begintt
\beginexample
gap> 1+2;
3
\endexample
\endtt
typesets the example
\beginexample
gap> 1+2;
3
\endexample
All examples in a chapter will also be written to files with the extension
`.example-<chapno>.tst', where <chapno> is the chapter number. These `.tst'
files can be used to verify the examples in the manual. See
"Testing the Examples" below for details.
\indextt{\\beginexample!indicating unstable output}
Examples whose output may vary can be excluded from these test files, by
using the command `\\testexamplefalse', e.~g.
\begintt
\testexamplefalse
\beginexample
gap> Exec("date");
Sun Oct 7 16:23:45 CEST 2001
\endexample
\endtt
`\\testexamplefalse' is only valid for the example immediately following.
Non-{\GAP} examples should be typeset in typewriter style
using the `\\begintt', `\\endtt' environment.
*Notes*
\beginlist%ordered
\item{1.}
The manual style will automatically indent examples. It also will break
examples which become too long to fit on one page. If you want to encourage
breaks at specific points in an example, end the example with `\\endexample'
and immediately start a new example environment with `\\beginexample' on
the next line.
\item{2.}
To typeset a pipe symbol `|' in the `\\begintt', `\\endtt' environment or
`\\beginexample', `\\endexample' you need to actually type `||'.
\endlist
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Tables, Displayed Mathematics and Mathematics Alignments}
\index{tables}\index{mathematics displays}\index{mathematics alignments}
\indextt{\\matrix}
Tables should normally be set using the `\\begintt', `\\endtt'
environment. This means that one should enter the appropriate white space
so that columns line up. Note that to get a vertical line `|' in the
`\\begintt', `\\endtt' environment one must actually type `||'. The
reason for setting tables this way is so that both the HTML converter and
{\GAP}'s built-in text browser have no trouble in displaying them
correctly.
The HTML converter when used with its `-t' option (which causes it to use
TtH to translate mathematics) usually does a reasonable job of converting
mathematics displays and mathematics alignments. To help {\GAP}'s
built-in text browser, however, one should follow a few rules:
\beginlist%unordered
\item{--} Place the `\$\$'s that begin and end the mathematics display on
lines of their own. (If you don't do this it will be displayed in the
same way as ordinary in-line mathematics.)
\item{--} Use only the `\\matrix\{ .. \}' environment for mathematics
alignments. The `\\matrix\{' starting the alignment should be on a line
on its own, (flush left and no trailing whitespace). The `\}' closing the
environment should also be on a line of its own. The built-in browser
doesn't do anything special to line things up; you must insert the
whitespace where it's needed. Any `\\hfill' macros you add to help the
line things up in the {\TeX} and HTML formats is ignored by the {\GAP}'s
built-in text browser. The `\\matrix\{ .. \}' environment should be used
even when one might like to use {\TeX}'s `\\cases\{ .. \}' environment.
\endlist
The following example shows a typical usage of the `\\matrix\{ .. \}'
environment (in particular, it shows how one can use it to avoid using
the `\\cases\{ .. \}' environment). Observe, how sufficient whitespace
has been added in order that alignment is maintained by {\GAP}'s built-in
text browser. (Recall that `\\right.' which produces nothing is required
to match `\\left\\\{'.)
\begintt
From a theorem of Gauss we know that
$$
b_N = \left\{
\matrix{
\frac{1}{2}(-1+\sqrt{N}) &{\rm if} &N \equiv 1 &\pmod 4\cr
\frac{1}{2}(-1+i \sqrt{N}) &{\rm if} &N \equiv -1 &\pmod 4\cr
}
\right.
$$
\endtt
The example produces \dots
From a theorem of Gauss we know that
$$
b_N = \left\{
\matrix{
\frac{1}{2}(-1+\sqrt{N}) &{\rm if} &N \equiv 1 &\pmod 4\cr
\frac{1}{2}(-1+i \sqrt{N}) &{\rm if} &N \equiv -1 &\pmod 4\cr
}
\right.
$$
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Testing the Examples}
Ideally, the {\GAP} examples (the text between `\\beginexample'
and `\\endexample') should be chosen such that every user obtains the
same output (up to line breaks and whitespace) when typing in your example.
This is often difficult to achieve, or can only be achieved at the cost of
writing unnecessarily complicated examples. Therefore, it is recommended that
you choose examples in such a way that when a user starts {\GAP}, loads your
package and types the examples of a chapter in the given order, then (s)he will
see the same output as in the manual examples. (This will ensure that the
global random number generator is initialized to the *same* values.
For more details,
see the last paragraph of ``Starting and Leaving GAP''
in the {\GAP} Tutorial.)
In cases where this is
impossible, you may use `\\testexamplefalse' before `\\beginexample', see
"Examples, Lists, and Verbatim".
As mentioned above, a {\TeX} run of the manual produces files
`manual.example-<chapno>.tst', one for each chapter containing at least
one {\GAP} example (the text between `\\beginexample'
and `\\endexample'). These files can be read into {\GAP} using `ReadTest'
(see `?ReadTest'), to ensure that the {\GAP} output for the examples
hasn't changed.
The test also requires that examples are not indented
in the {\TeX} files; in the typeset manual,
the lines between `\\beginexample' and `\\endexample'
and the lines between `\\begintt' and `\\endtt' are automatically
indented.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Usage of the Percent Symbol}
\indextt{\%}
The `\%' symbol has a number of very specific uses. Take care that you
use it correctly. These uses are:
\beginlist%ordered
\item{1.}
A line *beginning* with 16 (or more) `\%' symbols marks the *end* of a
section, or the *end* of a chapter introduction (which may be empty).
Such a line *must* precede *every* `\\Section'
(see~"gapmacro:Structuring the text: Chapters and Sections").
\item{2.}
A `\%' at the beginning of a line tells {\TeX} that the line is a comment
and is to be ignored by {\TeX}, *except* in the verbatim environments:
`\\begintt..\\endtt' and `\\beginexample..\\endexample'. However,
`\%display' or `\%enddisplay' commands have special meaning for the
on-line text help browser and for the HTML converter and may temporarily
alter the meaning of an initial `\%' for these (see~"Catering for Plain
Text and HTML Formats" for details); otherwise the meaning of an initial
`\%' is the same as for {\TeX}.
\index{continuation}
\item{3.}
A `\%' at the end of a line marks a ``continuation'', *except* in the
situation mentioned in item 4. A ``continuation'' may be needed for lines
of indexing commands (`\\index', `\\indextt' or `\\atindex'). Such
commands *must* occur on lines of their own (see~"TeX Macros"), *not*
mixed with text, and there must not be any superfluous whitespace (modulo
the next statement). Occasionally an indexing command is too long to
easily fit on a line; this is where a continuation is desirable; a `\%'
at the end of such a line indicates that the line is to be joined with
the next line after removal of the `\%' symbol and any initial whitespace
on the next line (this is what {\TeX} does! \dots~and we mimic this
behaviour for both the on-line text help browser and the HTML manuals).
A ``continuation'' may also be necessary for subsections, i.e.~lines
beginning with `\\>' or `\\)' (again see~"TeX Macros"); the usage is as
for indexing line continuations.
\item{4.}
A line ending with a `\%' that is not an indexing command line or a
subsection line that after any initial whitespace is removed matches
*exactly* `\{\%' or `\}\%', or begins with `\{\\' or `\\' and is followed
by a letter, is ignored by both the on-line browser and the HTML
converter. This is intended to screen the on-line browser and HTML
converter from {\TeX} commands such as `\\obeylines', `\\begingroup',
`\\def' etc., without having to resort to using the
`\%display\{tex\}..\%enddisplay' environment.
\endlist
*Warning.* In view of items 3.~and 4.~above, avoid using a `\%' at the
end of a line unless you really need it, and it fits into those
categories. In particular, do *not* put a `\%' at the end of an indexing
command line that is immediately followed by a line of text; otherwise,
the text line will not appear in the HTML manual or on-line via the text
help browser. Similarly, do not put a `\%' line at the end of a text line
that is immediately followed by an indexing command line; this causes the
indexing command line to be ignored by the HTML converter. For the HTML
converter it works best to put indexing commands all together at the
beginning of a paragraph, rather than strewn between lines of a
paragraph. However, for the {\TeX}-produced manuals after a maths display
one gets a rogue space if you do this (this is a bug); you can work
around the bug by putting at least one word of the paragraph followed by
your lines(s) of indexing commands.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Catering for Plain Text and HTML Formats}
\indextt{\%display}\indextt{\%enddisplay}
As described in~"TeX Macros", the use of macros should be restricted to
the ones given in the previous sections. By doing so, you should find
that the documentation you write will still look ok in {\GAP}'s on-line
help (plain text format) and in the translated HTML. However, in rare
situations one might be forced to use other {\TeX} macros, for example in
order to typeset a lattice. In this case you should provide an
alternative for the on-line help, and possibly also for the HTML version.
This can be done by putting in guiding commands as {\TeX} comments:
\begintt
%display{tex}
TeX version (only used by TeX manual)
%display{html}
%HTML version (only used by HTML manual)
%display{text}
%Text version (only used by the built-in manual browser)
%enddisplay
\endtt
Observe that the lines that should appear only in the {\TeX}-produced
manuals do not begin with a `\%'. For the HTML (resp.~text) version the
lines begin with a `\%'; each line of a `\%display\{html\}'
(resp.~`\%display\{text\}') environment is printed verbatim, after
removing the initial `\%' symbol. The above example produces:
%display{tex}
TeX version (only used by TeX manual)
%display{html}
%HTML version (only used by HTML manual)
%display{text}
%Text version (only used by the built-in manual browser)
%enddisplay
(Note the above example will vary according to whether you are viewing it
as a {\TeX}-produced manual, or as an HTML manual, or via the built-in
manual browser --- as it should!)
Sometimes one needs a `\%display' environment to be not seen by {\TeX},
but still interpreted normally (i.e.~not printed verbatim). The following
variant of the above provides this capability.
\begintt
%display{tex}
TeX version (only used by TeX manual)
%display{nontex}
%HTML and Text version (interpreted normally, after removing the \% symbol)
%enddisplay
\endtt
The above example produces:
%display{tex}
TeX version (only used by TeX manual)
%display{nontex}
%HTML and Text version (interpreted normally, after removing the \% symbol)
%enddisplay
It is permissible to abbreviate any of the above by omitting
`\%display\{tex\}', `\%display\{html\}', or `\%display\{text\}' if that
portion of the environment would be empty.
There are yet two more variants of conditional display. Firstly,
\begintt
%display{nonhtml}
%Text version (interpreted normally by built-in browser, after removing the
%\% symbol)
%enddisplay
\endtt
is normally used to ensure text only appears via the on-line help
browser. If there is no initial `\%' it also appears in the
{\TeX}-produced manuals. The above example produces:
%display{nonhtml}
%Text version (interpreted normally by built-in browser, after removing the
%\% symbol)
%enddisplay
Finally, there is
\begintt
%display{nontext}
%HTML version (interpreted normally by HTML converter, after removing the
%\% symbol)
%enddisplay
\endtt
which excludes text from the on-line help browser. Like the
`\%display\{nonhtml\}' environment, if there is no initial `\%' it also
appears in the {\TeX}-produced manuals. The example produces:
%display{nontext}
%HTML version (interpreted normally by HTML converter, after removing the
%\% symbol)
%enddisplay
However, the use of these special environments should be avoided as much
as possible, since it is much more difficult to maintain such
pseudo-duplicated documentation.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Umlauts}
To produce umlauts, use `\\accent127' and not the shorthand `\\\"'
(otherwise the HTML converter will not translate it properly).
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Producing a Manual}
\indextt{manual.tex}\indextt{manual.mst}\indextt{manualindex}
\indextt{manual.six}\indextt{manual.dvi}\indextt{makeindex}\indextt{bibtex}
\indextt{manual.lab}\indextt{manual.bib}\indextt{manual.bbl}
To produce a manual you will need the following files:
\beginitems
`manual.tex'&
contains the body of the manual
(as described in Section~"The Main File")
and an `\\Input' command for each chapter/appendix file.
`<file1>.tex', `<file2>.tex', \dots &
the chapter/appendix files. There must be one file for each chapter
or appendix, and each such file should have a `\\Chapter' or
`\\PreliminaryChapter' command. Alternatively, one can write
`.msk' files and use `buildman.pe' to generate the corresponding
`.tex' files (see~"Using buildman.pe").
`gapmacro.tex'&
contains the macros for the manual.
It must be input by an `\\input' statement (*not* and `\\Input'
statement, which creates a Table of Contents entry) in `manual.tex'.
You can either use the version in the `doc' directory of {\GAP}
(use a relative path then) or make a copy.
`manual.mst'&
is a ``configure'' file used by `makeindex' when processing
index information in a {\TeX}-generated and `manualindex'-preprocessed
`manual.idx' file.
It must reside in your manual directory.
`GAPDOCPATH/manualindex'&
is used to call `makeindex'.
`GAPDOCPATH' is the path of the `doc' directory of your {\GAP}
distribution.
\enditems
For bibliography information you will need a file `manual.bbl'. If you
intend to create it with Bib{\TeX}, you will need to indicate the
appropriate `.bib' file (as described in section "The main file"). Then
after running {\TeX} once over the manual, run Bib{\TeX} to create the
`manual.bbl' file.
Assuming that all necessary files are there (a `manual.lab' file for each
<book> argument of a `\\UseReferences' command, `mrabbrev.bib' and
`manualindex' in the {\GAP} `doc' directory),
on a Unix system the following calls will then produce a file `manual.dvi'
as well as a file `manual.six' which is used by the {\GAP} help functions.
If you are missing some of the needed files and don't have `CVS' access to
{\GAP}, just send an email request for them to
\Mailto{support@gap-system.org}.
Go to the directory holding the manual. Call
\begintt
tex manual
\endtt
to produce bibliography information. Unless you provide a `manual.bbl' file
which is not produced by Bib{\TeX}, call
\begintt
bibtex manual
\endtt
to produce the `manual.bbl' file. Then run {\TeX} twice over the manual to
fill all references and produce a stable table of contents:
\begintt
tex manual
tex manual
\endtt
If you have sections which are named like commands, you may get messages
about redefined labels. At this point you can ignore these.
Now it is time to produce the index. Call
\begintt
GAPDOCPATH/manualindex manual
\endtt
which preprocesses the `manual.idx' file and then
runs `makeindex'. Provided that `manual.mst' exists, this produces a file
`manual.ind'. Finally, once again run
\begintt
tex manual
\endtt
to incorporate the index. The manual is ready.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Using buildman.pe}
\indextt{buildman.pe}\indextt{\\Declaration}\indextt{\\FileHeader}
Rather than write the chapter/appendix `.tex' files directly, one may
incorporate one's documentation in comments in one's {\GAP} code. To do
it this way, there are four ingredients:
\beginitems
`.gd' files &
{\GAP} files with `.gd' suffixes that have the documentation in comments
(actually files with `.g' or `.gi' or any other extension are also
possible, but files with extension `.gd' are the default);
`.msk' files &
which are just like the `.tex' files, and must obey all the rules given
for `.tex' files previously, but additionally may have `\\FileHeader' or
`\\Declaration' commands at places where text should be inserted from a
`.gd' file, and with `\{\{<variable>\}\}' patterns which are replaced by
<replacement> when written to the `.tex' file, if the configuration file
<configfile> has a line of form: `<variable>=<replacement>';
<configfile> &
a file which defines `msfiles' (the list of `.msk' files), `gdfiles' (the
list of `.gd' files), `LIB' (the directory containing the `.gd' files),
`DIR' (the directory in which to put the constructed `.tex' files, one
`.tex' file for each `.msk' file), and optionally a line `check' (see
below) and `<variable>=<replacement>' lines; and
`buildman.pe' &
a perl program (in the `etc' directory for those with `CVS' access to
{\GAP}), which strips the comments from the `.gd' files according to the
`\\FileHeader' or `\\Declaration' commands in the `.msk' files,
translates any `\{\{<variable>\}\}' patterns defined by the file
<configfile> and constructs the `.tex' files.
\enditems
If you don't have `CVS' access and want to use `buildman.pe', just email
\Mailto{support@gap-system.org} and ask for it. Please note that
there is no obligation for package authors to `buildman.pe'; nor does it
attract the same level of support as the rest of {\GAP}; in general, bugs
can be expected to be fixed (eventually), but no new features will be
added. Also, note that the \package{GAPDoc} package provides a similar
facility.
The perl program `buildman.pe' is called as follows:
\){\kernttindent}buildman.pe -f <configfile>
*The form of <configfile>*
There is no restriction on how to name <configfile>, but by convention it
is of form `config.<something>' or `buildman.config'; <configfile> should
contain lines of form:
\){\kernttindent}msfiles=<msfile1>,<msfile2>,...,<msfilem>;
\){\kernttindent}gdfiles=<gdfile1>,<gdfile2>,...,<gdfilen>;
\){\kernttindent}LIB=<gdfile_dir>;
\){\kernttindent}DIR=<TeX_dir>;
Optionally, as mentioned above, one may also have:
\){\kernttindent}check;
which says to construct a `notfound' file that lists missing expected
data, and any number of lines of form
\){\kernttindent}<variable>=<replacement>
\goodbreak%
The file <configfile> should obey the following syntactic rules:
\beginlist%unordered
\item{--}
After `msfiles=' there should be a comma-separated and
semicolon-terminated list of `.msk' files with the `.msk' extensions
removed; `buildman.pe' assumes that the `.msk' files are all in, or at
least have path relative to, the directory in which `buildman.pe' is
called.
\item{--}
Similar to the `msfiles' definition, after `gdfiles=' there should be a
comma-separated and semicolon-terminated list of ```.gd''' files. If a
```.gd''' file really does have a `.gd' extension, it may be listed
without extension; otherwise the extension *must* be included. All the
```.gd''' files must be listed with path relative to the directory
defined by `LIB'.
\item{--}
For both the `msfiles' and `gdfiles' definitions, the lists following the
`=' may continue over several lines if necessary, and any whitespace,
parentheses (round brackets) or double-quotes characters are ignored.
\item{--}
The paths after `LIB=' and `DIR=' are assumed relative to the ``current
directory'', i.e. the directory in which `buildman.pe' is executed. For
each <msfilei> listed after the `msfiles' keyword, `buildman.pe'
constructs from `<msfilei>.msk' a corresponding `<msfilei>.tex' in
<TeX_dir>. The `LIB' and `DIR' definitions must be on a single line.
\item{--}
The terminating `;' is optional on the lines containing the keywords
`LIB', `DIR' or `check'.
\item{--}
Superfluous characters around any of the keywords `msfiles', `gdfiles',
`LIB', `DIR' or `check', but before the `=' on the lines where `=' is
required, are ignored. Whitespace and double-quotes characters are
ignored, everywhere.
\item{--}
The `<variable>=<replacement>' lines (if there are any) should have no
other punctuation or whitespace. These lines direct `buildman.pe' to
replace any string of form `\{\{<variable>\}\}' in a `.msk' file with
<replacement>.
\endlist
*Special `.msk' file commands*
Now we describe the special (non-{\TeX}) commands that direct
`buildman.pe' to extract text from ```.gd''' files.
\beginitems
`\\FileHeader[<n>]\{<gdfile>\}' &
This command is replaced by the text following a `\#<n>' line (for
positive integer <n>) in file `<gdfile>.gd' (or <gdfile> if <gdfile>
already contains a suffix). The argument `[<n>]' of `\\FileHeader' is
optional; if it is omitted <n> is taken to be 1. See below for the
typical form of a fileheader extracted by the `\\FileHeader' command; the
comments in the example describe its required format.
`\\Declaration\{<func>\}[<gdfile>]\{<label>\}!\{<sub-entry>\}@\{<index-entry>\}' &
This command is replaced by a `\\>' subsection declaration or block of
`\\>' declarations, and their description extracted from a block in a
```.gd''' file that starts with a line matching `\#<X> <func>', for some
letter <X> in `F', `M', `A', `P', `O', `C', `R' or `V'. The line
``matches'' if there is a `(', space, or newline after <func>. The
argument <func> (in `\{..\}') is the only mandatory argument.
&
If present, `[<gdfile>]', says that <func> is to be found in the file
`<gdfile>.gd' (or <gdfile> if <gdfile> already contains a suffix); it is
required only if <func> appears in more than one of the ```.gd''' files
listed in the file <configfile>. The <gdfile> argument is typically
required for distinguishing methods of operations.
&
The remaining arguments (if present) have exactly the purpose that they
have in subsection declarations, i.e.~lines of the following forms:
\)\kernttindent\\><func>!\{<sub-entry>\}
\)\kernttindent\\>\lq<command>\rq\{<label>\}
\)\kernttindent\\>\lq<command>\rq!\{<sub-entry>\}
\)\kernttindent\\>\lq<command>\rq@\{<index-entry>\}
&
(see Section~"TeX Macros"), and are used to build subsection declaration
lines of these forms. Note that the <label>, <sub-entry> and
<index-entry> arguments, if needed, should follow the `\\Declaration'
command (and *not* be in the ```.gd''' file `\#<X> <func>...' lines,
where they will be indistinguishable from comments). If in the ```.gd'''
file the `\#<X> <func>' line is followed by other `\#<Xi> <funci>' lines,
then each `\\>' subsection declaration formed has the same <label>,
<sub-entry> and <index-entry> arguments appended.
\enditems
Corresponding to `\\FileHeader[<n>]\{<gdfile>\}', in the ```.gd''' file
denoted by <gdfile>, there should be:
\)\kernttindent\#<n>
\)\kernttindent\#\#\ \ Text for \\FileHeader[<n>]\{<gdfile>\}. Each line
\)\kernttindent\#\#\ \ should have two \# characters followed by 2 blank
\)\kernttindent\#\#\ \ space characters at the left margin. The text
\)\kernttindent\#\#\ \ can and should include any necessary \{\\TeX\}
\)\kernttindent\#\#\ \ mark-up and indexing commands.
\)\kernttindent\#\#
\)\kernttindent\#\#\ \ A fileheader may consist of any number of paragraphs.
\)\kernttindent\#\#\ \ It is terminated by a totally empty line (i.e.~a
\)\kernttindent\#\#\ \ line devoid even of \# characters).
\)\kernttindent\#\#
Corresponding to each `\\Declaration\{<func>\}...' line of a `.msk' file
there should be in one of the ```.gd''' files, a block of form:
\)\kernttindent\#<X>\ \ <func>( <args> ) <comment>
\)\kernttindent\#<Y>\ \ <func2>( <args2> ) <comment2>
\)\kernttindent.
\)\kernttindent.
\)\kernttindent\#<Z>\ \ <funcn>( <argsn> ) <commentn>
\)\kernttindent\#\#
\)\kernttindent\#\#\ \ description of <func>, <func2>, ..., <funcn>.
\)\kernttindent\#\#
\){\kernttindent}Declare...( "<func>" ...);
\){\kernttindent}Declare...( "<func2>" ...);
\)\kernttindent.
\)\kernttindent.
\){\kernttindent}Declare...( "<funcn>" ...);
The above block should comply with the following syntactic rules. Below
we use the term ``function'' in a general sense to mean any one of
function (in the strict sense), attribute, category, method,
representation, operation, property or variable.
\beginlist%unordered
\item{--}
$<X>, <Y>, \dots, <Z> \in \{ `A', `C', `F', `M', `R', `O', `P', `V' \}$.
If the letter is `V' then no parentheses or arguments should follow the
``function name'' <funci>.
\item{--}
The letters, <X>, <Y>, \dots, <Z> are printed in the manual. If a letter
is `A' or `P', then also the letters `S' and `T' are printed if the
setter and the tester are available. If the letter is `A', then the
letter `M' is printed if the attribute is mutable.
\item{--}
The comments <comment>, <comment2>, \dots, <commentn> (by convention
starting with spaced dots) which do not appear in the manual, are
optional.
\item{--}
The <X>, <Y>, \dots, <Z> ``function name'' lines must appear on
consecutive lines, i.e.~not intermingled with text lines.
\item{--}
After the ``function name'' lines there should be text lines describing
the ``functions''. As with fileheader text these text lines should
contain any {\TeX} mark-up and indexing commands that are necessary, and
there should be two blank space characters between the `\#\#' and the
text. Lines starting with `\#T' (or some other non-`\#' character in
place of `T') are ignored.
\item{--}
It is assumed that for each ``function name'' <func>, <func2>, \dots,
<funcn> there is a corresponding {\GAP} declaration (which need not be
via a `Declare...' command, e.g.~it might be `BindGlobal') after the
`\#\#' text lines (and comment lines), *and* that they appear in the
*same* order.
\endlist
\goodbreak%
*Example*
Suppose we have a manual whose `.msk' files are in the directory `doc/build',
whose `.tex' files are created in the directory `doc/ref',
and whose {\GAP} code files are in the directory `lib',
one of them being the file `lib/algebra.gd',
which contains the following declaration:
\begintt
#############################################################################
##
#O DirectSumOfAlgebras( <A1>, <A2> )
#O DirectSumOfAlgebras( <list> )
##
## is the direct sum of the two algebras <A1> and <A2> respectively of the
## algebras in the list <list>.
##
## If all involved algebras are associative algebras then the result is also
## known to be associative.
## If all involved algebras are Lie algebras then the result is also known
## to be a Lie algebra.
##
## All involved algebras must have the same left acting domain.
##
## The default case is that the result is a structure constants algebra.
## If all involved algebras are matrix algebras, and either both are Lie
## algebras or both are associative then the result is again a
## matrix algebra of the appropriate type.
##
DeclareOperation( "DirectSumOfAlgebras", [ IsDenseList ] );
\endtt
Further suppose that the file `doc/build/algebra.msk' contains the line:
\begintt
\Declaration{DirectSumOfAlgebras}
\endtt
The ``config'' file `doc/build/config.alg':
\begintt
@msfiles = ("algebra","algfp","alglie","mgmring");
@gdfiles = ("algebra","alghom","alglie","object","liefam","mgmring","algrep",
"lierep");
DIR = "../ref";
LIB = "../../lib";
\endtt
specifies `algebra.msk' via the first entry of `msfiles' and
`lib/algebra.gd' via the first entry of `gdfiles' and (its directory by)
the definition of `LIB'. Observe that there are `@' and `"' symbols, as
well as parentheses and whitespace, in the above ``config'' file; *none*
of these is necessary, but they don't do any harm either. Generally, one
calls `buildman.pe' in the same directory that contains the `msfiles'
(which is why one doesn't need to specify the directory containing the
`msfiles') and the ``config'' file. Since `DIR = "../ref"', `buildman.pe'
constructs `algebra.tex' from `algebra.msk' in directory `doc/ref'. The
subsection generated in `algebra.tex' by the above `\\Declaration'
command starts with the header:
\begintt
\>DirectSumOfAlgebras( <A1>, <A2> ) O
\>DirectSumOfAlgebras( <list> ) O
\endtt
and is followed by its description, i.e.~the lines beginning with two
hashes and two blanks, but with the hashes and blanks stripped away, so
that when it is processed the resulting subsection appears as:
\){\fmark}DirectSumOfAlgebras( <A1>, <A2> )\hfill O
\){\fmark}DirectSumOfAlgebras( <list> )\hfill O
is the direct sum of the two algebras <A1> and <A2> respectively of the
algebras in the list <list>.
If all involved algebras are associative algebras then the result is also
known to be associative.
If all involved algebras are Lie algebras then the result is also known
to be a Lie algebra.
All involved algebras must have the same left acting domain.
The default case is that the result is a structure constants algebra.
If all involved algebras are matrix algebras, and either both are Lie
algebras or both are associative then the result is again a
matrix algebra of the appropriate type.
*Variable replacement*
As mentioned above the ``config'' file may also contain lines that assign
variables, e.g.
\begintt
versionnumber=4.3
versionsuffix=4r3
\endtt
Occurrences of these variables in double curly braces will be replaced by
their value. For example the lines
\begintt
When `unzoo -x' is applied to {\GAP}~{{versionnumber}}'s `zoo' file
`gap{{versionsuffix}}.zoo' a directory `gap{{versionsuffix}}' is formed.
\endtt
in a `.msk' file will be replaced by:
\begintt
When `unzoo -x' is applied to {\GAP}~4.3's `zoo' file
`gap4r3.zoo' a directory `gap4r3' is formed.
\endtt
in the corresponding `.tex' file.
This feature is very handy for information that changes over time.
*Final note*
There is a document for version `0.0' of `buildman.pe' that describes
features that have either never been used or have since been disabled.
Only the features described in this section can be relied upon to have
currency.
\EndOfBook
|