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
|
<?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 (Utils) - Chapter 1: Introduction</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="chap1" 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="chap8.html">8</a> <a href="chap9.html">9</a> <a href="chap10.html">10</a> <a href="chap11.html">11</a> <a href="chap12.html">12</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="chap0.html">[Previous Chapter]</a> <a href="chap2.html">[Next Chapter]</a> </div>
<p id="mathjaxlink" class="pcenter"><a href="chap1_mj.html">[MathJax on]</a></p>
<p><a id="X7DFB63A97E67C0A1" name="X7DFB63A97E67C0A1"></a></p>
<div class="ChapSects"><a href="chap1.html#X7DFB63A97E67C0A1">1 <span class="Heading">Introduction</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap1.html#X8508AD637B79CEE8">1.1 <span class="Heading">Information for package authors</span></a>
</span>
</div>
</div>
<h3>1 <span class="Heading">Introduction</span></h3>
<p>The <strong class="pkg">Utils</strong> package provides a space for utility functions from a variety of <strong class="pkg">GAP</strong> packages to be collected together into a single package. In this way it is hoped that they will become more visible to other package authors. This package was first distributed as part of the <strong class="pkg">GAP</strong> 4.8.2 distribution.</p>
<p>The package is loaded with the command</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">LoadPackage( "utils" ); </span>
</pre></div>
<p>Functions have been transferred from the following packages:</p>
<ul>
<li><p>Conversion of a <strong class="pkg">GAP</strong> group to a <span class="SimpleMath">Magma</span> output string, taken from various sources including <code class="file">other.gi</code> in the main library.</p>
</li>
</ul>
<p>Transfer is complete (for now) for functions from the following packages:</p>
<ul>
<li><p><strong class="pkg">AutoDoc</strong> <a href="chapBib.html#biBAutoDoc">[GH16]</a> (with function names changed);</p>
</li>
<li><p><strong class="pkg">ResClasses</strong> <a href="chapBib.html#biBResClasses">[Koh17b]</a>;</p>
</li>
<li><p><strong class="pkg">RCWA</strong> <a href="chapBib.html#biBRCWA">[Koh17a]</a>;</p>
</li>
<li><p><strong class="pkg">XMod</strong> <a href="chapBib.html#biBXMod">[WAOU17]</a>.</p>
</li>
</ul>
<p>The package may be obtained either as a compressed <code class="code">.tar</code> file or as a <code class="code">.zip</code> file, <code class="file">utils-version_number.tar.gz</code>, by ftp from one of the following sites:</p>
<ul>
<li><p>the <strong class="pkg">Utils</strong> GitHub release site: <span class="URL"><a href="https://gap-packages.github.io/utils/">https://gap-packages.github.io/utils/</a></span>.</p>
</li>
<li><p>any <strong class="pkg">GAP</strong> archive, e.g. <span class="URL"><a href="https://www.gap-system.org/Packages/packages.html">https://www.gap-system.org/Packages/packages.html</a></span>;</p>
</li>
</ul>
<p>The package also has a GitHub repository at: <span class="URL"><a href="https://github.com/gap-packages/utils">https://github.com/gap-packages/utils</a></span>.</p>
<p>Once the package is loaded, the manual <code class="code">doc/manual.pdf</code> can be found in the documentation folder. The <code class="code">html</code> versions, with or without <span class="SimpleMath">MathJax</span>, may be rebuilt as follows:</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">ReadPackage( "utils", "makedoc.g" ); </span>
</pre></div>
<p>It is possible to check that the package has been installed correctly by running the test files (which terminates the <strong class="pkg">GAP</strong> session):</p>
<div class="example"><pre>
<span class="GAPprompt">gap></span> <span class="GAPinput">ReadPackage( "utils", "tst/testall.g" );</span>
Architecture: . . . . .
testing: . . . . .
. . .
#I No errors detected while testing
</pre></div>
<p>Note that functions listed in this manual that are currently in the process of being transferred are only read from the source package <strong class="pkg">Home</strong> (say), and so can only be used if <strong class="pkg">Home</strong> has already been loaded. There are no such functions in transition at present.</p>
<p><a id="X8508AD637B79CEE8" name="X8508AD637B79CEE8"></a></p>
<h4>1.1 <span class="Heading">Information for package authors</span></h4>
<p>A function (or collection of functions) is suitable for transfer from a package <strong class="pkg">Home</strong> to <strong class="pkg">Utils</strong> if the following conditions are satisfied.</p>
<ul>
<li><p>The function is sufficiently non-specialised so that it might be of use to other authors.</p>
</li>
<li><p>The function does not depend on the remaining functions in <strong class="pkg">Home</strong></p>
</li>
<li><p>The function does not do what can already be done with a <strong class="pkg">GAP</strong> library function.</p>
</li>
<li><p>Documentation of the function and test examples are available.</p>
</li>
<li><p>When there is more than one active author of <strong class="pkg">Home</strong>, they should all be aware (and content) that the transfer is taking place.</p>
</li>
</ul>
<p>Authors of packages may be reluctant to let go of their utility functions. The following principles may help to reassure them. (Suggestions for more items here are welcome.)</p>
<ul>
<li><p>A function that has been transferred to <strong class="pkg">Utils</strong> will not be changed without the approval of the original author.</p>
</li>
<li><p>The current package maintainer has every intention of continuing to maintain <strong class="pkg">Utils</strong>. In the event that this proves impossible, the <strong class="pkg">GAP</strong> development team will surely find someone to take over.</p>
</li>
<li><p>Function names will not be changed unless specifically requested by <strong class="pkg">Home</strong>'s author(s) or unless they have the form <code class="code">HOME_FunctionName</code>.</p>
</li>
<li><p>In order to speed up the transfer process, only functions from one package will be in transition at any given time. Hopefully a week or two will suffice for most packages.</p>
</li>
<li><p>Any package author who transfers a function to <strong class="pkg">Utils</strong> will become an author of <strong class="pkg">Utils</strong>. (In truth, <strong class="pkg">Utils</strong> does not have <em>authors</em>, just a large number of <em>contributors</em>.)</p>
</li>
</ul>
<p>The process for transferring utility functions from <strong class="pkg">Home</strong> to <strong class="pkg">Utils</strong> is described in Chapter <a href="chap12.html#X84AC9613842F014C"><span class="RefLink">12</span></a>.</p>
<div class="chlinkprevnextbot"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap0.html">[Previous Chapter]</a> <a href="chap2.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="chap8.html">8</a> <a href="chap9.html">9</a> <a href="chap10.html">10</a> <a href="chap11.html">11</a> <a href="chap12.html">12</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>
|
