2000-03-05 11:24:24 +00:00
|
|
|
<?xml version="1.0"?>
|
2000-06-21 11:04:41 +00:00
|
|
|
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
|
2000-03-05 11:24:24 +00:00
|
|
|
<gsdoc base="gsdoc">
|
|
|
|
|
<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>
|
2000-06-21 11:04:41 +00:00
|
|
|
<version>0.2</version>
|
|
|
|
|
<date>21 June, 2000</date>
|
2000-03-05 11:24:24 +00:00
|
|
|
<abstract>
|
|
|
|
|
This documents the GNUstep Documentation markup language and tools
|
|
|
|
|
</abstract>
|
2000-03-05 17:22:57 +00:00
|
|
|
<copy>Free Software Foundation, Inc.</copy>
|
2000-03-05 11:24:24 +00:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
<front>
|
|
|
|
|
<contents/>
|
|
|
|
|
|
|
|
|
|
<chapter>
|
|
|
|
|
<heading>Introduction</heading>
|
|
|
|
|
<p>
|
|
|
|
|
The GSDoc markup language is an XML language designed specifically
|
|
|
|
|
for writing documentation for the
|
|
|
|
|
<uref url="http://www.gnustep.org">GNUstep project</uref>.
|
|
|
|
|
In practice, that means that it is designed for writing about
|
|
|
|
|
software, and in particular, for writing about Objective-C classes.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
This is also an example, as well as a test case, of the new
|
|
|
|
|
GNUstep documentation markup language (GSDoc).
|
|
|
|
|
</p>
|
|
|
|
|
<section>
|
|
|
|
|
<heading>Why another documentation language?</heading>
|
|
|
|
|
<p>
|
|
|
|
|
There are several reasons for producing the new markup
|
|
|
|
|
language -
|
|
|
|
|
</p>
|
|
|
|
|
<list>
|
|
|
|
|
<item>
|
|
|
|
|
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.
|
|
|
|
|
</item>
|
|
|
|
|
<item>
|
|
|
|
|
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.
|
|
|
|
|
</item>
|
|
|
|
|
<item>
|
|
|
|
|
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.
|
|
|
|
|
</item>
|
|
|
|
|
<item>
|
2000-03-05 17:25:33 +00:00
|
|
|
LinuxDoc, while being a nice basic system, seems to be
|
2000-03-05 11:24:24 +00:00
|
|
|
in the process of being replaced by DocBook.
|
|
|
|
|
</item>
|
|
|
|
|
</list>
|
|
|
|
|
<p>
|
|
|
|
|
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 -
|
|
|
|
|
</p>
|
|
|
|
|
<list>
|
|
|
|
|
<item>
|
|
|
|
|
Provide optimal support for GNUstep documentation.
|
|
|
|
|
</item>
|
|
|
|
|
<item>
|
2000-03-05 17:25:33 +00:00
|
|
|
Minimize the amount of work needed for development of
|
2000-03-05 11:24:24 +00:00
|
|
|
software tools.
|
|
|
|
|
</item>
|
|
|
|
|
<item>
|
|
|
|
|
Provide future-proofing in that documentation written in one
|
|
|
|
|
XML language should be quite easy to convert to another if
|
|
|
|
|
necessary.
|
|
|
|
|
</item>
|
|
|
|
|
</list>
|
|
|
|
|
</section>
|
|
|
|
|
</chapter>
|
|
|
|
|
</front>
|
|
|
|
|
|
|
|
|
|
<chapter>
|
|
|
|
|
<heading>The gsdoc DTD and what it means</heading>
|
|
|
|
|
<p>
|
|
|
|
|
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.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
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
|
2000-03-05 17:25:33 +00:00
|
|
|
of SGML while being much more light-weight (easy to use) because
|
2000-03-05 11:24:24 +00:00
|
|
|
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.
|
|
|
|
|
</p>
|
2000-03-05 15:45:45 +00:00
|
|
|
<section id="gsdoc">
|
2000-03-05 11:24:24 +00:00
|
|
|
<heading>Overall document structure</heading>
|
|
|
|
|
<p>
|
|
|
|
|
A GSDoc document consists of a <ref id="head">head</ref> and a
|
|
|
|
|
<ref id="body">body</ref> wrapped inside the overall document
|
|
|
|
|
framework that looks like this -
|
|
|
|
|
</p>
|
|
|
|
|
<example>
|
|
|
|
|
<?xml version="1.0"?>
|
2000-06-21 11:04:41 +00:00
|
|
|
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
|
|
|
|
|
<gsdoc base="MyDoc" prev="First" next="Last" up="Overview">
|
2000-03-05 11:24:24 +00:00
|
|
|
<head>
|
|
|
|
|
... your document head here
|
|
|
|
|
</head>
|
|
|
|
|
<body>
|
|
|
|
|
... your document body here
|
|
|
|
|
</body>
|
|
|
|
|
</gsdoc>
|
|
|
|
|
</example>
|
|
|
|
|
<p>
|
|
|
|
|
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 <em>gsdoc</em>
|
|
|
|
|
element -
|
|
|
|
|
</p>
|
|
|
|
|
<deflist>
|
|
|
|
|
<term>base</term>
|
|
|
|
|
<desc>
|
|
|
|
|
This is optional, but recommended - it specifies the base name
|
2000-03-05 17:25:33 +00:00
|
|
|
for the document. When the document is translated to another
|
|
|
|
|
format, the output file name should be based on this - eg.
|
2000-03-05 11:24:24 +00:00
|
|
|
if the base name of a document is <em>foo</em> then an html
|
|
|
|
|
output for this file would be <em>foo.html</em>.
|
|
|
|
|
</desc>
|
|
|
|
|
<term>prev</term>
|
|
|
|
|
<desc>
|
|
|
|
|
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.
|
|
|
|
|
</desc>
|
|
|
|
|
<term>next</term>
|
|
|
|
|
<desc>
|
|
|
|
|
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.
|
|
|
|
|
</desc>
|
|
|
|
|
<term>up</term>
|
|
|
|
|
<desc>
|
|
|
|
|
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.
|
|
|
|
|
</desc>
|
|
|
|
|
</deflist>
|
|
|
|
|
</section>
|
2000-03-05 15:45:45 +00:00
|
|
|
<section id="head">
|
|
|
|
|
<heading>The document head</heading>
|
|
|
|
|
<p>
|
|
|
|
|
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.
|
|
|
|
|
</p>
|
2000-03-05 17:22:57 +00:00
|
|
|
<example>
|
2000-06-21 11:04:41 +00:00
|
|
|
<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>
|
2000-03-05 17:22:57 +00:00
|
|
|
</example>
|
|
|
|
|
<p>
|
2000-03-05 17:25:33 +00:00
|
|
|
The above example shows all the elements possible in a document head -
|
2000-03-05 17:22:57 +00:00
|
|
|
</p>
|
2000-03-05 15:45:45 +00:00
|
|
|
<deflist>
|
|
|
|
|
<term><label id="title">title</label></term>
|
|
|
|
|
<desc>
|
|
|
|
|
The title of the document.
|
|
|
|
|
</desc>
|
2000-03-05 17:22:57 +00:00
|
|
|
<term><label id="author">author</label></term>
|
|
|
|
|
<desc>
|
|
|
|
|
<p>
|
|
|
|
|
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.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Of course, a document may have more than one author, in which
|
|
|
|
|
case you simply write multiple author elements.
|
|
|
|
|
</p>
|
|
|
|
|
</desc>
|
|
|
|
|
<term><label id="version">version</label></term>
|
|
|
|
|
<desc>
|
|
|
|
|
The version number of the document.
|
|
|
|
|
</desc>
|
|
|
|
|
<term><label id="date">date</label></term>
|
|
|
|
|
<desc>
|
|
|
|
|
The date at which the document was last modified.
|
|
|
|
|
</desc>
|
|
|
|
|
<term><label id="abstract">abstract</label></term>
|
|
|
|
|
<desc>
|
|
|
|
|
A <em>short</em> description of the document contents.
|
|
|
|
|
</desc>
|
|
|
|
|
<term><label id="copy">copy</label></term>
|
|
|
|
|
<desc>
|
|
|
|
|
The copyright owner of the document.
|
|
|
|
|
</desc>
|
2000-03-05 15:45:45 +00:00
|
|
|
</deflist>
|
|
|
|
|
</section>
|
|
|
|
|
<section id="body">
|
|
|
|
|
<heading>The document body</heading>
|
|
|
|
|
<p>
|
|
|
|
|
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
|
2000-03-05 17:25:33 +00:00
|
|
|
parts of the document would be expected to have their own separate
|
2000-03-05 15:45:45 +00:00
|
|
|
page numbering schemes.
|
|
|
|
|
</p>
|
2000-06-21 11:04:41 +00:00
|
|
|
<example>
|
|
|
|
|
<body>
|
|
|
|
|
<front>
|
|
|
|
|
<contents/>
|
|
|
|
|
<chapter>
|
|
|
|
|
<heading>Preface</heading>
|
|
|
|
|
<p>
|
|
|
|
|
Here is an introductory chapter for a dummy document.
|
|
|
|
|
</p>
|
|
|
|
|
</chapter>
|
|
|
|
|
</front>
|
|
|
|
|
<chapter>
|
|
|
|
|
<heading>Main text</heading>
|
|
|
|
|
<p>
|
|
|
|
|
Here is the main text of a chapter in the document.
|
|
|
|
|
</p>
|
|
|
|
|
</chapter>
|
|
|
|
|
<back>
|
|
|
|
|
<chapter>
|
|
|
|
|
<heading>Afterword</heading>
|
|
|
|
|
<p>
|
|
|
|
|
Adn after the main part of the doucment we can have some other stuff.
|
|
|
|
|
</p>
|
|
|
|
|
</chapter>
|
|
|
|
|
<index type="class"/>
|
|
|
|
|
</back>
|
|
|
|
|
</body>
|
|
|
|
|
</example>
|
|
|
|
|
<p>
|
|
|
|
|
The above example shows all the elements possible in a document body -
|
|
|
|
|
</p>
|
|
|
|
|
<deflist>
|
|
|
|
|
<term><label id="title">front</label></term>
|
|
|
|
|
<desc>
|
|
|
|
|
This is an optional part of the document that can come before the
|
|
|
|
|
main text. Typically, this could be used to contain an automatically
|
|
|
|
|
generated contents page and possibly an introduction.
|
|
|
|
|
When output is generated in book form, this part of the document
|
|
|
|
|
would probably have a different page numbering scheme from the
|
|
|
|
|
main part.
|
|
|
|
|
</desc>
|
|
|
|
|
<term><label id="chapter">chapter</label></term>
|
|
|
|
|
<desc>
|
|
|
|
|
<p>
|
|
|
|
|
After the <em>front</em> part of the document body comes a
|
|
|
|
|
mandatory sequence of one or more chapters. This is where
|
|
|
|
|
the main part of the document resides.
|
|
|
|
|
</p>
|
|
|
|
|
</desc>
|
|
|
|
|
<term><label id="back">back</label></term>
|
|
|
|
|
<desc>
|
|
|
|
|
After the chapters making up the main part of the body of the
|
|
|
|
|
document is an optional <em>back</em> part which may contain
|
|
|
|
|
chapters (such as appendices) possibly followed by an automatically
|
|
|
|
|
generated index.
|
|
|
|
|
</desc>
|
|
|
|
|
</deflist>
|
2000-03-05 15:45:45 +00:00
|
|
|
</section>
|
2000-03-05 11:24:24 +00:00
|
|
|
</chapter>
|
|
|
|
|
|
|
|
|
|
<chapter>
|
|
|
|
|
<heading>The gsdoc conversion tool</heading>
|
|
|
|
|
<p>
|
|
|
|
|
The gsdoc tool is written in Objective-C and uses the GNUstep base
|
|
|
|
|
library and the Gnome XML parser library.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
This tool is intended to convert GSDoc documents to other formats
|
|
|
|
|
though, at present, only HTML output is supported.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
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.
|
|
|
|
|
</p>
|
|
|
|
|
</chapter>
|
|
|
|
|
|
|
|
|
|
<back>
|
|
|
|
|
<!--
|
|
|
|
|
<chapter>
|
2000-03-05 17:25:33 +00:00
|
|
|
<heading>Afterward</heading>
|
2000-03-05 11:24:24 +00:00
|
|
|
</chapter>
|
|
|
|
|
-->
|
|
|
|
|
<index type="label"/>
|
|
|
|
|
</back>
|
|
|
|
|
</body>
|
|
|
|
|
</gsdoc>
|
