The GSDoc markup language is an XML language designed specifically
for writing documentation for the
This is also an example, as well as a test case, of the new GNUstep documentation markup language (GSDoc).
There are several reasons for producing the new markup language -
So, with only one markup language available that supported Objective-C, and with XML software becoming available, the decision was to take GDML and update it to be an XML language, in the hope that this would -
The GSDoc markup language is defined by an SGML DTD, that specifies the tags that may be used in marking up a GSDoc document, and how and where those tags may be placed. Please see the DTD for a precise specification.
The gsdoc DTD defines an XML language - that is, a markup language that conforms to a specific subset of SGML features defined as XML. The advantage of XML is that it provides most of the useful features of SGML while being much more light-weight (easy to use) because you can forget about the rest of SGML. As XML looks set to become increasingly popular, we can hope that documentation written with an XML language will be easily imported into XML software tools as they become available, so we will not (in the GNUstep project) need to devote a lot of time and effort to maintaining documentation tools.
A GSDoc document consists of a head and a body wrapped inside the overall document framework that looks like this -
The above example shows a GSDoc document framework. The first line specifies the XML version that the document conforms to. The second line specifies the version of GSDoc that the document conforms to. The third and final lines frame the main part of the document and supply all the (optional) attributes of the gsdoc element -
The document head contains information about the document as a whole: its title, authors, version, modification date, copyright, and perhaps an abstract of its contents. The title and at least one author are the only parts of the document head that must be present.
The above example shows all the elements possible in a document head -
The author of the document, also specifying an email address at which the author may be reached, a URL for a web page giving some information about the author, and an additional description of the author.
Of course, a document may have more than one author, in which case you simply write multiple author elements.
The document body contains the main part of the document, it consists of an optional front part (for contents pages, overview etc), a sequence of any number of chapters, and an optional back part (for indexes, appendices etc). Normally, each of these three parts of the document would be expected to have their own separate page numbering schemes.
The above example shows all the elements possible in a document body -
The contents element is used as a marker to specify that an automatically generated contents page (listing the chapters in the document) is to be inserted.
After the front part of the document body comes a mandatory sequence of one or more chapters. This is where the main part of the document resides. Each chapter consists of a heading, any number of blocks of information, and any number of sections.
The index element is used as a marker to specify that an automatically generated index is to be inserted. The type attribute of the index specifies what sort of item is to be in the index - the default type of label causes an index of all label and entry elements to be generated.
Actually, there is no such thing as a block element, this is just shorthand for refering to a group of elements that can be used in similar ways. The block elements are -
The br element is an empty element that always appears as <br/> in the document. This element simply specifies that a line-break should appear in the output text at this point.
This is the basic unit of the document - the main part of a document body will contain at least one chapter. Each chapter consists of a heading, zero or more blocks, and zero or more sections.
Each chapter in the document is automatically listed in the documents contents page (if it has one).
This is the main element for Objective-C code documentation. The name attribute is required for this element - it is the name of the class. The super attribute is normally necessary to provide the name of the superclass.
The elements in a class are - an optional declared element, zero or more conform element, an optional description, zero or more method elements, and an optional standards element.
This element contains simple text giving the name of a protocol or interface to which a class conforms.
This element contains simple text giving the name of the header file in which something is declared.
This element is used to contain descriptions of how software functions. It may contain text, but may also contain lists, paragraphs, examples and embedded data.
Each chapter, section sub-section, or sub-sub-section has a heading as the first thing in it. These headings introduce the sections and are listed in the contents page.
The paragraph element simply contains text. Most descriptive writing is inside paragraphs.
The section element is just like a chapter, except that it contains sub-sections where a chapter would contain sections.
The standards element contains any number of
standard elements whioch specify what standards a particular
piece of code does or does not conform to.
The defined values are -
The subsect element is just like a section, except that it contains sub-sub-sections where a section would contain sub-sections.
The subsubsect element is just like a sub-section, except that it contains only a heading and zero or more blocks.
This is not really an element, we simply talk about text where we mean raw text and very simple markup such as -
The gsdoc tool is written in Objective-C and uses the GNUstep base library and the Gnome XML parser library.
This tool is intended to convert GSDoc documents to other formats though, at present, only HTML output is supported.
Use of the tool is trivial - just provide it with a list of gsdoc file names, and it will produce a load of html output files.
The above example take MySource.h and MySource.m and generate one or more gsdoc files (they have the extension .html, so please rename them with .gsdoc extension after running AutoDoc
The above example will parse MyFile1.gsdoc MyFile2.gsdoc and generate MyFile1.html and MyFile2.html. It generate MyProject.gsdocrefs which will countain references of symbols found in MyFile1.gsdoc and MyFile2.gsdoc. MyFile1.html and MyFile2.html will have links to symbols found in MyProject.gsdocrefs and in .gsdocrefs founds in subdirectories of /usr/doc/gnustep. I indicate that the location of this doc will be /usr/doc/gnustep/MyProject. It also generate an index of MyFile1.html and MyFile2.html contents with the template /usr/GNUstep/System/Libraries/Resources/DocTemplates/indextemplate.gsdoc. Index file is index.gsdoc and the resulting file index.html is automatically generated. I define "version" so the index will take this version.