← Back to branch summary

~ubuntu-branches/ubuntu/karmic/gnustep-base/karmic

« back to all changes in this revision

Viewing changes to Tools/gsdoc.gsdoc

  • Committer: Bazaar Package Importer
  • Author(s): Eric Heintzmann
  • Date: 2005-04-17 00:14:38 UTC
  • mfrom: (1.2.1 upstream) (2.1.2 hoary)
  • Revision ID: james.westby@ubuntu.com-20050417001438-enf0y07c9tku85z1
Tags: 1.10.3-1
New upstream release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Tools/gsdoc.gsdoc
1
1
<?xml version="1.0"?>
2
 
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
 
2
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.1//EN" "http://www.gnustep.org/gsdoc-1_0_1.xml">
3
3
<gsdoc base="gsdoc">
4
4
  <head>
5
5
    <title>GNUstep Documentation XML markup language (GSDoc)</title>
7
7
      <email address="rfm@gnu.org"/>
8
8
      <url url="http://www.gnustep.org/developers/whoiswho.html"/>
9
9
      <desc>
10
 
        A person who has devotes far too much time to GNUstep development.
 
10
        A person who devotes far too much time to GNUstep development.
11
11
      </desc>
12
12
    </author>
13
 
    <version>0.2</version>
14
 
    <date>21 June, 2000</date>
 
13
    <version>1.0.1</version>
 
14
    <date>8 March, 2004</date>
15
15
    <abstract>
16
 
      This documents the GNUstep Documentation markup language and tools
 
16
      This documents the GNUstep Documentation markup language.
17
17
    </abstract>
18
18
    <copy>Free Software Foundation, Inc.</copy>
19
19
  </head>
23
23
      <contents/>
24
24
 
25
25
      <chapter>
26
 
        <heading>Introduction</heading>
27
 
        <p>
28
 
          The GSDoc markup language is an XML language designed specifically
29
 
          for writing documentation for the
30
 
          <uref url="http://www.gnustep.org">GNUstep project</uref>.
31
 
          In practice, that means that it is designed for writing about
32
 
          software, and in particular, for writing about Objective-C classes.
33
 
        </p>
34
 
        <p>
35
 
          This is also an example, as well as a test case, of the new
36
 
          GNUstep documentation markup language (GSDoc).
37
 
        </p>
38
 
        <section>
39
 
          <heading>Why another documentation language?</heading>
40
 
          <p>
41
 
            There are several reasons for producing the new markup
42
 
            language -
43
 
          </p>
44
 
        <list>
45
 
            <item>
46
 
              There were no existing markup languages that dealt well with
47
 
              documenting software written in the Objective-C language,
48
 
              except the GDML language - which has no easy to use support
49
 
              software.
50
 
            </item>
51
 
            <item>
52
 
              While the DocBook system works nicely for general software
53
 
              documentation, it requires a relatively large amount of
54
 
              support software and comes with a lot of baggage that's
55
 
              not directly useful for GNUstep.
56
 
            </item>
57
 
            <item>
58
 
              The GNU info system comes with easy to use, lightweight
59
 
              conversion tools, but is particularly ill suited to
60
 
              Objective-C documentation because the colon character
61
 
              using in Objective-C method names is used in info markup.
62
 
            </item>
63
 
            <item>
64
 
              LinuxDoc, while being a nice basic system, seems to be
65
 
              in the process of being replaced by DocBook.
66
 
            </item>
67
 
          </list>
68
 
          <p>
69
 
            So, with only one markup language available that supported
70
 
            Objective-C, and with XML software becoming available, the
71
 
            decision was to take GDML and update it to be an XML
72
 
            language, in the hope that this would - 
73
 
          </p>
74
 
          <list>
75
 
            <item>
76
 
              Provide optimal support for GNUstep documentation.
77
 
            </item>
78
 
            <item>
79
 
              Minimize the amount of work needed for development of
80
 
              software tools.
81
 
            </item>
82
 
            <item>
83
 
              Provide future-proofing in that documentation written in one
84
 
              XML language should be quite easy to convert to another if
85
 
              necessary.
86
 
            </item>
87
 
          </list>
88
 
        </section>
 
26
        <heading>Introduction</heading>
 
27
        <p>
 
28
          The GNUstep documentation markup language (GSDoc) is an XML language
 
29
          designed specifically for writing documentation for the
 
30
          <uref url="http://www.gnustep.org">GNUstep project</uref>.
 
31
          In practice, that means that it is designed for writing about
 
32
          software, and in particular, for writing about Objective-C classes.
 
33
        </p>
 
34
        <p>
 
35
          This document itself is an example, as well as a test case, of GSDoc
 
36
          itself.
 
37
        </p>
 
38
        <section>
 
39
          <heading>Why another documentation language?</heading>
 
40
          <p>
 
41
            There are several reasons for producing the new markup
 
42
            language -
 
43
          </p>
 
44
        <list>
 
45
            <item>
 
46
              There were no existing markup languages that dealt well with
 
47
              documenting software written in the Objective-C language,
 
48
              except the GDML language - which has no easy to use support
 
49
              software.
 
50
            </item>
 
51
            <item>
 
52
              While the DocBook system works nicely for general software
 
53
              documentation, it requires a relatively large amount of
 
54
              support software and comes with a lot of baggage that's
 
55
              not directly useful for GNUstep.
 
56
            </item>
 
57
            <item>
 
58
              The GNU info system comes with easy to use, lightweight
 
59
              conversion tools, but is particularly ill suited to
 
60
              Objective-C documentation because the colon character
 
61
              using in Objective-C method names is used in info markup.
 
62
            </item>
 
63
            <item>
 
64
              LinuxDoc, while being a nice basic system, seems to be
 
65
              in the process of being replaced by DocBook.
 
66
            </item>
 
67
          </list>
 
68
          <p>
 
69
            So, with only one markup language available that supported
 
70
            Objective-C, and with XML software becoming available, the
 
71
            decision was to take GDML and update it to be an XML
 
72
            language, in the hope that this would - 
 
73
          </p>
 
74
          <list>
 
75
            <item>
 
76
              Provide optimal support for GNUstep documentation.
 
77
            </item>
 
78
            <item>
 
79
              Minimize the amount of work needed for development of
 
80
              software tools.
 
81
            </item>
 
82
            <item>
 
83
              Provide future-proofing in that documentation written in one
 
84
              XML language should be quite easy to convert to another if
 
85
              necessary.
 
86
            </item>
 
87
          </list>
 
88
        </section>
89
89
      </chapter>
90
90
    </front>
91
91
 
92
92
    <chapter>
93
93
      <heading>The gsdoc DTD and what it means</heading>
94
94
      <p>
95
 
        The GSDoc markup language is defined by an SGML DTD, that specifies
96
 
        the tags that may be used in marking up a GSDoc document, and how
97
 
        and where those tags may be placed.  Please see the DTD for a
98
 
        precise specification.
 
95
        The GSDoc markup language is defined by an SGML DTD, that specifies
 
96
        the tags that may be used in marking up a GSDoc document, and how
 
97
        and where those tags may be placed.  The reader is encouraged to
 
98
        consult the DTD directly on any points that the present document leaves
 
99
        unclear.  The DTD is stored under
 
100
        <code>$GNUSTEP_ROOT/System/Library/DTDs</code> in a standard GNUstep
 
101
        installation.
99
102
      </p>
100
103
      <p>
101
 
        The gsdoc DTD defines an XML language - that is, a markup language
102
 
        that conforms to a specific subset of SGML features defined as XML.
103
 
        The advantage of XML is that it provides most of the useful features
104
 
        of SGML while being much more light-weight (easy to use) because
105
 
        you can forget about the rest of SGML.
106
 
        As XML looks set to become increasingly popular, we can hope that
107
 
        documentation written with an XML language will be easily imported
108
 
        into XML software tools as they become available, so we will not
109
 
        (in the GNUstep project) need to devote a lot of time and effort
110
 
        to maintaining documentation tools.
 
104
        The gsdoc DTD defines an XML language - that is, a markup language
 
105
        that conforms to a specific subset of SGML features defined as XML.
 
106
        The advantage of XML is that it provides most of the useful features
 
107
        of SGML while being much more light-weight (easy to use) because
 
108
        you can forget about the rest of SGML.
 
109
        As XML looks set to become increasingly popular, we can hope that
 
110
        documentation written with an XML language will be easily imported
 
111
        into XML software tools as they become available, so we will not
 
112
        (in the GNUstep project) need to devote a lot of time and effort
 
113
        to maintaining documentation tools.
111
114
      </p>
112
 
      <section id="gsdoc">
113
 
        <heading>Overall document structure</heading>
114
 
        <p>
115
 
          A GSDoc document consists of a <ref id="head">head</ref> and a
116
 
          <ref id="body">body</ref> wrapped inside the overall document
117
 
          framework that looks like this -
118
 
        </p>
119
 
        <example>
 
115
      <section id="gsdoc"><label id="gsdoc"/>
 
116
        <heading>Overall document structure</heading>
 
117
        <p>
 
118
          A GSDoc document consists of a <ref id="head">head</ref> and a
 
119
          <ref id="body">body</ref> wrapped inside the overall document
 
120
          framework that looks like this -
 
121
        </p>
 
122
        <example>
120
123
&lt;?xml version="1.0"?&gt;
121
124
&lt;!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml"&gt;
122
125
&lt;gsdoc base="MyDoc" prev="First" next="Last" up="Overview"&gt;
127
130
  ... your document body here
128
131
  &lt;/body&gt;
129
132
&lt;/gsdoc&gt;
130
 
        </example>
131
 
        <p>
132
 
          The above example shows a GSDoc document framework.
133
 
          The first line specifies the XML version that the document
134
 
          conforms to.
135
 
          The second line specifies the version of GSDoc that the
136
 
          document conforms to.
137
 
          The third and final lines frame the main part of the document
138
 
          and supply all the (optional) attributes of the <em>gsdoc</em>
139
 
          element -
140
 
        </p>
141
 
        <deflist>
142
 
          <term>base</term>
143
 
          <desc>
144
 
            This is optional, but recommended - it specifies the base name
145
 
            for the document.  When the document is translated to another
146
 
            format, the output file name should be based on this - eg.
147
 
            if the base name of a document is <em>foo</em> then an html
148
 
            output for this file would be <em>foo.html</em>.
149
 
          </desc>
150
 
          <term>prev</term>
151
 
          <desc>
152
 
            This optional attribute may be used as the name of a document
153
 
            that precedes this one in logical reading order.  If the
154
 
            converted output format of the document supports some sort of
155
 
            link between documents, the converter software may insert
156
 
            a link between the two documents.
157
 
          </desc>
158
 
          <term>next</term>
159
 
          <desc>
160
 
            This optional attribute may be used as the name of a document
161
 
            that follows this one in logical reading order.  If the
162
 
            converted output format of the document supports some sort of
163
 
            link between documents, the converter software may insert
164
 
            a link between the two documents.
165
 
          </desc>
166
 
          <term>up</term>
167
 
          <desc>
168
 
            This optional attribute may be used as the name of a document
169
 
            that is above this document in some sort of hierarchical
170
 
            structure (a contents list perhaps).
171
 
            If the converted output format of the document supports some sort
172
 
            of link between documents, the converter software may insert
173
 
            a link between the two documents.
174
 
          </desc>
175
 
        </deflist>
 
133
        </example>
 
134
        <p>
 
135
          The above example shows a GSDoc document framework.
 
136
          The first line specifies the XML version that the document
 
137
          conforms to.
 
138
          The second line specifies the version of GSDoc that the
 
139
          document conforms to.
 
140
          The third and final lines frame the main part of the document
 
141
          and supply all the (optional) attributes of the <em>gsdoc</em>
 
142
          element -
 
143
        </p>
 
144
        <deflist>
 
145
          <term><code>base</code></term>
 
146
          <desc>
 
147
            This is optional, but recommended - it specifies the base name
 
148
            for the document.  When the document is translated to another
 
149
            format, the output file name should be based on this - eg.
 
150
            if the base name of a document is <em>foo</em> then an html
 
151
            output for this file would be <em>foo.html</em>.
 
152
          </desc>
 
153
          <term><code>prev</code></term>
 
154
          <desc>
 
155
            This optional attribute may be used as the name of a document
 
156
            that precedes this one in logical reading order.  If the
 
157
            converted output format of the document supports some sort of
 
158
            link between documents, the converter software may insert
 
159
            a link between the two documents.
 
160
          </desc>
 
161
          <term><code>next</code></term>
 
162
          <desc>
 
163
            This optional attribute may be used as the name of a document
 
164
            that follows this one in logical reading order.  If the
 
165
            converted output format of the document supports some sort of
 
166
            link between documents, the converter software may insert
 
167
            a link between the two documents.
 
168
          </desc>
 
169
          <term><code>up</code></term>
 
170
          <desc>
 
171
            This optional attribute may be used as the name of a document
 
172
            that is above this document in some sort of hierarchical
 
173
            structure (a contents list perhaps).
 
174
            If the converted output format of the document supports some sort
 
175
            of link between documents, the converter software may insert
 
176
            a link between the two documents.
 
177
          </desc>
 
178
        </deflist>
176
179
      </section>
177
 
      <section id="head">
178
 
        <heading>The document head</heading>
179
 
        <p>
180
 
          The document head contains information about the document as
181
 
          a whole: its title, authors, version, modification date,
182
 
          copyright, and perhaps an abstract of its contents.
183
 
          The title and at least one author are the only parts of the
184
 
          document head that must be present.
185
 
        </p>
186
 
        <example>
 
180
      <section id="head"><label id="head"/>
 
181
        <heading>The document head</heading>
 
182
        <p>
 
183
          The document head contains information about the document as
 
184
          a whole: its title, authors, version, modification date,
 
185
          copyright, and perhaps an abstract of its contents.
 
186
          The title is the only part of the document head that must be present,
 
187
          although at least one author is strongly encouraged.
 
188
        </p>
 
189
        <example>
187
190
&lt;head&gt;
188
191
  &lt;title&gt;GNUstep Documentation XML markup language (GSDoc)&lt;/title&gt;
189
192
  &lt;author name="Richard Frith-Macdonald"&gt;
190
193
    &lt;email address="rfm@gnu.org"/&gt;
191
194
    &lt;url url="http://www.gnustep.org/developers/whoiswho.html"/&gt;
192
195
    &lt;desc&gt;
193
 
      A person who has devotes far too much time to GNUstep development.
 
196
      A person who devotes far too much time to GNUstep development.
194
197
    &lt;/desc&gt;
195
198
  &lt;/author&gt;
196
199
  &lt;version&gt;0.1&lt;/version&gt;
200
203
  &lt;/abstract&gt;
201
204
  &lt;copy&gt;Free Software Foundation, Inc.&lt;/copy&gt;
202
205
&lt;/head&gt;
203
 
        </example>
204
 
        <p>
205
 
          The above example shows all the elements possible in a document head -
206
 
        </p>
207
 
        <deflist>
208
 
        <term><label id="title">title</label></term>
209
 
        <desc>
210
 
          The title of the document.
211
 
        </desc>
212
 
        <term><label id="author">author</label></term>
213
 
        <desc>
214
 
          <p>
215
 
            The author of the document, also specifying an email address at
216
 
            which the author may be reached, a URL for a web page giving
217
 
            some information about the author, and an additional description
218
 
            of the author.
219
 
          </p>
220
 
          <p>
221
 
            Of course, a document may have more than one author, in which
222
 
            case you simply write multiple author elements.
223
 
          </p>
224
 
        </desc>
225
 
        <term><label id="version">version</label></term>
226
 
        <desc>
227
 
          The version number of the document.
228
 
        </desc>
229
 
        <term><label id="date">date</label></term>
230
 
        <desc>
231
 
          The date at which the document was last modified.
232
 
        </desc>
233
 
        <term><label id="abstract">abstract</label></term>
234
 
        <desc>
235
 
          A <em>short</em> description of the document contents.
236
 
        </desc>
237
 
        <term><label id="copy">copy</label></term>
238
 
        <desc>
239
 
          The copyright owner of the document.
240
 
        </desc>
241
 
        </deflist>
 
206
        </example>
 
207
        <p>
 
208
          The above example shows all the elements possible in a document head.  Only title is required (author is strongly encouraged), but if present they must occur in the order shown -
 
209
        </p>
 
210
        <deflist>
 
211
        <term><code><label id="title">&lt;title&gt;</label></code></term>
 
212
        <desc>
 
213
          The title of the document.  Required.
 
214
        </desc>
 
215
        <term><code><label id="author">&lt;author&gt;</label></code></term>
 
216
        <desc>
 
217
            The author of the document, also specifying an email address at
 
218
            which the author may be reached, a URL for a web page giving
 
219
            some information about the author, and an additional description
 
220
            of the author.  (Of course, a document may have more than one
 
221
            author, in which case you simply write multiple author elements.)
 
222
            Not required, but strongly encouraged.
 
223
        </desc>
 
224
        <term><code><label id="version">&lt;version&gt;</label></code></term>
 
225
        <desc>
 
226
          The version number of the document.
 
227
        </desc>
 
228
        <term><code><label id="date">&lt;date&gt;</label></code></term>
 
229
        <desc>
 
230
          The date at which the document was last modified.
 
231
        </desc>
 
232
        <term><code><label id="abstract">&lt;abstract&gt;</label></code></term>
 
233
        <desc>
 
234
          A <em>short</em> description of the document contents.
 
235
        </desc>
 
236
        <term><code><label id="copy">&lt;copy&gt;</label></code></term>
 
237
        <desc>
 
238
          The copyright owner of the document.
 
239
        </desc>
 
240
        </deflist>
242
241
      </section>
243
 
      <section id="body">
244
 
        <heading>The document body</heading>
245
 
        <p>
246
 
          The document body contains the main part of the document, it
247
 
          consists of an optional front part (for contents pages, overview
248
 
          etc), a sequence of any number of chapters, and an optional back
249
 
          part (for indexes, appendices etc).  Normally, each of these three
250
 
          parts of the document would be expected to have their own separate
251
 
          page numbering schemes.
252
 
        </p>
253
 
        <example>
 
242
      <section id="body"><label id="body"/>
 
243
        <heading>The document body</heading>
 
244
        <p>
 
245
          The document body contains the main part of the document, it
 
246
          consists of an optional front part (for contents pages, overview
 
247
          etc), a sequence of any number of chapters, and an optional back
 
248
          part (for indexes, appendices etc).  Normally, each of these three
 
249
          parts of the document would be expected to have their own separate
 
250
          page numbering schemes.
 
251
        </p>
 
252
        <example>
254
253
&lt;body&gt;
255
254
  &lt;front&gt;
256
255
    &lt;contents/&gt;
257
256
    &lt;chapter&gt;
258
257
      &lt;heading&gt;Preface&lt;/heading&gt;
259
258
      &lt;p&gt;
260
 
        Here is an introductory chapter for a dummy document.
 
259
        Here is an introductory chapter for a dummy document.
261
260
      &lt;/p&gt;
262
261
    &lt;/chapter&gt;
263
262
  &lt;/front&gt;
271
270
    &lt;chapter&gt;
272
271
      &lt;heading&gt;Afterword&lt;/heading&gt;
273
272
      &lt;p&gt;
274
 
        And after the main part of the doucment we can have some other stuff.
 
273
        And after the main part of the doucment we can have some other stuff.
275
274
      &lt;/p&gt;
276
275
    &lt;/chapter&gt;
277
276
    &lt;index type="class"/&gt;
278
277
  &lt;/back&gt;
279
278
&lt;/body&gt;
280
 
        </example>
281
 
        <p>
282
 
          The above example shows all the elements possible in a document body -
283
 
        </p>
284
 
        <deflist>
285
 
        <term>front</term>
286
 
        <desc>
287
 
          This is an optional part of the document that can come before the
288
 
          main text.  Typically, this could be used to contain an automatically
289
 
          generated contents page and possibly an introduction.
290
 
          When output is generated in book form, this part of the document
291
 
          would probably have a different page numbering scheme from the
292
 
          main part.
293
 
          <p>
294
 
            The <em>contents</em> element is used as a marker to specify
295
 
            that an automatically generated contents page (listing the
296
 
            chapters in the document) is to be inserted.
297
 
          </p>
298
 
        </desc>
299
 
        <term><label id="main">main</label></term>
300
 
        <desc>
301
 
          <p>
302
 
            After the <em>front</em> part of the document body comes a
303
 
            mandatory sequence of one or more chapters.  This is where
304
 
            the main part of the document resides.
305
 
            Each <ref id="chapter">chapter</ref> consists of a
306
 
            <ref id="heading">heading</ref>, any number
307
 
            of blocks of information, and any number of sections.
308
 
          </p>
309
 
        </desc>
310
 
        <term>back</term>
311
 
        <desc>
312
 
          After the chapters making up the main part of the body of the
313
 
          document is an optional <em>back</em> part which may contain
314
 
          chapters (such as appendices) possibly followed by an automatically
315
 
          generated index.
316
 
          <p>
317
 
            The <em>index</em> element is used as a marker to specify
318
 
            that an automatically generated index is to be inserted.
319
 
            The <em>type</em> attribute of the index specifies what sort
320
 
            of item is to be in the index - the default type of <em>label</em>
321
 
            causes an index of all <em>label</em> and <em>entry</em>
322
 
            elements to be generated.
323
 
          </p>
324
 
        </desc>
325
 
        </deflist>
 
279
        </example>
 
280
        <p>
 
281
          The above example shows all the elements possible at the top level in a document body -
 
282
        </p>
 
283
        <deflist>
 
284
        <term><code>&lt;front&gt;</code></term>
 
285
        <desc>
 
286
          This is an optional part of the document that can come before the
 
287
          main text.  Typically, this could be used to contain an automatically
 
288
          generated contents page and possibly an introduction.
 
289
          When output is generated in book form, this part of the document
 
290
          would probably have a different page numbering scheme from the
 
291
          main part.
 
292
          <p>
 
293
            The <code>&lt;contents&gt;</code> subelement is used as a marker
 
294
            to specify that an automatically generated contents page (listing
 
295
            the chapters in the document) is to be inserted.
 
296
          </p>
 
297
        </desc>
 
298
        <term><code>&lt;chapter&gt;</code></term>
 
299
        <desc>
 
300
            After the <em>front</em> part of the document body comes a
 
301
            mandatory sequence of one or more chapters.  This is where
 
302
            the main part of the document resides.
 
303
            Each <ref id="chapter">chapter</ref> consists of a
 
304
            <ref id="heading">heading</ref>, any number
 
305
            of blocks of information, and any number of sections.
 
306
        </desc>
 
307
        <term><br/><code>&lt;back&gt;</code></term>
 
308
        <desc>
 
309
          After the chapters making up the main part of the body of the
 
310
          document is an optional <em>back</em> part which may contain
 
311
          chapters (such as appendices) possibly followed by an automatically
 
312
          generated index.
 
313
          <p>
 
314
            The <code>&lt;index&gt;</code> element is used as a marker to
 
315
            specify that an automatically generated index is to be inserted.
 
316
            See <ref id="index">below</ref> for details.
 
317
          </p>
 
318
        </desc>
 
319
        </deflist>
326
320
      </section>
327
321
    </chapter>
328
322
 
329
323
    <chapter>
330
324
      <heading>Element reference</heading>
331
 
      <section id="block">
332
 
        <heading>block</heading>
333
 
        <p>
334
 
          Actually, there is no such thing as a <em>block</em> element, this
335
 
          is just shorthand for refering to a group of elements that can be
336
 
          used in similar ways.  The block elements are -
337
 
        </p>
338
 
        <deflist>
339
 
          <term><ref id="embed">embed</ref></term>
340
 
          <desc>embeded information from elsewhere</desc>
341
 
          <term><ref id="example">example</ref></term>
342
 
          <desc>the example</desc>
343
 
          <term><ref id="p">p</ref></term>
344
 
          <desc>the paragraph</desc>
345
 
          <term><label id="list">list</label></term>
346
 
          <desc>
347
 
            A variety of lists.
348
 
            <deflist>
349
 
              <term><ref id="list">list</ref></term>
350
 
              <desc>a simple list of items</desc>
351
 
              <term><ref id="enum">enum</ref></term>
352
 
              <desc>an enumerated list</desc>
353
 
              <term><ref id="deflist">deflist</ref></term>
354
 
              <desc>a list of terms and their definitions</desc>
355
 
              <term><ref id="qalist">qalist</ref></term>
356
 
              <desc>a list of questions and answers</desc>
357
 
            </deflist>
358
 
          </desc>
359
 
          <term>def</term>
360
 
          <desc>
361
 
            A variety of specialised elements for software documentation.
362
 
            <deflist>
363
 
              <term><ref id="class">class</ref></term>
364
 
              <desc>An Objective-C class definition</desc>
365
 
              <term><ref id="jclass">jclass</ref></term>
366
 
              <desc>A Java class definition</desc>
367
 
              <term><ref id="category">category</ref></term>
368
 
              <desc>An Objective-C category definition</desc>
369
 
              <term><ref id="protocol">protocol</ref></term>
370
 
              <desc>An Objective-C protocol or Java interface definition</desc>
371
 
              <term><ref id="function">function</ref></term>
372
 
              <desc>A function definition</desc>
373
 
              <term><ref id="macro">macro</ref></term>
374
 
              <desc>A macro definition</desc>
375
 
              <term><ref id="type">type</ref></term>
376
 
              <desc>A type definition</desc>
377
 
              <term><ref id="variable">variable</ref></term>
378
 
              <desc>A variable definition</desc>
379
 
            </deflist>
380
 
          </desc>
381
 
        </deflist>
382
 
      </section>
383
 
 
384
 
      <section id="br">
385
 
        <heading>br</heading>
386
 
        <p>
387
 
          The <em>br</em> element is an empty element that always appears
388
 
          as &lt;br/&gt; in the document.  This element simply specifies
389
 
          that a line-break should appear in the output text at this point.
390
 
        </p>
391
 
      </section>
392
 
 
393
 
      <section id="chapter">
394
 
        <heading>chapter</heading>
395
 
        <p>
396
 
          This is the basic unit of the document - the main part of
397
 
          a document <ref id="body">body</ref> will contain at least
398
 
          one chapter.
399
 
          Each chapter consists of a heading,
400
 
          zero or more <ref id="block">blocks</ref>,
401
 
          and zero or more <ref id="section">sections</ref>.
402
 
        </p>
403
 
        <p>
404
 
          Each chapter in the document is automatically listed in the
405
 
          documents contents page (if it has one).
406
 
        </p>
407
 
      </section>
408
 
 
409
 
      <section id="class">
410
 
        <heading>class</heading>
411
 
        <p>
412
 
          This is the main element for Objective-C code documentation.
413
 
          The <em>name</em> attribute is required for this element - it is
414
 
          the name of the class.  The <em>super</em> attribute is normally
415
 
          necessary to provide the name of the superclass.
416
 
        </p>
417
 
        <p>
418
 
          The elements in a class are - an optional
419
 
          <ref id="declared">declared</ref> element,
420
 
          zero or more <ref id="conform">conform</ref> element,
421
 
          an optional <ref id="desc">description</ref>,
422
 
          zero or more <ref id="method">method</ref> elements,
423
 
          and an optional <ref id="standards">standards</ref> element.
424
 
        </p>
425
 
      </section>
426
 
 
427
 
      <section id="conform">
428
 
        <heading>conform</heading>
429
 
        <p>
430
 
          This element contains simple text giving the name of a protocol
431
 
          or interface to which a class conforms.
432
 
        </p>
433
 
      </section>
434
 
 
435
 
      <section id="declared">
436
 
        <heading>declared</heading>
437
 
        <p>
438
 
          This element contains simple text giving the name of the header
439
 
          file in which something is declared.
440
 
        </p>
441
 
      </section>
442
 
 
443
 
      <section id="desc">
444
 
        <heading>desc</heading>
445
 
        <p>
446
 
          This element is used to contain descriptions of how software
447
 
          functions.  It may contain <ref id="text">text</ref>, but may
448
 
          also contain <ref id="list">lists</ref>,
449
 
          <ref id="p">paragraphs</ref>, 
450
 
          <ref id="example">examples</ref> and
451
 
          <ref id="mbed">embedded data</ref>.
452
 
        </p>
453
 
      </section>
454
 
 
455
 
      <section id="heading">
456
 
        <heading>heading</heading>
457
 
        <p>
458
 
          Each <ref id="chapter">chapter</ref>,
459
 
          <ref id="section">section</ref>
460
 
          <ref id="subsect">sub-section</ref>,
461
 
          or <ref id="subsubsect">sub-sub-section</ref>
462
 
          has a heading as the first thing in it.
463
 
          These headings introduce the sections and are listed in the
464
 
          contents page.
465
 
        </p>
466
 
      </section>
467
 
 
468
 
      <section id="p">
469
 
        <heading>p</heading>
470
 
        <p>
471
 
          The paragraph element simply contains <ref id="text">text</ref>.
472
 
          Most descriptive writing is inside paragraphs.
473
 
        </p>
474
 
      </section>
475
 
 
476
 
      <section id="section">
477
 
        <heading>section</heading>
478
 
        <p>
479
 
          The <em>section</em> element is just like a
480
 
          <ref id="chapter">chapter</ref>, except that it contains
481
 
          <ref id="subsect">sub-sections</ref> where a chapter would
482
 
          contain sections.
483
 
        </p>
484
 
      </section>
485
 
 
486
 
      <section id="standards">
487
 
        <heading>standards</heading>
488
 
        <p>
489
 
          The <em>standards</em> element contains any number of
490
 
          standard elements whioch specify what standards a particular
491
 
          piece of code does or does not conform to.
492
 
          <br/>
493
 
          The defined values are -
494
 
        </p>
495
 
        <list>
496
 
          <item>&lt;GNUstep/&gt;</item>
497
 
          <item>&lt;OpenStep/&gt;</item>
498
 
          <item>&lt;NotOpenStep/&gt;</item>
499
 
          <item>&lt;MacOS-X/&gt;</item>
500
 
          <item>&lt;NotMacOS-X/&gt;</item>
501
 
        </list>
502
 
      </section>
503
 
 
504
 
      <section id="subsect">
505
 
        <heading>subsect</heading>
506
 
        <p>
507
 
          The <em>subsect</em> element is just like a
508
 
          <ref id="section">section</ref>, except that it contains
509
 
          <ref id="subsubsect">sub-sub-sections</ref> where a section would
510
 
          contain sub-sections.
511
 
        </p>
512
 
      </section>
513
 
 
514
 
      <section id="subsubsect">
515
 
        <heading>subsubsect</heading>
516
 
        <p>
517
 
          The <em>subsubsect</em> element is just like a
518
 
          <ref id="subsect">sub-section</ref>, except that it contains
519
 
          only a <ref id="heading">heading</ref> and zero or more
520
 
          <ref id="block">blocks</ref>.
521
 
        </p>
522
 
      </section>
523
 
 
524
 
      <section id="text">
525
 
        <heading>text</heading>
526
 
        <p>
527
 
          This is not really an element, we simply talk about text where
528
 
          we mean raw text and very simple markup such as -
529
 
        </p>
530
 
        <deflist>
531
 
          <term><ref id="br">br</ref></term>
532
 
          <desc>a forced line-break</desc>
533
 
          <term><ref id="footnote">footnote</ref></term>
534
 
          <desc>a reference to a footnote that appears in full elsewhere</desc>
535
 
          <term><ref id="label">label</ref></term>
536
 
          <desc>
537
 
            a piece of text marked so that it can be referred to from elsewhere.
538
 
          </desc>
539
 
          <term><ref id="entry">entry</ref></term>
540
 
          <desc>
541
 
            an invisible mark that can be referred to from elsewhere.
542
 
          </desc>
543
 
          <term><ref id="ref">ref</ref></term>
544
 
          <desc>
545
 
            text marked as a reference to elsewhere in the document.
546
 
          </desc>
547
 
          <term><ref id="uref">uref</ref></term>
548
 
          <desc>
549
 
            text marked as a reference to a hypertext URL.
550
 
          </desc>
551
 
          <term><ref id="url">url</ref></term>
552
 
          <desc>
553
 
            a hypertext URL.
554
 
          </desc>
555
 
          <term><ref id="email">email</ref></term>
556
 
          <desc>
557
 
            an email address.
558
 
          </desc>
559
 
        </deflist>
560
 
      </section>
 
325
      <p>
 
326
        The allowable elements in GSDoc documents are described below, broken
 
327
        into sections by usage context.
 
328
      </p>
 
329
 
 
330
      <section id="sectioningElements"><label id="sectioningElements"/>
 
331
        <heading>Sectioning Elements</heading>
 
332
        <p>
 
333
          <em>Sectioning elements</em> define hierarchical document structure.
 
334
        </p>
 
335
        <deflist>
 
336
          <term><code><label id="chapter">&lt;chapter&gt;</label></code></term>
 
337
          <desc>This is the basic, top-level element of the document body.
 
338
          Each chapter consists of a <ref id="heading">heading</ref>,
 
339
          zero or more <ref id="blockElements">blocks</ref>, and zero or more
 
340
          <ref id="section">sections</ref>.  Each chapter in the document is
 
341
          automatically listed in the documents contents page (if it has one).
 
342
          </desc>
 
343
          <term><code><label id="section">&lt;section&gt;</label></code></term>
 
344
          <desc>First level below <code>chapter</code>.  It contains
 
345
          <ref id="subsection">sub-sections</ref> where a chapter would
 
346
          contain sections.</desc>
 
347
          <term><code><label id="subsection">&lt;subsection&gt;</label></code>
 
348
          </term>
 
349
          <desc>Level below <code>section</code>.</desc>
 
350
          <term><code><label id="subsubsection">&lt;subsubsection&gt;</label></code></term>
 
351
          <desc>Level below <code>subsection</code>.</desc>
 
352
          <term><code><label id="heading">&lt;heading&gt;</label></code></term>
 
353
          <desc>Each <ref id="chapter">chapter</ref>,
 
354
          <ref id="section">section</ref>
 
355
          <ref id="subsection">sub-section</ref>,
 
356
          or <ref id="subsubsection">sub-sub-section</ref>
 
357
          has a heading as the first thing in it.
 
358
          These headings introduce the sections and are listed in the
 
359
          contents page.</desc>
 
360
        </deflist>
 
361
      </section>
 
362
 
 
363
      <section id="blockElements"><label id="blockElements"/>
 
364
        <heading>Block Elements</heading>
 
365
        <p>
 
366
          <em>Block elements</em> can occur at the top level of sections,
 
367
          as well is in certain other contexts.  The block elements are -
 
368
        </p>
 
369
        <deflist>
 
370
          <term><code><label id="embed">&lt;embed&gt;</label></code></term>
 
371
          <desc>marks embedded information from elsewhere</desc>
 
372
          <term><br/><code><label id="example">&lt;example&gt;</label></code></term>
 
373
          <desc>marks an example</desc>
 
374
          <term><br/><code><label id="index">&lt;index&gt;</label></code></term>
 
375
          <desc>
 
376
            The <code>&lt;index&gt;</code> tag is special in that it is
 
377
            dynamically expanded during output based on information that has
 
378
            been collated from reading in various documentation and source
 
379
            files.  The <code>type</code> attribute of the index specifies
 
380
            what sort of item is to be in the index - the default type of
 
381
            <code>label</code> causes an index of all <em>label</em> and
 
382
            <em>entry</em> elements to be generated.  Currently the allowable
 
383
            types are: <code>class</code>, <code>category</code>,
 
384
            <code>protocol</code>, <code>method</code>,
 
385
            <code>ivariable</code>, <code>function</code>, <code>type</code>,
 
386
            <code>macro</code>, <code>variable</code>, <code>constant</code>,
 
387
            <code>label</code>, <code>title</code>, <code>EOModel</code>
 
388
            (associated with the Enterprise Objects Framework, for interacting
 
389
            with databases), <code>EOEntity</code>.  The default is
 
390
            "<code>label</code>".
 
391
            <p>
 
392
              The <code>&lt;index&gt;</code> element also takes three optional
 
393
             attributes -
 
394
            </p>
 
395
            <deflist>
 
396
              <term><code>scope</code></term>
 
397
              <desc>
 
398
                Determines whether the index is generated for the current file
 
399
                ("<code>file</code>" scope), or for the whole of the current
 
400
                project ("<code>project</code>" scope), or for everything the
 
401
                software can find ("<code>global</code>" scope).  In certain
 
402
                contexts the specified scope is automatically overridden ... if
 
403
                the document is processed in a standalone manner, the scope is
 
404
                always "<code>file</code>".  For method or ivariable indexing,
 
405
                if the index is inside a class, protocol, or category, only
 
406
                indexes for that unit are generated.
 
407
              </desc>
 
408
              <term><code>style</code></term>
 
409
              <desc>
 
410
                Determines whether the index is presented with standard
 
411
                embellishments such as bulleted entries and a header
 
412
                ("<code>normal</code>" style) or in a minimalist style suitable
 
413
                for, e.g., a navigation bar ("<code>bare</code>" style).
 
414
              </desc>
 
415
              <term><code>target</code></term>
 
416
              <desc>
 
417
                Provides additional information to accompany links formed from
 
418
                the index.  For HTML output, this is translated into a
 
419
                "<code>target</code>" attribute to the <code>&lt;a&gt;
 
420
                href="..."</code> element generated for a link.  In most cases
 
421
                this can safely be left out.
 
422
              </desc>
 
423
            </deflist>
 
424
          </desc>
 
425
 
 
426
          <term><br/><em>text elements</em></term>
 
427
          <desc>
 
428
            A variety of elements for text formatting, many based on HTML tags.
 
429
            See <ref id="textElements">below</ref> for details.
 
430
          </desc>
 
431
 
 
432
          <term><br/><em>list elements</em></term>
 
433
          <desc>
 
434
            A variety of lists.  See <ref id="listElements">below</ref> for
 
435
            details.
 
436
          </desc>
 
437
 
 
438
          <term><br/><em>cross reference elements</em></term>
 
439
          <desc>
 
440
            A variety of elements for representing external references and
 
441
            internal references to other parts of a document.
 
442
            See <ref id="crossrefElements">below</ref> for details.
 
443
          </desc>
 
444
 
 
445
          <term><br/><em>definition elements</em></term>
 
446
          <desc>
 
447
            A variety of specialised elements for software documentation.
 
448
            See <ref id="definitionElements">below</ref> for details.
 
449
          </desc>
 
450
        </deflist>
 
451
      </section>
 
452
 
 
453
      <section id="textElements"><label id="textElements"/>
 
454
        <heading>Text Elements</heading>
 
455
        <p>
 
456
          <em>Text elements</em> can occur within blocks and typically within
 
457
          other block elements such as
 
458
          <code><ref id="example">example</ref></code> as well.  They carry
 
459
          out various presentation-related purposed.
 
460
          The text elements are -
 
461
        </p>
 
462
        <deflist>
 
463
          <term><code><label id="p">&lt;p&gt;</label></code></term>
 
464
          <desc>The paragraph, as in HTML.  The paragraph element simply
 
465
          contains <ref id="textElements">text</ref>.  Most descriptive
 
466
          writing is inside paragraphs.</desc>
 
467
          <term><code><label id="br">&lt;br&gt;</label></code></term>
 
468
          <desc>The line-break, as in HTML.</desc>
 
469
          <term><code><label id="example">&lt;example&gt;</label></code>
 
470
          </term>
 
471
          <desc>Marks an example.</desc>
 
472
          <term><code><label id="footnote">&lt;footnote&gt;</label></code>
 
473
          </term>
 
474
          <desc>A reference to a footnote that appears in full elsewhere.
 
475
          </desc>
 
476
          <term><code><label id="code">&lt;code&gt;</label></code></term>
 
477
          <desc>The content is either a name for code (e.g. class names), or a
 
478
                relatively short code fragment.</desc>
 
479
          <term><code><label id="em">&lt;em&gt;</label></code></term>
 
480
          <desc>Emphasized text.</desc>
 
481
          <term><code><label id="strong">&lt;strong&gt;</label></code></term>
 
482
          <desc>More strongly emphasized text.</desc>
 
483
          <term><code><label id="file">&lt;file&gt;</label></code></term>
 
484
          <desc>The content is a filename.</desc>
 
485
          <term><code><label id="ivar">&lt;ivar&gt;</label></code></term>
 
486
          <desc>The content is a metasyntactic ivariable name.</desc>
 
487
          <term><code><label id="var">&lt;var&gt;</label></code></term>
 
488
          <desc>The content is a metasyntactic variable or argument name.</desc>
 
489
          <term><code><label id="site">&lt;site&gt;</label></code></term>
 
490
          <desc>The content is a fully qualified domain name on the Internet.
 
491
          </desc>
 
492
          <term><code><label id="cdata">(text)</label></code></term>
 
493
          <desc>Unstructured text content is also allowed.</desc>
 
494
        </deflist>
 
495
      </section>
 
496
 
 
497
      <section id="listElements"><label id="listElements"/>
 
498
        <heading>List Elements</heading>
 
499
        <p>
 
500
          <em>List elements</em> can occur within blocks and typically within
 
501
          other block elements such as
 
502
          <code><ref id="example">example</ref></code> as well.  They support
 
503
          presentation of various types of lists.
 
504
          The list elements are -
 
505
        </p>
 
506
        <deflist>
 
507
          <term><code><label id="list">&lt;list&gt;</label></code></term>
 
508
          <desc>A simple, unnumbered list of items, each contained within an
 
509
          <code>&lt;item&gt;</code> tag.</desc>
 
510
          <term><code><label id="enum">&lt;enum&gt;</label></code></term>
 
511
          <desc>A numbered list (<code>&lt;item&gt;</code> tags).</desc>
 
512
          <term><code><label id="deflist">&lt;deflist&gt;</label></code></term>
 
513
          <desc>A list of terms with definitions, marked as alternating
 
514
          <code>&lt;term&gt;</code> and <code>&lt;desc&gt;</code> tags.</desc>
 
515
          <term><code><label id="dictionary">&lt;dictionary&gt;</label></code>
 
516
          </term>
 
517
          <desc>An attribute-value list similar to an NSDictionary.  Consists
 
518
          of a sequence of <code>&lt;dictionaryItem&gt;</code> tags each with
 
519
          a required <code>key</code> attribute and an optional
 
520
          <code>value</code> attribute.  If this is excluded, the element
 
521
          content, which may be any
 
522
          <ref id="blockElements"><em>block</em> element</ref> (including
 
523
          another <code>&lt;dictionary&gt;</code> tag) is the value.</desc>
 
524
          <term><code><label id="qalist">&lt;qalist&gt;</label></code></term>
 
525
          <desc>A list of <code>&lt;question&gt;</code>s and
 
526
          <code>&lt;answer&gt;</code>s.</desc>
 
527
        </deflist>
 
528
      </section>
 
529
 
 
530
      <section id="crossrefElements"><label id="crossrefElements"/>
 
531
        <heading>Cross-Reference Elements</heading>
 
532
        <p>
 
533
          <em>Cross-reference elements</em> can occur within blocks and
 
534
          typically anywhere text elements can occur.  They represent
 
535
          references to other entities inside or outside the project being
 
536
          documented.  In output formats that support it, they are generally
 
537
          transformed into hyperlinks.  The cross-reference elements are -
 
538
        </p>
 
539
        <deflist>
 
540
          <term><code><label id="ref">&lt;ref&gt;</label></code></term>
 
541
          <desc>A reference to another entity within collection of documents
 
542
          describing the current project.  In practice this means a reference
 
543
          to an element in a GSDoc document.  Standard conventions for document
 
544
          naming and structure are used to generate a hyperlink in output.
 
545
          To support this resolution, two attributes must be specified.
 
546
          <deflist>
 
547
            <term><code>type</code></term>
 
548
            <desc>This is the type of entity being referenced.  It may take
 
549
            one of the following values: <code>class</code>,
 
550
            <code>category</code>, <code>protocol</code>, <code>method</code>,
 
551
            <code>ivariable</code>, <code>function</code>, <code>type</code>,
 
552
            <code>macro</code>, <code>variable</code>, <code>constant</code>,
 
553
            <code>label</code>, <code>EOModel</code>, <code>EOEntity</code>.
 
554
            If <code>type</code> is not specified, "<code>label</code>" is
 
555
            assumed.</desc>
 
556
            <term><code>id</code></term>
 
557
            <desc>Specifies the identifier of the reference.  In most cases
 
558
            this will be the name of the class, method, or other specific
 
559
            entity being referenced.  In the case of <code>label</code>
 
560
            references, this is the <code>id</code> attribute of the label
 
561
            being referenced.</desc>
 
562
            <term><code>class</code></term>
 
563
            <desc>In the case where a <code>method</code> is being referenced,
 
564
            the <code>class</code> attribute should be specified as well, and
 
565
            should contain the name of the class the method occurs in, in one
 
566
            of the following formats: "classname", "classname(categoryname)",
 
567
            or "(protocolname)".</desc>
 
568
          </deflist>
 
569
          </desc>
 
570
          <term><code><label id="prjref">&lt;prjref&gt;</label></code></term>
 
571
          <desc>A reference to another project, which assumedly has also had
 
572
          GSDoc generated for it.  A link in the output will be generated to
 
573
          ???.  The <code>&lt;prjref&gt;</code> tag may contain text content,
 
574
          which appears in the output.</desc>
 
575
          <term><code><label id="uref">&lt;uref&gt;</label></code></term>
 
576
          <desc>A reference to a URL.  Usage is similar to the
 
577
          <code>&lt;A&gt;</code> tag in HTML, except that the attribute
 
578
          '<code>url</code>' is used for the URL rather than
 
579
          '<code>href</code>'.  Text contents are shown in the output to label
 
580
          the hyperlink.</desc>
 
581
          <term><code><label id="url">&lt;url&gt;</label></code></term>
 
582
          <desc>Similar to <code>&lt;uref&gt;</code> except the URL itself is
 
583
          automatically used as the hyperlink label (and so the tag itself does
 
584
          not have text content).</desc>
 
585
          <term><code><label id="email">&lt;email&gt;</label></code></term>
 
586
          <desc>An email address.  Translates in HTML output to a
 
587
          <code>mailto:</code> link.</desc>
 
588
          <term><code><label id="entry">&lt;entry&gt;</label></code></term>
 
589
          <desc>An entry for the general index.  Contains text elements but
 
590
          this text appears only in the index, and never in the text itself.
 
591
          It takes a single attribute, <code>id</code>, which may be used to
 
592
          refer to the entry.  (If it is absent any text content is taken to
 
593
          be the id.)</desc>
 
594
          <term><code><label id="label">&lt;label&gt;</label></code></term>
 
595
          <desc>A general purpose marker that can contain text elements,
 
596
          which will appear in the output where the label occurs.
 
597
          It takes a single attribute, <code>id</code>, which may be used to
 
598
          refer to the label.  (If it is absent any text content is taken to
 
599
          be the id.)</desc>
 
600
        </deflist>
 
601
      </section>
 
602
 
 
603
      <section id="definitionElements"><label id="definitionElements"/>
 
604
        <heading>Definition Elements</heading>
 
605
        <p>
 
606
          <em>Definition elements</em> are specialized elements for software
 
607
          documentation.  They can occur in most places that block elements
 
608
          can occur.  They represent specific Objective-C elements, and are
 
609
          formatted specially in output.  In the majority of cases, you will
 
610
          not need to write GSDoc using these elements, since they can be
 
611
          autogenerated from Objective-C source files and special comments
 
612
          within them.  The definition elements are -
 
613
        </p>
 
614
        <deflist>
 
615
 
 
616
          <term><code><label id="class">&lt;class&gt;</label></code></term>
 
617
          <desc>
 
618
            An Objective-C <em>class</em> definition.  This is the main element
 
619
            for Objective-C code documentation. The <code>name</code> attribute
 
620
            is required for this element - it is the name of the class.  The
 
621
            <code>super</code> attribute is normally necessary to provide the
 
622
            name of the superclass.
 
623
            <p>
 
624
              The elements in a <code>&lt;class&gt;</code> are - an optional
 
625
              <ref id="declared">declared</ref> element,
 
626
              zero or more <ref id="conform">conform</ref> elements,
 
627
              an optional <ref id="desc">desc</ref>,
 
628
              zero or more <ref id="ivariable">ivariable</ref> elements,
 
629
              zero or more <ref id="method">method</ref> elements,
 
630
              and an optional <ref id="standards">standards</ref> element.
 
631
            </p>
 
632
          </desc>
 
633
 
 
634
          <term><code><label id="category">&lt;category&gt;</label></code>
 
635
          </term>
 
636
          <desc>
 
637
            An Objective-C <em>category</em> definition.  It requires both a
 
638
            <code>name</code> attribute providing the name of the category,
 
639
            and a <code>class</code> attribute naming the class the category
 
640
            is associated with.
 
641
            <p>
 
642
              The elements in a <code>&lt;category&gt;</code> are - an optional
 
643
              <ref id="declared">declared</ref> element,
 
644
              zero or more <ref id="conform">conform</ref> elements,
 
645
              an optional <ref id="desc">desc</ref>,
 
646
              zero or more <ref id="method">method</ref> elements,
 
647
              and an optional <ref id="standards">standards</ref> element.
 
648
            </p>
 
649
          </desc>
 
650
 
 
651
          <term><code><label id="protocol">&lt;protocol&gt;</label></code>
 
652
          </term>
 
653
          <desc>
 
654
            An Objective-C <em>protocol</em> definition.  It requires a
 
655
            <code>name</code> attribute providing the name of the protocol.
 
656
            <p>
 
657
              The elements in a <code>&lt;protocol&gt;</code> are - an optional
 
658
              <ref id="declared">declared</ref> element,
 
659
              zero or more <ref id="conform">conform</ref> elements,
 
660
              an optional <ref id="desc">desc</ref>,
 
661
              zero or more <ref id="method">method</ref> elements,
 
662
              and an optional <ref id="standards">standards</ref> element.
 
663
            </p>
 
664
          </desc>
 
665
 
 
666
          <term><code><label id="function">&lt;function&gt;</label></code>
 
667
          </term>
 
668
          <desc>
 
669
            A C <em>function</em> definition.  It requires a
 
670
            <code>name</code> attribute providing the function's name and a
 
671
            <code>type</code> attribute providing the return type.
 
672
            <p>
 
673
              The elements in a <code>&lt;function&gt;</code> are -
 
674
              a series of zero or more <ref id="arg">arg</ref> elements,
 
675
              followed by an optional <ref id="vararg">arg</ref> element,
 
676
              then an optional <ref id="declared">declared</ref> element,
 
677
              an optional <ref id="desc">desc</ref>,
 
678
              and an optional <ref id="standards">standards</ref> element.
 
679
            </p>
 
680
          </desc>
 
681
 
 
682
          <term><code><label id="macro">&lt;macro&gt;</label></code></term>
 
683
          <desc>
 
684
            A C <em>macro</em> definition.  It requires a
 
685
            <code>name</code> attribute providing the macro's name.
 
686
            <p>
 
687
              The elements in a <code>&lt;macro&gt;</code> are -
 
688
              a series of zero or more <ref id="arg">arg</ref> elements,
 
689
              followed by an optional <ref id="vararg">arg</ref> element,
 
690
              then an optional <ref id="declared">declared</ref> element,
 
691
              an optional <ref id="desc">desc</ref>,
 
692
              and an optional <ref id="standards">standards</ref> element.
 
693
            </p>
 
694
          </desc>
 
695
 
 
696
          <term><code><label id="type">&lt;type&gt;</label></code></term>
 
697
          <desc>
 
698
            A C <em>type</em> definition.  It requires a
 
699
            <code>name</code> attribute providing the macro's name.
 
700
            <p>
 
701
              The elements in a <code>&lt;macro&gt;</code> are -
 
702
              an optional <ref id="declared">declared</ref> element,
 
703
              an optional <ref id="desc">desc</ref>,
 
704
              and an optional <ref id="standards">standards</ref> element.
 
705
            </p>
 
706
          </desc>
 
707
 
 
708
          <term><code><label id="constant">&lt;constant&gt;</label></code>
 
709
          </term>
 
710
          <desc>
 
711
            A C <em>constant</em> definition.  It requires
 
712
            <code>name</code> and <code>type</code> attributes and a
 
713
             <code>value</code> attribute is optional.  In addition, an
 
714
             Objective-C role for the constant may be specified using the
 
715
             <code>role</code> attribute.  Acceptable values for this attribute
 
716
             are: "<code>except</code>", "<code>defaults</code>",
 
717
             "<code>notify</code>", or "<code>key</code>".
 
718
            <p>
 
719
              The elements in a <code>&lt;constant&gt;</code> are -
 
720
              an optional <ref id="declared">declared</ref> element,
 
721
              an optional <ref id="desc">desc</ref>,
 
722
              and an optional <ref id="standards">standards</ref> element.
 
723
            </p>
 
724
          </desc>
 
725
 
 
726
          <term><code><label id="variable">&lt;variable&gt;</label></code>
 
727
          </term>
 
728
          <desc>
 
729
            A C <em>variable</em> definition.  It requires
 
730
            <code>name</code> and <code>type</code> attributes and a
 
731
             <code>value</code> attribute is optional.
 
732
            <p>
 
733
              The elements in a <code>&lt;variable&gt;</code> are -
 
734
              an optional <ref id="declared">declared</ref> element,
 
735
              an optional <ref id="desc">desc</ref>,
 
736
              and an optional <ref id="standards">standards</ref> element.
 
737
            </p>
 
738
          </desc>
 
739
 
 
740
          <term><code><label id="ivariable">&lt;ivariable&gt;</label></code>
 
741
          </term>
 
742
          <desc>
 
743
            An objective C <em>instance variable</em> definition.  It requires
 
744
            <code>name</code> and <code>type</code> attributes and a
 
745
             <code>validity</code> attribute optionally specifies the access
 
746
             level for the variable (may be "<code>public</code>",
 
747
             "<code>protected</code>", or "<code>private</code>", the default
 
748
             is "<code>public</code>").
 
749
            <p>
 
750
              The elements in a <code>&lt;variable&gt;</code> are -
 
751
              an optional <ref id="desc">desc</ref>,
 
752
              and an optional <ref id="standards">standards</ref> element.
 
753
            </p>
 
754
          </desc>
 
755
 
 
756
          <term><code><label id="desc">&lt;desc&gt;</label></code></term>
 
757
          <desc>An element for general descriptive text.  Contains a block and
 
758
          occurs in various contexts including <ref id="deflist">deflists</ref>
 
759
          as well as most
 
760
          <ref id="definitionElements">definition elements</ref>.<br/><br/>
 
761
          </desc>
 
762
 
 
763
          <term><code><label id="standards">&lt;standards&gt;</label></code>
 
764
          </term>
 
765
          <desc>
 
766
              This element contains any number of standard elements which
 
767
              specify what standards a particular piece of code does or does
 
768
              not conform to.
 
769
              <br/>
 
770
              The defined values are -
 
771
            <list>
 
772
              <item><code>&lt;GNUstep/&gt;</code></item>
 
773
              <item><code>&lt;OpenStep/&gt;</code></item>
 
774
              <item><code>&lt;NotOpenStep/&gt;</code></item>
 
775
              <item><code>&lt;MacOS-X/&gt;</code></item>
 
776
              <item><code>&lt;NotMacOS-X/&gt;</code></item>
 
777
            </list>
 
778
            <br/>
 
779
          </desc>
 
780
 
 
781
          <term><code><label id="conform">&lt;conform&gt;</label></code></term>
 
782
          <desc>
 
783
            This element contains simple text giving the name of a protocol
 
784
            or interface to which a class conforms.<br/><br/>
 
785
          </desc>
 
786
 
 
787
          <term><code><label id="declared">&lt;declared&gt;</label></code>
 
788
          </term>
 
789
          <desc>
 
790
            This element contains simple text giving the name of the header
 
791
            file in which something is declared.<br/><br/>
 
792
          </desc>
 
793
 
 
794
          <term><code><label id="method">&lt;method&gt;</label></code>
 
795
          </term>
 
796
          <desc>
 
797
            Describes an Objective-C method.  Only valid within a
 
798
            <ref id="class">class</ref>, <ref id="protocol">protocol</ref>,
 
799
            or <ref id="category">category</ref>.  An optional
 
800
            <code>type</code> attribute describes the return type; an optional
 
801
            <code>factory</code> attribute ("<code>yes</code>" or
 
802
            "<code>no</code>", defaults to "<code>no</code>") specifies whether
 
803
            this is a class or instance method.  (Class methods are typically
 
804
            only used for construction purposes in Objective-C.)  An optional
 
805
            <code>init</code> attribute (also taking
 
806
            "<code>yes</code>" / "<code>no</code>") specifies whether this is
 
807
            the designated constructor.  An optional <code>override</code>
 
808
            attribute specifies whether this method should be overridden
 
809
            (if "yes" enter "<code>subclass</code>", if "no" enter
 
810
            "<code>never</code>").
 
811
            <p>
 
812
              The elements in a <code>&lt;method&gt;</code> are -
 
813
              the method's name (in a <ref id="sel">sel</ref> element), the
 
814
              method's arguments (a sequence of <ref id="arg">arg</ref> then
 
815
              <ref id="sel">sel</ref>,<ref id="arg">arg</ref> pairs, then an
 
816
              optional <ref id="vararg">vararg</ref> element),
 
817
              followed by an optional <ref id="desc">desc</ref>,
 
818
              zero or more <ref id="ivariable">ivariable</ref> elements,
 
819
              zero or more <ref id="method">method</ref> elements,
 
820
              and an optional <ref id="standards">standards</ref> element.
 
821
            </p>
 
822
          </desc>
 
823
 
 
824
          <term><code><label id="sel">&lt;sel&gt;</label></code></term>
 
825
          <desc>
 
826
            Content is a method name or argument name (referred to as a
 
827
            "selector" in some cases, but different from an Objective-C
 
828
            method selector (runtime pointer to a method implementation).
 
829
            <br/><br/>
 
830
          </desc>
 
831
 
 
832
          <term><code><label id="arg">&lt;arg&gt;</label></code></term>
 
833
          <desc>
 
834
            Content is a an argument name.  Takes a mandatory <code>type</code>
 
835
            attribute giving the argument's type.
 
836
            <br/><br/>
 
837
          </desc>
 
838
 
 
839
          <term><code><label id="vararg">&lt;vararg&gt;</label></code></term>
 
840
          <desc>
 
841
            An empty element indicating that a variable argument list may be
 
842
            used (in a <ref id="method">method</ref> or
 
843
            <ref id="function">function</ref> definition).
 
844
            <br/><br/>
 
845
          </desc>
 
846
 
 
847
        </deflist>
 
848
      </section>
 
849
 
561
850
 
562
851
    </chapter>
563
852
 
 
853
    <!-- Begin test dictionary. - ->
564
854
    <chapter>
565
 
      <heading>The gsdoc conversion tool</heading>
566
 
      <p>
567
 
        The gsdoc tool is written in Objective-C and uses the GNUstep base
568
 
        library and the Gnome XML parser library.
569
 
      </p>
570
 
      <p>
571
 
        This tool is intended to convert GSDoc documents to other formats
572
 
        though, at present, only HTML output is supported.
573
 
      </p>
574
 
      <p>
575
 
        Use of the tool is trivial - just provide it with a list of gsdoc
576
 
        file names, and it will produce a load of html output files.
577
 
      </p>
578
 
      <section>
579
 
        <heading>Parameters</heading>
580
 
        <deflist>
581
 
          <term><ref id="--makeRefs">--makeRefs=ReferencesFileName</ref>                  </term>
582
 
          <desc>
583
 
            With this option, gsdoc reads gsdoc files and creates
584
 
            ReferencesFileName.gsdocrefs files which can be used as
585
 
            <ref id="">--refs</ref> to make links between elements.
586
 
          </desc>
587
 
          <term><ref id="--projectName">--projectName=TheProjectName</ref>
588
 
          </term>
589
 
          <desc>
590
 
            Set the project name to "TheProjectName".  It is used to index
591
 
            titles,...
592
 
          </desc>
593
 
          <term><ref id="--refs">--refs=ARefFile or --refs=ARefDirectory</ref>
594
 
          </term>
595
 
          <desc>
596
 
            Use ARefFile.gsdocrefs (or files with extensions .gsdocrefs in
597
 
            ARefDirectory directory) as references files.  It enables you to
598
 
            make links between documentation areas.
599
 
          </desc>
600
 
          <term><ref id="--makeIndex">--makeIndex=MyIndexFileName</ref></term>
601
 
          <desc>
602
 
            Create an index of the parsed files and save it as
603
 
            MyIndexName.gsdoc. You have to set --makeIndexTemplate option.
604
 
          </desc>
605
 
          <term><ref id="--makeIndexTemplate">--makeIndexTemplate=MyIndexTemplateFileName</ref></term>
606
 
          <desc>
607
 
            The file used as index template for makeIndex option
608
 
          </desc>
609
 
          <term><ref id="--define-">--define-XXX=YYY</ref></term>
610
 
          <desc>
611
 
            Used to define a constant named XXX with value YYY in .gsdoc file,
612
 
            all [[infoDictionary.XXX]] texts are replaced with YYY
613
 
          </desc>
614
 
          <term><ref id="-verbose">--verbose=X</ref></term>
615
 
          <desc>
616
 
            Level of traces from 0 to ...
617
 
          </desc>
618
 
          <term><ref id="--location">--location=file://usr/doc/gnustep/MyProject or --location=http://www.gnustep.org/gnustep/MyProject</ref></term>
619
 
          <desc>
620
 
            Location of the installed documentation (it helps to make links
621
 
            between projects)
622
 
          </desc>
623
 
          <term><ref id="files">file1 file2</ref></term>
624
 
          <desc>
625
 
            The .gsdoc files to be processed.
626
 
          </desc>
627
 
        </deflist>
628
 
      </section>
629
 
      <section>
630
 
        <heading>Example</heading>
631
 
        <subsect>
632
 
          <heading>AutoDoc</heading>
633
 
          <example>
634
 
autodoc -allclasses -format html -template \
635
 
  /usr/GNUstep/System/Libraries/Resources/DocTemplates/AutoDocTemplate.gsdoc \
636
 
  -copyright "Orange Concept" \
637
 
  -define-author-name "Manuel Guesdon" \
638
 
  -define-author-email "mguesdon@orange-concept.com" \
639
 
  -define-author-desc "Developer" \
640
 
  -define-author-url "http://www.orange-concept.com" -define-dtd-ref \
641
 
  "/usr/GNUstep/System/Libraries/Resources/DTDs/gsdoc-0_6_6.dtd" \
642
 
  -define-stylesheeturl "http://www.orange-concept.com/styles/default.css" \
643
 
  -define-basetitle "MyDoc:" \
644
 
  -define-dtd-url "http://www.gnustep.org/gsdoc-0_6_6.xml" \
645
 
  -define-next "[[next]]" -define-prev "[[prev]]" -define-up "[[up]]" \
646
 
  MySource.h
647
 
          </example>
648
 
          <p>
649
 
            The above example takes MySource.h and MySource.m and generates
650
 
            one or more gsdoc files (they have the extension .html,
651
 
            so please rename them with .gsdoc extension after running
652
 
            AutoDoc
653
 
          </p>
654
 
        </subsect>
655
 
        <subsect>
656
 
          <heading>GSDoc</heading>
657
 
          <example>
658
 
gsdoc MyFile1.gsdoc MyFile2.gsdoc Explanations.gsdoc --makeRefs --makeIndex \
659
 
  --makeIndexTemplate=/usr/GNUstep/System/Libraries/Resources/DocTemplates/indextemplate.gsdoc  \
660
 
  --projectName="MyProject" --refs=/usr/doc/gnustep --define-version=2.1 \
661
 
  --verbose=1 --location="/usr/doc/gnustep/MyProject"
662
 
          </example>
663
 
          <p>
664
 
            The above example will parse MyFile1.gsdoc MyFile2.gsdoc and
665
 
            generate MyFile1.html and MyFile2.html. It generates
666
 
            MyProject.gsdocrefs which will countain references of symbols
667
 
            found in MyFile1.gsdoc and MyFile2.gsdoc. MyFile1.html and
668
 
            MyFile2.html will have links to symbols found in
669
 
            MyProject.gsdocrefs and in .gsdocrefs founds in subdirectories of
670
 
            /usr/doc/gnustep. I indicate that the location of this doc will
671
 
            be /usr/doc/gnustep/MyProject.  It also generate an index of
672
 
            MyFile1.html and MyFile2.html contents with the template
673
 
            /usr/GNUstep/System/Libraries/Resources/DocTemplates/indextemplate.gsdoc.
674
 
            Index file is index.gsdoc and the resulting file index.html is
675
 
            automatically generated. I define "version" so the index will
676
 
            take this version.
677
 
          </p>
678
 
        </subsect>
679
 
      </section>
 
855
      <heading>Dictionary Test</heading>
 
856
      <dictionary>
 
857
        <dictionaryItem key="key1" value="value1"/>
 
858
        <dictionaryItem key="key2">value2</dictionaryItem>
 
859
        <dictionaryItem key="key3">
 
860
          <dictionary>
 
861
            <dictionaryItem key="key3a" value="value3a"/>
 
862
            <dictionaryItem key="key3b">value3b</dictionaryItem>
 
863
            <dictionaryItem key="key3c">
 
864
              <dictionary>
 
865
                <dictionaryItem key="key3cI" value="value3cI"/>
 
866
              </dictionary>
 
867
            </dictionaryItem>
 
868
          </dictionary>
 
869
        </dictionaryItem>
 
870
        <dictionaryItem key="key4" value="value4"/>
 
871
      </dictionary>
680
872
    </chapter>
 
873
    < !- - End test dictionary. -->
681
874
 
682
875
    <back>
683
876
<!--
684
877
      <chapter>
685
 
        <heading>Afterward</heading>
 
878
        <heading>Afterward</heading>
686
879
      </chapter>
687
880
-->
688
 
      <index type="label"/>
689
881
    </back>
 
882
 
 
883
 
690
884
  </body>
691
885
</gsdoc>