1AUTOGSDOC(1)                 GNUstep System Manual                AUTOGSDOC(1)
2
3
4

NAME

6       autogsdoc - GNUstep API documentation generator and XML->HTML converter
7
8

SYNOPSIS

10       autogsdoc  [-Files  filename]  [-GenerateHtml  YES|no]  [-Clean yes|NO]
11       [-CleanTemplates yes|NO] [-IgnoreDependencies  yes|NO]  [-MakeDependen‐
12       cies yes|NO] [-ShowDependencies yes|NO] [-HeaderDirectory path] [-Docu‐
13       mentationDirectory path] [-Declared location] [-Project title]  [-Stan‐
14       dards   yes|NO]  [-DocumentAllInstanceVariables  yes|NO]  [-DocumentIn‐
15       stanceVariables   YES|no]   [-InstanceVariablesAtEnd   yes|NO]   [-Con‐
16       stantsTemplate filename] [-FunctionsTemplate filename] [-MacrosTemplate
17       filename] [-TypedefsTemplate  filename]  [-VariablesTemplate  filename]
18       [-SystemProjects string] [-LocalProjects string] [-Projects dictString]
19       [-Verbose yes|NO] [-Warn yes|NO] [-WordMap dictString] [files]
20
21

DESCRIPTION

23       The autogsdoc tool is a command-line utility that helps developers pro‐
24       duce  reference documentation for GNUstep APIs.  It also enables devel‐
25       opers to write and maintain other documentation in XML and have it con‐
26       verted to HTML.  In detail, autogsdoc will:
27
28       - Extract special comments describing the public interfaces of classes,
29         categories, protocols, functions, and macros from Objective C  source
30         code (header files and optionally source files) into GSDoc XML files.
31
32       - Convert  GSDoc XML files, whether generated from source code or writ‐
33         ten manually by developers, into HTML.
34
35       - Construct indices based on GSDoc XML file sets, and convert those  to
36         HTML as well.
37
38
39       The  most  common  usage  this  is  to run the command with one or more
40       header file names as arguments ... the tool  will  automatically  parse
41       corresponding source files in the same directory as the headers (or the
42       current directory, or the  directory  specified  using  the  Documenta‐
43       tionDirectory  default),  and  produce  GSDoc and HTML files as output.
44       For best results this mode should be run from the directory  containing
45       the  source files.  (Note that since C is a subset of Objective C, this
46       tool can operate to document functions and other C structures in  plain
47       C source.)
48
49       GSDoc  files  may  also be given directly in addition or by themselves,
50       and will be converted to HTML.  See the GSDoc HTML documentation or the
51       gsdoc(7) man page for information on the GSDoc format.
52
53       Finally, HTML files may be given on the command line.  Cross-references
54       to other parts of code documentation found within them will be  rewrit‐
55       ten based on what is found in the project currently.
56
57

SOURCE CODE MARKUP

59       The source code parser will automatically produce GSDoc documents list‐
60       ing the methods in the classes found in the source files, and  it  will
61       include text from specially formatted comments from the source files.
62
63       Any comment beginning with slash and two asterisks rather than the com‐
64       mon slash and single asterisk, is taken to be GSDoc markup, to  be  use
65       as  the  description of the class or method following it.  This comment
66       text is reformatted and then inserted into the output.
67       Where multiple comments are associated with the  same  item,  they  are
68       joined together with a line break (<br/>) between each if necessary.
69
70       The  tool can easily be used to document programs as well as libraries,
71       simply by giving it the name of the source file containing  the  main()
72       function of the program - it takes the special comments from that func‐
73       tion and handles them specially, inserting them as a section at the end
74       of  the  first chapter of the document (it creates the first chapter if
75       necessary).
76
77       Options are described in the section Arguments and Defaults below.
78
79

EXTRA MARKUP

81       There are some cases where special extra processing is performed,  pre‐
82       dominantly  in  the  first comment found in the source file, from which
83       various chunks of GSDoc markup may be extracted and placed into  appro‐
84       priate locations in the output document -
85
86       AutogsdocSource:
87           In  any  line where AutogsdocSource: is found, the remainder of the
88           line is taken as a source file name to be used  instead  of  making
89           the  assumption  that  each .h file processed uses a .m file of the
90           same name.  You may supply multiple AutogsdocSource: lines where  a
91           header  file  declares  items  which are defined in multiple source
92           files.  If a file name is absolute, it is used just as supplied. If
93           on  the  other  hand, it is a relative path, the software looks for
94           the source file first relative to the location of the header  file,
95           and  if not found there, relative to the current directory in which
96           autogsdoc is running, and finally relative to the directory  speci‐
97           fied by the DocumentationDirectory default.
98
99       <abstract>
100           An  abstract  of the content of the document ... placed in the head
101           of the GSDoc output.
102
103       <author>
104           A description of the author of the code - may be repeated to handle
105           the case where a document has multiple authors.  Placed in the head
106           of the GSDoc output.  As an aid to readability of the source,  some
107           special  additional processing is performed related to the document
108           author - Any line of the form 'Author:  name  <email-address>',  or
109           'By: name <email-address>', or 'Author: name' or 'By: name' will be
110           recognised and converted to an author element, possibly  containing
111           an email element.
112
113       <back>
114           Placed  in  the GSDoc output just before the end of the body of the
115           document - intended to be used for appendices, index etc..
116
117       <chapter>
118           Placed immediately before any  generated  class  documentation  ...
119           intended  to be used to provide overall description of how the code
120           being documented works.  Any documentation for the main()  function
121           of a program is inserted as a section at the end of this chapter.
122
123       <copy>
124           Copyright  of the content of the document ... placed in the head of
125           the GSDoc output.  As an aid to readability  of  the  source,  some
126           special  additional  processing is performed - Any line of the form
127           'Copyright (C) text' will be recognised and  converted  to  a  copy
128           element.
129
130       <date>
131           Date  of the revision of the document ... placed in the head of the
132           GSDoc output.  If this is omitted the tool will try to construct  a
133           value from the RCS Date tag (if available).
134
135       <front>
136           Inserted into the document at the start of the body ... intended to
137           provide for introduction or contents pages etc.
138
139       <title>
140           Title of the document ... placed in the head of the  GSDoc  output.
141           If  this  is omitted the tool will generate a (probably poor) title
142           of its own - so you should include this markup manually.
143
144       <version>
145           Version identifier of the document ... placed in the  head  of  the
146           GSDoc  output.  If this is omitted the tool will try to construct a
147           value from the RCS Revision tag (if available).
148
149       NB The markup just described may be used  within  class,  category,  or
150       protocol documentation ... if so, it is extracted and wrapped round the
151       rest of the documentation for the class as the  class's  chapter.   The
152       rest  of the class documentation is normally inserted at the end of the
153       chapter, but may instead be substituted  in  in  place  of  the  <unit>
154       pseudo-element within the <chapter> element.
155
156

METHOD MARKUP

158       In  comments  being  used to provide text for a method description, the
159       following markup is removed from the text and handled specially -
160
161       <init>
162           The method is marked as being the designated  initialiser  for  the
163           class.
164
165       <override-subclass>
166           The  method  is  marked as being one which subclasses must override
167           (e.g. an abstract method).
168
169       <override-never>
170           The method is marked as being one which subclasses should NOT over‐
171           ride.
172
173       <standards>
174           The  markup  is removed from the description and placed after it in
175           the GSDoc output - so that the method is  described  as  conforming
176           (or not conforming) to the specified standards.
177
178

AUTOMATED MARKUP

180       Generally,  the  text  in  comments  is  reformatted to standardise and
181       indent it nicely ... the reformatting is  not  performed  on  any  text
182       inside  an <example> element.  When the text is reformatted, it is bro‐
183       ken into whitespace separated “words” which are then subjected to  some
184       extra processing ...
185
186           Certain  well known constants such as YES, NO, and nil are enclosed
187           in <code> ... </code> markup.
188
189           The names  of  method  arguments  within  method  descriptions  are
190           enclosed in <var> ... </var> markup.
191
192           Method  names  (beginning  with  a  plus  or minus) are enclosed in
193           <ref...> ... </ref> markup.   E.g.  "-init"  (without  the  quotes)
194           would  be wrapped in a GSDoc reference element to point to the init
195           method of the current class or, if only one known class had an init
196           method,  it would refer to the method of that class.  Note the fact
197           that the method name must be surrounded by whitespace to be  recog‐
198           nized  (though  a  comma,  fullstop, or semicolon at the end of the
199           specifier will act like whitespace).
200
201           Method specifiers including class names (beginning and ending  with
202           square  brackets) are enclosed in <ref...> ... </ref> markup.  e.g.
203           '[NSObject-init]', will create a reference to the  init  method  of
204           NSObject (either the class proper, or any of its categories), while
205           '[(NSCopying)-copyWithZone:]', creates a reference to a  method  in
206           the  NSCopying  protocol.   Note that no spaces must appear between
207           the square  brackets  in  these  specifiers.   Protocol  names  are
208           enclosed  in  round brackets rather than the customary angle brack‐
209           ets, because GSDoc is an XML language, and XML treats angle  brack‐
210           ets specially.
211
212           Function  names (ending with '()') other than 'main()' are enclosed
213           in <ref...>  ...  </ref>  markup.   E.g.  "NSLogv()"  (without  the
214           quotes)  would  be wrapped in a GSDoc reference element to point to
215           the documentation of the NSLog function.  Note the  fact  that  the
216           function  name  must  be  surrounded by whitespace (though a comma,
217           fullstop, or semicolon at the end of the specifier will also act as
218           a whitespace terminator).
219
220

ARGUMENTS AND DEFAULTS

222       The tool accepts certain user defaults (which can of course be supplied
223       as command-line arguments by prepending '-' before the default name and
224       giving the value afterwards, as in -Clean YES):
225
226       Clean
227           If  this  boolean  value is set to YES, then rather than generating
228           documentation, the tool removes all GSDoc files  generated  in  the
229           project,  and  all  html  files generated from them (as well as any
230           which would be generated from GSDoc files listed  explicitly),  and
231           finally removes the project index file.  The only exception to this
232           is that template GSDoc files (i.e.  those  specified  using  "-Con‐
233           stantsTemplate  ...",  "-FunctionsTemplate ..."  arguments etc) are
234           not deleted unless the CleanTemplates flag is set.
235
236       CleanTemplates
237           This flag specifies whether template GSDoc files are to be  removed
238           along  with  other  files  when the Clean option is specified.  The
239           default is for them not to be removed ... since these templates may
240           have been produced manually and just had data inserted into them.
241
242       ConstantsTemplate
243           Specify  the  name  of a template document into which documentation
244           about constants should be inserted from all files in  the  project.
245           This is useful if constants in the source code are scattered around
246           many files, and you need to group them into  one  place.   You  are
247           responsible  for  ensuring  that  the basic template document (into
248           which individual constant documentation is inserted)  contains  all
249           the other information you want, but as a convenience autogsdoc will
250           generate a simple template (which you may then edit) for you if the
251           file  does not exist.  Insertion takes place immediately before the
252           back element (or if that does not exist, immediately before the end
253           of the body element) in the template.
254
255       Declared
256           Specify  where  headers  are  to be documented as being found.  The
257           actual name produced in the documentation is  formed  by  appending
258           the  last  component  of  the header file name to the value of this
259           default.  If this default is not specified, the full  name  of  the
260           header  file  (as supplied on the command line), with the HeaderDi‐
261           rectory default prepended, is used.  A typical usage of this  might
262           be  '"-Declared  Foundation"' when generating documentation for the
263           GNUstep base library.  This would result in the documentation  say‐
264           ing that NSString is declared in 'Foundation/NSString.h'
265
266       DocumentAllInstanceVariables
267           This  flag  permits  you to generate documentation for all instance
268           variables.  Normally, only those explicitly  declared  'public'  or
269           'protected' will be documented.
270
271       DocumentInstanceVariables
272           This  flag permits you to turn off documentation for instance vari‐
273           ables completely.  Normally, explicitly declared 'public' or  'pro‐
274           tected' instance variables will be documented.
275
276       InstanceVariablesAtEnd
277           This  flag,  if  set,  directs the HTML generator to place instance
278           variable documentation at the end of  the  class,  instead  of  the
279           beginning.   This  is useful if you use a lot of protected instance
280           variables which are only going to be of secondary interest to  gen‐
281           eral users of the class.
282
283       DocumentationDirectory
284           May  be used to specify the directory in which generated documenta‐
285           tion is to be placed.  If this is not set, output is placed in  the
286           current directory.  This directory is also used as a last resort to
287           locate source files (not headers), and more importantly, it is used
288           as  the  first  and only resort to locate any .gsdoc files that are
289           passed in on the command line.   Any  path  information  given  for
290           these  files  is  removed  and they are searched for in 'Documenta‐
291           tionDirectory' (even though they may not have been autogenerated).
292
293       Files
294           Specifies the name of a file containing a list of file names  as  a
295           property list array (name1,name2,...)  format.  If this is present,
296           filenames in the program argument list are ignored and the names in
297           this file are used as the list of names to process.
298
299       FunctionsTemplate
300           Specify  the  name  of a template document into which documentation
301           about functions should be inserted from all files in  the  project.
302           This  is  useful  if  function source code is scattered around many
303           files, and you need to group it into one place.  You are  responsi‐
304           ble for ensuring that the basic template document (into which indi‐
305           vidual function documentation is inserted) contains all  the  other
306           information  you want, but as a convenience autogsdoc will generate
307           a simple template (which you may then edit) for  you  if  the  file
308           does  not exist.  Insertion takes place immediately before the back
309           element (or if that does not exist, immediately before the  end  of
310           the body element) in the template.
311
312       GenerateHtml
313           May be used to specify if HTML output is to be generated.  Defaults
314           to YES.
315
316       HeaderDirectory
317           May be used to specify the directory  to  be  searched  for  header
318           files.   When  supplied, this value is prepended to relative header
319           names, otherwise the relative header names are interpreted relative
320           to the current directory.  Header files specified as absolute paths
321           are not influenced by this default.
322
323       IgnoreDependencies
324           A boolean value which may be  used  to  specify  that  the  program
325           should  ignore file modification times and regenerate files anyway.
326           Provided for use in conjunction with the 'make'  system,  which  is
327           expected to manage dependency checking itsself.
328
329       LocalProjects
330           This  value  is  used  to  control the automatic inclusion of local
331           external projects into the indexing system for generation of cross-
332           references  in  final  document  output.  If set to 'None', then no
333           local project references are done, otherwise, the  'Local'  GNUstep
334           documentation  directory  is  recursively searched for files with a
335           '.igsdoc' extension, and the indexing information from those  files
336           is  used.   The  value  of this string is also used to generate the
337           filenames in the cross reference ... if it is an empty string,  the
338           path to use is assumed to be a file in the same directory where the
339           igsdoc file was found, otherwise it is used as a prefix to the name
340           in the index.  NB. Local projects with the same name as the project
341           currently being documented will not be included by this  mechanism.
342           If  you  wish  to  include such projects, you must do so explicitly
343           using -Projects ...
344
345       MacrosTemplate
346           Specify the name of a template document  into  which  documentation
347           about  macros  should  be  inserted  from all files in the project.
348           This is useful if macro code is scattered around  many  files,  and
349           you  need  to  group  it  into  one place.  You are responsible for
350           ensuring that the basic template document  (into  which  individual
351           macro documentation is inserted) contains all the other information
352           you want, but as a convenience autogsdoc  will  generate  a  simple
353           template  (which  you  may  then edit) for you if the file does not
354           exist.  Insertion takes place immediately before the  back  element
355           (or if that does not exist, immediately before the end of the body
356            element) in the template.
357
358       MakeDependencies
359           A  filename  to  be used to output dependency information for make.
360           This will take the form of listing  all  header  and  source  files
361           known  for  the  project  as  dependencies of the project name (see
362           'Project').
363
364       Project
365           May be used to specify the name of this project ... determines  the
366           name of the index reference file produced as part of the documenta‐
367           tion to provide information enabling other projects to cross-refer‐
368           ence to items in this project.
369
370       Projects
371           This  value may be supplied as a dictionary containing the paths to
372           the igsdoc index/reference files used by external  projects,  along
373           with  values  to be used to map the filenames found in the indexes.
374           For example, if a project index (igsdoc) file says that  the  class
375           'Foo' is found in the file 'Foo', and the path associated with that
376           project index is '/usr/doc/proj', Then generated  html  output  may
377           reference  the  class  as  being in '/usr/doc/prj/Foo.html' .  Note
378           that a dictionary may be given on the command  line  by  using  the
379           standard  PropertyList  format  (not the XML format of OS X), using
380           semicolons as line-separators, and enclosing it in single quotes.
381
382       ShowDependencies
383           A boolean value which may be  used  to  specify  that  the  program
384           should  log  which  files  are  being  regenerated because of their
385           dependencies on other files.
386
387       Standards
388           A boolean value used to specify whether the program  should  insert
389           information  about  standards  complience  into  the documentation.
390           This should only be used when documenting the GNUstep libraries and
391           tools  themselves  as  it assumes that the code being documented is
392           part of GNUstep and possibly complies with the OpenStep standard or
393           implements MacOS-X compatible methods.
394
395       SystemProjects
396           This  value  is  used  to control the automatic inclusion of system
397           external projects into the indexing system for generation of cross-
398           references  in  final  document  output.  If set to 'None', then no
399           system project references are done, otherwise, the 'System' GNUstep
400           documentation  directory  is  recursively searched for files with a
401           '.igsdoc' extension, and the indexing information from those  files
402           is  used.   The  value  of this string is also used to generate the
403           filenames in the cross reference ... if it is an empty string,  the
404           path to use is assumed to be a file in the same directory where the
405           igsdoc file was found, otherwise it is used as a prefix to the name
406           in  the  index.   NB.  System  projects  with  the same name as the
407           project currently being documented will not  be  included  by  this
408           mechanism.   If  you  wish to include such projects, you must do so
409           explicitly using -Projects ...
410
411       TypedefsTemplate
412           Specify the name of a template document  into  which  documentation
413           about  typedefs  should  be inserted from all files in the project.
414           This is useful if typedef source  code  is  scattered  around  many
415           files,  and you need to group it into one place.  You are responsi‐
416           ble for ensuring that the basic template document (into which indi‐
417           vidual  typedef  documentation  is inserted) contains all the other
418           information you want, but as a convenience autogsdoc will  generate
419           a  simple  template  (which  you may then edit) for you if the file
420           does not exist.  Insertion takes place immediately before the  back
421           element  (or  if that does not exist, immediately before the end of
422           the body element) in the template.
423
424       Up  A string used to supply the name to be used in the 'up'  link  from
425           generated  GSDoc  documents.  This should normally be the name of a
426           file which contains an index of the contents of a project.  If this
427           is  missing  or  set  to an empty string, then no 'up' link will be
428           provided in the documents.
429
430       VariablesTemplate
431           Specify the name of a template document  into  which  documentation
432           about  variables  should be inserted from all files in the project.
433           This is useful if variable source code  is  scattered  around  many
434           files,  and you need to group it into one place.  You are responsi‐
435           ble for ensuring that the basic template document (into which indi‐
436           vidual  variable  documentation is inserted) contains all the other
437           information you want, but as a convenience autogsdoc will  generate
438           a  simple  template  (which  you may then edit) for you if the file
439           does not exist.  Insertion takes place immediately before the  back
440           element  (or  if that does not exist, immediately before the end of
441           the body element) in the template.
442
443       Verbose
444           A boolean used to specify whether you  want  verbose  debug/warning
445           output to be produced.
446
447       Warn
448           A  boolean used to specify whether you want standard warning output
449           (e.g. report of undocumented methods) produced.
450
451       WordMap
452           This value is a dictionary used to map  identifiers/keywords  found
453           in  the  source files  to other words.  Generally you will not have
454           to use this, but it is sometimes helpful to avoid the parser  being
455           confused  by the use of C preprocessor macros.  You can effectively
456           redefine the macro to something less confusing.  The value you  map
457           the  identifier  to  must  be one of - Another identifier, An empty
458           string - the value is ignored, Two slashes ('//') - the rest of the
459           line  is  ignored.  Note that a dictionary may be given on the com‐
460           mand line by using the standard PropertyList format  (not  the  XML
461           format of OS X), using semicolons as line-separators, and enclosing
462           it in single quotes.
463
464

INTER-DOCUMENT LINKAGE

466       The 'Up' default is used to specify the name of a document which should
467       be  used  as the 'up' link for any other documents used. This name must
468       not include a path or extension. Generally, the document referred to by
469       this default should be a hand-edited GSDoc document which should have a
470       <em>back</em> section containing a project index. e.g.
471
472       <?xml version="1.0"?>
473       <!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN"
474                               "http://www.gnustep.org/gsdoc-1_0_3.xml">
475       <gsdoc base="index">
476         <head>
477           <title>My project reference</title>
478           <author name="my name"></author>
479         </head>
480         <body>
481           <chapter>
482             <heading>My project reference</heading>
483           </chapter>
484           <back>
485             <index scope="project" type="title" />
486           </back>
487         </body>
488       </gsdoc>
489
490

FILES

492       Source: .h, .m, .c
493       GSDoc:  .gsdoc
494       Index:  .igsdoc
495       HTML:   .html
496
497

BUGS

499       Several GSDoc elements are not rendered properly into HTML yet.   These
500       are: <prjref>, <EOEntity>, <EOModel>.
501
502

DIAGNOSTICS

504       Error  messages  and  warnings  can come from each of the stages of the
505       pipeline: top-level control, source parsing, GSDoc parsing, and  index‐
506       ing.
507
508

SEE ALSO

510       gsdoc(7), GNUstep(7)
511

HISTORY

513       Autogsdoc combined the capabilities of two earlier tools, 'autodoc' and
514       'gsdoc', which performed the source->GSDoc and GSDoc->HTML translations
515       respectively.   These earlier tools and the GSDoc format were developed
516       for GNUstep based on the earlier GDML SGML language.
517
518       This manual page first appeared in gnustep-base 1.9.2 (March 2004).
519

AUTHORS

521       autogsdoc was written by Richard Frith-Macdonald <rfm@gnu.org>
522
523       This manual page added by Adrian Robert <arobert@cogsci.ucsd.edu>.
524
525
526
527GNUstep                           March 2004                      AUTOGSDOC(1)
Impressum