1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <html><head><title>The GNOME Handbook of Writing Software Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.40"/></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"><div class="titlepage"><div><h2 class="title"><a name="index"/>The GNOME Handbook of Writing Software Documentation</h2></div><div><h3 class="author">David Mason</h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br/></span><div class="address"><br/>
3 <tt><<a href="mailto:dcm@redhat.com">dcm@redhat.com</a>></tt><br/>
4 </div></div><h3 class="author">Daniel Mueth</h3><div class="affiliation"><div class="address"><br/>
5 <tt><<a href="mailto:d-mueth@uchicago.edu">d-mueth@uchicago.edu</a>></tt><br/>
6 </div></div><h3 class="author">Alexander Kirillov</h3><div class="affiliation"><div class="address"><br/>
7 <tt><<a href="mailto:kirillov@math.sunysb.edu">kirillov@math.sunysb.edu</a>></tt><br/>
8 </div></div></div><div><p class="releaseinfo">
10 </p></div><div><p class="copyright">Copyright © 2000 Red Hat, Inc., Daniel Mueth, and Alexander Kirillov</p></div><div><div class="legalnotice"><p>
11 Permission is granted to copy, distribute and/or modify this
12 document under the terms of the <i>GNU Free Documentation
13 License</i>, Version 1.1 or any later version published
14 by the Free Software Foundation with no Invariant Sections, no
15 Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
16 of the <i>GNU Free Documentation License</i> from
17 the Free Software Foundation by visiting <a href="http://www.fsf.org" target="_top">their Web site</a> or by writing to:
18 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 Boston, MA 02111-1307, USA.
21 Many of the names used by companies to distinguish their products and
22 services are claimed as trademarks. Where those names appear in any
23 GNOME documentation, and those trademarks are made aware to the members
24 of the GNOME Documentation Project, the names have been printed in caps
26 </p></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision
28 </td><td align="left">
30 </td></tr></table></div></div><hr/></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt> <a href="#intro">Introduction</a></dt><dd><dl><dt> <a href="#gdp">The GNOME Documentation Project</a></dt><dt> <a href="#notation">Notation and Conventions</a></dt><dt> <a href="#about">About This Handbook</a></dt></dl></dd><dt> <a href="#gettingstarted">Getting Started Writing GNOME Documentation</a></dt><dd><dl><dt> <a href="#selecting">Selecting A Document</a></dt><dt> <a href="#docbook">Installing and Using DocBook</a></dt><dt> <a href="#gdptemplates">GDP Document Templates</a></dt><dt> <a href="#screenshots">Screenshots</a></dt><dt> <a href="#applicationbugs">Application Bugs</a></dt><dt> <a href="#cvs">Using CVS</a></dt></dl></dd><dt> <a href="#gnomedocsystem">The GNOME Documentation System</a></dt><dd><dl><dt> <a href="#gnomehelpbrowser">The GNOME Help Browser</a></dt><dt> <a href="#gnomehelpbrowser2">The GNOME Help Browser (GNOME-2.0)</a></dt><dt> <a href="#gnomehelponthefly">Dynamic Document Synthesis(GNOME-2.0)</a></dt><dt> <a href="#gnomehelpcomponents">The GNOME Documentation Components</a></dt></dl></dd><dt> <a href="#docbookbasics">DocBook Basics </a></dt><dd><dl><dt> <a href="#introtodocbook">Introduction to DocBook</a></dt><dt> <a href="#xml">XML and SGML</a></dt><dt> <a href="#structure"> Structure Elements</a></dt><dt> <a href="#inline">Inline Elements</a></dt></dl></dd><dt> <a href="#conventions">GDP Documentation Conventions </a></dt><dd><dl><dt> <a href="#conventionsalldocs">Conventions for All GDP Documentation</a></dt><dt> <a href="#conventionsappdocs">Conventions for Application Documentation</a></dt></dl></dd><dt> <a href="#writingapplicationmanuals">Writing Application and Applet Manuals</a></dt><dt> <a href="#listingdocsinhelpmenu">Listing Documents in the Help Menu</a></dt><dt> <a href="#applicationhelpbuttons">Application Help Buttons</a></dt><dt> <a href="#packagingappletdocs">Packaging Applet Documentation</a></dt><dd><dl><dt> <a href="#appletfiles">Applet Documentation Files</a></dt><dt> <a href="#appletmenu">Adding Documentation to an Applet Menu</a></dt></dl></dd><dt> <a href="#writingcontextsensitivehelp">Writing Context Sensitive Help (coming in GNOME-2.0)</a></dt><dt> <a href="#referring">Referring to Other GNOME Documentation (coming in
31 GNOME-2.0)</a></dt><dt> <a href="#basics">Basics of Documentation Style</a></dt><dd><dl><dt> <a href="#styleplanning">Planning</a></dt><dt> <a href="#balance">Achieving a Balanced Style</a></dt><dt> <a href="#stylestructure">Structure</a></dt><dt> <a href="#stylegrammar">Grammar and Spelling</a></dt></dl></dd><dt> <a href="#teamwork">Teamwork</a></dt><dd><dl><dt> <a href="#teamworkgdp">Working With The GDP Team</a></dt><dt> <a href="#teamworkdevelopers">Working With Developers</a></dt></dl></dd><dt> <a href="#finishing">Finishing A Document</a></dt><dd><dl><dt> <a href="#editting">Editing The Document</a></dt><dt> <a href="#submitting">Submitting The Document</a></dt></dl></dd><dt> <a href="#resources">Resources</a></dt><dd><dl><dt> <a href="#resourcesweb">Resources On The Web</a></dt><dt> <a href="#resourcesbooks">Books</a></dt><dt> <a href="#mailinglists">Mailing Lists</a></dt><dt> <a href="#irc">IRC</a></dt></dl></dd><dt>A <a href="#templates">Document Templates</a></dt><dd><dl><dt> <a href="#template1">Template 1: Application Manual</a></dt><dt> <a href="#template2-1x">Template 2: Applet Manual For GNOME 1.x</a></dt><dt> <a href="#template2-2x">Template 2: Applet Manual For GNOME 2.x</a></dt></dl></dd></dl></div><div class="sect1"><a name="intro"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="intro"/>Introduction</h2></div></div><div class="sect2"><a name="gdp"/><div class="titlepage"><div><h3 class="title"><a name="gdp"/>The GNOME Documentation Project</h3></div></div><div class="sect3"><a name="goals"/><div class="titlepage"><div><h4 class="title"><a name="goals"/>Goals</h4></div></div><p>
32 The GNOME Documentation Project (GDP) aims to provide GNOME
33 and GNOME applications with a complete, intuitive, and clear
34 documentation system. At the center of the GDP is the
35 GNOME Help Browser, which
36 presents a unified interface to GNOME-specific documentation
37 as well as other Linux documentation such as man pages and
38 texinfo documents. The GNOME Help System provides a
39 comprehensive view of documentation on a machine by
40 dynamically assembling the documentation of GNOME
41 applications and components which are installed. The GDP is
42 responsible for writing numerous GNOME-related documents,
43 both for developers and for users. Developer documentation
44 includes <a href="http://developer.gnome.org/doc/API/" target="_top">APIs for the GNOME libraries</a>, <a href="http://developer.gnome.org/doc/whitepapers/" target="_top"><i>GNOME White
45 Papers</i></a>, GNOME developer <a href="http://developer.gnome.org/doc/tutorials/" target="_top">tutorials</a>, the <a href="http://developer.gnome.org/doc/FAQ/" target="_top"><i>GNOME Developer
46 FAQ</i></a>, the <a href="http://developer.gnome.org" target="_top">GNOME
47 Developer's Website</a>, and <i>GNOME
48 Handbook</i>'s, such as the one you are reading.
49 User documentation include the <a href="http://www.gnome.org/learn/" target="_top"><i>GNOME User's
50 Guide</i></a>, the <a href="http://www.gnome.org/learn/" target="_top"><i>GNOME FAQ</i></a>, and
51 GNOME application documentation. Most GNOME applications
52 have their own manual in addition to context sensitive help.
53 </p></div><div class="sect3"><a name="joining"/><div class="titlepage"><div><h4 class="title"><a name="joining"/>Joining the GDP</h4></div></div><p>
54 Documenting GNOME and all the numerous GNOME applications is
55 a very large project. The GDP is always looking for people
56 to help write, update, and edit documentation. If you are
57 interested in joining the GDP team, you should join the
58 <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
59 <i>gnome-doc-list mailing list</i> </a>.
60 Read <a href="#gettingstarted" title="Getting Started Writing GNOME Documentation">the section called “Getting Started Writing GNOME Documentation”</a>, for help selecting a
61 project to work on. Feel free to introduce yourself on the
62 gnome-doc-list mailing list and indicate which project you
63 intend to work on, or else ask for suggestions of important
64 documents which need work done. You may also want to join the
65 #docs IRC channel on irc.gnome.org to meet other GDP members
66 and discuss any questions you may have. For a list of GDP
67 projects and members, see the
68 <a href="http://developer.gnome.org/projects/gdp" target="_top">
69 <i>GDP Website</i></a>.
70 </p></div><div class="sect3"><a name="collaborating"/><div class="titlepage"><div><h4 class="title"><a name="collaborating"/>Collaborating with the GDP</h4></div></div><p>
71 GNOME developers, packagers, and translators may not be
72 writing GNOME documentation but will want to understand how
73 the GNOME documentation system works and will need to
74 collaborate with GDP members. This document should help to
75 outline the structure of how the GNOME documentation system
76 works. Developers who do not write the documentation for
77 their applications are encouraged to find a GDP member to
78 write the documentation. This is best done by sending an
79 email to the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
80 <i>gnome-doc-list mailing list</i> </a>
81 describing the application, where it can be downloaded from,
82 and that the developer(s) would like a GDP member to write
83 documentation for the application. The #docs IRC channel on
84 irc.gnome.org is another option for contacting GDP members.
85 </p></div></div><div class="sect2"><a name="notation"/><div class="titlepage"><div><h3 class="title"><a name="notation"/>Notation and Conventions</h3></div></div><p>
86 This Handbook uses the following notation:
87 <div class="informaltable" id="id2416529"><a name="id2416529"/><table border="0"><colgroup><col/><col/></colgroup><tbody><tr><td><tt>/usr/bin</tt></td><td>
89 </td></tr><tr><td><tt>foo.sgml</tt></td><td>
91 </td></tr><tr><td><b>command</b></td><td>
92 Command or text that would be typed.
93 </td></tr><tr><td><b><i><tt>replaceable</tt></i></b></td><td>
94 "Variable" text that can be replaced.
95 </td></tr><tr><td><tt>Program or Doc Code</tt></td><td>Program or document code</td></tr></tbody></table></div>
96 </p></div><div class="sect2"><a name="about"/><div class="titlepage"><div><h3 class="title"><a name="about"/>About This Handbook</h3></div></div><p>
97 This Handbook is a guide for both writing documentation for
98 GNOME components and applications and for properly binding and
99 packaging documentation into GNOME applications.
101 This Handbook, like all GNOME documentation, was written in
102 DocBook(SGML) and is available in several formats including
103 SGML, HTML, PostScript, and PDF. For the latest version, see
104 <a href="http://developer.gnome.org/projects/gdp/handbook.html" target="_top">
105 <i>Getting The GNOME Handbook of Writing Software
106 Documentation</i> </a>. Alternately, one may
107 download it anonymously from GNOME CVS under <tt>gnome-docu/gdp</tt>.
108 </p></div></div><div class="sect1"><a name="gettingstarted"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="gettingstarted"/>Getting Started Writing GNOME Documentation</h2></div></div><div class="sect2"><a name="selecting"/><div class="titlepage"><div><h3 class="title"><a name="selecting"/>Selecting A Document</h3></div></div><div class="sect3"><a name="know"/><div class="titlepage"><div><h4 class="title"><a name="know"/>Document Something You Know</h4></div></div><p>
109 The most frequently asked question of new contributors who
110 join the GDP is "which document should I start
111 with?". Because most people involved are volunteers, we do
112 not <i>assign</i> projects and applications to
113 write documents for. The first step is all yours - you must
114 decide what about GNOME interests you most and find out if
115 it has complete documents or not.
117 It is also important to spend some time with GNOME to make
118 sure you are familiar enough with it to be
119 <i>authoritative</i> in your writing. The
120 best way to do this is to just sit down and play with GNOME
121 as much as possible before starting to write.
123 The easiest way to get started is to improve existing
124 documentation. If you notice some inaccuracies or omissions
125 in the documentation, or you think that you can explain the
126 material more clearly, just send your suggestions to the
127 author of the original documentation or to the GNOME
128 documentation project at <tt><<a href="mailto:docs@gnome.org">docs@gnome.org</a>></tt>.
129 </p></div><div class="sect3"><a name="doctable"/><div class="titlepage"><div><h4 class="title"><a name="doctable"/>The GNOME Documentation Status Table</h4></div></div><p>
130 The <i>GDP Documentation Status Table</i>
131 (<i>DocTable</i>) (<a href="http://www.gnome.org/gdp/doctable/" target="_top">http://www.gnome.org/gdp/doctable/</a>) is a
132 web page which tracks the status of all the various
133 documentation components of GNOME. These components include
134 application documentation, internal GNOME component
135 documentation, user documentation, and developer
136 documentation. For each documentation item, it tracks the
137 current status of the documentation, who is working on the
138 particular document, where the documentation can be found,
139 and provides a forum for the discussion of each item.
141 You should use the <i>DocTable</i> to help
142 you select a documentation item which needs work done. Once
143 you have selected an item to work on, please register
144 yourself as an author so that other authors do not duplicate
145 your work and may contact you to help or offer suggestions.
146 Also be sure to keep the status icons up-to-date so that
147 the GDP team can easily identify which items need additional
148 help. The <i>DocTable</i> also allows
149 people to make announcements and suggestions and to discuss
150 issues in the comments section.
151 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2412924"/>Note</h3><p>
152 Note that the information in the
153 <i>DocTable</i> may not always be up-to-date
154 or accurate. When you assign yourself to documenting an
155 application, make sure you find out the latest status of
156 documentation by contacting the application author.
157 </p></div></div></div><div class="sect2"><a name="docbook"/><div class="titlepage"><div><h3 class="title"><a name="docbook"/>Installing and Using DocBook</h3></div></div><p>
158 All documentation for the GNOME project is written in SGML
159 using the DocBook DTD. There are many advantages to using
160 this for documentation, not least of which is the single
161 source nature of SGML. To contribute to the GDP you should
162 learn to use DocBook.
163 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2412986"/>NOTE</h3><p>
164 To get started writing for the GDP you do not need to rush
165 out and learn DocBook - if you feel it is too much to handle
166 for now, you can submit plain ASCII text to the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
167 <i>gnome-doc-list mailing list</i>
168 </a>and a volunteer will mark it up for you. Seeing your
169 document marked up will also be a great way for you to start
171 </p></div><div class="sect3"><a name="installingdocbook"/><div class="titlepage"><div><h4 class="title"><a name="installingdocbook"/>Installing DocBook</h4></div></div><p>
172 Download and install the following <a href="ftp://sourceware.cygnus.com:/pub/docbook-tools/" target="_top">DocBook Tools packages</a>: jade, docbook,
173 jadetex, sgml-common, and stylesheets. (RPM users should note
174 that jade is platform dependent (eg. i386), while the other packages
175 are in the <tt>noarch</tt>
176 directory.) You can find more
177 information on DocBook Tools <a href=" http://sourceware.cygnus.com/docbook-tools/" target="_top">here</a>.
179 If you are an Emacs user you may
180 want to grab the psgml package as well. This is a major mode
181 for editing sgml files in Emacs.
182 </p></div><div class="sect3"><a name="gdpstylesheets"/><div class="titlepage"><div><h4 class="title"><a name="gdpstylesheets"/>GDP Stylesheets</h4></div></div><p>
183 The GDP uses its own DocBook stylesheets. To use the GDP
184 stylesheets, you should download the file
185 <tt>gdp-both.dsl</tt> from the <tt>gnome-docu/gdp/dsssl</tt> module in
186 CVS (or from <a href="http://developer.gnome.org/projects/gdp/stylesheets.html" target="_top">
187 GDP Custom DSSSL Stylesheet</a>)and copy it
190 <tt>/usr/lib/sgml/stylesheets/cygnus-both.dsl</tt>.
191 Alternately, you can download and install the
192 <a href="http://people.redhat.com/dcm/software.html" target="_top">gnome-doc-tools package</a> which will set
193 up the stylesheets as well as the DTD discussed below.
194 </p></div><div class="sect3"><a name="gdpdtd"/><div class="titlepage"><div><h4 class="title"><a name="gdpdtd"/>GDP DTD (PNG Image Support)</h4></div></div><p>
195 Due to some license issues involved with the creation of
196 gifs, the GNOME Documentation Project has decided to use the
197 PNG image format for all images in GNOME documentation. You
198 can read more about the issues involved with gifs at <a href="http://www.gnu.org/philosophy/gif.html" target="_top">http://www.gnu.org/philosophy/gif.html</a>.
200 The current DocBook DTD(3.1) does not include support for
201 embedding PNG images in your documents. Since the GDP uses
202 many screenshots in its documentation, we use our own
203 variation on the DocBook DTD which has PNG image support.
204 We encourage everybody to use this DTD instead of the
205 default DocBook DTD since your source document header and
206 your output document appearance subtly vary between the two
207 DTD's. To install the GDP custom DTD with PNG image support
209 </p><div class="itemizedlist"><ul><li style="list-style-type: opencircle"><p><a name="id2413298"/>
210 Download <a href="http://www.labs.redhat.com/png/png-support.html" target="_top">the
211 GDP DocBook DTD for PNG support</a> and install it
212 where you keep your DTD's. (On Red Hat use <tt>/usr/lib/sgml/</tt>.) Note that
213 the 3.0 DTD is missing support for the
214 <tt><legalnotice></tt> tag, so it is
215 recommended that you use version 3.1
216 </p></li><li style="list-style-type: disc"><p><a name="id2413345"/>
217 Add the new DTD to your SGML CATALOG file. The location
218 of your SGML CATALOG file may vary depending upon your
219 distribution. (On Red Hat it is usually in
220 /usr/lib/sgml/CATALOG.) Add the following line to this
222 <pre class="programlisting">
223 PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd"
225 If you are using the 3.1 DTD, use:
226 <pre class="programlisting">
227 PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd"
229 </p></li></ul></div><p>
230 Alternately, you can download and install the
231 <a href="http://people.redhat.com/dcm/software.html" target="_top">gnome-doc-tools package</a> which will set
232 up the custom stylesheets and DTD for you.
234 To include PNG files in your documents, you will need to
235 indicate that you are using this special DTD. To do
236 this, use the following headers:
239 <pre class="programlisting">
240 <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant
245 <pre class="programlisting">
246 <!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant
249 </p></div><div class="sect3"><a name="editors"/><div class="titlepage"><div><h4 class="title"><a name="editors"/>Editors</h4></div></div><p>
250 There are many editors on Linux and UNIX systems available
251 to you. Which editor you use to work on the sgml documents
252 is completely up to you, as long as the editor is able to
253 preserve sgml and produce the source in a format that is
254 readable by everyone.
256 Probably the two most popular editors available are
258 vi. These and other editors are
259 used regularly by members of the GDP. Emacs has a major
260 mode, psgml, for editing sgml files which can save you time
261 and effort in adding and closing tags. You will find the
262 psgml package in DocBook Tools, which is the standard set of
263 tools for the GDP. You may find out more about DocBook Tools
264 in <a href="#installingdocbook" title="Installing DocBook">the section called “Installing DocBook”</a>.
265 </p></div><div class="sect3"><a name="make-output"/><div class="titlepage"><div><h4 class="title"><a name="make-output"/>Creating Something Useful with your Docs</h4></div></div><p>
266 The tools available in DocBook Tools allow you to convert
267 your sgml document to many different formats including html
268 and Postscript. The primary tool used to do the conversion
269 is an application called Jade. In
270 most cases you will not have to work directly with
271 Jade; Instead, you will use the
272 scripts provided by DocBook Tools.
274 To preview your DocBook document, it is easiest to convert
275 it to <tt>html</tt>. If you have installed the
276 DocBook tools described above, all you have to do is to run
277 the command <tt>$</tt><b>db2html
278 mydocument.sgml</b>. If there are no sgml syntax
279 errors, this will create a directory <tt>mydocument</tt> and place the
280 resulting html files in it. The title page of the document
282 <tt>mydocument/index.html</tt>. If you have
283 screenshots in your document, you will have to copy these
284 files into the <tt>mydocument</tt> directory by
285 hand. You can use any web browser to view your document.
286 Note that every time you run <b>db2html</b>, it
287 creates the <tt>mydocument</tt> directory over, so
288 you will have to copy the screenshots over each time.
290 You can also convert your document to PostScript by running
291 the command <tt>$</tt><b>db2ps
292 mydocument.sgml</b>, after which you can print out or
293 view the resulting .ps file.
294 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2413716"/>NOTE</h3><p>
295 The html files you get will not look quite the same as the
296 documentation distributed with GNOME unless you have the
297 custom stylesheets installed on your machine. DocBook
298 Tools' default stylesheets will produce a different look
299 to your docs. You can read more about the GDP stylesheets
300 in <a href="#gdpstylesheets" title="GDP Stylesheets">the section called “GDP Stylesheets”</a>.
301 </p></div></div><div class="sect3"><a name="jadeimages"/><div class="titlepage"><div><h4 class="title"><a name="jadeimages"/>Images in DocBook Tools</h4></div></div><p>
302 If your document uses images you will need to take note of a
303 few things that should take place in order for you to make
304 use of those images in your output.
306 The DocBook Tools scripts and applications are smart enough
307 to know that when you are creating html you will be using
308 PNG files and when you are creating Postscript you will be
309 using EPS files (you must use EPS with Postscript).
311 Thus, you should never explicitly
312 include the extension of the image file, since DocBook
313 Tools will automatically insert it for you. For example:
314 </p><pre class="programlisting">
317 <title>My Image</title>
319 <screeninfo>Sample GNOME Display</screeninfo>
320 <graphic format="png" fileref="myfile" srccredit="me">
325 You will notice in this example that the file
326 <tt>myfile.png</tt> was referred to as simply
327 <tt>myfile</tt>. Now when you run
328 <b>db2html</b> to create an html file, it will
329 automatically look for <tt>myfile.png</tt> in
332 If you want to create PostScript ouput, you will need to create an
333 EPS version of your image file to be displayed in the
334 PostScript file. There is a simple script available which
335 allows you to change a PNG image into an EPS file
336 easily. You can download this file - img2eps - from <a href="http://people.redhat.com/dcm/sgml.html" target="_top">http://people.redhat.com/dcm/sgml.html</a>
337 (look for the img2eps section). Note that this script is
338 included in the gnome-doc-tools package, so if you are using
339 this package, you should already have
340 <b>img2eps</b> on you system.
341 </p></div><div class="sect3"><a name="moredocbookinfo"/><div class="titlepage"><div><h4 class="title"><a name="moredocbookinfo"/>Learning DocBook</h4></div></div><p>
342 There are many resources available to help you learn DocBook.
343 The following resources on the web are useful for learning
345 </p><div class="itemizedlist"><ul><li style="list-style-type: disc"><p><a name="id2413930"/>
346 <a href="http://www.docbook.org" target="_top">http://www.docbook.org</a> - Norman
347 Walsh's <i>DocBook: The Definitive
348 Guide</i>. Online O'Reilly book on using
349 DocBook. Contains an excellent element reference. May be
350 too formal for a beginner.
351 </p></li><li style="list-style-type: disc"><p><a name="id2413963"/>
352 <a href="http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html" target="_top">A Practical Introduction to DocBook</a>
353 - The Open Source Writers Group's introduction to using
354 DocBook. This is an excellent HOW-TO type article on
356 </p></li><li style="list-style-type: disc"><p><a name="id2413992"/>
357 <a href="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html" target="_top">Getting Going with DocBook: Notes for
358 Hackers</a> - Mark Galassi's introduction to DocBook
359 for hackers. This has to be one of the first
360 introductions to DocBook ever - still as good as it ever
362 </p></li><li style="list-style-type: disc"><p><a name="id2527122"/>
363 <a href="http://www.freebsd.org/tutorials/docproj-primer/" target="_top">
364 FreeBSD Documentation Project Primer for New
365 Contributors</a> - FreeBSD documentation project
366 primer. Chapter 4.2 provides a very good introduction to
367 writing documentation using DocBook. Note that it also
368 describes some custom extensions of DocBook;
369 fortunately, they are clearly marked as such.
370 </p></li></ul></div><p>
371 Norman Walsh's book is also available in print.
373 The following sections of this document are designed to help
374 documentation authors write correct and consistent DocBook:
375 </p><div class="itemizedlist"><ul><li style="list-style-type: disc"><p><a name="id2527176"/>
376 <a href="#docbookbasics" title="DocBook Basics ">the section called “DocBook Basics ”</a> - Descriptions of
377 commonly used DocBook tags.
378 </p></li></ul></div><p>
379 You may also discuss specific DocBook questions with GDP
380 members on the #docs IRC channel at irc.gnome.org and on the
381 gnome-doc-list mailing list.
382 </p></div></div><div class="sect2"><a name="gdptemplates"/><div class="titlepage"><div><h3 class="title"><a name="gdptemplates"/>GDP Document Templates</h3></div></div><p>
383 Templates for various types of GNOME documents are found in
384 <a href="#templates" title="A. Document Templates">Appendix A. Document Templates</a>. They are kept in CVS in
385 gnome-docu/gdp/templates. The easiest source to get them from
386 is probably the <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
387 Document Templates</a> web page, which is typically kept
388 completely up-to-date with CVS and has a basic description of
390 </p></div><div class="sect2"><a name="screenshots"/><div class="titlepage"><div><h3 class="title"><a name="screenshots"/>Screenshots</h3></div></div><p>
391 Most GNOME documents will have screenshots of the particular
392 applet, application, GNOME component, or widget being
393 discussed. As discussed above in <a href="#gdpdtd" title="GDP DTD (PNG Image Support)">the section called “GDP DTD (PNG Image Support)”</a> you
394 will need to install the special GDP DocBook DTD which
395 supports PNG images, the format used for all images in GNOME
396 documentation. For the basic DocBook structure used to insert
397 images in a document, see <a href="#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a> above.
398 </p><div class="sect3"><a name="screenshotappearance"/><div class="titlepage"><div><h4 class="title"><a name="screenshotappearance"/>Screenshot Appearance</h4></div></div><p>
399 For all screenshots of windows that typically have border
400 decorations (e.g. applications and dialogs, but not applets
401 in a panel), GDP standards dictate
402 the appearance of the window. (This is to minimize possible
403 confusion to the reader, improve the appearance of GNOME
404 documents, and guarantee the screenshot is readable when
405 printed.) All screenshots should be taken with the SawFish
406 (formerly known as Sawmill) window manager using the
407 MicroGui theme and Helvetica 12pt font. (A different window
408 manager can be used provided the MicroGui theme is available
409 for this window manager and the appearance is identical to
410 that when using the SawFish window manager.) The default
411 GTK+ theme(gtk) and font (Helvetica 12 pt) should be used
412 for all screenshots. If you are unable to provide
413 screenshots in this form, you should create screenshots as
414 you wish them to appear and send them to the
415 <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
416 <i>gnome-doc-list mailing list</i> </a>
417 requesting a GDP member reproduce these screenshots in the
418 correct format and email them to you.
419 </p></div><div class="sect3"><a name="screenshottools"/><div class="titlepage"><div><h4 class="title"><a name="screenshottools"/>Screenshot Tools</h4></div></div><p>
420 There are many tools for taking screenshots in
421 GNOME/Linux. Perhaps the most convenient is the
422 Screen-Shooter Applet. Just click
423 on the window icon in the applet and then on the window you
424 would like to take a screenshot of. (Note that
425 at the time of this writing, PNG images taken by
426 screenshooter do not appear properly in
428 GNOME Help Browser. You
429 should save your screenshot as a GIF and
430 then use <b>convert filename.gif
431 filename.png</b>.) For applets
433 xv can be used to crop the
434 screenshot to only include the relevant portion of the
437 gimp can both be used for taking
438 screenshots, cropping screenshots, and converting image
440 </p></div><div class="sect3"><a name="screenshotfiles"/><div class="titlepage"><div><h4 class="title"><a name="screenshotfiles"/>Screenshot Files</h4></div></div><p>
441 Screenshots should be kept in the main documentation
442 directory with your SGML file for applets, or should be
443 kept in a directory called "figs" for application and other
444 documentation. After you use <b>db2html</b> to
445 convert your SGML file to HTML (see <a href="#make-output" title="Creating Something Useful with your Docs">the section called “Creating Something Useful with your Docs”</a>), you will need to copy your
446 screenshots (either the individual PNG files for applet
447 documentation, or the whole "figs" directory for other
448 documentation) into the newly created HTML directory. Note
449 that every time you use <b>db2html</b> the HTML
450 directory is erased and rewritten, so do not store your only
451 copy of the screenshots in that directory. If you wish to
452 create PostScript or PDF output, you will need to manually
453 convert the PNG images to EPS as described in <a href="#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a>, but will not need to copy these
454 images from their default location, as they are included
455 directly into the output(PostScript of PDF) file.
456 </p></div></div><div class="sect2"><a name="applicationbugs"/><div class="titlepage"><div><h3 class="title"><a name="applicationbugs"/>Application Bugs</h3></div></div><p>
457 Documentation authors tend to investigate and test applets and
458 applications more thoroughly than most
459 users. Often documentation authors will discover one or
460 more bugs in the software. These bugs vary from small ones,
461 such as mis-spelled words or missing
462 About dialogs in the menu, to large
463 ones which cause the applet to crash. As all users, you
464 should be sure to report these bugs so that application
465 developers know of them and can fix them. The easiest way to
466 submit a bug report is by using the Bug
467 Buddy applet which is part of the gnome-applets
469 </p></div><div class="sect2"><a name="cvs"/><div class="titlepage"><div><h3 class="title"><a name="cvs"/>Using CVS</h3></div></div><p>
470 CVS (Concurrent Versions System) is a tool that allows
471 multiple developers to concurrently work on a set of
472 documents, keeping track of the modifications made by each
473 person. The files are stored on a server and each developer
474 checks files out, modifies them, and then checks in their
475 modified version of the files. Many GNOME programs and
476 documents are stored in CVS. The GNOME CVS server allows
477 users to anonymously check out CVS files. Most GDP members
478 will need to use anonymous CVS to download the most up-to-date
479 version of documentation or programs. Modified documents will
480 typically be emailed to the the application developer. Core
481 GDP members may also be granted login CVS privileges so they
482 may commit modified files directly to CVS.
483 </p><div class="sect3"><a name="anonymouscvs"/><div class="titlepage"><div><h4 class="title"><a name="anonymouscvs"/>Anonymous CVS</h4></div></div><p>
484 To anonymously check out documents from CVS, you must first
485 log in. From the bash shell, you should set your CVSROOT
486 shell variable with <b> export
487 CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</b>
488 and then login with <b>cvs login</b>(there is no
489 password, just hit return). As an example, we will use the
490 "gnome-docu/gdp" module which contains this and several
491 other documents. To check these documents out for the first
492 time, type <b>cvs -z3 checkout
493 gnome-docu/gdp</b>. After you have this document
494 checked out and you would like to download any updates on
495 the CVS server, use <b>cvs -z3 update -Pd</b>.
496 </p></div><div class="sect3"><a name="logincvs"/><div class="titlepage"><div><h4 class="title"><a name="logincvs"/>Login CVS</h4></div></div><p> If you have been given a
497 login for the GNOME CVS server, you may commit your file
498 modifications to CVS. Be sure to read the following section
499 on CVS etiquette before making any commits to CVS. To log in
500 to the CVS server as user
501 <b><i><tt>username</tt></i></b> with a
502 password, you must first set your CVSROOT shell variable with
504 CVSROOT=':pserver:<i><tt>username</tt></i>@cvs.gnome.org:/cvs/gnome'</b>.
505 Log in with <b>cvs login</b> and enter your
506 password. You may check out and update modules as described
507 above for anonymous CVS access. As a login CVS user, you may
508 also check modified versions of a file into the CVS server.
510 <b><i><tt>filename</tt></i></b> into
511 the CVS server, type <b>cvs -z3 commit
512 <i><tt>filename</tt></i></b>. You will be
513 given a vi editor window to type in a brief log entry,
514 summarizing your changes. The default editor can be changed
515 using the <tt>EDITOR</tt> environment variable or
516 with the <b><tt>-e</tt></b> option. You
517 may also check in any modifications to files in the working
518 directory and subdirectories using <b>cvs -z3
520 add a new file to the CVS server, use <b>cvs -z3 add
521 <i><tt>filename</tt></i></b>, followed by the
523 </p></div><div class="sect3"><a name="cvsetiquette"/><div class="titlepage"><div><h4 class="title"><a name="cvsetiquette"/>CVS Etiquette</h4></div></div><p>
524 Because files in CVS are typically used and modified by
525 multiple developers and documentation authors, users should
526 exercise a few simple practices out of courtesy towards the
527 other CVS users and the project leader. First, you should
528 not make CVS commits to a package without first discussing
529 your plans with the project leader. This way, the project
530 leader knows who is modifying the files and generally, what
531 sort of changes/development is being done. Also, whenever a
532 CVS user commits a file to CVS, they should make an entry in
533 the CVS log and in the <tt>ChangeLog</tt> so
534 that other users know who is making modifications and what
535 is being modified. When modifying files created by others,
536 you should follow the indentation scheme used by the initial
538 </p></div></div></div><div class="sect1"><a name="gnomedocsystem"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="gnomedocsystem"/>The GNOME Documentation System</h2></div></div><div class="sect2"><a name="gnomehelpbrowser"/><div class="titlepage"><div><h3 class="title"><a name="gnomehelpbrowser"/>The GNOME Help Browser</h3></div></div><p>
539 At the core of the GNOME help system is the GNOME
540 Help Browser. The Help
541 Browser provides a unified interface to several
542 distinct documentation systems on Linux/Unix systems: man
543 pages, texinfo pages, Linux Documentation Project(LDP)
544 documents, GNOME application documentation, and other GNOME
547 The GNOME Help Browser works by
548 searching standard directories for documents which are to be
549 presented. Thus, the documentation that appears in the GHB is
550 specific to each computer and will typically only represent
551 software that is installed on the computer.
552 </p></div><div class="sect2"><a name="gnomehelpbrowser2"/><div class="titlepage"><div><h3 class="title"><a name="gnomehelpbrowser2"/>The GNOME Help Browser (GNOME-2.0)</h3></div></div><p> In
553 GNOME 2.0, the GNOME Help Browser
554 will be replaced by Nautilus.
555 Nautilus will be the file manager/graphical shell for GNOME 2.0
556 and will also implement a more sophisticated help system than
557 that used by the GNOME Help Browser
558 used in GNOME 1.0. It will read and display DocBook files
559 directly, avoiding the need for duplicating documents in both
560 DocBook and HTML formats. Its display engine for DocBook will
561 be much faster than running jade to
562 convert to HTML for rendering. Because it uses the original
563 DocBook source for documentation, it will be possible to do more
564 sophisticated searching using the meta information included in
565 the documents. And since Nautilus is a virtual file system
566 layer which is Internet-capable, it will be able to find and
567 display documents which are on the web as well as those on the
568 local file system. For more information on
569 Nautilus, visit the #nautilus IRC
570 channel on irc.gnome.org. </p></div><div class="sect2"><a name="gnomehelponthefly"/><div class="titlepage"><div><h3 class="title"><a name="gnomehelponthefly"/>Dynamic Document Synthesis(GNOME-2.0)</h3></div></div><p>
571 GNOME uses the documentation presented by all the various
572 GNOME components and applications installed on the system to
573 present a complete and customized documentation environment
574 describing only components which are currently installed on a
575 users system. Some of this documentation, such as the manuals
576 for applets, will be combined in such a way that it appears to
577 be a single document.
579 By using such a system, you can be sure that any GNOME app you
580 install that has documentation will show up in the index,
581 table of contents, any search you do in the help browser.
582 </p></div><div class="sect2"><a name="gnomehelpcomponents"/><div class="titlepage"><div><h3 class="title"><a name="gnomehelpcomponents"/>The GNOME Documentation Components</h3></div></div><div class="sect3"><a name="applicationmanualsintro"/><div class="titlepage"><div><h4 class="title"><a name="applicationmanualsintro"/>Application Manuals</h4></div></div><p>
583 Every GNOME application should have an application manual.
584 An application manual is a document specific to the
585 particular application which explains the various windows
586 and features of the application. Application Manuals
587 typically use screenshots (PNG format) for clarity. Writing
588 application manuals is discussed in more detail in <a href="#writingapplicationmanuals" title="Writing Application and Applet Manuals">the section called “Writing Application and Applet Manuals”</a> below.
589 </p></div><div class="sect3"><a name="applicationhelpintro"/><div class="titlepage"><div><h4 class="title"><a name="applicationhelpintro"/>Application Help</h4></div></div><p>
590 Applications should have a Help
591 button on screens on which users may need help. These
592 Help buttons should pull up the
593 default help browser, determined by the
594 <tt>ghelp</tt> URL Handler (configured using the
595 Control Center), typically the
596 GNOME Help Browser. The help
597 browser should show either the first page of the application
598 manual, or else the relevant page thereof. Application help
599 is described in more detail in <a href="#applicationhelpbuttons" title="Application Help Buttons">the section called “Application Help Buttons”</a> below.
600 </p></div><div class="sect3"><a name="contextsensitivehelpintro"/><div class="titlepage"><div><h4 class="title"><a name="contextsensitivehelpintro"/>Application Context Sensitive Help (coming in
601 GNOME-2.0)</h4></div></div><p>
602 Context sensitive help is a system which will allow the user
603 to query any part (button, widget, etc.) of an application
604 window. This is done by either entering a CS Help mode by
605 clicking on an icon or by right clicking on the application
606 part and selecting "What's This" or whatever is decided on
607 at the time. Context sensitive help is described in more
608 detail in <a href="#writingcontextsensitivehelp" title="Writing Context Sensitive Help (coming in GNOME-2.0)">the section called “Writing Context Sensitive Help (coming in GNOME-2.0)”</a>
610 </p></div><div class="sect3"><a name="userguide"/><div class="titlepage"><div><h4 class="title"><a name="userguide"/>The GNOME User Guide</h4></div></div><p>
611 The <i>GNOME User Guide</i> describes the
612 GNOME desktop environment and core components of GNOME such
614 control center. In GNOME 1.x this
615 was the main and only source of documentation. In GNOME 2.0
616 this will become a document for the web and for printing
617 that is derived from various parts chosen in the system that
618 are necessary for the new user to understand.
619 </p></div><div class="sect3"><a name="userdocs"/><div class="titlepage"><div><h4 class="title"><a name="userdocs"/>User Documents</h4></div></div><p>
620 Aside from the <i>GNOME User Guide</i>,
621 there are several other documents to help GNOME users learn
622 GNOME, including the <i>GNOME FAQ</i>,
623 <i>GNOME Installation and Configuration
624 Guide</i>, and the <i>GNOME Administrators
626 </p></div><div class="sect3"><a name="developerdocs"/><div class="titlepage"><div><h4 class="title"><a name="developerdocs"/>Developer Documents</h4></div></div><p>
627 There are many White Papers, Tutorials, HOWTO's and FAQ's to
628 make programming GNOME and GNOME applications as easy as
631 API documentation is also available for the GNOME libraries. This is
632 detailed documentation of the code that is used to build GNOME
633 apps. You can keep up with the GNOME API docs on the <a href="http://developer.gnome.org/doc/API/" target="_top">GNOME API
635 </p></div><div class="sect3"><a name="projectdocs"/><div class="titlepage"><div><h4 class="title"><a name="projectdocs"/>Project Documents</h4></div></div><p>
636 Some GNOME projects have documentation to maintain
637 consistency in their product and to help new contributors
638 get up to speed quickly. Among these are the GDP documents,
639 such as the one you are reading now.
640 </p></div></div></div><div class="sect1"><a name="docbookbasics"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="docbookbasics"/>DocBook Basics </h2></div></div><div class="sect2"><a name="introtodocbook"/><div class="titlepage"><div><h3 class="title"><a name="introtodocbook"/>Introduction to DocBook</h3></div></div><p>
641 To understand DocBook, a basic understanding of SGML is
642 helpful. SGML stands for Standard General Markup Language and
643 is one of the first markup languages every created. HTML is
644 actually derived from SGML and XML is a subset of SGML. SGML
645 uses what is called a Document Type Definition to specify
646 <i>elements</i> which are contained between
647 brackets, < and >. Text is marked by both beginning and
648 ending elements, for example in the DocBook DTD, one denotes a
649 title with <tt><title></tt>The
650 Title<tt></title></tt>.
652 The DTD (in the case of the GDP, DocBook) defines rules for how the
653 elements can be used. For example, if one element can only be used when
654 embedded within another, this is defined in the DTD.
656 An SGML file is just a plain ASCII file containing the text
657 with the markup specified above. To convert it to some easily
658 readable format, you need special tools. The GDP uses <i>DocBook
659 Tools</i>, a free package of utilities for working with DocBook
660 which includes <i>Jade</i>, which does the SGML/DSSL
661 parsing. You can read more about DocBook Tools in <a href="#installingdocbook" title="Installing DocBook">the section called “Installing DocBook”</a>.
663 The final appearance of the output (e.g. PostScript or HTML)
665 <i>stylesheet</i>. Stylesheets are files,
666 written in a special language (DSSSL -- Document Style
667 Semantics and Specification Language), which specify the
668 appearance of various DocBook elements, for example,
669 what fonts to use for titles and various inline elements, page
670 numbering style, and much more. DocBook tools come with a
671 collection of stylesheets (Norman Walsh's modular
672 stylesheets); GNOME Document Project uses some customized
673 version of this stylesheets -- see <a href="#gdpstylesheets" title="GDP Stylesheets">the section called “GDP Stylesheets”</a>.
675 The advantage of specifying the <i>structure</i>
676 of a document with SGML instead of specifying the
677 <i>appearance</i> of the document with a typical
678 word processor, or with html, is that the resulting document
679 can be processed in a variety of ways using the structural
680 information. Whereas formatting a document for appearance
681 assumes a medium (typically written text on a standard-sized
682 piece of paper), SGML can be processed to produce output for a
683 large variety of media such as text, postscript, HTML,
684 Braille, audio, and potentially many other formats.
686 Using 'content' as the elements to define the text of a document also
687 allows for search engines to make use of the actual elements to make a
688 "smarter search". For example, if you are searching for all documents
689 written by the author "Susie" your search engine could be made smart
690 enough to only search <author> elements, making for a faster and more
693 Since the overall appearance of the output is determined not by the DTD
694 or the SGML document, but rather by a stylesheet, the appearance of a
695 document can be easily changed just by changing the stylesheet. This
696 allows everyone in the project to create documents that all look the
699 As stated before, the GDP uses the DocBook DTD. For a list of
700 introductory and reference resources on DocBook, see <a href="#resources" title="Resources">the section called “Resources”</a>. The following sections also provide
701 convenient instructions on which markup tags to use in various
702 circumstances. Be sure to read <a href="#conventions" title="GDP Documentation Conventions ">the section called “GDP Documentation Conventions ”</a>
703 for GDP documentation-specific guidelines.
704 </p></div><div class="sect2"><a name="xml"/><div class="titlepage"><div><h3 class="title"><a name="xml"/>XML and SGML</h3></div></div><p> In not so distant future (probably before GNOME 2.0),
705 DocBook itself and GNOME Documentation project will migrate from
706 SGML to XML. This transition should be relatively painless:
707 (almost) all DocBook tags will remain the same. However, XML has
708 stricter syntax rules than SGML; thus, some constructions which
709 are valid in SGML will not be valid in XML. Therefore, to be
710 ready for this transistion, it is <i>strongly
711 advised</i> that the documentation writers conform to XML
712 syntax rules. Here are most important differences:
713 </p><div class="variablelist"><dl><dt><a name="id2529076"/><span class="term"> <i>Minimization</i></span></dt><dd><p><a name="id2529088"/>
714 It is possible with some implementations of SGML to use
715 minimizations to close elements in a document by using
716 </>, for example:
717 <tt><tt><title></tt>The
718 Title<tt></></tt></tt>. This is not
719 allowed in XML. You can use <b>sgmlnorm</b> command,
720 included in DocBook Tools package, to expand minimized tags;
721 if you are using Emacs with psgml
722 mode, you can also use menu command
723 Modify->Normalize.
724 </p></dd><dt><a name="id2529176"/><span class="term"> <i>Self-closing tags</i></span></dt><dd><p><a name="id2529188"/>
725 Also, in SGML some tags are allowed not to have closing
726 tags. For example, it is legal for
727 <tt><xref></tt> not to have a closing tag:
729 linkend="someid"></tt></tt>. In
730 XML, it is illegal; instead, you should use
732 linkend="someid"/></tt></tt> (note the
734 </p></dd><dt><a name="id2529236"/><span class="term"> <i>Case sensitive tags</i></span></dt><dd><p><a name="id2529248"/>
735 In XML, unlike SGML, tags are case-senstive
736 <tt><title></tt> and
737 <tt><TITLE></tt> are different tags!
738 Therefore, please always use lowercase tags (except for
739 things like <tt>DOCTYPE, CDATA</tt> and
740 <tt>ENTITY</tt>, which are not DocBook tags).
741 </p></dd></dl></div></div><div class="sect2"><a name="structure"/><div class="titlepage"><div><h3 class="title"><a name="structure"/> Structure Elements</h3></div></div><div class="sect3"><a name="section"/><div class="titlepage"><div><h4 class="title"><a name="section"/>Sections and paragraphs</h4></div></div><p>
742 Top-level element of a book body must be
743 <tt><chapter></tt>; it may contain one or more
744 <tt><sect1></tt>, each of them may contain
745 <tt><sect2></tt> and so on up to
746 <tt><sect5></tt>. The top-level element of an
747 article body is always
748 <tt><sect1></tt>. Regardless of which elements
749 you use, give each structural element a unique id, so that
750 you can link to it. For usage example, see the template.
751 </p><p> Please try to avoid using deeply nested sections; for
752 most situations, <tt><sect1></tt> and
753 <tt><sect2></tt> should be sufficient. If not,
754 you probably should split your <tt><sect1></tt>
755 into several smaller ones.
756 </p><p> Use the tag <tt><para></tt> for
757 paragraphs, even if there is only one paragraph in a
758 section--see template for examples.
759 </p></div><div class="sect3"><a name="notes"/><div class="titlepage"><div><h4 class="title"><a name="notes"/>Notes, Warnings, And Tips</h4></div></div><p>
760 For notes, tips, warnings, and important information, which
761 should be set apart from the main text (usually as a
762 paragraph with some warning sign on the margin), use tags
763 <tt><note></tt>, <tt><tip></tt>,
764 <tt><warning></tt>,
765 <tt><important></tt> respectively. For example:
766 <pre class="programlisting">
769 <title>TIP</title>
771 To speed up program compilation, use <application>gcc</application>
772 compiler with Pentium optimization.
774 </tip> </pre> produces
775 </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="extip"/>TIP</h3><p>
776 To speed up program compilation, use
777 gcc compiler with Pentium
778 optimization. </p></div><p>
779 Note that this should not be inside a
780 <tt><para></tt> but between paragraphs.
781 </p></div><div class="sect3"><a name="figures"/><div class="titlepage"><div><h4 class="title"><a name="figures"/> Screenshots and other figures</h4></div></div><p>
782 To include screenshots and other figures, use the following
785 <pre class="programlisting">
787 <figure id="shot1">
788 <title>Screenshot</title>
790 <screeninfo>Screenshot of a program</screeninfo>
791 <graphic format="PNG" fileref="figures/example_screenshot" srccredit="ME">
796 replacing <tt>example_screenshot</tt> with the
797 actual file name (without extension). The result will look like this:
799 <div class="figure"><p><a name="shot1"/><b>Figure 1. Screenshot</b></p><div class="screenshot"><p><img src="figures/example_screenshot"/></p></div></div>
800 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2529626"/>NOTE</h3><p>
801 Notice in this example that the screenshot file name does
802 not include the file type extension -- to find out
803 why, please read <a href="#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a>.
804 </p></div></div><div class="sect3"><a name="listing"/><div class="titlepage"><div><h4 class="title"><a name="listing"/>Program listings and terminal session</h4></div></div><p>
805 To show a file fragment--for example, program
806 listing--use <tt><programlisting></tt> tag:
807 <pre class="programlisting">
809 <programlisting>
811 Name=Gnumeric spreadsheet
813 Icon=gnome-gnumeric.png
816 </programlisting>
819 <pre class="programlisting">
821 Name=Gnumeric spreadsheet
823 Icon=gnome-gnumeric.png
827 As a matter of fact, all examples in this document were
828 produced using <tt><programlisting></tt>.
830 To show a record of terminal session--i.e., sequence of
831 commands entered at the command line--use
832 <tt><screen></tt> tag:
833 <pre class="programlisting">
836 <prompt>bash$</prompt><userinput>make love</userinput>
837 make: *** No rule to make target `love'. Stop.
842 <tt>bash$</tt><b><tt>make love</tt></b>
843 make: *** No rule to make target `love'. Stop.
845 Note the use of tags <tt><prompt></tt> and
846 <tt><userinput></tt> for marking system prompt
847 and commands entered by user.
848 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2529790"/>NOTE</h3><p>
849 Note that both <tt><programlisting></tt>
850 and <tt><screen></tt> preserve linebreaks,
851 but interpret SGML tags (unlike LaTeX
852 verbatim environment). Take a look at
853 the source of this document to see how you can have SGML
854 tags literally shown but not interpreted,
856 </p></div><div class="sect3"><a name="lists"/><div class="titlepage"><div><h4 class="title"><a name="lists"/> Lists</h4></div></div><p>
857 The most common list types in DocBook are
858 <tt><itemizedlist></tt>,
859 <tt><orderedlist></tt>, and
860 <tt><variablelist></tt>.
861 </p><div class="variablelist"><dl><dt><a name="id2529876"/><span class="term"> <tt><itemizedlist></tt></span></dt><dd><p><a name="id2529888"/>
862 This is the simplest unnumbered list, parallel to
863 <tt><ul></tt> in HTML. Here is an example:
864 <pre class="programlisting">
869 <guilabel>Show backup files</guilabel> &mdash; This will
870 show any backup file that might be on your system.
875 <guilabel>Show hidden files</guilabel> &mdash; This will
876 show all "dot files" or files that begin with a dot. This
877 files typically include configuration files and directories.
882 <guilabel>Mix files and directories</guilabel> &mdash; This
883 option will display files and directories in the order you
885 always having directories shown above files.
888 </itemizedlist>
892 </p><div class="itemizedlist"><ul><li><p><a name="id2529912"/>
894 This will show any backup file that might be on
896 </p></li><li><p><a name="id2529958"/>
898 This will show all "dot files" or files that
899 begin with a dot. This files typically include
900 configuration files and directories.
901 </p></li><li><p><a name="id2529981"/>
902 Mix files and directories
903 -- This option will display files and
904 directories in the order you sort them instead
905 of always having directories shown above files.
906 </p></li></ul></div><p> Note the use of <tt>&mdash;</tt>
907 for long dash (see <a href="#specsymb" title=" Special symbols ">the section called “ Special symbols ”</a>). Also,
908 please note that the result looks much nicer because the
909 terms being explained (Show backup
910 files, etc.) are set in a different font. In
911 this case, it was achieved by using <a href="#gui" title="GUI elements"><tt><guilabel></tt></a>
912 tag. In other cases, use appropriate tags such as
913 <a href="#gui" title="GUI elements"><tt><guimenuitem></tt></a>,
914 <a href="#filenames" title="Filenames, commands, and other computer-related things"><tt><command></tt></a>,
917 <a href="#gui" title="GUI elements"><tt><emphasis></tt></a>.
918 </p></dd><dt><a name="id2530107"/><span class="term"> <tt><orderedlist></tt></span></dt><dd><p><a name="id2530119"/>
919 This list is completely analogous to
920 <tt><itemizedlist></tt> and has the same
921 syntax, but it produces numbered list. By default,
922 this list uses Arabic numerals for numbering entries;
923 you can override this using <tt>numeration</tt>,
924 for example <tt><orderedlist
925 numeration="lowerroman"></tt>. Possible values of
926 these attribute are <tt>arabic</tt>,
931 </p></dd><dt><a name="id2530183"/><span class="term"> <tt><variablelist></tt></span></dt><dd><p><a name="id2530195"/> This list is used when each entry is
932 rather long, so it should be formatted as a block of text
933 with some subtitle, like a small subsection. The
934 <tt><variablelist></tt> is more complicated
935 than itemizedlists, but for larger blocks of text, or when
936 you're explaining or defining something, it's best to use
937 them. Their greatest advantage is that it's easier for a
938 computer to search. The lines you are reading now were
939 produced by <tt><variablelist></tt>. The
940 source looked liked this:
941 <pre class="programlisting">
945 <term> <sgmltag>&lt;itemizedlist></sgmltag></term>
946 <listitem><para>
947 This is the simplest unnumbered list, parallel to
948 <sgmltag>&lt;ul></sgmltag> in HTML. Here is an example:...
949 </para></listitem>
950 </varlistentry>
952 <term> <sgmltag>&lt;orderedlist></sgmltag></term>
953 <listitem><para>
954 This list is completely analogous to
955 <sgmltag>&lt;itemizedlist></sgmltag>
956 </para></listitem>
957 </varlistentry>
959 <term> <sgmltag>&lt;variablelist></sgmltag></term>
960 <listitem><para>
961 This list is used when each entry is rather long,...
962 </para></listitem>
963 </varlistentry>
964 </variablelist>
967 </p></dd></dl></div><p>
968 Lists can be nested; in this case, the stylesheets
969 are smart enough to change the numeration (for
970 <tt><orderedlist></tt>) or marks of each entry
971 (in <tt><itemizedlist></tt>) for sub-lists
972 </p></div></div><div class="sect2"><a name="inline"/><div class="titlepage"><div><h3 class="title"><a name="inline"/>Inline Elements</h3></div></div><div class="sect3"><a name="gui"/><div class="titlepage"><div><h4 class="title"><a name="gui"/>GUI elements</h4></div></div><div class="itemizedlist"><ul><li><p><a name="id2530324"/>
973 <tt><guibutton></tt> -- used for
974 buttons, including checkbuttons and radio buttons
975 </p></li><li><p><a name="id2530343"/>
976 <tt><guimenu></tt>,
977 <tt><guisubmenu></tt> --used for
978 top-level menus and submenus
979 respectively, for example <tt>
980 <guisubmenu>Utilities</guisubmenu> submenu of the
981 <guimenu>Main Menu</guimenu></tt>
982 </p></li><li><p><a name="id2530378"/>
983 <tt><guimenuitem></tt>--an entry in a
985 </p></li><li><p><a name="id2530395"/>
986 <tt><guiicon></tt>--an icon
987 </p></li><li><p><a name="id2530412"/>
988 <tt><guilabel></tt>--for items which have
989 labels, like tabs, or bounding boxes.
990 </p></li><li><p><a name="id2530429"/>
991 <tt><interface></tt>-- for most everything
992 else... a window, a dialog box, the Panel, etc.
993 </p></li></ul></div><p>
994 If you need to refer to a sequence of menu choices, such as
995 Main Menu->Utilities->GNOME
997 there is a special construction for this, too:
998 <pre class="programlisting">
1001 <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
1002 <guimenuitem>GNOME terminal</guimenuitem> </menuchoice>
1004 </p></div><div class="sect3"><a name="links"/><div class="titlepage"><div><h4 class="title"><a name="links"/>Links and references</h4></div></div><p>
1005 To refer to another place in the same document, you can use
1006 tags <tt><xref></tt> and
1007 <tt><link></tt>. The first of them
1008 automatically inserts the full name of the element you refer
1009 to (section, figure, etc.), while the second just creates a
1010 link (in HTML output). Here is an example:
1011 <pre class="programlisting">
1012 An example of a <link linkend="extip">tip</link> was given in
1013 <xref linkend="notes" />.
1015 which produces: An example of a <a href="#extip">tip</a> was given in <a href="#notes" title="Notes, Warnings, And Tips">the section called “Notes, Warnings, And Tips”</a>.
1017 Here <tt>notes</tt> and <tt>extip</tt>
1018 are the id attributes of <a href="#notes" title="Notes, Warnings, And Tips">the section called “Notes, Warnings, And Tips”</a> and of the
1019 example of a tip in it.
1020 </p><p> To produce a link to an external source, such as a
1021 Web page or a local file, use <tt><ulink></tt>
1023 <pre class="programlisting">
1024 To find more about GNOME, please visit <ulink type="http"
1025 url="http://www.gnome.org">GNOME Web page</ulink>
1027 which produces: To find more about GNOME, please visit
1028 <a href="http://www.gnome.org" target="_top">The GNOME Web
1029 Site</a> You can use any of the standard URL types, such
1030 as <tt>http, ftp, file, telnet, mailto</tt> (in
1031 most cases, however, use of <tt>mailto</tt> is
1032 unnecessary--see discussion of
1033 <tt><email></tt> tag).
1034 </p></div><div class="sect3"><a name="filenames"/><div class="titlepage"><div><h4 class="title"><a name="filenames"/>Filenames, commands, and other
1035 computer-related things</h4></div></div><p>
1036 Here are some tags used to describe operating system-related
1038 </p><div class="itemizedlist"><ul><li><p><a name="id2530717"/> <tt><filename></tt> -- used
1040 e.g.<tt><filename></tt>
1042 <tt></filename></tt>
1043 produces: <tt>foo.sgml</tt>.
1044 </p></li><li><p><a name="id2530757"/> <tt><filename
1045 class="directory"></tt> -- used for
1046 directories, e.g.<tt><filename
1047 class="directory"></tt>/usr/bin
1048 <tt></filename></tt>
1049 produces: <tt>/usr/bin</tt>.
1050 </p></li><li><p><a name="id2530804"/>
1051 <tt><application></tt> -- used for
1053 e.g. <tt><application></tt>Gnumeric
1054 <tt></application></tt> produces:
1056 </p></li><li><p><a name="id2530845"/>
1057 <tt><envar></tt> -- used for
1058 environment variables, e.g.
1059 <tt><envar></tt>PATH<tt></envar></tt>.
1060 </p></li><li><p><a name="id2530876"/>
1061 <tt><command></tt> -- used for
1062 commands entered on command line, e.g.
1063 <tt><command></tt>make install
1064 <tt></command></tt> produces:
1065 <b>make install</b>.
1066 </p></li><li><p><a name="id2530916"/>
1067 <tt><replaceable></tt> -- used for
1068 replaceable text, e.g.
1069 <tt><command></tt>db2html<tt><replaceable></tt>
1071 <tt></replaceable></tt><tt></command></tt>
1072 produces: <b>db2html
1073 <i><tt>foo.sgml</tt></i></b>.
1074 </p></li></ul></div></div><div class="sect3"><a name="keys"/><div class="titlepage"><div><h4 class="title"><a name="keys"/>Keyboard input</h4></div></div><p> To mark up text input by the user, use
1075 <tt><userinput></tt>.
1076 </p><p> To mark keystrokes such as shortcuts and other
1077 commands, use <tt><keycap></tt>.
1078 This is used for marking up what is printed on the top
1079 of the physical key on the keyboard. There are a couple of
1080 other tags for keys, too: <tt><keysym></tt>
1081 and <tt><keycode></tt>. However you are
1082 unlikely to need these for most documentation. For reference,
1083 <tt><keysym></tt> is for the “symbolic
1084 name” of a key. <tt><keycode></tt> is
1085 for the “scan code” of a key. These are not
1086 terms commonly required in GNOME documentation,
1087 although <tt><keysym></tt> is useful for marking
1090 To mark up a combination of keystrokes, use the
1091 <tt><keycombo></tt> wrapper:
1092 <pre class="programlisting">
1095 <keycap>Ctrl</keycap>
1096 <keycap>Alt</keycap>
1097 <keycap>F1</keycap>
1101 Finally, if you want to show a shortcut for some menu
1102 command, here are the appropriate tags (rather long):
1103 <pre class="programlisting">
1107 <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
1109 <guimenuitem> Quit</guimenuitem>
1112 which produces simply
1113 Quit (<b>Ctrl-q</b>)
1114 </p></div><div class="sect3"><a name="email"/><div class="titlepage"><div><h4 class="title"><a name="email"/>E-mail addresses</h4></div></div><p> To mark up e-mail
1115 address, use <tt><email></tt>:
1116 <pre class="programlisting">
1117 The easiest way to get in touch with me is by e-mail
1118 (<email>me@mydomain.com</email>)
1120 which produces: The easiest way to get in touch with me is
1121 by e-mail (<tt><<a href="mailto:me@mydomain.com">me@mydomain.com</a>></tt>) Note that
1122 <tt><email></tt> automatically produces a link
1124 </p></div><div class="sect3"><a name="specsymb"/><div class="titlepage"><div><h4 class="title"><a name="specsymb"/> Special symbols </h4></div></div><p>
1125 DocBook also provides special means for entering
1126 typographic symbols which can not be entered directly
1127 form the keyboard (such as copyright sign). This is done using
1128 <i>entities</i>, which is SGML analogue of
1129 macros, or commands, of LaTeX. They generally have the form
1130 <tt>&entityname;</tt>. Note that the semicolon
1133 here is partial list of most commonly used enitites:
1134 </p><div class="itemizedlist"><ul><li><p><a name="id2531260"/>
1135 <tt>&amp;</tt> -- ampersend (&)
1136 </p></li><li><p><a name="id2531274"/>
1137 <tt>&lt;</tt> -- left angle bracket (<)
1138 </p></li><li><p><a name="id2531287"/>
1139 <tt>&copy;</tt> -- copyright sign (©)
1140 </p></li><li><p><a name="id2531348"/>
1141 <tt>&mdash;</tt> -- long dash (--)
1142 </p></li><li><p><a name="id2531314"/>
1143 <tt>&hellip;</tt> -- ellipsis (...)
1144 </p></li></ul></div><p>
1145 Note that the actual look of the resulting symbols depends
1146 on the fonts used by your browser; for example, it might
1147 happen that long dash (<tt>&mdash;</tt>) looks
1148 exactly like the usual dash (-). However, in the PostScript
1149 (and thus, in print) the output will look markedly better if
1150 you use appropriate tags.
1151 </p></div></div></div><div class="sect1"><a name="conventions"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="conventions"/>GDP Documentation Conventions </h2></div></div><div class="sect2"><a name="conventionsalldocs"/><div class="titlepage"><div><h3 class="title"><a name="conventionsalldocs"/>Conventions for All GDP Documentation</h3></div></div><div class="sect3"><a name="xmlcomp"/><div class="titlepage"><div><h4 class="title"><a name="xmlcomp"/> XML compatibility </h4></div></div><p>
1152 All GNOME documentation should conform to XML syntax
1153 requirements, which are stricter than SGML ones -- see
1154 <a href="#xml" title="XML and SGML">the section called “XML and SGML”</a> for more informaion.
1155 </p></div><div class="sect3"><a name="authorsnames"/><div class="titlepage"><div><h4 class="title"><a name="authorsnames"/> Authors' names</h4></div></div><p>
1156 All GNOME documentation should contain the names of both the
1157 application authors and documentation authors, as well as a
1158 link to the application web page (if it exists) and
1159 information for bug submission -- see templates for an
1161 </p></div></div><div class="sect2"><a name="conventionsappdocs"/><div class="titlepage"><div><h3 class="title"><a name="conventionsappdocs"/>Conventions for Application Documentation</h3></div></div><div class="sect3"><a name="applicationversionid"/><div class="titlepage"><div><h4 class="title"><a name="applicationversionid"/>Application Version Identification</h4></div></div><p>
1162 Application documentation should identify the version of the
1163 application for which the documentation is written:
1164 <pre class="programlisting">
1166 <sect1 id="intro">
1167 <title>Introduction</title>
1169 blah-blah-blah This document describes version 1.0.53 of gfoo.
1173 </p></div><div class="sect3"><a name="license"/><div class="titlepage"><div><h4 class="title"><a name="license"/> Copyright information </h4></div></div><p> Application
1174 documentation should contain a copyright notice, stating the
1175 licensing terms. It is suggested that you use the GNU Free
1176 Documentation License. You could also use some other license
1177 allowing free redistribution, such as GPL or Open Content
1178 license. If documentation uses some trademarks (such as UNIX,
1179 Linux, Windows, etc.), proper legal junk should also be
1180 included (see templates).
1181 </p></div><div class="sect3"><a name="license2"/><div class="titlepage"><div><h4 class="title"><a name="license2"/>Software license</h4></div></div><p>
1182 All GNOME applications must contain information about the
1183 license (for software, not for documentation), either in the
1184 "About" box or in the manual.
1185 </p></div><div class="sect3"><a name="bugtraq"/><div class="titlepage"><div><h4 class="title"><a name="bugtraq"/> Bug reporting</h4></div></div><p>
1186 Application documentation should give an address for
1187 reporting bugs and for submitting comments about the
1188 documentaion (see templates for an example).
1189 </p></div></div></div><div class="sect1"><a name="writingapplicationmanuals"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="writingapplicationmanuals"/>Writing Application and Applet Manuals</h2></div></div><p>
1190 Every GNOME application or applet should have a manual specific
1191 to that particular application. This manual should be a complete
1192 and authoritative guide. The manual should describe what the
1193 program does and how to use it. Manuals will typically describe
1194 each window or panel presented to the user using screenshots (in
1195 PNG format only) when appropriate. They should also describe
1196 each feature and preference option available.
1197 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2531646"/>Documentation Availability</h3><p>
1198 Applications and applets should not rely on documentation
1199 which is only available on the internet. All manuals and
1200 other documentation should be packaged with the application or
1201 applet and be made available to the user through the standard
1202 GNOME help system methods described below.
1203 </p></div><p> Application manuals should be based on the template in
1204 <a href="#template1" title="Template 1: Application Manual">the section called “Template 1: Application Manual”</a>. Applet manuals should be based on
1205 the templates in <a href="#template2-1x" title="Template 2: Applet Manual For GNOME 1.x">the section called “Template 2: Applet Manual For GNOME 1.x”</a> for GNOME
1206 versions 1.x and the templates in <a href="#template2-2x" title="Template 2: Applet Manual For GNOME 2.x">the section called “Template 2: Applet Manual For GNOME 2.x”</a>
1207 for GNOME versions 2.x.
1208 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2531713"/>Manuals For Large Applications</h3><p>
1209 Manuals for very large applications, such as GNOME Workshop
1210 components should be a <tt><book></tt> (and thus
1211 use <tt><chapter></tt> for each primary section)
1212 , instead of <tt><article></tt> which most
1213 applications use(with each primary section being a
1214 <tt><sect1></tt>).
1215 </p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2531756"/>Applet Manuals in GNOME 2.0</h3><p>
1216 Note that applet manuals in GNOME 2.0 are treated in a special
1217 way. The manuals for all applets are merged into a single
1218 virtual document by Nautilus. For this reason, the header
1219 information for applet manuals is omitted and the first
1220 section of each applet is
1221 <tt><sect1></tt>. Applet manuals will typically
1222 have several sections, each of which is
1223 <tt><sect2></tt>.
1225 Application manuals should be made available by having a
1226 "Manual" entry in the Help pull-down menu
1228 application, as described in <a href="#listingdocsinhelpmenu" title="Listing Documents in the Help Menu">the section called “Listing Documents in the Help Menu”</a>.
1229 Applets should make their manuals available by
1230 right-clicking on the applet.
1231 </p></div><div class="sect1"><a name="listingdocsinhelpmenu"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="listingdocsinhelpmenu"/>Listing Documents in the Help Menu</h2></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2531851"/>Developer Information</h3><p>
1232 This section is for developers. Documentation authors
1233 generally do not need to know this material.
1235 Typically the application manual and possibly additional help
1236 documents will be made available to the user under the
1237 Help menu at the top right of the
1238 application. To do this, you must first write a
1239 <tt>topic.dat</tt> file. The format for this file is:
1240 <pre class="programlisting">
1241 One line for each 'topic'.
1243 Two columns, as defined by perl -e 'split(/\s+/,$aline,2)'
1245 First column is the HTML file (and optional section) for the topic,
1246 relative to the app's help file dir.
1248 Second column is the user-visible topic name.
1250 For example, Gnumeric's
1251 <tt>topic.dat</tt> file is:
1252 <pre class="programlisting">
1253 gnumeric.html Gnumeric manual
1254 function-reference.html Gnumeric function reference
1256 When the application is installed, the
1257 <tt>topic.dat</tt> file should be placed in the
1258 <tt>$prefix/share/gnome/help/<i><tt>appname</tt></i>/C/</tt> directory
1259 where <i><tt>appname</tt></i> is replaced by the
1260 application's name. The application documentation (converted
1261 from SGML into HTML with <b>db2html</b>) should be
1262 placed in this directory too.
1263 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2531991"/>Note</h3><p>
1264 If the help files are not present in the correct directory, the
1265 menu items will NOT appear when the program is run.
1267 The <tt>topic.dat</tt> file is used by the GNOME
1268 menu building code to generate the Help
1269 menu. When you define your menu:
1270 <pre class="programlisting">
1271 GnomeUIInfo helpmenu[] = {
1273 N_("About"), N_("Info about this program"),
1274 about_cb, NULL, NULL,
1275 GNOME_APP_PIXMAP_STOCK, GNOME_STOCK_MENU_ABOUT,
1277 GNOMEUIINFO_SEPARATOR,
1278 GNOMEUIINFO_HELP("<i>appname</i>"),
1282 the line specifying <tt>GNOMEUIINFO_HELP</tt> causes
1283 GNOME to create a menu entry which is tied to the documentation
1284 in the directory mentioned above. Also, all the topics in the
1285 <tt>topic.dat</tt> file will get menu entries in the
1286 Help menu. When the user selects any of these
1287 topics from the Help menu, a help browser
1288 will be started with the associated HTML documentation.
1289 </p></div><div class="sect1"><a name="applicationhelpbuttons"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="applicationhelpbuttons"/>Application Help Buttons</h2></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2532116"/>Developer Information</h3><p>
1290 This section is for developers. Documentation authors
1291 generally do not need to know this material.
1293 Most GNOME applications will have Help
1294 buttons. These are most often seen in Preference windows. (All
1295 Preference windows should have Help
1296 buttons.) Most Help buttons will connect
1297 to the application manual, although some may connect to special
1298 documents. Because the Help buttons do
1299 not generally have their own special documentation, the
1300 documentation author(s) do not need to do very much. However,
1301 the application author must be careful to guarantee that the
1302 application correctly opens the help documentation when the
1303 Help buttons are pressed.
1305 To make the Help buttons call the correct document in the GNOME Help
1306 Browser the developer should add code based on the following example:
1307 </p><pre class="programlisting">
1309 tmp = gnome_help_file_find_file ("module", "page.html");
1311 gnome_help_goto(0, tmp);
1314 </pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2532218"/>NOTE</h3><p>
1315 The example above is in the C language, please refer to other
1316 documentation or forums for other GNOME language bindings.
1317 </p></div></div><div class="sect1"><a name="packagingappletdocs"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="packagingappletdocs"/>Packaging Applet Documentation</h2></div></div><div class="sect2"><a name="appletfiles"/><div class="titlepage"><div><h3 class="title"><a name="appletfiles"/>Applet Documentation Files</h3></div></div><p>
1318 In GNOME 2.0 each applet will have its own documentation
1319 installed separately, and the GNOME 2.0 help
1320 browser (Nautilus) will dynamically
1321 merge the applet documents into a single virtual book
1322 called <i>GNOME Applets</i>. During the
1323 transitionary stage between GNOME 1.0 and GNOME 2.0, each
1324 applet in the gnome-applets package has its own manual(stored
1325 with the applet in CVS), but they are merged together manually
1326 to create the <i>GNOME Applets</i> book before
1328 <tt><<a href="mailto:hobbit@aloss.ukuu.org.uk">hobbit@aloss.ukuu.org.uk</a>></tt> is the maintainer of
1329 this document. Applet documentation should be sent to Telsa
1330 (or placed in CVS) who will make sure they are correctly
1331 packaged with the applets. The applet author should be
1332 contacted to modify the menu items and help buttons to bind to
1333 the applet documentation if necessary.
1335 Images which are part of the applet documentation should be in
1336 PNG format and should reside in the same directory as the SGML
1337 document file in CVS(gnome-applets/APPLETNAME/help/C).
1339 Applets which are not part of the gnome-applets package must
1340 package their documentation with the particular applet
1341 package. They should use the same applet template as other
1342 applets. However, the <tt><xref></tt> links to
1343 the introductory chapter of the <i>GNOME
1344 Applets</i> book must be removed (as the 1.x
1345 GNOME Help Browser does not allow
1346 you to create links between separate documents) and replaced
1347 with suitable text. Note that since this document is not part
1348 of the <i>GNOME Applets</i> book, you must
1349 remember to add <tt><legalnotice></tt> and
1350 <tt><copyright></tt> sections.
1351 </p></div><div class="sect2"><a name="appletmenu"/><div class="titlepage"><div><h3 class="title"><a name="appletmenu"/>Adding Documentation to an Applet Menu</h3></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2532404"/>Developer Information</h3><p>
1352 This section is for developers. Documentation authors
1353 generally do not need to know this material.
1355 Applets should have About and
1356 Manual menu items, typically as the first
1357 and second top-most items in the menu respectively. This
1358 section describes how the developer creates these menu items
1359 and links them to the documentation.
1361 To add an applet's manual to its applet menu, use:
1362 <pre class="programlisting">
1363 /* add an item to the applet menu */
1364 applet_widget_register_callback(APPLET_WIDGET(applet), "manual",
1365 _("Manual"), &open_manual, NULL);
1367 Here the second argument is an arbitrary name for the
1368 callback, the third argument is the label which will appear
1369 when the user right clicks on the applet, and the fourth
1370 argument is the callback function.
1372 You will need to write a simple callback function to open the
1373 help browser to the appropriate document. This is done using
1374 the <tt>gnome_help_file_find_file</tt> function,
1375 as described in <a href="#applicationhelpbuttons" title="Application Help Buttons">the section called “Application Help Buttons”</a>.
1377 You will also want to add an About menu
1378 item to the applet's menu. This is a
1379 stock menu item and is done:
1380 <pre class="programlisting">
1381 applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about",
1382 GNOME_STOCK_MENU_ABOUT, _("About"), &my_applet_cb_about,
1386 More information can be found at <a href="http://developer.gnome.org/doc/tutorials/applet/index.html" target="_top">Writing
1387 GNOME panel applets using the GTK+/GTK-- widget set</a>.
1388 </p></div></div><div class="sect1"><a name="writingcontextsensitivehelp"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="writingcontextsensitivehelp"/>Writing Context Sensitive Help (coming in GNOME-2.0)</h2></div></div><p>
1389 Context sensitive help, also known as "pop-up" help, will allow
1390 a user to obtain help information about specific buttons or
1391 parts of an application.
1393 Context sensitive help is still under development and not all
1394 the details are available at this time. However, the basics can
1395 be shown here so that you can understand how the system will
1398 The Context Sensitive Help system is designed to allow the
1399 developer to give an id to a particular portion of the User
1400 Interface, for example, a button. Once the interface is complete
1401 a Perl script can then be run against the interface code to
1402 create a "map" file. This map file allows the developer or
1403 writer to associate particular paragraph sections from an XML
1404 document to the interface items.
1406 The XML used for the document is a small XML DTD that is being
1407 developed to use the same tags (albeit, much fewer) as DocBook
1408 so that writers do not have to re-learn a new DTD.
1410 Once the document is written and map file is complete, when the
1411 user launches context sensitive help on the interface (either by
1412 pressing a button and then clicking on the interface item they
1413 want information on, or by right mouse clicking on the interface
1414 item and selecting a pop-up menu item like "What's This") a
1415 small transient window will appear with brief but detailed
1416 information on the interface item.
1417 </p></div><div class="sect1"><a name="referring"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="referring"/>Referring to Other GNOME Documentation (coming in
1418 GNOME-2.0)</h2></div></div><p>
1419 In the GNOME 2.0 Help System, you will be able to create links
1420 from one document to another. The exact mechanism for doing
1421 this is in development.
1422 </p></div><div class="sect1"><a name="basics"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="basics"/>Basics of Documentation Style</h2></div></div><p>
1423 Most people have never enjoyed reading a software manual, and
1424 they probably never will. Many times, they'll read the
1425 documentation only when they run into problems, and they'll be
1426 frustrated and upset before they even read a word. On the
1427 other hand, some readers will read the manual all the way
1428 through, or at least look at the introduction before they
1429 start. Your document might serve as a reference for an expert
1430 or a guide to a beginner, and it must have enough depth to
1431 satisfy the first without overwhelming the second. Ideally, it
1432 will serve beginners as they <i>become</i>
1433 experts. Remember, your goal is to produce <i>complete,
1434 intuitive and clear</i> documentation.
1436 In order to write useful documentation, you'll have to know who
1437 your audience is likely to be. Then, you can look for the
1438 problems they're likely to run into, and solve them. It will
1439 also help if you focus on the tasks users will perform, and
1440 group features accordingly, rather than simply describing
1442 </p><div class="sect2"><a name="styleplanning"/><div class="titlepage"><div><h3 class="title"><a name="styleplanning"/>Planning</h3></div></div><p>
1443 Begin documenting by learning how to use the application and
1444 reading over any existing documentation. Pay attention to
1445 places where your document will differ from the template. It
1446 may help to develop a document skeleton: a valid XML or SGML
1447 document that has little or no content. For very large
1448 applications, you will need to make significant departures
1449 from the templates, since you'll be using the
1450 <tt><book></tt> tag instead of
1451 <tt><chapter></tt> or
1452 <tt><article></tt>.
1453 </p></div><div class="sect2"><a name="balance"/><div class="titlepage"><div><h3 class="title"><a name="balance"/>Achieving a Balanced Style</h3></div></div><p>
1454 Just as you need to juggle expert and novice readers,
1455 you'll have to juggle a number of other extremes as you write:
1456 <div class="itemizedlist"><ul><li><p><a name="id2532825"/>
1457 Documents should be complete, yet concise. You should
1458 describe every feature, but you'll have decide how much
1459 detail is really necessary. It's not, for example,
1460 necessary to describe every button and form field in a
1461 dialog box, but you should make sure that your readers
1462 know how to bring up the dialog and what it does. If
1463 you spend fewer words on the obvious, you can spend more
1464 time clarifying the ambiguous labels and explaining
1465 items that are more complex.
1466 </p></li><li><p><a name="id2532845"/>
1467 Be engaging and friendly, yet professional. Games
1468 documents may be less formal than productivity
1469 application documents (people don't
1470 <i>use</i> games, they
1471 <i>play</i> them), but all of them should
1472 maintain a standard of style which holds the reader's
1473 interest without resorting to jokes and untranslatable
1475 </p></li><li><p><a name="id2532874"/>
1476 Examples, tips, notes, and screenshots are useful to
1477 break up long stretches of text, but too many can get in
1478 the way, and make your documents too choppy to read.
1479 It's good to provide a screenshot of any dialog windows
1480 a user might run into, but if a dialog box has several
1481 tabs, it's not usually necessary to have one for each.
1482 </p></li><li><p><a name="id2532892"/>
1483 The GDP strives to have all of its documentation conform
1484 to certain standards of style and content, but every
1485 document (and every writer) is different. You will need
1486 to use your judgement, and write documents to fit with
1487 the rest of the project, without compromising the
1488 individual needs of your subject, or your own
1489 individuality as a writer.
1490 </p></li></ul></div>
1491 </p></div><div class="sect2"><a name="stylestructure"/><div class="titlepage"><div><h3 class="title"><a name="stylestructure"/>Structure</h3></div></div><p>
1492 In general, you won't have to worry too much about structure,
1493 because the templates provide you with an excellent example.
1494 As a general rule, try to follow that structural example.
1495 That means using links, hierarchical nesting, and, if
1496 necessary, a glossary or index. You probably won't need to
1497 use every available structural tag, but take advantage of
1498 what DocBook provides you.
1500 As to linking, there's some disagreement about whether to use
1501 <tt><xref></tt> <tt><link></tt>
1502 when you make links within your documents. You'll have to
1503 decide, based on the different ways that they are presented
1504 in output, which is more appropriate given the context.
1505 Regardless of which you use, you should not forget to use
1506 them. Help your readers find information that relevant to
1509 The table of contents will be generated automatically, but
1510 you will probably have to develop your own index if you wish
1511 to have one. The Nautilus Help Browser will have new, and
1512 currently unknown, indexing capabilities, so index style and
1513 structure are still under discussion. The GNOME User's Guide
1514 will contain a glossary in its next versions; unless you're
1515 writing a<tt><book></tt>, it will probably be best to
1516 contribute to that rather than developing your own.
1517 </p></div><div class="sect2"><a name="stylegrammar"/><div class="titlepage"><div><h3 class="title"><a name="stylegrammar"/>Grammar and Spelling</h3></div></div><p>
1518 Nobody expects you to be perfect; they just expect the
1519 documentation for their software to be error-free. That means
1520 that, in the same way that developers look for bugs and accept
1521 bug reports, writers must check for errors in their documents.
1522 Poor grammar, bad spelling, and gross technical errors in
1523 draft documents are fine. However, if those problems show up
1524 in a "real" release, they can count against the credibility of
1525 GNOME and Linux. They'll also make you look bad.
1527 There is no substitute for a human proofreader; use a
1528 spell-check program, then read it over yourself, and then find
1529 someone else to help you. Other GDP members are, of course,
1530 willing and able to help you, but non-writers are often at
1533 Proofreading documents is both a also a good way to
1534 familiarize yourself with documentation, and it certainly
1535 makes you valuable to the GDP. Help other writers proof their
1536 documents, and they will help you with yours.
1537 </p></div></div><div class="sect1"><a name="teamwork"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="teamwork"/>Teamwork</h2></div></div><div class="sect2"><a name="teamworkgdp"/><div class="titlepage"><div><h3 class="title"><a name="teamworkgdp"/>Working With The GDP Team</h3></div></div><p>
1538 The GDP team is a valuable resource for any documentation
1539 author. GDP members can answer most questions documentation
1540 authors have during the course of their work. It is also
1541 important to make sure you are not duplicating work of other
1542 GDP members by visiting the <i>GDP Documentation
1543 Status Table</i> (<a href="http://www.gnome.org/gdp/doctable/" target="_top">http://www.gnome.org/gdp/doctable/</a>) and
1544 assigning a documentation item to yourself. This table also
1545 provides a forum for making suggestions and announcements for
1546 each documentation item. The best way to get in touch with
1547 GDP members is on the #docs IRC channel at irc.gnome.org or
1548 else by emailing the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
1549 <i>gnome-doc-list mailing list</i></a>.
1551 After an author has finished a document (or even a draft
1552 version of the document), it is a good idea to ask a member of
1553 the GDP team to read the document, checking it for grammar,
1554 proper DocBook markup, and clarity. One may typically find
1555 another author to do this by either asking on the #docs IRC
1556 channel at irc.gnome.org or by emailing the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
1557 <i>gnome-doc-list mailing list</i></a>.
1558 </p></div><div class="sect2"><a name="teamworkdevelopers"/><div class="titlepage"><div><h3 class="title"><a name="teamworkdevelopers"/>Working With Developers</h3></div></div><p>
1559 Writing documentation typically involves a certain amount of
1560 interaction with the developers of GNOME or the application
1561 which is being documented. Often a document author will need
1562 to ask the developer technical questions during the course of
1563 writing a document. After the document is finished, it is good
1564 idea to ask the developer to read the document to make sure it
1565 is technically correct. The documentation author should also
1566 make sure that the application author correctly binds and
1567 packages the documentation with the application.
1568 </p></div></div><div class="sect1"><a name="finishing"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="finishing"/>Finishing A Document</h2></div></div><div class="sect2"><a name="editting"/><div class="titlepage"><div><h3 class="title"><a name="editting"/>Editing The Document</h3></div></div><p>
1569 When the document is finished, the document should be edited
1570 by another member of the GDP for spelling, clarity, and
1571 DocBook markup. It should also be read by an application
1572 author to make sure the document is technically accurate.
1573 </p></div><div class="sect2"><a name="submitting"/><div class="titlepage"><div><h3 class="title"><a name="submitting"/>Submitting The Document</h3></div></div><p>
1574 After the document has been edited and checked for technical
1575 accuracy, it is ready to be combined with the application or
1576 documentation package. This is typically done by passing the
1577 document to the application or package developer. In some
1578 cases, the documents can be committed directly into CVS,
1579 however this should only be done after obtaining permission to
1580 make CVS commits from the developer. Note that in many cases,
1581 the application may need to be modified to correctly link to
1582 the documentation. The packaging system (tarballs and binary
1583 packages) may also need to be modified to include the
1584 documentation in the package. Generally, this should be done
1587 The final step is to email the GNOME Translation Team at
1588 <tt><<a href="mailto:gnome-i18n@nuclecu.unam.mx">gnome-i18n@nuclecu.unam.mx</a>></tt> to notify them that
1589 there is a new document for them to translate.
1590 </p></div></div><div class="sect1"><a name="resources"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="resources"/>Resources</h2></div></div><div class="sect2"><a name="resourcesweb"/><div class="titlepage"><div><h3 class="title"><a name="resourcesweb"/>Resources On The Web</h3></div></div><p> The <a href="http://developer.gnome.org/projects/gdp/" target="_top">GNOME
1591 Documentation Project Web page</a> lists current GDP
1592 projects and members.
1594 The <a href="http://www.gnome.org/gdp/doctable/" target="_top">GDP Documentation Status Table</a> tracks the
1595 status of all the various documentation components of GNOME.
1597 Norman Walsh's <a href="http://www.docbook.org" target="_top"> <i>DocBook: The Definitive
1598 Guide</i></a> in an excellent book on DocBook,
1599 available both online and in print.
1600 </p></div><div class="sect2"><a name="resourcesbooks"/><div class="titlepage"><div><h3 class="title"><a name="resourcesbooks"/>Books</h3></div></div><p>
1601 Docbook: The Definitive Guide is available in both printed
1602 form and on the web at:
1603 <a href="http://www.docbook.org/tdg/index.html" target="_top">
1604 <i>Docbook: The Definitive Guide</i>
1606 </p></div><div class="sect2"><a name="mailinglists"/><div class="titlepage"><div><h3 class="title"><a name="mailinglists"/>Mailing Lists</h3></div></div><p>
1607 The <i>gnome-docs-list</i> mailing list is the
1608 main discussion area for all contributors to the GNOME
1609 Documentation Project. You can find out how to subscribe to
1610 this list on <a href="http://www.gnome.org/resources/mailing-lists.html" target="_top">GNOME Mailing Lists</a>. This is a rather
1611 low-volume list, so you will not be flooded with messages.
1612 </p></div><div class="sect2"><a name="irc"/><div class="titlepage"><div><h3 class="title"><a name="irc"/>IRC</h3></div></div><p>
1613 Internet Relay Chat (IRC) is a fast and easy way to get in
1614 touch with other GDP members. There are generally at least a
1615 few members here who can answer questions or discuss
1616 documentation issues. The IRC channel is #docs at
1618 </p></div></div><div class="appendix"><h2 class="title" style="clear: both"><a name="templates"/>A. Document Templates</h2><div class="sect1"><a name="template1"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="template1"/>Template 1: Application Manual</h2></div></div><p>
1619 The following template should be used for all application
1620 manuals. You can always get the latest copy of this
1621 template from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
1622 Documentation Templates</a>.
1623 <pre class="programlisting">
1626 <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
1627 <!-- if not using PNG graphic, replace reference above with
1628 .....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
1630 <!ENTITY version "1.0.53">
1631 <!-- replace version above with actual application version number-->
1632 <!-- Template Version: 1.0.1 (do not remove this line) -->
1636 <!-- This is a GNOME documentation template, designed by the GNOME
1637 Documentation Project Team. Please use it for writing GNOME
1638 documentation, making obvious changes. In particular, all the words
1639 written in UPPERCASE (with the exception of GNOME) should be
1640 replaced. As for "legalnotice", please leave the reference
1643 Remember that this is a guide, rather than a perfect model to follow
1644 slavishly. Make your manual logical and readable. And don't forget
1645 to remove these comments in your final documentation! ;-)
1648 <!-- =============Document Header ============================= -->
1650 <article id="index"> <!-- please do not change the id -->
1653 <title>MY-GNOME-APP</title>
1655 <year>2000</year>
1656 <holder>ME-THE-AUTHOR</holder>
1659 <!-- translators: uncomment this:
1662 <year>2000</year>
1663 <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
1668 <!-- do not put authorname in the header except in copyright - use
1669 section "authors" below -->
1673 Permission is granted to copy, distribute and/or modify this
1674 document under the terms of the <citetitle>GNU Free
1675 Documentation License</citetitle>, Version 1.1 or any later
1676 version published by the Free Software Foundation with no
1677 Invariant Sections, no Front-Cover Texts, and no Back-Cover
1678 Texts. You may obtain a copy of the <citetitle>GNU Free
1679 Documentation License</citetitle> from the Free Software
1680 Foundation by visiting <ulink type="http"
1681 url="http://www.fsf.org">their Web site</ulink> or by writing
1682 to: Free Software Foundation, Inc., 59 Temple Place - Suite
1683 330, Boston, MA 02111-1307, USA.
1686 Many of the names used by companies to distinguish their
1687 products and services are claimed as trademarks. Where those
1688 names appear in any GNOME documentation, and those trademarks
1689 are made aware to the members of the GNOME Documentation
1690 Project, the names have been printed in caps or initial caps.
1692 </legalnotice>
1694 <!-- this is the version of manual, not application -->
1696 This is version 1.0 of MY-GNOME-APP manual.
1697 </releaseinfo>
1701 <!-- ============= Document Body ============================= -->
1703 <!-- ============= Introduction ============================== -->
1704 <sect1 id="intro">
1705 <title>Introduction</title>
1708 <application>MY-GNOME-APP</application> is an application which
1709 proves mathematical theorems. It has all the basic features
1710 expected from a mathematical theorem prover, as well as a number
1711 of advanced ones, such as proof by confusion. In fact, many of
1712 the proofs produced by <application>MY-GNOME-APP</application>
1713 are so complex that they are capable of proving almost anything
1714 with a virtually null likelihood of being disproven. It also has
1715 the very popular predecessor of proof by confusion, proof by
1716 dialog, first implemented by Plato.
1719 It also allows you to save and print theorem proofs and to add
1720 comments to the proofs it produces.
1724 To run <application>MY-GNOME-APP</application>, select
1726 <guisubmenu>SUBMENU</guisubmenu>
1727 <guimenuitem>MY-GNOME-APP</guimenuitem>
1729 from the <guimenu>Main Menu</guimenu>, or type
1730 <command>MYGNOMEAPP</command> on the command line.
1734 <application>MY-GNOME-APP</application> is included in the
1735 <filename>GNOME-PACKAGE</filename> package, which is part of the
1736 GNOME desktop environment. This document describes version
1737 &version; of <application>MY-GNOME-APP</application>.
1742 <!-- ================ Usage ================================ -->
1743 <!-- This section should describe basic usage of the application. -->
1745 <sect1 id="usage">
1746 <title>Using MY-GNOME-APP</title>
1748 <application>MY-GNOME-APP</application> can be used to produce a
1749 perfect proof of <emphasis>any</emphasis> mathematical theorem
1750 (provided, of course, that this theorem is correct), thus
1751 providing for new users an easy-to-use graphical interface to
1752 modern mathematics. This section describes basic usage of
1753 <application>MY-GNOME-APP</application>.
1756 <!-- ========= Basic Usage =========================== -->
1757 <sect2 id="mainwin">
1758 <title>Basic usage</title>
1760 Starting <application>MY-GNOME-APP</application> opens the
1761 <interface>Main window</interface>, shown in <xref
1762 linkend="mainwindow-fig">. The window is at first empty.
1764 <!-- ==== Figure ==== -->
1765 <figure id="mainwindow-fig">
1766 <title>MY-GNOME-APP Main Window</title>
1768 <screeninfo>MY-GNOME-APP Main Window</screeninfo>
1769 <graphic fileref="SCREENSHOT" format="png" srccredit="ME">
1773 <!-- ==== End of Figure ==== -->
1777 <!-- For this app, one could put "proving" or "edit" (probably even
1778 both of them) as sect2's seperate from the main window
1779 section. Since they were both so closely involved with the main
1780 window, I decided to have them as sect3's isntead. Judgement
1783 <sect3 id="proving">
1784 <title>Proving a Theorem</title>
1786 To get a proof of a theorem, select
1788 <guisubmenu>File</guisubmenu>
1789 <guimenuitem>New</guimenuitem>
1790 </menuchoice>,
1792 bring up the <interface>New Proof</interface> dialog box.
1793 Enter the statement of the theorem in the
1794 <guilabel>Theorem statement</guilabel> field, select your
1795 desired proof type from the drop-down menu, and and press
1796 <guibutton>Prove!</guibutton>.
1799 If <application>MY-GNOME-APP</application> cannot prove the
1800 theorem by the method you have chosen, or if you have not
1801 selected a proof type at all,
1802 <application>MY-GNOME-APP</application> will attempt to
1803 choose the one that it thinks is most conclusive. In order,
1804 it will attempt to prove the theorem with the following techniques:
1806 <variablelist>
1807 <varlistentry>
1808 <term>Deduction</term>
1811 This is a proof method that is generally accepted
1812 for full credit by Logic professors.
1815 </varlistentry>
1816 <varlistentry>
1817 <term>Induction</term>
1820 This logical style will also earn you full credit on
1824 </varlistentry>
1825 <varlistentry>
1826 <term>Dialog</term>
1829 This logical method is best for Philosophy classes,
1830 and will probably only merit partial credit on Logic
1831 or Mathematics homework.
1834 </varlistentry>
1835 <varlistentry>
1836 <term>Confusion</term>
1839 Suitable only for political debates, battles of wits
1840 against the unarmed, and Philosophy classes focusing
1841 on the works of Kant. Use with caution.
1844 </varlistentry>
1845 </variablelist>
1848 <!-- You might want to include a note, warning, or tip, e.g. -->
1851 <title>Proving Incorrect Theorms</title>
1853 <application>MY-GNOME-APP</application> cannot prove
1854 incorrect theorems. If the theorem you have entered is not
1855 demonstrably true, you will get a message to that effect
1856 in the main window. To disprove a theorem, ask
1857 <application>MY-GNOME-APP</application> to prove its
1862 <sect3 id="editing">
1863 <title>Editing Proofs</title>
1865 Once you have proven the theorem, it will be displayed in
1866 the <interface>main window</interface>. There, you can read
1867 it over, choose text styles for different portions of it,
1868 and make comments on it. This section will guide you through
1872 To alter text styles, first select the statement you wish to
1873 change by clicking on it once. You can select several
1874 statements by Then, choose the style you want to apply from
1875 the <guisubmenu>Style</guisubmenu> submenu of the
1876 <guimenu>Edit</guimenu> menu.
1877 <application>MY-GNOME-APP</application> will convert the
1881 You can also enter comments on a statement by selecting that
1882 statement, and then beginning to type. Comments will appear
1883 after the statement you have selected.
1887 <title>Altering The Proofs Themselves</title>
1889 <application>MY-GNOME-APP</application> does not allow you
1890 to alter a proof it has produced itself. You can, save
1891 your proof as a plain text file (using the
1892 <guimenuitem>Save as...</guimenuitem> menu), and alter it
1893 that way. Be aware, however, that
1894 <application>MY-GNOME-APP</application> uses its own file
1895 format for saved proofs, and cannot re-open a file unless
1896 it is in the .mga format.
1902 <!-- If there are other functions performed from the main window,
1903 they belong here. -->
1907 <!-- =========================================================
1908 Additional Sect2's should describe additional windows, such as
1909 larger dialog boxes, or functionality that differs significantly
1910 from the most immediate functions of the application. Make the
1912 ============================================================= -->
1915 <sect2 id="toolbar">
1916 <title>Toolbar</title>
1918 The toolbar (shown in <xref linkend="figure-usage-toolbar">)
1919 provides access to several commonly used routines.
1920 <figure id="figure-usage-toolbar">
1921 <title>MY-GNOME-APP Toolbar</title>
1923 <screeninfo>MY-GNOME-APP Toolbar</screeninfo>
1924 <graphic fileref="usage-toolbar.png" format="png"></graphic>
1927 <variablelist>
1928 <varlistentry>
1929 <term>New</term>
1932 Brings up the <interface>New Theorem</interface>
1936 </varlistentry>
1937 <varlistentry>
1938 <term>Open</term>
1941 Open an exisiting theorem you want to prove, or a
1942 completed proof you wish to print or format.
1945 </varlistentry>
1946 <varlistentry>
1947 <term>Save</term>
1950 Save the current theorem permanently in a
1954 </varlistentry>
1955 </variablelist>
1958 <!-- ========= Menus =========================== -->
1960 <sect2 id="menubar">
1962 <!-- Describing the menubar ensures comprehensive feature
1963 coverage. Nest itemizedlists inside variablelists so that each
1964 menu is easily located by indexing software. Proper indentation
1965 makes it easier! -->
1967 <title>Menus</title>
1969 The menu bar, located at the top of the <interface>Main
1970 Window</interface>, contains the following menus:
1972 <variablelist>
1973 <varlistentry>
1974 <term><guimenu>File</guimenu></term>
1978 <itemizedlist>
1983 <keycap>F3</keycap>
1985 <guimenuitem>Open</guimenuitem>
1987 &mdash; This opens a file which is saved on your computer.
1994 <keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
1996 <guimenuitem>Save</guimenuitem>
1998 &mdash; This saves your file.
2005 <keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo>
2007 <guimenuitem>Close</guimenuitem>
2009 &mdash; This closes your file.
2016 <keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
2018 <guimenuitem>Exit</guimenuitem>
2020 &mdash; This quits the application.
2023 </itemizedlist>
2026 </varlistentry>
2028 <varlistentry>
2029 <term><guimenu>Edit</guimenu></term>
2033 <itemizedlist>
2038 <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo>
2040 <guimenuitem>Cut</guimenuitem>
2042 &mdash; This removes any text or data which is selected and
2043 places it in the buffer.
2050 <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
2052 <guimenuitem>Copy</guimenuitem>
2054 &mdash; This copies any text or data which is selected into
2062 <keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo>
2064 <guimenuitem>Paste</guimenuitem>
2066 &mdash; This pastes any text or data which is copied into
2072 <guimenuitem>COMMAND1&hellip;</guimenuitem>
2073 &mdash; This opens the <interface>COMMAND1</interface>
2074 dialog, which is used to ....
2079 <guimenuitem>COMMAND2</guimenuitem>
2080 &mdash; This ....
2083 </itemizedlist>
2086 </varlistentry>
2089 <varlistentry>
2090 <term><guimenu>Settings</guimenu></term>
2094 <itemizedlist>
2097 <guimenuitem>Preferences&hellip;</guimenuitem>
2098 &mdash; This opens the <link
2099 linkend="prefs"><interface>Preferences
2100 Dialog</interface></link>, which allows you to configure
2106 <guimenuitem>COMMAND3</guimenuitem> &mdash;
2107 This command does something.
2110 </itemizedlist>
2113 </varlistentry>
2115 <varlistentry>
2116 <term><guimenu>Help</guimenu></term>
2120 <itemizedlist>
2123 <guimenuitem>Manual</guimenuitem> &mdash; This
2124 opens the <application>GNOME Help
2125 Browser</application> and displays this manual.
2131 <guimenuitem>About</guimenuitem> &mdash; This
2132 opens the <interface>About</interface> dialog
2133 which shows basic information about
2134 <application>MY-GNOME-APP</application>, such as
2135 the author's name, the application version number,
2136 and the URL for the application's Web page if one
2140 </itemizedlist>
2143 </varlistentry>
2144 </variablelist>
2150 <!-- ============= Customization ============================= -->
2152 <sect1 id="prefs">
2153 <title>Customization</title>
2155 To change the application settings, select
2157 <guimenu>Settings</guimenu>
2158 <guimenuitem>Preferences...</guimenuitem>
2159 </menuchoice>. This opens the
2160 <interface>Preferences</interface> dialog, shown in <xref
2161 linkend="preferences-fig">.
2164 <figure id="preferences-fig">
2165 <title>Preferences Dialog</title>
2167 <screeninfo>Preferences Dialog</screeninfo>
2168 <graphic fileref="SCREENSHOT" format="png"
2175 The properties in the <guilabel>PREFSTABNAME</guilabel> tab are:
2177 <!--many people use itemizedlists in cases like this. Variablelists
2178 are more appropriate -->
2180 <variablelist>
2181 <varlistentry>
2182 <term> <guilabel>Default Text Style</guilabel></term>
2185 Select the default text style for statements in your
2186 proof. You can still change the style for individual
2187 proofs or sections of a proof at a later date.
2190 </varlistentry>
2191 <varlistentry>
2192 <term>(Configuration Item Label)</term>
2195 (Description of Configuration)
2198 </varlistentry>
2199 <varlistentry>
2200 <term>(Configuration Item Label)</term>
2203 (Description of Configuration)
2206 </varlistentry>
2207 </variablelist>
2211 The properties in the <guilabel>SECONDTABNAME</guilabel> tab are:
2212 <variablelist>
2213 <varlistentry>
2214 <term>(Configuration Item Label)</term>
2217 (Description of Configuration)
2220 </varlistentry>
2221 <varlistentry>
2222 <term>(Configuration Item Label)</term>
2225 (Description of Configuration)
2228 </varlistentry>
2229 </variablelist>
2233 After you have made all the changes you want, click on
2234 <guibutton>OK</guibutton> to apply the changes and close the
2235 <interface>Properties</interface> dialog. To cancel the changes
2236 and return to previous values, click the
2237 <guibutton>Close</guibutton> button.
2243 <!-- ============= Various Sections ============================= -->
2245 <!-- Here you should add, if necessary, several more sect1's,
2246 describing other windows (besides the main one), file formats,
2247 preferences dialogs, etc. as appropriate. Try not to make any of
2248 these sections too long. -->
2251 <!-- ============= Bugs ================================== -->
2252 <!-- This section should describe known bugs and limitations of
2253 the program if there are any - please be frank and list all
2254 problems you know of. -->
2255 <sect1 id="bugs">
2256 <title>Known Bugs and Limitations</title>
2258 This application has no known bugs.
2263 <!-- ============= Authors ================================ -->
2265 <sect1 id="authors">
2266 <title>Authors</title>
2268 <application>MY-GNOME-APP</application> was written by GNOME-HACKER
2269 (<email>hacker@gnome.org</email>). To find more information about
2270 <application>MY-GNOME-APP</application>, please visit the <ulink
2271 url="http://www.my-gnome-app.org" type="http">MY-GNOME-APP Web
2272 page</ulink>. Please send all comments, suggestions, and bug
2273 reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
2274 bug tracking database</ulink>. (Instructions for submitting bug
2275 reports can be found <ulink
2276 url="http://bugs.gnome.org/Reporting.html" type="http">
2277 on-line</ulink>.) You can also use <application>Bug Report
2278 Tool</application> (<command>bug-buddy</command>), available in the
2279 <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
2280 Menu</guimenu>, for submitting bug reports.
2284 This manual was written by ME
2285 (<email>MYNAME@MYADDRESS</email>). Please send all comments and
2286 suggestions regarding this manual to the <ulink type="http"
2287 url="http://developer.gnome.org/projects/gdp">GNOME Documentation
2288 Project</ulink> by sending an email to
2289 <email>docs@gnome.org</email>. You can also add your comments online
2290 by using the <ulink type="http"
2291 url="http://www.gnome.org/gdp/doctable/">GNOME Documentation Status
2292 Table</ulink>.
2295 <!-- For translations: uncomment this:
2298 Latin translation was done by ME
2299 (<email>MYNAME@MYADDRESS</email>). Please send all comments and
2300 suggestions regarding this translation to SOMEWHERE.
2308 <!-- ============= Application License ============================= -->
2310 <sect1 id="license">
2311 <title>License</title>
2313 This program is free software; you can redistribute it and/or
2314 modify it under the terms of the <citetitle>GNU General Public
2315 License</citetitle> as published by the Free Software Foundation;
2316 either version 2 of the License, or (at your option) any later
2320 This program is distributed in the hope that it will be useful, but
2321 WITHOUT ANY WARRANTY; without even the implied warranty of
2322 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2323 <citetitle>GNU General Public License</citetitle> for more details.
2326 A copy of the <citetitle>GNU General Public License</citetitle> is
2327 included as an appendix to the <citetitle>GNOME Users
2328 Guide</citetitle>. You may also obtain a copy of the
2329 <citetitle>GNU General Public License</citetitle> from the Free
2330 Software Foundation by visiting <ulink type="http"
2331 url="http://www.fsf.org">their Web site</ulink> or by writing to
2333 Free Software Foundation, Inc.
2334 <street>59 Temple Place</street> - Suite 330
2335 <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
2336 <country>USA</country>
2354 </p></div><div class="sect1"><a name="template2-1x"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="template2-1x"/>Template 2: Applet Manual For GNOME 1.x</h2></div></div><p>
2355 The following templates should be used for all applet
2356 manuals in GNOME 1.x releases. You can always get the latest
2357 copy of these templates from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
2358 Documentation Templates</a>. Note that the template
2359 consists of two files; the first file calls the second as an
2360 entity. You should name the first file
2361 <tt><i><tt>appletname</tt></i>-applet.sgml</tt>
2362 and the second file should be named
2363 <tt><i><tt>appletname</tt></i>.sgml</tt>,
2365 <tt><i><tt>appletname</tt></i></tt> is
2366 the name of the applet.
2367 <pre class="programlisting">
2370 <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
2371 <!entity APPLETNAME.sgml SYSTEM "applet_template_1.sgml">
2372 <!-- Template Version: 1.0.1 (do not remove this line) -->
2375 <!-- This is a GNOME documentation template, designed by the GNOME
2376 Documentation Project Team. Please use it for writing GNOME
2377 documentation, making obvious changes. In particular, all the words
2378 written in UPPERCASE (with the exception of GNOME) should be
2379 replaced. As for "legalnotice", please leave the reference
2380 unchanged,make sure to add/remove trademarks to the list as
2381 appropriate for your document.
2383 Please don't forget to remove these comments in your final documentation,
2387 <article id="index"> <!-- please do not change the id -->
2389 <!-- ============= Document Header ============================= -->
2391 <title>APPLETNAME Applet</title>
2393 <year>2000</year>
2394 <holder>YOURFULLNAME</holder>
2397 <!-- translators: uncomment this:
2400 <year>2000</year>
2401 <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
2406 <!-- do not put authorname in the header except in copyright - use
2407 section "authors" below -->
2411 Permission is granted to copy, distribute and/or modify this
2412 document under the terms of the <citetitle>GNU Free Documentation
2413 License</citetitle>, Version 1.1 or any later version published
2414 by the Free Software Foundation with no Invariant Sections, no
2415 Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
2416 of the <citetitle>GNU Free Documentation License</citetitle> from
2417 the Free Software Foundation by visiting <ulink type="http"
2418 url="http://www.fsf.org">their Web site</ulink> or by writing to:
2419 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
2420 Boston, MA 02111-1307, USA.
2423 Many of the names used by companies to distinguish their products and
2424 services are claimed as trademarks. Where those names appear in any
2425 GNOME documentation, and those trademarks are made aware to the members
2426 of the GNOME Documentation Project, the names have been printed in caps
2429 </legalnotice>
2432 This is version XXX of the APPLETNAME applet manual.
2433 </releaseinfo>
2436 <!-- ============= Document Body ============================= -->
2438 &APPLETNAME.sgml;
2447 <pre class="programlisting">
2449 <!-- Template Version: 1.0.1 (do not remove this line) -->
2451 <sect1 id="APPLET">
2452 <title>APPLET Applet</title>
2455 <application>APPLET</application> applet, shown in <xref
2456 linkend="APPLETapplet-fig">, allows you to &hellip;. To add this
2457 applet to a <interface>Panel</interface>,
2458 right-click on the <interface>Panel</interface> and choose
2460 <guimenu>Panel</guimenu>
2461 <guisubmenu>Add to panel</guisubmenu>
2462 <guisubmenu>Applet</guisubmenu>
2463 <guisubmenu>SECTION</guisubmenu>
2464 <guimenuitem>APPLET</guimenuitem>
2465 </menuchoice>.
2468 <figure id="APPLETapplet-fig">
2469 <title>APPLET Applet</title>
2471 <screeninfo>APPLET Applet</screeninfo>
2472 <graphic format="png" fileref="APPLET_applet"
2473 srccredit="YOURNAME">
2478 <!-- ============= Usage ================================ -->
2479 <sect2 id="APPLET-usage">
2480 <title>Usage</title>
2482 (Place a short description of how to use the applet here.)
2486 Right-clicking on the applet brings up a menu containing the
2488 <itemizedlist>
2492 <guimenuitem>Properties&hellip;</guimenuitem> &mdash;
2493 opens the <link linkend="APPLET-prefs">
2494 <guilabel>Properties</guilabel></link> dialog.
2500 <guimenuitem>Help</guimenuitem> &mdash;
2501 displays this document.
2507 <guimenuitem>About&hellip;</guimenuitem> &mdash;
2508 shows basic information about <application>APPLET
2509 Applet</application>, including the applet's version and the
2514 </itemizedlist>
2519 <!-- ============= Customization ============================= -->
2520 <sect2 id="APPLET-prefs">
2521 <title>Customization</title>
2523 You can customize <application>APPLET</application>
2524 applet by right-clicking on it and choosing
2525 <guimenuitem>Properties&hellip;</guimenuitem>. This will open the
2526 <interface>Properties</interface> dialog(shown in <xref
2527 linkend="APPLET-settings-fig">), which allows you to
2528 change various settings.
2531 <figure id="APPLET-settings-fig">
2532 <title>Properties dialog</title>
2534 <screeninfo>Properties dialog</screeninfo>
2535 <graphic format="png" fileref="APPLET_settings"
2536 srccredit="YOURNAME">
2543 <itemizedlist>
2547 (Configuration Item Label) &mdash; If this button is
2548 checked&hellip;(description)
2554 (Configuration Item Label) &mdash; Selecting this
2555 button&hellip;(description)
2561 (Configuration Item Label) &mdash; Enter the name of
2562 &hellip;(description)
2565 </itemizedlist>
2569 After you have made all the changes you want, click on
2570 <guibutton>OK</guibutton> to apply the changes and close the
2571 <interface>Properties</interface> dialog. To cancel the changes
2572 and return to previous values, click the
2573 <guibutton>Close</guibutton> button.
2578 <!-- ============= Bugs ================================== -->
2579 <!-- This section should describe known bugs and limitations of
2580 the program if there are any - please be frank and list all
2581 problems you know of -->
2582 <sect2 id="bugs">
2583 <title>Known Bugs and Limitations</title>
2585 This applet has no known bugs.
2590 <!-- ============= Authors ================================ -->
2592 <sect2 id="authors">
2593 <title>Authors</title>
2595 <application>APPLET</application> was written by GNOME-HACKER
2596 (<email>hacker@gnome.org</email>). Please send all comments,
2597 suggestions, and bug
2598 reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
2599 bug tracking database</ulink>. (Instructions for submitting bug
2600 reports can be found <ulink
2601 url="http://bugs.gnome.org/Reporting.html" type="http">
2602 on-line</ulink>. You can also use <application>Bug Report
2603 Tool</application> (<command>bug-buddy</command>), available in the
2604 <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
2605 Menu</guimenu>, for submitting bug reports.
2609 This manual was written by ME
2610 (<email>MYNAME@MYADDRESS</email>). Please send all comments and
2611 suggestions regarding this manual to the <ulink type="http"
2612 url="http://developer.gnome.org/projects/gdp">GNOME Documentation
2613 Project</ulink> by sending an email to
2614 <email>docs@gnome.org</email>. You can also submit comments online
2615 by using the <ulink type="http"
2616 url="http://www.gnome.org/gdp/doctable/">GNOME Documentation
2617 Status Table</ulink>.
2620 <!-- For translations: uncomment this:
2623 Latin translation was done by ME
2624 (<email>MYNAME@MYADDRESS</email>). Please send all comments and
2625 suggestions regarding this translation to SOMEWHERE.
2633 <!-- ============= Application License ============================= -->
2635 <sect2 id="license">
2636 <title>License</title>
2638 This program is free software; you can redistribute it and/or
2639 modify it under the terms of the <citetitle>GNU General Public
2640 License</citetitle> as published by the Free Software Foundation;
2641 either version 2 of the License, or (at your option) any later
2645 This program is distributed in the hope that it will be useful, but
2646 WITHOUT ANY WARRANTY; without even the implied warranty of
2647 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2648 <citetitle>GNU General Public License</citetitle> for more details.
2651 A copy of the <citetitle>GNU General Public License</citetitle> is
2652 included as an appendix to the <citetitle>GNOME Users
2653 Guide</citetitle>. You may also obtain a copy of the
2654 <citetitle>GNU General Public License</citetitle> from the Free
2655 Software Foundation by visiting <ulink type="http"
2656 url="http://www.fsf.org">their Web site</ulink> or by writing to
2658 Free Software Foundation, Inc.
2659 <street>59 Temple Place</street> - Suite 330
2660 <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
2661 <country>USA</country>
2676 </p></div><div class="sect1"><a name="template2-2x"/><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="template2-2x"/>Template 2: Applet Manual For GNOME 2.x</h2></div></div><p>
2677 The following templates should be used for all applet
2678 manuals in GNOME 2.x releases. You can always get the latest
2679 copy of these templates from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
2680 Documentation Templates</a>.
2682 Note that this template consists of two files. The first file
2683 is an introductory chapter. You should not modify this
2684 chapter. The second file is the actual applet document, which
2685 you should modify to describe the applet you are documenting.
2686 You can name the first file whatever you like, such as
2687 <tt>gnome-applets.sgml</tt>. Name the second file
2688 according to the applet's name:
2689 <tt><i><tt>appletname</tt></i>-applet.sgml</tt>.
2690 Make sure you update the entity
2691 at the top of the shell document to reflect the new name of
2692 the applet document.
2694 <pre class="programlisting">
2696 <!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
2697 <!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part">
2701 <book id="gnome-applets">
2704 <title>GNOME Applets</title>
2706 <author><firstname>Telsa</firstname><surname>Gwynne</surname></author>
2707 <author><firstname>John</firstname><surname>Fleck</surname></author>
2708 <author><firstname>David</firstname><surname>Mason</surname>
2709 <affiliation><orgname>Red Hat, Inc.</orgname></affiliation>
2711 <author><firstname>Dan</firstname><surname>Mueth</surname></author>
2712 <author><firstname>Alexander</firstname><surname>Kirillov</surname></author>
2713 </authorgroup>
2714 <edition>GNOME Applets version 0.1 for GNOME 1.1.5</edition>
2715 <pubdate>2000</pubdate>
2717 <year>2000</year>
2718 <holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and
2719 Alexander Kirillov</holder>
2723 Permission is granted to make and distribute verbatim copies of this
2724 manual provided the copyright notice and this permission notice are
2725 preserved on all copies.
2728 Permission is granted to copy and distribute modified versions of
2729 this manual under the conditions for verbatim copying, provided that
2730 the entire resulting derived work is distributed under the terms of a
2731 permission notice identical to this one.
2734 Permission is granted to copy and distribute translations of this
2735 manual into another language, under the above conditions for modified
2736 versions, except that this permission notice may be stated in a
2737 translation approved by the Free Software Foundation.
2740 Many of the names used by companies to distinguish their products and
2741 services are claimed as trademarks. Where those names appear in any
2742 GNOME documentation, and those trademarks are made aware to the members
2743 of the GNOME Documentation Project, the names have been printed in caps
2746 </legalnotice>
2749 <!-- #### Introduction ###### -->
2750 <chapter id="applets-intro">
2751 <title>Introduction</title>
2753 <!-- #### Intro | What Are Applets? ###### -->
2754 <sect1 id="applets-what-are">
2755 <title>What Are Applets?</title>
2757 Applets are one of the most popular and useful objects you can add
2758 to your <interface>Panel</interface> to customize your desktop.
2759 An applet is a small application which runs inside a small area of
2760 your <interface>Panel</interface>. Applets have been written for
2761 a wide range of purposes. Some are very powerful interactive
2762 tools, such as the <application>Tasklist</application> Applet
2763 which allows you to easily
2764 control all of your main applications. Others are simple system
2765 monitors, displaying information such as the amount of power left
2766 in the battery on your laptop (see <application>Battery Charge
2767 Monitor</application>) or weather
2768 information(see <application>GNOME Weather</application>). Some
2769 are simply for amusement(see <application>Fish</application>).
2773 Applets are similar to swallowed applications in that both of them
2774 reside within the <interface>Panel</interface>. However,
2775 swallowed applications are generally applications which were
2776 not designed to run within the <interface>Panel</interface>.
2777 Typically one will swallow an application which already exists in
2778 the main <interface>desktop</interface> area, putting it into your
2779 <interface>Panel</interface>. The application will continue to
2780 run in the <interface>Panel</interface> until you end the
2781 application or unswallow it, placing it back onto the main part of
2782 your desktop when you need to.
2786 <figure id="example-applets-fig">
2787 <title>Example Applets</title>
2789 <screeninfo>Example Applets</screeninfo>
2790 <graphic fileref="example_applets" format="png"
2791 srccredit="muet">
2795 Several example applets are shown in <xref
2796 linkend="example-applets-fig">. From left to right, they are: (1)
2797 <application>Mixer Applet</application>, which allows you to turn
2798 on/off sound and control its volume by clicking on the applet. (2)
2799 <application>Sound Monitor</application> Applet, which displays
2800 the current volume of sound being played and allows you to control
2801 various sound features. (3) <application>GTCD</application>
2802 Applet, a CD player which has all its controls
2803 available in the applet and displays the track and time. (4)
2804 <application>Drive Mount</application> Applet, used to mount and
2805 unmount drives with a single click of the mouse. (5)
2806 <application>Desk Guide</application> which allows you to view
2807 and control multiple virtual screens. (6)
2808 <application>Tasklist</application> Applet which allows you to
2809 control your various windows and applications.
2812 There are many other applets to choose from. The rest of this
2813 chapter will explain the basic information to get you started
2814 adding, moving, and removing applets from your
2815 <interface>Panels</interface> and using them. The following
2816 chapters go through each of the standard GNOME applets describing
2817 them in detail. There are also additional applets which can be
2818 downloaded off the Web. See <ulink type="http"
2819 url="http://www.gnome.org/applist/list-martin.phtml">The GNOME
2820 Software Map</ulink> for lists of additional GNOME applications
2824 As you read through the the rest of this chapter, you should try
2825 adding and removing applets from your <interface>Panel</interface> and
2826 experiment with them freely.
2830 <!-- #### Intro | Adding, Moving, and Removing Applets ###### -->
2831 <sect1 id="applet-add-move-replace">
2832 <title>Adding, Moving, and Removing Applets</title>
2834 <sect2 id="adding-applets">
2835 <title>Adding Applets to a Panel</title>
2837 To add an applet to a <interface>Panel</interface>, right-click
2838 on the <interface>Panel</interface> and select
2839 <menuchoice><guimenu>Panel</guimenu><guisubmenu>Add to panel</guisubmenu>
2840 <guisubmenu>Applet</guisubmenu></menuchoice>. This will show you
2841 the menu of all the applets on your system, divided into
2842 categories. Choosing any applet from this menu will add it to the
2843 <interface>Panel</interface>.
2847 <sect2 id="moving-applets">
2848 <title>Moving Applets In or Between Panels</title>
2850 It is easy to move applets in a <interface>Panel</interface> or
2851 between two <interface>Panels</interface>. If you have a
2852 three-button mouse, just move the mouse over the applet, depress
2853 the middle mouse button and drag the applet to its new location,
2854 releasing the middle mouse button when you are finished. Note
2855 that you can drag applets within a <interface>Panel</interface>
2856 or between two <interface>Panels</interface> this way. If you
2857 don't have a three-button mouse, just
2858 right-click on the applet and choose
2859 <guimenuitem>Move</guimenuitem>. The cursor will turn into a
2860 cross and the applet will move with your mouse until you press
2861 any mouse button to indicate you are finished moving it.
2862 If, in the course of this movement, it hits
2863 other objects, the behavior depends on the global preferences
2864 you have set for your <interface>Panels</interface> in the
2865 <application>GNOME Control Center</application>: the applet you are
2866 moving can switch places with other objects, "push" all objects
2867 it meets, or "jump" over all other objects without disturbing
2868 them. You can also override the default behavior by holding
2869 <keycap>Shift</keycap> button (for "push" mode),
2870 <keycap>Ctrl</keycap> (for "switched" mode), or
2871 <keycap>Alt</keycap> (for "free" mode, i.e. jumping other other
2872 objects without disturbing them) button while dragging.
2875 To change the global Panel preferences, right-click on any applet
2876 or <interface>Panel</interface> and select
2878 <guimenu>Panel</guimenu>
2879 <guimenuitem>Global Preferences...</guimenuitem>
2880 </menuchoice>.
2881 The <guilabel>Default movement mode</guilabel> is set under the
2882 <guilabel>Applets</guilabel> tab.
2886 <sect2 id="removing-applets">
2887 <title>Removing Applets from a Panel</title>
2889 To remove an applet from a <interface>Panel</interface>,
2890 right-click on the applet and select <guimenuitem>Remove from
2891 panel...</guimenuitem>.
2897 <!-- #### Intro | The Right-Click Pop-Up Menu ###### -->
2898 <sect1 id="right-click-pop-up-menu">
2899 <title>The Right-Click Pop-Up Menu</title>
2901 Clicking the right mouse button on any applet brings up
2902 a <guimenu>pop-up menu</guimenu>. This
2903 menu always has certain standard menu items in it and
2904 often has additional items which vary depending on the particular
2907 <sect2 id="standard-right-click-items">
2908 <title>Standard Pop-Up Items</title>
2910 All applets should have the following items in their right-click
2911 <guimenu>pop-up menu</guimenu>:
2912 <variablelist>
2913 <varlistentry>
2914 <term>Remove from panel</term>
2917 The <guimenuitem>Remove from panel</guimenuitem> menu item
2918 removes the applet from the <interface>Panel</interface>.
2921 </varlistentry>
2923 <varlistentry>
2924 <term>Move</term>
2927 After selecting <guimenuitem>Move</guimenuitem>, your mouse
2928 pointer will change appearance (typically to a cross with
2929 arrows in each direction). As you move your mouse, the applet
2930 will move with it. When you have finished moving the applet,
2931 click any mouse button and the applet will anchor in its
2932 current position. Note that applets can be moved between two
2933 <interface>Panels</interface> this way.
2936 </varlistentry>
2938 <varlistentry>
2939 <term>Panel</term>
2942 The <guisubmenu>Panel</guisubmenu> submenu contains various
2943 items and submenus for adding and removing
2944 <interface>Panels</interface> and applets and for changing
2948 </varlistentry>
2950 <varlistentry>
2951 <term>About</term>
2954 The <guimenuitem>About...</guimenuitem> menu item brings up a
2955 dialogue box containing various information about the applet,
2956 typically including the applet's name, version, author,
2957 copyright, license and desciption.
2960 </varlistentry>
2962 <varlistentry>
2963 <term>Help</term>
2966 The <guimenuitem>Help</guimenuitem> menu item brings up the help
2967 manual for the applet.
2970 </varlistentry>
2971 </variablelist>
2975 <sect2 id="applet-properties-dialog">
2976 <title>The Applet Properties Dialog</title>
2978 Many applets have customizable properties. These applets will
2979 have a <guimenuitem>Properties...</guimenuitem> menu item in their
2980 right-click <guimenu>pop-up menu</guimenu> which brings up the
2981 <interface>Properties</interface> dialog where you can alter the
2982 appearance or behaviour of the applet.
2983 <figure id="example-props-dialog-fig">
2984 <title>An Example Applet Properties Dialog</title>
2986 <screeninfo>An Example Applets Properties Dialog</screeninfo>
2987 <graphic fileref="applet_props_dialog" format="png"
2988 srccredit="muet">
2992 All <interface>Properties</interface> dialogs have the following
2993 buttons at the bottom of the dialog:
2994 <itemizedlist>
2997 <guibutton>OK</guibutton> &mdash;
2998 Pressing <guibutton>OK</guibutton> will activate any changes
2999 in the properties you have made and close the
3000 <interface>Properties</interface> dialog.
3005 <guibutton>Apply</guibutton> &mdash;
3006 Pressing <guibutton>Apply</guibutton> at any time will
3007 make your changes active without closing the
3008 <interface>Properties</interface> dialog. This is helpful if
3009 you would like to test the effects of the changes you have
3010 made but may want to continue changing the properties.
3015 <guibutton>Close</guibutton> &mdash;
3016 Pressing <guibutton>Close</guibutton> will close the
3017 <interface>Properties</interface> dialog. Only changes in the
3018 configuration which were previously applied with the
3019 <guibutton>Apply</guibutton> button will persist. Other
3020 changes will not be made active.
3025 <guibutton>Help</guibutton> &mdash;
3026 Pressing <guibutton>Help</guibutton> brings up the manual for
3027 the application, opening it to the page describing the
3028 <interface>Properties</interface> dialog.
3031 </itemizedlist>
3035 <sect2 id="common-right-click-items">
3036 <title>Other Common Pop-Up Items</title>
3038 Many applets also have one or more of the following items in their
3039 right-click pop-up menu:
3040 <variablelist>
3041 <varlistentry>
3042 <term>Run...</term>
3045 The <guimenuitem>Run...</guimenuitem> menu item generally
3046 invokes a program which is related to the applet in some way
3047 but which runs in its own window rather than in the
3053 The <application>CPU Load</application> applet, which monitors
3054 what programs are running, has a <guimenuitem>Run
3055 gtop...</guimenuitem> menu item. Selecting this menu item
3056 starts <application>GTop</application>, which allows you to
3057 view and control programs which are running.
3062 The <application>CD Player</application> applet has a
3063 <guimenuitem>Run gtcd...</guimenuitem> menu item which
3064 starts the GNOME <application>CD Player</application> when
3065 selected, which has more capabilities than the applet.
3068 </orderedlist>
3070 </varlistentry>
3071 </variablelist>
3076 <sect1 id="feedback">
3077 <title>Feedback</title>
3078 <sect2 id="reporting-bugs">
3079 <title>Reporting Applet Bugs</title>
3081 GNOME users are encouraged to report bugs to <ulink type="http"
3082 url="http://bugs.gnome.org">The GNOME Bug Tracking
3083 System</ulink>. The easiest way to submit bugs is to use the
3084 <application>Bug Report Tool</application> program by selecting
3086 <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
3087 <guimenuitem>Bug Report Tool</guimenuitem>
3088 </menuchoice>.
3089 Be sure to be complete in describing what you did to cause the
3090 bug to surface and, if possible, describe how the developer can
3091 reproduce the the scenario.
3094 <sect2 id="documentation-feedback">
3095 <title>Providing Feedback</title>
3097 GNOME users are welcome to provide suggestions for how
3098 applications and documentation can be improved. Suggestions for
3099 application changes should be submitted using the
3100 <application>Bug Report Tool</application> discussed above.
3101 Suggestions for documentation changes can be emailed directly to
3102 the documentation author (whose email should be included in the
3103 "Authors" section of the document) or by sending an email to
3104 <email>docs@gnome.org</email>.
3107 <sect2 id="joining-gnome">
3108 <title>Joining GNOME</title>
3110 GNOME is a community project, created by hundreds of programmers,
3111 documentation writers, icon design artists, web masters, and
3112 other people, most of whom work on a volunteer basis. New GNOME
3113 contributors are always welcome. To join the GNOME team, visit
3114 these web sites: developers &mdash; <ulink type="http"
3115 url="http://developer.gnome.org">The GNOME Development
3116 Site</ulink>, documentation writers &mdash; <ulink type="http"
3117 url="http://developer.gnome.org/projects/gdp">The GNOME Documentation
3118 Project</ulink>, icon design artists &mdash; <ulink type="http"
3119 url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>,
3120 general &mdash; <ulink type="http"
3121 url="http://developer.gnome.org/helping/">Helping GNOME</ulink>,
3122 or just join the gnome-list email list (see <ulink type="http"
3123 url="http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing
3124 Lists</ulink>) to discuss what you are interested in doing.
3130 <!-- ############### Template Applets ##################### -->
3131 <chapter id="template-applets">
3132 <title>Template Applets</title>
3134 &TEMPLATE-APPLET
3149 <pre class="programlisting">
3152 <!-- Please replace everywhere below GNOMEAPPLET with the name of -->
3153 <!-- your applet. Most importantly, all id attributes should start -->
3154 <!-- with the name of your applet - this is necessary to avoid name -->
3155 <!-- conflict among different applets -->
3156 <!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email-->
3157 <!-- Please replace HACKER-NAME with the applet author's name and -->
3158 <!-- HACKER-EMAIL with the applet author's email -->
3160 <!-- You should name your file: GNOMEAPPLET-applet.sgml -->
3161 <!-- Screenshots should be in PNG format and placed in the -->
3162 <!-- same directory as GNOMEAPPLET-applet.sgml -->
3164 <!-- Applet docs will be merged into <chapter>'s inside a -->
3165 <!-- <book>. Thus, the indentation below (2 spaces before the <sect1>) is -->
3166 <!-- correct.-->
3168 <!-- Permission is granted to make and distribute verbatim copies of -->
3169 <!-- this manual provided the copyright notice and this permission -->
3170 <!-- notice are preserved on all copies. -->
3172 <!-- Permission is granted to copy and distribute modified versions of -->
3173 <!-- this manual under the conditions for verbatim copying, provided -->
3174 <!-- that the entire resulting derived work is distributed under the -->
3175 <!-- terms of a permission notice identical to this one. -->
3177 <!-- Permission is granted to copy and distribute translations of this -->
3178 <!-- manual into another language, under the above conditions for -->
3179 <!-- modified versions, except that this permission notice may be -->
3180 <!-- stated in a translation approved by the Foundation. -->
3182 <!-- ############### GNOMEAPPLET ############### -->
3183 <sect1 id="GNOMEAPPLET">
3184 <title>GNOMEAPPLET Applet</title>
3187 <application>GNOMEAPPLET</application> applet, shown in <xref
3188 linkend="GNOMEAPPLET-fig">, does this and that. To learn how to
3189 add this applet to a <interface>Panel</interface>, see <xref
3190 linkend="adding-applets">.
3194 <figure id="GNOMEAPPLET-fig">
3195 <title>GNOMEAPPLET</title>
3197 <screeninfo>GNOMEAPPLET</screeninfo>
3198 <graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME">
3203 <sect2 id="GNOMEAPPLET-usage">
3204 <title>Usage</title>
3206 This applet does nothing. To use it, just
3207 left-click on it and it will instantly do nothing.
3211 <sect2 id="GNOMEAPPLET-right-click">
3212 <title>Right-Click Pop-Up Menu Items</title>
3214 In addition to the standard menu items (see <xref
3215 linkend="standard-right-click-items">), the right-click pop-up menu has
3216 the following items:
3217 <itemizedlist>
3220 <guimenuitem>Properties...</guimenuitem> &mdash; This menu
3221 item opens the <interface>Properties</interface> dialog (see
3222 <xref linkend="GNOMEAPPLET-properties">) which allows you to
3223 customize the appearance and behavior of this applet.
3228 <guimenuitem>Run Hello World...</guimenuitem> &mdash; This
3229 menu item starts the program <application>Hello
3230 World</application>, used to say "hello" to the world.
3233 </itemizedlist>
3237 <sect2 id="GNOMEAPPLET-properties">
3238 <title>Properties</title>
3240 You can configure <application>GNOMEAPPLET</application> applet by
3241 right-clicking on the applet and choosing the
3242 <guimenuitem>Properties...</guimenuitem> menu item. This will open the
3243 <interface>Properties</interface> dialog, shown in <xref
3244 linkend="GNOMEAPPLET-properties-fig">.
3246 <figure id="GNOMEAPPLET-properties-fig">
3247 <title>Properties Dialog</title>
3249 <screeninfo>Properties Dialog</screeninfo>
3250 <graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME">
3256 To change the color of the applet, click on the
3257 <guibutton>color</guibutton> button. To change other properties,
3258 click on other buttons.
3262 For more information on the <interface>Properties</interface>
3263 dialog, including descriptions of the <guibutton>OK</guibutton>,
3264 <guibutton>Apply</guibutton>, <guibutton>Cancel</guibutton>, and
3265 <guibutton>Help</guibutton> buttons, see <xref
3266 linkend="applet-properties-dialog">.
3270 <sect2 id="GNOMEAPPLET-bugs">
3271 <title> Known Bugs and Limitations</title>
3273 There are no known bugs in the
3274 <application>GNOMEAPPLET</application> applet.
3278 <sect2 id="GNOMEAPPLET-authors">
3279 <title>Authors</title>
3281 This applet was writen by HACKER-NAME
3282 <email>HACKER-EMAIL</email>. The documentation for this applet
3283 which you are reading now was written by
3284 YOUR-NAME <email>YOUR-EMAIL</email>. For information on submitting
3285 bug reports and suggestions for improvements, see <xref
3286 linkend="feedback">.
3300 </p></div></div></div></body></html>
projects / platform / upstream / libxslt.git / blob