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
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>GAP (AutoDoc) - Chapter 4: AutoDoc</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="chap4" onload="jscontent()">
<div class="chlinktop"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<div class="chlinkprevnexttop"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap3.html">[Previous Chapter]</a> <a href="chapBib.html">[Next Chapter]</a> </div>
<p id="mathjaxlink" class="pcenter"><a href="chap4_mj.html">[MathJax on]</a></p>
<p><a id="X7CBD8AAF7DCEF352" name="X7CBD8AAF7DCEF352"></a></p>
<div class="ChapSects"><a href="chap4.html#X7CBD8AAF7DCEF352">4 <span class="Heading">AutoDoc</span></a>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap4.html#X863584DB8497D8BA">4.1 <span class="Heading">The AutoDoc() function</span></a>
</span>
<div class="ContSSBlock">
<span class="ContSS"><br /><span class="nocss"> </span><a href="chap4.html#X7CBD8AAF7DCEF352">4.1-1 AutoDoc</a></span>
</div></div>
<div class="ContSect"><span class="tocline"><span class="nocss"> </span><a href="chap4.html#X7A489A5D79DA9E5C">4.2 <span class="Heading">Examples</span></a>
</span>
</div>
</div>
<h3>4 <span class="Heading">AutoDoc</span></h3>
<p><a id="X863584DB8497D8BA" name="X863584DB8497D8BA"></a></p>
<h4>4.1 <span class="Heading">The AutoDoc() function</span></h4>
<p><a id="X7CBD8AAF7DCEF352" name="X7CBD8AAF7DCEF352"></a></p>
<h5>4.1-1 AutoDoc</h5>
<div class="func"><table class="func" width="100%"><tr><td class="tdleft"><code class="func">‣ AutoDoc</code>( [<var class="Arg">packageOrDirectory</var>][,] [<var class="Arg">optrec</var>] )</td><td class="tdright">( function )</td></tr></table></div>
<p>Returns: nothing</p>
<p>This is the main function of the <strong class="pkg">AutoDoc</strong> package. It can perform any combination of the following tasks:</p>
<ol>
<li><p>It can (re)generate a scaffold for your package manual. That is, it can produce two XML files in <strong class="pkg">GAPDoc</strong> format to be used as part of your manual: First, a file named <code class="file">doc/PACKAGENAME.xml</code> (with your package's name substituted) which is used as main XML file for the package manual, i.e. this file sets the XML doctype and defines various XML entities, includes other XML files (both those generated by <strong class="pkg">AutoDoc</strong> as well as additional files created by other means), tells <strong class="pkg">GAPDoc</strong> to generate a table of contents and an index, and more. Secondly, it creates a file <code class="file">doc/title.xml</code> containing a title page for your documentation, with information about your package (name, description, version), its authors and more, based on the data in your <code class="file">PackageInfo.g</code>.</p>
</li>
<li><p>It can scan your package for <strong class="pkg">AutoDoc</strong> based documentation (by using <strong class="pkg">AutoDoc</strong> tags and the Autodoc command. This will produce further XML files to be used as part of the package manual.</p>
</li>
<li><p>It can use <strong class="pkg">GAPDoc</strong> to generate PDF, text and HTML (with MathJaX enabled) documentation from the <strong class="pkg">GAPDoc</strong> XML files it generated as well as additional such files provided by you. For this, it invokes <code class="func">MakeGAPDocDoc</code> (<a href="../../../pkg/gapdoc/doc/chap5_mj.html#X826F530686F4D052"><span class="RefLink">GAPDoc: MakeGAPDocDoc</span></a>) to convert the XML sources, and it also instructs <strong class="pkg">GAPDoc</strong> to copy supplementary files (such as CSS style files) into your doc directory (see <code class="func">CopyHTMLStyleFiles</code> (<a href="../../../pkg/gapdoc/doc/chap5_mj.html#X813599E982DE9B98"><span class="RefLink">GAPDoc: CopyHTMLStyleFiles</span></a>)).</p>
</li>
</ol>
<p>For more information and some examples, please refer to Chapter <a href="chap1.html#X7A0D7AA484F466E1"><span class="RefLink">1</span></a>.</p>
<p>The parameters have the following meanings:</p>
<dl>
<dt><strong class="Mark"><var class="Arg">packageOrDirectory</var></strong></dt>
<dd><p>The purpose of this parameter is twofold: to determine the package directory in which <strong class="pkg">AutoDoc</strong> will operate, and to find the metadata concerning the package being documented. The parameter is either a string, an <code class="code">IsDirectory</code> object, or omitted. If it is a string, <strong class="pkg">AutoDoc</strong> interprets it as the name of a package, uses the metadata of the first package known to <strong class="pkg">GAP</strong> with that name, and uses the <code class="code">InstallationPath</code> specified in that metadata as the package directory. If <var class="Arg">packageOrDirectory</var> is an <code class="code">IsDirectory</code> object, this is used as package directory; if the argument is omitted, then the current directory is used. In the last two cases, the specified directory must contain a <code class="file">PackageInfo.g</code> file, and <strong class="pkg">AutoDoc</strong> extracts all needed metadata from that. The <code class="code">IsDirectory</code> form is for example useful if you have multiple versions of the package around and want to make sure the documentation of the correct version is built.</p>
<p>Note that when using <code class="code">AutoDocWorksheet</code> (see <a href="chap3.html#X801D4A2F8292704C"><span class="RefLink">3.1</span></a>), there is no parameter corresponding to <var class="Arg">packageOrDirectory</var> and so the "package directory" is always the current directory, and there is no metadata.</p>
</dd>
<dt><strong class="Mark"><var class="Arg">optrec</var></strong></dt>
<dd><p><var class="Arg">optrec</var> can be a record with some additional options. The following are currently supported:</p>
<dl>
<dt><strong class="Mark"><var class="Arg">dir</var></strong></dt>
<dd><p>This should either be a string, in which case it must be a path <em>relative</em> to the specified package directory, or a <code class="code">Directory()</code> object. (Thus, the only way to designate an absolute directory is with a <code class="code">Directory()</code> object.) This option specifies where the package documentation (e.g. the <strong class="pkg">GAPDoc</strong> XML or the manual PDF, etc.) files are stored and/or will be generated. <br /> <em>Default value: <code class="code">"doc/"</code>.</em></p>
</dd>
<dt><strong class="Mark"><var class="Arg">scaffold</var></strong></dt>
<dd><p>This controls whether and how to generate scaffold XML files for the package documentation.</p>
<p>The value should be either <code class="keyw">true</code>, <code class="keyw">false</code> or a record. If it is a record or <code class="keyw">true</code> (the latter is equivalent to specifying an empty record), then this feature is enabled. It is also enabled if <var class="Arg">opt.scaffold</var> is missing but the package's info record in <code class="file">PackageInfo.g</code> has an <code class="code">AutoDoc</code> entry. In all other cases (in particular if <var class="Arg">opt.scaffold</var> is <code class="keyw">false</code>), scaffolding is disabled.</p>
<p>If scaffolding is enabled, and <var class="Arg">PackageInfo.AutoDoc</var> exists, then it is assumed to be a record, and its contents are used as default values for the scaffold settings.</p>
<p>If <var class="Arg">opt.scaffold</var> is a record, it may contain the following entries.</p>
<dl>
<dt><strong class="Mark"><var class="Arg">includes</var></strong></dt>
<dd><p>A list of XML files to be included in the body of the main XML file. If you specify this list and also are using <strong class="pkg">AutoDoc</strong> to document your operations with <strong class="pkg">AutoDoc</strong> comments, you can add <code class="file">_AutoDocMainFile.xml</code> to this list to control at which point the documentation produced by <strong class="pkg">AutoDoc</strong> is inserted. If you do not do this, it will be added after the last of your own XML files.</p>
</dd>
<dt><strong class="Mark"><var class="Arg">index</var></strong></dt>
<dd><p>By default, the scaffold creates an index. If you do not want an index, set this to <code class="keyw">false</code>.</p>
</dd>
<dt><strong class="Mark"><var class="Arg">appendix</var></strong></dt>
<dd><p>This entry is similar to <var class="Arg">opt.scaffold.includes</var> but is used to specify files to include after the main body of the manual, i.e. typically appendices.</p>
</dd>
<dt><strong class="Mark"><var class="Arg">bib</var></strong></dt>
<dd><p>The name of a bibliography file, in BibTeX or XML format. If this key is not set, but there is a file <code class="file">doc/PACKAGENAME.bib</code> then it is assumed that you want to use this as your bibliography.</p>
</dd>
<dt><strong class="Mark"><var class="Arg">entities</var></strong></dt>
<dd><p>A record whose keys are taken as entity names, set to the corresponding (string) values. For example, if you pass the record "SomePackage",</p>
<div class="example"><pre>
rec( SomePackage := "<Package>SomePackage</Package>",
RELEASEYEAR := "2015" )</pre></div>
<p>then the following entity definitions are added to the XML preamble:</p>
<div class="example"><pre><!ENTITY SomePackage '<Package>SomePackage</Package>'>
<!ENTITY RELEASEYEAR '2015'></pre></div>
<p>This allows you to write "&SomePackage;" and "&RELEASEYEAR;" in your documentation, which will be replaced by respective values specified in the entities definition.</p>
</dd>
<dt><strong class="Mark"><var class="Arg">TitlePage</var></strong></dt>
<dd><p>A record whose entries are used to embellish the generated title page for the package manual with extra information, such as a copyright statement or acknowledgments. To this end, the names of the record components are used as XML element names, and the values of the components are outputted as content of these XML elements. For example, you could pass the following record to set a custom acknowledgements text:</p>
<div class="example"><pre>
rec( Acknowledgements := "Many thanks to ..." )</pre></div>
<p>For a list of valid entries in the title page, please refer to the <strong class="pkg">GAPDoc</strong> manual, specifically section <a href="../../../pkg/gapdoc/doc/chap3_mj.html#X842B421A7FBCDD2C"><span class="RefLink">GAPDoc: TitlePage</span></a>.</p>
</dd>
<dt><strong class="Mark"><var class="Arg">MainPage</var></strong></dt>
<dd><p>If scaffolding is enabled, by default a main XML file is generated (this is the file which contains the XML doctype and more). If you do not want this (e.g. because you have a handwritten main XML file), but still want <strong class="pkg">AutoDoc</strong> to generate a title page for you, you can set this option to <code class="keyw">false</code></p>
</dd>
<dt><strong class="Mark"><var class="Arg">document_class</var></strong></dt>
<dd><p>Sets the document class of the resulting PDF. The value can either be a string which has to be the name of the new document class, a list containing this string, or a list of two strings. Then the first one has to be the document class name, the second one the option string ( contained in [ ] ) in LaTeX.</p>
</dd>
<dt><strong class="Mark"><var class="Arg">latex_header_file</var></strong></dt>
<dd><p>Replaces the standard header from <strong class="pkg">GAPDoc</strong> completely with the header in this LaTeX file. Please be careful here, and look at <strong class="pkg">GAPDoc</strong>'s <code class="file">latexheader.tex</code> file for an example.</p>
</dd>
</dl>
</dd>
<dt><strong class="Mark"><var class="Arg">autodoc</var></strong></dt>
<dd><p>This controls whether and how to generate additional XML documentation files by scanning for <strong class="pkg">AutoDoc</strong> documentation comments.</p>
<p>The value should be either <code class="keyw">true</code>, <code class="keyw">false</code> or a record. If it is a record or <code class="keyw">true</code> (the latter is equivalent to specifying an empty record), then this feature is enabled. It is also enabled if <var class="Arg">opt.autodoc</var> is missing but the package depends (directly) on the <strong class="pkg">AutoDoc</strong> package. In all other cases (in particular if <var class="Arg">opt.autodoc</var> is <code class="keyw">false</code>), this feature is disabled.</p>
<p>If <var class="Arg">opt.autodoc</var> is a record, it may contain the following entries.</p>
<dl>
<dt><strong class="Mark"><var class="Arg">files</var></strong></dt>
<dd><p>A list of files (given by paths relative to the package directory) to be scanned for <strong class="pkg">AutoDoc</strong> documentation comments. Usually it is more convenient to use <var class="Arg">autodoc.scan_dirs</var>, see below.</p>
</dd>
<dt><strong class="Mark"><var class="Arg">scan_dirs</var></strong></dt>
<dd><p>A list of subdirectories of the package directory (given as relative paths) which <strong class="pkg">AutoDoc</strong> then scans for .gi, .gd, .g, and .autodoc files; all of these files are then scanned for <strong class="pkg">AutoDoc</strong> documentation comments. <br /> <em>Default value: <code class="code">[ ".", "gap", "lib", "examples", "examples/doc" ]</code>.</em></p>
</dd>
<dt><strong class="Mark"><var class="Arg">level</var></strong></dt>
<dd><p>This defines the level of the created documentation. The default value is 0. When parts of the manual are declared with a higher value they will not be printed into the manual.</p>
</dd>
</dl>
</dd>
<dt><strong class="Mark"><var class="Arg">gapdoc</var></strong></dt>
<dd><p>This controls whether and how to invoke <strong class="pkg">GAPDoc</strong> to create HTML, PDF and text files from your various XML files.</p>
<p>The value should be either <code class="keyw">true</code>, <code class="keyw">false</code> or a record. If it is a record or <code class="keyw">true</code> (the latter is equivalent to specifying an empty record), then this feature is enabled. It is also enabled if <var class="Arg">opt.gapdoc</var> is missing. In all other cases (in particular if <var class="Arg">opt.gapdoc</var> is <code class="keyw">false</code>), this feature is disabled.</p>
<p>If <var class="Arg">opt.gapdoc</var> is a record, it may contain the following entries.</p>
<dl>
<dt><strong class="Mark"><var class="Arg">main</var></strong></dt>
<dd><p>The name of the main XML file of the package manual. This exists primarily to support packages with existing manual which use a filename here which differs from the default. In particular, specifying this is unnecessary when using scaffolding. <br /> <em>Default value: <code class="code">PACKAGENAME.xml</code></em>.</p>
</dd>
<dt><strong class="Mark"><var class="Arg">files</var></strong></dt>
<dd><p>A list of files (given by paths relative to the package directory) to be scanned for <strong class="pkg">GAPDoc</strong> documentation comments. Usually it is more convenient to use <var class="Arg">gapdoc.scan_dirs</var>, see below.</p>
</dd>
<dt><strong class="Mark"><var class="Arg">scan_dirs</var></strong></dt>
<dd><p>A list of subdirectories of the package directory (given as relative paths) which <strong class="pkg">AutoDoc</strong> then scans for .gi, .gd and .g files; all of these files are then scanned for <strong class="pkg">GAPDoc</strong> documentation comments. <br /> <em>Default value: <code class="code">[ ".", "gap", "lib", "examples", "examples/doc" ]</code>.</em></p>
</dd>
<dt><strong class="Mark"><var class="Arg">LaTeXOptions</var></strong></dt>
<dd><p>Must be a record with entries which can be understood by <code class="func">SetGapDocLaTeXOptions</code> (<a href="../../../pkg/gapdoc/doc/chap5_mj.html#X85BE6DF178423EF5"><span class="RefLink">GAPDoc: SetGapDocLaTeXOptions</span></a>). Each entry can be a string, which will be given to <strong class="pkg">GAPDoc</strong> directly, or a list containing of two entries: The first one must be the string "file", the second one a filename. This file will be read and then its content is passed to <strong class="pkg">GAPDoc</strong> as option with the name of the entry.</p>
</dd>
<dt><strong class="Mark"><var class="Arg">gap_root_relative_path</var></strong></dt>
<dd><p>Either a boolean, or a string containing a relative path. By default (if this option is not set, or is set to <code class="keyw">false</code>), references in the generated documentation referring to external documentation (such as the <strong class="pkg">GAP</strong> manual) are encoded using absolute paths. This is fine as long as the documentation stays on only a single computer, but is problematic when preparing documentation that should be used on multiple computers, e.g., when creating a distribution archive of a <strong class="pkg">GAP</strong> package.<br /> Thus, if a relative path is provided via this option (or if it is set to <code class="keyw">true</code>, in which case the relative path <code class="file">../../..</code> is used), then <strong class="pkg">AutoDoc</strong> and <strong class="pkg">GAPDoc</strong> attempt to replace all absolute paths in references to <strong class="pkg">GAP</strong> manuals by paths based on this relative path.</p>
<p>On a technical level, <strong class="pkg">AutoDoc</strong> passes the relative path to the <var class="Arg">gaproot</var> parameter of <code class="func">MakeGAPDocDoc</code> (<a href="../../../pkg/gapdoc/doc/chap5_mj.html#X826F530686F4D052"><span class="RefLink">GAPDoc: MakeGAPDocDoc</span></a>)</p>
</dd>
</dl>
</dd>
<dt><strong class="Mark"><var class="Arg">extract_examples</var></strong></dt>
<dd><p>Either <code class="keyw">true</code> or a record. If set to <code class="keyw">true</code>, then all manual examples are extracted and placed into files <code class="file">tst/PACKAGENAME01.tst</code>, <code class="file">tst/PACKAGENAME02.tst</code>, ... and so on, with one file for each chapter. For chapters with no examples, no file is created.</p>
<p>As a record, the entry can have the following entries itself, to specify some options.</p>
<dl>
<dt><strong class="Mark">units</strong></dt>
<dd><p>This controls how examples are grouped into files. Recognized values are "Chapter" (default), "Section", "Subsection" or "Single". Depending on the value, one file is created for each chapter, each section, each subsection or each example. For all other values only a single file is created.</p>
<p>On a technical level, <strong class="pkg">AutoDoc</strong> passes the value to the <var class="Arg">units</var> parameter of <code class="func">ExtractExamples</code> (<a href="../../../pkg/gapdoc/doc/chap5_mj.html#X8337B2BC79253B3F"><span class="RefLink">GAPDoc: ExtractExamples</span></a>).</p>
</dd>
<dt><strong class="Mark">skip_empty_in_numbering</strong></dt>
<dd><p>If set to <code class="keyw">true</code> (the default), the generated files use filenames with strictly sequential numbering; that means that if chapter 1 (or whatever units are being used) contains no examples but chapter 2 does, then the examples for chapter 2 are put into the file <code class="file">tst/PACKAGENAME01.tst</code>. If this option is set to <code class="keyw">false</code>, then the chapter numbers are used to generate the filenames; so the examples for chapter 2 would be put into the file <code class="file">tst/PACKAGENAME02.tst</code>.</p>
</dd>
</dl>
</dd>
<dt><strong class="Mark"><var class="Arg">maketest</var></strong></dt>
<dd><p><em>This option is deprecated. Please use <code class="code">extract_examples</code> instead.</em></p>
<p>Either <code class="keyw">true</code> or a record. When it is <code class="keyw">true</code>, a simple <code class="file">maketest.g</code> file is created in the main package directory, which can be used to test the examples from the manual. As a record, the entry can have the following entries itself, to specify some options.</p>
<dl>
<dt><strong class="Mark">filename</strong></dt>
<dd><p>Sets the name of the test file.</p>
</dd>
<dt><strong class="Mark">commands</strong></dt>
<dd><p>A list of strings, each one a command, which will be executed at the beginning of the test file.</p>
</dd>
</dl>
</dd>
</dl>
</dd>
</dl>
<p><a id="X7A489A5D79DA9E5C" name="X7A489A5D79DA9E5C"></a></p>
<h4>4.2 <span class="Heading">Examples</span></h4>
<p>Some basic examples for using <code class="code">AutoDoc</code> were already shown in Chapter <a href="chap1.html#X7A0D7AA484F466E1"><span class="RefLink">1</span></a>.</p>
<div class="chlinkprevnextbot"> <a href="chap0.html">[Top of Book]</a> <a href="chap0.html#contents">[Contents]</a> <a href="chap3.html">[Previous Chapter]</a> <a href="chapBib.html">[Next Chapter]</a> </div>
<div class="chlinkbot"><span class="chlink1">Goto Chapter: </span><a href="chap0.html">Top</a> <a href="chap1.html">1</a> <a href="chap2.html">2</a> <a href="chap3.html">3</a> <a href="chap4.html">4</a> <a href="chapBib.html">Bib</a> <a href="chapInd.html">Ind</a> </div>
<hr />
<p class="foot">generated by <a href="http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc">GAPDoc2HTML</a></p>
</body>
</html>
|
