Debian Codegraph @

tests/docbook/result/fo/gdp-handbook.fo

raw
1 <?xml version="1.0"?>
2 <fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format" font-family="Times Roman" font-size="10pt" text-align="justify">
3 <fo:layout-master-set>
4 <fo:simple-page-master master-name="blank" page-width="8.5in" page-height="11in" margin-top="1in" margin-bottom="1in" margin-left="10pc" margin-right="1in">
5 <fo:region-body margin-bottom="24pt" margin-top="24pt"/>
6 <fo:region-before region-name="xsl-region-before-blank" extent="12pt"/>
7 <fo:region-after region-name="xsl-region-after-blank" extent="12pt"/>
8 </fo:simple-page-master>
9 <fo:simple-page-master master-name="simple1" page-width="8.5in" page-height="11in" margin-top="1in" margin-bottom="1in" margin-left="10pc" margin-right="1in">
10 <fo:region-body margin-bottom="24pt" margin-top="24pt"/>
11 <fo:region-before extent="12pt"/>
12 <fo:region-after extent="12pt"/>
13 </fo:simple-page-master>
14 <fo:simple-page-master master-name="left1" page-width="8.5in" page-height="11in" margin-top="1in" margin-bottom="1in" margin-left="10pc" margin-right="1in">
15 <fo:region-body margin-bottom="24pt" margin-top="24pt"/>
16 <fo:region-before region-name="xsl-region-before-left" extent="12pt"/>
17 <fo:region-after region-name="xsl-region-after-left" extent="12pt"/>
18 </fo:simple-page-master>
19 <fo:simple-page-master master-name="right1" page-width="8.5in" page-height="11in" margin-top="1in" margin-bottom="1in" margin-left="1in" margin-right="10pc">
20 <fo:region-body margin-bottom="24pt" margin-top="24pt"/>
21 <fo:region-before region-name="xsl-region-before-right" extent="12pt"/>
22 <fo:region-after region-name="xsl-region-after-right" extent="12pt"/>
23 </fo:simple-page-master>
24 <fo:simple-page-master master-name="first1" page-width="8.5in" page-height="11in" margin-top="1in" margin-bottom="1in" margin-left="1in" margin-right="1in">
25 <fo:region-body margin-bottom="24pt" margin-top="24pt"/>
26 <fo:region-before region-name="xsl-region-before-first" extent="12pt"/>
27 <fo:region-after region-name="xsl-region-after-first" extent="12pt"/>
28 </fo:simple-page-master>
29 <fo:simple-page-master master-name="simple2" page-width="8.5in" page-height="11in" margin-top="1in" margin-bottom="1in" margin-left="10pc" margin-right="1in">
30 <fo:region-body column-count="1" margin-bottom="24pt" margin-top="24pt"/>
31 <fo:region-before extent="12pt"/>
32 <fo:region-after extent="12pt"/>
33 </fo:simple-page-master>
34 <fo:simple-page-master master-name="left2" page-width="8.5in" page-height="11in" margin-top="1in" margin-bottom="1in" margin-left="10pc" margin-right="1in">
35 <fo:region-body column-count="1" margin-bottom="24pt" margin-top="24pt"/>
36 <fo:region-before region-name="xsl-region-before-left" extent="12pt"/>
37 <fo:region-after region-name="xsl-region-after-left" extent="12pt"/>
38 </fo:simple-page-master>
39 <fo:simple-page-master master-name="right2" page-width="8.5in" page-height="11in" margin-top="1in" margin-bottom="1in" margin-left="1in" margin-right="10pc">
40 <fo:region-body column-count="1" margin-bottom="24pt" margin-top="24pt"/>
41 <fo:region-before region-name="xsl-region-before-right" extent="12pt"/>
42 <fo:region-after region-name="xsl-region-after-right" extent="12pt"/>
43 </fo:simple-page-master>
44 <fo:simple-page-master master-name="first2" page-width="8.5in" page-height="11in" margin-top="1in" margin-bottom="1in" margin-left="1in" margin-right="1in">
45 <fo:region-body column-count="1" margin-bottom="24pt" margin-top="24pt"/>
46 <fo:region-before region-name="xsl-region-before-first" extent="12pt"/>
47 <fo:region-after region-name="xsl-region-after-first" extent="12pt"/>
48 </fo:simple-page-master>
49 <fo:page-sequence-master master-name="titlepage1">
50 <fo:repeatable-page-master-alternatives>
51 <fo:conditional-page-master-reference master-name="first1"/>
52 </fo:repeatable-page-master-alternatives>
53 </fo:page-sequence-master>
54 <fo:page-sequence-master master-name="oneside1">
55 <fo:repeatable-page-master-alternatives>
56 <fo:conditional-page-master-reference master-name="simple1"/>
57 </fo:repeatable-page-master-alternatives>
58 </fo:page-sequence-master>
59 <fo:page-sequence-master master-name="twoside1">
60 <fo:repeatable-page-master-alternatives>
61 <fo:conditional-page-master-reference master-name="blank" blank-or-not-blank="blank"/>
62 <fo:conditional-page-master-reference master-name="right1" odd-or-even="odd"/>
63 <fo:conditional-page-master-reference master-name="left1" odd-or-even="even"/>
64 </fo:repeatable-page-master-alternatives>
65 </fo:page-sequence-master>
66 <fo:page-sequence-master master-name="titlepage2">
67 <fo:repeatable-page-master-alternatives>
68 <fo:conditional-page-master-reference master-name="first2"/>
69 </fo:repeatable-page-master-alternatives>
70 </fo:page-sequence-master>
71 <fo:page-sequence-master master-name="oneside2">
72 <fo:repeatable-page-master-alternatives>
73 <fo:conditional-page-master-reference master-name="simple2"/>
74 </fo:repeatable-page-master-alternatives>
75 </fo:page-sequence-master>
76 <fo:page-sequence-master master-name="twoside2">
77 <fo:repeatable-page-master-alternatives>
78 <fo:conditional-page-master-reference master-name="blank" blank-or-not-blank="blank"/>
79 <fo:conditional-page-master-reference master-name="right2" odd-or-even="odd"/>
80 <fo:conditional-page-master-reference master-name="left2" odd-or-even="even"/>
81 </fo:repeatable-page-master-alternatives>
82 </fo:page-sequence-master>
83 </fo:layout-master-set>
84 <fo:page-sequence id="index" hyphenate="true" master-name="oneside1" language="en">
85 <fo:static-content flow-name="xsl-region-after">
86 <fo:block text-align="center" font-size="10pt">
87 <fo:page-number/>
88 </fo:block>
89 </fo:static-content>
90 <fo:flow flow-name="xsl-region-body">
91 <fo:block>
92 <fo:block text-align="center" margin-left="-4pc" keep-with-next="always" font-size="24.8832pt" font-weight="bold" font-family="Helvetica">
93 <fo:block keep-with-next.within-column="always" hyphenate="false">The GNOME Handbook of Writing Software Documentation</fo:block>
94 </fo:block>
95 <fo:block>David Mason<fo:block><fo:block>Red Hat, Inc.</fo:block><fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" linefeed-treatment="preserve" white-space-collapse="false">
96 <fo:inline font-family="Courier">&lt;[email protected]&gt;</fo:inline>
97 </fo:block></fo:block>Daniel Mueth<fo:block><fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" linefeed-treatment="preserve" white-space-collapse="false">
98 <fo:inline font-family="Courier">&lt;[email protected]&gt;</fo:inline>
99 </fo:block></fo:block>Alexander Kirillov<fo:block><fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" linefeed-treatment="preserve" white-space-collapse="false">
100 <fo:inline font-family="Courier">&lt;[email protected]&gt;</fo:inline>
101 </fo:block></fo:block></fo:block>
102 <fo:block>
103 This is a pre-release!
104 </fo:block>
105 <fo:block>Copyright © 2000 Red Hat, Inc., Daniel Mueth, and Alexander Kirillov</fo:block>
106 <fo:block>
107 <fo:block>
108 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
109 Permission is granted to copy, distribute and/or modify this
110 document under the terms of the <fo:inline font-style="italic">GNU Free Documentation
111 License</fo:inline>, Version 1.1 or any later version published
112 by the Free Software Foundation with no Invariant Sections, no
113 Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
114 of the <fo:inline font-style="italic">GNU Free Documentation License</fo:inline> from
115 the Free Software Foundation by visiting <fo:basic-link external-destination="http://www.fsf.org">their Web site</fo:basic-link><fo:inline hyphenate="false"> [http://www.fsf.org]</fo:inline> or by writing to:
116 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
117 Boston, MA 02111-1307, USA.
118 </fo:block>
119 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
120 Many of the names used by companies to distinguish their products and
121 services are claimed as trademarks. Where those names appear in any
122 GNOME documentation, and those trademarks are made aware to the members
123 of the GNOME Documentation Project, the names have been printed in caps
124 or initial caps.
125 </fo:block>
126 </fo:block>
127 </fo:block>
128 <fo:block>
129 <fo:table table-layout="fixed">
130 <fo:table-column column-number="1" column-width="33%"/>
131 <fo:table-column column-number="2" column-width="33%"/>
132 <fo:table-column column-number="3" column-width="33%"/>
133 <fo:table-body>
134 <fo:table-row>
135 <fo:table-cell number-columns-spanned="3">
136 <fo:block>Revision History</fo:block>
137 </fo:table-cell>
138 </fo:table-row>
139 <fo:table-row>
140 <fo:table-cell>
141 <fo:block>Revision
142 0.99
143 </fo:block>
144 </fo:table-cell>
145 <fo:table-cell>
146 <fo:block>
147 04.10.2000
148 </fo:block>
149 </fo:table-cell>
150 <fo:table-cell>
151 <fo:block/>
152 </fo:table-cell>
153 </fo:table-row>
154 </fo:table-body>
155 </fo:table>
156 </fo:block>
157 </fo:block>
158 <fo:block id="intro">
159 <fo:block>
160 <fo:block margin-left="-4pc" font-family="Helvetica">
161 <fo:block keep-with-next.within-column="always">
162 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Introduction</fo:block>
163 </fo:block>
164 </fo:block>
165 </fo:block>
166 <fo:block id="gdp">
167 <fo:block>
168 <fo:block margin-left="-4pc" font-family="Helvetica">
169 <fo:block keep-with-next.within-column="always">
170 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">The GNOME Documentation Project</fo:block>
171 </fo:block>
172 </fo:block>
173 </fo:block>
174 <fo:block id="goals">
175 <fo:block>
176 <fo:block margin-left="-4pc" font-family="Helvetica">
177 <fo:block keep-with-next.within-column="always">
178 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Goals</fo:block>
179 </fo:block>
180 </fo:block>
181 </fo:block>
182 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
183 The GNOME Documentation Project (GDP) aims to provide GNOME
184 and GNOME applications with a complete, intuitive, and clear
185 documentation system. At the center of the GDP is the
186 GNOME Help Browser, which
187 presents a unified interface to GNOME-specific documentation
188 as well as other Linux documentation such as man pages and
189 texinfo documents. The GNOME Help System provides a
190 comprehensive view of documentation on a machine by
191 dynamically assembling the documentation of GNOME
192 applications and components which are installed. The GDP is
193 responsible for writing numerous GNOME-related documents,
194 both for developers and for users. Developer documentation
195 includes <fo:basic-link external-destination="http://developer.gnome.org/doc/API/">APIs for the GNOME libraries</fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/doc/API/]</fo:inline>, <fo:basic-link external-destination="http://developer.gnome.org/doc/whitepapers/"><fo:inline font-style="italic">GNOME White
196 Papers</fo:inline></fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/doc/whitepapers/]</fo:inline>, GNOME developer <fo:basic-link external-destination="http://developer.gnome.org/doc/tutorials/">tutorials</fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/doc/tutorials/]</fo:inline>, the <fo:basic-link external-destination="http://developer.gnome.org/doc/FAQ/"><fo:inline font-style="italic">GNOME Developer
197 FAQ</fo:inline></fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/doc/FAQ/]</fo:inline>, the <fo:basic-link external-destination="http://developer.gnome.org">GNOME
198 Developer's Website</fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org]</fo:inline>, and <fo:inline font-style="italic">GNOME
199 Handbook</fo:inline>'s, such as the one you are reading.
200 User documentation include the <fo:basic-link external-destination="http://www.gnome.org/learn/"><fo:inline font-style="italic">GNOME User's
201 Guide</fo:inline></fo:basic-link><fo:inline hyphenate="false"> [http://www.gnome.org/learn/]</fo:inline>, the <fo:basic-link external-destination="http://www.gnome.org/learn/"><fo:inline font-style="italic">GNOME FAQ</fo:inline></fo:basic-link><fo:inline hyphenate="false"> [http://www.gnome.org/learn/]</fo:inline>, and
202 GNOME application documentation. Most GNOME applications
203 have their own manual in addition to context sensitive help.
204 </fo:block>
205 </fo:block>
206 <fo:block id="joining">
207 <fo:block>
208 <fo:block margin-left="-4pc" font-family="Helvetica">
209 <fo:block keep-with-next.within-column="always">
210 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Joining the GDP</fo:block>
211 </fo:block>
212 </fo:block>
213 </fo:block>
214 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
215 Documenting GNOME and all the numerous GNOME applications is
216 a very large project. The GDP is always looking for people
217 to help write, update, and edit documentation. If you are
218 interested in joining the GDP team, you should join the
219 <fo:basic-link external-destination="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
220 <fo:inline font-style="italic">gnome-doc-list mailing list</fo:inline> </fo:basic-link><fo:inline hyphenate="false"> [http://mail.gnome.org/mailman/listinfo/gnome-doc-list/]</fo:inline>.
221 Read <fo:basic-link internal-destination="gettingstarted">the section called “Getting Started Writing GNOME Documentation”</fo:basic-link>, for help selecting a
222 project to work on. Feel free to introduce yourself on the
223 gnome-doc-list mailing list and indicate which project you
224 intend to work on, or else ask for suggestions of important
225 documents which need work done. You may also want to join the
226 #docs IRC channel on irc.gnome.org to meet other GDP members
227 and discuss any questions you may have. For a list of GDP
228 projects and members, see the
229 <fo:basic-link external-destination="http://developer.gnome.org/projects/gdp">
230 <fo:inline font-style="italic">GDP Website</fo:inline></fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/projects/gdp]</fo:inline>.
231 </fo:block>
232 </fo:block>
233 <fo:block id="collaborating">
234 <fo:block>
235 <fo:block margin-left="-4pc" font-family="Helvetica">
236 <fo:block keep-with-next.within-column="always">
237 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Collaborating with the GDP</fo:block>
238 </fo:block>
239 </fo:block>
240 </fo:block>
241 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
242 GNOME developers, packagers, and translators may not be
243 writing GNOME documentation but will want to understand how
244 the GNOME documentation system works and will need to
245 collaborate with GDP members. This document should help to
246 outline the structure of how the GNOME documentation system
247 works. Developers who do not write the documentation for
248 their applications are encouraged to find a GDP member to
249 write the documentation. This is best done by sending an
250 email to the <fo:basic-link external-destination="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
251 <fo:inline font-style="italic">gnome-doc-list mailing list</fo:inline> </fo:basic-link><fo:inline hyphenate="false"> [http://mail.gnome.org/mailman/listinfo/gnome-doc-list/]</fo:inline>
252 describing the application, where it can be downloaded from,
253 and that the developer(s) would like a GDP member to write
254 documentation for the application. The #docs IRC channel on
255 irc.gnome.org is another option for contacting GDP members.
256 </fo:block>
257 </fo:block>
258 </fo:block>
259 <fo:block id="notation">
260 <fo:block>
261 <fo:block margin-left="-4pc" font-family="Helvetica">
262 <fo:block keep-with-next.within-column="always">
263 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Notation and Conventions</fo:block>
264 </fo:block>
265 </fo:block>
266 </fo:block>
267 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
268 This Handbook uses the following notation:
269 <fo:table><fo:table-column column-number="1"/><fo:table-column column-number="2"/><fo:table-body><fo:table-row><fo:table-cell><fo:block><fo:inline font-family="Courier">/usr/bin</fo:inline></fo:block></fo:table-cell><fo:table-cell><fo:block>
270 Directory
271 </fo:block></fo:table-cell></fo:table-row><fo:table-row><fo:table-cell><fo:block><fo:inline font-family="Courier">foo.sgml</fo:inline></fo:block></fo:table-cell><fo:table-cell><fo:block>
272 Filename
273 </fo:block></fo:table-cell></fo:table-row><fo:table-row><fo:table-cell><fo:block><fo:inline font-weight="bold">command</fo:inline></fo:block></fo:table-cell><fo:table-cell><fo:block>
274 Command or text that would be typed.
275 </fo:block></fo:table-cell></fo:table-row><fo:table-row><fo:table-cell><fo:block><fo:inline font-weight="bold"><fo:inline font-style="italic" font-family="Courier">replaceable</fo:inline></fo:inline></fo:block></fo:table-cell><fo:table-cell><fo:block>
276 "Variable" text that can be replaced.
277 </fo:block></fo:table-cell></fo:table-row><fo:table-row><fo:table-cell><fo:block><fo:inline font-family="Courier">Program or Doc Code</fo:inline></fo:block></fo:table-cell><fo:table-cell><fo:block>Program or document code</fo:block></fo:table-cell></fo:table-row></fo:table-body></fo:table>
278 </fo:block>
279 </fo:block>
280 <fo:block id="about">
281 <fo:block>
282 <fo:block margin-left="-4pc" font-family="Helvetica">
283 <fo:block keep-with-next.within-column="always">
284 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">About This Handbook</fo:block>
285 </fo:block>
286 </fo:block>
287 </fo:block>
288 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
289 This Handbook is a guide for both writing documentation for
290 GNOME components and applications and for properly binding and
291 packaging documentation into GNOME applications.
292 </fo:block>
293 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
294 This Handbook, like all GNOME documentation, was written in
295 DocBook(SGML) and is available in several formats including
296 SGML, HTML, PostScript, and PDF. For the latest version, see
297 <fo:basic-link external-destination="http://developer.gnome.org/projects/gdp/handbook.html">
298 <fo:inline font-style="italic">Getting The GNOME Handbook of Writing Software
299 Documentation</fo:inline> </fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/projects/gdp/handbook.html]</fo:inline>. Alternately, one may
300 download it anonymously from GNOME CVS under <fo:inline font-family="Courier">gnome-docu/gdp</fo:inline>.
301 </fo:block>
302 </fo:block>
303 </fo:block>
304 <fo:block id="gettingstarted">
305 <fo:block>
306 <fo:block margin-left="-4pc" font-family="Helvetica">
307 <fo:block keep-with-next.within-column="always">
308 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Getting Started Writing GNOME Documentation</fo:block>
309 </fo:block>
310 </fo:block>
311 </fo:block>
312 <fo:block id="selecting">
313 <fo:block>
314 <fo:block margin-left="-4pc" font-family="Helvetica">
315 <fo:block keep-with-next.within-column="always">
316 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Selecting A Document</fo:block>
317 </fo:block>
318 </fo:block>
319 </fo:block>
320 <fo:block id="know">
321 <fo:block>
322 <fo:block margin-left="-4pc" font-family="Helvetica">
323 <fo:block keep-with-next.within-column="always">
324 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Document Something You Know</fo:block>
325 </fo:block>
326 </fo:block>
327 </fo:block>
328 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
329 The most frequently asked question of new contributors who
330 join the GDP is "which document should I start
331 with?". Because most people involved are volunteers, we do
332 not <fo:inline font-style="italic">assign</fo:inline> projects and applications to
333 write documents for. The first step is all yours - you must
334 decide what about GNOME interests you most and find out if
335 it has complete documents or not.
336 </fo:block>
337 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
338 It is also important to spend some time with GNOME to make
339 sure you are familiar enough with it to be
340 <fo:inline font-style="italic">authoritative</fo:inline> in your writing. The
341 best way to do this is to just sit down and play with GNOME
342 as much as possible before starting to write.
343 </fo:block>
344 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
345 The easiest way to get started is to improve existing
346 documentation. If you notice some inaccuracies or omissions
347 in the documentation, or you think that you can explain the
348 material more clearly, just send your suggestions to the
349 author of the original documentation or to the GNOME
350 documentation project at <fo:inline font-family="Courier">&lt;[email protected]&gt;</fo:inline>.
351 </fo:block>
352 </fo:block>
353 <fo:block id="doctable">
354 <fo:block>
355 <fo:block margin-left="-4pc" font-family="Helvetica">
356 <fo:block keep-with-next.within-column="always">
357 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">The GNOME Documentation Status Table</fo:block>
358 </fo:block>
359 </fo:block>
360 </fo:block>
361 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
362 The <fo:inline font-style="italic">GDP Documentation Status Table</fo:inline>
363 (<fo:inline font-style="italic">DocTable</fo:inline>) (<fo:basic-link external-destination="http://www.gnome.org/gdp/doctable/">http://www.gnome.org/gdp/doctable/</fo:basic-link><fo:inline hyphenate="false"> [http://www.gnome.org/gdp/doctable/]</fo:inline>) is a
364 web page which tracks the status of all the various
365 documentation components of GNOME. These components include
366 application documentation, internal GNOME component
367 documentation, user documentation, and developer
368 documentation. For each documentation item, it tracks the
369 current status of the documentation, who is working on the
370 particular document, where the documentation can be found,
371 and provides a forum for the discussion of each item.
372 </fo:block>
373 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
374 You should use the <fo:inline font-style="italic">DocTable</fo:inline> to help
375 you select a documentation item which needs work done. Once
376 you have selected an item to work on, please register
377 yourself as an author so that other authors do not duplicate
378 your work and may contact you to help or offer suggestions.
379 Also be sure to keep the status icons up-to-date so that
380 the GDP team can easily identify which items need additional
381 help. The <fo:inline font-style="italic">DocTable</fo:inline> also allows
382 people to make announcements and suggestions and to discuss
383 issues in the comments section.
384 </fo:block>
385 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348418272">
386 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">Note</fo:block>
387 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
388 Note that the information in the
389 <fo:inline font-style="italic">DocTable</fo:inline> may not always be up-to-date
390 or accurate. When you assign yourself to documenting an
391 application, make sure you find out the latest status of
392 documentation by contacting the application author.
393 </fo:block>
394 </fo:block>
395 </fo:block>
396 </fo:block>
397 <fo:block id="docbook">
398 <fo:block>
399 <fo:block margin-left="-4pc" font-family="Helvetica">
400 <fo:block keep-with-next.within-column="always">
401 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Installing and Using DocBook</fo:block>
402 </fo:block>
403 </fo:block>
404 </fo:block>
405 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
406 All documentation for the GNOME project is written in SGML
407 using the DocBook DTD. There are many advantages to using
408 this for documentation, not least of which is the single
409 source nature of SGML. To contribute to the GDP you should
410 learn to use DocBook.
411 </fo:block>
412 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348423072">
413 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">NOTE</fo:block>
414 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
415 To get started writing for the GDP you do not need to rush
416 out and learn DocBook - if you feel it is too much to handle
417 for now, you can submit plain ASCII text to the <fo:basic-link external-destination="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
418 <fo:inline font-style="italic">gnome-doc-list mailing list</fo:inline>
419 </fo:basic-link><fo:inline hyphenate="false"> [http://mail.gnome.org/mailman/listinfo/gnome-doc-list/]</fo:inline>and a volunteer will mark it up for you. Seeing your
420 document marked up will also be a great way for you to start
421 learning DocBook.
422 </fo:block>
423 </fo:block>
424 <fo:block id="installingdocbook">
425 <fo:block>
426 <fo:block margin-left="-4pc" font-family="Helvetica">
427 <fo:block keep-with-next.within-column="always">
428 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Installing DocBook</fo:block>
429 </fo:block>
430 </fo:block>
431 </fo:block>
432 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
433 Download and install the following <fo:basic-link external-destination="ftp://sourceware.cygnus.com:/pub/docbook-tools/">DocBook Tools packages</fo:basic-link><fo:inline hyphenate="false"> [ftp://sourceware.cygnus.com:/pub/docbook-tools/]</fo:inline>: jade, docbook,
434 jadetex, sgml-common, and stylesheets. (RPM users should note
435 that jade is platform dependent (eg. i386), while the other packages
436 are in the <fo:inline font-family="Courier">noarch</fo:inline>
437 directory.) You can find more
438 information on DocBook Tools <fo:basic-link external-destination="http://sourceware.cygnus.com/docbook-tools/">here</fo:basic-link><fo:inline hyphenate="false"> [http://sourceware.cygnus.com/docbook-tools/]</fo:inline>.
439 </fo:block>
440 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
441 If you are an Emacs user you may
442 want to grab the psgml package as well. This is a major mode
443 for editing sgml files in Emacs.
444 </fo:block>
445 </fo:block>
446 <fo:block id="gdpstylesheets">
447 <fo:block>
448 <fo:block margin-left="-4pc" font-family="Helvetica">
449 <fo:block keep-with-next.within-column="always">
450 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">GDP Stylesheets</fo:block>
451 </fo:block>
452 </fo:block>
453 </fo:block>
454 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
455 The GDP uses its own DocBook stylesheets. To use the GDP
456 stylesheets, you should download the file
457 <fo:inline font-family="Courier">gdp-both.dsl</fo:inline> from the <fo:inline font-family="Courier">gnome-docu/gdp/dsssl</fo:inline> module in
458 CVS (or from <fo:basic-link external-destination="http://developer.gnome.org/projects/gdp/stylesheets.html">
459 GDP Custom DSSSL Stylesheet</fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/projects/gdp/stylesheets.html]</fo:inline>)and copy it
460
461 over the file
462 <fo:inline font-family="Courier">/usr/lib/sgml/stylesheets/cygnus-both.dsl</fo:inline>.
463 Alternately, you can download and install the
464 <fo:basic-link external-destination="http://people.redhat.com/dcm/software.html">gnome-doc-tools package</fo:basic-link><fo:inline hyphenate="false"> [http://people.redhat.com/dcm/software.html]</fo:inline> which will set
465 up the stylesheets as well as the DTD discussed below.
466 </fo:block>
467 </fo:block>
468 <fo:block id="gdpdtd">
469 <fo:block>
470 <fo:block margin-left="-4pc" font-family="Helvetica">
471 <fo:block keep-with-next.within-column="always">
472 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">GDP DTD (PNG Image Support)</fo:block>
473 </fo:block>
474 </fo:block>
475 </fo:block>
476 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
477 Due to some license issues involved with the creation of
478 gifs, the GNOME Documentation Project has decided to use the
479 PNG image format for all images in GNOME documentation. You
480 can read more about the issues involved with gifs at <fo:basic-link external-destination="http://www.gnu.org/philosophy/gif.html">http://www.gnu.org/philosophy/gif.html</fo:basic-link><fo:inline hyphenate="false"> [http://www.gnu.org/philosophy/gif.html]</fo:inline>.
481 </fo:block>
482 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
483 The current DocBook DTD(3.1) does not include support for
484 embedding PNG images in your documents. Since the GDP uses
485 many screenshots in its documentation, we use our own
486 variation on the DocBook DTD which has PNG image support.
487 We encourage everybody to use this DTD instead of the
488 default DocBook DTD since your source document header and
489 your output document appearance subtly vary between the two
490 DTD's. To install the GDP custom DTD with PNG image support
491 by hand:
492 </fo:block>
493 <fo:list-block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348443424" provisional-distance-between-starts="1.5em" provisional-label-separation="0.2em">
494 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348444000">
495 <fo:list-item-label end-indent="label-end()">
496 <fo:block>•</fo:block>
497 </fo:list-item-label>
498 <fo:list-item-body start-indent="body-start()">
499 <fo:block>
500 Download <fo:basic-link external-destination="http://www.labs.redhat.com/png/png-support.html">the
501 GDP DocBook DTD for PNG support</fo:basic-link><fo:inline hyphenate="false"> [http://www.labs.redhat.com/png/png-support.html]</fo:inline> and install it
502 where you keep your DTD's. (On Red Hat use <fo:inline font-family="Courier">/usr/lib/sgml/</fo:inline>.) Note that
503 the 3.0 DTD is missing support for the
504 <fo:inline font-family="Courier">&lt;legalnotice&gt;</fo:inline> tag, so it is
505 recommended that you use version 3.1
506 </fo:block>
507 </fo:list-item-body>
508 </fo:list-item>
509 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348447456">
510 <fo:list-item-label end-indent="label-end()">
511 <fo:block>•</fo:block>
512 </fo:list-item-label>
513 <fo:list-item-body start-indent="body-start()">
514 <fo:block>
515 Add the new DTD to your SGML CATALOG file. The location
516 of your SGML CATALOG file may vary depending upon your
517 distribution. (On Red Hat it is usually in
518 /usr/lib/sgml/CATALOG.) Add the following line to this
519 file:
520 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
521 PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd"
522 </fo:block>
523 If you are using the 3.1 DTD, use:
524 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
525 PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd"
526 </fo:block>
527 </fo:block>
528 </fo:list-item-body>
529 </fo:list-item>
530 </fo:list-block>
531 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
532 Alternately, you can download and install the
533 <fo:basic-link external-destination="http://people.redhat.com/dcm/software.html">gnome-doc-tools package</fo:basic-link><fo:inline hyphenate="false"> [http://people.redhat.com/dcm/software.html]</fo:inline> which will set
534 up the custom stylesheets and DTD for you.
535 </fo:block>
536 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
537 To include PNG files in your documents, you will need to
538 indicate that you are using this special DTD. To do
539 this, use the following headers:
540 </fo:block>
541 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
542 Articles:
543 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
544 &lt;!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant
545 V1.1//EN"[]&gt;
546 </fo:block>
547 </fo:block>
548 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
549 Books:
550 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
551 &lt;!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant
552 V1.1//EN"[]&gt;
553 </fo:block>
554 </fo:block>
555 </fo:block>
556 <fo:block id="editors">
557 <fo:block>
558 <fo:block margin-left="-4pc" font-family="Helvetica">
559 <fo:block keep-with-next.within-column="always">
560 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Editors</fo:block>
561 </fo:block>
562 </fo:block>
563 </fo:block>
564 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
565 There are many editors on Linux and UNIX systems available
566 to you. Which editor you use to work on the sgml documents
567 is completely up to you, as long as the editor is able to
568 preserve sgml and produce the source in a format that is
569 readable by everyone.
570 </fo:block>
571 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
572 Probably the two most popular editors available are
573 Emacs and
574 vi. These and other editors are
575 used regularly by members of the GDP. Emacs has a major
576 mode, psgml, for editing sgml files which can save you time
577 and effort in adding and closing tags. You will find the
578 psgml package in DocBook Tools, which is the standard set of
579 tools for the GDP. You may find out more about DocBook Tools
580 in <fo:basic-link internal-destination="installingdocbook">the section called “Installing DocBook”</fo:basic-link>.
581 </fo:block>
582 </fo:block>
583 <fo:block id="make-output">
584 <fo:block>
585 <fo:block margin-left="-4pc" font-family="Helvetica">
586 <fo:block keep-with-next.within-column="always">
587 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Creating Something Useful with your Docs</fo:block>
588 </fo:block>
589 </fo:block>
590 </fo:block>
591 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
592 The tools available in DocBook Tools allow you to convert
593 your sgml document to many different formats including html
594 and Postscript. The primary tool used to do the conversion
595 is an application called Jade. In
596 most cases you will not have to work directly with
597 Jade; Instead, you will use the
598 scripts provided by DocBook Tools.
599 </fo:block>
600 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
601 To preview your DocBook document, it is easiest to convert
602 it to <fo:inline font-family="Courier">html</fo:inline>. If you have installed the
603 DocBook tools described above, all you have to do is to run
604 the command <fo:inline font-family="Courier">$</fo:inline><fo:inline font-weight="bold">db2html
605 mydocument.sgml</fo:inline>. If there are no sgml syntax
606 errors, this will create a directory <fo:inline font-family="Courier">mydocument</fo:inline> and place the
607 resulting html files in it. The title page of the document
608 will typically be
609 <fo:inline font-family="Courier">mydocument/index.html</fo:inline>. If you have
610 screenshots in your document, you will have to copy these
611 files into the <fo:inline font-family="Courier">mydocument</fo:inline> directory by
612 hand. You can use any web browser to view your document.
613 Note that every time you run <fo:inline font-weight="bold">db2html</fo:inline>, it
614 creates the <fo:inline font-family="Courier">mydocument</fo:inline> directory over, so
615 you will have to copy the screenshots over each time.
616 </fo:block>
617 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
618 You can also convert your document to PostScript by running
619 the command <fo:inline font-family="Courier">$</fo:inline><fo:inline font-weight="bold">db2ps
620 mydocument.sgml</fo:inline>, after which you can print out or
621 view the resulting .ps file.
622 </fo:block>
623 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348464736">
624 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">NOTE</fo:block>
625 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
626 The html files you get will not look quite the same as the
627 documentation distributed with GNOME unless you have the
628 custom stylesheets installed on your machine. DocBook
629 Tools' default stylesheets will produce a different look
630 to your docs. You can read more about the GDP stylesheets
631 in <fo:basic-link internal-destination="gdpstylesheets">the section called “GDP Stylesheets”</fo:basic-link>.
632 </fo:block>
633 </fo:block>
634 </fo:block>
635 <fo:block id="jadeimages">
636 <fo:block>
637 <fo:block margin-left="-4pc" font-family="Helvetica">
638 <fo:block keep-with-next.within-column="always">
639 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Images in DocBook Tools</fo:block>
640 </fo:block>
641 </fo:block>
642 </fo:block>
643 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
644 If your document uses images you will need to take note of a
645 few things that should take place in order for you to make
646 use of those images in your output.
647 </fo:block>
648 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
649 The DocBook Tools scripts and applications are smart enough
650 to know that when you are creating html you will be using
651 PNG files and when you are creating Postscript you will be
652 using EPS files (you must use EPS with Postscript).
653 </fo:block>
654 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
655 Thus, you should never explicitly
656 include the extension of the image file, since DocBook
657 Tools will automatically insert it for you. For example:
658 </fo:block>
659 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
660
661 &lt;figure&gt;
662 &lt;title&gt;My Image&lt;/title&gt;
663 &lt;screenshot&gt;
664 &lt;screeninfo&gt;Sample GNOME Display&lt;/screeninfo&gt;
665 &lt;graphic format="png" fileref="myfile" srccredit="me"&gt;
666 &lt;/graphic&gt;
667 &lt;/screenshot&gt;
668 &lt;/figure&gt;
669 </fo:block>
670 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
671 You will notice in this example that the file
672 <fo:inline font-family="Courier">myfile.png</fo:inline> was referred to as simply
673 <fo:inline font-family="Courier">myfile</fo:inline>. Now when you run
674 <fo:inline font-weight="bold">db2html</fo:inline> to create an html file, it will
675 automatically look for <fo:inline font-family="Courier">myfile.png</fo:inline> in
676 the directory.
677 </fo:block>
678 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
679 If you want to create PostScript output, you will need to create an
680 EPS version of your image file to be displayed in the
681 PostScript file. There is a simple script available which
682 allows you to change a PNG image into an EPS file
683 easily. You can download this file - img2eps - from <fo:basic-link external-destination="http://people.redhat.com/dcm/sgml.html">http://people.redhat.com/dcm/sgml.html</fo:basic-link><fo:inline hyphenate="false"> [http://people.redhat.com/dcm/sgml.html]</fo:inline>
684 (look for the img2eps section). Note that this script is
685 included in the gnome-doc-tools package, so if you are using
686 this package, you should already have
687 <fo:inline font-weight="bold">img2eps</fo:inline> on you system.
688 </fo:block>
689 </fo:block>
690 <fo:block id="moredocbookinfo">
691 <fo:block>
692 <fo:block margin-left="-4pc" font-family="Helvetica">
693 <fo:block keep-with-next.within-column="always">
694 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Learning DocBook</fo:block>
695 </fo:block>
696 </fo:block>
697 </fo:block>
698 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
699 There are many resources available to help you learn DocBook.
700 The following resources on the web are useful for learning
701 DocBook:
702 </fo:block>
703 <fo:list-block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348478752" provisional-distance-between-starts="1.5em" provisional-label-separation="0.2em">
704 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348479328">
705 <fo:list-item-label end-indent="label-end()">
706 <fo:block>•</fo:block>
707 </fo:list-item-label>
708 <fo:list-item-body start-indent="body-start()">
709 <fo:block>
710 <fo:basic-link external-destination="http://www.docbook.org">http://www.docbook.org</fo:basic-link><fo:inline hyphenate="false"> [http://www.docbook.org]</fo:inline> - Norman
711 Walsh's <fo:inline font-style="italic">DocBook: The Definitive
712 Guide</fo:inline>. Online O'Reilly book on using
713 DocBook. Contains an excellent element reference. May be
714 too formal for a beginner.
715 </fo:block>
716 </fo:list-item-body>
717 </fo:list-item>
718 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348482016">
719 <fo:list-item-label end-indent="label-end()">
720 <fo:block>•</fo:block>
721 </fo:list-item-label>
722 <fo:list-item-body start-indent="body-start()">
723 <fo:block>
724 <fo:basic-link external-destination="http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html">A Practical Introduction to DocBook</fo:basic-link><fo:inline hyphenate="false"> [http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html]</fo:inline>
725 - The Open Source Writers Group's introduction to using
726 DocBook. This is an excellent HOW-TO type article on
727 getting started.
728 </fo:block>
729 </fo:list-item-body>
730 </fo:list-item>
731 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348484128">
732 <fo:list-item-label end-indent="label-end()">
733 <fo:block>•</fo:block>
734 </fo:list-item-label>
735 <fo:list-item-body start-indent="body-start()">
736 <fo:block>
737 <fo:basic-link external-destination="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Getting Going with DocBook: Notes for
738 Hackers</fo:basic-link><fo:inline hyphenate="false"> [http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html]</fo:inline> - Mark Galassi's introduction to DocBook
739 for hackers. This has to be one of the first
740 introductions to DocBook ever - still as good as it ever
741 was.
742 </fo:block>
743 </fo:list-item-body>
744 </fo:list-item>
745 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348486240">
746 <fo:list-item-label end-indent="label-end()">
747 <fo:block>•</fo:block>
748 </fo:list-item-label>
749 <fo:list-item-body start-indent="body-start()">
750 <fo:block>
751 <fo:basic-link external-destination="http://www.freebsd.org/tutorials/docproj-primer/">
752 FreeBSD Documentation Project Primer for New
753 Contributors</fo:basic-link><fo:inline hyphenate="false"> [http://www.freebsd.org/tutorials/docproj-primer/]</fo:inline> - FreeBSD documentation project
754 primer. Chapter 4.2 provides a very good introduction to
755 writing documentation using DocBook. Note that it also
756 describes some custom extensions of DocBook;
757 fortunately, they are clearly marked as such.
758 </fo:block>
759 </fo:list-item-body>
760 </fo:list-item>
761 </fo:list-block>
762 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
763 Norman Walsh's book is also available in print.
764 </fo:block>
765 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
766 The following sections of this document are designed to help
767 documentation authors write correct and consistent DocBook:
768 </fo:block>
769 <fo:list-block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348489696" provisional-distance-between-starts="1.5em" provisional-label-separation="0.2em">
770 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348490272">
771 <fo:list-item-label end-indent="label-end()">
772 <fo:block>•</fo:block>
773 </fo:list-item-label>
774 <fo:list-item-body start-indent="body-start()">
775 <fo:block>
776 <fo:basic-link internal-destination="docbookbasics">the section called “DocBook Basics ”</fo:basic-link> - Descriptions of
777 commonly used DocBook tags.
778 </fo:block>
779 </fo:list-item-body>
780 </fo:list-item>
781 </fo:list-block>
782 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
783 You may also discuss specific DocBook questions with GDP
784 members on the #docs IRC channel at irc.gnome.org and on the
785 gnome-doc-list mailing list.
786 </fo:block>
787 </fo:block>
788 </fo:block>
789 <fo:block id="gdptemplates">
790 <fo:block>
791 <fo:block margin-left="-4pc" font-family="Helvetica">
792 <fo:block keep-with-next.within-column="always">
793 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">GDP Document Templates</fo:block>
794 </fo:block>
795 </fo:block>
796 </fo:block>
797 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
798 Templates for various types of GNOME documents are found in
799 <fo:basic-link internal-destination="templates">Appendix A. Document Templates</fo:basic-link>. They are kept in CVS in
800 gnome-docu/gdp/templates. The easiest source to get them from
801 is probably the <fo:basic-link external-destination="http://developer.gnome.org/projects/gdp/templates.html">GDP
802 Document Templates</fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/projects/gdp/templates.html]</fo:inline> web page, which is typically kept
803 completely up-to-date with CVS and has a basic description of
804 each file from CVS.
805 </fo:block>
806 </fo:block>
807 <fo:block id="screenshots">
808 <fo:block>
809 <fo:block margin-left="-4pc" font-family="Helvetica">
810 <fo:block keep-with-next.within-column="always">
811 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Screenshots</fo:block>
812 </fo:block>
813 </fo:block>
814 </fo:block>
815 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
816 Most GNOME documents will have screenshots of the particular
817 applet, application, GNOME component, or widget being
818 discussed. As discussed above in <fo:basic-link internal-destination="gdpdtd">the section called “GDP DTD (PNG Image Support)”</fo:basic-link> you
819 will need to install the special GDP DocBook DTD which
820 supports PNG images, the format used for all images in GNOME
821 documentation. For the basic DocBook structure used to insert
822 images in a document, see <fo:basic-link internal-destination="jadeimages">the section called “Images in DocBook Tools”</fo:basic-link> above.
823 </fo:block>
824 <fo:block id="screenshotappearance">
825 <fo:block>
826 <fo:block margin-left="-4pc" font-family="Helvetica">
827 <fo:block keep-with-next.within-column="always">
828 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Screenshot Appearance</fo:block>
829 </fo:block>
830 </fo:block>
831 </fo:block>
832 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
833 For all screenshots of windows that typically have border
834 decorations (e.g. applications and dialogs, but not applets
835 in a panel), GDP standards dictate
836 the appearance of the window. (This is to minimize possible
837 confusion to the reader, improve the appearance of GNOME
838 documents, and guarantee the screenshot is readable when
839 printed.) All screenshots should be taken with the SawFish
840 (formerly known as Sawmill) window manager using the
841 MicroGui theme and Helvetica 12pt font. (A different window
842 manager can be used provided the MicroGui theme is available
843 for this window manager and the appearance is identical to
844 that when using the SawFish window manager.) The default
845 GTK+ theme(gtk) and font (Helvetica 12 pt) should be used
846 for all screenshots. If you are unable to provide
847 screenshots in this form, you should create screenshots as
848 you wish them to appear and send them to the
849 <fo:basic-link external-destination="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
850 <fo:inline font-style="italic">gnome-doc-list mailing list</fo:inline> </fo:basic-link><fo:inline hyphenate="false"> [http://mail.gnome.org/mailman/listinfo/gnome-doc-list/]</fo:inline>
851 requesting a GDP member reproduce these screenshots in the
852 correct format and email them to you.
853 </fo:block>
854 </fo:block>
855 <fo:block id="screenshottools">
856 <fo:block>
857 <fo:block margin-left="-4pc" font-family="Helvetica">
858 <fo:block keep-with-next.within-column="always">
859 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Screenshot Tools</fo:block>
860 </fo:block>
861 </fo:block>
862 </fo:block>
863 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
864 There are many tools for taking screenshots in
865 GNOME/Linux. Perhaps the most convenient is the
866 Screen-Shooter Applet. Just click
867 on the window icon in the applet and then on the window you
868 would like to take a screenshot of. (Note that
869 at the time of this writing, PNG images taken by
870 screenshooter do not appear properly in
871 Netscape or the
872 GNOME Help Browser. You
873 should save your screenshot as a GIF and
874 then use <fo:inline font-weight="bold">convert filename.gif
875 filename.png</fo:inline>.) For applets
876 in a Panel,
877 xv can be used to crop the
878 screenshot to only include the relevant portion of the
879 Panel. Note that
880 xv and
881 gimp can both be used for taking
882 screenshots, cropping screenshots, and converting image
883 formats.
884 </fo:block>
885 </fo:block>
886 <fo:block id="screenshotfiles">
887 <fo:block>
888 <fo:block margin-left="-4pc" font-family="Helvetica">
889 <fo:block keep-with-next.within-column="always">
890 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Screenshot Files</fo:block>
891 </fo:block>
892 </fo:block>
893 </fo:block>
894 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
895 Screenshots should be kept in the main documentation
896 directory with your SGML file for applets, or should be
897 kept in a directory called "figs" for application and other
898 documentation. After you use <fo:inline font-weight="bold">db2html</fo:inline> to
899 convert your SGML file to HTML (see <fo:basic-link internal-destination="make-output">the section called “Creating Something Useful with your Docs”</fo:basic-link>), you will need to copy your
900 screenshots (either the individual PNG files for applet
901 documentation, or the whole "figs" directory for other
902 documentation) into the newly created HTML directory. Note
903 that every time you use <fo:inline font-weight="bold">db2html</fo:inline> the HTML
904 directory is erased and rewritten, so do not store your only
905 copy of the screenshots in that directory. If you wish to
906 create PostScript or PDF output, you will need to manually
907 convert the PNG images to EPS as described in <fo:basic-link internal-destination="jadeimages">the section called “Images in DocBook Tools”</fo:basic-link>, but will not need to copy these
908 images from their default location, as they are included
909 directly into the output(PostScript of PDF) file.
910 </fo:block>
911 </fo:block>
912 </fo:block>
913 <fo:block id="applicationbugs">
914 <fo:block>
915 <fo:block margin-left="-4pc" font-family="Helvetica">
916 <fo:block keep-with-next.within-column="always">
917 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Application Bugs</fo:block>
918 </fo:block>
919 </fo:block>
920 </fo:block>
921 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
922 Documentation authors tend to investigate and test applets and
923 applications more thoroughly than most
924 users. Often documentation authors will discover one or
925 more bugs in the software. These bugs vary from small ones,
926 such as mis-spelled words or missing
927 About dialogs in the menu, to large
928 ones which cause the applet to crash. As all users, you
929 should be sure to report these bugs so that application
930 developers know of them and can fix them. The easiest way to
931 submit a bug report is by using the Bug
932 Buddy applet which is part of the gnome-applets
933 package.
934 </fo:block>
935 </fo:block>
936 <fo:block id="cvs">
937 <fo:block>
938 <fo:block margin-left="-4pc" font-family="Helvetica">
939 <fo:block keep-with-next.within-column="always">
940 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Using CVS</fo:block>
941 </fo:block>
942 </fo:block>
943 </fo:block>
944 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
945 CVS (Concurrent Versions System) is a tool that allows
946 multiple developers to concurrently work on a set of
947 documents, keeping track of the modifications made by each
948 person. The files are stored on a server and each developer
949 checks files out, modifies them, and then checks in their
950 modified version of the files. Many GNOME programs and
951 documents are stored in CVS. The GNOME CVS server allows
952 users to anonymously check out CVS files. Most GDP members
953 will need to use anonymous CVS to download the most up-to-date
954 version of documentation or programs. Modified documents will
955 typically be emailed to the the application developer. Core
956 GDP members may also be granted login CVS privileges so they
957 may commit modified files directly to CVS.
958 </fo:block>
959 <fo:block id="anonymouscvs">
960 <fo:block>
961 <fo:block margin-left="-4pc" font-family="Helvetica">
962 <fo:block keep-with-next.within-column="always">
963 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Anonymous CVS</fo:block>
964 </fo:block>
965 </fo:block>
966 </fo:block>
967 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
968 To anonymously check out documents from CVS, you must first
969 log in. From the bash shell, you should set your CVSROOT
970 shell variable with <fo:inline font-weight="bold"> export
971 CVSROOT=':pserver:[email protected]:/cvs/gnome'</fo:inline>
972 and then login with <fo:inline font-weight="bold">cvs login</fo:inline>(there is no
973 password, just hit return). As an example, we will use the
974 "gnome-docu/gdp" module which contains this and several
975 other documents. To check these documents out for the first
976 time, type <fo:inline font-weight="bold">cvs -z3 checkout
977 gnome-docu/gdp</fo:inline>. After you have this document
978 checked out and you would like to download any updates on
979 the CVS server, use <fo:inline font-weight="bold">cvs -z3 update -Pd</fo:inline>.
980 </fo:block>
981 </fo:block>
982 <fo:block id="logincvs">
983 <fo:block>
984 <fo:block margin-left="-4pc" font-family="Helvetica">
985 <fo:block keep-with-next.within-column="always">
986 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Login CVS</fo:block>
987 </fo:block>
988 </fo:block>
989 </fo:block>
990 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> If you have been given a
991 login for the GNOME CVS server, you may commit your file
992 modifications to CVS. Be sure to read the following section
993 on CVS etiquette before making any commits to CVS. To log in
994 to the CVS server as user
995 <fo:inline font-weight="bold"><fo:inline font-style="italic" font-family="Courier">username</fo:inline></fo:inline> with a
996 password, you must first set your CVSROOT shell variable with
997 <fo:inline font-weight="bold"> export
998 CVSROOT=':pserver:<fo:inline font-style="italic" font-family="Courier">username</fo:inline>@cvs.gnome.org:/cvs/gnome'</fo:inline>.
999 Log in with <fo:inline font-weight="bold">cvs login</fo:inline> and enter your
1000 password. You may check out and update modules as described
1001 above for anonymous CVS access. As a login CVS user, you may
1002 also check modified versions of a file into the CVS server.
1003 To check
1004 <fo:inline font-weight="bold"><fo:inline font-style="italic" font-family="Courier">filename</fo:inline></fo:inline> into
1005 the CVS server, type <fo:inline font-weight="bold">cvs -z3 commit
1006 <fo:inline font-style="italic" font-family="Courier">filename</fo:inline></fo:inline>. You will be
1007 given a vi editor window to type in a brief log entry,
1008 summarizing your changes. The default editor can be changed
1009 using the <fo:inline font-family="Courier">EDITOR</fo:inline> environment variable or
1010 with the <fo:inline font-weight="bold"><fo:inline font-family="Courier">-e</fo:inline></fo:inline> option. You
1011 may also check in any modifications to files in the working
1012 directory and subdirectories using <fo:inline font-weight="bold">cvs -z3
1013 commit</fo:inline>. To
1014 add a new file to the CVS server, use <fo:inline font-weight="bold">cvs -z3 add
1015 <fo:inline font-style="italic" font-family="Courier">filename</fo:inline></fo:inline>, followed by the
1016 commit command.
1017 </fo:block>
1018 </fo:block>
1019 <fo:block id="cvsetiquette">
1020 <fo:block>
1021 <fo:block margin-left="-4pc" font-family="Helvetica">
1022 <fo:block keep-with-next.within-column="always">
1023 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">CVS Etiquette</fo:block>
1024 </fo:block>
1025 </fo:block>
1026 </fo:block>
1027 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1028 Because files in CVS are typically used and modified by
1029 multiple developers and documentation authors, users should
1030 exercise a few simple practices out of courtesy towards the
1031 other CVS users and the project leader. First, you should
1032 not make CVS commits to a package without first discussing
1033 your plans with the project leader. This way, the project
1034 leader knows who is modifying the files and generally, what
1035 sort of changes/development is being done. Also, whenever a
1036 CVS user commits a file to CVS, they should make an entry in
1037 the CVS log and in the <fo:inline font-family="Courier">ChangeLog</fo:inline> so
1038 that other users know who is making modifications and what
1039 is being modified. When modifying files created by others,
1040 you should follow the indentation scheme used by the initial
1041 author.
1042 </fo:block>
1043 </fo:block>
1044 </fo:block>
1045 </fo:block>
1046 <fo:block id="gnomedocsystem">
1047 <fo:block>
1048 <fo:block margin-left="-4pc" font-family="Helvetica">
1049 <fo:block keep-with-next.within-column="always">
1050 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">The GNOME Documentation System</fo:block>
1051 </fo:block>
1052 </fo:block>
1053 </fo:block>
1054 <fo:block id="gnomehelpbrowser">
1055 <fo:block>
1056 <fo:block margin-left="-4pc" font-family="Helvetica">
1057 <fo:block keep-with-next.within-column="always">
1058 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">The GNOME Help Browser</fo:block>
1059 </fo:block>
1060 </fo:block>
1061 </fo:block>
1062 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1063 At the core of the GNOME help system is the GNOME
1064 Help Browser. The Help
1065 Browser provides a unified interface to several
1066 distinct documentation systems on Linux/Unix systems: man
1067 pages, texinfo pages, Linux Documentation Project(LDP)
1068 documents, GNOME application documentation, and other GNOME
1069 documents.
1070 </fo:block>
1071 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1072 The GNOME Help Browser works by
1073 searching standard directories for documents which are to be
1074 presented. Thus, the documentation that appears in the GHB is
1075 specific to each computer and will typically only represent
1076 software that is installed on the computer.
1077 </fo:block>
1078 </fo:block>
1079 <fo:block id="gnomehelpbrowser2">
1080 <fo:block>
1081 <fo:block margin-left="-4pc" font-family="Helvetica">
1082 <fo:block keep-with-next.within-column="always">
1083 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">The GNOME Help Browser (GNOME-2.0)</fo:block>
1084 </fo:block>
1085 </fo:block>
1086 </fo:block>
1087 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> In
1088 GNOME 2.0, the GNOME Help Browser
1089 will be replaced by Nautilus.
1090 Nautilus will be the file manager/graphical shell for GNOME 2.0
1091 and will also implement a more sophisticated help system than
1092 that used by the GNOME Help Browser
1093 used in GNOME 1.0. It will read and display DocBook files
1094 directly, avoiding the need for duplicating documents in both
1095 DocBook and HTML formats. Its display engine for DocBook will
1096 be much faster than running jade to
1097 convert to HTML for rendering. Because it uses the original
1098 DocBook source for documentation, it will be possible to do more
1099 sophisticated searching using the meta information included in
1100 the documents. And since Nautilus is a virtual file system
1101 layer which is Internet-capable, it will be able to find and
1102 display documents which are on the web as well as those on the
1103 local file system. For more information on
1104 Nautilus, visit the #nautilus IRC
1105 channel on irc.gnome.org. </fo:block>
1106 </fo:block>
1107 <fo:block id="gnomehelponthefly">
1108 <fo:block>
1109 <fo:block margin-left="-4pc" font-family="Helvetica">
1110 <fo:block keep-with-next.within-column="always">
1111 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Dynamic Document Synthesis(GNOME-2.0)</fo:block>
1112 </fo:block>
1113 </fo:block>
1114 </fo:block>
1115 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1116 GNOME uses the documentation presented by all the various
1117 GNOME components and applications installed on the system to
1118 present a complete and customized documentation environment
1119 describing only components which are currently installed on a
1120 users system. Some of this documentation, such as the manuals
1121 for applets, will be combined in such a way that it appears to
1122 be a single document.
1123 </fo:block>
1124 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1125 By using such a system, you can be sure that any GNOME app you
1126 install that has documentation will show up in the index,
1127 table of contents, any search you do in the help browser.
1128 </fo:block>
1129 </fo:block>
1130 <fo:block id="gnomehelpcomponents">
1131 <fo:block>
1132 <fo:block margin-left="-4pc" font-family="Helvetica">
1133 <fo:block keep-with-next.within-column="always">
1134 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">The GNOME Documentation Components</fo:block>
1135 </fo:block>
1136 </fo:block>
1137 </fo:block>
1138 <fo:block id="applicationmanualsintro">
1139 <fo:block>
1140 <fo:block margin-left="-4pc" font-family="Helvetica">
1141 <fo:block keep-with-next.within-column="always">
1142 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Application Manuals</fo:block>
1143 </fo:block>
1144 </fo:block>
1145 </fo:block>
1146 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1147 Every GNOME application should have an application manual.
1148 An application manual is a document specific to the
1149 particular application which explains the various windows
1150 and features of the application. Application Manuals
1151 typically use screenshots (PNG format) for clarity. Writing
1152 application manuals is discussed in more detail in <fo:basic-link internal-destination="writingapplicationmanuals">the section called “Writing Application and Applet Manuals”</fo:basic-link> below.
1153 </fo:block>
1154 </fo:block>
1155 <fo:block id="applicationhelpintro">
1156 <fo:block>
1157 <fo:block margin-left="-4pc" font-family="Helvetica">
1158 <fo:block keep-with-next.within-column="always">
1159 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Application Help</fo:block>
1160 </fo:block>
1161 </fo:block>
1162 </fo:block>
1163 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1164 Applications should have a Help
1165 button on screens on which users may need help. These
1166 Help buttons should pull up the
1167 default help browser, determined by the
1168 <fo:inline font-family="Courier">ghelp</fo:inline> URL Handler (configured using the
1169 Control Center), typically the
1170 GNOME Help Browser. The help
1171 browser should show either the first page of the application
1172 manual, or else the relevant page thereof. Application help
1173 is described in more detail in <fo:basic-link internal-destination="applicationhelpbuttons">the section called “Application Help Buttons”</fo:basic-link> below.
1174 </fo:block>
1175 </fo:block>
1176 <fo:block id="contextsensitivehelpintro">
1177 <fo:block>
1178 <fo:block margin-left="-4pc" font-family="Helvetica">
1179 <fo:block keep-with-next.within-column="always">
1180 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Application Context Sensitive Help (coming in
1181 GNOME-2.0)</fo:block>
1182 </fo:block>
1183 </fo:block>
1184 </fo:block>
1185 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1186 Context sensitive help is a system which will allow the user
1187 to query any part (button, widget, etc.) of an application
1188 window. This is done by either entering a CS Help mode by
1189 clicking on an icon or by right clicking on the application
1190 part and selecting "What's This" or whatever is decided on
1191 at the time. Context sensitive help is described in more
1192 detail in <fo:basic-link internal-destination="writingcontextsensitivehelp">the section called “Writing Context Sensitive Help (coming in GNOME-2.0)”</fo:basic-link>
1193 below.
1194 </fo:block>
1195 </fo:block>
1196 <fo:block id="userguide">
1197 <fo:block>
1198 <fo:block margin-left="-4pc" font-family="Helvetica">
1199 <fo:block keep-with-next.within-column="always">
1200 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">The GNOME User Guide</fo:block>
1201 </fo:block>
1202 </fo:block>
1203 </fo:block>
1204 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1205 The <fo:inline font-style="italic">GNOME User Guide</fo:inline> describes the
1206 GNOME desktop environment and core components of GNOME such
1207 as the panel and
1208 control center. In GNOME 1.x this
1209 was the main and only source of documentation. In GNOME 2.0
1210 this will become a document for the web and for printing
1211 that is derived from various parts chosen in the system that
1212 are necessary for the new user to understand.
1213 </fo:block>
1214 </fo:block>
1215 <fo:block id="userdocs">
1216 <fo:block>
1217 <fo:block margin-left="-4pc" font-family="Helvetica">
1218 <fo:block keep-with-next.within-column="always">
1219 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">User Documents</fo:block>
1220 </fo:block>
1221 </fo:block>
1222 </fo:block>
1223 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1224 Aside from the <fo:inline font-style="italic">GNOME User Guide</fo:inline>,
1225 there are several other documents to help GNOME users learn
1226 GNOME, including the <fo:inline font-style="italic">GNOME FAQ</fo:inline>,
1227 <fo:inline font-style="italic">GNOME Installation and Configuration
1228 Guide</fo:inline>, and the <fo:inline font-style="italic">GNOME Administrators
1229 Guide</fo:inline>.
1230 </fo:block>
1231 </fo:block>
1232 <fo:block id="developerdocs">
1233 <fo:block>
1234 <fo:block margin-left="-4pc" font-family="Helvetica">
1235 <fo:block keep-with-next.within-column="always">
1236 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Developer Documents</fo:block>
1237 </fo:block>
1238 </fo:block>
1239 </fo:block>
1240 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1241 There are many White Papers, Tutorials, HOWTO's and FAQ's to
1242 make programming GNOME and GNOME applications as easy as
1243 possible.
1244 </fo:block>
1245 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1246 API documentation is also available for the GNOME libraries. This is
1247 detailed documentation of the code that is used to build GNOME
1248 apps. You can keep up with the GNOME API docs on the <fo:basic-link external-destination="http://developer.gnome.org/doc/API/">GNOME API
1249 Reference</fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/doc/API/]</fo:inline> page.
1250 </fo:block>
1251 </fo:block>
1252 <fo:block id="projectdocs">
1253 <fo:block>
1254 <fo:block margin-left="-4pc" font-family="Helvetica">
1255 <fo:block keep-with-next.within-column="always">
1256 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Project Documents</fo:block>
1257 </fo:block>
1258 </fo:block>
1259 </fo:block>
1260 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1261 Some GNOME projects have documentation to maintain
1262 consistency in their product and to help new contributors
1263 get up to speed quickly. Among these are the GDP documents,
1264 such as the one you are reading now.
1265 </fo:block>
1266 </fo:block>
1267 </fo:block>
1268 </fo:block>
1269 <fo:block id="docbookbasics">
1270 <fo:block>
1271 <fo:block margin-left="-4pc" font-family="Helvetica">
1272 <fo:block keep-with-next.within-column="always">
1273 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">DocBook Basics </fo:block>
1274 </fo:block>
1275 </fo:block>
1276 </fo:block>
1277 <fo:block id="introtodocbook">
1278 <fo:block>
1279 <fo:block margin-left="-4pc" font-family="Helvetica">
1280 <fo:block keep-with-next.within-column="always">
1281 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Introduction to DocBook</fo:block>
1282 </fo:block>
1283 </fo:block>
1284 </fo:block>
1285 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1286 To understand DocBook, a basic understanding of SGML is
1287 helpful. SGML stands for Standard General Markup Language and
1288 is one of the first markup languages every created. HTML is
1289 actually derived from SGML and XML is a subset of SGML. SGML
1290 uses what is called a Document Type Definition to specify
1291 <fo:inline font-style="italic">elements</fo:inline> which are contained between
1292 brackets, &lt; and &gt;. Text is marked by both beginning and
1293 ending elements, for example in the DocBook DTD, one denotes a
1294 title with <fo:inline font-family="Courier">&lt;title&gt;</fo:inline>The
1295 Title<fo:inline font-family="Courier">&lt;/title&gt;</fo:inline>.
1296 </fo:block>
1297 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1298 The DTD (in the case of the GDP, DocBook) defines rules for how the
1299 elements can be used. For example, if one element can only be used when
1300 embedded within another, this is defined in the DTD.
1301 </fo:block>
1302 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1303 An SGML file is just a plain ASCII file containing the text
1304 with the markup specified above. To convert it to some easily
1305 readable format, you need special tools. The GDP uses <fo:inline font-style="italic">DocBook
1306 Tools</fo:inline>, a free package of utilities for working with DocBook
1307 which includes <fo:inline font-style="italic">Jade</fo:inline>, which does the SGML/DSSL
1308 parsing. You can read more about DocBook Tools in <fo:basic-link internal-destination="installingdocbook">the section called “Installing DocBook”</fo:basic-link>.
1309 </fo:block>
1310 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1311 The final appearance of the output (e.g. PostScript or HTML)
1312 is determined by a
1313 <fo:inline font-style="italic">stylesheet</fo:inline>. Stylesheets are files,
1314 written in a special language (DSSSL -- Document Style
1315 Semantics and Specification Language), which specify the
1316 appearance of various DocBook elements, for example,
1317 what fonts to use for titles and various inline elements, page
1318 numbering style, and much more. DocBook tools come with a
1319 collection of stylesheets (Norman Walsh's modular
1320 stylesheets); GNOME Document Project uses some customized
1321 version of this stylesheets -- see <fo:basic-link internal-destination="gdpstylesheets">the section called “GDP Stylesheets”</fo:basic-link>.
1322 </fo:block>
1323 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1324 The advantage of specifying the <fo:inline font-style="italic">structure</fo:inline>
1325 of a document with SGML instead of specifying the
1326 <fo:inline font-style="italic">appearance</fo:inline> of the document with a typical
1327 word processor, or with html, is that the resulting document
1328 can be processed in a variety of ways using the structural
1329 information. Whereas formatting a document for appearance
1330 assumes a medium (typically written text on a standard-sized
1331 piece of paper), SGML can be processed to produce output for a
1332 large variety of media such as text, postscript, HTML,
1333 Braille, audio, and potentially many other formats.
1334 </fo:block>
1335 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1336 Using 'content' as the elements to define the text of a document also
1337 allows for search engines to make use of the actual elements to make a
1338 "smarter search". For example, if you are searching for all documents
1339 written by the author "Susie" your search engine could be made smart
1340 enough to only search &lt;author&gt; elements, making for a faster and more
1341 accurate search.
1342 </fo:block>
1343 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1344 Since the overall appearance of the output is determined not by the DTD
1345 or the SGML document, but rather by a stylesheet, the appearance of a
1346 document can be easily changed just by changing the stylesheet. This
1347 allows everyone in the project to create documents that all look the
1348 same.
1349 </fo:block>
1350 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1351 As stated before, the GDP uses the DocBook DTD. For a list of
1352 introductory and reference resources on DocBook, see <fo:basic-link internal-destination="resources">the section called “Resources”</fo:basic-link>. The following sections also provide
1353 convenient instructions on which markup tags to use in various
1354 circumstances. Be sure to read <fo:basic-link internal-destination="conventions">the section called “GDP Documentation Conventions ”</fo:basic-link>
1355 for GDP documentation-specific guidelines.
1356 </fo:block>
1357 </fo:block>
1358 <fo:block id="xml">
1359 <fo:block>
1360 <fo:block margin-left="-4pc" font-family="Helvetica">
1361 <fo:block keep-with-next.within-column="always">
1362 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">XML and SGML</fo:block>
1363 </fo:block>
1364 </fo:block>
1365 </fo:block>
1366 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> In not so distant future (probably before GNOME 2.0),
1367 DocBook itself and GNOME Documentation project will migrate from
1368 SGML to XML. This transition should be relatively painless:
1369 (almost) all DocBook tags will remain the same. However, XML has
1370 stricter syntax rules than SGML; thus, some constructions which
1371 are valid in SGML will not be valid in XML. Therefore, to be
1372 ready for this transistion, it is <fo:inline font-style="italic">strongly
1373 advised</fo:inline> that the documentation writers conform to XML
1374 syntax rules. Here are most important differences:
1375 </fo:block>
1376 <fo:list-block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348613152" provisional-distance-between-starts="1in" provisional-label-separation="0.25in">
1377 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348613536">
1378 <fo:list-item-label end-indent="label-end()">
1379 <fo:block>
1380 <fo:inline> <fo:inline font-style="italic">Minimization</fo:inline></fo:inline>
1381 </fo:block>
1382 </fo:list-item-label>
1383 <fo:list-item-body start-indent="body-start()">
1384 <fo:block>
1385 It is possible with some implementations of SGML to use
1386 minimizations to close elements in a document by using
1387 &lt;/&gt;, for example:
1388 <fo:inline font-family="Courier"><fo:inline font-family="Courier">&lt;title&gt;</fo:inline>The
1389 Title<fo:inline font-family="Courier">&lt;/&gt;</fo:inline></fo:inline>. This is not
1390 allowed in XML. You can use <fo:inline font-weight="bold">sgmlnorm</fo:inline> command,
1391 included in DocBook Tools package, to expand minimized tags;
1392 if you are using Emacs with psgml
1393 mode, you can also use menu command
1394 Modify-&gt;Normalize.
1395 </fo:block>
1396 </fo:list-item-body>
1397 </fo:list-item>
1398 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348621792">
1399 <fo:list-item-label end-indent="label-end()">
1400 <fo:block>
1401 <fo:inline> <fo:inline font-style="italic">Self-closing tags</fo:inline></fo:inline>
1402 </fo:block>
1403 </fo:list-item-label>
1404 <fo:list-item-body start-indent="body-start()">
1405 <fo:block>
1406 Also, in SGML some tags are allowed not to have closing
1407 tags. For example, it is legal for
1408 <fo:inline font-family="Courier">&lt;xref&gt;</fo:inline> not to have a closing tag:
1409 <fo:inline font-family="Courier"><fo:inline font-family="Courier">&lt;xref
1410 linkend="someid"&gt;</fo:inline></fo:inline>. In
1411 XML, it is illegal; instead, you should use
1412 <fo:inline font-family="Courier"><fo:inline font-family="Courier">&lt;xref
1413 linkend="someid"/&gt;</fo:inline></fo:inline> (note the
1414 slash!).
1415 </fo:block>
1416 </fo:list-item-body>
1417 </fo:list-item>
1418 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348626976">
1419 <fo:list-item-label end-indent="label-end()">
1420 <fo:block>
1421 <fo:inline> <fo:inline font-style="italic">Case sensitive tags</fo:inline></fo:inline>
1422 </fo:block>
1423 </fo:list-item-label>
1424 <fo:list-item-body start-indent="body-start()">
1425 <fo:block>
1426 In XML, unlike SGML, tags are case-senstive
1427 <fo:inline font-family="Courier">&lt;title&gt;</fo:inline> and
1428 <fo:inline font-family="Courier">&lt;TITLE&gt;</fo:inline> are different tags!
1429 Therefore, please always use lowercase tags (except for
1430 things like <fo:inline font-family="Courier">DOCTYPE, CDATA</fo:inline> and
1431 <fo:inline font-family="Courier">ENTITY</fo:inline>, which are not DocBook tags).
1432 </fo:block>
1433 </fo:list-item-body>
1434 </fo:list-item>
1435 </fo:list-block>
1436 </fo:block>
1437 <fo:block id="structure">
1438 <fo:block>
1439 <fo:block margin-left="-4pc" font-family="Helvetica">
1440 <fo:block keep-with-next.within-column="always">
1441 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em"> Structure Elements</fo:block>
1442 </fo:block>
1443 </fo:block>
1444 </fo:block>
1445 <fo:block id="section">
1446 <fo:block>
1447 <fo:block margin-left="-4pc" font-family="Helvetica">
1448 <fo:block keep-with-next.within-column="always">
1449 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Sections and paragraphs</fo:block>
1450 </fo:block>
1451 </fo:block>
1452 </fo:block>
1453 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1454 Top-level element of a book body must be
1455 <fo:inline font-family="Courier">&lt;chapter&gt;</fo:inline>; it may contain one or more
1456 <fo:inline font-family="Courier">&lt;sect1&gt;</fo:inline>, each of them may contain
1457 <fo:inline font-family="Courier">&lt;sect2&gt;</fo:inline> and so on up to
1458 <fo:inline font-family="Courier">&lt;sect5&gt;</fo:inline>. The top-level element of an
1459 article body is always
1460 <fo:inline font-family="Courier">&lt;sect1&gt;</fo:inline>. Regardless of which elements
1461 you use, give each structural element a unique id, so that
1462 you can link to it. For usage example, see the template.
1463 </fo:block>
1464 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> Please try to avoid using deeply nested sections; for
1465 most situations, <fo:inline font-family="Courier">&lt;sect1&gt;</fo:inline> and
1466 <fo:inline font-family="Courier">&lt;sect2&gt;</fo:inline> should be sufficient. If not,
1467 you probably should split your <fo:inline font-family="Courier">&lt;sect1&gt;</fo:inline>
1468 into several smaller ones.
1469 </fo:block>
1470 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> Use the tag <fo:inline font-family="Courier">&lt;para&gt;</fo:inline> for
1471 paragraphs, even if there is only one paragraph in a
1472 section--see template for examples.
1473 </fo:block>
1474 </fo:block>
1475 <fo:block id="notes">
1476 <fo:block>
1477 <fo:block margin-left="-4pc" font-family="Helvetica">
1478 <fo:block keep-with-next.within-column="always">
1479 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Notes, Warnings, And Tips</fo:block>
1480 </fo:block>
1481 </fo:block>
1482 </fo:block>
1483 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1484 For notes, tips, warnings, and important information, which
1485 should be set apart from the main text (usually as a
1486 paragraph with some warning sign on the margin), use tags
1487 <fo:inline font-family="Courier">&lt;note&gt;</fo:inline>, <fo:inline font-family="Courier">&lt;tip&gt;</fo:inline>,
1488 <fo:inline font-family="Courier">&lt;warning&gt;</fo:inline>,
1489 <fo:inline font-family="Courier">&lt;important&gt;</fo:inline> respectively. For example:
1490 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
1491
1492 &lt;tip&gt;
1493 &lt;title&gt;TIP&lt;/title&gt;
1494 &lt;para&gt;
1495 To speed up program compilation, use &lt;application&gt;gcc&lt;/application&gt;
1496 compiler with Pentium optimization.
1497 &lt;/para&gt;
1498 &lt;/tip&gt; </fo:block> produces
1499 </fo:block>
1500 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="extip">
1501 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">TIP</fo:block>
1502 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1503 To speed up program compilation, use
1504 gcc compiler with Pentium
1505 optimization. </fo:block>
1506 </fo:block>
1507 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1508 Note that this should not be inside a
1509 <fo:inline font-family="Courier">&lt;para&gt;</fo:inline> but between paragraphs.
1510 </fo:block>
1511 </fo:block>
1512 <fo:block id="figures">
1513 <fo:block>
1514 <fo:block margin-left="-4pc" font-family="Helvetica">
1515 <fo:block keep-with-next.within-column="always">
1516 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em"> Screenshots and other figures</fo:block>
1517 </fo:block>
1518 </fo:block>
1519 </fo:block>
1520 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1521 To include screenshots and other figures, use the following
1522 tags:
1523
1524 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
1525
1526 &lt;figure id="shot1"&gt;
1527 &lt;title&gt;Screenshot&lt;/title&gt;
1528 &lt;screenshot&gt;
1529 &lt;screeninfo&gt;Screenshot of a program&lt;/screeninfo&gt;
1530 &lt;graphic format="PNG" fileref="figures/example_screenshot" srccredit="ME"&gt;
1531 &lt;/graphic&gt;
1532 &lt;/screenshot&gt;
1533 &lt;/figure&gt;
1534 </fo:block>
1535 replacing <fo:inline font-family="Courier">example_screenshot</fo:inline> with the
1536 actual file name (without extension). The result will look like this:
1537
1538 <fo:block id="shot1" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em" space-after.minimum="1em" space-after.optimum="1.5em" space-after.maximum="2em" keep-with-previous.within-column="always"><fo:block font-weight="bold" font-size="12pt" hyphenate="false" keep-with-next.within-column="always" space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">Screenshot</fo:block><fo:block><fo:block><fo:external-graphic src="url(file:figures/example_screenshot)" content-width="auto" content-height="auto" width="auto" height="auto"/></fo:block></fo:block></fo:block>
1539 </fo:block>
1540 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348576864">
1541 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">NOTE</fo:block>
1542 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1543 Notice in this example that the screenshot file name does
1544 not include the file type extension -- to find out
1545 why, please read <fo:basic-link internal-destination="jadeimages">the section called “Images in DocBook Tools”</fo:basic-link>.
1546 </fo:block>
1547 </fo:block>
1548 </fo:block>
1549 <fo:block id="listing">
1550 <fo:block>
1551 <fo:block margin-left="-4pc" font-family="Helvetica">
1552 <fo:block keep-with-next.within-column="always">
1553 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Program listings and terminal session</fo:block>
1554 </fo:block>
1555 </fo:block>
1556 </fo:block>
1557 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1558 To show a file fragment--for example, program
1559 listing--use <fo:inline font-family="Courier">&lt;programlisting&gt;</fo:inline> tag:
1560 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
1561
1562 &lt;programlisting&gt;
1563 [Desktop Entry]
1564 Name=Gnumeric spreadsheet
1565 Exec=gnumeric
1566 Icon=gnome-gnumeric.png
1567 Terminal=0
1568 Type=Application
1569 &lt;/programlisting&gt;
1570 </fo:block>
1571 which produces
1572 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
1573 [Desktop Entry]
1574 Name=Gnumeric spreadsheet
1575 Exec=gnumeric
1576 Icon=gnome-gnumeric.png
1577 Terminal=0
1578 Type=Application
1579 </fo:block>
1580 As a matter of fact, all examples in this document were
1581 produced using <fo:inline font-family="Courier">&lt;programlisting&gt;</fo:inline>.
1582 </fo:block>
1583 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1584 To show a record of terminal session--i.e., sequence of
1585 commands entered at the command line--use
1586 <fo:inline font-family="Courier">&lt;screen&gt;</fo:inline> tag:
1587 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
1588
1589 &lt;screen&gt;
1590 &lt;prompt&gt;bash$&lt;/prompt&gt;&lt;userinput&gt;make love&lt;/userinput&gt;
1591 make: *** No rule to make target `love'. Stop.
1592 &lt;/screen&gt;
1593 </fo:block>
1594 which produces
1595 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
1596 <fo:inline font-family="Courier">bash$</fo:inline><fo:inline font-weight="bold" font-family="Courier">make love</fo:inline>
1597 make: *** No rule to make target `love'. Stop.
1598 </fo:block>
1599 Note the use of tags <fo:inline font-family="Courier">&lt;prompt&gt;</fo:inline> and
1600 <fo:inline font-family="Courier">&lt;userinput&gt;</fo:inline> for marking system prompt
1601 and commands entered by user.
1602 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348664224"><fo:block font-size="14pt" font-weight="bold" keep-with-next="always">NOTE</fo:block><fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1603 Note that both <fo:inline font-family="Courier">&lt;programlisting&gt;</fo:inline>
1604 and <fo:inline font-family="Courier">&lt;screen&gt;</fo:inline> preserve linebreaks,
1605 but interpret SGML tags (unlike LaTeX
1606 verbatim environment). Take a look at
1607 the source of this document to see how you can have SGML
1608 tags literally shown but not interpreted,
1609 </fo:block></fo:block>
1610 </fo:block>
1611 </fo:block>
1612 <fo:block id="lists">
1613 <fo:block>
1614 <fo:block margin-left="-4pc" font-family="Helvetica">
1615 <fo:block keep-with-next.within-column="always">
1616 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em"> Lists</fo:block>
1617 </fo:block>
1618 </fo:block>
1619 </fo:block>
1620 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1621 The most common list types in DocBook are
1622 <fo:inline font-family="Courier">&lt;itemizedlist&gt;</fo:inline>,
1623 <fo:inline font-family="Courier">&lt;orderedlist&gt;</fo:inline>, and
1624 <fo:inline font-family="Courier">&lt;variablelist&gt;</fo:inline>.
1625 </fo:block>
1626 <fo:list-block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348671520" provisional-distance-between-starts="1in" provisional-label-separation="0.25in">
1627 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348671904">
1628 <fo:list-item-label end-indent="label-end()">
1629 <fo:block>
1630 <fo:inline> <fo:inline font-family="Courier">&lt;itemizedlist&gt;</fo:inline></fo:inline>
1631 </fo:block>
1632 </fo:list-item-label>
1633 <fo:list-item-body start-indent="body-start()">
1634 <fo:block>
1635 This is the simplest unnumbered list, parallel to
1636 <fo:inline font-family="Courier">&lt;ul&gt;</fo:inline> in HTML. Here is an example:
1637 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
1638
1639 &lt;itemizedlist&gt;
1640 &lt;listitem&gt;
1641 &lt;para&gt;
1642 &lt;guilabel&gt;Show backup files&lt;/guilabel&gt; &amp;mdash; This will
1643 show any backup file that might be on your system.
1644 &lt;/para&gt;
1645 &lt;/listitem&gt;
1646 &lt;listitem&gt;
1647 &lt;para&gt;
1648 &lt;guilabel&gt;Show hidden files&lt;/guilabel&gt; &amp;mdash; This will
1649 show all "dot files" or files that begin with a dot. This
1650 files typically include configuration files and directories.
1651 &lt;/para&gt;
1652 &lt;/listitem&gt;
1653 &lt;listitem&gt;
1654 &lt;para&gt;
1655 &lt;guilabel&gt;Mix files and directories&lt;/guilabel&gt; &amp;mdash; This
1656 option will display files and directories in the order you
1657 sort them instead of
1658 always having directories shown above files.
1659 &lt;/para&gt;
1660 &lt;/listitem&gt;
1661 &lt;/itemizedlist&gt;
1662
1663 </fo:block>
1664 and output:
1665 </fo:block>
1666 <fo:list-block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348675360" provisional-distance-between-starts="1.5em" provisional-label-separation="0.2em">
1667 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348675744">
1668 <fo:list-item-label end-indent="label-end()">
1669 <fo:block>•</fo:block>
1670 </fo:list-item-label>
1671 <fo:list-item-body start-indent="body-start()">
1672 <fo:block>
1673 Show backup files --
1674 This will show any backup file that might be on
1675 your system.
1676 </fo:block>
1677 </fo:list-item-body>
1678 </fo:list-item>
1679 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348677856">
1680 <fo:list-item-label end-indent="label-end()">
1681 <fo:block>•</fo:block>
1682 </fo:list-item-label>
1683 <fo:list-item-body start-indent="body-start()">
1684 <fo:block>
1685 Show hidden files --
1686 This will show all "dot files" or files that
1687 begin with a dot. This files typically include
1688 configuration files and directories.
1689 </fo:block>
1690 </fo:list-item-body>
1691 </fo:list-item>
1692 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348679968">
1693 <fo:list-item-label end-indent="label-end()">
1694 <fo:block>•</fo:block>
1695 </fo:list-item-label>
1696 <fo:list-item-body start-indent="body-start()">
1697 <fo:block>
1698 Mix files and directories
1699 -- This option will display files and
1700 directories in the order you sort them instead
1701 of always having directories shown above files.
1702 </fo:block>
1703 </fo:list-item-body>
1704 </fo:list-item>
1705 </fo:list-block>
1706 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> Note the use of <fo:inline font-family="Courier">&amp;mdash;</fo:inline>
1707 for long dash (see <fo:basic-link internal-destination="specsymb">the section called “ Special symbols ”</fo:basic-link>). Also,
1708 please note that the result looks much nicer because the
1709 terms being explained (Show backup
1710 files, etc.) are set in a different font. In
1711 this case, it was achieved by using <fo:basic-link internal-destination="gui"><fo:inline font-family="Courier">&lt;guilabel&gt;</fo:inline></fo:basic-link>
1712 tag. In other cases, use appropriate tags such as
1713 <fo:basic-link internal-destination="gui"><fo:inline font-family="Courier">&lt;guimenuitem&gt;</fo:inline></fo:basic-link>,
1714 <fo:basic-link internal-destination="filenames"><fo:inline font-family="Courier">&lt;command&gt;</fo:inline></fo:basic-link>,
1715 or -- if none of
1716 this applies -- use
1717 <fo:basic-link internal-destination="gui"><fo:inline font-family="Courier">&lt;emphasis&gt;</fo:inline></fo:basic-link>.
1718 </fo:block>
1719 </fo:list-item-body>
1720 </fo:list-item>
1721 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348689568">
1722 <fo:list-item-label end-indent="label-end()">
1723 <fo:block>
1724 <fo:inline> <fo:inline font-family="Courier">&lt;orderedlist&gt;</fo:inline></fo:inline>
1725 </fo:block>
1726 </fo:list-item-label>
1727 <fo:list-item-body start-indent="body-start()">
1728 <fo:block>
1729 This list is completely analogous to
1730 <fo:inline font-family="Courier">&lt;itemizedlist&gt;</fo:inline> and has the same
1731 syntax, but it produces numbered list. By default,
1732 this list uses Arabic numerals for numbering entries;
1733 you can override this using <fo:inline font-family="Courier">numeration</fo:inline>,
1734 for example <fo:inline font-family="Courier">&lt;orderedlist
1735 numeration="lowerroman"&gt;</fo:inline>. Possible values of
1736 these attribute are <fo:inline font-family="Courier">arabic</fo:inline>,
1737 <fo:inline font-family="Courier">upperalpha</fo:inline>,
1738 <fo:inline font-family="Courier">loweralpha</fo:inline>,
1739 <fo:inline font-family="Courier">upperroman</fo:inline>,
1740 <fo:inline font-family="Courier">lowerroman</fo:inline>.
1741 </fo:block>
1742 </fo:list-item-body>
1743 </fo:list-item>
1744 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348696480">
1745 <fo:list-item-label end-indent="label-end()">
1746 <fo:block>
1747 <fo:inline> <fo:inline font-family="Courier">&lt;variablelist&gt;</fo:inline></fo:inline>
1748 </fo:block>
1749 </fo:list-item-label>
1750 <fo:list-item-body start-indent="body-start()">
1751 <fo:block> This list is used when each entry is
1752 rather long, so it should be formatted as a block of text
1753 with some subtitle, like a small subsection. The
1754 <fo:inline font-family="Courier">&lt;variablelist&gt;</fo:inline> is more complicated
1755 than itemizedlists, but for larger blocks of text, or when
1756 you're explaining or defining something, it's best to use
1757 them. Their greatest advantage is that it's easier for a
1758 computer to search. The lines you are reading now were
1759 produced by <fo:inline font-family="Courier">&lt;variablelist&gt;</fo:inline>. The
1760 source looked liked this:
1761 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
1762
1763 &lt;variablelist&gt;
1764 &lt;varlistentry&gt;
1765 &lt;term&gt; &lt;sgmltag&gt;&amp;lt;itemizedlist&gt;&lt;/sgmltag&gt;&lt;/term&gt;
1766 &lt;listitem&gt;&lt;para&gt;
1767 This is the simplest unnumbered list, parallel to
1768 &lt;sgmltag&gt;&amp;lt;ul&gt;&lt;/sgmltag&gt; in HTML. Here is an example:...
1769 &lt;/para&gt;&lt;/listitem&gt;
1770 &lt;/varlistentry&gt;
1771 &lt;varlistentry&gt;
1772 &lt;term&gt; &lt;sgmltag&gt;&amp;lt;orderedlist&gt;&lt;/sgmltag&gt;&lt;/term&gt;
1773 &lt;listitem&gt;&lt;para&gt;
1774 This list is completely analogous to
1775 &lt;sgmltag&gt;&amp;lt;itemizedlist&gt;&lt;/sgmltag&gt;
1776 &lt;/para&gt;&lt;/listitem&gt;
1777 &lt;/varlistentry&gt;
1778 &lt;varlistentry&gt;
1779 &lt;term&gt; &lt;sgmltag&gt;&amp;lt;variablelist&gt;&lt;/sgmltag&gt;&lt;/term&gt;
1780 &lt;listitem&gt;&lt;para&gt;
1781 This list is used when each entry is rather long,...
1782 &lt;/para&gt;&lt;/listitem&gt;
1783 &lt;/varlistentry&gt;
1784 &lt;/variablelist&gt;
1785
1786 </fo:block>
1787 </fo:block>
1788 </fo:list-item-body>
1789 </fo:list-item>
1790 </fo:list-block>
1791 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1792 Lists can be nested; in this case, the stylesheets
1793 are smart enough to change the numeration (for
1794 <fo:inline font-family="Courier">&lt;orderedlist&gt;</fo:inline>) or marks of each entry
1795 (in <fo:inline font-family="Courier">&lt;itemizedlist&gt;</fo:inline>) for sub-lists
1796 </fo:block>
1797 </fo:block>
1798 </fo:block>
1799 <fo:block id="inline">
1800 <fo:block>
1801 <fo:block margin-left="-4pc" font-family="Helvetica">
1802 <fo:block keep-with-next.within-column="always">
1803 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Inline Elements</fo:block>
1804 </fo:block>
1805 </fo:block>
1806 </fo:block>
1807 <fo:block id="gui">
1808 <fo:block>
1809 <fo:block margin-left="-4pc" font-family="Helvetica">
1810 <fo:block keep-with-next.within-column="always">
1811 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">GUI elements</fo:block>
1812 </fo:block>
1813 </fo:block>
1814 </fo:block>
1815 <fo:list-block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348705888" provisional-distance-between-starts="1.5em" provisional-label-separation="0.2em">
1816 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348706272">
1817 <fo:list-item-label end-indent="label-end()">
1818 <fo:block>•</fo:block>
1819 </fo:list-item-label>
1820 <fo:list-item-body start-indent="body-start()">
1821 <fo:block>
1822 <fo:inline font-family="Courier">&lt;guibutton&gt;</fo:inline> -- used for
1823 buttons, including checkbuttons and radio buttons
1824 </fo:block>
1825 </fo:list-item-body>
1826 </fo:list-item>
1827 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348708192">
1828 <fo:list-item-label end-indent="label-end()">
1829 <fo:block>•</fo:block>
1830 </fo:list-item-label>
1831 <fo:list-item-body start-indent="body-start()">
1832 <fo:block>
1833 <fo:inline font-family="Courier">&lt;guimenu&gt;</fo:inline>,
1834 <fo:inline font-family="Courier">&lt;guisubmenu&gt;</fo:inline> --used for
1835 top-level menus and submenus
1836 respectively, for example <fo:inline font-family="Courier">
1837 &lt;guisubmenu&gt;Utilities&lt;/guisubmenu&gt; submenu of the
1838 &lt;guimenu&gt;Main Menu&lt;/guimenu&gt;</fo:inline>
1839 </fo:block>
1840 </fo:list-item-body>
1841 </fo:list-item>
1842 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348711456">
1843 <fo:list-item-label end-indent="label-end()">
1844 <fo:block>•</fo:block>
1845 </fo:list-item-label>
1846 <fo:list-item-body start-indent="body-start()">
1847 <fo:block>
1848 <fo:inline font-family="Courier">&lt;guimenuitem&gt;</fo:inline>--an entry in a
1849 menu
1850 </fo:block>
1851 </fo:list-item-body>
1852 </fo:list-item>
1853 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348713184">
1854 <fo:list-item-label end-indent="label-end()">
1855 <fo:block>•</fo:block>
1856 </fo:list-item-label>
1857 <fo:list-item-body start-indent="body-start()">
1858 <fo:block>
1859 <fo:inline font-family="Courier">&lt;guiicon&gt;</fo:inline>--an icon
1860 </fo:block>
1861 </fo:list-item-body>
1862 </fo:list-item>
1863 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348714912">
1864 <fo:list-item-label end-indent="label-end()">
1865 <fo:block>•</fo:block>
1866 </fo:list-item-label>
1867 <fo:list-item-body start-indent="body-start()">
1868 <fo:block>
1869 <fo:inline font-family="Courier">&lt;guilabel&gt;</fo:inline>--for items which have
1870 labels, like tabs, or bounding boxes.
1871 </fo:block>
1872 </fo:list-item-body>
1873 </fo:list-item>
1874 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348716640">
1875 <fo:list-item-label end-indent="label-end()">
1876 <fo:block>•</fo:block>
1877 </fo:list-item-label>
1878 <fo:list-item-body start-indent="body-start()">
1879 <fo:block>
1880 <fo:inline font-family="Courier">&lt;interface&gt;</fo:inline>-- for most everything
1881 else... a window, a dialog box, the Panel, etc.
1882 </fo:block>
1883 </fo:list-item-body>
1884 </fo:list-item>
1885 </fo:list-block>
1886 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1887 If you need to refer to a sequence of menu choices, such as
1888 Main Menu-&gt;Utilities-&gt;GNOME
1889 terminal
1890 there is a special construction for this, too:
1891 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
1892
1893 &lt;menuchoice&gt;
1894 &lt;guimenu&gt;Main Menu&lt;/guimenu&gt; &lt;guisubmenu&gt;Utilities&lt;/guisubmenu&gt;
1895 &lt;guimenuitem&gt;GNOME terminal&lt;/guimenuitem&gt; &lt;/menuchoice&gt;
1896 </fo:block>
1897 </fo:block>
1898 </fo:block>
1899 <fo:block id="links">
1900 <fo:block>
1901 <fo:block margin-left="-4pc" font-family="Helvetica">
1902 <fo:block keep-with-next.within-column="always">
1903 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Links and references</fo:block>
1904 </fo:block>
1905 </fo:block>
1906 </fo:block>
1907 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1908 To refer to another place in the same document, you can use
1909 tags <fo:inline font-family="Courier">&lt;xref&gt;</fo:inline> and
1910 <fo:inline font-family="Courier">&lt;link&gt;</fo:inline>. The first of them
1911 automatically inserts the full name of the element you refer
1912 to (section, figure, etc.), while the second just creates a
1913 link (in HTML output). Here is an example:
1914 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
1915 An example of a &lt;link linkend="extip"&gt;tip&lt;/link&gt; was given in
1916 &lt;xref linkend="notes" /&gt;.
1917 </fo:block>
1918 which produces: An example of a <fo:basic-link internal-destination="extip">tip</fo:basic-link> was given in <fo:basic-link internal-destination="notes">the section called “Notes, Warnings, And Tips”</fo:basic-link>.
1919 </fo:block>
1920 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1921 Here <fo:inline font-family="Courier">notes</fo:inline> and <fo:inline font-family="Courier">extip</fo:inline>
1922 are the id attributes of <fo:basic-link internal-destination="notes">the section called “Notes, Warnings, And Tips”</fo:basic-link> and of the
1923 example of a tip in it.
1924 </fo:block>
1925 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> To produce a link to an external source, such as a
1926 Web page or a local file, use <fo:inline font-family="Courier">&lt;ulink&gt;</fo:inline>
1927 tag, for example:
1928 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
1929 To find more about GNOME, please visit &lt;ulink type="http"
1930 url="http://www.gnome.org"&gt;GNOME Web page&lt;/ulink&gt;
1931 </fo:block>
1932 which produces: To find more about GNOME, please visit
1933 <fo:basic-link external-destination="http://www.gnome.org">The GNOME Web
1934 Site</fo:basic-link><fo:inline hyphenate="false"> [http://www.gnome.org]</fo:inline> You can use any of the standard URL types, such
1935 as <fo:inline font-family="Courier">http, ftp, file, telnet, mailto</fo:inline> (in
1936 most cases, however, use of <fo:inline font-family="Courier">mailto</fo:inline> is
1937 unnecessary--see discussion of
1938 <fo:inline font-family="Courier">&lt;email&gt;</fo:inline> tag).
1939 </fo:block>
1940 </fo:block>
1941 <fo:block id="filenames">
1942 <fo:block>
1943 <fo:block margin-left="-4pc" font-family="Helvetica">
1944 <fo:block keep-with-next.within-column="always">
1945 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Filenames, commands, and other
1946 computer-related things</fo:block>
1947 </fo:block>
1948 </fo:block>
1949 </fo:block>
1950 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
1951 Here are some tags used to describe operating system-related
1952 things:
1953 </fo:block>
1954 <fo:list-block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348729504" provisional-distance-between-starts="1.5em" provisional-label-separation="0.2em">
1955 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348729888">
1956 <fo:list-item-label end-indent="label-end()">
1957 <fo:block>•</fo:block>
1958 </fo:list-item-label>
1959 <fo:list-item-body start-indent="body-start()">
1960 <fo:block> <fo:inline font-family="Courier">&lt;filename&gt;</fo:inline> -- used
1961 for filenames,
1962 e.g.<fo:inline font-family="Courier">&lt;filename&gt;</fo:inline>
1963 foo.sgml
1964 <fo:inline font-family="Courier">&lt;/filename&gt;</fo:inline>
1965 produces: <fo:inline font-family="Courier">foo.sgml</fo:inline>.
1966 </fo:block>
1967 </fo:list-item-body>
1968 </fo:list-item>
1969 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348733728">
1970 <fo:list-item-label end-indent="label-end()">
1971 <fo:block>•</fo:block>
1972 </fo:list-item-label>
1973 <fo:list-item-body start-indent="body-start()">
1974 <fo:block> <fo:inline font-family="Courier">&lt;filename
1975 class="directory"&gt;</fo:inline> -- used for
1976 directories, e.g.<fo:inline font-family="Courier">&lt;filename
1977 class="directory"&gt;</fo:inline>/usr/bin
1978 <fo:inline font-family="Courier">&lt;/filename&gt;</fo:inline>
1979 produces: <fo:inline font-family="Courier">/usr/bin</fo:inline>.
1980 </fo:block>
1981 </fo:list-item-body>
1982 </fo:list-item>
1983 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348737760">
1984 <fo:list-item-label end-indent="label-end()">
1985 <fo:block>•</fo:block>
1986 </fo:list-item-label>
1987 <fo:list-item-body start-indent="body-start()">
1988 <fo:block>
1989 <fo:inline font-family="Courier">&lt;application&gt;</fo:inline> -- used for
1990 application names,
1991 e.g. <fo:inline font-family="Courier">&lt;application&gt;</fo:inline>Gnumeric
1992 <fo:inline font-family="Courier">&lt;/application&gt;</fo:inline> produces:
1993 Gnumeric.
1994 </fo:block>
1995 </fo:list-item-body>
1996 </fo:list-item>
1997 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348741600">
1998 <fo:list-item-label end-indent="label-end()">
1999 <fo:block>•</fo:block>
2000 </fo:list-item-label>
2001 <fo:list-item-body start-indent="body-start()">
2002 <fo:block>
2003 <fo:inline font-family="Courier">&lt;envar&gt;</fo:inline> -- used for
2004 environment variables, e.g.
2005 <fo:inline font-family="Courier">&lt;envar&gt;</fo:inline>PATH<fo:inline font-family="Courier">&lt;/envar&gt;</fo:inline>.
2006 </fo:block>
2007 </fo:list-item-body>
2008 </fo:list-item>
2009 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348744672">
2010 <fo:list-item-label end-indent="label-end()">
2011 <fo:block>•</fo:block>
2012 </fo:list-item-label>
2013 <fo:list-item-body start-indent="body-start()">
2014 <fo:block>
2015 <fo:inline font-family="Courier">&lt;command&gt;</fo:inline> -- used for
2016 commands entered on command line, e.g.
2017 <fo:inline font-family="Courier">&lt;command&gt;</fo:inline>make install
2018 <fo:inline font-family="Courier">&lt;/command&gt;</fo:inline> produces:
2019 <fo:inline font-weight="bold">make install</fo:inline>.
2020 </fo:block>
2021 </fo:list-item-body>
2022 </fo:list-item>
2023 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348748512">
2024 <fo:list-item-label end-indent="label-end()">
2025 <fo:block>•</fo:block>
2026 </fo:list-item-label>
2027 <fo:list-item-body start-indent="body-start()">
2028 <fo:block>
2029 <fo:inline font-family="Courier">&lt;replaceable&gt;</fo:inline> -- used for
2030 replaceable text, e.g.
2031 <fo:inline font-family="Courier">&lt;command&gt;</fo:inline>db2html<fo:inline font-family="Courier">&lt;replaceable&gt;</fo:inline>
2032 foo.sgml
2033 <fo:inline font-family="Courier">&lt;/replaceable&gt;</fo:inline><fo:inline font-family="Courier">&lt;/command&gt;</fo:inline>
2034 produces: <fo:inline font-weight="bold">db2html
2035 <fo:inline font-style="italic" font-family="Courier">foo.sgml</fo:inline></fo:inline>.
2036 </fo:block>
2037 </fo:list-item-body>
2038 </fo:list-item>
2039 </fo:list-block>
2040 </fo:block>
2041 <fo:block id="keys">
2042 <fo:block>
2043 <fo:block margin-left="-4pc" font-family="Helvetica">
2044 <fo:block keep-with-next.within-column="always">
2045 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Keyboard input</fo:block>
2046 </fo:block>
2047 </fo:block>
2048 </fo:block>
2049 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> To mark up text input by the user, use
2050 <fo:inline font-family="Courier">&lt;userinput&gt;</fo:inline>.
2051 </fo:block>
2052 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> To mark keystrokes such as shortcuts and other
2053 commands, use <fo:inline font-family="Courier">&lt;keycap&gt;</fo:inline>.
2054 This is used for marking up what is printed on the top
2055 of the physical key on the keyboard. There are a couple of
2056 other tags for keys, too: <fo:inline font-family="Courier">&lt;keysym&gt;</fo:inline>
2057 and <fo:inline font-family="Courier">&lt;keycode&gt;</fo:inline>. However you are
2058 unlikely to need these for most documentation. For reference,
2059 <fo:inline font-family="Courier">&lt;keysym&gt;</fo:inline> is for the “symbolic
2060 name” of a key. <fo:inline font-family="Courier">&lt;keycode&gt;</fo:inline> is
2061 for the “scan code” of a key. These are not
2062 terms commonly required in GNOME documentation,
2063 although <fo:inline font-family="Courier">&lt;keysym&gt;</fo:inline> is useful for marking
2064 up control codes.
2065 </fo:block>
2066 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2067 To mark up a combination of keystrokes, use the
2068 <fo:inline font-family="Courier">&lt;keycombo&gt;</fo:inline> wrapper:
2069 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
2070
2071 &lt;keycombo&gt;
2072 &lt;keycap&gt;Ctrl&lt;/keycap&gt;
2073 &lt;keycap&gt;Alt&lt;/keycap&gt;
2074 &lt;keycap&gt;F1&lt;/keycap&gt;
2075 &lt;/keycombo&gt;
2076 </fo:block>
2077 </fo:block>
2078 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2079 Finally, if you want to show a shortcut for some menu
2080 command, here are the appropriate tags (rather long):
2081 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
2082
2083 &lt;menuchoice&gt;
2084 &lt;shortcut&gt;
2085 &lt;keycombo&gt;&lt;keycap&gt;Ctrl&lt;/keycap&gt;&lt;keycap&gt;q&lt;/keycap&gt;&lt;/keycombo&gt;
2086 &lt;/shortcut&gt;
2087 &lt;guimenuitem&gt; Quit&lt;/guimenuitem&gt;
2088 &lt;/menuchoice&gt;
2089 </fo:block>
2090 which produces simply
2091 Quit (<fo:inline font-weight="bold">Ctrl-q</fo:inline>)
2092 </fo:block>
2093 </fo:block>
2094 <fo:block id="email">
2095 <fo:block>
2096 <fo:block margin-left="-4pc" font-family="Helvetica">
2097 <fo:block keep-with-next.within-column="always">
2098 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">E-mail addresses</fo:block>
2099 </fo:block>
2100 </fo:block>
2101 </fo:block>
2102 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> To mark up e-mail
2103 address, use <fo:inline font-family="Courier">&lt;email&gt;</fo:inline>:
2104 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
2105 The easiest way to get in touch with me is by e-mail
2106 (&lt;email&gt;[email protected]&lt;/email&gt;)
2107 </fo:block>
2108 which produces: The easiest way to get in touch with me is
2109 by e-mail (<fo:inline font-family="Courier">&lt;[email protected]&gt;</fo:inline>) Note that
2110 <fo:inline font-family="Courier">&lt;email&gt;</fo:inline> automatically produces a link
2111 in html version.
2112 </fo:block>
2113 </fo:block>
2114 <fo:block id="specsymb">
2115 <fo:block>
2116 <fo:block margin-left="-4pc" font-family="Helvetica">
2117 <fo:block keep-with-next.within-column="always">
2118 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em"> Special symbols </fo:block>
2119 </fo:block>
2120 </fo:block>
2121 </fo:block>
2122 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2123 DocBook also provides special means for entering
2124 typographic symbols which can not be entered directly
2125 form the keyboard (such as copyright sign). This is done using
2126 <fo:inline font-style="italic">entities</fo:inline>, which is SGML analogue of
2127 macros, or commands, of LaTeX. They generally have the form
2128 <fo:inline font-family="Courier">&amp;entityname;</fo:inline>. Note that the semicolon
2129 is required.
2130 </fo:block>
2131 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2132 here is partial list of most commonly used enitites:
2133 </fo:block>
2134 <fo:list-block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348792672" provisional-distance-between-starts="1.5em" provisional-label-separation="0.2em">
2135 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348793056">
2136 <fo:list-item-label end-indent="label-end()">
2137 <fo:block>•</fo:block>
2138 </fo:list-item-label>
2139 <fo:list-item-body start-indent="body-start()">
2140 <fo:block>
2141 <fo:inline font-family="Courier">&amp;amp;</fo:inline> -- ampersend (&amp;)
2142 </fo:block>
2143 </fo:list-item-body>
2144 </fo:list-item>
2145 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348794592">
2146 <fo:list-item-label end-indent="label-end()">
2147 <fo:block>•</fo:block>
2148 </fo:list-item-label>
2149 <fo:list-item-body start-indent="body-start()">
2150 <fo:block>
2151 <fo:inline font-family="Courier">&amp;lt;</fo:inline> -- left angle bracket (&lt;)
2152 </fo:block>
2153 </fo:list-item-body>
2154 </fo:list-item>
2155 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348796128">
2156 <fo:list-item-label end-indent="label-end()">
2157 <fo:block>•</fo:block>
2158 </fo:list-item-label>
2159 <fo:list-item-body start-indent="body-start()">
2160 <fo:block>
2161 <fo:inline font-family="Courier">&amp;copy;</fo:inline> -- copyright sign (©)
2162 </fo:block>
2163 </fo:list-item-body>
2164 </fo:list-item>
2165 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348798240">
2166 <fo:list-item-label end-indent="label-end()">
2167 <fo:block>•</fo:block>
2168 </fo:list-item-label>
2169 <fo:list-item-body start-indent="body-start()">
2170 <fo:block>
2171 <fo:inline font-family="Courier">&amp;mdash;</fo:inline> -- long dash (--)
2172 </fo:block>
2173 </fo:list-item-body>
2174 </fo:list-item>
2175 <fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348799968">
2176 <fo:list-item-label end-indent="label-end()">
2177 <fo:block>•</fo:block>
2178 </fo:list-item-label>
2179 <fo:list-item-body start-indent="body-start()">
2180 <fo:block>
2181 <fo:inline font-family="Courier">&amp;hellip;</fo:inline> -- ellipsis (...)
2182 </fo:block>
2183 </fo:list-item-body>
2184 </fo:list-item>
2185 </fo:list-block>
2186 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2187 Note that the actual look of the resulting symbols depends
2188 on the fonts used by your browser; for example, it might
2189 happen that long dash (<fo:inline font-family="Courier">&amp;mdash;</fo:inline>) looks
2190 exactly like the usual dash (-). However, in the PostScript
2191 (and thus, in print) the output will look markedly better if
2192 you use appropriate tags.
2193 </fo:block>
2194 </fo:block>
2195 </fo:block>
2196 </fo:block>
2197 <fo:block id="conventions">
2198 <fo:block>
2199 <fo:block margin-left="-4pc" font-family="Helvetica">
2200 <fo:block keep-with-next.within-column="always">
2201 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">GDP Documentation Conventions </fo:block>
2202 </fo:block>
2203 </fo:block>
2204 </fo:block>
2205 <fo:block id="conventionsalldocs">
2206 <fo:block>
2207 <fo:block margin-left="-4pc" font-family="Helvetica">
2208 <fo:block keep-with-next.within-column="always">
2209 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Conventions for All GDP Documentation</fo:block>
2210 </fo:block>
2211 </fo:block>
2212 </fo:block>
2213 <fo:block id="xmlcomp">
2214 <fo:block>
2215 <fo:block margin-left="-4pc" font-family="Helvetica">
2216 <fo:block keep-with-next.within-column="always">
2217 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em"> XML compatibility </fo:block>
2218 </fo:block>
2219 </fo:block>
2220 </fo:block>
2221 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2222 All GNOME documentation should conform to XML syntax
2223 requirements, which are stricter than SGML ones -- see
2224 <fo:basic-link internal-destination="xml">the section called “XML and SGML”</fo:basic-link> for more informaion.
2225 </fo:block>
2226 </fo:block>
2227 <fo:block id="authorsnames">
2228 <fo:block>
2229 <fo:block margin-left="-4pc" font-family="Helvetica">
2230 <fo:block keep-with-next.within-column="always">
2231 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em"> Authors' names</fo:block>
2232 </fo:block>
2233 </fo:block>
2234 </fo:block>
2235 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2236 All GNOME documentation should contain the names of both the
2237 application authors and documentation authors, as well as a
2238 link to the application web page (if it exists) and
2239 information for bug submission -- see templates for an
2240 example.
2241 </fo:block>
2242 </fo:block>
2243 </fo:block>
2244 <fo:block id="conventionsappdocs">
2245 <fo:block>
2246 <fo:block margin-left="-4pc" font-family="Helvetica">
2247 <fo:block keep-with-next.within-column="always">
2248 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Conventions for Application Documentation</fo:block>
2249 </fo:block>
2250 </fo:block>
2251 </fo:block>
2252 <fo:block id="applicationversionid">
2253 <fo:block>
2254 <fo:block margin-left="-4pc" font-family="Helvetica">
2255 <fo:block keep-with-next.within-column="always">
2256 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Application Version Identification</fo:block>
2257 </fo:block>
2258 </fo:block>
2259 </fo:block>
2260 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2261 Application documentation should identify the version of the
2262 application for which the documentation is written:
2263 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
2264
2265 &lt;sect1 id="intro"&gt;
2266 &lt;title&gt;Introduction&lt;/title&gt;
2267 &lt;para&gt;
2268 blah-blah-blah This document describes version 1.0.53 of gfoo.
2269 &lt;/para&gt;
2270 &lt;/sect1&gt;
2271 </fo:block>
2272 </fo:block>
2273 </fo:block>
2274 <fo:block id="license">
2275 <fo:block>
2276 <fo:block margin-left="-4pc" font-family="Helvetica">
2277 <fo:block keep-with-next.within-column="always">
2278 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em"> Copyright information </fo:block>
2279 </fo:block>
2280 </fo:block>
2281 </fo:block>
2282 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> Application
2283 documentation should contain a copyright notice, stating the
2284 licensing terms. It is suggested that you use the GNU Free
2285 Documentation License. You could also use some other license
2286 allowing free redistribution, such as GPL or Open Content
2287 license. If documentation uses some trademarks (such as UNIX,
2288 Linux, Windows, etc.), proper legal junk should also be
2289 included (see templates).
2290 </fo:block>
2291 </fo:block>
2292 <fo:block id="license2">
2293 <fo:block>
2294 <fo:block margin-left="-4pc" font-family="Helvetica">
2295 <fo:block keep-with-next.within-column="always">
2296 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Software license</fo:block>
2297 </fo:block>
2298 </fo:block>
2299 </fo:block>
2300 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2301 All GNOME applications must contain information about the
2302 license (for software, not for documentation), either in the
2303 "About" box or in the manual.
2304 </fo:block>
2305 </fo:block>
2306 <fo:block id="bugtraq">
2307 <fo:block>
2308 <fo:block margin-left="-4pc" font-family="Helvetica">
2309 <fo:block keep-with-next.within-column="always">
2310 <fo:block font-size="12pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em"> Bug reporting</fo:block>
2311 </fo:block>
2312 </fo:block>
2313 </fo:block>
2314 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2315 Application documentation should give an address for
2316 reporting bugs and for submitting comments about the
2317 documentaion (see templates for an example).
2318 </fo:block>
2319 </fo:block>
2320 </fo:block>
2321 </fo:block>
2322 <fo:block id="writingapplicationmanuals">
2323 <fo:block>
2324 <fo:block margin-left="-4pc" font-family="Helvetica">
2325 <fo:block keep-with-next.within-column="always">
2326 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Writing Application and Applet Manuals</fo:block>
2327 </fo:block>
2328 </fo:block>
2329 </fo:block>
2330 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2331 Every GNOME application or applet should have a manual specific
2332 to that particular application. This manual should be a complete
2333 and authoritative guide. The manual should describe what the
2334 program does and how to use it. Manuals will typically describe
2335 each window or panel presented to the user using screenshots (in
2336 PNG format only) when appropriate. They should also describe
2337 each feature and preference option available.
2338 </fo:block>
2339 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348824736">
2340 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">Documentation Availability</fo:block>
2341 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2342 Applications and applets should not rely on documentation
2343 which is only available on the internet. All manuals and
2344 other documentation should be packaged with the application or
2345 applet and be made available to the user through the standard
2346 GNOME help system methods described below.
2347 </fo:block>
2348 </fo:block>
2349 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> Application manuals should be based on the template in
2350 <fo:basic-link internal-destination="template1">the section called “Template 1: Application Manual”</fo:basic-link>. Applet manuals should be based on
2351 the templates in <fo:basic-link internal-destination="template2-1x">the section called “Template 2: Applet Manual For GNOME 1.x”</fo:basic-link> for GNOME
2352 versions 1.x and the templates in <fo:basic-link internal-destination="template2-2x">the section called “Template 2: Applet Manual For GNOME 2.x”</fo:basic-link>
2353 for GNOME versions 2.x.
2354 </fo:block>
2355 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348828768">
2356 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">Manuals For Large Applications</fo:block>
2357 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2358 Manuals for very large applications, such as GNOME Workshop
2359 components should be a <fo:inline font-family="Courier">&lt;book&gt;</fo:inline> (and thus
2360 use <fo:inline font-family="Courier">&lt;chapter&gt;</fo:inline> for each primary section)
2361 , instead of <fo:inline font-family="Courier">&lt;article&gt;</fo:inline> which most
2362 applications use(with each primary section being a
2363 <fo:inline font-family="Courier">&lt;sect1&gt;</fo:inline>).
2364 </fo:block>
2365 </fo:block>
2366 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348832800">
2367 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">Applet Manuals in GNOME 2.0</fo:block>
2368 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2369 Note that applet manuals in GNOME 2.0 are treated in a special
2370 way. The manuals for all applets are merged into a single
2371 virtual document by Nautilus. For this reason, the header
2372 information for applet manuals is omitted and the first
2373 section of each applet is
2374 <fo:inline font-family="Courier">&lt;sect1&gt;</fo:inline>. Applet manuals will typically
2375 have several sections, each of which is
2376 <fo:inline font-family="Courier">&lt;sect2&gt;</fo:inline>.
2377 </fo:block>
2378 </fo:block>
2379 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2380 Application manuals should be made available by having a
2381 "Manual" entry in the Help pull-down menu
2382 at the top of the
2383 application, as described in <fo:basic-link internal-destination="listingdocsinhelpmenu">the section called “Listing Documents in the Help Menu”</fo:basic-link>.
2384 Applets should make their manuals available by
2385 right-clicking on the applet.
2386 </fo:block>
2387 </fo:block>
2388 <fo:block id="listingdocsinhelpmenu">
2389 <fo:block>
2390 <fo:block margin-left="-4pc" font-family="Helvetica">
2391 <fo:block keep-with-next.within-column="always">
2392 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Listing Documents in the Help Menu</fo:block>
2393 </fo:block>
2394 </fo:block>
2395 </fo:block>
2396 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348839328">
2397 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">Developer Information</fo:block>
2398 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2399 This section is for developers. Documentation authors
2400 generally do not need to know this material.
2401 </fo:block>
2402 </fo:block>
2403 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2404 Typically the application manual and possibly additional help
2405 documents will be made available to the user under the
2406 Help menu at the top right of the
2407 application. To do this, you must first write a
2408 <fo:inline font-family="Courier">topic.dat</fo:inline> file. The format for this file is:
2409 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
2410 One line for each 'topic'.
2411
2412 Two columns, as defined by perl -e 'split(/\s+/,$aline,2)'
2413
2414 First column is the HTML file (and optional section) for the topic,
2415 relative to the app's help file dir.
2416
2417 Second column is the user-visible topic name.
2418 </fo:block>
2419 For example, Gnumeric's
2420 <fo:inline font-family="Courier">topic.dat</fo:inline> file is:
2421 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
2422 gnumeric.html Gnumeric manual
2423 function-reference.html Gnumeric function reference
2424 </fo:block>
2425 When the application is installed, the
2426 <fo:inline font-family="Courier">topic.dat</fo:inline> file should be placed in the
2427 <fo:inline font-family="Courier">$prefix/share/gnome/help/<fo:inline font-style="italic" font-family="Courier">appname</fo:inline>/C/</fo:inline> directory
2428 where <fo:inline font-style="italic" font-family="Courier">appname</fo:inline> is replaced by the
2429 application's name. The application documentation (converted
2430 from SGML into HTML with <fo:inline font-weight="bold">db2html</fo:inline>) should be
2431 placed in this directory too.
2432 </fo:block>
2433 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348850272">
2434 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">Note</fo:block>
2435 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2436 If the help files are not present in the correct directory, the
2437 menu items will NOT appear when the program is run.
2438 </fo:block>
2439 </fo:block>
2440 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2441 The <fo:inline font-family="Courier">topic.dat</fo:inline> file is used by the GNOME
2442 menu building code to generate the Help
2443 menu. When you define your menu:
2444 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
2445 GnomeUIInfo helpmenu[] = {
2446 {GNOME_APP_UI_ITEM,
2447 N_("About"), N_("Info about this program"),
2448 about_cb, NULL, NULL,
2449 GNOME_APP_PIXMAP_STOCK, GNOME_STOCK_MENU_ABOUT,
2450 0, 0, NULL},
2451 GNOMEUIINFO_SEPARATOR,
2452 GNOMEUIINFO_HELP("<fo:inline font-style="italic">appname</fo:inline>"),
2453 GNOMEUIINFO_END
2454 };
2455 </fo:block>
2456 the line specifying <fo:inline font-family="Courier">GNOMEUIINFO_HELP</fo:inline> causes
2457 GNOME to create a menu entry which is tied to the documentation
2458 in the directory mentioned above. Also, all the topics in the
2459 <fo:inline font-family="Courier">topic.dat</fo:inline> file will get menu entries in the
2460 Help menu. When the user selects any of these
2461 topics from the Help menu, a help browser
2462 will be started with the associated HTML documentation.
2463 </fo:block>
2464 </fo:block>
2465 <fo:block id="applicationhelpbuttons">
2466 <fo:block>
2467 <fo:block margin-left="-4pc" font-family="Helvetica">
2468 <fo:block keep-with-next.within-column="always">
2469 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Application Help Buttons</fo:block>
2470 </fo:block>
2471 </fo:block>
2472 </fo:block>
2473 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348777696">
2474 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">Developer Information</fo:block>
2475 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2476 This section is for developers. Documentation authors
2477 generally do not need to know this material.
2478 </fo:block>
2479 </fo:block>
2480 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2481 Most GNOME applications will have Help
2482 buttons. These are most often seen in Preference windows. (All
2483 Preference windows should have Help
2484 buttons.) Most Help buttons will connect
2485 to the application manual, although some may connect to special
2486 documents. Because the Help buttons do
2487 not generally have their own special documentation, the
2488 documentation author(s) do not need to do very much. However,
2489 the application author must be careful to guarantee that the
2490 application correctly opens the help documentation when the
2491 Help buttons are pressed.
2492 </fo:block>
2493 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2494 To make the Help buttons call the correct document in the GNOME Help
2495 Browser the developer should add code based on the following example:
2496 </fo:block>
2497 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
2498 gchar *tmp;
2499 tmp = gnome_help_file_find_file ("module", "page.html");
2500 if (tmp) {
2501 gnome_help_goto(0, tmp);
2502 g_free(tmp);
2503 }
2504 </fo:block>
2505 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348859104">
2506 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">NOTE</fo:block>
2507 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2508 The example above is in the C language, please refer to other
2509 documentation or forums for other GNOME language bindings.
2510 </fo:block>
2511 </fo:block>
2512 </fo:block>
2513 <fo:block id="packagingappletdocs">
2514 <fo:block>
2515 <fo:block margin-left="-4pc" font-family="Helvetica">
2516 <fo:block keep-with-next.within-column="always">
2517 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Packaging Applet Documentation</fo:block>
2518 </fo:block>
2519 </fo:block>
2520 </fo:block>
2521 <fo:block id="appletfiles">
2522 <fo:block>
2523 <fo:block margin-left="-4pc" font-family="Helvetica">
2524 <fo:block keep-with-next.within-column="always">
2525 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Applet Documentation Files</fo:block>
2526 </fo:block>
2527 </fo:block>
2528 </fo:block>
2529 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2530 In GNOME 2.0 each applet will have its own documentation
2531 installed separately, and the GNOME 2.0 help
2532 browser (Nautilus) will dynamically
2533 merge the applet documents into a single virtual book
2534 called <fo:inline font-style="italic">GNOME Applets</fo:inline>. During the
2535 transitionary stage between GNOME 1.0 and GNOME 2.0, each
2536 applet in the gnome-applets package has its own manual(stored
2537 with the applet in CVS), but they are merged together manually
2538 to create the <fo:inline font-style="italic">GNOME Applets</fo:inline> book before
2539 distribution. Telsa
2540 <fo:inline font-family="Courier">&lt;[email protected]&gt;</fo:inline> is the maintainer of
2541 this document. Applet documentation should be sent to Telsa
2542 (or placed in CVS) who will make sure they are correctly
2543 packaged with the applets. The applet author should be
2544 contacted to modify the menu items and help buttons to bind to
2545 the applet documentation if necessary.
2546 </fo:block>
2547 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2548 Images which are part of the applet documentation should be in
2549 PNG format and should reside in the same directory as the SGML
2550 document file in CVS(gnome-applets/APPLETNAME/help/C).
2551 </fo:block>
2552 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2553 Applets which are not part of the gnome-applets package must
2554 package their documentation with the particular applet
2555 package. They should use the same applet template as other
2556 applets. However, the <fo:inline font-family="Courier">&lt;xref&gt;</fo:inline> links to
2557 the introductory chapter of the <fo:inline font-style="italic">GNOME
2558 Applets</fo:inline> book must be removed (as the 1.x
2559 GNOME Help Browser does not allow
2560 you to create links between separate documents) and replaced
2561 with suitable text. Note that since this document is not part
2562 of the <fo:inline font-style="italic">GNOME Applets</fo:inline> book, you must
2563 remember to add <fo:inline font-family="Courier">&lt;legalnotice&gt;</fo:inline> and
2564 <fo:inline font-family="Courier">&lt;copyright&gt;</fo:inline> sections.
2565 </fo:block>
2566 </fo:block>
2567 <fo:block id="appletmenu">
2568 <fo:block>
2569 <fo:block margin-left="-4pc" font-family="Helvetica">
2570 <fo:block keep-with-next.within-column="always">
2571 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Adding Documentation to an Applet Menu</fo:block>
2572 </fo:block>
2573 </fo:block>
2574 </fo:block>
2575 <fo:block space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" start-indent="0.25in" end-indent="0.25in" id="idp106373348872928">
2576 <fo:block font-size="14pt" font-weight="bold" keep-with-next="always">Developer Information</fo:block>
2577 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2578 This section is for developers. Documentation authors
2579 generally do not need to know this material.
2580 </fo:block>
2581 </fo:block>
2582 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2583 Applets should have About and
2584 Manual menu items, typically as the first
2585 and second top-most items in the menu respectively. This
2586 section describes how the developer creates these menu items
2587 and links them to the documentation.
2588 </fo:block>
2589 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2590 To add an applet's manual to its applet menu, use:
2591 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
2592 /* add an item to the applet menu */
2593 applet_widget_register_callback(APPLET_WIDGET(applet), "manual",
2594 _("Manual"), &amp;open_manual, NULL);
2595 </fo:block>
2596 Here the second argument is an arbitrary name for the
2597 callback, the third argument is the label which will appear
2598 when the user right clicks on the applet, and the fourth
2599 argument is the callback function.
2600 </fo:block>
2601 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2602 You will need to write a simple callback function to open the
2603 help browser to the appropriate document. This is done using
2604 the <fo:inline font-family="Courier">gnome_help_file_find_file</fo:inline> function,
2605 as described in <fo:basic-link internal-destination="applicationhelpbuttons">the section called “Application Help Buttons”</fo:basic-link>.
2606 </fo:block>
2607 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2608 You will also want to add an About menu
2609 item to the applet's menu. This is a
2610 stock menu item and is done:
2611 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
2612 applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about",
2613 GNOME_STOCK_MENU_ABOUT, _("About"), &amp;my_applet_cb_about,
2614 NULL);
2615 </fo:block>
2616 </fo:block>
2617 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2618 More information can be found at <fo:basic-link external-destination="http://developer.gnome.org/doc/tutorials/applet/index.html">Writing
2619 GNOME panel applets using the GTK+/GTK-- widget set</fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/doc/tutorials/applet/index.html]</fo:inline>.
2620 </fo:block>
2621 </fo:block>
2622 </fo:block>
2623 <fo:block id="writingcontextsensitivehelp">
2624 <fo:block>
2625 <fo:block margin-left="-4pc" font-family="Helvetica">
2626 <fo:block keep-with-next.within-column="always">
2627 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Writing Context Sensitive Help (coming in GNOME-2.0)</fo:block>
2628 </fo:block>
2629 </fo:block>
2630 </fo:block>
2631 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2632 Context sensitive help, also known as "pop-up" help, will allow
2633 a user to obtain help information about specific buttons or
2634 parts of an application.
2635 </fo:block>
2636 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2637 Context sensitive help is still under development and not all
2638 the details are available at this time. However, the basics can
2639 be shown here so that you can understand how the system will
2640 work.
2641 </fo:block>
2642 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2643 The Context Sensitive Help system is designed to allow the
2644 developer to give an id to a particular portion of the User
2645 Interface, for example, a button. Once the interface is complete
2646 a Perl script can then be run against the interface code to
2647 create a "map" file. This map file allows the developer or
2648 writer to associate particular paragraph sections from an XML
2649 document to the interface items.
2650 </fo:block>
2651 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2652 The XML used for the document is a small XML DTD that is being
2653 developed to use the same tags (albeit, much fewer) as DocBook
2654 so that writers do not have to re-learn a new DTD.
2655 </fo:block>
2656 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2657 Once the document is written and map file is complete, when the
2658 user launches context sensitive help on the interface (either by
2659 pressing a button and then clicking on the interface item they
2660 want information on, or by right mouse clicking on the interface
2661 item and selecting a pop-up menu item like "What's This") a
2662 small transient window will appear with brief but detailed
2663 information on the interface item.
2664 </fo:block>
2665 </fo:block>
2666 <fo:block id="referring">
2667 <fo:block>
2668 <fo:block margin-left="-4pc" font-family="Helvetica">
2669 <fo:block keep-with-next.within-column="always">
2670 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Referring to Other GNOME Documentation (coming in
2671 GNOME-2.0)</fo:block>
2672 </fo:block>
2673 </fo:block>
2674 </fo:block>
2675 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2676 In the GNOME 2.0 Help System, you will be able to create links
2677 from one document to another. The exact mechanism for doing
2678 this is in development.
2679 </fo:block>
2680 </fo:block>
2681 <fo:block id="basics">
2682 <fo:block>
2683 <fo:block margin-left="-4pc" font-family="Helvetica">
2684 <fo:block keep-with-next.within-column="always">
2685 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Basics of Documentation Style</fo:block>
2686 </fo:block>
2687 </fo:block>
2688 </fo:block>
2689 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2690 Most people have never enjoyed reading a software manual, and
2691 they probably never will. Many times, they'll read the
2692 documentation only when they run into problems, and they'll be
2693 frustrated and upset before they even read a word. On the
2694 other hand, some readers will read the manual all the way
2695 through, or at least look at the introduction before they
2696 start. Your document might serve as a reference for an expert
2697 or a guide to a beginner, and it must have enough depth to
2698 satisfy the first without overwhelming the second. Ideally, it
2699 will serve beginners as they <fo:inline font-style="italic">become</fo:inline>
2700 experts. Remember, your goal is to produce <fo:inline font-style="italic">complete,
2701 intuitive and clear</fo:inline> documentation.
2702 </fo:block>
2703 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2704 In order to write useful documentation, you'll have to know who
2705 your audience is likely to be. Then, you can look for the
2706 problems they're likely to run into, and solve them. It will
2707 also help if you focus on the tasks users will perform, and
2708 group features accordingly, rather than simply describing
2709 features at random.
2710 </fo:block>
2711 <fo:block id="styleplanning">
2712 <fo:block>
2713 <fo:block margin-left="-4pc" font-family="Helvetica">
2714 <fo:block keep-with-next.within-column="always">
2715 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Planning</fo:block>
2716 </fo:block>
2717 </fo:block>
2718 </fo:block>
2719 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2720 Begin documenting by learning how to use the application and
2721 reading over any existing documentation. Pay attention to
2722 places where your document will differ from the template. It
2723 may help to develop a document skeleton: a valid XML or SGML
2724 document that has little or no content. For very large
2725 applications, you will need to make significant departures
2726 from the templates, since you'll be using the
2727 <fo:inline font-family="Courier">&lt;book&gt;</fo:inline> tag instead of
2728 <fo:inline font-family="Courier">&lt;chapter&gt;</fo:inline> or
2729 <fo:inline font-family="Courier">&lt;article&gt;</fo:inline>.
2730 </fo:block>
2731 </fo:block>
2732 <fo:block id="balance">
2733 <fo:block>
2734 <fo:block margin-left="-4pc" font-family="Helvetica">
2735 <fo:block keep-with-next.within-column="always">
2736 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Achieving a Balanced Style</fo:block>
2737 </fo:block>
2738 </fo:block>
2739 </fo:block>
2740 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2741 Just as you need to juggle expert and novice readers,
2742 you'll have to juggle a number of other extremes as you write:
2743 <fo:list-block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348901152" provisional-distance-between-starts="1.5em" provisional-label-separation="0.2em"><fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348901536"><fo:list-item-label end-indent="label-end()"><fo:block>•</fo:block></fo:list-item-label><fo:list-item-body start-indent="body-start()"><fo:block>
2744 Documents should be complete, yet concise. You should
2745 describe every feature, but you'll have decide how much
2746 detail is really necessary. It's not, for example,
2747 necessary to describe every button and form field in a
2748 dialog box, but you should make sure that your readers
2749 know how to bring up the dialog and what it does. If
2750 you spend fewer words on the obvious, you can spend more
2751 time clarifying the ambiguous labels and explaining
2752 items that are more complex.
2753 </fo:block></fo:list-item-body></fo:list-item><fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348902688"><fo:list-item-label end-indent="label-end()"><fo:block>•</fo:block></fo:list-item-label><fo:list-item-body start-indent="body-start()"><fo:block>
2754 Be engaging and friendly, yet professional. Games
2755 documents may be less formal than productivity
2756 application documents (people don't
2757 <fo:inline font-style="italic">use</fo:inline> games, they
2758 <fo:inline font-style="italic">play</fo:inline> them), but all of them should
2759 maintain a standard of style which holds the reader's
2760 interest without resorting to jokes and untranslatable
2761 allusions or puns.
2762 </fo:block></fo:list-item-body></fo:list-item><fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348904992"><fo:list-item-label end-indent="label-end()"><fo:block>•</fo:block></fo:list-item-label><fo:list-item-body start-indent="body-start()"><fo:block>
2763 Examples, tips, notes, and screenshots are useful to
2764 break up long stretches of text, but too many can get in
2765 the way, and make your documents too choppy to read.
2766 It's good to provide a screenshot of any dialog windows
2767 a user might run into, but if a dialog box has several
2768 tabs, it's not usually necessary to have one for each.
2769 </fo:block></fo:list-item-body></fo:list-item><fo:list-item space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em" id="idp106373348906144"><fo:list-item-label end-indent="label-end()"><fo:block>•</fo:block></fo:list-item-label><fo:list-item-body start-indent="body-start()"><fo:block>
2770 The GDP strives to have all of its documentation conform
2771 to certain standards of style and content, but every
2772 document (and every writer) is different. You will need
2773 to use your judgement, and write documents to fit with
2774 the rest of the project, without compromising the
2775 individual needs of your subject, or your own
2776 individuality as a writer.
2777 </fo:block></fo:list-item-body></fo:list-item></fo:list-block>
2778 </fo:block>
2779 </fo:block>
2780 <fo:block id="stylestructure">
2781 <fo:block>
2782 <fo:block margin-left="-4pc" font-family="Helvetica">
2783 <fo:block keep-with-next.within-column="always">
2784 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Structure</fo:block>
2785 </fo:block>
2786 </fo:block>
2787 </fo:block>
2788 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2789 In general, you won't have to worry too much about structure,
2790 because the templates provide you with an excellent example.
2791 As a general rule, try to follow that structural example.
2792 That means using links, hierarchical nesting, and, if
2793 necessary, a glossary or index. You probably won't need to
2794 use every available structural tag, but take advantage of
2795 what DocBook provides you.
2796 </fo:block>
2797 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2798 As to linking, there's some disagreement about whether to use
2799 <fo:inline font-family="Courier">&lt;xref&gt;</fo:inline> <fo:inline font-family="Courier">&lt;link&gt;</fo:inline>
2800 when you make links within your documents. You'll have to
2801 decide, based on the different ways that they are presented
2802 in output, which is more appropriate given the context.
2803 Regardless of which you use, you should not forget to use
2804 them. Help your readers find information that relevant to
2805 the issue at hand.
2806 </fo:block>
2807 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2808 The table of contents will be generated automatically, but
2809 you will probably have to develop your own index if you wish
2810 to have one. The Nautilus Help Browser will have new, and
2811 currently unknown, indexing capabilities, so index style and
2812 structure are still under discussion. The GNOME User's Guide
2813 will contain a glossary in its next versions; unless you're
2814 writing a<fo:inline font-family="Courier">&lt;book&gt;</fo:inline>, it will probably be best to
2815 contribute to that rather than developing your own.
2816 </fo:block>
2817 </fo:block>
2818 <fo:block id="stylegrammar">
2819 <fo:block>
2820 <fo:block margin-left="-4pc" font-family="Helvetica">
2821 <fo:block keep-with-next.within-column="always">
2822 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Grammar and Spelling</fo:block>
2823 </fo:block>
2824 </fo:block>
2825 </fo:block>
2826 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2827 Nobody expects you to be perfect; they just expect the
2828 documentation for their software to be error-free. That means
2829 that, in the same way that developers look for bugs and accept
2830 bug reports, writers must check for errors in their documents.
2831 Poor grammar, bad spelling, and gross technical errors in
2832 draft documents are fine. However, if those problems show up
2833 in a "real" release, they can count against the credibility of
2834 GNOME and Linux. They'll also make you look bad.
2835 </fo:block>
2836 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2837 There is no substitute for a human proofreader; use a
2838 spell-check program, then read it over yourself, and then find
2839 someone else to help you. Other GDP members are, of course,
2840 willing and able to help you, but non-writers are often at
2841 least as helpful.
2842 </fo:block>
2843 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2844 Proofreading documents is both a also a good way to
2845 familiarize yourself with documentation, and it certainly
2846 makes you valuable to the GDP. Help other writers proof their
2847 documents, and they will help you with yours.
2848 </fo:block>
2849 </fo:block>
2850 </fo:block>
2851 <fo:block id="teamwork">
2852 <fo:block>
2853 <fo:block margin-left="-4pc" font-family="Helvetica">
2854 <fo:block keep-with-next.within-column="always">
2855 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Teamwork</fo:block>
2856 </fo:block>
2857 </fo:block>
2858 </fo:block>
2859 <fo:block id="teamworkgdp">
2860 <fo:block>
2861 <fo:block margin-left="-4pc" font-family="Helvetica">
2862 <fo:block keep-with-next.within-column="always">
2863 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Working With The GDP Team</fo:block>
2864 </fo:block>
2865 </fo:block>
2866 </fo:block>
2867 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2868 The GDP team is a valuable resource for any documentation
2869 author. GDP members can answer most questions documentation
2870 authors have during the course of their work. It is also
2871 important to make sure you are not duplicating work of other
2872 GDP members by visiting the <fo:inline font-style="italic">GDP Documentation
2873 Status Table</fo:inline> (<fo:basic-link external-destination="http://www.gnome.org/gdp/doctable/">http://www.gnome.org/gdp/doctable/</fo:basic-link><fo:inline hyphenate="false"> [http://www.gnome.org/gdp/doctable/]</fo:inline>) and
2874 assigning a documentation item to yourself. This table also
2875 provides a forum for making suggestions and announcements for
2876 each documentation item. The best way to get in touch with
2877 GDP members is on the #docs IRC channel at irc.gnome.org or
2878 else by emailing the <fo:basic-link external-destination="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
2879 <fo:inline font-style="italic">gnome-doc-list mailing list</fo:inline></fo:basic-link><fo:inline hyphenate="false"> [http://mail.gnome.org/mailman/listinfo/gnome-doc-list/]</fo:inline>.
2880 </fo:block>
2881 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2882 After an author has finished a document (or even a draft
2883 version of the document), it is a good idea to ask a member of
2884 the GDP team to read the document, checking it for grammar,
2885 proper DocBook markup, and clarity. One may typically find
2886 another author to do this by either asking on the #docs IRC
2887 channel at irc.gnome.org or by emailing the <fo:basic-link external-destination="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
2888 <fo:inline font-style="italic">gnome-doc-list mailing list</fo:inline></fo:basic-link><fo:inline hyphenate="false"> [http://mail.gnome.org/mailman/listinfo/gnome-doc-list/]</fo:inline>.
2889 </fo:block>
2890 </fo:block>
2891 <fo:block id="teamworkdevelopers">
2892 <fo:block>
2893 <fo:block margin-left="-4pc" font-family="Helvetica">
2894 <fo:block keep-with-next.within-column="always">
2895 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Working With Developers</fo:block>
2896 </fo:block>
2897 </fo:block>
2898 </fo:block>
2899 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2900 Writing documentation typically involves a certain amount of
2901 interaction with the developers of GNOME or the application
2902 which is being documented. Often a document author will need
2903 to ask the developer technical questions during the course of
2904 writing a document. After the document is finished, it is good
2905 idea to ask the developer to read the document to make sure it
2906 is technically correct. The documentation author should also
2907 make sure that the application author correctly binds and
2908 packages the documentation with the application.
2909 </fo:block>
2910 </fo:block>
2911 </fo:block>
2912 <fo:block id="finishing">
2913 <fo:block>
2914 <fo:block margin-left="-4pc" font-family="Helvetica">
2915 <fo:block keep-with-next.within-column="always">
2916 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Finishing A Document</fo:block>
2917 </fo:block>
2918 </fo:block>
2919 </fo:block>
2920 <fo:block id="editting">
2921 <fo:block>
2922 <fo:block margin-left="-4pc" font-family="Helvetica">
2923 <fo:block keep-with-next.within-column="always">
2924 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Editing The Document</fo:block>
2925 </fo:block>
2926 </fo:block>
2927 </fo:block>
2928 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2929 When the document is finished, the document should be edited
2930 by another member of the GDP for spelling, clarity, and
2931 DocBook markup. It should also be read by an application
2932 author to make sure the document is technically accurate.
2933 </fo:block>
2934 </fo:block>
2935 <fo:block id="submitting">
2936 <fo:block>
2937 <fo:block margin-left="-4pc" font-family="Helvetica">
2938 <fo:block keep-with-next.within-column="always">
2939 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Submitting The Document</fo:block>
2940 </fo:block>
2941 </fo:block>
2942 </fo:block>
2943 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2944 After the document has been edited and checked for technical
2945 accuracy, it is ready to be combined with the application or
2946 documentation package. This is typically done by passing the
2947 document to the application or package developer. In some
2948 cases, the documents can be committed directly into CVS,
2949 however this should only be done after obtaining permission to
2950 make CVS commits from the developer. Note that in many cases,
2951 the application may need to be modified to correctly link to
2952 the documentation. The packaging system (tarballs and binary
2953 packages) may also need to be modified to include the
2954 documentation in the package. Generally, this should be done
2955 by the developers.
2956 </fo:block>
2957 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2958 The final step is to email the GNOME Translation Team at
2959 <fo:inline font-family="Courier">&lt;[email protected]&gt;</fo:inline> to notify them that
2960 there is a new document for them to translate.
2961 </fo:block>
2962 </fo:block>
2963 </fo:block>
2964 <fo:block id="resources">
2965 <fo:block>
2966 <fo:block margin-left="-4pc" font-family="Helvetica">
2967 <fo:block keep-with-next.within-column="always">
2968 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Resources</fo:block>
2969 </fo:block>
2970 </fo:block>
2971 </fo:block>
2972 <fo:block id="resourcesweb">
2973 <fo:block>
2974 <fo:block margin-left="-4pc" font-family="Helvetica">
2975 <fo:block keep-with-next.within-column="always">
2976 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Resources On The Web</fo:block>
2977 </fo:block>
2978 </fo:block>
2979 </fo:block>
2980 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em"> The <fo:basic-link external-destination="http://developer.gnome.org/projects/gdp/">GNOME
2981 Documentation Project Web page</fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/projects/gdp/]</fo:inline> lists current GDP
2982 projects and members.
2983 </fo:block>
2984 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2985 The <fo:basic-link external-destination="http://www.gnome.org/gdp/doctable/">GDP Documentation Status Table</fo:basic-link><fo:inline hyphenate="false"> [http://www.gnome.org/gdp/doctable/]</fo:inline> tracks the
2986 status of all the various documentation components of GNOME.
2987 </fo:block>
2988 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
2989 Norman Walsh's <fo:basic-link external-destination="http://www.docbook.org"> <fo:inline font-style="italic">DocBook: The Definitive
2990 Guide</fo:inline></fo:basic-link><fo:inline hyphenate="false"> [http://www.docbook.org]</fo:inline> in an excellent book on DocBook,
2991 available both online and in print.
2992 </fo:block>
2993 </fo:block>
2994 <fo:block id="resourcesbooks">
2995 <fo:block>
2996 <fo:block margin-left="-4pc" font-family="Helvetica">
2997 <fo:block keep-with-next.within-column="always">
2998 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Books</fo:block>
2999 </fo:block>
3000 </fo:block>
3001 </fo:block>
3002 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
3003 Docbook: The Definitive Guide is available in both printed
3004 form and on the web at:
3005 <fo:basic-link external-destination="http://www.docbook.org/tdg/index.html">
3006 <fo:inline font-style="italic">Docbook: The Definitive Guide</fo:inline>
3007 </fo:basic-link><fo:inline hyphenate="false"> [http://www.docbook.org/tdg/index.html]</fo:inline>
3008 </fo:block>
3009 </fo:block>
3010 <fo:block id="mailinglists">
3011 <fo:block>
3012 <fo:block margin-left="-4pc" font-family="Helvetica">
3013 <fo:block keep-with-next.within-column="always">
3014 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Mailing Lists</fo:block>
3015 </fo:block>
3016 </fo:block>
3017 </fo:block>
3018 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
3019 The <fo:inline font-style="italic">gnome-docs-list</fo:inline> mailing list is the
3020 main discussion area for all contributors to the GNOME
3021 Documentation Project. You can find out how to subscribe to
3022 this list on <fo:basic-link external-destination="http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing Lists</fo:basic-link><fo:inline hyphenate="false"> [http://www.gnome.org/resources/mailing-lists.html]</fo:inline>. This is a rather
3023 low-volume list, so you will not be flooded with messages.
3024 </fo:block>
3025 </fo:block>
3026 <fo:block id="irc">
3027 <fo:block>
3028 <fo:block margin-left="-4pc" font-family="Helvetica">
3029 <fo:block keep-with-next.within-column="always">
3030 <fo:block font-size="14pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">IRC</fo:block>
3031 </fo:block>
3032 </fo:block>
3033 </fo:block>
3034 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
3035 Internet Relay Chat (IRC) is a fast and easy way to get in
3036 touch with other GDP members. There are generally at least a
3037 few members here who can answer questions or discuss
3038 documentation issues. The IRC channel is #docs at
3039 irc.gnome.org.
3040 </fo:block>
3041 </fo:block>
3042 </fo:block>
3043 <fo:block id="templates">
3044 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Document Templates</fo:block>
3045 <fo:block id="template1">
3046 <fo:block>
3047 <fo:block margin-left="-4pc" font-family="Helvetica">
3048 <fo:block keep-with-next.within-column="always">
3049 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Template 1: Application Manual</fo:block>
3050 </fo:block>
3051 </fo:block>
3052 </fo:block>
3053 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
3054 The following template should be used for all application
3055 manuals. You can always get the latest copy of this
3056 template from <fo:basic-link external-destination="http://developer.gnome.org/projects/gdp/templates.html">GDP
3057 Documentation Templates</fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/projects/gdp/templates.html]</fo:inline>.
3058 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
3059
3060
3061 &lt;!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
3062 &lt;!-- if not using PNG graphic, replace reference above with
3063 .....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
3064 --&gt;
3065 &lt;!ENTITY version "1.0.53"&gt;
3066 &lt;!-- replace version above with actual application version number--&gt;
3067 &lt;!-- Template Version: 1.0.1 (do not remove this line) --&gt;
3068 ]&gt;
3069
3070
3071 &lt;!-- This is a GNOME documentation template, designed by the GNOME
3072 Documentation Project Team. Please use it for writing GNOME
3073 documentation, making obvious changes. In particular, all the words
3074 written in UPPERCASE (with the exception of GNOME) should be
3075 replaced. As for "legalnotice", please leave the reference
3076 unchanged.
3077
3078 Remember that this is a guide, rather than a perfect model to follow
3079 slavishly. Make your manual logical and readable. And don't forget
3080 to remove these comments in your final documentation! ;-)
3081 --&gt;
3082
3083 &lt;!-- =============Document Header ============================= --&gt;
3084
3085 &lt;article id="index"&gt; &lt;!-- please do not change the id --&gt;
3086
3087 &lt;artheader&gt;
3088 &lt;title&gt;MY-GNOME-APP&lt;/title&gt;
3089 &lt;copyright&gt;
3090 &lt;year&gt;2000&lt;/year&gt;
3091 &lt;holder&gt;ME-THE-AUTHOR&lt;/holder&gt;
3092 &lt;/copyright&gt;
3093
3094 &lt;!-- translators: uncomment this:
3095
3096 &lt;copyright&gt;
3097 &lt;year&gt;2000&lt;/year&gt;
3098 &lt;holder&gt;ME-THE-TRANSLATOR (Latin translation)&lt;/holder&gt;
3099 &lt;/copyright&gt;
3100
3101 --&gt;
3102
3103 &lt;!-- do not put authorname in the header except in copyright - use
3104 section "authors" below --&gt;
3105
3106 &lt;legalnotice&gt;
3107 &lt;para&gt;
3108 Permission is granted to copy, distribute and/or modify this
3109 document under the terms of the &lt;citetitle&gt;GNU Free
3110 Documentation License&lt;/citetitle&gt;, Version 1.1 or any later
3111 version published by the Free Software Foundation with no
3112 Invariant Sections, no Front-Cover Texts, and no Back-Cover
3113 Texts. You may obtain a copy of the &lt;citetitle&gt;GNU Free
3114 Documentation License&lt;/citetitle&gt; from the Free Software
3115 Foundation by visiting &lt;ulink type="http"
3116 url="http://www.fsf.org"&gt;their Web site&lt;/ulink&gt; or by writing
3117 to: Free Software Foundation, Inc., 59 Temple Place - Suite
3118 330, Boston, MA 02111-1307, USA.
3119 &lt;/para&gt;
3120 &lt;para&gt;
3121 Many of the names used by companies to distinguish their
3122 products and services are claimed as trademarks. Where those
3123 names appear in any GNOME documentation, and those trademarks
3124 are made aware to the members of the GNOME Documentation
3125 Project, the names have been printed in caps or initial caps.
3126 &lt;/para&gt;
3127 &lt;/legalnotice&gt;
3128
3129 &lt;!-- this is the version of manual, not application --&gt;
3130 &lt;releaseinfo&gt;
3131 This is version 1.0 of MY-GNOME-APP manual.
3132 &lt;/releaseinfo&gt;
3133
3134 &lt;/artheader&gt;
3135
3136 &lt;!-- ============= Document Body ============================= --&gt;
3137
3138 &lt;!-- ============= Introduction ============================== --&gt;
3139 &lt;sect1 id="intro"&gt;
3140 &lt;title&gt;Introduction&lt;/title&gt;
3141
3142 &lt;para&gt;
3143 &lt;application&gt;MY-GNOME-APP&lt;/application&gt; is an application which
3144 proves mathematical theorems. It has all the basic features
3145 expected from a mathematical theorem prover, as well as a number
3146 of advanced ones, such as proof by confusion. In fact, many of
3147 the proofs produced by &lt;application&gt;MY-GNOME-APP&lt;/application&gt;
3148 are so complex that they are capable of proving almost anything
3149 with a virtually null likelihood of being disproven. It also has
3150 the very popular predecessor of proof by confusion, proof by
3151 dialog, first implemented by Plato.
3152 &lt;/para&gt;
3153 &lt;para&gt;
3154 It also allows you to save and print theorem proofs and to add
3155 comments to the proofs it produces.
3156 &lt;/para&gt;
3157
3158 &lt;para&gt;
3159 To run &lt;application&gt;MY-GNOME-APP&lt;/application&gt;, select
3160 &lt;menuchoice&gt;
3161 &lt;guisubmenu&gt;SUBMENU&lt;/guisubmenu&gt;
3162 &lt;guimenuitem&gt;MY-GNOME-APP&lt;/guimenuitem&gt;
3163 &lt;/menuchoice&gt;
3164 from the &lt;guimenu&gt;Main Menu&lt;/guimenu&gt;, or type
3165 &lt;command&gt;MYGNOMEAPP&lt;/command&gt; on the command line.
3166 &lt;/para&gt;
3167
3168 &lt;para&gt;
3169 &lt;application&gt;MY-GNOME-APP&lt;/application&gt; is included in the
3170 &lt;filename&gt;GNOME-PACKAGE&lt;/filename&gt; package, which is part of the
3171 GNOME desktop environment. This document describes version
3172 &amp;version; of &lt;application&gt;MY-GNOME-APP&lt;/application&gt;.
3173 &lt;/para&gt;
3174 &lt;/sect1&gt;
3175
3176
3177 &lt;!-- ================ Usage ================================ --&gt;
3178 &lt;!-- This section should describe basic usage of the application. --&gt;
3179
3180 &lt;sect1 id="usage"&gt;
3181 &lt;title&gt;Using MY-GNOME-APP&lt;/title&gt;
3182 &lt;para&gt;
3183 &lt;application&gt;MY-GNOME-APP&lt;/application&gt; can be used to produce a
3184 perfect proof of &lt;emphasis&gt;any&lt;/emphasis&gt; mathematical theorem
3185 (provided, of course, that this theorem is correct), thus
3186 providing for new users an easy-to-use graphical interface to
3187 modern mathematics. This section describes basic usage of
3188 &lt;application&gt;MY-GNOME-APP&lt;/application&gt;.
3189 &lt;/para&gt;
3190
3191 &lt;!-- ========= Basic Usage =========================== --&gt;
3192 &lt;sect2 id="mainwin"&gt;
3193 &lt;title&gt;Basic usage&lt;/title&gt;
3194 &lt;para&gt;
3195 Starting &lt;application&gt;MY-GNOME-APP&lt;/application&gt; opens the
3196 &lt;interface&gt;Main window&lt;/interface&gt;, shown in &lt;xref
3197 linkend="mainwindow-fig"&gt;. The window is at first empty.
3198
3199 &lt;!-- ==== Figure ==== --&gt;
3200 &lt;figure id="mainwindow-fig"&gt;
3201 &lt;title&gt;MY-GNOME-APP Main Window&lt;/title&gt;
3202 &lt;screenshot&gt;
3203 &lt;screeninfo&gt;MY-GNOME-APP Main Window&lt;/screeninfo&gt;
3204 &lt;graphic fileref="SCREENSHOT" format="png" srccredit="ME"&gt;
3205 &lt;/graphic&gt;
3206 &lt;/screenshot&gt;
3207 &lt;/figure&gt;
3208 &lt;!-- ==== End of Figure ==== --&gt;
3209 &lt;/para&gt;
3210
3211
3212 &lt;!-- For this app, one could put "proving" or "edit" (probably even
3213 both of them) as sect2's seperate from the main window
3214 section. Since they were both so closely involved with the main
3215 window, I decided to have them as sect3's isntead. Judgement
3216 call. --&gt;
3217
3218 &lt;sect3 id="proving"&gt;
3219 &lt;title&gt;Proving a Theorem&lt;/title&gt;
3220 &lt;para&gt;
3221 To get a proof of a theorem, select
3222 &lt;menuchoice&gt;
3223 &lt;guisubmenu&gt;File&lt;/guisubmenu&gt;
3224 &lt;guimenuitem&gt;New&lt;/guimenuitem&gt;
3225 &lt;/menuchoice&gt;,
3226 which will
3227 bring up the &lt;interface&gt;New Proof&lt;/interface&gt; dialog box.
3228 Enter the statement of the theorem in the
3229 &lt;guilabel&gt;Theorem statement&lt;/guilabel&gt; field, select your
3230 desired proof type from the drop-down menu, and and press
3231 &lt;guibutton&gt;Prove!&lt;/guibutton&gt;.
3232 &lt;/para&gt;
3233 &lt;para&gt;
3234 If &lt;application&gt;MY-GNOME-APP&lt;/application&gt; cannot prove the
3235 theorem by the method you have chosen, or if you have not
3236 selected a proof type at all,
3237 &lt;application&gt;MY-GNOME-APP&lt;/application&gt; will attempt to
3238 choose the one that it thinks is most conclusive. In order,
3239 it will attempt to prove the theorem with the following techniques:
3240
3241 &lt;variablelist&gt;
3242 &lt;varlistentry&gt;
3243 &lt;term&gt;Deduction&lt;/term&gt;
3244 &lt;listitem&gt;
3245 &lt;para&gt;
3246 This is a proof method that is generally accepted
3247 for full credit by Logic professors.
3248 &lt;/para&gt;
3249 &lt;/listitem&gt;
3250 &lt;/varlistentry&gt;
3251 &lt;varlistentry&gt;
3252 &lt;term&gt;Induction&lt;/term&gt;
3253 &lt;listitem&gt;
3254 &lt;para&gt;
3255 This logical style will also earn you full credit on
3256 your homework.
3257 &lt;/para&gt;
3258 &lt;/listitem&gt;
3259 &lt;/varlistentry&gt;
3260 &lt;varlistentry&gt;
3261 &lt;term&gt;Dialog&lt;/term&gt;
3262 &lt;listitem&gt;
3263 &lt;para&gt;
3264 This logical method is best for Philosophy classes,
3265 and will probably only merit partial credit on Logic
3266 or Mathematics homework.
3267 &lt;/para&gt;
3268 &lt;/listitem&gt;
3269 &lt;/varlistentry&gt;
3270 &lt;varlistentry&gt;
3271 &lt;term&gt;Confusion&lt;/term&gt;
3272 &lt;listitem&gt;
3273 &lt;para&gt;
3274 Suitable only for political debates, battles of wits
3275 against the unarmed, and Philosophy classes focusing
3276 on the works of Kant. Use with caution.
3277 &lt;/para&gt;
3278 &lt;/listitem&gt;
3279 &lt;/varlistentry&gt;
3280 &lt;/variablelist&gt;
3281 &lt;/para&gt;
3282
3283 &lt;!-- You might want to include a note, warning, or tip, e.g. --&gt;
3284
3285 &lt;warning&gt;
3286 &lt;title&gt;Proving Incorrect Theorms&lt;/title&gt;
3287 &lt;para&gt;
3288 &lt;application&gt;MY-GNOME-APP&lt;/application&gt; cannot prove
3289 incorrect theorems. If the theorem you have entered is not
3290 demonstrably true, you will get a message to that effect
3291 in the main window. To disprove a theorem, ask
3292 &lt;application&gt;MY-GNOME-APP&lt;/application&gt; to prove its
3293 logical inverse.
3294 &lt;/para&gt;
3295 &lt;/warning&gt;
3296 &lt;/sect3&gt;
3297 &lt;sect3 id="editing"&gt;
3298 &lt;title&gt;Editing Proofs&lt;/title&gt;
3299 &lt;para&gt;
3300 Once you have proven the theorem, it will be displayed in
3301 the &lt;interface&gt;main window&lt;/interface&gt;. There, you can read
3302 it over, choose text styles for different portions of it,
3303 and make comments on it. This section will guide you through
3304 that process.
3305 &lt;/para&gt;
3306 &lt;para&gt;
3307 To alter text styles, first select the statement you wish to
3308 change by clicking on it once. You can select several
3309 statements by Then, choose the style you want to apply from
3310 the &lt;guisubmenu&gt;Style&lt;/guisubmenu&gt; submenu of the
3311 &lt;guimenu&gt;Edit&lt;/guimenu&gt; menu.
3312 &lt;application&gt;MY-GNOME-APP&lt;/application&gt; will convert the
3313 text to that style.
3314 &lt;/para&gt;
3315 &lt;para&gt;
3316 You can also enter comments on a statement by selecting that
3317 statement, and then beginning to type. Comments will appear
3318 after the statement you have selected.
3319 &lt;/para&gt;
3320
3321 &lt;note&gt;
3322 &lt;title&gt;Altering The Proofs Themselves&lt;/title&gt;
3323 &lt;para&gt;
3324 &lt;application&gt;MY-GNOME-APP&lt;/application&gt; does not allow you
3325 to alter a proof it has produced itself. You can, save
3326 your proof as a plain text file (using the
3327 &lt;guimenuitem&gt;Save as...&lt;/guimenuitem&gt; menu), and alter it
3328 that way. Be aware, however, that
3329 &lt;application&gt;MY-GNOME-APP&lt;/application&gt; uses its own file
3330 format for saved proofs, and cannot re-open a file unless
3331 it is in the .mga format.
3332 &lt;/para&gt;
3333 &lt;/note&gt;
3334 &lt;/sect3&gt;
3335
3336
3337 &lt;!-- If there are other functions performed from the main window,
3338 they belong here. --&gt;
3339
3340 &lt;/sect2&gt;
3341
3342 &lt;!-- =========================================================
3343 Additional Sect2's should describe additional windows, such as
3344 larger dialog boxes, or functionality that differs significantly
3345 from the most immediate functions of the application. Make the
3346 structure logical.
3347 ============================================================= --&gt;
3348
3349
3350 &lt;sect2 id="toolbar"&gt;
3351 &lt;title&gt;Toolbar&lt;/title&gt;
3352 &lt;para&gt;
3353 The toolbar (shown in &lt;xref linkend="figure-usage-toolbar"&gt;)
3354 provides access to several commonly used routines.
3355 &lt;figure id="figure-usage-toolbar"&gt;
3356 &lt;title&gt;MY-GNOME-APP Toolbar&lt;/title&gt;
3357 &lt;screenshot&gt;
3358 &lt;screeninfo&gt;MY-GNOME-APP Toolbar&lt;/screeninfo&gt;
3359 &lt;graphic fileref="usage-toolbar.png" format="png"&gt;&lt;/graphic&gt;
3360 &lt;/screenshot&gt;
3361 &lt;/figure&gt;
3362 &lt;variablelist&gt;
3363 &lt;varlistentry&gt;
3364 &lt;term&gt;New&lt;/term&gt;
3365 &lt;listitem&gt;
3366 &lt;para&gt;
3367 Brings up the &lt;interface&gt;New Theorem&lt;/interface&gt;
3368 dialog.
3369 &lt;/para&gt;
3370 &lt;/listitem&gt;
3371 &lt;/varlistentry&gt;
3372 &lt;varlistentry&gt;
3373 &lt;term&gt;Open&lt;/term&gt;
3374 &lt;listitem&gt;
3375 &lt;para&gt;
3376 Open an exisiting theorem you want to prove, or a
3377 completed proof you wish to print or format.
3378 &lt;/para&gt;
3379 &lt;/listitem&gt;
3380 &lt;/varlistentry&gt;
3381 &lt;varlistentry&gt;
3382 &lt;term&gt;Save&lt;/term&gt;
3383 &lt;listitem&gt;
3384 &lt;para&gt;
3385 Save the current theorem permanently in a
3386 file.
3387 &lt;/para&gt;
3388 &lt;/listitem&gt;
3389 &lt;/varlistentry&gt;
3390 &lt;/variablelist&gt;
3391 &lt;/para&gt;
3392 &lt;/sect2&gt;
3393 &lt;!-- ========= Menus =========================== --&gt;
3394
3395 &lt;sect2 id="menubar"&gt;
3396
3397 &lt;!-- Describing the menubar ensures comprehensive feature
3398 coverage. Nest itemizedlists inside variablelists so that each
3399 menu is easily located by indexing software. Proper indentation
3400 makes it easier! --&gt;
3401
3402 &lt;title&gt;Menus&lt;/title&gt;
3403 &lt;para&gt;
3404 The menu bar, located at the top of the &lt;interface&gt;Main
3405 Window&lt;/interface&gt;, contains the following menus:
3406 &lt;/para&gt;
3407 &lt;variablelist&gt;
3408 &lt;varlistentry&gt;
3409 &lt;term&gt;&lt;guimenu&gt;File&lt;/guimenu&gt;&lt;/term&gt;
3410 &lt;listitem&gt;
3411 &lt;para&gt;
3412 This menu contains:
3413 &lt;itemizedlist&gt;
3414 &lt;listitem&gt;
3415 &lt;para&gt;
3416 &lt;menuchoice&gt;
3417 &lt;shortcut&gt;
3418 &lt;keycap&gt;F3&lt;/keycap&gt;
3419 &lt;/shortcut&gt;
3420 &lt;guimenuitem&gt;Open&lt;/guimenuitem&gt;
3421 &lt;/menuchoice&gt;
3422 &amp;mdash; This opens a file which is saved on your computer.
3423 &lt;/para&gt;
3424 &lt;/listitem&gt;
3425 &lt;listitem&gt;
3426 &lt;para&gt;
3427 &lt;menuchoice&gt;
3428 &lt;shortcut&gt;
3429 &lt;keycombo&gt;&lt;keycap&gt;Ctrl&lt;/keycap&gt;&lt;keycap&gt;S&lt;/keycap&gt;&lt;/keycombo&gt;
3430 &lt;/shortcut&gt;
3431 &lt;guimenuitem&gt;Save&lt;/guimenuitem&gt;
3432 &lt;/menuchoice&gt;
3433 &amp;mdash; This saves your file.
3434 &lt;/para&gt;
3435 &lt;/listitem&gt;
3436 &lt;listitem&gt;
3437 &lt;para&gt;
3438 &lt;menuchoice&gt;
3439 &lt;shortcut&gt;
3440 &lt;keycombo&gt;&lt;keycap&gt;Ctrl&lt;/keycap&gt;&lt;keycap&gt;W&lt;/keycap&gt;&lt;/keycombo&gt;
3441 &lt;/shortcut&gt;
3442 &lt;guimenuitem&gt;Close&lt;/guimenuitem&gt;
3443 &lt;/menuchoice&gt;
3444 &amp;mdash; This closes your file.
3445 &lt;/para&gt;
3446 &lt;/listitem&gt;
3447 &lt;listitem&gt;
3448 &lt;para&gt;
3449 &lt;menuchoice&gt;
3450 &lt;shortcut&gt;
3451 &lt;keycombo&gt;&lt;keycap&gt;Ctrl&lt;/keycap&gt;&lt;keycap&gt;Q&lt;/keycap&gt;&lt;/keycombo&gt;
3452 &lt;/shortcut&gt;
3453 &lt;guimenuitem&gt;Exit&lt;/guimenuitem&gt;
3454 &lt;/menuchoice&gt;
3455 &amp;mdash; This quits the application.
3456 &lt;/para&gt;
3457 &lt;/listitem&gt;
3458 &lt;/itemizedlist&gt;
3459 &lt;/para&gt;
3460 &lt;/listitem&gt;
3461 &lt;/varlistentry&gt;
3462
3463 &lt;varlistentry&gt;
3464 &lt;term&gt;&lt;guimenu&gt;Edit&lt;/guimenu&gt;&lt;/term&gt;
3465 &lt;listitem&gt;
3466 &lt;para&gt;
3467 This menu contains:
3468 &lt;itemizedlist&gt;
3469 &lt;listitem&gt;
3470 &lt;para&gt;
3471 &lt;menuchoice&gt;
3472 &lt;shortcut&gt;
3473 &lt;keycombo&gt;&lt;keycap&gt;Ctrl&lt;/keycap&gt;&lt;keycap&gt;X&lt;/keycap&gt;&lt;/keycombo&gt;
3474 &lt;/shortcut&gt;
3475 &lt;guimenuitem&gt;Cut&lt;/guimenuitem&gt;
3476 &lt;/menuchoice&gt;
3477 &amp;mdash; This removes any text or data which is selected and
3478 places it in the buffer.
3479 &lt;/para&gt;
3480 &lt;/listitem&gt;
3481 &lt;listitem&gt;
3482 &lt;para&gt;
3483 &lt;menuchoice&gt;
3484 &lt;shortcut&gt;
3485 &lt;keycombo&gt;&lt;keycap&gt;Ctrl&lt;/keycap&gt;&lt;keycap&gt;C&lt;/keycap&gt;&lt;/keycombo&gt;
3486 &lt;/shortcut&gt;
3487 &lt;guimenuitem&gt;Copy&lt;/guimenuitem&gt;
3488 &lt;/menuchoice&gt;
3489 &amp;mdash; This copies any text or data which is selected into
3490 the buffer.
3491 &lt;/para&gt;
3492 &lt;/listitem&gt;
3493 &lt;listitem&gt;
3494 &lt;para&gt;
3495 &lt;menuchoice&gt;
3496 &lt;shortcut&gt;
3497 &lt;keycombo&gt;&lt;keycap&gt;Ctrl&lt;/keycap&gt;&lt;keycap&gt;V&lt;/keycap&gt;&lt;/keycombo&gt;
3498 &lt;/shortcut&gt;
3499 &lt;guimenuitem&gt;Paste&lt;/guimenuitem&gt;
3500 &lt;/menuchoice&gt;
3501 &amp;mdash; This pastes any text or data which is copied into
3502 the buffer.
3503 &lt;/para&gt;
3504 &lt;/listitem&gt;
3505 &lt;listitem&gt;
3506 &lt;para&gt;
3507 &lt;guimenuitem&gt;COMMAND1&amp;hellip;&lt;/guimenuitem&gt;
3508 &amp;mdash; This opens the &lt;interface&gt;COMMAND1&lt;/interface&gt;
3509 dialog, which is used to ....
3510 &lt;/para&gt;
3511 &lt;/listitem&gt;
3512 &lt;listitem&gt;
3513 &lt;para&gt;
3514 &lt;guimenuitem&gt;COMMAND2&lt;/guimenuitem&gt;
3515 &amp;mdash; This ....
3516 &lt;/para&gt;
3517 &lt;/listitem&gt;
3518 &lt;/itemizedlist&gt;
3519 &lt;/para&gt;
3520 &lt;/listitem&gt;
3521 &lt;/varlistentry&gt;
3522
3523
3524 &lt;varlistentry&gt;
3525 &lt;term&gt;&lt;guimenu&gt;Settings&lt;/guimenu&gt;&lt;/term&gt;
3526 &lt;listitem&gt;
3527 &lt;para&gt;
3528 This menu contains:
3529 &lt;itemizedlist&gt;
3530 &lt;listitem&gt;
3531 &lt;para&gt;
3532 &lt;guimenuitem&gt;Preferences&amp;hellip;&lt;/guimenuitem&gt;
3533 &amp;mdash; This opens the &lt;link
3534 linkend="prefs"&gt;&lt;interface&gt;Preferences
3535 Dialog&lt;/interface&gt;&lt;/link&gt;, which allows you to configure
3536 many settings.
3537 &lt;/para&gt;
3538 &lt;/listitem&gt;
3539 &lt;listitem&gt;
3540 &lt;para&gt;
3541 &lt;guimenuitem&gt;COMMAND3&lt;/guimenuitem&gt; &amp;mdash;
3542 This command does something.
3543 &lt;/para&gt;
3544 &lt;/listitem&gt;
3545 &lt;/itemizedlist&gt;
3546 &lt;/para&gt;
3547 &lt;/listitem&gt;
3548 &lt;/varlistentry&gt;
3549
3550 &lt;varlistentry&gt;
3551 &lt;term&gt;&lt;guimenu&gt;Help&lt;/guimenu&gt;&lt;/term&gt;
3552 &lt;listitem&gt;
3553 &lt;para&gt;
3554 This menu contains:
3555 &lt;itemizedlist&gt;
3556 &lt;listitem&gt;
3557 &lt;para&gt;
3558 &lt;guimenuitem&gt;Manual&lt;/guimenuitem&gt; &amp;mdash; This
3559 opens the &lt;application&gt;GNOME Help
3560 Browser&lt;/application&gt; and displays this manual.
3561 &lt;/para&gt;
3562 &lt;/listitem&gt;
3563
3564 &lt;listitem&gt;
3565 &lt;para&gt;
3566 &lt;guimenuitem&gt;About&lt;/guimenuitem&gt; &amp;mdash; This
3567 opens the &lt;interface&gt;About&lt;/interface&gt; dialog
3568 which shows basic information about
3569 &lt;application&gt;MY-GNOME-APP&lt;/application&gt;, such as
3570 the author's name, the application version number,
3571 and the URL for the application's Web page if one
3572 exists.
3573 &lt;/para&gt;
3574 &lt;/listitem&gt;
3575 &lt;/itemizedlist&gt;
3576 &lt;/para&gt;
3577 &lt;/listitem&gt;
3578 &lt;/varlistentry&gt;
3579 &lt;/variablelist&gt;
3580 &lt;/sect2&gt;
3581 &lt;/sect1&gt;
3582
3583
3584
3585 &lt;!-- ============= Customization ============================= --&gt;
3586
3587 &lt;sect1 id="prefs"&gt;
3588 &lt;title&gt;Customization&lt;/title&gt;
3589 &lt;para&gt;
3590 To change the application settings, select
3591 &lt;menuchoice&gt;
3592 &lt;guimenu&gt;Settings&lt;/guimenu&gt;
3593 &lt;guimenuitem&gt;Preferences...&lt;/guimenuitem&gt;
3594 &lt;/menuchoice&gt;. This opens the
3595 &lt;interface&gt;Preferences&lt;/interface&gt; dialog, shown in &lt;xref
3596 linkend="preferences-fig"&gt;.
3597 &lt;/para&gt;
3598
3599 &lt;figure id="preferences-fig"&gt;
3600 &lt;title&gt;Preferences Dialog&lt;/title&gt;
3601 &lt;screenshot&gt;
3602 &lt;screeninfo&gt;Preferences Dialog&lt;/screeninfo&gt;
3603 &lt;graphic fileref="SCREENSHOT" format="png"
3604 srccredit="ME"&gt;
3605 &lt;/graphic&gt;
3606 &lt;/screenshot&gt;
3607 &lt;/figure&gt;
3608
3609 &lt;para&gt;
3610 The properties in the &lt;guilabel&gt;PREFSTABNAME&lt;/guilabel&gt; tab are:
3611
3612 &lt;!--many people use itemizedlists in cases like this. Variablelists
3613 are more appropriate --&gt;
3614
3615 &lt;variablelist&gt;
3616 &lt;varlistentry&gt;
3617 &lt;term&gt; &lt;guilabel&gt;Default Text Style&lt;/guilabel&gt;&lt;/term&gt;
3618 &lt;listitem&gt;
3619 &lt;para&gt;
3620 Select the default text style for statements in your
3621 proof. You can still change the style for individual
3622 proofs or sections of a proof at a later date.
3623 &lt;/para&gt;
3624 &lt;/listitem&gt;
3625 &lt;/varlistentry&gt;
3626 &lt;varlistentry&gt;
3627 &lt;term&gt;(Configuration Item Label)&lt;/term&gt;
3628 &lt;listitem&gt;
3629 &lt;para&gt;
3630 (Description of Configuration)
3631 &lt;/para&gt;
3632 &lt;/listitem&gt;
3633 &lt;/varlistentry&gt;
3634 &lt;varlistentry&gt;
3635 &lt;term&gt;(Configuration Item Label)&lt;/term&gt;
3636 &lt;listitem&gt;
3637 &lt;para&gt;
3638 (Description of Configuration)
3639 &lt;/para&gt;
3640 &lt;/listitem&gt;
3641 &lt;/varlistentry&gt;
3642 &lt;/variablelist&gt;
3643 &lt;/para&gt;
3644
3645 &lt;para&gt;
3646 The properties in the &lt;guilabel&gt;SECONDTABNAME&lt;/guilabel&gt; tab are:
3647 &lt;variablelist&gt;
3648 &lt;varlistentry&gt;
3649 &lt;term&gt;(Configuration Item Label)&lt;/term&gt;
3650 &lt;listitem&gt;
3651 &lt;para&gt;
3652 (Description of Configuration)
3653 &lt;/para&gt;
3654 &lt;/listitem&gt;
3655 &lt;/varlistentry&gt;
3656 &lt;varlistentry&gt;
3657 &lt;term&gt;(Configuration Item Label)&lt;/term&gt;
3658 &lt;listitem&gt;
3659 &lt;para&gt;
3660 (Description of Configuration)
3661 &lt;/para&gt;
3662 &lt;/listitem&gt;
3663 &lt;/varlistentry&gt;
3664 &lt;/variablelist&gt;
3665 &lt;/para&gt;
3666
3667 &lt;para&gt;
3668 After you have made all the changes you want, click on
3669 &lt;guibutton&gt;OK&lt;/guibutton&gt; to apply the changes and close the
3670 &lt;interface&gt;Properties&lt;/interface&gt; dialog. To cancel the changes
3671 and return to previous values, click the
3672 &lt;guibutton&gt;Close&lt;/guibutton&gt; button.
3673 &lt;/para&gt;
3674
3675 &lt;/sect1&gt;
3676
3677
3678 &lt;!-- ============= Various Sections ============================= --&gt;
3679
3680 &lt;!-- Here you should add, if necessary, several more sect1's,
3681 describing other windows (besides the main one), file formats,
3682 preferences dialogs, etc. as appropriate. Try not to make any of
3683 these sections too long. --&gt;
3684
3685
3686 &lt;!-- ============= Bugs ================================== --&gt;
3687 &lt;!-- This section should describe known bugs and limitations of
3688 the program if there are any - please be frank and list all
3689 problems you know of. --&gt;
3690 &lt;sect1 id="bugs"&gt;
3691 &lt;title&gt;Known Bugs and Limitations&lt;/title&gt;
3692 &lt;para&gt;
3693 This application has no known bugs.
3694 &lt;/para&gt;
3695 &lt;/sect1&gt;
3696
3697
3698 &lt;!-- ============= Authors ================================ --&gt;
3699
3700 &lt;sect1 id="authors"&gt;
3701 &lt;title&gt;Authors&lt;/title&gt;
3702 &lt;para&gt;
3703 &lt;application&gt;MY-GNOME-APP&lt;/application&gt; was written by GNOME-HACKER
3704 (&lt;email&gt;[email protected]&lt;/email&gt;). To find more information about
3705 &lt;application&gt;MY-GNOME-APP&lt;/application&gt;, please visit the &lt;ulink
3706 url="http://www.my-gnome-app.org" type="http"&gt;MY-GNOME-APP Web
3707 page&lt;/ulink&gt;. Please send all comments, suggestions, and bug
3708 reports to the &lt;ulink url="http://bugs.gnome.org" type="http"&gt;GNOME
3709 bug tracking database&lt;/ulink&gt;. (Instructions for submitting bug
3710 reports can be found &lt;ulink
3711 url="http://bugs.gnome.org/Reporting.html" type="http"&gt;
3712 on-line&lt;/ulink&gt;.) You can also use &lt;application&gt;Bug Report
3713 Tool&lt;/application&gt; (&lt;command&gt;bug-buddy&lt;/command&gt;), available in the
3714 &lt;guisubmenu&gt;Utilities&lt;/guisubmenu&gt; submenu of &lt;guimenu&gt;Main
3715 Menu&lt;/guimenu&gt;, for submitting bug reports.
3716 &lt;/para&gt;
3717
3718 &lt;para&gt;
3719 This manual was written by ME
3720 (&lt;email&gt;MYNAME@MYADDRESS&lt;/email&gt;). Please send all comments and
3721 suggestions regarding this manual to the &lt;ulink type="http"
3722 url="http://developer.gnome.org/projects/gdp"&gt;GNOME Documentation
3723 Project&lt;/ulink&gt; by sending an email to
3724 &lt;email&gt;[email protected]&lt;/email&gt;. You can also add your comments online
3725 by using the &lt;ulink type="http"
3726 url="http://www.gnome.org/gdp/doctable/"&gt;GNOME Documentation Status
3727 Table&lt;/ulink&gt;.
3728 &lt;/para&gt;
3729
3730 &lt;!-- For translations: uncomment this:
3731
3732 &lt;para&gt;
3733 Latin translation was done by ME
3734 (&lt;email&gt;MYNAME@MYADDRESS&lt;/email&gt;). Please send all comments and
3735 suggestions regarding this translation to SOMEWHERE.
3736 &lt;/para&gt;
3737
3738 --&gt;
3739
3740 &lt;/sect1&gt;
3741
3742
3743 &lt;!-- ============= Application License ============================= --&gt;
3744
3745 &lt;sect1 id="license"&gt;
3746 &lt;title&gt;License&lt;/title&gt;
3747 &lt;para&gt;
3748 This program is free software; you can redistribute it and/or
3749 modify it under the terms of the &lt;citetitle&gt;GNU General Public
3750 License&lt;/citetitle&gt; as published by the Free Software Foundation;
3751 either version 2 of the License, or (at your option) any later
3752 version.
3753 &lt;/para&gt;
3754 &lt;para&gt;
3755 This program is distributed in the hope that it will be useful, but
3756 WITHOUT ANY WARRANTY; without even the implied warranty of
3757 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3758 &lt;citetitle&gt;GNU General Public License&lt;/citetitle&gt; for more details.
3759 &lt;/para&gt;
3760 &lt;para&gt;
3761 A copy of the &lt;citetitle&gt;GNU General Public License&lt;/citetitle&gt; is
3762 included as an appendix to the &lt;citetitle&gt;GNOME Users
3763 Guide&lt;/citetitle&gt;. You may also obtain a copy of the
3764 &lt;citetitle&gt;GNU General Public License&lt;/citetitle&gt; from the Free
3765 Software Foundation by visiting &lt;ulink type="http"
3766 url="http://www.fsf.org"&gt;their Web site&lt;/ulink&gt; or by writing to
3767 &lt;address&gt;
3768 Free Software Foundation, Inc.
3769 &lt;street&gt;59 Temple Place&lt;/street&gt; - Suite 330
3770 &lt;city&gt;Boston&lt;/city&gt;, &lt;state&gt;MA&lt;/state&gt; &lt;postcode&gt;02111-1307&lt;/postcode&gt;
3771 &lt;country&gt;USA&lt;/country&gt;
3772 &lt;/address&gt;
3773 &lt;/para&gt;
3774 &lt;/sect1&gt;
3775 &lt;/article&gt;
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788 </fo:block>
3789 </fo:block>
3790 </fo:block>
3791 <fo:block id="template2-1x">
3792 <fo:block>
3793 <fo:block margin-left="-4pc" font-family="Helvetica">
3794 <fo:block keep-with-next.within-column="always">
3795 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Template 2: Applet Manual For GNOME 1.x</fo:block>
3796 </fo:block>
3797 </fo:block>
3798 </fo:block>
3799 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
3800 The following templates should be used for all applet
3801 manuals in GNOME 1.x releases. You can always get the latest
3802 copy of these templates from <fo:basic-link external-destination="http://developer.gnome.org/projects/gdp/templates.html">GDP
3803 Documentation Templates</fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/projects/gdp/templates.html]</fo:inline>. Note that the template
3804 consists of two files; the first file calls the second as an
3805 entity. You should name the first file
3806 <fo:inline font-family="Courier"><fo:inline font-style="italic" font-family="Courier">appletname</fo:inline>-applet.sgml</fo:inline>
3807 and the second file should be named
3808 <fo:inline font-family="Courier"><fo:inline font-style="italic" font-family="Courier">appletname</fo:inline>.sgml</fo:inline>,
3809 where
3810 <fo:inline font-family="Courier"><fo:inline font-style="italic" font-family="Courier">appletname</fo:inline></fo:inline> is
3811 the name of the applet.
3812 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
3813
3814
3815 &lt;!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
3816 &lt;!entity APPLETNAME.sgml SYSTEM "applet_template_1.sgml"&gt;
3817 &lt;!-- Template Version: 1.0.1 (do not remove this line) --&gt;
3818 ]&gt;
3819
3820 &lt;!-- This is a GNOME documentation template, designed by the GNOME
3821 Documentation Project Team. Please use it for writing GNOME
3822 documentation, making obvious changes. In particular, all the words
3823 written in UPPERCASE (with the exception of GNOME) should be
3824 replaced. As for "legalnotice", please leave the reference
3825 unchanged,make sure to add/remove trademarks to the list as
3826 appropriate for your document.
3827
3828 Please don't forget to remove these comments in your final documentation,
3829 thanks ;-).
3830 --&gt;
3831
3832 &lt;article id="index"&gt; &lt;!-- please do not change the id --&gt;
3833
3834 &lt;!-- ============= Document Header ============================= --&gt;
3835 &lt;artheader&gt;
3836 &lt;title&gt;APPLETNAME Applet&lt;/title&gt;
3837 &lt;copyright&gt;
3838 &lt;year&gt;2000&lt;/year&gt;
3839 &lt;holder&gt;YOURFULLNAME&lt;/holder&gt;
3840 &lt;/copyright&gt;
3841
3842 &lt;!-- translators: uncomment this:
3843
3844 &lt;copyright&gt;
3845 &lt;year&gt;2000&lt;/year&gt;
3846 &lt;holder&gt;ME-THE-TRANSLATOR (Latin translation)&lt;/holder&gt;
3847 &lt;/copyright&gt;
3848
3849 --&gt;
3850
3851 &lt;!-- do not put authorname in the header except in copyright - use
3852 section "authors" below --&gt;
3853
3854 &lt;legalnotice&gt;
3855 &lt;para&gt;
3856 Permission is granted to copy, distribute and/or modify this
3857 document under the terms of the &lt;citetitle&gt;GNU Free Documentation
3858 License&lt;/citetitle&gt;, Version 1.1 or any later version published
3859 by the Free Software Foundation with no Invariant Sections, no
3860 Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
3861 of the &lt;citetitle&gt;GNU Free Documentation License&lt;/citetitle&gt; from
3862 the Free Software Foundation by visiting &lt;ulink type="http"
3863 url="http://www.fsf.org"&gt;their Web site&lt;/ulink&gt; or by writing to:
3864 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
3865 Boston, MA 02111-1307, USA.
3866 &lt;/para&gt;
3867 &lt;para&gt;
3868 Many of the names used by companies to distinguish their products and
3869 services are claimed as trademarks. Where those names appear in any
3870 GNOME documentation, and those trademarks are made aware to the members
3871 of the GNOME Documentation Project, the names have been printed in caps
3872 or initial caps.
3873 &lt;/para&gt;
3874 &lt;/legalnotice&gt;
3875
3876 &lt;releaseinfo&gt;
3877 This is version XXX of the APPLETNAME applet manual.
3878 &lt;/releaseinfo&gt;
3879 &lt;/artheader&gt;
3880
3881 &lt;!-- ============= Document Body ============================= --&gt;
3882
3883 &amp;APPLETNAME.sgml;
3884
3885 &lt;/article&gt;
3886
3887
3888
3889
3890
3891 </fo:block>
3892 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
3893
3894 &lt;!-- Template Version: 1.0.1 (do not remove this line) --&gt;
3895
3896 &lt;sect1 id="APPLET"&gt;
3897 &lt;title&gt;APPLET Applet&lt;/title&gt;
3898
3899 &lt;para&gt;
3900 &lt;application&gt;APPLET&lt;/application&gt; applet, shown in &lt;xref
3901 linkend="APPLETapplet-fig"&gt;, allows you to &amp;hellip;. To add this
3902 applet to a &lt;interface&gt;Panel&lt;/interface&gt;,
3903 right-click on the &lt;interface&gt;Panel&lt;/interface&gt; and choose
3904 &lt;menuchoice&gt;
3905 &lt;guimenu&gt;Panel&lt;/guimenu&gt;
3906 &lt;guisubmenu&gt;Add to panel&lt;/guisubmenu&gt;
3907 &lt;guisubmenu&gt;Applet&lt;/guisubmenu&gt;
3908 &lt;guisubmenu&gt;SECTION&lt;/guisubmenu&gt;
3909 &lt;guimenuitem&gt;APPLET&lt;/guimenuitem&gt;
3910 &lt;/menuchoice&gt;.
3911 &lt;/para&gt;
3912
3913 &lt;figure id="APPLETapplet-fig"&gt;
3914 &lt;title&gt;APPLET Applet&lt;/title&gt;
3915 &lt;screenshot&gt;
3916 &lt;screeninfo&gt;APPLET Applet&lt;/screeninfo&gt;
3917 &lt;graphic format="png" fileref="APPLET_applet"
3918 srccredit="YOURNAME"&gt;
3919 &lt;/graphic&gt;
3920 &lt;/screenshot&gt;
3921 &lt;/figure&gt;
3922
3923 &lt;!-- ============= Usage ================================ --&gt;
3924 &lt;sect2 id="APPLET-usage"&gt;
3925 &lt;title&gt;Usage&lt;/title&gt;
3926 &lt;para&gt;
3927 (Place a short description of how to use the applet here.)
3928 &lt;/para&gt;
3929
3930 &lt;para&gt;
3931 Right-clicking on the applet brings up a menu containing the
3932 following items:
3933 &lt;itemizedlist&gt;
3934
3935 &lt;listitem&gt;
3936 &lt;para&gt;
3937 &lt;guimenuitem&gt;Properties&amp;hellip;&lt;/guimenuitem&gt; &amp;mdash;
3938 opens the &lt;link linkend="APPLET-prefs"&gt;
3939 &lt;guilabel&gt;Properties&lt;/guilabel&gt;&lt;/link&gt; dialog.
3940 &lt;/para&gt;
3941 &lt;/listitem&gt;
3942
3943 &lt;listitem&gt;
3944 &lt;para&gt;
3945 &lt;guimenuitem&gt;Help&lt;/guimenuitem&gt; &amp;mdash;
3946 displays this document.
3947 &lt;/para&gt;
3948 &lt;/listitem&gt;
3949
3950 &lt;listitem&gt;
3951 &lt;para&gt;
3952 &lt;guimenuitem&gt;About&amp;hellip;&lt;/guimenuitem&gt; &amp;mdash;
3953 shows basic information about &lt;application&gt;APPLET
3954 Applet&lt;/application&gt;, including the applet's version and the
3955 author's name.
3956 &lt;/para&gt;
3957 &lt;/listitem&gt;
3958
3959 &lt;/itemizedlist&gt;
3960 &lt;/para&gt;
3961 &lt;/sect2&gt;
3962
3963
3964 &lt;!-- ============= Customization ============================= --&gt;
3965 &lt;sect2 id="APPLET-prefs"&gt;
3966 &lt;title&gt;Customization&lt;/title&gt;
3967 &lt;para&gt;
3968 You can customize &lt;application&gt;APPLET&lt;/application&gt;
3969 applet by right-clicking on it and choosing
3970 &lt;guimenuitem&gt;Properties&amp;hellip;&lt;/guimenuitem&gt;. This will open the
3971 &lt;interface&gt;Properties&lt;/interface&gt; dialog(shown in &lt;xref
3972 linkend="APPLET-settings-fig"&gt;), which allows you to
3973 change various settings.
3974 &lt;/para&gt;
3975
3976 &lt;figure id="APPLET-settings-fig"&gt;
3977 &lt;title&gt;Properties dialog&lt;/title&gt;
3978 &lt;screenshot&gt;
3979 &lt;screeninfo&gt;Properties dialog&lt;/screeninfo&gt;
3980 &lt;graphic format="png" fileref="APPLET_settings"
3981 srccredit="YOURNAME"&gt;
3982 &lt;/graphic&gt;
3983 &lt;/screenshot&gt;
3984 &lt;/figure&gt;
3985
3986 &lt;para&gt;
3987 The properties are:
3988 &lt;itemizedlist&gt;
3989
3990 &lt;listitem&gt;
3991 &lt;para&gt;
3992 (Configuration Item Label) &amp;mdash; If this button is
3993 checked&amp;hellip;(description)
3994 &lt;/para&gt;
3995 &lt;/listitem&gt;
3996
3997 &lt;listitem&gt;
3998 &lt;para&gt;
3999 (Configuration Item Label) &amp;mdash; Selecting this
4000 button&amp;hellip;(description)
4001 &lt;/para&gt;
4002 &lt;/listitem&gt;
4003
4004 &lt;listitem&gt;
4005 &lt;para&gt;
4006 (Configuration Item Label) &amp;mdash; Enter the name of
4007 &amp;hellip;(description)
4008 &lt;/para&gt;
4009 &lt;/listitem&gt;
4010 &lt;/itemizedlist&gt;
4011 &lt;/para&gt;
4012
4013 &lt;para&gt;
4014 After you have made all the changes you want, click on
4015 &lt;guibutton&gt;OK&lt;/guibutton&gt; to apply the changes and close the
4016 &lt;interface&gt;Properties&lt;/interface&gt; dialog. To cancel the changes
4017 and return to previous values, click the
4018 &lt;guibutton&gt;Close&lt;/guibutton&gt; button.
4019 &lt;/para&gt;
4020 &lt;/sect2&gt;
4021
4022
4023 &lt;!-- ============= Bugs ================================== --&gt;
4024 &lt;!-- This section should describe known bugs and limitations of
4025 the program if there are any - please be frank and list all
4026 problems you know of --&gt;
4027 &lt;sect2 id="bugs"&gt;
4028 &lt;title&gt;Known Bugs and Limitations&lt;/title&gt;
4029 &lt;para&gt;
4030 This applet has no known bugs.
4031 &lt;/para&gt;
4032 &lt;/sect2&gt;
4033
4034
4035 &lt;!-- ============= Authors ================================ --&gt;
4036
4037 &lt;sect2 id="authors"&gt;
4038 &lt;title&gt;Authors&lt;/title&gt;
4039 &lt;para&gt;
4040 &lt;application&gt;APPLET&lt;/application&gt; was written by GNOME-HACKER
4041 (&lt;email&gt;[email protected]&lt;/email&gt;). Please send all comments,
4042 suggestions, and bug
4043 reports to the &lt;ulink url="http://bugs.gnome.org" type="http"&gt;GNOME
4044 bug tracking database&lt;/ulink&gt;. (Instructions for submitting bug
4045 reports can be found &lt;ulink
4046 url="http://bugs.gnome.org/Reporting.html" type="http"&gt;
4047 on-line&lt;/ulink&gt;. You can also use &lt;application&gt;Bug Report
4048 Tool&lt;/application&gt; (&lt;command&gt;bug-buddy&lt;/command&gt;), available in the
4049 &lt;guisubmenu&gt;Utilities&lt;/guisubmenu&gt; submenu of &lt;guimenu&gt;Main
4050 Menu&lt;/guimenu&gt;, for submitting bug reports.
4051 &lt;/para&gt;
4052
4053 &lt;para&gt;
4054 This manual was written by ME
4055 (&lt;email&gt;MYNAME@MYADDRESS&lt;/email&gt;). Please send all comments and
4056 suggestions regarding this manual to the &lt;ulink type="http"
4057 url="http://developer.gnome.org/projects/gdp"&gt;GNOME Documentation
4058 Project&lt;/ulink&gt; by sending an email to
4059 &lt;email&gt;[email protected]&lt;/email&gt;. You can also submit comments online
4060 by using the &lt;ulink type="http"
4061 url="http://www.gnome.org/gdp/doctable/"&gt;GNOME Documentation
4062 Status Table&lt;/ulink&gt;.
4063 &lt;/para&gt;
4064
4065 &lt;!-- For translations: uncomment this:
4066
4067 &lt;para&gt;
4068 Latin translation was done by ME
4069 (&lt;email&gt;MYNAME@MYADDRESS&lt;/email&gt;). Please send all comments and
4070 suggestions regarding this translation to SOMEWHERE.
4071 &lt;/para&gt;
4072
4073 --&gt;
4074
4075 &lt;/sect2&gt;
4076
4077
4078 &lt;!-- ============= Application License ============================= --&gt;
4079
4080 &lt;sect2 id="license"&gt;
4081 &lt;title&gt;License&lt;/title&gt;
4082 &lt;para&gt;
4083 This program is free software; you can redistribute it and/or
4084 modify it under the terms of the &lt;citetitle&gt;GNU General Public
4085 License&lt;/citetitle&gt; as published by the Free Software Foundation;
4086 either version 2 of the License, or (at your option) any later
4087 version.
4088 &lt;/para&gt;
4089 &lt;para&gt;
4090 This program is distributed in the hope that it will be useful, but
4091 WITHOUT ANY WARRANTY; without even the implied warranty of
4092 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
4093 &lt;citetitle&gt;GNU General Public License&lt;/citetitle&gt; for more details.
4094 &lt;/para&gt;
4095 &lt;para&gt;
4096 A copy of the &lt;citetitle&gt;GNU General Public License&lt;/citetitle&gt; is
4097 included as an appendix to the &lt;citetitle&gt;GNOME Users
4098 Guide&lt;/citetitle&gt;. You may also obtain a copy of the
4099 &lt;citetitle&gt;GNU General Public License&lt;/citetitle&gt; from the Free
4100 Software Foundation by visiting &lt;ulink type="http"
4101 url="http://www.fsf.org"&gt;their Web site&lt;/ulink&gt; or by writing to
4102 &lt;address&gt;
4103 Free Software Foundation, Inc.
4104 &lt;street&gt;59 Temple Place&lt;/street&gt; - Suite 330
4105 &lt;city&gt;Boston&lt;/city&gt;, &lt;state&gt;MA&lt;/state&gt; &lt;postcode&gt;02111-1307&lt;/postcode&gt;
4106 &lt;country&gt;USA&lt;/country&gt;
4107 &lt;/address&gt;
4108 &lt;/para&gt;
4109 &lt;/sect2&gt;
4110
4111 &lt;/sect1&gt;
4112
4113
4114
4115
4116
4117
4118
4119
4120 </fo:block>
4121 </fo:block>
4122 </fo:block>
4123 <fo:block id="template2-2x">
4124 <fo:block>
4125 <fo:block margin-left="-4pc" font-family="Helvetica">
4126 <fo:block keep-with-next.within-column="always">
4127 <fo:block font-size="16pt" font-weight="bold" font-family="Helvetica" space-before.minimum="1em" space-before.optimum="1.5em" space-before.maximum="2em">Template 2: Applet Manual For GNOME 2.x</fo:block>
4128 </fo:block>
4129 </fo:block>
4130 </fo:block>
4131 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
4132 The following templates should be used for all applet
4133 manuals in GNOME 2.x releases. You can always get the latest
4134 copy of these templates from <fo:basic-link external-destination="http://developer.gnome.org/projects/gdp/templates.html">GDP
4135 Documentation Templates</fo:basic-link><fo:inline hyphenate="false"> [http://developer.gnome.org/projects/gdp/templates.html]</fo:inline>.
4136 </fo:block>
4137 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
4138 Note that this template consists of two files. The first file
4139 is an introductory chapter. You should not modify this
4140 chapter. The second file is the actual applet document, which
4141 you should modify to describe the applet you are documenting.
4142 You can name the first file whatever you like, such as
4143 <fo:inline font-family="Courier">gnome-applets.sgml</fo:inline>. Name the second file
4144 according to the applet's name:
4145 <fo:inline font-family="Courier"><fo:inline font-style="italic" font-family="Courier">appletname</fo:inline>-applet.sgml</fo:inline>.
4146 Make sure you update the entity
4147 at the top of the shell document to reflect the new name of
4148 the applet document.
4149 </fo:block>
4150 <fo:block space-before.optimum="1em" space-before.minimum="0.8em" space-before.maximum="1.2em">
4151 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
4152
4153 &lt;!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
4154 &lt;!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part"&gt;
4155
4156 ]&gt;
4157
4158 &lt;book id="gnome-applets"&gt;
4159
4160 &lt;bookinfo&gt;
4161 &lt;title&gt;GNOME Applets&lt;/title&gt;
4162 &lt;authorgroup&gt;
4163 &lt;author&gt;&lt;firstname&gt;Telsa&lt;/firstname&gt;&lt;surname&gt;Gwynne&lt;/surname&gt;&lt;/author&gt;
4164 &lt;author&gt;&lt;firstname&gt;John&lt;/firstname&gt;&lt;surname&gt;Fleck&lt;/surname&gt;&lt;/author&gt;
4165 &lt;author&gt;&lt;firstname&gt;David&lt;/firstname&gt;&lt;surname&gt;Mason&lt;/surname&gt;
4166 &lt;affiliation&gt;&lt;orgname&gt;Red Hat, Inc.&lt;/orgname&gt;&lt;/affiliation&gt;
4167 &lt;/author&gt;
4168 &lt;author&gt;&lt;firstname&gt;Dan&lt;/firstname&gt;&lt;surname&gt;Mueth&lt;/surname&gt;&lt;/author&gt;
4169 &lt;author&gt;&lt;firstname&gt;Alexander&lt;/firstname&gt;&lt;surname&gt;Kirillov&lt;/surname&gt;&lt;/author&gt;
4170 &lt;/authorgroup&gt;
4171 &lt;edition&gt;GNOME Applets version 0.1 for GNOME 1.1.5&lt;/edition&gt;
4172 &lt;pubdate&gt;2000&lt;/pubdate&gt;
4173 &lt;copyright&gt;
4174 &lt;year&gt;2000&lt;/year&gt;
4175 &lt;holder&gt;Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and
4176 Alexander Kirillov&lt;/holder&gt;
4177 &lt;/copyright&gt;
4178 &lt;legalnotice&gt;
4179 &lt;para&gt;
4180 Permission is granted to make and distribute verbatim copies of this
4181 manual provided the copyright notice and this permission notice are
4182 preserved on all copies.
4183 &lt;/para&gt;
4184 &lt;para&gt;
4185 Permission is granted to copy and distribute modified versions of
4186 this manual under the conditions for verbatim copying, provided that
4187 the entire resulting derived work is distributed under the terms of a
4188 permission notice identical to this one.
4189 &lt;/para&gt;
4190 &lt;para&gt;
4191 Permission is granted to copy and distribute translations of this
4192 manual into another language, under the above conditions for modified
4193 versions, except that this permission notice may be stated in a
4194 translation approved by the Free Software Foundation.
4195 &lt;/para&gt;
4196 &lt;para&gt;
4197 Many of the names used by companies to distinguish their products and
4198 services are claimed as trademarks. Where those names appear in any
4199 GNOME documentation, and those trademarks are made aware to the members
4200 of the GNOME Documentation Project, the names have been printed in caps
4201 or initial caps.
4202 &lt;/para&gt;
4203 &lt;/legalnotice&gt;
4204 &lt;/bookinfo&gt;
4205
4206 &lt;!-- #### Introduction ###### --&gt;
4207 &lt;chapter id="applets-intro"&gt;
4208 &lt;title&gt;Introduction&lt;/title&gt;
4209
4210 &lt;!-- #### Intro | What Are Applets? ###### --&gt;
4211 &lt;sect1 id="applets-what-are"&gt;
4212 &lt;title&gt;What Are Applets?&lt;/title&gt;
4213 &lt;para&gt;
4214 Applets are one of the most popular and useful objects you can add
4215 to your &lt;interface&gt;Panel&lt;/interface&gt; to customize your desktop.
4216 An applet is a small application which runs inside a small area of
4217 your &lt;interface&gt;Panel&lt;/interface&gt;. Applets have been written for
4218 a wide range of purposes. Some are very powerful interactive
4219 tools, such as the &lt;application&gt;Tasklist&lt;/application&gt; Applet
4220 which allows you to easily
4221 control all of your main applications. Others are simple system
4222 monitors, displaying information such as the amount of power left
4223 in the battery on your laptop (see &lt;application&gt;Battery Charge
4224 Monitor&lt;/application&gt;) or weather
4225 information(see &lt;application&gt;GNOME Weather&lt;/application&gt;). Some
4226 are simply for amusement(see &lt;application&gt;Fish&lt;/application&gt;).
4227 &lt;/para&gt;
4228
4229 &lt;para&gt;
4230 Applets are similar to swallowed applications in that both of them
4231 reside within the &lt;interface&gt;Panel&lt;/interface&gt;. However,
4232 swallowed applications are generally applications which were
4233 not designed to run within the &lt;interface&gt;Panel&lt;/interface&gt;.
4234 Typically one will swallow an application which already exists in
4235 the main &lt;interface&gt;desktop&lt;/interface&gt; area, putting it into your
4236 &lt;interface&gt;Panel&lt;/interface&gt;. The application will continue to
4237 run in the &lt;interface&gt;Panel&lt;/interface&gt; until you end the
4238 application or unswallow it, placing it back onto the main part of
4239 your desktop when you need to.
4240 &lt;/para&gt;
4241
4242 &lt;para&gt;
4243 &lt;figure id="example-applets-fig"&gt;
4244 &lt;title&gt;Example Applets&lt;/title&gt;
4245 &lt;screenshot&gt;
4246 &lt;screeninfo&gt;Example Applets&lt;/screeninfo&gt;
4247 &lt;graphic fileref="example_applets" format="png"
4248 srccredit="muet"&gt;
4249 &lt;/graphic&gt;
4250 &lt;/screenshot&gt;
4251 &lt;/figure&gt;
4252 Several example applets are shown in &lt;xref
4253 linkend="example-applets-fig"&gt;. From left to right, they are: (1)
4254 &lt;application&gt;Mixer Applet&lt;/application&gt;, which allows you to turn
4255 on/off sound and control its volume by clicking on the applet. (2)
4256 &lt;application&gt;Sound Monitor&lt;/application&gt; Applet, which displays
4257 the current volume of sound being played and allows you to control
4258 various sound features. (3) &lt;application&gt;GTCD&lt;/application&gt;
4259 Applet, a CD player which has all its controls
4260 available in the applet and displays the track and time. (4)
4261 &lt;application&gt;Drive Mount&lt;/application&gt; Applet, used to mount and
4262 unmount drives with a single click of the mouse. (5)
4263 &lt;application&gt;Desk Guide&lt;/application&gt; which allows you to view
4264 and control multiple virtual screens. (6)
4265 &lt;application&gt;Tasklist&lt;/application&gt; Applet which allows you to
4266 control your various windows and applications.
4267 &lt;/para&gt;
4268 &lt;para&gt;
4269 There are many other applets to choose from. The rest of this
4270 chapter will explain the basic information to get you started
4271 adding, moving, and removing applets from your
4272 &lt;interface&gt;Panels&lt;/interface&gt; and using them. The following
4273 chapters go through each of the standard GNOME applets describing
4274 them in detail. There are also additional applets which can be
4275 downloaded off the Web. See &lt;ulink type="http"
4276 url="http://www.gnome.org/applist/list-martin.phtml"&gt;The GNOME
4277 Software Map&lt;/ulink&gt; for lists of additional GNOME applications
4278 and applets.
4279 &lt;/para&gt;
4280 &lt;para&gt;
4281 As you read through the the rest of this chapter, you should try
4282 adding and removing applets from your &lt;interface&gt;Panel&lt;/interface&gt; and
4283 experiment with them freely.
4284 &lt;/para&gt;
4285 &lt;/sect1&gt;
4286
4287 &lt;!-- #### Intro | Adding, Moving, and Removing Applets ###### --&gt;
4288 &lt;sect1 id="applet-add-move-replace"&gt;
4289 &lt;title&gt;Adding, Moving, and Removing Applets&lt;/title&gt;
4290
4291 &lt;sect2 id="adding-applets"&gt;
4292 &lt;title&gt;Adding Applets to a Panel&lt;/title&gt;
4293 &lt;para&gt;
4294 To add an applet to a &lt;interface&gt;Panel&lt;/interface&gt;, right-click
4295 on the &lt;interface&gt;Panel&lt;/interface&gt; and select
4296 &lt;menuchoice&gt;&lt;guimenu&gt;Panel&lt;/guimenu&gt;&lt;guisubmenu&gt;Add to panel&lt;/guisubmenu&gt;
4297 &lt;guisubmenu&gt;Applet&lt;/guisubmenu&gt;&lt;/menuchoice&gt;. This will show you
4298 the menu of all the applets on your system, divided into
4299 categories. Choosing any applet from this menu will add it to the
4300 &lt;interface&gt;Panel&lt;/interface&gt;.
4301 &lt;/para&gt;
4302 &lt;/sect2&gt;
4303
4304 &lt;sect2 id="moving-applets"&gt;
4305 &lt;title&gt;Moving Applets In or Between Panels&lt;/title&gt;
4306 &lt;para&gt;
4307 It is easy to move applets in a &lt;interface&gt;Panel&lt;/interface&gt; or
4308 between two &lt;interface&gt;Panels&lt;/interface&gt;. If you have a
4309 three-button mouse, just move the mouse over the applet, depress
4310 the middle mouse button and drag the applet to its new location,
4311 releasing the middle mouse button when you are finished. Note
4312 that you can drag applets within a &lt;interface&gt;Panel&lt;/interface&gt;
4313 or between two &lt;interface&gt;Panels&lt;/interface&gt; this way. If you
4314 don't have a three-button mouse, just
4315 right-click on the applet and choose
4316 &lt;guimenuitem&gt;Move&lt;/guimenuitem&gt;. The cursor will turn into a
4317 cross and the applet will move with your mouse until you press
4318 any mouse button to indicate you are finished moving it.
4319 If, in the course of this movement, it hits
4320 other objects, the behavior depends on the global preferences
4321 you have set for your &lt;interface&gt;Panels&lt;/interface&gt; in the
4322 &lt;application&gt;GNOME Control Center&lt;/application&gt;: the applet you are
4323 moving can switch places with other objects, "push" all objects
4324 it meets, or "jump" over all other objects without disturbing
4325 them. You can also override the default behavior by holding
4326 &lt;keycap&gt;Shift&lt;/keycap&gt; button (for "push" mode),
4327 &lt;keycap&gt;Ctrl&lt;/keycap&gt; (for "switched" mode), or
4328 &lt;keycap&gt;Alt&lt;/keycap&gt; (for "free" mode, i.e. jumping other other
4329 objects without disturbing them) button while dragging.
4330 &lt;/para&gt;
4331 &lt;para&gt;
4332 To change the global Panel preferences, right-click on any applet
4333 or &lt;interface&gt;Panel&lt;/interface&gt; and select
4334 &lt;menuchoice&gt;
4335 &lt;guimenu&gt;Panel&lt;/guimenu&gt;
4336 &lt;guimenuitem&gt;Global Preferences...&lt;/guimenuitem&gt;
4337 &lt;/menuchoice&gt;.
4338 The &lt;guilabel&gt;Default movement mode&lt;/guilabel&gt; is set under the
4339 &lt;guilabel&gt;Applets&lt;/guilabel&gt; tab.
4340 &lt;/para&gt;
4341 &lt;/sect2&gt;
4342
4343 &lt;sect2 id="removing-applets"&gt;
4344 &lt;title&gt;Removing Applets from a Panel&lt;/title&gt;
4345 &lt;para&gt;
4346 To remove an applet from a &lt;interface&gt;Panel&lt;/interface&gt;,
4347 right-click on the applet and select &lt;guimenuitem&gt;Remove from
4348 panel...&lt;/guimenuitem&gt;.
4349 &lt;/para&gt;
4350 &lt;/sect2&gt;
4351 &lt;/sect1&gt;
4352
4353
4354 &lt;!-- #### Intro | The Right-Click Pop-Up Menu ###### --&gt;
4355 &lt;sect1 id="right-click-pop-up-menu"&gt;
4356 &lt;title&gt;The Right-Click Pop-Up Menu&lt;/title&gt;
4357 &lt;para&gt;
4358 Clicking the right mouse button on any applet brings up
4359 a &lt;guimenu&gt;pop-up menu&lt;/guimenu&gt;. This
4360 menu always has certain standard menu items in it and
4361 often has additional items which vary depending on the particular
4362 applet.
4363 &lt;/para&gt;
4364 &lt;sect2 id="standard-right-click-items"&gt;
4365 &lt;title&gt;Standard Pop-Up Items&lt;/title&gt;
4366 &lt;para&gt;
4367 All applets should have the following items in their right-click
4368 &lt;guimenu&gt;pop-up menu&lt;/guimenu&gt;:
4369 &lt;variablelist&gt;
4370 &lt;varlistentry&gt;
4371 &lt;term&gt;Remove from panel&lt;/term&gt;
4372 &lt;listitem&gt;
4373 &lt;para&gt;
4374 The &lt;guimenuitem&gt;Remove from panel&lt;/guimenuitem&gt; menu item
4375 removes the applet from the &lt;interface&gt;Panel&lt;/interface&gt;.
4376 &lt;/para&gt;
4377 &lt;/listitem&gt;
4378 &lt;/varlistentry&gt;
4379
4380 &lt;varlistentry&gt;
4381 &lt;term&gt;Move&lt;/term&gt;
4382 &lt;listitem&gt;
4383 &lt;para&gt;
4384 After selecting &lt;guimenuitem&gt;Move&lt;/guimenuitem&gt;, your mouse
4385 pointer will change appearance (typically to a cross with
4386 arrows in each direction). As you move your mouse, the applet
4387 will move with it. When you have finished moving the applet,
4388 click any mouse button and the applet will anchor in its
4389 current position. Note that applets can be moved between two
4390 &lt;interface&gt;Panels&lt;/interface&gt; this way.
4391 &lt;/para&gt;
4392 &lt;/listitem&gt;
4393 &lt;/varlistentry&gt;
4394
4395 &lt;varlistentry&gt;
4396 &lt;term&gt;Panel&lt;/term&gt;
4397 &lt;listitem&gt;
4398 &lt;para&gt;
4399 The &lt;guisubmenu&gt;Panel&lt;/guisubmenu&gt; submenu contains various
4400 items and submenus for adding and removing
4401 &lt;interface&gt;Panels&lt;/interface&gt; and applets and for changing
4402 the configuration.
4403 &lt;/para&gt;
4404 &lt;/listitem&gt;
4405 &lt;/varlistentry&gt;
4406
4407 &lt;varlistentry&gt;
4408 &lt;term&gt;About&lt;/term&gt;
4409 &lt;listitem&gt;
4410 &lt;para&gt;
4411 The &lt;guimenuitem&gt;About...&lt;/guimenuitem&gt; menu item brings up a
4412 dialogue box containing various information about the applet,
4413 typically including the applet's name, version, author,
4414 copyright, license and desciption.
4415 &lt;/para&gt;
4416 &lt;/listitem&gt;
4417 &lt;/varlistentry&gt;
4418
4419 &lt;varlistentry&gt;
4420 &lt;term&gt;Help&lt;/term&gt;
4421 &lt;listitem&gt;
4422 &lt;para&gt;
4423 The &lt;guimenuitem&gt;Help&lt;/guimenuitem&gt; menu item brings up the help
4424 manual for the applet.
4425 &lt;/para&gt;
4426 &lt;/listitem&gt;
4427 &lt;/varlistentry&gt;
4428 &lt;/variablelist&gt;
4429 &lt;/para&gt;
4430 &lt;/sect2&gt;
4431
4432 &lt;sect2 id="applet-properties-dialog"&gt;
4433 &lt;title&gt;The Applet Properties Dialog&lt;/title&gt;
4434 &lt;para&gt;
4435 Many applets have customizable properties. These applets will
4436 have a &lt;guimenuitem&gt;Properties...&lt;/guimenuitem&gt; menu item in their
4437 right-click &lt;guimenu&gt;pop-up menu&lt;/guimenu&gt; which brings up the
4438 &lt;interface&gt;Properties&lt;/interface&gt; dialog where you can alter the
4439 appearance or behaviour of the applet.
4440 &lt;figure id="example-props-dialog-fig"&gt;
4441 &lt;title&gt;An Example Applet Properties Dialog&lt;/title&gt;
4442 &lt;screenshot&gt;
4443 &lt;screeninfo&gt;An Example Applets Properties Dialog&lt;/screeninfo&gt;
4444 &lt;graphic fileref="applet_props_dialog" format="png"
4445 srccredit="muet"&gt;
4446 &lt;/graphic&gt;
4447 &lt;/screenshot&gt;
4448 &lt;/figure&gt;
4449 All &lt;interface&gt;Properties&lt;/interface&gt; dialogs have the following
4450 buttons at the bottom of the dialog:
4451 &lt;itemizedlist&gt;
4452 &lt;listitem&gt;
4453 &lt;para&gt;
4454 &lt;guibutton&gt;OK&lt;/guibutton&gt; &amp;mdash;
4455 Pressing &lt;guibutton&gt;OK&lt;/guibutton&gt; will activate any changes
4456 in the properties you have made and close the
4457 &lt;interface&gt;Properties&lt;/interface&gt; dialog.
4458 &lt;/para&gt;
4459 &lt;/listitem&gt;
4460 &lt;listitem&gt;
4461 &lt;para&gt;
4462 &lt;guibutton&gt;Apply&lt;/guibutton&gt; &amp;mdash;
4463 Pressing &lt;guibutton&gt;Apply&lt;/guibutton&gt; at any time will
4464 make your changes active without closing the
4465 &lt;interface&gt;Properties&lt;/interface&gt; dialog. This is helpful if
4466 you would like to test the effects of the changes you have
4467 made but may want to continue changing the properties.
4468 &lt;/para&gt;
4469 &lt;/listitem&gt;
4470 &lt;listitem&gt;
4471 &lt;para&gt;
4472 &lt;guibutton&gt;Close&lt;/guibutton&gt; &amp;mdash;
4473 Pressing &lt;guibutton&gt;Close&lt;/guibutton&gt; will close the
4474 &lt;interface&gt;Properties&lt;/interface&gt; dialog. Only changes in the
4475 configuration which were previously applied with the
4476 &lt;guibutton&gt;Apply&lt;/guibutton&gt; button will persist. Other
4477 changes will not be made active.
4478 &lt;/para&gt;
4479 &lt;/listitem&gt;
4480 &lt;listitem&gt;
4481 &lt;para&gt;
4482 &lt;guibutton&gt;Help&lt;/guibutton&gt; &amp;mdash;
4483 Pressing &lt;guibutton&gt;Help&lt;/guibutton&gt; brings up the manual for
4484 the application, opening it to the page describing the
4485 &lt;interface&gt;Properties&lt;/interface&gt; dialog.
4486 &lt;/para&gt;
4487 &lt;/listitem&gt;
4488 &lt;/itemizedlist&gt;
4489 &lt;/para&gt;
4490 &lt;/sect2&gt;
4491
4492 &lt;sect2 id="common-right-click-items"&gt;
4493 &lt;title&gt;Other Common Pop-Up Items&lt;/title&gt;
4494 &lt;para&gt;
4495 Many applets also have one or more of the following items in their
4496 right-click pop-up menu:
4497 &lt;variablelist&gt;
4498 &lt;varlistentry&gt;
4499 &lt;term&gt;Run...&lt;/term&gt;
4500 &lt;listitem&gt;
4501 &lt;para&gt;
4502 The &lt;guimenuitem&gt;Run...&lt;/guimenuitem&gt; menu item generally
4503 invokes a program which is related to the applet in some way
4504 but which runs in its own window rather than in the
4505 panel. For example:
4506 &lt;/para&gt;
4507 &lt;orderedlist&gt;
4508 &lt;listitem&gt;
4509 &lt;para&gt;
4510 The &lt;application&gt;CPU Load&lt;/application&gt; applet, which monitors
4511 what programs are running, has a &lt;guimenuitem&gt;Run
4512 gtop...&lt;/guimenuitem&gt; menu item. Selecting this menu item
4513 starts &lt;application&gt;GTop&lt;/application&gt;, which allows you to
4514 view and control programs which are running.
4515 &lt;/para&gt;
4516 &lt;/listitem&gt;
4517 &lt;listitem&gt;
4518 &lt;para&gt;
4519 The &lt;application&gt;CD Player&lt;/application&gt; applet has a
4520 &lt;guimenuitem&gt;Run gtcd...&lt;/guimenuitem&gt; menu item which
4521 starts the GNOME &lt;application&gt;CD Player&lt;/application&gt; when
4522 selected, which has more capabilities than the applet.
4523 &lt;/para&gt;
4524 &lt;/listitem&gt;
4525 &lt;/orderedlist&gt;
4526 &lt;/listitem&gt;
4527 &lt;/varlistentry&gt;
4528 &lt;/variablelist&gt;
4529 &lt;/para&gt;
4530 &lt;/sect2&gt;
4531 &lt;/sect1&gt;
4532
4533 &lt;sect1 id="feedback"&gt;
4534 &lt;title&gt;Feedback&lt;/title&gt;
4535 &lt;sect2 id="reporting-bugs"&gt;
4536 &lt;title&gt;Reporting Applet Bugs&lt;/title&gt;
4537 &lt;para&gt;
4538 GNOME users are encouraged to report bugs to &lt;ulink type="http"
4539 url="http://bugs.gnome.org"&gt;The GNOME Bug Tracking
4540 System&lt;/ulink&gt;. The easiest way to submit bugs is to use the
4541 &lt;application&gt;Bug Report Tool&lt;/application&gt; program by selecting
4542 &lt;menuchoice&gt;
4543 &lt;guimenu&gt;Main Menu&lt;/guimenu&gt; &lt;guisubmenu&gt;Utilities&lt;/guisubmenu&gt;
4544 &lt;guimenuitem&gt;Bug Report Tool&lt;/guimenuitem&gt;
4545 &lt;/menuchoice&gt;.
4546 Be sure to be complete in describing what you did to cause the
4547 bug to surface and, if possible, describe how the developer can
4548 reproduce the the scenario.
4549 &lt;/para&gt;
4550 &lt;/sect2&gt;
4551 &lt;sect2 id="documentation-feedback"&gt;
4552 &lt;title&gt;Providing Feedback&lt;/title&gt;
4553 &lt;para&gt;
4554 GNOME users are welcome to provide suggestions for how
4555 applications and documentation can be improved. Suggestions for
4556 application changes should be submitted using the
4557 &lt;application&gt;Bug Report Tool&lt;/application&gt; discussed above.
4558 Suggestions for documentation changes can be emailed directly to
4559 the documentation author (whose email should be included in the
4560 "Authors" section of the document) or by sending an email to
4561 &lt;email&gt;[email protected]&lt;/email&gt;.
4562 &lt;/para&gt;
4563 &lt;/sect2&gt;
4564 &lt;sect2 id="joining-gnome"&gt;
4565 &lt;title&gt;Joining GNOME&lt;/title&gt;
4566 &lt;para&gt;
4567 GNOME is a community project, created by hundreds of programmers,
4568 documentation writers, icon design artists, web masters, and
4569 other people, most of whom work on a volunteer basis. New GNOME
4570 contributors are always welcome. To join the GNOME team, visit
4571 these web sites: developers &amp;mdash; &lt;ulink type="http"
4572 url="http://developer.gnome.org"&gt;The GNOME Development
4573 Site&lt;/ulink&gt;, documentation writers &amp;mdash; &lt;ulink type="http"
4574 url="http://developer.gnome.org/projects/gdp"&gt;The GNOME Documentation
4575 Project&lt;/ulink&gt;, icon design artists &amp;mdash; &lt;ulink type="http"
4576 url="http://gnome-icons.sourceforge.net/"&gt;Gnome Icon Web&lt;/ulink&gt;,
4577 general &amp;mdash; &lt;ulink type="http"
4578 url="http://developer.gnome.org/helping/"&gt;Helping GNOME&lt;/ulink&gt;,
4579 or just join the gnome-list email list (see &lt;ulink type="http"
4580 url="http://www.gnome.org/resources/mailing-lists.html"&gt;GNOME Mailing
4581 Lists&lt;/ulink&gt;) to discuss what you are interested in doing.
4582 &lt;/para&gt;
4583 &lt;/sect2&gt;
4584 &lt;/sect1&gt;
4585 &lt;/chapter&gt;
4586
4587 &lt;!-- ############### Template Applets ##################### --&gt;
4588 &lt;chapter id="template-applets"&gt;
4589 &lt;title&gt;Template Applets&lt;/title&gt;
4590
4591 &amp;TEMPLATE-APPLET
4592
4593 &lt;/chapter&gt;
4594
4595 &lt;/book&gt;
4596
4597
4598
4599
4600
4601
4602
4603
4604 </fo:block>
4605
4606 <fo:block font-family="Courier" font-size="9pt" space-before.minimum="0.8em" space-before.optimum="1em" space-before.maximum="1.2em" wrap-option="no-wrap" text-align="start" white-space-collapse="false" linefeed-treatment="preserve">
4607
4608
4609 &lt;!-- Please replace everywhere below GNOMEAPPLET with the name of --&gt;
4610 &lt;!-- your applet. Most importantly, all id attributes should start --&gt;
4611 &lt;!-- with the name of your applet - this is necessary to avoid name --&gt;
4612 &lt;!-- conflict among different applets --&gt;
4613 &lt;!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email--&gt;
4614 &lt;!-- Please replace HACKER-NAME with the applet author's name and --&gt;
4615 &lt;!-- HACKER-EMAIL with the applet author's email --&gt;
4616
4617 &lt;!-- You should name your file: GNOMEAPPLET-applet.sgml --&gt;
4618 &lt;!-- Screenshots should be in PNG format and placed in the --&gt;
4619 &lt;!-- same directory as GNOMEAPPLET-applet.sgml --&gt;
4620
4621 &lt;!-- Applet docs will be merged into &lt;chapter&gt;'s inside a --&gt;
4622 &lt;!-- &lt;book&gt;. Thus, the indentation below (2 spaces before the &lt;sect1&gt;) is --&gt;
4623 &lt;!-- correct.--&gt;
4624
4625 &lt;!-- Permission is granted to make and distribute verbatim copies of --&gt;
4626 &lt;!-- this manual provided the copyright notice and this permission --&gt;
4627 &lt;!-- notice are preserved on all copies. --&gt;
4628 &lt;!-- --&gt;
4629 &lt;!-- Permission is granted to copy and distribute modified versions of --&gt;
4630 &lt;!-- this manual under the conditions for verbatim copying, provided --&gt;
4631 &lt;!-- that the entire resulting derived work is distributed under the --&gt;
4632 &lt;!-- terms of a permission notice identical to this one. --&gt;
4633 &lt;!-- --&gt;
4634 &lt;!-- Permission is granted to copy and distribute translations of this --&gt;
4635 &lt;!-- manual into another language, under the above conditions for --&gt;
4636 &lt;!-- modified versions, except that this permission notice may be --&gt;
4637 &lt;!-- stated in a translation approved by the Foundation. --&gt;
4638
4639 &lt;!-- ############### GNOMEAPPLET ############### --&gt;
4640 &lt;sect1 id="GNOMEAPPLET"&gt;
4641 &lt;title&gt;GNOMEAPPLET Applet&lt;/title&gt;
4642
4643 &lt;para&gt;
4644 &lt;application&gt;GNOMEAPPLET&lt;/application&gt; applet, shown in &lt;xref
4645 linkend="GNOMEAPPLET-fig"&gt;, does this and that. To learn how to
4646 add this applet to a &lt;interface&gt;Panel&lt;/interface&gt;, see &lt;xref
4647 linkend="adding-applets"&gt;.
4648 &lt;/para&gt;
4649
4650
4651 &lt;figure id="GNOMEAPPLET-fig"&gt;
4652 &lt;title&gt;GNOMEAPPLET&lt;/title&gt;
4653 &lt;screenshot&gt;
4654 &lt;screeninfo&gt;GNOMEAPPLET&lt;/screeninfo&gt;
4655 &lt;graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME"&gt;
4656 &lt;/graphic&gt;
4657 &lt;/screenshot&gt;
4658 &lt;/figure&gt;
4659
4660 &lt;sect2 id="GNOMEAPPLET-usage"&gt;
4661 &lt;title&gt;Usage&lt;/title&gt;
4662 &lt;para&gt;
4663 This applet does nothing. To use it, just
4664 left-click on it and it will instantly do nothing.
4665 &lt;/para&gt;
4666 &lt;/sect2&gt;
4667
4668 &lt;sect2 id="GNOMEAPPLET-right-click"&gt;
4669 &lt;title&gt;Right-Click Pop-Up Menu Items&lt;/title&gt;
4670 &lt;para&gt;
4671 In addition to the standard menu items (see &lt;xref
4672 linkend="standard-right-click-items"&gt;), the right-click pop-up menu has
4673 the following items:
4674 &lt;itemizedlist&gt;
4675 &lt;listitem&gt;
4676 &lt;para&gt;
4677 &lt;guimenuitem&gt;Properties...&lt;/guimenuitem&gt; &amp;mdash; This menu
4678 item opens the &lt;interface&gt;Properties&lt;/interface&gt; dialog (see
4679 &lt;xref linkend="GNOMEAPPLET-properties"&gt;) which allows you to
4680 customize the appearance and behavior of this applet.
4681 &lt;/para&gt;
4682 &lt;/listitem&gt;
4683 &lt;listitem&gt;
4684 &lt;para&gt;
4685 &lt;guimenuitem&gt;Run Hello World...&lt;/guimenuitem&gt; &amp;mdash; This
4686 menu item starts the program &lt;application&gt;Hello
4687 World&lt;/application&gt;, used to say "hello" to the world.
4688 &lt;/para&gt;
4689 &lt;/listitem&gt;
4690 &lt;/itemizedlist&gt;
4691 &lt;/para&gt;
4692 &lt;/sect2&gt;
4693
4694 &lt;sect2 id="GNOMEAPPLET-properties"&gt;
4695 &lt;title&gt;Properties&lt;/title&gt;
4696 &lt;para&gt;
4697 You can configure &lt;application&gt;GNOMEAPPLET&lt;/application&gt; applet by
4698 right-clicking on the applet and choosing the
4699 &lt;guimenuitem&gt;Properties...&lt;/guimenuitem&gt; menu item. This will open the
4700 &lt;interface&gt;Properties&lt;/interface&gt; dialog, shown in &lt;xref
4701 linkend="GNOMEAPPLET-properties-fig"&gt;.
4702 &lt;/para&gt;
4703 &lt;figure id="GNOMEAPPLET-properties-fig"&gt;
4704 &lt;title&gt;Properties Dialog&lt;/title&gt;
4705 &lt;screenshot&gt;
4706 &lt;screeninfo&gt;Properties Dialog&lt;/screeninfo&gt;
4707 &lt;graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME"&gt;
4708 &lt;/graphic&gt;
4709 &lt;/screenshot&gt;
4710 &lt;/figure&gt;
4711
4712 &lt;para&gt;
4713 To change the color of the applet, click on the
4714 &lt;guibutton&gt;color&lt;/guibutton&gt; button. To change other properties,
4715 click on other buttons.
4716 &lt;/para&gt;
4717
4718 &lt;para&gt;
4719 For more information on the &lt;interface&gt;Properties&lt;/interface&gt;
4720 dialog, including descriptions of the &lt;guibutton&gt;OK&lt;/guibutton&gt;,
4721 &lt;guibutton&gt;Apply&lt;/guibutton&gt;, &lt;guibutton&gt;Cancel&lt;/guibutton&gt;, and
4722 &lt;guibutton&gt;Help&lt;/guibutton&gt; buttons, see &lt;xref
4723 linkend="applet-properties-dialog"&gt;.
4724 &lt;/para&gt;
4725 &lt;/sect2&gt;
4726
4727 &lt;sect2 id="GNOMEAPPLET-bugs"&gt;
4728 &lt;title&gt; Known Bugs and Limitations&lt;/title&gt;
4729 &lt;para&gt;
4730 There are no known bugs in the
4731 &lt;application&gt;GNOMEAPPLET&lt;/application&gt; applet.
4732 &lt;/para&gt;
4733 &lt;/sect2&gt;
4734
4735 &lt;sect2 id="GNOMEAPPLET-authors"&gt;
4736 &lt;title&gt;Authors&lt;/title&gt;
4737 &lt;para&gt;
4738 This applet was writen by HACKER-NAME
4739 &lt;email&gt;HACKER-EMAIL&lt;/email&gt;. The documentation for this applet
4740 which you are reading now was written by
4741 YOUR-NAME &lt;email&gt;YOUR-EMAIL&lt;/email&gt;. For information on submitting
4742 bug reports and suggestions for improvements, see &lt;xref
4743 linkend="feedback"&gt;.
4744 &lt;/para&gt;
4745 &lt;/sect2&gt;
4746
4747 &lt;/sect1&gt;
4748
4749
4750
4751
4752
4753
4754
4755
4756 </fo:block>
4757 </fo:block>
4758 </fo:block>
4759 </fo:block>
4760 </fo:flow>
4761 </fo:page-sequence>
4762 </fo:root>