AUTOGSDOC(1)

🦋 autogsdoc 🦋 — 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]
[-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 🌸

Okay bestie, so autogsdoc is this command-line utility that helps developers produce reference documentation for GNUstep APIs. It also lets developers write and maintain other documentation in XML and have it converted to HTML. Iconic, honestly. 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 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 used 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 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 — so when you run with the Clean option, this flag decides whether template GSDoc files get yeeted along with everything else 🗑️. The default is like… nope, they stay, because those templates might've been hand-made and just had data dropped into them. Respect the craft, bestie 💅.
• ConstantsTemplate — give it the name of a template document, and docs about constants from literally every file in the project get inserted into it ✨. Iconic when your constants are scattered across a million files and you need them all in one place. You're the one responsible for making sure the base template doc (the one individual constant docs get inserted into) has all the other info you want — but as a lil convenience, autogsdoc will generate a simple template for you (which you can then edit) if the file doesn't already exist 🫶. Insertion happens immediately before the back element (or, if that's not a thing, immediately before the end of the body element) in the template.
• Declared — says where headers should be documented as being found 👀. The actual name in the docs is made by appending the last component of the header file name to this default's value. If you don't set it, the full name of the header file (as supplied on the command line) gets used, with the HeaderDirectory default prepended. Classic usage: "-Declared Foundation" when generating docs for the GNUstep base library — that makes the docs say NSString is declared in Foundation/NSString.h 🎀.
• DocumentAllInstanceVariables — this flag lets you generate docs for all instance variables. Normally only the ones explicitly declared public or protected get documented, so this is the "give me everything" button 💖.
• DocumentInstanceVariables — the opposite vibe: this one lets you turn off instance-variable docs completely. Normally, explicitly declared public or protected instance variables get documented — this flag says "not today" 🙈.
• InstanceVariablesAtEnd — set this and the HTML generator puts instance-variable documentation at the end of the class instead of the beginning ✨. Super useful if you've got a pile of protected instance variables that are honestly only of secondary interest to people actually using the class.
• DocumentationDirectory — the directory where generated documentation goes 📁. Not set? Output lands in the current directory. This directory is also the last resort for locating source files (not headers), and — more importantly — it's the first and only resort for locating any .gsdoc files passed in on the command line. Any path info you give for those files gets stripped and they're searched for in DocumentationDirectory (yes, even though they might not have been autogenerated) 👑.
• Files — the name of a file containing a list of file names as a property list array — (name1,name2,...) format 🗂️. If this is present, the filenames in the program argument list get ignored, and the names in this file become the list of names to process. Periodt.
• FunctionsTemplate — same deal as ConstantsTemplate but for functions 🧚: name a template document, and function docs from every file in the project get inserted into it. Great when function source is scattered everywhere and you need it grouped. You're responsible for making sure the base template doc (the one individual function docs go into) has all the other info you want, but autogsdoc will generate a simple template (which you may then edit) for you if the file doesn't exist. Insertion takes place immediately before the back element (or if that doesn't exist, immediately before the end of the body element) in the template.
• GenerateHtml — says whether HTML output should be generated. Defaults to YES 💖.
• HeaderDirectory — the directory searched for header files 🌸. When supplied, this value gets prepended to relative header names; otherwise relative header names are interpreted relative to the current directory. Header files given as absolute paths? They don't care about this default, not even a little.
• IgnoreDependencies — a boolean that tells the program to ignore file modification times and just regenerate everything anyway 🔥. It exists for use with the make system, which is expected to manage dependency checking itself. Make's the main character here, let it cook.
• LocalProjects — controls the automatic inclusion of local external projects into the indexing system used for cross-references in the final doc output 🦋. Set it to None and no local project references happen at all. Otherwise the Local GNUstep documentation directory gets recursively searched for files with a .igsdoc extension, and the indexing info in those files gets used. The value of this string also generates the filenames in the cross reference — if it's an empty string, the path used is assumed to be a file in the same directory where the igsdoc file was found; otherwise it's used as a prefix to the name in the index. NB 🚨 local projects with the same name as the project you're currently documenting will not be included by this mechanism — if you want those, you gotta include them explicitly with -Projects ...
• MacrosTemplate — you guessed it, the macro edition ✨: name a template document and macro docs from all files in the project get inserted into it. Useful when macro code is scattered around and you need it in one place. You're responsible for ensuring the base template doc (into which individual macro docs are inserted) contains all the other info you want, but as a convenience autogsdoc will generate a simple template (which you may then edit) if the file doesn't exist. Insertion takes place immediately before the back element (or if that doesn't exist, immediately before the end of the body element) in the template.
• MakeDependencies — a filename to output dependency information for make 🛠️. It takes the form of listing all header and source files known for the project as dependencies of the project name (see Project).
• Project — the name of this project 👑… which determines the name of the index reference file produced as part of the documentation, giving other projects the info they need to cross-reference items in this one.
• Projects — a dictionary containing the paths to the igsdoc index/reference files used by external projects, plus values used to map the filenames found in those indexes 🗺️. Example time: if a project index (igsdoc) file says 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. Also note: you can give a dictionary on the command line using standard PropertyList format (not the XML format of OS X), using semicolons as line-separators and wrapping it in single quotes 💅.
• ShowDependencies — a boolean that makes the program log which files are being regenerated because of their dependencies on other files 👀. Very "who's responsible for this rebuild" of it.
• Standards — a boolean for whether the program inserts information about standards compliance into the documentation 📋. Should only be used when documenting the GNUstep libraries and tools themselves, since it assumes the code being documented is part of GNUstep and possibly complies with the OpenStep standard or implements MacOS-X compatible methods. So like… don't use it on your random side project, bestie 😭.
• SystemProjects — the system twin of LocalProjects 💜: controls automatic inclusion of system external projects into the indexing system for cross-references in final output. Set to None and no system project references happen. Otherwise the System GNUstep documentation directory gets recursively searched for files with a .igsdoc extension, and their indexing info is used. The string's value also generates the filenames in the cross reference — empty string means the path is assumed to be a file in the same directory where the igsdoc file was found; otherwise it's a prefix to the name in the index. NB 🚨 system projects with the same name as the project currently being documented won't be included by this mechanism — include them explicitly with -Projects ... if you want them.
• TypedefsTemplate — the typedef edition 🎀: name a template document and typedef docs from all files in the project get inserted. Useful when typedef source code is scattered around and you need it grouped. You're responsible for ensuring the base template doc (into which individual typedef documentation is inserted) contains all the other info you want, but as a convenience autogsdoc will generate a simple template (which you may then edit) if the file doesn't exist. Insertion takes place immediately before the back element (or if that doesn't exist, immediately before the end of the body element) in the template.
• Up — a string that supplies the name used in the up link from generated GSDoc documents ⬆️. Normally this should be the name of a file containing an index of the project's contents. If it's missing or set to an empty string, no up link gets provided in the documents at all. Rip the up link, gone but not forgotten 🫡.

---

okay that's the rest of the defaults list, and there's still more page coming so don't go anywhere 💖

• VariablesTemplate — okay so this is the name of a template document where docs about variables get inserted from all the files in the project. It’s giving “variable source code is scattered around many files, and you need to group it into one place” energy 💖. You are responsible for making sure the basic template document (the one individual variable docs get inserted into) contains all the other info you want — but as a convenience, autogsdoc will generate a simple template for you (which you may then edit) if the file does not exist. Insertion happens 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, bestie — no sneaky paths, no extensions. 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>. Not them being the flop era of HTML rendering, but okay 😭.

🩺 DIAGNOSTICS 🩺

Error messages and warnings can come from each of the stages of the pipeline: top-level control, source parsing, GSDoc parsing, and indexing. So yeah, the drama can start anywhere in the pipeline 💅.

👀 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). Periodt.

👑 AUTHORS 👑

autogsdoc was written by Richard Frith-Macdonald <rfm@gnu.org> 🫶

This manual page added by Adrian Robert <arobert@cogsci.ucsd.edu>. ⭐

---

That’s the whole page, bestie — it’s from GNUstep, dated March 2004, and it’s AUTOGSDOC(1). Stay iconic. 💅👑