mirror of
https://github.com/gnustep/libs-base.git
synced 2025-04-22 08:26:27 +00:00
remove unused file
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@7522 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Richard Frith-MacDonald
parent
bda0c34eb8
commit
ad4737dd34
1 changed files with 0 additions and 288 deletions
288
GSDoc/gsdoc.html
288
GSDoc/gsdoc.html
|
|
@ -1,288 +0,0 @@
|
|||
<html><head>
|
||||
<title>GNUstep Documentation XML markup language (GSDoc)</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>GNUstep Documentation XML markup language (GSDoc)</h1>
|
||||
<h3>Authors</h3>
|
||||
<dl>
|
||||
<dt><a href="http://www.gnustep.org/developers/whoiswho.html">Richard Frith-Macdonald</a>
|
||||
<dd>
|
||||
|
||||
A person who has devotes far too much time to GNUstep development.
|
||||
</dl>
|
||||
<p>Version: 0.1</p>
|
||||
<p>Date: 4 march, 2000</p>
|
||||
<blockquote>
|
||||
This documents the GNUstep Documentation markup language and tools
|
||||
</blockquote>
|
||||
<p>Copyright: Free Software Foundation, Inc.</p>
|
||||
<h1>Contents</h1>
|
||||
<ul>
|
||||
<li><a href="#cont-0">Introduction</a>
|
||||
<ul>
|
||||
<li><a href="#cont-1">Why another documentation language?</a>
|
||||
</ul>
|
||||
<li><a href="#cont-2">The gsdoc DTD and what it means</a>
|
||||
<ul>
|
||||
<li><a href="#gsdoc">Overall document structure</a>
|
||||
<li><a href="#head">The document head</a>
|
||||
<li><a href="#body">The document body</a>
|
||||
</ul>
|
||||
<li><a href="#cont-3">The gsdoc conversion tool</a>
|
||||
</ul>
|
||||
<h2><a name="cont-0">Introduction</a></h2>
|
||||
<p>
|
||||
|
||||
The GSDoc markup language is an XML language designed specifically
|
||||
for writing documentation for the
|
||||
<a href="http://www.gnustep.org">GNUstep project</a>.
|
||||
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>
|
||||
<h3><a name="cont-1">Why another documentation language?</a></h3>
|
||||
<p>
|
||||
|
||||
There are several reasons for producing the new markup
|
||||
language -
|
||||
</p>
|
||||
<ul>
|
||||
<li>
|
||||
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.
|
||||
|
||||
<li>
|
||||
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.
|
||||
|
||||
<li>
|
||||
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.
|
||||
|
||||
<li>
|
||||
LinuxDoc, while being a nice basic system, seems to be
|
||||
in the process of being replaced by DocBook.
|
||||
|
||||
</ul>
|
||||
<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>
|
||||
<ul>
|
||||
<li>
|
||||
Provide optimal support for GNUstep documentation.
|
||||
|
||||
<li>
|
||||
Minimize the amount of work needed for development of
|
||||
software tools.
|
||||
|
||||
<li>
|
||||
Provide future-proofing in that documentation written in one
|
||||
XML language should be quite easy to convert to another if
|
||||
necessary.
|
||||
|
||||
</ul>
|
||||
<h2><a name="cont-2">The gsdoc DTD and what it means</a></h2>
|
||||
<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
|
||||
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.
|
||||
</p>
|
||||
<h3><a name="gsdoc">Overall document structure</a></h3>
|
||||
<p>
|
||||
|
||||
A GSDoc document consists of a <a href="#head">head</a> and a
|
||||
<a href="#body">body</a> wrapped inside the overall document
|
||||
framework that looks like this -
|
||||
</p>
|
||||
<a name="label-0">example</a>
|
||||
<pre>
|
||||
|
||||
<?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>
|
||||
|
||||
</pre>
|
||||
<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>
|
||||
<dl>
|
||||
<dt>base
|
||||
<dd>
|
||||
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 <em>foo</em> then an html
|
||||
output for this file would be <em>foo.html</em>.
|
||||
|
||||
<dt>prev
|
||||
<dd>
|
||||
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.
|
||||
|
||||
<dt>next
|
||||
<dd>
|
||||
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.
|
||||
|
||||
<dt>up
|
||||
<dd>
|
||||
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.
|
||||
|
||||
</dl>
|
||||
<h3><a name="head">The document head</a></h3>
|
||||
<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>
|
||||
<a name="label-1">example</a>
|
||||
<pre>
|
||||
|
||||
<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>
|
||||
|
||||
</pre>
|
||||
<p>
|
||||
|
||||
The above example shows all the elements possible in a document head -
|
||||
</p>
|
||||
<dl>
|
||||
<dt><a name="title">title</a>
|
||||
<dd>
|
||||
The title of the document.
|
||||
|
||||
<dt><a name="author">author</a>
|
||||
<dd>
|
||||
<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>
|
||||
|
||||
|
||||
<dt><a name="version">version</a>
|
||||
<dd>
|
||||
The version number of the document.
|
||||
|
||||
<dt><a name="date">date</a>
|
||||
<dd>
|
||||
The date at which the document was last modified.
|
||||
|
||||
<dt><a name="abstract">abstract</a>
|
||||
<dd>
|
||||
A <em>short</em> description of the document contents.
|
||||
|
||||
<dt><a name="copy">copy</a>
|
||||
<dd>
|
||||
The copyright owner of the document.
|
||||
|
||||
</dl>
|
||||
<h3><a name="body">The document body</a></h3>
|
||||
<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
|
||||
parts of the document would be expected to have their own separate
|
||||
page numbering schemes.
|
||||
</p>
|
||||
<h2><a name="cont-3">The gsdoc conversion tool</a></h2>
|
||||
<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>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
Loading…
Reference in a new issue