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>
|
2000-06-21 17:28:00 +00:00
|
|
|
And after the main part of the doucment we can have some other stuff.
|
2000-06-21 11:04:41 +00:00
|
|
|
</p>
|
|
|
|
|
</chapter>
|
|
|
|
|
<index type="class"/>
|
|
|
|
|
</back>
|
|
|
|
|
</body>
|
|
|
|
|
</example>
|
|
|
|
|
<p>
|
|
|
|
|
The above example shows all the elements possible in a document body -
|
|
|
|
|
</p>
|
|
|
|
|
<deflist>
|
2000-06-21 17:28:00 +00:00
|
|
|
<term>front</term>
|
2000-06-21 11:04:41 +00:00
|
|
|
<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.
|
2000-06-21 17:28:00 +00:00
|
|
|
<p>
|
|
|
|
|
The <em>contents</em> element is used as a marker to specify
|
|
|
|
|
that an automatically generated contents page (listing the
|
|
|
|
|
chapters in the document) is to be inserted.
|
|
|
|
|
</p>
|
2000-06-21 11:04:41 +00:00
|
|
|
</desc>
|
2000-06-21 17:28:00 +00:00
|
|
|
<term><label id="main">main</label></term>
|
2000-06-21 11:04:41 +00:00
|
|
|
<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.
|
2000-06-21 17:28:00 +00:00
|
|
|
Each <ref id="chapter">chapter</ref> consists of a
|
|
|
|
|
<ref id="heading">heading</ref>, any number
|
|
|
|
|
of blocks of information, and any number of sections.
|
2000-06-21 11:04:41 +00:00
|
|
|
</p>
|
|
|
|
|
</desc>
|
2000-06-21 17:28:00 +00:00
|
|
|
<term>back</term>
|
2000-06-21 11:04:41 +00:00
|
|
|
<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.
|
2000-06-21 17:28:00 +00:00
|
|
|
<p>
|
|
|
|
|
The <em>index</em> element is used as a marker to specify
|
|
|
|
|
that an automatically generated index is to be inserted.
|
|
|
|
|
The <em>type</em> attribute of the index specifies what sort
|
|
|
|
|
of item is to be in the index - the default type of <em>label</em>
|
|
|
|
|
causes an index of all <em>label</em> and <em>entry</em>
|
|
|
|
|
elements to be generated.
|
|
|
|
|
</p>
|
2000-06-21 11:04:41 +00:00
|
|
|
</desc>
|
|
|
|
|
</deflist>
|
2000-03-05 15:45:45 +00:00
|
|
|
</section>
|
2000-03-05 11:24:24 +00:00
|
|
|
</chapter>
|
|
|
|
|
|
2000-06-21 17:28:00 +00:00
|
|
|
<chapter>
|
|
|
|
|
<heading>Element reference</heading>
|
|
|
|
|
<section id="block">
|
|
|
|
|
<heading>block</heading>
|
|
|
|
|
<p>
|
|
|
|
|
Actually, there is no such thing as a <em>block</em> element, this
|
|
|
|
|
is just shorthand for refering to a group of elements that can be
|
|
|
|
|
used in similar ways. The block elements are -
|
|
|
|
|
</p>
|
|
|
|
|
<deflist>
|
|
|
|
|
<term><ref id="embed">embed</ref></term>
|
|
|
|
|
<desc>embeded information from elsewhere</desc>
|
|
|
|
|
<term><ref id="example">example</ref></term>
|
|
|
|
|
<desc>the example</desc>
|
|
|
|
|
<term><ref id="p">p</ref></term>
|
|
|
|
|
<desc>the paragraph</desc>
|
|
|
|
|
<term><label id="list">list</label></term>
|
|
|
|
|
<desc>
|
|
|
|
|
A variety of lists.
|
|
|
|
|
<deflist>
|
|
|
|
|
<term><ref id="list">list</ref></term>
|
|
|
|
|
<desc>a simple list of items</desc>
|
|
|
|
|
<term><ref id="enum">enum</ref></term>
|
|
|
|
|
<desc>an enumerated list</desc>
|
|
|
|
|
<term><ref id="deflist">deflist</ref></term>
|
|
|
|
|
<desc>a list of terms and their definitions</desc>
|
|
|
|
|
<term><ref id="qalist">qalist</ref></term>
|
|
|
|
|
<desc>a list of questions and answers</desc>
|
|
|
|
|
</deflist>
|
|
|
|
|
</desc>
|
|
|
|
|
<term>def</term>
|
|
|
|
|
<desc>
|
|
|
|
|
A variety of specialised elements for software documentation.
|
|
|
|
|
<deflist>
|
|
|
|
|
<term><ref id="class">class</ref></term>
|
|
|
|
|
<desc>An Objective-C class definition</desc>
|
|
|
|
|
<term><ref id="jclass">jclass</ref></term>
|
|
|
|
|
<desc>A Java class definition</desc>
|
|
|
|
|
<term><ref id="category">category</ref></term>
|
|
|
|
|
<desc>An Objective-C category definition</desc>
|
|
|
|
|
<term><ref id="protocol">protocol</ref></term>
|
|
|
|
|
<desc>An Objective-C protocol or Java interface definition</desc>
|
|
|
|
|
<term><ref id="function">function</ref></term>
|
|
|
|
|
<desc>A function definition</desc>
|
|
|
|
|
<term><ref id="macro">macro</ref></term>
|
|
|
|
|
<desc>A macro definition</desc>
|
|
|
|
|
<term><ref id="type">type</ref></term>
|
|
|
|
|
<desc>A type definition</desc>
|
|
|
|
|
<term><ref id="variable">variable</ref></term>
|
|
|
|
|
<desc>A variable definition</desc>
|
|
|
|
|
</deflist>
|
|
|
|
|
</desc>
|
|
|
|
|
</deflist>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="br">
|
|
|
|
|
<heading>br</heading>
|
|
|
|
|
<p>
|
|
|
|
|
The <em>br</em> 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.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="chapter">
|
|
|
|
|
<heading>chapter</heading>
|
|
|
|
|
<p>
|
|
|
|
|
This is the basic unit of the document - the main part of
|
|
|
|
|
a document <ref id="body">body</ref> will contain at least
|
|
|
|
|
one chapter.
|
|
|
|
|
Each chapter consists of a heading,
|
|
|
|
|
zero or more <ref id="block">blocks</ref>,
|
|
|
|
|
and zero or more <ref id="section">sections</ref>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Each chapter in the document is automatically listed in the
|
|
|
|
|
documents contents page (if it has one).
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="class">
|
|
|
|
|
<heading>class</heading>
|
|
|
|
|
<p>
|
|
|
|
|
This is the main element for Objective-C code documentation.
|
|
|
|
|
The <em>name</em> attribute is required for this element - it is
|
|
|
|
|
the name of the class. The <em>super</em> attribute is normally
|
|
|
|
|
necessary to provide the name of the superclass.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The elements in a class are - an optional
|
|
|
|
|
<ref id="declared">declared</ref> element,
|
|
|
|
|
zero or more <ref id="conform">conform</ref> element,
|
|
|
|
|
an optional <ref id="desc">description</ref>,
|
|
|
|
|
zero or more <ref id="method">method</ref> elements,
|
|
|
|
|
and an optional <ref id="standards">standards</ref> element.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="conform">
|
|
|
|
|
<heading>conform</heading>
|
|
|
|
|
<p>
|
|
|
|
|
This element contains simple text giving the name of a protocol
|
|
|
|
|
or interface to which a class conforms.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="declared">
|
|
|
|
|
<heading>declared</heading>
|
|
|
|
|
<p>
|
|
|
|
|
This element contains simple text giving the name of the header
|
|
|
|
|
file in which something is declared.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="desc">
|
|
|
|
|
<heading>desc</heading>
|
|
|
|
|
<p>
|
|
|
|
|
This element is used to contain descriptions of how software
|
|
|
|
|
functions. It may contain <ref id="text">text</ref>, but may
|
|
|
|
|
also contain <ref id="list">lists</ref>,
|
|
|
|
|
<ref id="p">paragraphs</ref>,
|
|
|
|
|
<ref id="example">examples</ref> and
|
|
|
|
|
<ref id="mbed">embedded data</ref>.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="heading">
|
|
|
|
|
<heading>heading</heading>
|
|
|
|
|
<p>
|
|
|
|
|
Each <ref id="chapter">chapter</ref>,
|
|
|
|
|
<ref id="section">section</ref>
|
|
|
|
|
<ref id="subsect">sub-section</ref>,
|
|
|
|
|
or <ref id="subsubsect">sub-sub-section</ref>
|
|
|
|
|
has a heading as the first thing in it.
|
|
|
|
|
These headings introduce the sections and are listed in the
|
|
|
|
|
contents page.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="p">
|
|
|
|
|
<heading>p</heading>
|
|
|
|
|
<p>
|
|
|
|
|
The paragraph element simply contains <ref id="text">text</ref>.
|
|
|
|
|
Most descriptive writing is inside paragraphs.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="section">
|
|
|
|
|
<heading>section</heading>
|
|
|
|
|
<p>
|
|
|
|
|
The <em>section</em> element is just like a
|
|
|
|
|
<ref id="chapter">chapter</ref>, except that it contains
|
|
|
|
|
<ref id="subsect">sub-sections</ref> where a chapter would
|
|
|
|
|
contain sections.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="standards">
|
|
|
|
|
<heading>standards</heading>
|
|
|
|
|
<p>
|
|
|
|
|
The <em>standards</em> element contains any number of
|
|
|
|
|
standard elements whioch specify what standards a particular
|
|
|
|
|
piece of code does or does not conform to.
|
|
|
|
|
<br/>
|
|
|
|
|
The defined values are -
|
|
|
|
|
</p>
|
|
|
|
|
<list>
|
|
|
|
|
<item><GNUstep/></item>
|
|
|
|
|
<item><OpenStep/></item>
|
|
|
|
|
<item><NotOpenStep/></item>
|
|
|
|
|
<item><MacOS-X/></item>
|
|
|
|
|
<item><NotMacOS-X/></item>
|
|
|
|
|
</list>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="subsect">
|
|
|
|
|
<heading>subsect</heading>
|
|
|
|
|
<p>
|
|
|
|
|
The <em>subsect</em> element is just like a
|
|
|
|
|
<ref id="section">section</ref>, except that it contains
|
|
|
|
|
<ref id="subsubsect">sub-sub-sections</ref> where a section would
|
|
|
|
|
contain sub-sections.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="subsubsect">
|
|
|
|
|
<heading>subsubsect</heading>
|
|
|
|
|
<p>
|
|
|
|
|
The <em>subsubsect</em> element is just like a
|
|
|
|
|
<ref id="subsect">sub-section</ref>, except that it contains
|
|
|
|
|
only a <ref id="heading">heading</ref> and zero or more
|
|
|
|
|
<ref id="block">blocks</ref>.
|
|
|
|
|
</p>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="text">
|
|
|
|
|
<heading>text</heading>
|
|
|
|
|
<p>
|
|
|
|
|
This is not really an element, we simply talk about text where
|
|
|
|
|
we mean raw text and very simple markup such as -
|
|
|
|
|
</p>
|
|
|
|
|
<deflist>
|
|
|
|
|
<term><ref id="br">br</ref></term>
|
|
|
|
|
<desc>a forced line-break</desc>
|
|
|
|
|
<term><ref id="footnote">footnote</ref></term>
|
|
|
|
|
<desc>a reference to a footnote that appears in full elsewhere</desc>
|
|
|
|
|
<term><ref id="label">label</ref></term>
|
|
|
|
|
<desc>
|
|
|
|
|
a piece of text marked so that it can be referred to from elsewhere.
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="entry">entry</ref></term>
|
|
|
|
|
<desc>
|
|
|
|
|
an invisible mark that can be referred to from elsewhere.
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="ref">ref</ref></term>
|
|
|
|
|
<desc>
|
|
|
|
|
text marked as a reference to elsewhere in the document.
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="uref">uref</ref></term>
|
|
|
|
|
<desc>
|
|
|
|
|
text marked as a reference to a hypertext URL.
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="url">url</ref></term>
|
|
|
|
|
<desc>
|
|
|
|
|
a hypertext URL.
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="email">email</ref></term>
|
|
|
|
|
<desc>
|
|
|
|
|
an email address.
|
|
|
|
|
</desc>
|
|
|
|
|
</deflist>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
</chapter>
|
|
|
|
|
|
2000-03-05 11:24:24 +00:00
|
|
|
<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>
|
2001-01-05 20:27:49 +00:00
|
|
|
<section>
|
|
|
|
|
<heading>Parameters</heading>
|
|
|
|
|
<deflist>
|
|
|
|
|
<term><ref id="--makeRefs">--makeRefs=ReferencesFileName</ref> </term>
|
|
|
|
|
<desc>
|
|
|
|
|
With this option, gsdoc reads gsdoc files and creates
|
|
|
|
|
ReferencesFileName.gsdocrefs files which can be used as
|
|
|
|
|
<ref id="">--refs</ref> to make links between elements.
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="--projectName">--projectName=TheProjectName</ref>
|
|
|
|
|
</term>
|
|
|
|
|
<desc>
|
|
|
|
|
Set the project name to "TheProjectName". It is used to index
|
|
|
|
|
titles,...
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="--refs">--refs=ARefFile or --refs=ARefDirectory</ref>
|
|
|
|
|
</term>
|
|
|
|
|
<desc>
|
|
|
|
|
Use ARefFile.gsdocrefs (or files with extensions .gsdocrefs in
|
|
|
|
|
ARefDirectory directory) as references files. It enables you to
|
|
|
|
|
make links between documentation areas.
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="--makeIndex">--makeIndex=MyIndexFileName</ref></term>
|
|
|
|
|
<desc>
|
|
|
|
|
Create an index of the parsed files and save it as
|
|
|
|
|
MyIndexName.gsdoc. You have to set --makeIndexTemplate option.
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="--makeIndexTemplate">--makeIndexTemplate=MyIndexTemplateFileName</ref></term>
|
|
|
|
|
<desc>
|
|
|
|
|
The file used as index template for makeIndex option
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="--define-">--define-XXX=YYY</ref></term>
|
|
|
|
|
<desc>
|
|
|
|
|
Used to define a constant named XXX with value YYY in .gsdoc file,
|
|
|
|
|
all [[infoDictionary.XXX]] texts are replaced with YYY
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="-verbose">--verbose=X</ref></term>
|
|
|
|
|
<desc>
|
|
|
|
|
Level of traces from 0 to ...
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="--location">--location=file://usr/doc/gnustep/MyProject or --location=http://www.gnustep.org/gnustep/MyProject</ref></term>
|
|
|
|
|
<desc>
|
|
|
|
|
Location of the installed documentation (it helps to make links
|
|
|
|
|
between projects)
|
|
|
|
|
</desc>
|
|
|
|
|
<term><ref id="files">file1 file2</ref></term>
|
|
|
|
|
<desc>
|
|
|
|
|
The .gsdoc files to be processed.
|
|
|
|
|
</desc>
|
|
|
|
|
</deflist>
|
|
|
|
|
</section>
|
|
|
|
|
<section>
|
|
|
|
|
<heading>Example</heading>
|
|
|
|
|
<subsect>
|
|
|
|
|
<heading>AutoDoc</heading>
|
|
|
|
|
<example>
|
|
|
|
|
autodoc -allclasses -format html -template \
|
|
|
|
|
/usr/GNUstep/System/Libraries/Resources/DocTemplates/AutoDocTemplate.gsdoc \
|
|
|
|
|
-copyright "Orange Concept" \
|
|
|
|
|
-define-author-name "Manuel Guesdon" \
|
|
|
|
|
-define-author-email "mguesdon@orange-concept.com" \
|
|
|
|
|
-define-author-desc "Developer" \
|
|
|
|
|
-define-author-url "http://www.orange-concept.com" -define-dtd-ref \
|
|
|
|
|
"/usr/GNUstep/System/Libraries/Resources/DTDs/gsdoc-0_6_6.dtd" \
|
|
|
|
|
-define-stylesheeturl "http://www.orange-concept.com/styles/default.css" \
|
|
|
|
|
-define-basetitle "MyDoc:" \
|
|
|
|
|
-define-dtd-url "http://www.gnustep.org/gsdoc-0_6_6.xml" \
|
|
|
|
|
-define-next "[[next]]" -define-prev "[[prev]]" -define-up "[[up]]" \
|
|
|
|
|
MySource.h
|
|
|
|
|
</example>
|
|
|
|
|
<p>
|
|
|
|
|
The above example takes MySource.h and MySource.m and generates
|
|
|
|
|
one or more gsdoc files (they have the extension .html,
|
|
|
|
|
so please rename them with .gsdoc extension after running
|
|
|
|
|
AutoDoc
|
|
|
|
|
</p>
|
|
|
|
|
</subsect>
|
|
|
|
|
<subsect>
|
|
|
|
|
<heading>GSDoc</heading>
|
|
|
|
|
<example>
|
|
|
|
|
gsdoc MyFile1.gsdoc MyFile2.gsdoc Explanations.gsdoc --makeRefs --makeIndex \
|
|
|
|
|
--makeIndexTemplate=/usr/GNUstep/System/Libraries/Resources/DocTemplates/indextemplate.gsdoc \
|
|
|
|
|
--projectName="MyProject" --refs=/usr/doc/gnustep --define-version=2.1 \
|
|
|
|
|
--verbose=1 --location="/usr/doc/gnustep/MyProject"
|
|
|
|
|
</example>
|
|
|
|
|
<p>
|
|
|
|
|
The above example will parse MyFile1.gsdoc MyFile2.gsdoc and
|
|
|
|
|
generate MyFile1.html and MyFile2.html. It generates
|
|
|
|
|
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.
|
|
|
|
|
</p>
|
|
|
|
|
</subsect>
|
|
|
|
|
</section>
|
2000-03-05 11:24:24 +00:00
|
|
|
</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>
|
