Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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]  [-MakeDependen-
       cies yes|NO] [-ShowDependencies yes|NO] [-HeaderDirectory path] [-Docu-
       mentationDirectory path]	[-Declared location] [-Project title]  [-Stan-
       dards   yes|NO]	[-DocumentAllInstanceVariables	yes|NO]	 [-DocumentIn-
       stanceVariables	 YES|no]   [-InstanceVariablesAtEnd   yes|NO]	[-Con-
       stantsTemplate 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 pro-
       duce  reference documentation for GNUstep APIs.	It also	enables	devel-
       opers 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 writ-
	 ten 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  Documenta-
       tionDirectory  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  rewrit-
       ten 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	speci-
	   fied	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 el-
	   ement.

       <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 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 in-
       dent 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  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	recog-
	   nized  (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  en-
	   closed  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	"-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
	   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 ac-
	   tual	name produced in the documentation is formed by	appending  the
	   last	 component  of	the  header file name to the value of this de-
	   fault.  If this default is not specified,  the  full	 name  of  the
	   header  file	 (as supplied on the command line), with the HeaderDi-
	   rectory 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  say-
	   ing 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 'Documenta-
	   tionDirectory' (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  responsi-
	   ble for ensuring that the basic template document (into which indi-
	   vidual 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 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
	   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 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 en-
	   suring 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 ex-
	   ist.	 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/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 de-
	   pendencies 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 ex-
	   ternal 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 responsi-
	   ble for ensuring that the basic template document (into which indi-
	   vidual  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 responsi-
	   ble for ensuring that the basic template document (into which indi-
	   vidual  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 com-
	   mand	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)

NAME | SYNOPSIS | DESCRIPTION | SOURCE CODE MARKUP | EXTRA MARKUP | METHOD MARKUP | AUTOMATED MARKUP | ARGUMENTS AND DEFAULTS | INTER-DOCUMENT LINKAGE | FILES | BUGS | DIAGNOSTICS | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=autogsdoc&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help