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"> 9 This is a pre-release! 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. 20 </p><p> 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 25 or initial 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 27 0.99 28 </td><td align="left"> 29 04.10.2000 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> 88 Directory 89 </td></tr><tr><td><tt>foo.sgml</tt></td><td> 90 Filename 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. 100 </p><p> 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. 116 </p><p> 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. 122 </p><p> 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. 140 </p><p> 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 170 learning DocBook. 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>. 178 </p><p> 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 188 189 over the file 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>. 199 </p><p> 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 208 by hand: 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 221 file: 222 <pre class="programlisting"> 223PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd" 224 </pre> 225 If you are using the 3.1 DTD, use: 226 <pre class="programlisting"> 227PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd" 228 </pre> 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. 233 </p><p> 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: 237 </p><p> 238 Articles: 239 <pre class="programlisting"> 240<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant 241V1.1//EN"[]> 242 </pre> 243 </p><p> 244 Books: 245 <pre class="programlisting"> 246<!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant 247V1.1//EN"[]> 248 </pre> 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. 255 </p><p> 256 Probably the two most popular editors available are 257 Emacs and 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. 273 </p><p> 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 281 will typically be 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. 289 </p><p> 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. 305 </p><p> 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). 310 </p><p> 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"> 315 316<figure> 317 <title>My Image</title> 318 <screenshot> 319 <screeninfo>Sample GNOME Display</screeninfo> 320 <graphic format="png" fileref="myfile" srccredit="me"> 321 </graphic> 322 </screenshot> 323</figure> 324 </pre><p> 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 330 the directory. 331 </p><p> 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 344 DocBook: 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 355 getting started. 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 361 was. 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. 372 </p><p> 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 389 each file from CVS. 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 427 Netscape or the 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 432 in a Panel, 433 xv can be used to crop the 434 screenshot to only include the relevant portion of the 435 Panel. Note that 436 xv and 437 gimp can both be used for taking 438 screenshots, cropping screenshots, and converting image 439 formats. 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 468 package. 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 503 <b> export 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. 509 To check 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 519 commit</b>. To 520 add a new file to the CVS server, use <b>cvs -z3 add 521 <i><tt>filename</tt></i></b>, followed by the 522 commit command. 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 537 author. 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 545 documents. 546 </p><p> 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. 578 </p><p> 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> 609 below. 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 613 as the panel and 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 625 Guide</i>. 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 629 possible. 630 </p><p> 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 634 Reference</a> page. 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>. 651 </p><p> 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. 655 </p><p> 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>. 662 </p><p> 663 The final appearance of the output (e.g. PostScript or HTML) 664 is determined by a 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>. 674 </p><p> 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. 685 </p><p> 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 691 accurate search. 692 </p><p> 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 697 same. 698 </p><p> 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: 728 <tt><tt><xref 729 linkend="someid"></tt></tt>. In 730 XML, it is illegal; instead, you should use 731 <tt><tt><xref 732 linkend="someid"/></tt></tt> (note the 733 slash!). 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"> 767 768<tip> 769 <title>TIP</title> 770 <para> 771 To speed up program compilation, use <application>gcc</application> 772 compiler with Pentium optimization. 773 </para> 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 783 tags: 784 785 <pre class="programlisting"> 786 787<figure id="shot1"> 788 <title>Screenshot</title> 789 <screenshot> 790 <screeninfo>Screenshot of a program</screeninfo> 791 <graphic format="PNG" fileref="figures/example_screenshot" srccredit="ME"> 792 </graphic> 793 </screenshot> 794</figure> 795 </pre> 796 replacing <tt>example_screenshot</tt> with the 797 actual file name (without extension). The result will look like this: 798 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"> 808 809<programlisting> 810[Desktop Entry] 811Name=Gnumeric spreadsheet 812Exec=gnumeric 813Icon=gnome-gnumeric.png 814Terminal=0 815Type=Application 816</programlisting> 817 </pre> 818 which produces 819 <pre class="programlisting"> 820[Desktop Entry] 821Name=Gnumeric spreadsheet 822Exec=gnumeric 823Icon=gnome-gnumeric.png 824Terminal=0 825Type=Application 826 </pre> 827 As a matter of fact, all examples in this document were 828 produced using <tt><programlisting></tt>. 829 </p><p> 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"> 834 835<screen> 836<prompt>bash$</prompt><userinput>make love</userinput> 837make: *** No rule to make target `love'. Stop. 838</screen> 839 </pre> 840 which produces 841 <pre class="screen"> 842<tt>bash$</tt><b><tt>make love</tt></b> 843make: *** No rule to make target `love'. Stop. 844 </pre> 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, 855 </p></div> 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"> 865 866<itemizedlist> 867 <listitem> 868 <para> 869 <guilabel>Show backup files</guilabel> &mdash; This will 870 show any backup file that might be on your system. 871 </para> 872 </listitem> 873 <listitem> 874 <para> 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. 878 </para> 879 </listitem> 880 <listitem> 881 <para> 882 <guilabel>Mix files and directories</guilabel> &mdash; This 883 option will display files and directories in the order you 884 sort them instead of 885 always having directories shown above files. 886 </para> 887 </listitem> 888</itemizedlist> 889 890 </pre> 891 and output: 892 </p><div class="itemizedlist"><ul><li><p><a name="id2529912"/> 893 Show backup files -- 894 This will show any backup file that might be on 895 your system. 896 </p></li><li><p><a name="id2529958"/> 897 Show hidden files -- 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>, 915 or -- if none of 916 this applies -- use 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>, 927 <tt>upperalpha</tt>, 928 <tt>loweralpha</tt>, 929 <tt>upperroman</tt>, 930 <tt>lowerroman</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"> 942 943<variablelist> 944 <varlistentry> 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> 951 <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> 958 <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> 965 966 </pre> 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 984 menu 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 996 terminal 997 there is a special construction for this, too: 998 <pre class="programlisting"> 999 1000<menuchoice> 1001 <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu> 1002 <guimenuitem>GNOME terminal</guimenuitem> </menuchoice> 1003 </pre> 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"> 1012An example of a <link linkend="extip">tip</link> was given in 1013<xref linkend="notes" />. 1014 </pre> 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>. 1016 </p><p> 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> 1022 tag, for example: 1023 <pre class="programlisting"> 1024 To find more about GNOME, please visit <ulink type="http" 1025url="http://www.gnome.org">GNOME Web page</ulink> 1026 </pre> 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 1037 things: 1038 </p><div class="itemizedlist"><ul><li><p><a name="id2530717"/> <tt><filename></tt> -- used 1039 for filenames, 1040 e.g.<tt><filename></tt> 1041 foo.sgml 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 1052 application names, 1053 e.g. <tt><application></tt>Gnumeric 1054 <tt></application></tt> produces: 1055 Gnumeric. 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> 1070 foo.sgml 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 1088 up control codes. 1089 </p><p> 1090 To mark up a combination of keystrokes, use the 1091 <tt><keycombo></tt> wrapper: 1092 <pre class="programlisting"> 1093 1094<keycombo> 1095 <keycap>Ctrl</keycap> 1096 <keycap>Alt</keycap> 1097 <keycap>F1</keycap> 1098</keycombo> 1099 </pre> 1100 </p><p> 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"> 1104 1105<menuchoice> 1106 <shortcut> 1107 <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo> 1108 </shortcut> 1109 <guimenuitem> Quit</guimenuitem> 1110</menuchoice> 1111 </pre> 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>) 1119 </pre> 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 1123 in html version. 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 1131 is required. 1132 </p><p> 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 1160 example. 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"> 1165 1166<sect1 id="intro"> 1167 <title>Introduction</title> 1168 <para> 1169 blah-blah-blah This document describes version 1.0.53 of gfoo. 1170 </para> 1171</sect1> 1172 </pre> 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>. 1224 </p></div><p> 1225 Application manuals should be made available by having a 1226 "Manual" entry in the Help pull-down menu 1227 at the top of the 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. 1234 </p></div><p> 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"> 1241One line for each 'topic'. 1242 1243Two columns, as defined by perl -e 'split(/\s+/,$aline,2)' 1244 1245First column is the HTML file (and optional section) for the topic, 1246relative to the app's help file dir. 1247 1248Second column is the user-visible topic name. 1249 </pre> 1250 For example, Gnumeric's 1251 <tt>topic.dat</tt> file is: 1252 <pre class="programlisting"> 1253gnumeric.html Gnumeric manual 1254function-reference.html Gnumeric function reference 1255 </pre> 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. 1266 </p></div><p> 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"> 1271GnomeUIInfo helpmenu[] = { 1272 {GNOME_APP_UI_ITEM, 1273 N_("About"), N_("Info about this program"), 1274 about_cb, NULL, NULL, 1275 GNOME_APP_PIXMAP_STOCK, GNOME_STOCK_MENU_ABOUT, 1276 0, 0, NULL}, 1277 GNOMEUIINFO_SEPARATOR, 1278 GNOMEUIINFO_HELP("<i>appname</i>"), 1279 GNOMEUIINFO_END 1280 }; 1281</pre> 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. 1292 </p></div><p> 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. 1304 </p><p> 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"> 1308gchar *tmp; 1309tmp = gnome_help_file_find_file ("module", "page.html"); 1310if (tmp) { 1311 gnome_help_goto(0, tmp); 1312 g_free(tmp); 1313} 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 1327 distribution. Telsa 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. 1334 </p><p> 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). 1338 </p><p> 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. 1354 </p></div><p> 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. 1360 </p><p> 1361 To add an applet's manual to its applet menu, use: 1362<pre class="programlisting"> 1363/* add an item to the applet menu */ 1364applet_widget_register_callback(APPLET_WIDGET(applet), "manual", 1365_("Manual"), &open_manual, NULL); 1366</pre> 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. 1371 </p><p> 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>. 1376 </p><p> 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"> 1381applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about", 1382 GNOME_STOCK_MENU_ABOUT, _("About"), &my_applet_cb_about, 1383 NULL); 1384</pre> 1385 </p><p> 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. 1392 </p><p> 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 1396 work. 1397 </p><p> 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. 1405 </p><p> 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. 1409 </p><p> 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. 1435 </p><p> 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 1441 features at random. 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 1474 allusions or puns. 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. 1499 </p><p> 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 1507 the issue at hand. 1508 </p><p> 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. 1526 </p><p> 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 1531 least as helpful. 1532 </p><p> 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>. 1550 </p><p> 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 1585 by the developers. 1586 </p><p> 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. 1593 </p><p> 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. 1596 </p><p> 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> 1605 </a> 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 1617 irc.gnome.org. 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"> 1624 1625 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"[ 1629 --> 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) --> 1633]> 1634 1635 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 1641 unchanged. 1642 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! ;-) 1646 --> 1647 1648<!-- =============Document Header ============================= --> 1649 1650<article id="index"> <!-- please do not change the id --> 1651 1652 <artheader> 1653 <title>MY-GNOME-APP</title> 1654 <copyright> 1655 <year>2000</year> 1656 <holder>ME-THE-AUTHOR</holder> 1657 </copyright> 1658 1659 <!-- translators: uncomment this: 1660 1661 <copyright> 1662 <year>2000</year> 1663 <holder>ME-THE-TRANSLATOR (Latin translation)</holder> 1664 </copyright> 1665 1666 --> 1667 1668 <!-- do not put authorname in the header except in copyright - use 1669 section "authors" below --> 1670 1671 <legalnotice> 1672 <para> 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. 1684 </para> 1685 <para> 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. 1691 </para> 1692 </legalnotice> 1693 1694 <!-- this is the version of manual, not application --> 1695 <releaseinfo> 1696 This is version 1.0 of MY-GNOME-APP manual. 1697 </releaseinfo> 1698 1699 </artheader> 1700 1701 <!-- ============= Document Body ============================= --> 1702 1703 <!-- ============= Introduction ============================== --> 1704 <sect1 id="intro"> 1705 <title>Introduction</title> 1706 1707 <para> 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. 1717 </para> 1718 <para> 1719 It also allows you to save and print theorem proofs and to add 1720 comments to the proofs it produces. 1721 </para> 1722 1723 <para> 1724 To run <application>MY-GNOME-APP</application>, select 1725 <menuchoice> 1726 <guisubmenu>SUBMENU</guisubmenu> 1727 <guimenuitem>MY-GNOME-APP</guimenuitem> 1728 </menuchoice> 1729 from the <guimenu>Main Menu</guimenu>, or type 1730 <command>MYGNOMEAPP</command> on the command line. 1731 </para> 1732 1733 <para> 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>. 1738 </para> 1739 </sect1> 1740 1741 1742 <!-- ================ Usage ================================ --> 1743 <!-- This section should describe basic usage of the application. --> 1744 1745 <sect1 id="usage"> 1746 <title>Using MY-GNOME-APP</title> 1747 <para> 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>. 1754 </para> 1755 1756 <!-- ========= Basic Usage =========================== --> 1757 <sect2 id="mainwin"> 1758 <title>Basic usage</title> 1759 <para> 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. 1763 1764 <!-- ==== Figure ==== --> 1765 <figure id="mainwindow-fig"> 1766 <title>MY-GNOME-APP Main Window</title> 1767 <screenshot> 1768 <screeninfo>MY-GNOME-APP Main Window</screeninfo> 1769 <graphic fileref="SCREENSHOT" format="png" srccredit="ME"> 1770 </graphic> 1771 </screenshot> 1772 </figure> 1773 <!-- ==== End of Figure ==== --> 1774 </para> 1775 1776 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 1781 call. --> 1782 1783 <sect3 id="proving"> 1784 <title>Proving a Theorem</title> 1785 <para> 1786 To get a proof of a theorem, select 1787 <menuchoice> 1788 <guisubmenu>File</guisubmenu> 1789 <guimenuitem>New</guimenuitem> 1790 </menuchoice>, 1791 which will 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>. 1797 </para> 1798 <para> 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: 1805 1806 <variablelist> 1807 <varlistentry> 1808 <term>Deduction</term> 1809 <listitem> 1810 <para> 1811 This is a proof method that is generally accepted 1812 for full credit by Logic professors. 1813 </para> 1814 </listitem> 1815 </varlistentry> 1816 <varlistentry> 1817 <term>Induction</term> 1818 <listitem> 1819 <para> 1820 This logical style will also earn you full credit on 1821 your homework. 1822 </para> 1823 </listitem> 1824 </varlistentry> 1825 <varlistentry> 1826 <term>Dialog</term> 1827 <listitem> 1828 <para> 1829 This logical method is best for Philosophy classes, 1830 and will probably only merit partial credit on Logic 1831 or Mathematics homework. 1832 </para> 1833 </listitem> 1834 </varlistentry> 1835 <varlistentry> 1836 <term>Confusion</term> 1837 <listitem> 1838 <para> 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. 1842 </para> 1843 </listitem> 1844 </varlistentry> 1845 </variablelist> 1846 </para> 1847 1848 <!-- You might want to include a note, warning, or tip, e.g. --> 1849 1850 <warning> 1851 <title>Proving Incorrect Theorms</title> 1852 <para> 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 1858 logical inverse. 1859 </para> 1860 </warning> 1861 </sect3> 1862 <sect3 id="editing"> 1863 <title>Editing Proofs</title> 1864 <para> 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 1869 that process. 1870 </para> 1871 <para> 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 1878 text to that style. 1879 </para> 1880 <para> 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. 1884 </para> 1885 1886 <note> 1887 <title>Altering The Proofs Themselves</title> 1888 <para> 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. 1897 </para> 1898 </note> 1899 </sect3> 1900 1901 1902 <!-- If there are other functions performed from the main window, 1903 they belong here. --> 1904 1905 </sect2> 1906 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 1911 structure logical. 1912 ============================================================= --> 1913 1914 1915 <sect2 id="toolbar"> 1916 <title>Toolbar</title> 1917 <para> 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> 1922 <screenshot> 1923 <screeninfo>MY-GNOME-APP Toolbar</screeninfo> 1924 <graphic fileref="usage-toolbar.png" format="png"></graphic> 1925 </screenshot> 1926 </figure> 1927 <variablelist> 1928 <varlistentry> 1929 <term>New</term> 1930 <listitem> 1931 <para> 1932 Brings up the <interface>New Theorem</interface> 1933 dialog. 1934 </para> 1935 </listitem> 1936 </varlistentry> 1937 <varlistentry> 1938 <term>Open</term> 1939 <listitem> 1940 <para> 1941 Open an exisiting theorem you want to prove, or a 1942 completed proof you wish to print or format. 1943 </para> 1944 </listitem> 1945 </varlistentry> 1946 <varlistentry> 1947 <term>Save</term> 1948 <listitem> 1949 <para> 1950 Save the current theorem permanently in a 1951 file. 1952 </para> 1953 </listitem> 1954 </varlistentry> 1955 </variablelist> 1956 </para> 1957 </sect2> 1958 <!-- ========= Menus =========================== --> 1959 1960 <sect2 id="menubar"> 1961 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! --> 1966 1967 <title>Menus</title> 1968 <para> 1969 The menu bar, located at the top of the <interface>Main 1970 Window</interface>, contains the following menus: 1971 </para> 1972 <variablelist> 1973 <varlistentry> 1974 <term><guimenu>File</guimenu></term> 1975 <listitem> 1976 <para> 1977 This menu contains: 1978 <itemizedlist> 1979 <listitem> 1980 <para> 1981 <menuchoice> 1982 <shortcut> 1983 <keycap>F3</keycap> 1984 </shortcut> 1985 <guimenuitem>Open</guimenuitem> 1986 </menuchoice> 1987 &mdash; This opens a file which is saved on your computer. 1988 </para> 1989 </listitem> 1990 <listitem> 1991 <para> 1992 <menuchoice> 1993 <shortcut> 1994 <keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo> 1995 </shortcut> 1996 <guimenuitem>Save</guimenuitem> 1997 </menuchoice> 1998 &mdash; This saves your file. 1999 </para> 2000 </listitem> 2001 <listitem> 2002 <para> 2003 <menuchoice> 2004 <shortcut> 2005 <keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo> 2006 </shortcut> 2007 <guimenuitem>Close</guimenuitem> 2008 </menuchoice> 2009 &mdash; This closes your file. 2010 </para> 2011 </listitem> 2012 <listitem> 2013 <para> 2014 <menuchoice> 2015 <shortcut> 2016 <keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo> 2017 </shortcut> 2018 <guimenuitem>Exit</guimenuitem> 2019 </menuchoice> 2020 &mdash; This quits the application. 2021 </para> 2022 </listitem> 2023 </itemizedlist> 2024 </para> 2025 </listitem> 2026 </varlistentry> 2027 2028 <varlistentry> 2029 <term><guimenu>Edit</guimenu></term> 2030 <listitem> 2031 <para> 2032 This menu contains: 2033 <itemizedlist> 2034 <listitem> 2035 <para> 2036 <menuchoice> 2037 <shortcut> 2038 <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo> 2039 </shortcut> 2040 <guimenuitem>Cut</guimenuitem> 2041 </menuchoice> 2042 &mdash; This removes any text or data which is selected and 2043 places it in the buffer. 2044 </para> 2045 </listitem> 2046 <listitem> 2047 <para> 2048 <menuchoice> 2049 <shortcut> 2050 <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> 2051 </shortcut> 2052 <guimenuitem>Copy</guimenuitem> 2053 </menuchoice> 2054 &mdash; This copies any text or data which is selected into 2055 the buffer. 2056 </para> 2057 </listitem> 2058 <listitem> 2059 <para> 2060 <menuchoice> 2061 <shortcut> 2062 <keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo> 2063 </shortcut> 2064 <guimenuitem>Paste</guimenuitem> 2065 </menuchoice> 2066 &mdash; This pastes any text or data which is copied into 2067 the buffer. 2068 </para> 2069 </listitem> 2070 <listitem> 2071 <para> 2072 <guimenuitem>COMMAND1&hellip;</guimenuitem> 2073 &mdash; This opens the <interface>COMMAND1</interface> 2074 dialog, which is used to .... 2075 </para> 2076 </listitem> 2077 <listitem> 2078 <para> 2079 <guimenuitem>COMMAND2</guimenuitem> 2080 &mdash; This .... 2081 </para> 2082 </listitem> 2083 </itemizedlist> 2084 </para> 2085 </listitem> 2086 </varlistentry> 2087 2088 2089 <varlistentry> 2090 <term><guimenu>Settings</guimenu></term> 2091 <listitem> 2092 <para> 2093 This menu contains: 2094 <itemizedlist> 2095 <listitem> 2096 <para> 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 2101 many settings. 2102 </para> 2103 </listitem> 2104 <listitem> 2105 <para> 2106 <guimenuitem>COMMAND3</guimenuitem> &mdash; 2107 This command does something. 2108 </para> 2109 </listitem> 2110 </itemizedlist> 2111 </para> 2112 </listitem> 2113 </varlistentry> 2114 2115 <varlistentry> 2116 <term><guimenu>Help</guimenu></term> 2117 <listitem> 2118 <para> 2119 This menu contains: 2120 <itemizedlist> 2121 <listitem> 2122 <para> 2123 <guimenuitem>Manual</guimenuitem> &mdash; This 2124 opens the <application>GNOME Help 2125 Browser</application> and displays this manual. 2126 </para> 2127 </listitem> 2128 2129 <listitem> 2130 <para> 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 2137 exists. 2138 </para> 2139 </listitem> 2140 </itemizedlist> 2141 </para> 2142 </listitem> 2143 </varlistentry> 2144 </variablelist> 2145 </sect2> 2146 </sect1> 2147 2148 2149 2150 <!-- ============= Customization ============================= --> 2151 2152 <sect1 id="prefs"> 2153 <title>Customization</title> 2154 <para> 2155 To change the application settings, select 2156 <menuchoice> 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">. 2162 </para> 2163 2164 <figure id="preferences-fig"> 2165 <title>Preferences Dialog</title> 2166 <screenshot> 2167 <screeninfo>Preferences Dialog</screeninfo> 2168 <graphic fileref="SCREENSHOT" format="png" 2169 srccredit="ME"> 2170 </graphic> 2171 </screenshot> 2172 </figure> 2173 2174 <para> 2175 The properties in the <guilabel>PREFSTABNAME</guilabel> tab are: 2176 2177 <!--many people use itemizedlists in cases like this. Variablelists 2178 are more appropriate --> 2179 2180 <variablelist> 2181 <varlistentry> 2182 <term> <guilabel>Default Text Style</guilabel></term> 2183 <listitem> 2184 <para> 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. 2188 </para> 2189 </listitem> 2190 </varlistentry> 2191 <varlistentry> 2192 <term>(Configuration Item Label)</term> 2193 <listitem> 2194 <para> 2195 (Description of Configuration) 2196 </para> 2197 </listitem> 2198 </varlistentry> 2199 <varlistentry> 2200 <term>(Configuration Item Label)</term> 2201 <listitem> 2202 <para> 2203 (Description of Configuration) 2204 </para> 2205 </listitem> 2206 </varlistentry> 2207 </variablelist> 2208 </para> 2209 2210 <para> 2211 The properties in the <guilabel>SECONDTABNAME</guilabel> tab are: 2212 <variablelist> 2213 <varlistentry> 2214 <term>(Configuration Item Label)</term> 2215 <listitem> 2216 <para> 2217 (Description of Configuration) 2218 </para> 2219 </listitem> 2220 </varlistentry> 2221 <varlistentry> 2222 <term>(Configuration Item Label)</term> 2223 <listitem> 2224 <para> 2225 (Description of Configuration) 2226 </para> 2227 </listitem> 2228 </varlistentry> 2229 </variablelist> 2230 </para> 2231 2232 <para> 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. 2238 </para> 2239 2240 </sect1> 2241 2242 2243 <!-- ============= Various Sections ============================= --> 2244 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. --> 2249 2250 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> 2257 <para> 2258 This application has no known bugs. 2259 </para> 2260 </sect1> 2261 2262 2263<!-- ============= Authors ================================ --> 2264 2265 <sect1 id="authors"> 2266 <title>Authors</title> 2267 <para> 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. 2281 </para> 2282 2283 <para> 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>. 2293 </para> 2294 2295 <!-- For translations: uncomment this: 2296 2297 <para> 2298 Latin translation was done by ME 2299 (<email>MYNAME@MYADDRESS</email>). Please send all comments and 2300 suggestions regarding this translation to SOMEWHERE. 2301 </para> 2302 2303 --> 2304 2305 </sect1> 2306 2307 2308 <!-- ============= Application License ============================= --> 2309 2310 <sect1 id="license"> 2311 <title>License</title> 2312 <para> 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 2317 version. 2318 </para> 2319 <para> 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. 2324 </para> 2325 <para> 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 2332 <address> 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> 2337 </address> 2338 </para> 2339 </sect1> 2340</article> 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353</pre> 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>, 2364 where 2365 <tt><i><tt>appletname</tt></i></tt> is 2366 the name of the applet. 2367 <pre class="programlisting"> 2368 2369 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) --> 2373]> 2374 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. 2382 2383 Please don't forget to remove these comments in your final documentation, 2384 thanks ;-). 2385--> 2386 2387<article id="index"> <!-- please do not change the id --> 2388 2389 <!-- ============= Document Header ============================= --> 2390 <artheader> 2391 <title>APPLETNAME Applet</title> 2392 <copyright> 2393 <year>2000</year> 2394 <holder>YOURFULLNAME</holder> 2395 </copyright> 2396 2397 <!-- translators: uncomment this: 2398 2399 <copyright> 2400 <year>2000</year> 2401 <holder>ME-THE-TRANSLATOR (Latin translation)</holder> 2402 </copyright> 2403 2404 --> 2405 2406 <!-- do not put authorname in the header except in copyright - use 2407 section "authors" below --> 2408 2409 <legalnotice> 2410 <para> 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. 2421 </para> 2422 <para> 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 2427 or initial caps. 2428 </para> 2429 </legalnotice> 2430 2431 <releaseinfo> 2432 This is version XXX of the APPLETNAME applet manual. 2433 </releaseinfo> 2434 </artheader> 2435 2436 <!-- ============= Document Body ============================= --> 2437 2438 &APPLETNAME.sgml; 2439 2440</article> 2441 2442 2443 2444 2445 2446</pre> 2447 <pre class="programlisting"> 2448 2449 <!-- Template Version: 1.0.1 (do not remove this line) --> 2450 2451 <sect1 id="APPLET"> 2452 <title>APPLET Applet</title> 2453 2454 <para> 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 2459 <menuchoice> 2460 <guimenu>Panel</guimenu> 2461 <guisubmenu>Add to panel</guisubmenu> 2462 <guisubmenu>Applet</guisubmenu> 2463 <guisubmenu>SECTION</guisubmenu> 2464 <guimenuitem>APPLET</guimenuitem> 2465 </menuchoice>. 2466 </para> 2467 2468 <figure id="APPLETapplet-fig"> 2469 <title>APPLET Applet</title> 2470 <screenshot> 2471 <screeninfo>APPLET Applet</screeninfo> 2472 <graphic format="png" fileref="APPLET_applet" 2473 srccredit="YOURNAME"> 2474 </graphic> 2475 </screenshot> 2476 </figure> 2477 2478 <!-- ============= Usage ================================ --> 2479 <sect2 id="APPLET-usage"> 2480 <title>Usage</title> 2481 <para> 2482 (Place a short description of how to use the applet here.) 2483 </para> 2484 2485 <para> 2486 Right-clicking on the applet brings up a menu containing the 2487 following items: 2488 <itemizedlist> 2489 2490 <listitem> 2491 <para> 2492 <guimenuitem>Properties&hellip;</guimenuitem> &mdash; 2493 opens the <link linkend="APPLET-prefs"> 2494 <guilabel>Properties</guilabel></link> dialog. 2495 </para> 2496 </listitem> 2497 2498 <listitem> 2499 <para> 2500 <guimenuitem>Help</guimenuitem> &mdash; 2501 displays this document. 2502 </para> 2503 </listitem> 2504 2505 <listitem> 2506 <para> 2507 <guimenuitem>About&hellip;</guimenuitem> &mdash; 2508 shows basic information about <application>APPLET 2509 Applet</application>, including the applet's version and the 2510 author's name. 2511 </para> 2512 </listitem> 2513 2514 </itemizedlist> 2515 </para> 2516 </sect2> 2517 2518 2519 <!-- ============= Customization ============================= --> 2520 <sect2 id="APPLET-prefs"> 2521 <title>Customization</title> 2522 <para> 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. 2529 </para> 2530 2531 <figure id="APPLET-settings-fig"> 2532 <title>Properties dialog</title> 2533 <screenshot> 2534 <screeninfo>Properties dialog</screeninfo> 2535 <graphic format="png" fileref="APPLET_settings" 2536 srccredit="YOURNAME"> 2537 </graphic> 2538 </screenshot> 2539 </figure> 2540 2541 <para> 2542 The properties are: 2543 <itemizedlist> 2544 2545 <listitem> 2546 <para> 2547 (Configuration Item Label) &mdash; If this button is 2548 checked&hellip;(description) 2549 </para> 2550 </listitem> 2551 2552 <listitem> 2553 <para> 2554 (Configuration Item Label) &mdash; Selecting this 2555 button&hellip;(description) 2556 </para> 2557 </listitem> 2558 2559 <listitem> 2560 <para> 2561 (Configuration Item Label) &mdash; Enter the name of 2562 &hellip;(description) 2563 </para> 2564 </listitem> 2565 </itemizedlist> 2566 </para> 2567 2568 <para> 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. 2574 </para> 2575 </sect2> 2576 2577 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> 2584 <para> 2585 This applet has no known bugs. 2586 </para> 2587 </sect2> 2588 2589 2590 <!-- ============= Authors ================================ --> 2591 2592 <sect2 id="authors"> 2593 <title>Authors</title> 2594 <para> 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. 2606 </para> 2607 2608 <para> 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>. 2618 </para> 2619 2620 <!-- For translations: uncomment this: 2621 2622 <para> 2623 Latin translation was done by ME 2624 (<email>MYNAME@MYADDRESS</email>). Please send all comments and 2625 suggestions regarding this translation to SOMEWHERE. 2626 </para> 2627 2628 --> 2629 2630 </sect2> 2631 2632 2633 <!-- ============= Application License ============================= --> 2634 2635 <sect2 id="license"> 2636 <title>License</title> 2637 <para> 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 2642 version. 2643 </para> 2644 <para> 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. 2649 </para> 2650 <para> 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 2657 <address> 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> 2662 </address> 2663 </para> 2664 </sect2> 2665 2666 </sect1> 2667 2668 2669 2670 2671 2672 2673 2674 2675</pre> 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>. 2681 </p><p> 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. 2693 </p><p> 2694 <pre class="programlisting"> 2695 2696<!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[ 2697<!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part"> 2698 2699]> 2700 2701<book id="gnome-applets"> 2702 2703 <bookinfo> 2704 <title>GNOME Applets</title> 2705 <authorgroup> 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> 2710 </author> 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> 2716 <copyright> 2717 <year>2000</year> 2718 <holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and 2719 Alexander Kirillov</holder> 2720 </copyright> 2721 <legalnotice> 2722 <para> 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. 2726 </para> 2727 <para> 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. 2732 </para> 2733 <para> 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. 2738 </para> 2739 <para> 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 2744 or initial caps. 2745 </para> 2746 </legalnotice> 2747 </bookinfo> 2748 2749 <!-- #### Introduction ###### --> 2750 <chapter id="applets-intro"> 2751 <title>Introduction</title> 2752 2753 <!-- #### Intro | What Are Applets? ###### --> 2754 <sect1 id="applets-what-are"> 2755 <title>What Are Applets?</title> 2756 <para> 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>). 2770 </para> 2771 2772 <para> 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. 2783 </para> 2784 2785 <para> 2786 <figure id="example-applets-fig"> 2787 <title>Example Applets</title> 2788 <screenshot> 2789 <screeninfo>Example Applets</screeninfo> 2790 <graphic fileref="example_applets" format="png" 2791 srccredit="muet"> 2792 </graphic> 2793 </screenshot> 2794 </figure> 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. 2810 </para> 2811 <para> 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 2821 and applets. 2822 </para> 2823 <para> 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. 2827 </para> 2828 </sect1> 2829 2830 <!-- #### Intro | Adding, Moving, and Removing Applets ###### --> 2831 <sect1 id="applet-add-move-replace"> 2832 <title>Adding, Moving, and Removing Applets</title> 2833 2834 <sect2 id="adding-applets"> 2835 <title>Adding Applets to a Panel</title> 2836 <para> 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>. 2844 </para> 2845 </sect2> 2846 2847 <sect2 id="moving-applets"> 2848 <title>Moving Applets In or Between Panels</title> 2849 <para> 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. 2873 </para> 2874 <para> 2875 To change the global Panel preferences, right-click on any applet 2876 or <interface>Panel</interface> and select 2877 <menuchoice> 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. 2883 </para> 2884 </sect2> 2885 2886 <sect2 id="removing-applets"> 2887 <title>Removing Applets from a Panel</title> 2888 <para> 2889 To remove an applet from a <interface>Panel</interface>, 2890 right-click on the applet and select <guimenuitem>Remove from 2891 panel...</guimenuitem>. 2892 </para> 2893 </sect2> 2894 </sect1> 2895 2896 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> 2900 <para> 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 2905 applet. 2906 </para> 2907 <sect2 id="standard-right-click-items"> 2908 <title>Standard Pop-Up Items</title> 2909 <para> 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> 2915 <listitem> 2916 <para> 2917 The <guimenuitem>Remove from panel</guimenuitem> menu item 2918 removes the applet from the <interface>Panel</interface>. 2919 </para> 2920 </listitem> 2921 </varlistentry> 2922 2923 <varlistentry> 2924 <term>Move</term> 2925 <listitem> 2926 <para> 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. 2934 </para> 2935 </listitem> 2936 </varlistentry> 2937 2938 <varlistentry> 2939 <term>Panel</term> 2940 <listitem> 2941 <para> 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 2945 the configuration. 2946 </para> 2947 </listitem> 2948 </varlistentry> 2949 2950 <varlistentry> 2951 <term>About</term> 2952 <listitem> 2953 <para> 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. 2958 </para> 2959 </listitem> 2960 </varlistentry> 2961 2962 <varlistentry> 2963 <term>Help</term> 2964 <listitem> 2965 <para> 2966 The <guimenuitem>Help</guimenuitem> menu item brings up the help 2967 manual for the applet. 2968 </para> 2969 </listitem> 2970 </varlistentry> 2971 </variablelist> 2972 </para> 2973 </sect2> 2974 2975 <sect2 id="applet-properties-dialog"> 2976 <title>The Applet Properties Dialog</title> 2977 <para> 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> 2985 <screenshot> 2986 <screeninfo>An Example Applets Properties Dialog</screeninfo> 2987 <graphic fileref="applet_props_dialog" format="png" 2988 srccredit="muet"> 2989 </graphic> 2990 </screenshot> 2991 </figure> 2992 All <interface>Properties</interface> dialogs have the following 2993 buttons at the bottom of the dialog: 2994 <itemizedlist> 2995 <listitem> 2996 <para> 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. 3001 </para> 3002 </listitem> 3003 <listitem> 3004 <para> 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. 3011 </para> 3012 </listitem> 3013 <listitem> 3014 <para> 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. 3021 </para> 3022 </listitem> 3023 <listitem> 3024 <para> 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. 3029 </para> 3030 </listitem> 3031 </itemizedlist> 3032 </para> 3033 </sect2> 3034 3035 <sect2 id="common-right-click-items"> 3036 <title>Other Common Pop-Up Items</title> 3037 <para> 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> 3043 <listitem> 3044 <para> 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 3048 panel. For example: 3049 </para> 3050 <orderedlist> 3051 <listitem> 3052 <para> 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. 3058 </para> 3059 </listitem> 3060 <listitem> 3061 <para> 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. 3066 </para> 3067 </listitem> 3068 </orderedlist> 3069 </listitem> 3070 </varlistentry> 3071 </variablelist> 3072 </para> 3073 </sect2> 3074 </sect1> 3075 3076 <sect1 id="feedback"> 3077 <title>Feedback</title> 3078 <sect2 id="reporting-bugs"> 3079 <title>Reporting Applet Bugs</title> 3080 <para> 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 3085 <menuchoice> 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. 3092 </para> 3093 </sect2> 3094 <sect2 id="documentation-feedback"> 3095 <title>Providing Feedback</title> 3096 <para> 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>. 3105 </para> 3106 </sect2> 3107 <sect2 id="joining-gnome"> 3108 <title>Joining GNOME</title> 3109 <para> 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. 3125 </para> 3126 </sect2> 3127 </sect1> 3128 </chapter> 3129 3130 <!-- ############### Template Applets ##################### --> 3131 <chapter id="template-applets"> 3132 <title>Template Applets</title> 3133 3134 &TEMPLATE-APPLET 3135 3136 </chapter> 3137 3138</book> 3139 3140 3141 3142 3143 3144 3145 3146 3147 </pre> 3148 3149 <pre class="programlisting"> 3150 3151 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 --> 3159 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 --> 3163 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.--> 3167 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. --> 3171 <!-- --> 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. --> 3176 <!-- --> 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. --> 3181 3182 <!-- ############### GNOMEAPPLET ############### --> 3183 <sect1 id="GNOMEAPPLET"> 3184 <title>GNOMEAPPLET Applet</title> 3185 3186 <para> 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">. 3191 </para> 3192 3193 3194 <figure id="GNOMEAPPLET-fig"> 3195 <title>GNOMEAPPLET</title> 3196 <screenshot> 3197 <screeninfo>GNOMEAPPLET</screeninfo> 3198 <graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME"> 3199 </graphic> 3200 </screenshot> 3201 </figure> 3202 3203 <sect2 id="GNOMEAPPLET-usage"> 3204 <title>Usage</title> 3205 <para> 3206 This applet does nothing. To use it, just 3207 left-click on it and it will instantly do nothing. 3208 </para> 3209 </sect2> 3210 3211 <sect2 id="GNOMEAPPLET-right-click"> 3212 <title>Right-Click Pop-Up Menu Items</title> 3213 <para> 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> 3218 <listitem> 3219 <para> 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. 3224 </para> 3225 </listitem> 3226 <listitem> 3227 <para> 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. 3231 </para> 3232 </listitem> 3233 </itemizedlist> 3234 </para> 3235 </sect2> 3236 3237 <sect2 id="GNOMEAPPLET-properties"> 3238 <title>Properties</title> 3239 <para> 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">. 3245 </para> 3246 <figure id="GNOMEAPPLET-properties-fig"> 3247 <title>Properties Dialog</title> 3248 <screenshot> 3249 <screeninfo>Properties Dialog</screeninfo> 3250 <graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME"> 3251 </graphic> 3252 </screenshot> 3253 </figure> 3254 3255 <para> 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. 3259 </para> 3260 3261 <para> 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">. 3267 </para> 3268 </sect2> 3269 3270 <sect2 id="GNOMEAPPLET-bugs"> 3271 <title> Known Bugs and Limitations</title> 3272 <para> 3273 There are no known bugs in the 3274 <application>GNOMEAPPLET</application> applet. 3275 </para> 3276 </sect2> 3277 3278 <sect2 id="GNOMEAPPLET-authors"> 3279 <title>Authors</title> 3280 <para> 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">. 3287 </para> 3288 </sect2> 3289 3290 </sect1> 3291 3292 3293 3294 3295 3296 3297 3298 3299</pre> 3300 </p></div></div></div></body></html> 3301
