GNUstep Documentation XML markup language (GSDoc)

Authors

Richard Frith-Macdonald: A person who has devotes far too much time to GNUstep development.

Version: 0.1

Date: 4 march, 2000

This documents the GNUstep Documentation markup language and tools

Introduction
- Why another documentation language?
The gsdoc DTD and what it means
The gsdoc conversion tool

Introduction

The GSDoc markup language is an XML language designed specifically for writing documentation for the GNUstep project. In practice, that means that it is designed for writing about software, and in particular, for writing about Objective-C classes.

This is also an example, as well as a test case, of the new GNUstep documentation markup language (GSDoc).

Why another documentation language?

There are several reasons for producing the new markup language -

There were no existing markup languages that dealt well with documenting software written in the Objective-C language, except the GDML language - which has no easy to use support software.
While the DocBook system works nicely for general software documentation, it requires a relatively large amount of support software and comes with a lot of baggage that's not directly useful for GNUstep.
The GNU info system comes with easy to use, lightweight conversion tools, but is particularly ill suited to Objective-C documentation because the colon character using in Objective-C method names is used in info markup.
LinuxDoc, while being a nice basic system, seems to be in the process of being replaced by DocBook.

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 -

Provide optimal support for GNUstep documentation.
Minimize the amount of work needed for development of software tools.
Provide future-proofing in that documentation written in one XML language should be quite easy to convert to another if necessary.

The gsdoc DTD and what it means

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.

Overall document structure

A GSDoc document consists of a head and a body wrapped inside the overall document framework that looks like this -

example


<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.5//EN" "http://www.gnustep.org/gsdoc-0_6_5.xml">
<gsdoc base="MyDoc" prev="First.html" next="Last.html" up="Overview.html">
  <head>
  ... your document head here
  </head>
  <body>
  ... your document body here
  </body>
</gsdoc>

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 -

base: This is optional, but recommended - it specifies the base name for the document. When the document is translated to another format, the output file name should be based on this - eg. if the base name of a document is foo then an html output for this file would be foo.html.
prev: This optional attribute may be used as the name of a document that precedes this one in logical reading order. If the converted output format of the document supports some sort of link between documents, the converter software may insert a link between the two documents.
next: This optional attribute may be used as the name of a document that follows this one in logical reading order. If the converted output format of the document supports some sort of link between documents, the converter software may insert a link between the two documents.
up: This optional attribute may be used as the name of a document that is above this document in some sort of hierarchical structure (a contents list perhaps). If the converted output format of the document supports some sort of link between documents, the converter software may insert a link between the two documents.

The document head

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.

example


  <head>
    <title>GNUstep Documentation XML markup language (GSDoc)</title>
    <author name="Richard Frith-Macdonald">
      <email address="rfm@gnu.org"/>
      <url url="http://www.gnustep.org/developers/whoiswho.html"/>
      <desc>
	A person who has devotes far too much time to GNUstep development.
      </desc>
    </author>
    <version>0.1</version>
    <date>4 march, 2000</date>
    <abstract>
      This documents the GNUstep Documentation markup language and tools
    </abstract>
    <copy>Free Software Foundation, Inc.</copy>
  </head>

The above example shows all the elements possible in a document head -

title

The title of the document.

author

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.

version

The version number of the document.

date

The date at which the document was last modified.

abstract

A short description of the document contents.

copy

The copyright owner of the document.

The document body

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 gsdoc conversion tool

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.