22
22
<heading>The autogsdoc tool</heading>
24
The autogsdoc tool is a command-line utility for parsing ObjectiveC
25
source code (header files and optionally source files) in order to
26
generate documentation covering the public interface of the various
27
classes, categories, and protocols in the source.
30
The simple way to use this is to run the command with one or more
31
header file names as arguments ... the tool will automatically
32
parse corresponding source files in the same directory (or the
33
directory specified using the DocumentationDirectory default),
34
and produce gsdoc files as output.<br />
37
Even without any human assistance, this tool will produce skeleton
38
documents listing the methods in the classes found in the source
39
files, but more importantly it can take specially formatted comments
40
from the source files and insert those comments into the gsdoc output.
43
Any comment beginning with slash and <em>two</em> asterisks rather than
44
the common slash and single asterisk, is taken to be gsdoc markup, to
45
be use as the description of the class or method following it. This
46
comment text is reformatted and then inserted into the output.
49
There are some cases where special extra processing is performed,
50
predominantly in the first comment found in the source file,
51
from which various chunks of gsdoc markup may be extracted and
52
placed into appropriate locations in the output document -
55
<item><strong>AutogsdocSource</strong>
56
In any line where <code>AutogsdocSource</code>: is found, the remainder
57
of the line is taken as a source file name to be used instead of
58
making the assumption that each .h file processed uses a .m file
59
of the same name. You may supply multiple <code>AutogsdocSource</code>:
60
lines where a header file declares items which are defined in
61
multiple source files.
63
<item><strong><abstract></strong>
64
An abstract of the content of the document ... placed in the head
67
<item><strong><author></strong>
68
A description of the author of the code - may be repeated to handle
69
the case where a document has multiple authors. Placed in the
70
head of the gsdoc output.<br />
71
As an aid to readability of the source, some special additional
72
processing is performed related to the document author -<br />
73
Any line of the form '<code>Author</code>: name <email-address>',
74
or '<code>By</code>: name <email-address>',
75
or '<code>Author</code>: name' or '<code>By</code>: name'
76
will be recognised and converted to an <em>author</em> element,
77
possibly containing an <em>email</em> element.
79
<item><strong><back></strong>
80
Placed in the gsdoc output just before the end of the body of the
81
document - intended to be used for appendices, index etc.
83
<item><strong><chapter></strong>
84
Placed immediately before any generated class documentation ...
85
intended to be used to provide overall description of how the
86
code being documented works.<br />
88
<item><strong><copy></strong>
89
Copyright of the content of the document ... placed in the head
90
of the gsdoc output.<br />
91
As an aid to readability of the source, some special additional
92
processing is performed -<br />
93
Any line of the form 'Copyright (C) text' will be recognised and
94
converted to a <em>copy</em> element.
96
<item><strong><date></strong>
97
Date of the revision of the document ... placed in the head
98
of the gsdoc output. If this is omitted the tool will try to
99
construct a value from the RCS Date tag (if available).
101
<item><strong><front></strong>
102
Inserted into the document at the start of the body ... intended
103
to provide for introduction or contents pages etc.
105
<item><strong><title></strong>
106
Title of the document ... placed in the head of the gsdoc output.
107
If this is omitted the tool will generate a (probably poor)
111
<strong>NB</strong>This markup may be used within
112
class, category, or protocol documentation ... if so, it is
113
extracted and wrapped round the rest of the documentation for
114
the class as the classes chapter.
115
The rest of the class documentation is normally
116
inserted at the end of the chapter, but may instead be sbstituted
117
in in place of the <unit /> pseudo-element within the
118
<chapter> element.
120
<item><strong><version></strong>
121
Version identifier of the document ... placed in the head
122
of the gsdoc output. If this is omitted the tool will try to
123
construct a value from the RCS Revision tag (if available).
127
In comments being used to provide text for a method description, the
128
following markup is removed from the text and handled specially -
131
<item><strong><init /></strong>
132
The method is marked as being the designated initialiser for the class.
134
<item><strong><override-subclass /></strong>
135
The method is marked as being one which subclasses must override
136
(eg an abstract method).
138
<item><strong><override-never /></strong>
139
The method is marked as being one which subclasses should <em>NOT</em>
142
<item><strong><standards> ... </standards></strong>
143
The markup is removed from the description and placed <em>after</em>
144
it in the gsdoc output - so that the method is described as
145
conforming (or not conforming) to the specified standards.
149
Generally, the text in comments is reformatted to standardise and
150
indent it nicely ... the reformatting is <em>not</em> performed on
151
any text inside an <example> element.<br />
152
When the text is reformatted, it is broken into whitespace separated
153
'words' which are then subjected to some extra processing ...
156
<item>Certain well known constants such as YES, NO, and nil are
157
enclosed in <code> ... </code> markup.
159
<item>The names of method arguments within method descriptions are
160
enclosed in <var> ... </var> markup.
162
<item>Method names (beginning with a plus or minus) are enclosed
163
in <ref...> ... </ref> markup.<br />
164
eg. "-init" (without the quotes) would be wrapped in a gsdoc
165
reference element to point to the init method of the current
166
class or, if only one known class had an init method, it
167
would refer to the method of that class.
168
<br />Note the fact that the method name must be surrounded by
169
whitespace (though a comma, fullstop, or semicolon at the end
170
of the specifier will also act as a whitespace terminator).
172
<item>Method specifiers including class names (beginning and ending with
173
square brackets) are enclosed in <ref...> ... </ref> markup.
174
<br />eg. [ NSObject-init],
175
will create a reference to the init method of NSObject, while
176
<br />[ (NSCopying)-copyWithZone:], creates a
177
reference to a method in the NSCopyIng protocol.
178
<br />Note that no spaces must appear between the square brackets
180
<br />Protocol namnes are enclosed in round brackets rather than
181
the customary angle brackets, because gsdoc is an XML language, and
182
XML treats angle brackets specially.
186
The tools accepts certain user defaults (which can of course be
187
supplied as command-line arguments as usual) -
190
<item><strong>Declared</strong>
191
Specify where headers are to be documented as being found.<br />
192
The actual name produced in the documentation is formed by appending
193
the last component of the header file name to the value of this
195
If this default is not specified, the full name of the header file
196
(as supplied on the command line), with the HeaderDirectory
197
default prepended, is used.<br />
198
A typical usage of this might be <code>-Declared Foundation</code>
199
when generating documentation for the GNUstep base library. This
200
would result in the documentation saying that NSString is declared
201
in <code>Foundation/NSString.h</code>
203
<item><strong>DocumentAllInstanceVariables</strong>
204
This flag permits you to generate documentation for all instance
205
variables. Normally, only those explicitly declared 'public' or
206
'protected' will be documented.
208
<item><strong>DocumentationDirectory</strong>
209
May be used to specify the directory in which generated
210
documentation is to be placed. If this is not set, output
211
is placed in the current directory.
213
<item><strong>GenerateHtml</strong>
214
May be used to specify if HTML output is to be generated.
217
<item><strong>HeaderDirectory</strong>
218
May be used to specify the directory to be searched for header files.
219
If this is not specified, headers are looked for relative to the
220
current directory or using absolute path names if given.
222
<item><strong>IgnoreDependencies</strong>
223
A boolean value which may be used to specify that the program should
224
ignore file modification times and regenerate files anyway. Provided
225
for use in conjunction with the <code>make</code> system, which is
226
expected to manage dependency checking itsself.
228
<item><strong>LocalProjects</strong>
229
This value is used to control the automatic inclusion of local
230
external projects into the indexing system for generation of
231
cross-references in final document output.<br />
232
If set to 'None', then no local project references are done,
233
otherwise, the 'Local' GNUstep documentation directory is recursively
234
searched for files with a <code>.igsdoc</code> extension, and the
235
indexing information from those files is used.<br />
236
The value of this string is also used to generate the filenames in
237
the cross reference ... if it is an empty string, the path to use
238
is assumed to be a file in the same directory where the igsdoc
239
file was found, otherwise it is used as a prefix to the name in
242
<item><strong>Project</strong>
243
May be used to specify the name of this project ... determines the
244
name of the index reference file produced as part of the documentation
245
to provide information enabling other projects to cross-reference to
246
items in this project.
248
<item><strong>Projects</strong>
249
This value may be supplied as a dictionary containing the paths to
250
the igsdoc index/reference files used by external projects, along
251
with values to be used to map the filenames found in the indexes.<br />
252
For example, if a project index (igsdoc) file says that the class
253
<code>Foo</code> is found in the file <code>Foo</code>, and the
254
path associated with that project index is <code>/usr/doc/proj</code>,
255
Then generated html output may reference the class as being in
256
<code>/usr/doc/prj/Foo.html</code>
258
<item><strong>ShowDependencies</strong>
259
A boolean value which may be used to specify that the program should
260
log which files are being regenerated because of their dependencies
263
<item><strong>Standards</strong>
264
A boolean value used to specify whether the program should insert
265
information about standards complience into ythe documentation.
266
This should only be used when documenting the GNUstep libraries
267
and tools themselves as it assumes that the code being documented
268
is part of GNUstep and possibly complies with the OpenStep standard
269
or implements MacOS-X compatible methods.
271
<item><strong>SystemProjects</strong>
272
This value is used to control the automatic inclusion of system
273
external projects into the indexing system for generation of
274
cross-references in final document output.<br />
275
If set to 'None', then no system project references are done,
276
otherwise, the 'System' GNUstep documentation directory is recursively
277
searched for files with a <code>.igsdoc</code> extension, and the
278
indexing information from those files is used.<br />
279
The value of this string is also used to generate the filenames in
280
the cross reference ... if it is an empty string, the path to use
281
is assumed to be a file in the same directory where the igsdoc
282
file was found, otherwise it is used as a prefix to the name in
285
<item><strong>Up</strong>
286
A string used to supply the name to be used in the 'up' link from
287
generated gsdoc documents. This should normally be the name of a
288
file which contains an index of the contents of a project.<br />
289
If this is missing or set to an empty string, then no 'up' link
290
will be provided in the documents.
292
<item><strong>WordMap</strong>
293
This value is a dictionary used to map identifiers/keywords found
294
in the source files to other words. Generally you will not have
295
to use this, but it is sometimes helpful to avoid the parser being
296
confused by the use of C preprocessor macros. You can effectively
297
redefine the macro to something less confusing.
24
<heading>Overview</heading>
26
The autogsdoc tool is a command-line utility that helps developers
27
produce reference documentation for GNUstep APIs. It also enables
28
developers to write and maintain other documentation in XML and have it
29
converted to HTML. In detail, autogsdoc will:
33
Extract special comments describing the public interfaces of classes,
34
categories, protocols, functions, and macros from Objective C source
35
code (header files and optionally source files) into GSDoc XML files.
36
(Note that since C is a subset of Objective C, this tool can operate
37
to document functions and other C structures in plain C source.)
40
Convert GSDoc XML files, whether generated from source code or written
41
manually by developers, into HTML.
44
Construct indices based on GSDoc XML file sets, and convert those
49
synopsis: <code>autogsdoc (options) (files)</code><br/>
50
    (options) described below<br/>
51
    (files) <code>.h</code>, <code>.m</code>, <code>.gsdoc</code>, and/or <code>.html</code> files, in any order.
54
The most common usage this is to run the command with one or more
55
header file names as arguments ... the tool will automatically
56
parse corresponding source files in the same directory as the
57
headers (or the current directory, or the directory specified
58
using the DocumentationDirectory default), and produce GSDoc
59
and HTML files as output. For best results this mode should be
60
run from the directory containing the source files.
63
GSDoc files may also be given directly in addition or by themselves, and
64
will be converted to HTML. See the
65
<uref url="gsdoc.html">GSDoc reference</uref> for information
69
Finally, HTML files may be given on the command line. Cross-references
70
to other parts of code documentation found within them will be rewritten
71
based on what is found in the project currently.
75
<heading>Source Code Markup</heading>
77
The source code parser will automatically produce GSDoc documents
78
listing the methods in the classes found in the source files, and it
79
will include text from specially formatted comments from the source
83
Any comment beginning with slash and <em>two</em> asterisks rather than
84
the common slash and single asterisk, is taken to be GSDoc markup, to
85
be use as the description of the class or method following it. This
86
comment text is reformatted and then inserted into the output.<br />
87
Where multiple comments are associated with the same item, they are
88
joined together with a line break (<br />) between each if
92
The tool can easily be used to document programs as well as libraries,
93
simply by giving it the name of the source file containing the main()
94
function of the program - it takes the special comments from that
95
function and handles them specially, inserting them as a section at
96
the end of the first chapter of the document (it creates the first
97
chapter if necessary).
100
<strong>Options</strong> are described in the section
101
<em>Arguments and Defaults</em> below.
105
<heading>Extra markup</heading>
107
There are some cases where special extra processing is performed,
108
predominantly in the first comment found in the source file,
109
from which various chunks of GSDoc markup may be extracted and
110
placed into appropriate locations in the output document -
113
<item><strong>AutogsdocSource</strong>: 
114
In any line where <code>AutogsdocSource</code>:  is found, the
115
remainder of the line is taken as a source file name to be used
116
instead of making the assumption that each .h file processed uses
117
a  .m file of the same name. You may supply multiple
118
<code>AutogsdocSource</code>:  lines where a header file declares
119
items which are defined in multiple source files.<br /> If a file name
120
is absolute, it is used just as supplied.<br /> If on the other hand,
121
it is a relative path, the software looks for the source file first
122
relative to the location of the header file, and if not found there,
123
relative to the current directory in which autogsdoc is running, and
124
finally relative to the directory specified by the
125
<code>DocumentationDirectory</code> default.
127
<item><strong><abstract></strong>
128
An abstract of the content of the document ... placed in the head
131
<item><strong><author></strong>
132
A description of the author of the code - may be repeated to handle
133
the case where a document has multiple authors. Placed in the
134
head of the GSDoc output.<br />
135
As an aid to readability of the source, some special additional
136
processing is performed related to the document author -<br />
137
Any line of the form '<code>Author</code>: name <email-address>',
138
or '<code>By</code>: name <email-address>',
139
or '<code>Author</code>: name' or '<code>By</code>: name'
140
will be recognised and converted to an <em>author</em> element,
141
possibly containing an <em>email</em> element.
143
<item><strong><back></strong>
144
Placed in the GSDoc output just before the end of the body of the
145
document - intended to be used for appendices, index etc..
147
<item><strong><chapter></strong>
148
Placed immediately before any generated class documentation ...
149
intended to be used to provide overall description of how the
150
code being documented works.<br />Any documentation for the main()
151
function of a program is inserted as a section at the end of this
154
<item><strong><copy></strong>
155
Copyright of the content of the document ... placed in the head
156
of the GSDoc output.<br />
157
As an aid to readability of the source, some special additional
158
processing is performed -<br />
159
Any line of the form 'Copyright (C) text' will be recognised and
160
converted to a <em>copy</em> element.
162
<item><strong><date></strong>
163
Date of the revision of the document ... placed in the head
164
of the GSDoc output. If this is omitted the tool will try to
165
construct a value from the RCS Date tag (if available).
167
<item><strong><front></strong>
168
Inserted into the document at the start of the body ... intended
169
to provide for introduction or contents pages etc.
171
<item><strong><title></strong>
172
Title of the document ... placed in the head of the GSDoc output.
173
If this is omitted the tool will generate a (probably poor)
174
title of its own - so you should include this markup manually.
176
<item><strong><version></strong>
177
Version identifier of the document ... placed in the head
178
of the GSDoc output. If this is omitted the tool will try to
179
construct a value from the RCS Revision tag (if available).
183
<strong>NB</strong>The markup just described may be used within class,
184
category, or protocol documentation ... if so, it is extracted and
185
wrapped round the rest of the documentation for the class as the
186
class's chapter. The rest of the class documentation is normally
187
inserted at the end of the chapter, but may instead be substituted in
188
in place of the <unit /> pseudo-element within the
189
<chapter> element.
193
<heading>Method markup</heading>
195
In comments being used to provide text for a method description, the
196
following markup is removed from the text and handled specially -
199
<item><strong><init /></strong>
200
The method is marked as being the designated initialiser for the class.
202
<item><strong><override-subclass /></strong>
203
The method is marked as being one which subclasses must override
204
(e.g. an abstract method).
206
<item><strong><override-never /></strong>
207
The method is marked as being one which subclasses should <em>NOT</em>
210
<item><strong><standards> ... </standards></strong>
211
The markup is removed from the description and placed <em>after</em>
212
it in the GSDoc output - so that the method is described as
213
conforming (or not conforming) to the specified standards.
218
<heading>Automated markup</heading>
220
Generally, the text in comments is reformatted to standardise and
221
indent it nicely ... the reformatting is <em>not</em> performed on
222
any text inside an <example> element.<br />
223
When the text is reformatted, it is broken into whitespace separated
224
'words' which are then subjected to some extra processing ...
227
<item>Certain well known constants such as YES, NO, and nil are
228
enclosed in <code> ... </code> markup.
230
<item>The names of method arguments within method descriptions are
231
enclosed in <var> ... </var> markup.
233
<item>Method names (beginning with a plus or minus) are enclosed
234
in <ref...> ... </ref> markup.<br />
235
e.g. "-init" (without the quotes) would be wrapped in a GSDoc
236
reference element to point to the init method of the current
237
class or, if only one known class had an init method, it
238
would refer to the method of that class.
239
<br />Note the fact that the method name must be surrounded by
240
whitespace to be recognized (though a comma, fullstop, or semicolon
241
at the end of the specifier will act like whitespace).
243
<item>Method specifiers including class names (beginning and ending with
244
square brackets) are enclosed in <ref...> ... </ref> markup.
245
<br />e.g. <code>[</code>NSObject-init<code>]</code>,
246
will create a reference to the init method of NSObject (either the
247
class proper, or any of its categories), while
248
<br /><code>[</code>(NSCopying)-copyWithZone:<code>]</code>, creates a
249
reference to a method in the NSCopying protocol.
250
<br />Note that no spaces must appear between the square brackets
252
<br />Protocol names are enclosed in round brackets rather than
253
the customary angle brackets, because GSDoc is an XML language, and
254
XML treats angle brackets specially.
256
<item>Class names (and also protocol and category names) enclosed
257
in square brackets are also cross referenced.
258
<br />Protocol names are enclosed in round brackets rather than
259
the customary angle brackets, because GSDoc is an XML language, and
260
XML treats angle brackets specially.
262
<item>Function names (ending with '()') other than 'main()' are enclosed
263
in <ref...> ... </ref> markup.<br />
264
e.g. "NSLogv()" (without the quotes) would be wrapped in a GSDoc
265
reference element to point to the documentation of the NSLog function.
266
<br />Note the fact that the function name must be surrounded by
267
whitespace (though a comma, fullstop, or semicolon at the end
268
of the specifier will also act as a whitespace terminator).
274
<heading>Arguments and Defaults</heading>
276
The tool accepts certain user defaults (which can of course be
277
supplied as command-line arguments by prepending '-' before the default
278
name and giving the value afterwards, as in -<code>Clean YES</code>):
281
<item><strong>Clean</strong>
282
If this boolean value is set to YES, then rather than generating
283
documentation, the tool removes all GSDoc files generated in the
284
project, and all html files generated from them (as well as any
285
which would be generated from GSDoc files listed explicitly),
286
and finally removes the project index file.<br />
287
The only exception to this is that template GSDoc files (i.e. those
288
specified using "-ConstantsTemplate ...", "-FunctionsTemplate ..."
289
arguments etc) are not deleted unless the CleanTemplates flag is set.
291
<item><strong>CleanTemplates</strong>
292
This flag specifies whether template GSDoc files are to be removed
293
along with other files when the Clean option is specified.
294
The default is for them not to be removed ... since these templates
295
may have been produced manually and just had data inserted into them.
297
<item><strong>ConstantsTemplate</strong>
298
Specify the name of a template document into which documentation
299
about constants should be inserted from all files in the project.<br />
300
This is useful if constants in the source code are scattered around many
301
files, and you need to group them into one place.<br />
302
You are responsible for ensuring that the basic template document
303
(into which individual constant documentation is inserted) contains
304
all the other information you want, but as a convenience autogsdoc
305
will generate a simple template (which you may then edit) for you
306
if the file does not exist.
307
<br />Insertion takes place immediately before the <em>back</em>
308
element (or if that does not exist, immediately before the end
309
of the <em>body</em> element) in the template.
311
<item><strong>Declared</strong>
312
Specify where headers are to be documented as being found.<br />
313
The actual name produced in the documentation is formed by appending
314
the last component of the header file name to the value of this
316
If this default is not specified, the full name of the header file
317
(as supplied on the command line), with the HeaderDirectory
318
default prepended, is used.<br />
319
A typical usage of this might be <code>"-Declared Foundation"</code>
320
when generating documentation for the GNUstep base library. This
321
would result in the documentation saying that NSString is declared
322
in <code>Foundation/NSString.h</code>
324
<item><strong>DocumentAllInstanceVariables</strong>
325
This flag permits you to generate documentation for all instance
326
variables. Normally, only those explicitly declared 'public' or
327
'protected' will be documented.
329
<item><strong>DocumentInstanceVariables</strong>
330
This flag permits you to turn off documentation for instance
331
variables completely. Normally, explicitly declared 'public' or
332
'protected' instance variables will be documented.
334
<item><strong>InstanceVariablesAtEnd</strong>
335
This flag, if set, directs the HTML generator to place instance
336
variable documentation at the end of the class, instead of the
337
beginning. This is useful if you use a lot of protected instance
338
variables which are only going to be of secondary interest to general
341
<item><strong>DocumentationDirectory</strong>
342
May be used to specify the directory in which generated documentation
343
is to be placed. If this is not set, output is placed in the current
344
directory. This directory is also used as a last resort to locate
345
source files (not headers), and more importantly, it is used as the
346
<em>first and only</em> resort to locate any <code>.gsdoc</code> files
347
that are passed in on the command line. Any path information given
348
for these files is <em><strong>removed</strong></em> and they are
349
searched for in <code>DocumentationDirectory</code> (even though they
350
may not have been autogenerated).
352
<item><strong>Files</strong>
353
Specifies the name of a file containing a list of file names as
354
a property list array <em>(name1,name2,...)</em> format. If this
355
is present, filenames in the program argument list are ignored and
356
the names in this file are used as the list of names to process.
358
<item><strong>FunctionsTemplate</strong>
359
Specify the name of a template document into which documentation
360
about functions should be inserted from all files in the project.<br />
361
This is useful if function source code is scattered around many
362
files, and you need to group it into one place.<br />
363
You are responsible for ensuring that the basic template document
364
(into which individual function documentation is inserted) contains
365
all the other information you want, but as a convenience autogsdoc
366
will generate a simple template (which you may then edit) for you
367
if the file does not exist.
368
<br />Insertion takes place immediately before the <em>back</em>
369
element (or if that does not exist, immediately before the end
370
of the <em>body</em> element) in the template.
372
<item><strong>GenerateHtml</strong>
373
May be used to specify if HTML output is to be generated.
376
<item><strong>HeaderDirectory</strong>
377
May be used to specify the directory to be searched for header files.
378
When supplied, this value is prepended to relative header names,
379
otherwise the relative header names are interpreted relative to
380
the current directory.<br />
381
Header files specified as absolute paths are not influenced by this
384
<item><strong>IgnoreDependencies</strong>
385
A boolean value which may be used to specify that the program should
386
ignore file modification times and regenerate files anyway. Provided
387
for use in conjunction with the <code>make</code> system, which is
388
expected to manage dependency checking itself.
390
<item><strong>LocalProjects</strong>
391
This value is used to control the automatic inclusion of local
392
external projects into the indexing system for generation of
393
cross-references in final document output.<br />
394
If set to 'None', then no local project references are done,
395
otherwise, the 'Local' GNUstep documentation directory is recursively
396
searched for files with a <code>.igsdoc</code> extension, and the
397
indexing information from those files is used.<br />
398
The value of this string is also used to generate the filenames in
399
the cross reference ... if it is an empty string, the path to use
400
is assumed to be a file in the same directory where the igsdoc
401
file was found, otherwise it is used as a prefix to the name in
403
NB. Local projects with the same name as the project currently
404
being documented will <em>not</em> be included by this mechanism.
405
If you wish to include such projects, you must do so explicitly
406
using <em>"-Projects ..."</em>
408
<item><strong>MacrosTemplate</strong>
409
Specify the name of a template document into which documentation
410
about macros should be inserted from all files in the project.<br />
411
This is useful if macro code is scattered around many
412
files, and you need to group it into one place.<br />
413
You are responsible for ensuring that the basic template document
414
(into which individual macro documentation is inserted) contains
415
all the other information you want, but as a convenience autogsdoc
416
will generate a simple template (which you may then edit) for you
417
if the file does not exist.
418
<br />Insertion takes place immediately before the <em>back</em>
419
element (or if that does not exist, immediately before the end
420
of the <em>body</em> element) in the template.
422
<item><strong>MakeDependencies</strong>
423
A filename to be used to output dependency information for make. This
424
will take the form of listing all header and source files known for
425
the project as dependencies of the project name (see
426
<code>Project</code>).
428
<item><strong>Project</strong>
429
Specifies the name of this project ... determines the
430
name of the index reference file produced as part of the documentation
431
to provide information enabling other projects to cross-reference to
432
items in this project. If not set, 'Untitled' is used.
434
<item><strong>Projects</strong>
435
This value may be supplied as a dictionary containing the paths to
436
the igsdoc index/reference files used by external projects, along
437
with values to be used to map the filenames found in the indexes.<br />
438
For example, if a project index (igsdoc) file says that the class
439
<code>Foo</code> is found in the file <code>Foo</code>, and the
440
path associated with that project index is <code>/usr/doc/proj</code>,
441
Then generated html output may reference the class as being in
442
<code>/usr/doc/prj/Foo.html</code> . Note that a dictionary may be
443
given on the command line by using the standard PropertyList format
444
(not the XML format of OS X), using semicolons as line-separators, and
445
enclosing it in single quotes.
447
<item><strong>ShowDependencies</strong>
448
A boolean value which may be used to specify that the program should
449
log which files are being regenerated because of their dependencies
452
<item><strong>Standards</strong>
453
A boolean value used to specify whether the program should insert
454
information about standards complience into the documentation.
455
This should only be used when documenting the GNUstep libraries
456
and tools themselves as it assumes that the code being documented
457
is part of GNUstep and possibly complies with the OpenStep standard
458
or implements MacOS-X compatible methods.
460
<item><strong>SystemProjects</strong>
461
This value is used to control the automatic inclusion of system
462
external projects into the indexing system for generation of
463
cross-references in final document output.<br />
464
If set to 'None', then no system project references are done,
465
otherwise, the 'System' GNUstep documentation directory is recursively
466
searched for files with a <code>.igsdoc</code> extension, and the
467
indexing information from those files is used.<br />
468
The value of this string is also used to generate the filenames in
469
the cross reference ... if it is an empty string, the path to use
470
is assumed to be a file in the same directory where the igsdoc
471
file was found, otherwise it is used as a prefix to the name in
473
NB. System projects with the same name as the project currently
474
being documented will <em>not</em> be included by this mechanism.
475
If you wish to include such projects, you must do so explicitly
476
using <em>"-Projects ..."</em>
478
<item><strong>TypedefsTemplate</strong>
479
Specify the name of a template document into which documentation
480
about typedefs should be inserted from all files in the project.<br />
481
This is useful if typedef source code is scattered around many
482
files, and you need to group it into one place.<br />
483
You are responsible for ensuring that the basic template document
484
(into which individual typedef documentation is inserted) contains
485
all the other information you want, but as a convenience autogsdoc
486
will generate a simple template (which you may then edit) for you
487
if the file does not exist.
488
<br />Insertion takes place immediately before the <em>back</em>
489
element (or if that does not exist, immediately before the end
490
of the <em>body</em> element) in the template.
492
<item><strong>Up</strong>
493
A string used to supply the name to be used in the 'up' link from
494
generated GSDoc documents. This should normally be the name of a
495
file which contains an index of the contents of a project.<br />
496
If this is missing or set to an empty string, then no 'up' link
497
will be provided in the documents.
499
<item><strong>VariablesTemplate</strong>
500
Specify the name of a template document into which documentation
501
about variables should be inserted from all files in the project.<br />
502
This is useful if variable source code is scattered around many
503
files, and you need to group it into one place.<br />
504
You are responsible for ensuring that the basic template document
505
(into which individual variable documentation is inserted) contains
506
all the other information you want, but as a convenience autogsdoc
507
will generate a simple template (which you may then edit) for you
508
if the file does not exist.
509
<br />Insertion takes place immediately before the <em>back</em>
510
element (or if that does not exist, immediately before the end
511
of the <em>body</em> element) in the template.
513
<item><strong>Verbose</strong>
514
A boolean used to specify whether you want verbose debug/warning
515
output to be produced.
517
<item><strong>Warn</strong>
518
A boolean used to specify whether you want standard warning
519
output (e.g. report of undocumented methods) produced.
521
<item><strong>WordMap</strong>
522
This value is a dictionary used to map identifiers/keywords found
523
in the source files to other words. Generally you will not have
524
to use this, but it is sometimes helpful to avoid the parser being
525
confused by the use of C preprocessor macros. You can effectively
526
redefine the macro to something less confusing.<br />
527
The value you map the identifier to must be one of -<br />
528
Another identifier,<br />
529
An empty string - the value is ignored,<br />
530
Two slashes ('//') - the rest of the line is ignored.<br />
531
Note that a dictionary may be given on the command line by using the
532
standard PropertyList format (not the XML format of OS X), using
533
semicolons as line-separators, and enclosing it in single quotes.
301
538
<heading>Inter-document linkage</heading>
360
624
NSString *refsFile;
627
unsigned firstFile = 1;
363
628
BOOL generateHtml = YES;
364
629
BOOL ignoreDependencies = NO;
365
630
BOOL showDependencies = NO;
366
631
BOOL verbose = NO;
633
BOOL instanceVarsAtEnd = YES;
634
NSArray *files = nil;
368
635
NSMutableArray *sFiles = nil; // Source
369
636
NSMutableArray *gFiles = nil; // GSDOC
370
637
NSMutableArray *hFiles = nil; // HTML
371
CREATE_AUTORELEASE_POOL(outer);
372
CREATE_AUTORELEASE_POOL(pool);
639
NSAutoreleasePool *outer = nil;
640
NSAutoreleasePool *pool = nil;
646
NSArray *informalProtocols = nil;
649
Overall process in this file is as follows:
651
1) Get/test defaults and arguments.
653
2) Init filename list, and move .h/.m into "source files", .gsdoc into
654
"gsdoc files", and .html into "html files".
656
3) Load existing .igsdoc file (PropertyList/Dictionary format) if found,
657
initializing an AGSIndex from it.
661
4a) Build list of all template files, and remove generated content
662
from them if not cleaning templates.
663
4b) Figure out generated files from index file (if none assumes none
664
generated) and remove them (but not template files unless
666
4c) Remove index file.
667
4d) Remove HTML files corresponding to .gsdoc files in current list.
669
5) Start with "source files".. for each one (hereafter called a "header
672
5a) Parse declarations (in .h or .m) using an AGSParser object.
673
5b) Determine (possibly multiple) dependent .m files corresponding to
675
5c) Feed parser results to an AGSOutput instance.
677
6) Move to "gsdoc files" (including both command-line given ones and
678
just-generated ones).. and generate the index; for each one:
680
6a) Remove any path specification and search in
681
documentationDirectory then CWD for it.
682
6b) Parse the file, call [localRefs makeRefs: root],
683
[projectRefs mergeRefs: localRefs] to make indices.
685
7) Write the .igsdoc file.
687
8) Build index references to external projects.
689
9) Create HTML frames auxiliary files.
691
10) If needed, re-pass through the "gsdoc files" to generate HTML.
692
10a) Find files as before.
693
10b) Parse as before.
694
10c) Feed the DOM tree to an AGSHtml instance, and dump the result to
697
11) For HTML files that were given on the command line, adjust all cross
698
reference HREFs to paths given in arguments.
700
12) If MakeDependencies was requested, list all header and source files
701
as colon-dependencies of the project name.
376
705
#ifdef GS_PASS_ARGUMENTS
377
706
[NSProcessInfo initializeWithArguments: argv count: argc environment: env];
710
outer = [NSAutoreleasePool new];
381
714
NSLog(@"ERROR: The GNUstep Base Library was built\n"
382
715
@" without an available libxml library. Autogsdoc needs the libxml\n"
383
716
@" library to function. Aborting");
721
* 1) Get/test defaults and arguments.
387
723
defs = [NSUserDefaults standardUserDefaults];
388
724
[defs registerDefaults: [NSDictionary dictionaryWithObjectsAndKeys:
389
725
@"Untitled", @"Project",
728
// BEGIN test for any unrecognized arguments, or "--help"
729
argsRecognized = [NSDictionary dictionaryWithObjectsAndKeys:
730
@"\t\t\tBOOL\t(NO)\n\tproduce verbose output",
732
@"\t\t\tBOOL\t(NO)\n\tproduce warnings",
734
@"\tBOOL\t(NO)\n\tignore file mod times (always generate)",
735
@"IgnoreDependencies",
736
@"\t\tBOOL\t(NO)\n\tlog files being regenerated due to dependencies",
738
@"\t\tBOOL\t(YES)\n\tgenerate HTML output "
739
@"(as opposed to just gsdoc from source)",
741
@"\t\t\tSTR\t(\"\")\n\tspecify where headers "
742
@"are to be documented as being found",
744
@"\t\t\tSTR\t(\"Untitled\")\n\thead title name of this documentation",
746
@"\t\tSTR\t(.)\n\tdirectory to search for .h files",
748
@"\tSTR\t(.)\n\tdirectory to place generated files and "
749
@"search for gsdoc files",
750
@"DocumentationDirectory",
751
@"\t\t\tSTR\t(\"\")\n\tname of file containing filenames to document",
753
@"\t\t\tBOOL\t(NO)\n\tremove all generated files",
755
@"\t\tBOOL\t(NO)\n\tremove template files when cleaning",
757
@"\t\t\tSTR\t(\"\")\n\tfilename to link to from generated HTML",
759
@"\t\t\tspecial\t(nil)\n\tdictionary used to preprocess (see docs)",
761
@"\t\t\tBOOL\t(NO)\n\twhether to insert information on "
762
@"standards compliance",
764
@"BOOL\t(NO)\n\tdocument private instance variables",
765
@"DocumentAllInstanceVariables",
766
@"\tBOOL\t(YES)\n\tdocument instance variables at all",
767
@"DocumentInstanceVariables",
768
@"\tBOOL\t(YES)\n\tput instance variable docs at end of class",
769
@"InstanceVariablesAtEnd",
770
@"\t\tSTR\t(\"None\")\n\twhether to include other projects in index",
772
@"\t\tSTR\t(\"None\")\n\twhether to include system projects in index",
774
@"\t\t\tSTR\t(\"None\")\n\texplicit list of other projects to index",
776
@"\t\tSTR\t(\"\")\n\tfile to output dependency info for 'make' into",
778
@"\t\tSTR\t(\"\")\n\tfile into which docs for constants "
779
@"should be consolidated",
780
@"ConstantsTemplate",
781
@"\t\tSTR\t(\"\")\n\tfile into which docs for functions "
782
@"should be consolidated",
783
@"FunctionsTemplate",
784
@"\t\tSTR\t(\"\")\n\tfile into which docs for macros "
785
@"should be consolidated",
787
@"\t\tSTR\t(\"\")\n\tfile into which docs for typedefs "
788
@"should be consolidated",
790
@"\t\tSTR\t(\"\")\n\tfile into which docs for variables "
791
@"should be consolidated",
792
@"VariablesTemplate",
793
@"\t\tBOOL\t(NO)\n\tif YES, create documentation pages "
794
@"for display in HTML frames",
797
argSet = [NSSet setWithArray: [argsRecognized allKeys]];
798
argsGiven = [[NSProcessInfo processInfo] arguments];
800
for (i = 0; i < [argsGiven count]; i++)
802
arg = [argsGiven objectAtIndex: i];
803
if ([arg characterAtIndex: 0] == '-')
805
opt = ([arg characterAtIndex: 1] == '-') ?
806
[arg substringFromIndex: 2] : [arg substringFromIndex: 1];
812
if (![argSet containsObject: opt] || [@"help" isEqual: opt])
814
NSArray *args = [argsRecognized allKeys];
816
GSPrintf(stderr, @"Usage:\n");
817
GSPrintf(stderr, [NSString stringWithFormat:
818
@" %@ [options] [files]\n", [argsGiven objectAtIndex: 0]]);
819
GSPrintf(stderr, @"\n Options:\n");
820
for (i = 0; i < [args count]; i++)
822
arg = [args objectAtIndex: i];
824
[NSString stringWithFormat: @" -%@\t%@\n\n",
825
arg, [argsRecognized objectForKey: arg]]);
828
GSPrintf(stderr, @"\n Files:\n");
829
GSPrintf(stderr, @" [.h files]\t\tMust be in 'HeaderDirectory'\n");
831
@" [.m files]\t\tAbsolute or relative path (from here)\n");
833
@" [.gsdoc files]\tMust be in 'DocumentationDirectory'\n\n");
838
mgr = [NSFileManager defaultManager];
392
841
verbose = [defs boolForKey: @"Verbose"];
842
warn = [defs boolForKey: @"Warn"];
393
843
ignoreDependencies = [defs boolForKey: @"IgnoreDependencies"];
394
844
showDependencies = [defs boolForKey: @"ShowDependencies"];
395
845
if (ignoreDependencies == YES)
added
removed
Tools/autogsdoc.m
