AUTOGSDOC(1) GNUstep System Manual AUTOGSDOC(1)
NAME
autogsdoc - GNUstep API documentation generator and XML->HTML converter
SYNOPSIS
autogsdoc [-Files filename] [-GenerateHtml YES|no] [-Clean yes|NO]
[-CleanTemplates yes|NO] [-IgnoreDependencies yes|NO] [-MakeDependencies
yes|NO] [-ShowDependencies yes|NO] [-HeaderDirectory path] [-Documenta-
tionDirectory path] [-Declared location] [-Project title] [-Standards
yes|NO] [-DocumentAllInstanceVariables yes|NO] [-DocumentInstanceVari-
ables YES|no] [-InstanceVariablesAtEnd yes|NO] [-ConstantsTemplate file-
name] [-FunctionsTemplate filename] [-MacrosTemplate filename] [-Type-
defsTemplate filename] [-VariablesTemplate filename] [-SystemProjects
string] [-LocalProjects string] [-Projects dictString] [-Verbose yes|NO]
[-Warn yes|NO] [-WordMap dictString] [files]
DESCRIPTION
The autogsdoc tool is a command-line utility that helps developers pro-
duce reference documentation for GNUstep APIs. It also enables develop-
ers to write and maintain other documentation in XML and have it con-
verted to HTML. In detail, autogsdoc will:
- Extract special comments describing the public interfaces of classes,
categories, protocols, functions, and macros from Objective C source
code (header files and optionally source files) into GSDoc XML files.
- Convert GSDoc XML files, whether generated from source code or written
manually by developers, into HTML.
- Construct indices based on GSDoc XML file sets, and convert those to
HTML as well.
The most common usage this is to run the command with one or more header
file names as arguments ... the tool will automatically parse corre-
sponding source files in the same directory as the headers (or the cur-
rent directory, or the directory specified using the DocumentationDirec-
tory default), and produce GSDoc and HTML files as output. For best re-
sults this mode should be run from the directory containing the source
files. (Note that since C is a subset of Objective C, this tool can op-
erate to document functions and other C structures in plain C source.)
GSDoc files may also be given directly in addition or by themselves, and
will be converted to HTML. See the GSDoc HTML documentation or the gs-
doc(7) man page for information on the GSDoc format.
Finally, HTML files may be given on the command line. Cross-references
to other parts of code documentation found within them will be rewritten
based on what is found in the project currently.
SOURCE CODE MARKUP
The source code parser will automatically produce GSDoc documents list-
ing the methods in the classes found in the source files, and it will
include text from specially formatted comments from the source files.
Any comment beginning with slash and two asterisks rather than the com-
mon slash and single asterisk, is taken to be GSDoc markup, to be use as
the description of the class or method following it. This comment text
is reformatted and then inserted into the output.
Where multiple comments are associated with the same item, they are
joined together with a line break (<br/>) between each if necessary.
The tool can easily be used to document programs as well as libraries,
simply by giving it the name of the source file containing the main()
function of the program - it takes the special comments from that func-
tion and handles them specially, inserting them as a section at the end
of the first chapter of the document (it creates the first chapter if
necessary).
Options are described in the section Arguments and Defaults below.
EXTRA MARKUP
There are some cases where special extra processing is performed, pre-
dominantly in the first comment found in the source file, from which
various chunks of GSDoc markup may be extracted and placed into appro-
priate locations in the output document -
AutogsdocSource:
In any line where AutogsdocSource: is found, the remainder of the
line is taken as a source file name to be used instead of making the
assumption that each .h file processed uses a .m file of the same
name. You may supply multiple AutogsdocSource: lines where a header
file declares items which are defined in multiple source files. If
a file name is absolute, it is used just as supplied. If on the
other hand, it is a relative path, the software looks for the source
file first relative to the location of the header file, and if not
found there, relative to the current directory in which autogsdoc is
running, and finally relative to the directory specified by the Doc-
umentationDirectory default.
<abstract>
An abstract of the content of the document ... placed in the head of
the GSDoc output.
<author>
A description of the author of the code - may be repeated to handle
the case where a document has multiple authors. Placed in the head
of the GSDoc output. As an aid to readability of the source, some
special additional processing is performed related to the document
author - Any line of the form 'Author: name <email-address>', or
'By: name <email-address>', or 'Author: name' or 'By: name' will be
recognised and converted to an author element, possibly containing
an email element.
<back>
Placed in the GSDoc output just before the end of the body of the
document - intended to be used for appendices, index etc..
<chapter>
Placed immediately before any generated class documentation ... in-
tended to be used to provide overall description of how the code be-
ing documented works. Any documentation for the main() function of
a program is inserted as a section at the end of this chapter.
<copy>
Copyright of the content of the document ... placed in the head of
the GSDoc output. As an aid to readability of the source, some spe-
cial additional processing is performed - Any line of the form
'Copyright (C) text' will be recognised and converted to a copy ele-
ment.
<date>
Date of the revision of the document ... placed in the head of the
GSDoc output. If this is omitted the tool will try to construct a
value from the RCS Date tag (if available).
<front>
Inserted into the document at the start of the body ... intended to
provide for introduction or contents pages etc.
<title>
Title of the document ... placed in the head of the GSDoc output.
If this is omitted the tool will generate a (probably poor) title of
its own - so you should include this markup manually.
<version>
Version identifier of the document ... placed in the head of the GS-
Doc output. If this is omitted the tool will try to construct a
value from the RCS Revision tag (if available).
NB The markup just described may be used within class, category, or pro-
tocol documentation ... if so, it is extracted and wrapped round the
rest of the documentation for the class as the class's chapter. The
rest of the class documentation is normally inserted at the end of the
chapter, but may instead be substituted in in place of the <unit>
pseudo-element within the <chapter> element.
METHOD MARKUP
In comments being used to provide text for a method description, the
following markup is removed from the text and handled specially -
<init>
The method is marked as being the designated initialiser for the
class.
<override-subclass>
The method is marked as being one which subclasses must override
(e.g. an abstract method).
<override-never>
The method is marked as being one which subclasses should NOT over-
ride.
<standards>
The markup is removed from the description and placed after it in
the GSDoc output - so that the method is described as conforming (or
not conforming) to the specified standards.
AUTOMATED MARKUP
Generally, the text in comments is reformatted to standardise and indent
it nicely ... the reformatting is not performed on any text inside an
<example> element. When the text is reformatted, it is broken into
whitespace separated “words” which are then subjected to some extra pro-
cessing ...
Certain well known constants such as YES, NO, and nil are enclosed
in <code> ... </code> markup.
The names of method arguments within method descriptions are en-
closed in <var> ... </var> markup.
Method names (beginning with a plus or minus) are enclosed in
<ref...> ... </ref> markup. E.g. "-init" (without the quotes) would
be wrapped in a GSDoc reference element to point to the init method
of the current class or, if only one known class had an init method,
it would refer to the method of that class. Note the fact that the
method name must be surrounded by whitespace to be recognized
(though a comma, fullstop, or semicolon at the end of the specifier
will act like whitespace).
Method specifiers including class names (beginning and ending with
square brackets) are enclosed in <ref...> ... </ref> markup. e.g.
'[NSObject-init]', will create a reference to the init method of
NSObject (either the class proper, or any of its categories), while
'[(NSCopying)-copyWithZone:]', creates a reference to a method in
the NSCopying protocol. Note that no spaces must appear between the
square brackets in these specifiers. Protocol names are enclosed in
round brackets rather than the customary angle brackets, because GS-
Doc is an XML language, and XML treats angle brackets specially.
Function names (ending with '()') other than 'main()' are enclosed
in <ref...> ... </ref> markup. E.g. "NSLogv()" (without the quotes)
would be wrapped in a GSDoc reference element to point to the docu-
mentation of the NSLog function. Note the fact that the function
name must be surrounded by whitespace (though a comma, fullstop, or
semicolon at the end of the specifier will also act as a whitespace
terminator).
ARGUMENTS AND DEFAULTS
The tool accepts certain user defaults (which can of course be supplied
as command-line arguments by prepending '-' before the default name and
giving the value afterwards, as in -Clean YES):
Clean
If this boolean value is set to YES, then rather than generating
documentation, the tool removes all GSDoc files generated in the
project, and all html files generated from them (as well as any
which would be generated from GSDoc files listed explicitly), and
finally removes the project index file. The only exception to this
is that template GSDoc files (i.e. those specified using "-Con-
stantsTemplate ...", "-FunctionsTemplate ..." arguments etc) are
not deleted unless the CleanTemplates flag is set.
CleanTemplates
This flag specifies whether template GSDoc files are to be removed
along with other files when the Clean option is specified. The de-
fault is for them not to be removed ... since these templates may
have been produced manually and just had data inserted into them.
ConstantsTemplate
Specify the name of a template document into which documentation
about constants should be inserted from all files in the project.
This is useful if constants in the source code are scattered around
many files, and you need to group them into one place. You are re-
sponsible for ensuring that the basic template document (into which
individual constant documentation is inserted) contains all the
other information you want, but as a convenience autogsdoc will gen-
erate a simple template (which you may then edit) for you if the
file does not exist. Insertion takes place immediately before the
back element (or if that does not exist, immediately before the end
of the body element) in the template.
Declared
Specify where headers are to be documented as being found. The ac-
tual name produced in the documentation is formed by appending the
last component of the header file name to the value of this default.
If this default is not specified, the full name of the header file
(as supplied on the command line), with the HeaderDirectory default
prepended, is used. A typical usage of this might be '"-Declared
Foundation"' when generating documentation for the GNUstep base li-
brary. This would result in the documentation saying that NSString
is declared in 'Foundation/NSString.h'
DocumentAllInstanceVariables
This flag permits you to generate documentation for all instance
variables. Normally, only those explicitly declared 'public' or
'protected' will be documented.
DocumentInstanceVariables
This flag permits you to turn off documentation for instance vari-
ables completely. Normally, explicitly declared 'public' or 'pro-
tected' instance variables will be documented.
InstanceVariablesAtEnd
This flag, if set, directs the HTML generator to place instance
variable documentation at the end of the class, instead of the be-
ginning. This is useful if you use a lot of protected instance
variables which are only going to be of secondary interest to gen-
eral users of the class.
DocumentationDirectory
May be used to specify the directory in which generated documenta-
tion is to be placed. If this is not set, output is placed in the
current directory. This directory is also used as a last resort to
locate source files (not headers), and more importantly, it is used
as the first and only resort to locate any .gsdoc files that are
passed in on the command line. Any path information given for these
files is removed and they are searched for in 'DocumentationDirec-
tory' (even though they may not have been autogenerated).
Files
Specifies the name of a file containing a list of file names as a
property list array (name1,name2,...) format. If this is present,
filenames in the program argument list are ignored and the names in
this file are used as the list of names to process.
FunctionsTemplate
Specify the name of a template document into which documentation
about functions should be inserted from all files in the project.
This is useful if function source code is scattered around many
files, and you need to group it into one place. You are responsible
for ensuring that the basic template document (into which individual
function documentation is inserted) contains all the other informa-
tion you want, but as a convenience autogsdoc will generate a simple
template (which you may then edit) for you if the file does not ex-
ist. Insertion takes place immediately before the back element (or
if that does not exist, immediately before the end of the body ele-
ment) in the template.
GenerateHtml
May be used to specify if HTML output is to be generated. Defaults
to YES.
HeaderDirectory
May be used to specify the directory to be searched for header
files. When supplied, this value is prepended to relative header
names, otherwise the relative header names are interpreted relative
to the current directory. Header files specified as absolute paths
are not influenced by this default.
IgnoreDependencies
A boolean value which may be used to specify that the program should
ignore file modification times and regenerate files anyway. Pro-
vided for use in conjunction with the 'make' system, which is ex-
pected to manage dependency checking itsself.
LocalProjects
This value is used to control the automatic inclusion of local ex-
ternal projects into the indexing system for generation of cross-
references in final document output. If set to 'None', then no lo-
cal project references are done, otherwise, the 'Local' GNUstep doc-
umentation directory is recursively searched for files with a '.igs-
doc' extension, and the indexing information from those files is
used. The value of this string is also used to generate the file-
names in the cross reference ... if it is an empty string, the path
to use is assumed to be a file in the same directory where the igs-
doc file was found, otherwise it is used as a prefix to the name in
the index. NB. Local projects with the same name as the project
currently being documented will not be included by this mechanism.
If you wish to include such projects, you must do so explicitly us-
ing -Projects ...
MacrosTemplate
Specify the name of a template document into which documentation
about macros should be inserted from all files in the project. This
is useful if macro code is scattered around many files, and you need
to group it into one place. You are responsible for ensuring that
the basic template document (into which individual macro documenta-
tion is inserted) contains all the other information you want, but
as a convenience autogsdoc will generate a simple template (which
you may then edit) for you if the file does not exist. Insertion
takes place immediately before the back element (or if that does not
exist, immediately before the end of the body
element) in the template.
MakeDependencies
A filename to be used to output dependency information for make.
This will take the form of listing all header and source files known
for the project as dependencies of the project name (see 'Project').
Project
May be used to specify the name of this project ... determines the
name of the index reference file produced as part of the documenta-
tion to provide information enabling other projects to cross-refer-
ence to items in this project.
Projects
This value may be supplied as a dictionary containing the paths to
the igsdoc index/reference files used by external projects, along
with values to be used to map the filenames found in the indexes.
For example, if a project index (igsdoc) file says that the class
'Foo' is found in the file 'Foo', and the path associated with that
project index is '/usr/share/doc/proj', Then generated html output
may reference the class as being in '/usr/share/doc/prj/Foo.html' .
Note that a dictionary may be given on the command line by using the
standard PropertyList format (not the XML format of OS X), using
semicolons as line-separators, and enclosing it in single quotes.
ShowDependencies
A boolean value which may be used to specify that the program should
log which files are being regenerated because of their dependencies
on other files.
Standards
A boolean value used to specify whether the program should insert
information about standards complience into the documentation. This
should only be used when documenting the GNUstep libraries and tools
themselves as it assumes that the code being documented is part of
GNUstep and possibly complies with the OpenStep standard or imple-
ments MacOS-X compatible methods.
SystemProjects
This value is used to control the automatic inclusion of system ex-
ternal projects into the indexing system for generation of cross-
references in final document output. If set to 'None', then no sys-
tem project references are done, otherwise, the 'System' GNUstep
documentation directory is recursively searched for files with a
'.igsdoc' extension, and the indexing information from those files
is used. The value of this string is also used to generate the
filenames in the cross reference ... if it is an empty string, the
path to use is assumed to be a file in the same directory where the
igsdoc file was found, otherwise it is used as a prefix to the name
in the index. NB. System projects with the same name as the project
currently being documented will not be included by this mechanism.
If you wish to include such projects, you must do so explicitly us-
ing -Projects ...
TypedefsTemplate
Specify the name of a template document into which documentation
about typedefs should be inserted from all files in the project.
This is useful if typedef source code is scattered around many
files, and you need to group it into one place. You are responsible
for ensuring that the basic template document (into which individual
typedef documentation is inserted) contains all the other informa-
tion you want, but as a convenience autogsdoc will generate a simple
template (which you may then edit) for you if the file does not ex-
ist. Insertion takes place immediately before the back element (or
if that does not exist, immediately before the end of the body ele-
ment) in the template.
Up A string used to supply the name to be used in the 'up' link from
generated GSDoc documents. This should normally be the name of a
file which contains an index of the contents of a project. If this
is missing or set to an empty string, then no 'up' link will be pro-
vided in the documents.
VariablesTemplate
Specify the name of a template document into which documentation
about variables should be inserted from all files in the project.
This is useful if variable source code is scattered around many
files, and you need to group it into one place. You are responsible
for ensuring that the basic template document (into which individual
variable documentation is inserted) contains all the other informa-
tion you want, but as a convenience autogsdoc will generate a simple
template (which you may then edit) for you if the file does not ex-
ist. Insertion takes place immediately before the back element (or
if that does not exist, immediately before the end of the body ele-
ment) in the template.
Verbose
A boolean used to specify whether you want verbose debug/warning
output to be produced.
Warn
A boolean used to specify whether you want standard warning output
(e.g. report of undocumented methods) produced.
WordMap
This value is a dictionary used to map identifiers/keywords found in
the source files to other words. Generally you will not have to
use this, but it is sometimes helpful to avoid the parser being con-
fused by the use of C preprocessor macros. You can effectively re-
define the macro to something less confusing. The value you map the
identifier to must be one of - Another identifier, An empty string -
the value is ignored, Two slashes ('//') - the rest of the line is
ignored. Note that a dictionary may be given on the command line by
using the standard PropertyList format (not the XML format of OS X),
using semicolons as line-separators, and enclosing it in single
quotes.
INTER-DOCUMENT LINKAGE
The 'Up' default is used to specify the name of a document which should
be used as the 'up' link for any other documents used. This name must
not include a path or extension. Generally, the document referred to by
this default should be a hand-edited GSDoc document which should have a
<em>back</em> section containing a project index. e.g.
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN"
"http://www.gnustep.org/gsdoc-1_0_3.xml">
<gsdoc base="index">
<head>
<title>My project reference</title>
<author name="my name"></author>
</head>
<body>
<chapter>
<heading>My project reference</heading>
</chapter>
<back>
<index scope="project" type="title" />
</back>
</body>
</gsdoc>
FILES
Source: .h, .m, .c
GSDoc: .gsdoc
Index: .igsdoc
HTML: .html
BUGS
Several GSDoc elements are not rendered properly into HTML yet. These
are: <prjref>, <EOEntity>, <EOModel>.
DIAGNOSTICS
Error messages and warnings can come from each of the stages of the
pipeline: top-level control, source parsing, GSDoc parsing, and index-
ing.
SEE ALSO
gsdoc(7), GNUstep(7)
HISTORY
Autogsdoc combined the capabilities of two earlier tools, 'autodoc' and
'gsdoc', which performed the source->GSDoc and GSDoc->HTML translations
respectively. These earlier tools and the GSDoc format were developed
for GNUstep based on the earlier GDML SGML language.
This manual page first appeared in gnustep-base 1.9.2 (March 2004).
AUTHORS
autogsdoc was written by Richard Frith-Macdonald <rfm@gnu.org>
This manual page added by Adrian Robert <arobert@cogsci.ucsd.edu>.
GNUstep March 2004 AUTOGSDOC(1)
Generated by dwww version 1.16 on Sat Oct 3 06:46:29 CEST 2026.