Provided by: gnustep-base-runtime_1.24.0-1ubuntu3_amd64 
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] [-DocumentationDirectory path] [-Declared location] [-Project
title] [-Standards yes|NO] [-DocumentAllInstanceVariables yes|NO]
[-DocumentInstanceVariables YES|no] [-InstanceVariablesAtEnd yes|NO] [-ConstantsTemplate
filename] [-FunctionsTemplate filename] [-MacrosTemplate filename] [-TypedefsTemplate
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 produce reference
documentation for GNUstep APIs. It also enables developers to write and maintain other
documentation in XML and have it converted 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 corresponding source files in the same
directory as the headers (or the current directory, or the directory specified using the
DocumentationDirectory default), and produce GSDoc and HTML files as output. For best
results 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 operate 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 gsdoc(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 listing 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 common 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 function 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, predominantly in the
first comment found in the source file, from which various chunks of GSDoc markup may be
extracted and placed into appropriate 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
DocumentationDirectory 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 ... intended to be used
to provide overall description of how the code being 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 special additional processing is
performed - Any line of the form 'Copyright (C) text' will be recognised and converted
to a copy element.
<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 GSDoc 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 protocol 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 override.
<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 processing ...
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 enclosed 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 GSDoc 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 documentation 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 "-ConstantsTemplate ...",
"-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 default 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 responsible 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 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.
Declared
Specify where headers are to be documented as being found. The actual 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 library. 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 variables completely.
Normally, explicitly declared 'public' or 'protected' 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 beginning. This is useful if you use a lot of
protected instance variables which are only going to be of secondary interest to
general users of the class.
DocumentationDirectory
May be used to specify the directory in which generated documentation 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 'DocumentationDirectory' (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 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.
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. Provided for use in conjunction with
the 'make' system, which is expected to manage dependency checking itsself.
LocalProjects
This value is used to control the automatic inclusion of local external projects into
the indexing system for generation of cross-references in final document output. If
set to 'None', then no local project references are done, otherwise, the 'Local'
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.
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 using -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 documentation
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 documentation to provide information enabling
other projects to cross-reference 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/doc/proj', Then generated html output may reference the
class as being in '/usr/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 implements MacOS-X compatible methods.
SystemProjects
This value is used to control the automatic inclusion of system external projects into
the indexing system for generation of cross-references in final document output. If
set to 'None', then no system 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 using -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 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.
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 provided 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 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.
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 confused by the use of C preprocessor macros. You can
effectively redefine 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 indexing.
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>.