|
|
 |
|
The GNUstep Documentation Markup Language is intended to be used for writing GNUstep documentation. It is is abbreviated as GDML. Cheesy, isn't it? But the abbreviation has the advantage of being very short, compared to the previous name of gnustepdoc.
GDML is still a very new markup language, so there will be big changes every once in a while without prior notice.
A more easy to handle package for GDML than what I am offering here (this page is for people who can install everything themselves) is available at http://www.tiptree.demon.co.uk Richard Frith-Macdonald's home page, which may probably be out of date with respect to GDML since GDML is currently continuously changing.
Why define a new documentation markup language when we already have a host of others, like HMTL, Texinfo, or TeX? The biggest reason is that no text markup language freely available to us is able to markup Objective-C method names satisfactorily (unofficial support in Texinfo has existed for a long time, but there was no official support at the time of writing).
<!--
Document Type Definition for GNUstep Documentation Markup
Language (GDML).
Maintained by Yoo C. Chung <wacko@laplace.snu.ac.kr>
Copyright (C) 1997 Yoo C. Chung
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.
This library is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU Library General Public License for more
details.
You should have received a copy of the GNU Library General
Public License along with this library; if not, write to the
Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
02139, USA.
-->
<!ENTITY % GDML.Version
"-//GNUstep//DTD GDML 1.0//EN"
-- Typical usage:
<!DOCTYPE GDML PUBLIC "-//GNUstep//DTD GDML 1.0//EN">
...
-- >
<!--***** Character entities. *****-->
<!-- General purpose characters for GDML. -->
<!ENTITY copy SDATA "©" -- copyright symbol -- >
<!ENTITY tm SDATA "&tm;" -- trademark symbol -- >
<!ENTITY dots SDATA "&dots;" -- ellipsis (...) -- >
<!ENTITY nbsp SDATA " " -- non breakable space -- >
<!ENTITY amp CDATA "&" -- ampersand -- >
<!ENTITY quot CDATA '"' -- quotation mark (") -- >
<!ENTITY lt CDATA "<" -- lesser than symbol -- >
<!ENTITY gt CDATA ">" -- greater than symbol -- >
<!-- Smileys. -->
<!ENTITY smile SDATA "⌣" -- ordinary smile -- >
<!ENTITY wink SDATA "&wink;" -- wink -- >
<!ENTITY frown SDATA "⌢" -- frown -- >
<!--***** Entity declarations. *****-->
<!-- Entity for phrase elements. -->
<!ENTITY % phrase "VAR | EM | CODE | STRONG | FILE | SITE">
<!-- Entity for cross references. -->
<!ENTITY % xref "REF | UREF | URL | EMAIL">
<!-- Entity for anchors. -->
<!ENTITY % anchor "LABEL | ENTRY">
<!-- Entity for text level elements. -->
<!ENTITY % text "#PCDATA | %xref | %anchor | %phrase | FOOTNOTE">
<!-- Entity for definition elements. -->
<!ENTITY % def "CLASS|CATEGORY|PROTOCOL|FUNCTION|MACRO|TYPE|VARIABLE">
<!-- Entity for list elements. -->
<!ENTITY % list "LIST | ENUM | DEFLIST | QALIST">
<!-- Entity for block elements like paragraphs. -->
<!ENTITY % block "%def | %list | P | EXAMPLE | EMBED">
<!--**********-->
<!-- Used for describing something. -->
<!ELEMENT DESC - - (%block)*>
<!-- A footnote. -->
<!ELEMENT FOOTNOTE - - (%text)* -(FOOTNOTE)>
<!--***** Phrase elements. *****-->
<!-- The content is a metasyntactic variable name. -->
<!ELEMENT VAR - - (%text)*>
<!-- Emphasize the content. -->
<!ELEMENT EM - - (%text)*>
<!-- The content is too important that simple emphasizing isn't
enough. -->
<!ELEMENT STRONG - - (%text)*>
<!-- The content is either a name for code (e.g. class names), or a
relatively short code fragment. -->
<!ELEMENT CODE - - (%text)*>
<!-- The content is a file name. -->
<!ELEMENT FILE - - CDATA>
<!-- The content is a fully qualified domain name on the Internet. -->
<!ELEMENT SITE - - CDATA>
<!--***** List elements. *****-->
<!-- An item in a list. -->
<!ELEMENT ITEM - O (%block)*>
<!-- An enumerated list. -->
<!ELEMENT ENUM - - (ITEM+)>
<!-- A ordinary, unnumbered list. -->
<!ELEMENT LIST - - (ITEM+)>
<!-- A term to defined in a definition list. -->
<!ELEMENT TERM - - (%text)*>
<!-- A definition list. -->
<!ELEMENT DEFLIST - - (TERM, DESC)+>
<!-- A question for a question and answer list. -->
<!ELEMENT QUESTION - O (%text)*>
<!-- An answer for a question and answer list. -->
<!ELEMENT ANSWER - O (%block)*>
<!-- A question and answer list. -->
<!ELEMENT QALIST - - (QUESTION, ANSWER)+>
<!--**********-->
<!--***** Cross references. *****-->
<!-- A reference. If TYPE is implied, a reference to a label. -->
<!ELEMENT REF - O EMPTY>
<!ATTLIST REF
id CDATA #REQUIRED -- ID of the reference --
type (class|protocol|method|function|type|macro|variable) #IMPLIED
class CDATA #IMPLIED -- specific class for a method -- >
<!-- An e-mail address. -->
<!ELEMENT EMAIL - - CDATA>
<!-- A URL. -->
<!ELEMENT URL - - CDATA>
<!-- A reference to a URL. The text contained appears in the output. -->
<!ELEMENT UREF - - (%text)* -(UREF)>
<!ATTLIST UREF
url CDATA #REQUIRED
hide (hide) #IMPLIED -- hide URL in output -- >
<!--***** Anchors. *****-->
<!-- An anchor for a general reference. The text contained appears in
the ouput. -->
<!ELEMENT LABEL - - (%text)* -(LABEL)>
<!ATTLIST LABEL
id CDATA #REQUIRED>
<!-- An entry for the general index. -->
<!ELEMENT ENTRY - - (%text)* -(ENTRY)
--
The text that is contained appears in the index, and never in
the text itself.
-- >
<!--***** Argument elements. *****-->
<!-- A group of arguments in functions and the like. -->
<!ELEMENT ARGS O O (ARG*, VARARG?)>
<!-- An argument. -->
<!ELEMENT ARG - O (#PCDATA)*>
<!ATTLIST ARG
type CDATA #IMPLIED>
<!-- Denotes that the rest of the arguments is a variable list, like
in printf(). -->
<!ELEMENT VARARG - O EMPTY>
<!--***** Method elements. *****-->
<!-- A component for a method selector. -->
<!ELEMENT SEL - O (#PCDATA)*>
<!-- A complete method with the selector and arguments. -->
<!ELEMENT METHCALL O O ((SEL, ARG?), (SEL, ARG)*, VARARG?)>
<!-- A method. If there is no DESC, it is understood that the element
is used to override some information from the same method in the
superclass. -->
<!ELEMENT METHOD - O (METHCALL, DESC?)>
<!ATTLIST METHOD
type CDATA #IMPLIED
factory (factory) #IMPLIED -- if not set, instance method --
override (subclass|never) #IMPLIED
role (alloc|init|dealloc|copy|mcopy) #IMPLIED>
<!--***** Elements for definitions of classes, functions, etc. *****-->
<!-- A standard that something is compliant with. -->
<!ELEMENT STANDARD - O (%text)*>
<!-- A macro definition. -->
<!ELEMENT MACRO - - (ARGS?, DESC?, STANDARD*)>
<!ATTLIST MACRO
name CDATA #REQUIRED>
<!-- To be replaced with the name of the type whenever it occurs in a
prototype. -->
<!ELEMENT TYPENAME - O EMPTY>
<!-- Whenever the element typename occurs, replace it with the name. -->
<!ELEMENT PROTO O O (%text | TYPENAME)*>
<!-- A type definition. -->
<!ELEMENT TYPE - - (PROTO, DESC?, STANDARD*)>
<!ATTLIST TYPE
name CDATA #REQUIRED>
<!-- Variable definition. -->
<!ELEMENT VARIABLE - O (DESC?, STANDARD*)>
<!ATTLIST VARIABLE
name CDATA #REQUIRED
type CDATA #REQUIRED
value CDATA #IMPLIED -- Possibly constant default value --
role (except|defaults|notify|key) #IMPLIED>
<!-- A function definition. -->
<!ELEMENT FUNCTION - - (ARGS, DESC?, STANDARD*)>
<!ATTLIST FUNCTION
name CDATA #REQUIRED
type CDATA #REQUIRED>
<!-- Protocol definition. -->
<!ELEMENT PROTOCOL - - (DESC?, METHOD*, STANDARD*)>
<!ATTLIST PROTOCOL
name CDATA #REQUIRED>
<!-- Category definition. -->
<!ELEMENT CATEGORY - - (DESC?, METHOD*, STANDARD*)>
<!ATTLIST CATEGORY
name CDATA #REQUIRED
class CDATA #REQUIRED>
<!-- Show a protocol a class conforms to. -->
<!ELEMENT CONFORM - - (#PCDATA)*>
<!-- Class definition. -->
<!ELEMENT CLASS - - (CONFORM*, DESC?, METHOD*, STANDARD*)>
<!ATTLIST CLASS
name CDATA #REQUIRED
super CDATA #IMPLIED>
<!--***** Elements for ordinary block level elements. *****-->
<!-- A paragraph. -->
<!ELEMENT P - O (%text)*>
<!-- An example. The content shows up verbatim. -->
<!ELEMENT EXAMPLE - - RCDATA>
<!ATTLIST EXAMPLE
id CDATA #IMPLIED
caption CDATA #IMPLIED>
<!-- An embedded object. If it is of a type that the SGML processor
cannot handle, then use the content, which is ignored otherwise. -->
<!ELEMENT EMBED - - (%block)*>
<!ATTLIST EMBED
id CDATA #IMPLIED
refer (file|url) file -- method of referring to object --
src CDATA #REQUIRED -- the reference to the object --
type CDATA #IMPLIED -- Internet media type of the object--
title CDATA #IMPLIED -- optional title describing object -- >
<!--***** Elements for document structure such as chapters. *****-->
<!-- A heading for chapters, sections, ... -->
<!ELEMENT HEADING - - (%text)*>
<!-- A subsubsection. -->
<!ELEMENT SSUBSECT - O (HEADING, (%block)*)>
<!ATTLIST SSUBSECT
id CDATA #IMPLIED>
<!-- A subsection. -->
<!ELEMENT SUBSECT - O (HEADING, (%block)*, SSUBSECT*)>
<!ATTLIST SUBSECT
id CDATA #IMPLIED>
<!-- A section. -->
<!ELEMENT SECTION - O (HEADING, (%block)*, SUBSECT*)>
<!ATTLIST SECTION
id CDATA #IMPLIED>
<!-- A chapter. -->
<!ELEMENT CHAPTER - O (HEADING, (%block)*, SECTION*)>
<!ATTLIST CHAPTER
id CDATA #IMPLIED>
<!--***** Elements that make searching for things easier. *****-->
<!-- Table of contents. -->
<!ELEMENT CONTENTS - O EMPTY>
<!-- Index -->
<!ELEMENT INDEX - O EMPTY>
<!--***** Elements that describe the document itself. *****-->
<!-- Copyright of the document. -->
<!ELEMENT COPY - - (%text)*>
<!-- An abstract. -->
<!ELEMENT ABSTRACT - - (%text)*>
<!-- The version of the document. -->
<!ELEMENT VERSION - - (%text)*>
<!-- The date the document was written. -->
<!ELEMENT DATE - - (%text)*>
<!-- An author. -->
<!ELEMENT AUTHOR - O (EMAIL?, URL?, DESC?)>
<!ATTLIST AUTHOR
name CDATA #REQUIRED>
<!-- The title of the document. -->
<!ELEMENT TITLE - - (%text)*>
<!--***** The topmost structures for the document body. *****-->
<!-- Unnumbered parts appearing in the front, such as a preface. -->
<!ELEMENT FRONT - - (CONTENTS?, CHAPTER*)>
<!-- The main content for the document. -->
<!ELEMENT MAIN O O (CHAPTER+)>
<!-- Unnumbered parts appearing in the back, such as an afterword or
indices. -->
<!ELEMENT BACK - - (CHAPTER*, INDEX?)>
<!--***** The topmost structures for the document. *****-->
<!-- The head containing general information about the document. -->
<!ELEMENT HEAD O O (TITLE, AUTHOR+, VERSION?, DATE?, ABSTRACT?, COPY?)>
<!-- The main part of the document. -->
<!ELEMENT BODY O O (FRONT?, MAIN, BACK?)>
<!--**********-->
<!-- The entire document. -->
<!ELEMENT GDML O O (HEAD, BODY)>
|
<!doctype gdml public "-//GNUstep//DTD GDML 1.0//EN">
<head>
<title/GNUstep Time Zone Reference/
<author name="Yoo C. Chung">
<email/wacko@laplace.snu.ac.kr/
<url>http://plaza.snu.ac.kr/~wacko/</url>
<desc>
<p>
A person who has very little spare time, and spends it on stuff
like GNUstep, anime fanfics, and games.
</desc>
<author name="Skuld">
<email/skuld@yggdrasil.heaven.org/
<url>http://yggdrasil.heaven.org/skuld/</url>
<desc>
<p>
The goddess of the future, who will watch and guide me in my hunt
for bugs. May all bow before her divinity.
</desc>
<version/0.1/
<date/6 June, 1997/
<abstract>
This documents the interface to the time zone classes in the
GNUstep Base Library.
</abstract>
<copy>
This document is in the public domain.
</copy>
</head>
<body>
<front>
<contents>
<chapter>
<heading/Preface/
<p>
This documents the interface to the time zone classes. These
classes are needed for proper adjustment of the local time in
each geographical region.
<p>
This is also an example, as well as a test case, of the new
GNUstep Documentation Markup Language (GDML).
</front>
<chapter>
<heading/The Time Zone Management Classes/
<p>
The classes <ref type=class id="NSTimeZone"> and <ref type=class
id="NSTimeZoneDetail"> are used to manage time zones. They are
declared in <file>Foundation/NSDate.h</file>.
<p>
<code/NSTimeZone/ is used to specify the time zone region, while
<code/NSTimeZoneDetail/ is used to actually obtain the difference
in seconds from UTC<footnote/Universal Coordinated Time./ that a
time zone has for a certain date.
<class name="NSTimeZone" super="NSObject">
<desc>
<p>
The world is divided into separate time zones because the sun
rises at different times. We really should all move
underground and match our clocks. &wink; However, since this is
currently not the case, our computers need a way to find the
offset from a single agreed upon time and use that in local
time calculations.
<p>
To make things even worse, there is this evil thing called
daylight saving time, which is usually used for the purpose of
utilizing as much of the sun as possible while it is still up.
(Really, everyone should stay in their rooms and play with
their computers, but for some reason they don't &dots;)
<p>
Therefore we need an object that knows about a time zone so
that the appropriate object that knows all about offsets from
UTC and whether it's daylight saving time for a certain date
can be obtained. <ref type=class id="NSTimeZone"> is a class
that can create such objects.
</desc>
<method factory type="NSTimeZoneDetail*">
<sel>defaultTimeZone
<desc>
<p>
Returns the time zone detail (see <ref type=class
id="NSTimeZoneDetail">) for the current time.
</desc>
<method factory type="NSTimeZone*">
<sel>localTimeZone
<desc>
<p>
Returns the time zone for the local region. The local region
is either specified with the <code/TZ/ environment variable,
or is specified at compile time, with the former taking
precedence.
</desc>
<method factory type="NSTimeZone*">
<sel>timeZoneForSecondsFromGMT: <arg type="int">seconds
<desc>
<p>
Returns a time zone which is always <var/seconds/ seconds off
from UTC. (In OpenStep the offset is from
GMT<footnote/Greenwich Mean Time./, but using UTC makes more
sense.)
</desc>
<method factory type="NSTimeZoneDetail*">
<sel>timeZoneWithAbbreviation:
<arg type="NSString*">abbreviation
<desc>
<p>
Returns a time zone detail for which the time zone
abbreviation is <var/abbreviation/. Note that there can be
many time zone details for a single abbreviation.
</desc>
<method factory type="NSTimeZone*">
<sel>timeZoneWithName: <arg type="NSString*">aTimeZoneName
<desc>
<p>
Returns a time zone for the geographical region specified by
<var/aTimeZoneName/.
</desc>
<method type="NSTimeZoneDetail*">
<sel>timeZoneDetailForDate: <arg type="NSDate*">date
<desc>
<p>
Returns the appropriate time zone detail for the time zone and
the given date <var/date/.
</desc>
<method factory type="void">
<sel>setDefaultTimeZone: <arg type="NSTimeZone*">aTimeZone
<desc>
<p>
Set the default time zone used for time calculation to the
time zone specified by the string <var/aTimeZone/.
</desc>
<method factory type="NSDictionary*">
<sel>abbreviationDictionary
<desc>
<p>
Returns a dictionary that maps a time zone abbreviation to a
single arbitrary time zone name.
</desc>
<method factory type="NSDictionary*">
<sel>abbreviationMap
<desc>
<p>
Returns a dictionary that maps a time zone abbreviation to an
array that holds all the time zone names that use the
abbreviation.
<p>
This is a GNU extension, and is not defined by OpenStep.
</desc>
<method type="NSString*" override=subclass>
<sel>timeZoneName
<desc>
<p>Returns the name for the time zone.
</desc>
<method factory type="NSArray*">
<sel>timeZoneArray
<desc>
<p>
Returns an array containing 24 arrays that in turn contain the
time zone names that are grouped according to the offset from
UTC. For example, a time zone that has an offset of 5 hours
(or -19 hours) goes into the fifth array in the array.
<p>
Note that OpenStep groups them by latitudinal region, and the
exact details of the grouping is not specified.
</desc>
<method type="NSArray*" override=subclass>
<sel>timeZoneDetailArray
<desc>
<p>
This returns an array containing all the possible time zone
details for the time zone.
</desc>
<standard>OpenStep
<standard>GNU
</class>
<class name="NSTimeZoneDetail" super="NSTimeZone">
<desc>
<p>
A time zone doesn't know the actual offset from UTC that a
certain region has, since the offset is not always the same
because of changes in time rules and such. Since the details
are different for different dates, <ref type=class
id="NSTimeZone"> must return an object that details the time
zone for a specific date. <code/NSTimeZoneDetail/ is the class
for such objects.
<p>
It is from <code/NSTimeZoneDetail/ that we obtain the actual
offsets from UTC. In addition, we can obtain the time zone
abbreviation (which is also dependent on the date) and whether
the time zone uses daylight saving time for the date on which
the time zone detail was created.
</desc>
<method type="BOOL" override=subclass>
<sel>isDaylightSavingTimeZone
<desc>
<p>
If the time zone detail describes a time zone for which the
date the detail was created for is daylight saving time,
return <code/YES/, else return <code/NO/.
</desc>
<method type="NSString*" override=subclass>
<sel>timeZoneAbbreviation
<desc>
<p>Returns the abbreviation for the time zone detail.
</desc>
<method type="int" override=subclass>
<sel>timeZoneSecondsFromGMT
<desc>
<p>
Returns the offset from UTC for local time in seconds.
<p>
Note that OpenStep specifies an offset from GMT to be
returned, but using UTC makes more sense.
</desc>
<standard>OpenStep
<standard>GNU
</class>
<back>
<chapter>
<heading/Afterword/
<p>
Hopefully, this document shows that GDML is indeed useful for
writing documentation for GNUstep.
<p>
Even if it is not, it should still be useful since it documents
the interface to the time zone classes, and should easily be
converted to other text markup formats.
<p>
Please send any questions about the DTD or this document to
<email/wacko@laplace.snu.ac.kr/.
<p>
And by the way, I've tried out the time zone implementation in
the GNUstep Base Library and it seems to work for the following
time zone regions:
<list>
<item><p>Asia/Seoul
<item><p>US/Eastern
<item><p>America/Los_Angeles
</list>
<p>
And here's a small incomplete class definition with somewhat
longer method names.
<class name="NSObject">
<conform/NSObject/
<conform/NSCoding/
<conform/NSCopying/
<desc>
<p>A superclass of all classes.
</desc>
<method>
<sel>perform: <arg type="SEL">aSelector
<sel>withObject: <arg>object1
<sel>withObject: <arg>object2
<desc>
<p>
This should really go into a protocol definition, but I wanted
to show a class definition with protocols.
</desc>
<method type="NSString*">
<sel>stringWithFormat: <arg type="NSString*">format <vararg>
<desc>
<p>
This is not in <code/NSObject/, but I wanted to show the use
of a variable argument list.
</desc>
</class>
<p>
And here's an example:
<example>
int
function (void *ptr)
{
return realloc(ptr, 100);
}
</example>
<p>
And here is a macro definition:
<macro name="MAX">
<args>
<arg>a <arg>b
<desc>
<p>Return the larger between <var/a/ and <var/b/.
</desc>
<standard>SomeOS
</macro>
<macro name="NS_DURING">
<desc>
<p>Start an exception handling domain.
</desc>
</macro>
<p>
And here is a type definition:
<type name="NSTimeInterval">
typedef double <typename>;
<desc>
<p>Used to save intervals between certain times in seconds.
</desc>
</type>
<p>
And here is a function definition:
<function name="NSZoneMalloc" type="void*">
<arg type="NSZone*">zone
<arg type="size_t">size
<desc>
<p>
Allocate <var/size/ bytes from the dynamic memory allocation
zone <var/zone/.
</desc>
<standard>OpenStep
<standard>GNU
</function>
<p>
This is a variable definition:
<variable name="NSMallocException" type="NSString*"
value='@"NSMallocException"'>
<desc>
<p>The exception raised when error occurs in memory allocation.
</desc>
<standard>OpenStep
<standard>GNU
</variable>
<p>
Here's an example of an embedded object:
<embed url src="http://plaza.snu.ac.kr/~wacko/gnustep/">
<p>
If the SGML processor cannot embed this object, then this should
appear.
<p>
The type of the object will usually be inferred from the HTTP
response from the web server when the object is referred to by a
URL (of course, the SGML processor must figure the type out
itself if the protocol doesn't give such information). If the
type is specified in the element, then that will override the
server's response.
<p>
If an object cannot be embedded, then there can be an alternate
embedded object:
<embed src="some-diagram.ps" type="application/postscript">
<p>
If even this object cannot be embedded, then this will also
appear.
<p>
When embedding a file, the type does not really need to be
specified, since the SGML processor will figure out the type in
some implementation defined manner. But to be really sure it
deals with it the way the author wants to, the type should be
specified.
</embed>
</embed>
<qalist>
<question>
Can FAQs be written with GDML?
<answer>
<p>Yes, using the <code/QALIST/ element.
</qalist>
<index>
</back>
</body>
<!--
Local Variables:
sgml-indent-step: 1
End:
-->
|
|
e-mail