gnustep/libs-base
0
0
Fork 0
mirror of https://github.com/gnustep/libs-base.git synced 2025-04-23 00:41:02 +00:00
Code Issues Projects Releases Packages Wiki Activity

Update

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@6271 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Richard Frith-MacDonald 2000-03-11 22:05:35 +00:00
parent 156f8f2cb6
commit 154341cecc
3 changed files with 233 additions and 268 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
ChangeLog
View file

@ -1,3 +1,7 @@
Sat Mar 11 21:04:00 2000 Richard Frith-Macdonald <richard@brainstorm.co.uk>
* GSDoc/gsdoc.m: Updated for recent version of xml library.
Fri Mar 10 10:45:00 2000 Richard Frith-Macdonald <richard@brainstorm.co.uk>
* GSDoc/gsdoc-0_6_5.dtd: Altered to add standard conformance to

4
GSDoc/README
View file

@ -1,5 +1,5 @@
28-Feb-2000
11-Mar-2000
GSDoc should probably be part of the 'Tools' directory of gstep-base,
but it depends on a version of the nome XML parsing library this is
@ -15,7 +15,7 @@ Password - 'anonymous'
cvs -d :pserver:anonymous@dev.w3.org:/sources/public checkout XML
Older versions of the library may work - but I doubt it.
Newer versions may also fail - try using the -D 28-Feb-2000 flag with CVS
Newer versions may also fail - try using the -D 11-Mar-2000 flag with CVS
to get the version I used.
Once you have built and installed the xml parser library, you can build

493
GSDoc/gsdoc.html
View file

@ -1,299 +1,260 @@
<html><head>
<title>GNUstep Documentation XML markup language (GSDoc)</title>
<title>NSObject</title>
</head>
<body>
<h1>GNUstep Documentation XML markup language (GSDoc)</h1>
<h1>NSObject</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>
</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>
<p>Date: 28 February, 2000</p>
<h2><a name="cont-0">NSObject</a></h2>
<h2><a name="NSObject">NSObject</a></h2>
<p><b>Declared in:</b> Foundation/NSObject.h</p>
<p><b>Conforms to:</b> NSObject
</p>
<hr>
<ul>
<li><a href="#cont-0">Introduction</a>
<ul>
<li><a href="#cont-1">Why another documentation language?</a>
<li><a href="gsdoc.html#method-0">+alloc</a>
<li><a href="gsdoc.html#method-1">+allocWithZone:</a>
<li><a href="gsdoc.html#method-2">+cancelPreviousPerformRequestsWithTarget:selector:</a>
<li><a href="gsdoc.html#method-3">+class</a>
<li><a href="gsdoc.html#method-4">+conformsToProtocol:</a>
<li><a href="gsdoc.html#method-5">+copyWithZone:</a>
<li><a href="gsdoc.html#method-6">+description</a>
<li><a href="gsdoc.html#method-7">+initialize</a>
<li><a href="gsdoc.html#method-8">+instanceMethodForSelector:</a>
<li><a href="gsdoc.html#method-9">+instanceMethodSignatureForSelector:</a>
<li><a href="gsdoc.html#method-10">+instancesRespondToSelector:</a>
<li><a href="gsdoc.html#method-11">+load</a>
<li><a href="gsdoc.html#method-12">+mutableCopyWithZone:</a>
<li><a href="gsdoc.html#method-13">+new</a>
<li><a href="gsdoc.html#method-14">+poseAsClass:</a>
<li><a href="gsdoc.html#method-15">+setVersion:</a>
<li><a href="gsdoc.html#method-16">+superclass</a>
<li><a href="gsdoc.html#method-17">+version</a>
<li><a href="gsdoc.html#method-18">-awakeAfterUsingCoder:</a>
<li><a href="gsdoc.html#method-19">-classForArchiver</a>
<li><a href="gsdoc.html#method-20">-classForCoder</a>
<li><a href="gsdoc.html#method-21">-classForPortCoder</a>
<li><a href="gsdoc.html#method-22">-connection:handleRequest:</a>
<li><a href="gsdoc.html#method-23">-copy</a>
<li><a href="gsdoc.html#method-24">-dealloc</a>
<li><a href="gsdoc.html#method-25">-description</a>
<li><a href="gsdoc.html#method-26">-doesNotRecognizeSelector:</a>
<li><a href="gsdoc.html#method-27">-forwardInvocation:</a>
<li><a href="gsdoc.html#method-28">-hash</a>
<li><a href="gsdoc.html#method-29">-init</a>
<li><a href="gsdoc.html#method-30">-isEqual:</a>
<li><a href="gsdoc.html#method-31">-methodForSelector:</a>
<li><a href="gsdoc.html#method-32">-methodSignatureForSelector:</a>
<li><a href="gsdoc.html#method-33">-mutableCopy</a>
<li><a href="gsdoc.html#method-34">-performSelector:withObject:</a>
<li><a href="gsdoc.html#method-35">-performSelector:withObject:afterDelay:inModes:</a>
<li><a href="gsdoc.html#method-36">-replacementObjectForArchiver:</a>
<li><a href="gsdoc.html#method-37">-replacementObjectForCoder:</a>
<li><a href="gsdoc.html#method-38">-replacementObjectForPortCoder:</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>
<hr>
<h2><a name="method-0">alloc</a></h2>
+ (id) <b>alloc</b><br>
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>
<hr>
<h2><a name="method-1">allocWithZone:</a></h2>
+ (id) <b>allocWithZone:</b> (NSZone*)zone<br>
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>
<hr>
<h2><a name="method-2">cancelPreviousPerformRequestsWithTarget:selector:</a></h2>
+ (void) <b>cancelPreviousPerformRequestsWithTarget:</b> (id)aTarget <b>selector:</b> (SEL)aSelector<br>
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>
<hr>
<h2><a name="method-3">class</a></h2>
+ (Class) <b>class</b><br>
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>
<hr>
<h2><a name="method-4">conformsToProtocol:</a></h2>
+ (BOOL) <b>conformsToProtocol:</b> (Protocol*)aProtocol<br>
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>
<hr>
<h2><a name="method-5">copyWithZone:</a></h2>
+ (id) <b>copyWithZone:</b> (NSZone*)zone<br>
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>
<hr>
<h2><a name="method-6">description</a></h2>
+ (NSString*) <b>description</b><br>
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>
<hr>
<h2><a name="method-7">initialize</a></h2>
+ (void) <b>initialize</b><br>
&#60;?xml version="1.0"?>
&#60;!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.5//EN" "http://www.gnustep.org/gsdoc-0_6_5.xml">
&#60;gsdoc base="MyDoc" prev="First.html" next="Last.html" up="Overview.html">
&#60;head>
... your document head here
&#60;/head>
&#60;body>
... your document body here
&#60;/body>
&#60;/gsdoc>
</pre>
<p>
<hr>
<h2><a name="method-8">instanceMethodForSelector:</a></h2>
+ (IMP) <b>instanceMethodForSelector:</b> (SEL)aSelector<br>
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>.
<em>foo</em> then an html
output for this file would be <em>foo.html</em>.
then an html
output for this file would be <em>foo.html</em>.
<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>
<hr>
<h2><a name="method-9">instanceMethodSignatureForSelector:</a></h2>
+ (NSMethodSignature*) <b>instanceMethodSignatureForSelector:</b> (SEL)aSelector<br>
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>
<hr>
<h2><a name="method-10">instancesRespondToSelector:</a></h2>
+ (BOOL) <b>instancesRespondToSelector:</b> (SEL)aSelector<br>
&#60;head>
&#60;title>GNUstep Documentation XML markup language (GSDoc)&#60;/title>
&#60;author name="Richard Frith-Macdonald">
&#60;email address="rfm@gnu.org"/>
&#60;url url="http://www.gnustep.org/developers/whoiswho.html"/>
&#60;desc>
A person who has devotes far too much time to GNUstep development.
&#60;/desc>
&#60;/author>
&#60;version>0.1&#60;/version>
&#60;date>4 march, 2000&#60;/date>
&#60;abstract>
This documents the GNUstep Documentation markup language and tools
&#60;/abstract>
&#60;copy>Free Software Foundation, Inc.&#60;/copy>
&#60;/head>
</pre>
<p>
<hr>
<h2><a name="method-11">load</a></h2>
+ (void) <b>load</b><br>
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>
<hr>
<h2><a name="method-12">mutableCopyWithZone:</a></h2>
+ (id) <b>mutableCopyWithZone:</b> (NSZone*)zone<br>
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>
<hr>
<h2><a name="method-13">new</a></h2>
+ (id) <b>new</b><br>
<p>
<hr>
<h2><a name="method-14">poseAsClass:</a></h2>
+ (void) <b>poseAsClass:</b> (Class)aClass<br>
Of course, a document may have more than one author, in which
case you simply write multiple author elements.
</p>
<hr>
<h2><a name="method-15">setVersion:</a></h2>
+ (void) <b>setVersion:</b> (int)aVersion<br>
<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.
<em>short</em> description of the document contents.
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>
<hr>
<h2><a name="method-16">superclass</a></h2>
+ (Class) <b>superclass</b><br>
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>
<hr>
<h2><a name="method-17">version</a></h2>
+ (int) <b>version</b><br>
The gsdoc tool is written in Objective-C and uses the GNUstep base
library and the Gnome XML parser library.
</p>
<p>
<hr>
<h2><a name="method-18">awakeAfterUsingCoder:</a></h2>
- (id) <b>awakeAfterUsingCoder:</b> (NSCoder*)aDecoder<br>
This tool is intended to convert GSDoc documents to other formats
though, at present, only HTML output is supported.
</p>
<p>
<hr>
<h2><a name="method-19">classForArchiver</a></h2>
- (Class) <b>classForArchiver</b><br>
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>
<hr>
<h2><a name="method-20">classForCoder</a></h2>
- (Class) <b>classForCoder</b><br>
<hr>
<h2><a name="method-21">classForPortCoder</a></h2>
- (Class) <b>classForPortCoder</b><br>
<hr>
<h2><a name="method-22">connection:handleRequest:</a></h2>
- (BOOL) <b>connection:</b> (NSConnection*)connection <b>handleRequest:</b> (NSDistantObjectRequest*)doreq<br>
<hr>
<h2><a name="method-23">copy</a></h2>
- (id) <b>copy</b><br>
<hr>
<h2><a name="method-24">dealloc</a></h2>
- (void) <b>dealloc</b><br>
<hr>
<h2><a name="method-25">description</a></h2>
- (NSString*) <b>description</b><br>
<hr>
<h2><a name="method-26">doesNotRecognizeSelector:</a></h2>
- (void) <b>doesNotRecognizeSelector:</b> (SEL)aSelector<br>
<hr>
<h2><a name="method-27">forwardInvocation:</a></h2>
- (void) <b>forwardInvocation:</b> (NSInvocation*)anInvocation<br>
<hr>
<h2><a name="method-28">hash</a></h2>
- (unsigned int) <b>hash</b><br>
<hr>
<h2><a name="method-29">init</a></h2>
- (id) <b>init</b><br>
<hr>
<h2><a name="method-30">isEqual:</a></h2>
- (BOOL) <b>isEqual:</b> (id)anObject<br>
<hr>
<h2><a name="method-31">methodForSelector:</a></h2>
- (IMP) <b>methodForSelector:</b> (SEL)aSelector<br>
<hr>
<h2><a name="method-32">methodSignatureForSelector:</a></h2>
- (NSMethodSignature*) <b>methodSignatureForSelector:</b> (SEL)aSelector<br>
<hr>
<h2><a name="method-33">mutableCopy</a></h2>
- (id) <b>mutableCopy</b><br>
<hr>
<h2><a name="method-34">performSelector:withObject:</a></h2>
- (void) <b>performSelector:</b> (SEL)aSelector <b>withObject:</b> (id)anArgument<br>
<hr>
<h2><a name="method-35">performSelector:withObject:afterDelay:inModes:</a></h2>
- (void) <b>performSelector:</b> (SEL)aSelector <b>withObject:</b> (id)anArgument <b>afterDelay:</b> (NSTimeInterval)delay <b>inModes:</b> (NSArray*)modes<br>
<hr>
<h2><a name="method-36">replacementObjectForArchiver:</a></h2>
- (id) <b>replacementObjectForArchiver:</b> (NSArchiver*)anArchiver<br>
<hr>
<h2><a name="method-37">replacementObjectForCoder:</a></h2>
- (id) <b>replacementObjectForCoder:</b> (NSCoder*)aCoder<br>
<hr>
<h2><a name="method-38">replacementObjectForPortCoder:</a></h2>
- (id) <b>replacementObjectForPortCoder:</b> (NSPortCoder*)aCoder<br>
<hr>
</body>
</html>