1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><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"></a>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> 2������������<tt><<a href="mailto:dcm@redhat.com">dcm@redhat.com</a>></tt><br> 3����������</div></div><h3 class="author">Daniel Mueth</h3><div class="affiliation"><div class="address"><br> 4������������<tt><<a href="mailto:d-mueth@uchicago.edu">d-mueth@uchicago.edu</a>></tt><br> 5����������</div></div><h3 class="author">Alexander Kirillov</h3><div class="affiliation"><div class="address"><br> 6������������<tt><<a href="mailto:kirillov@math.sunysb.edu">kirillov@math.sunysb.edu</a>></tt><br> 7����������</div></div></div><div><p class="releaseinfo"> 8 This is a pre-release! 9 </p></div><div><p class="copyright">Copyright � 2000 Red Hat, Inc., Daniel Mueth, and Alexander Kirillov</p></div><div><div class="legalnotice"><p> 10 Permission is granted to copy, distribute and/or modify this 11 document under the terms of the <i>GNU Free Documentation 12 License</i>, Version 1.1 or any later version published 13 by the Free Software Foundation with no Invariant Sections, no 14 Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy 15 of the <i>GNU Free Documentation License</i> from 16 the Free Software Foundation by visiting <a href="http://www.fsf.org" target="_top">their Web site</a> or by writing to: 17 Free Software Foundation, Inc., 59 Temple Place - Suite 330, 18 Boston, MA 02111-1307, USA. 19 </p><p> 20 Many of the names used by companies to distinguish their products and 21 services are claimed as trademarks. Where those names appear in any 22 GNOME documentation, and those trademarks are made aware to the members 23 of the GNOME Documentation Project, the names have been printed in caps 24 or initial caps. 25 </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 26 0.99 27 </td><td align="left"> 28 04.10.2000 29 </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 30 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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="intro"></a>Introduction</h2></div></div><div class="sect2"><a name="gdp"></a><div class="titlepage"><div><h3 class="title"><a name="gdp"></a>The GNOME Documentation Project</h3></div></div><div class="sect3"><a name="goals"></a><div class="titlepage"><div><h4 class="title"><a name="goals"></a>Goals</h4></div></div><p> 31 The GNOME Documentation Project (GDP) aims to provide GNOME 32 and GNOME applications with a complete, intuitive, and clear 33 documentation system. At the center of the GDP is the 34 GNOME Help Browser, which 35 presents a unified interface to GNOME-specific documentation 36 as well as other Linux documentation such as man pages and 37 texinfo documents. The GNOME Help System provides a 38 comprehensive view of documentation on a machine by 39 dynamically assembling the documentation of GNOME 40 applications and components which are installed. The GDP is 41 responsible for writing numerous GNOME-related documents, 42 both for developers and for users. Developer documentation 43 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 44 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 45 FAQ</i></a>, the <a href="http://developer.gnome.org" target="_top">GNOME 46 Developer's Website</a>, and <i>GNOME 47 Handbook</i>'s, such as the one you are reading. 48 User documentation include the <a href="http://www.gnome.org/learn/" target="_top"><i>GNOME User's 49 Guide</i></a>, the <a href="http://www.gnome.org/learn/" target="_top"><i>GNOME FAQ</i></a>, and 50 GNOME application documentation. Most GNOME applications 51 have their own manual in addition to context sensitive help. 52 </p></div><div class="sect3"><a name="joining"></a><div class="titlepage"><div><h4 class="title"><a name="joining"></a>Joining the GDP</h4></div></div><p> 53 Documenting GNOME and all the numerous GNOME applications is 54 a very large project. The GDP is always looking for people 55 to help write, update, and edit documentation. If you are 56 interested in joining the GDP team, you should join the 57 <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top"> 58 <i>gnome-doc-list mailing list</i> </a>. 59 Read <a href="#gettingstarted" title="Getting Started Writing GNOME Documentation">the section called “Getting Started Writing GNOME Documentation”</a>, for help selecting a 60 project to work on. Feel free to introduce yourself on the 61 gnome-doc-list mailing list and indicate which project you 62 intend to work on, or else ask for suggestions of important 63 documents which need work done. You may also want to join the 64 #docs IRC channel on irc.gnome.org to meet other GDP members 65 and discuss any questions you may have. For a list of GDP 66 projects and members, see the 67 <a href="http://developer.gnome.org/projects/gdp" target="_top"> 68 <i>GDP Website</i></a>. 69 </p></div><div class="sect3"><a name="collaborating"></a><div class="titlepage"><div><h4 class="title"><a name="collaborating"></a>Collaborating with the GDP</h4></div></div><p> 70 GNOME developers, packagers, and translators may not be 71 writing GNOME documentation but will want to understand how 72 the GNOME documentation system works and will need to 73 collaborate with GDP members. This document should help to 74 outline the structure of how the GNOME documentation system 75 works. Developers who do not write the documentation for 76 their applications are encouraged to find a GDP member to 77 write the documentation. This is best done by sending an 78 email to the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top"> 79 <i>gnome-doc-list mailing list</i> </a> 80 describing the application, where it can be downloaded from, 81 and that the developer(s) would like a GDP member to write 82 documentation for the application. The #docs IRC channel on 83 irc.gnome.org is another option for contacting GDP members. 84 </p></div></div><div class="sect2"><a name="notation"></a><div class="titlepage"><div><h3 class="title"><a name="notation"></a>Notation and Conventions</h3></div></div><p> 85 This Handbook uses the following notation: 86 <div class="informaltable" id="id2797678"><a name="id2797678"></a><table border="0"><colgroup><col><col></colgroup><tbody><tr><td><tt>/usr/bin</tt></td><td> 87 Directory 88 </td></tr><tr><td><tt>foo.sgml</tt></td><td> 89 Filename 90 </td></tr><tr><td><b>command</b></td><td> 91 Command or text that would be typed. 92 </td></tr><tr><td><b><i><tt>replaceable</tt></i></b></td><td> 93 "Variable" text that can be replaced. 94 </td></tr><tr><td><tt>Program or Doc Code</tt></td><td>Program or document code</td></tr></tbody></table></div> 95 </p></div><div class="sect2"><a name="about"></a><div class="titlepage"><div><h3 class="title"><a name="about"></a>About This Handbook</h3></div></div><p> 96 This Handbook is a guide for both writing documentation for 97 GNOME components and applications and for properly binding and 98 packaging documentation into GNOME applications. 99 </p><p> 100 This Handbook, like all GNOME documentation, was written in 101 DocBook(SGML) and is available in several formats including 102 SGML, HTML, PostScript, and PDF. For the latest version, see 103 <a href="http://developer.gnome.org/projects/gdp/handbook.html" target="_top"> 104 <i>Getting The GNOME Handbook of Writing Software 105 Documentation</i> </a>. Alternately, one may 106 download it anonymously from GNOME CVS under <tt>gnome-docu/gdp</tt>. 107 </p></div></div><div class="sect1"><a name="gettingstarted"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="gettingstarted"></a>Getting Started Writing GNOME Documentation</h2></div></div><div class="sect2"><a name="selecting"></a><div class="titlepage"><div><h3 class="title"><a name="selecting"></a>Selecting A Document</h3></div></div><div class="sect3"><a name="know"></a><div class="titlepage"><div><h4 class="title"><a name="know"></a>Document Something You Know</h4></div></div><p> 108 The most frequently asked question of new contributors who 109 join the GDP is "which document should I start 110 with?". Because most people involved are volunteers, we do 111 not <i>assign</i> projects and applications to 112 write documents for. The first step is all yours - you must 113 decide what about GNOME interests you most and find out if 114 it has complete documents or not. 115 </p><p> 116 It is also important to spend some time with GNOME to make 117 sure you are familiar enough with it to be 118 <i>authoritative</i> in your writing. The 119 best way to do this is to just sit down and play with GNOME 120 as much as possible before starting to write. 121 </p><p> 122 The easiest way to get started is to improve existing 123 documentation. If you notice some inaccuracies or omissions 124 in the documentation, or you think that you can explain the 125 material more clearly, just send your suggestions to the 126 author of the original documentation or to the GNOME 127 documentation project at <tt><<a href="mailto:docs@gnome.org">docs@gnome.org</a>></tt>. 128 </p></div><div class="sect3"><a name="doctable"></a><div class="titlepage"><div><h4 class="title"><a name="doctable"></a>The GNOME Documentation Status Table</h4></div></div><p> 129 The <i>GDP Documentation Status Table</i> 130 (<i>DocTable</i>) (<a href="http://www.gnome.org/gdp/doctable/" target="_top">http://www.gnome.org/gdp/doctable/</a>) is a 131 web page which tracks the status of all the various 132 documentation components of GNOME. These components include 133 application documentation, internal GNOME component 134 documentation, user documentation, and developer 135 documentation. For each documentation item, it tracks the 136 current status of the documentation, who is working on the 137 particular document, where the documentation can be found, 138 and provides a forum for the discussion of each item. 139 </p><p> 140 You should use the <i>DocTable</i> to help 141 you select a documentation item which needs work done. Once 142 you have selected an item to work on, please register 143 yourself as an author so that other authors do not duplicate 144 your work and may contact you to help or offer suggestions. 145 Also be sure to keep the status icons up-to-date so that 146 the GDP team can easily identify which items need additional 147 help. The <i>DocTable</i> also allows 148 people to make announcements and suggestions and to discuss 149 issues in the comments section. 150 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2795548"></a>Note</h3><p> 151 Note that the information in the 152 <i>DocTable</i> may not always be up-to-date 153 or accurate. When you assign yourself to documenting an 154 application, make sure you find out the latest status of 155 documentation by contacting the application author. 156 </p></div></div></div><div class="sect2"><a name="docbook"></a><div class="titlepage"><div><h3 class="title"><a name="docbook"></a>Installing and Using DocBook</h3></div></div><p> 157 All documentation for the GNOME project is written in SGML 158 using the DocBook DTD. There are many advantages to using 159 this for documentation, not least of which is the single 160 source nature of SGML. To contribute to the GDP you should 161 learn to use DocBook. 162 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2795631"></a>NOTE</h3><p> 163 To get started writing for the GDP you do not need to rush 164 out and learn DocBook - if you feel it is too much to handle 165 for now, you can submit plain ASCII text to the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top"> 166 <i>gnome-doc-list mailing list</i> 167 </a>and a volunteer will mark it up for you. Seeing your 168 document marked up will also be a great way for you to start 169 learning DocBook. 170 </p></div><div class="sect3"><a name="installingdocbook"></a><div class="titlepage"><div><h4 class="title"><a name="installingdocbook"></a>Installing DocBook</h4></div></div><p> 171 Download and install the following <a href="ftp://sourceware.cygnus.com:/pub/docbook-tools/" target="_top">DocBook Tools packages</a>: jade, docbook, 172 jadetex, sgml-common, and stylesheets. (RPM users should note 173 that jade is platform dependent (eg. i386), while the other packages 174 are in the <tt>noarch</tt> 175 directory.) You can find more 176 information on DocBook Tools <a href="http://sourceware.cygnus.com/docbook-tools/" target="_top">here</a>. 177 </p><p> 178 If you are an Emacs user you may 179 want to grab the psgml package as well. This is a major mode 180 for editing sgml files in Emacs. 181 </p></div><div class="sect3"><a name="gdpstylesheets"></a><div class="titlepage"><div><h4 class="title"><a name="gdpstylesheets"></a>GDP Stylesheets</h4></div></div><p> 182 The GDP uses its own DocBook stylesheets. To use the GDP 183 stylesheets, you should download the file 184 <tt>gdp-both.dsl</tt> from the <tt>gnome-docu/gdp/dsssl</tt> module in 185 CVS (or from <a href="http://developer.gnome.org/projects/gdp/stylesheets.html" target="_top"> 186 GDP Custom DSSSL Stylesheet</a>)and copy it 187 188 over the file 189 <tt>/usr/lib/sgml/stylesheets/cygnus-both.dsl</tt>. 190 Alternately, you can download and install the 191 <a href="http://people.redhat.com/dcm/software.html" target="_top">gnome-doc-tools package</a> which will set 192 up the stylesheets as well as the DTD discussed below. 193 </p></div><div class="sect3"><a name="gdpdtd"></a><div class="titlepage"><div><h4 class="title"><a name="gdpdtd"></a>GDP DTD (PNG Image Support)</h4></div></div><p> 194 Due to some license issues involved with the creation of 195 gifs, the GNOME Documentation Project has decided to use the 196 PNG image format for all images in GNOME documentation. You 197 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>. 198 </p><p> 199 The current DocBook DTD(3.1) does not include support for 200 embedding PNG images in your documents. Since the GDP uses 201 many screenshots in its documentation, we use our own 202 variation on the DocBook DTD which has PNG image support. 203 We encourage everybody to use this DTD instead of the 204 default DocBook DTD since your source document header and 205 your output document appearance subtly vary between the two 206 DTD's. To install the GDP custom DTD with PNG image support 207 by hand: 208 </p><div class="itemizedlist"><ul><li style="list-style-type: opencircle"><p><a name="id2796045"></a> 209 Download <a href="http://www.labs.redhat.com/png/png-support.html" target="_top">the 210 GDP DocBook DTD for PNG support</a> and install it 211 where you keep your DTD's. (On Red Hat use <tt>/usr/lib/sgml/</tt>.) Note that 212 the 3.0 DTD is missing support for the 213 <tt><legalnotice></tt> tag, so it is 214 recommended that you use version 3.1 215 </p></li><li style="list-style-type: disc"><p><a name="id2796107"></a> 216 Add the new DTD to your SGML CATALOG file. The location 217 of your SGML CATALOG file may vary depending upon your 218 distribution. (On Red Hat it is usually in 219 /usr/lib/sgml/CATALOG.) Add the following line to this 220 file: 221 <pre class="programlisting"> 222PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd" 223 </pre> 224 If you are using the 3.1 DTD, use: 225 <pre class="programlisting"> 226PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd" 227 </pre> 228 </p></li></ul></div><p> 229 Alternately, you can download and install the 230 <a href="http://people.redhat.com/dcm/software.html" target="_top">gnome-doc-tools package</a> which will set 231 up the custom stylesheets and DTD for you. 232 </p><p> 233 To include PNG files in your documents, you will need to 234 indicate that you are using this special DTD. To do 235 this, use the following headers: 236 </p><p> 237 Articles: 238 <pre class="programlisting"> 239<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant 240V1.1//EN"[]> 241 </pre> 242 </p><p> 243 Books: 244 <pre class="programlisting"> 245<!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant 246V1.1//EN"[]> 247 </pre> 248 </p></div><div class="sect3"><a name="editors"></a><div class="titlepage"><div><h4 class="title"><a name="editors"></a>Editors</h4></div></div><p> 249 There are many editors on Linux and UNIX systems available 250 to you. Which editor you use to work on the sgml documents 251 is completely up to you, as long as the editor is able to 252 preserve sgml and produce the source in a format that is 253 readable by everyone. 254 </p><p> 255 Probably the two most popular editors available are 256 Emacs and 257 vi. These and other editors are 258 used regularly by members of the GDP. Emacs has a major 259 mode, psgml, for editing sgml files which can save you time 260 and effort in adding and closing tags. You will find the 261 psgml package in DocBook Tools, which is the standard set of 262 tools for the GDP. You may find out more about DocBook Tools 263 in <a href="#installingdocbook" title="Installing DocBook">the section called “Installing DocBook”</a>. 264 </p></div><div class="sect3"><a name="make-output"></a><div class="titlepage"><div><h4 class="title"><a name="make-output"></a>Creating Something Useful with your Docs</h4></div></div><p> 265 The tools available in DocBook Tools allow you to convert 266 your sgml document to many different formats including html 267 and Postscript. The primary tool used to do the conversion 268 is an application called Jade. In 269 most cases you will not have to work directly with 270 Jade; Instead, you will use the 271 scripts provided by DocBook Tools. 272 </p><p> 273 To preview your DocBook document, it is easiest to convert 274 it to <tt>html</tt>. If you have installed the 275 DocBook tools described above, all you have to do is to run 276 the command <tt>$</tt><b>db2html 277 mydocument.sgml</b>. If there are no sgml syntax 278 errors, this will create a directory <tt>mydocument</tt> and place the 279 resulting html files in it. The title page of the document 280 will typically be 281 <tt>mydocument/index.html</tt>. If you have 282 screenshots in your document, you will have to copy these 283 files into the <tt>mydocument</tt> directory by 284 hand. You can use any web browser to view your document. 285 Note that every time you run <b>db2html</b>, it 286 creates the <tt>mydocument</tt> directory over, so 287 you will have to copy the screenshots over each time. 288 </p><p> 289 You can also convert your document to PostScript by running 290 the command <tt>$</tt><b>db2ps 291 mydocument.sgml</b>, after which you can print out or 292 view the resulting .ps file. 293 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2796585"></a>NOTE</h3><p> 294 The html files you get will not look quite the same as the 295 documentation distributed with GNOME unless you have the 296 custom stylesheets installed on your machine. DocBook 297 Tools' default stylesheets will produce a different look 298 to your docs. You can read more about the GDP stylesheets 299 in <a href="#gdpstylesheets" title="GDP Stylesheets">the section called “GDP Stylesheets”</a>. 300 </p></div></div><div class="sect3"><a name="jadeimages"></a><div class="titlepage"><div><h4 class="title"><a name="jadeimages"></a>Images in DocBook Tools</h4></div></div><p> 301 If your document uses images you will need to take note of a 302 few things that should take place in order for you to make 303 use of those images in your output. 304 </p><p> 305 The DocBook Tools scripts and applications are smart enough 306 to know that when you are creating html you will be using 307 PNG files and when you are creating Postscript you will be 308 using EPS files (you must use EPS with Postscript). 309 </p><p> 310 Thus, you should never explicitly 311 include the extension of the image file, since DocBook 312 Tools will automatically insert it for you. For example: 313 </p><pre class="programlisting"> 314 315<figure> 316 <title>My Image</title> 317 <screenshot> 318 <screeninfo>Sample GNOME Display</screeninfo> 319 <graphic format="png" fileref="myfile" srccredit="me"> 320 </graphic> 321 </screenshot> 322</figure> 323 </pre><p> 324 You will notice in this example that the file 325 <tt>myfile.png</tt> was referred to as simply 326 <tt>myfile</tt>. Now when you run 327 <b>db2html</b> to create an html file, it will 328 automatically look for <tt>myfile.png</tt> in 329 the directory. 330 </p><p> 331 If you want to create PostScript ouput, you will need to create an 332 EPS version of your image file to be displayed in the 333 PostScript file. There is a simple script available which 334 allows you to change a PNG image into an EPS file 335 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> 336 (look for the img2eps section). Note that this script is 337 included in the gnome-doc-tools package, so if you are using 338 this package, you should already have 339 <b>img2eps</b> on you system. 340 </p></div><div class="sect3"><a name="moredocbookinfo"></a><div class="titlepage"><div><h4 class="title"><a name="moredocbookinfo"></a>Learning DocBook</h4></div></div><p> 341 There are many resources available to help you learn DocBook. 342 The following resources on the web are useful for learning 343 DocBook: 344 </p><div class="itemizedlist"><ul><li style="list-style-type: disc"><p><a name="id2918531"></a> 345 <a href="http://www.docbook.org" target="_top">http://www.docbook.org</a> - Norman 346 Walsh's <i>DocBook: The Definitive 347 Guide</i>. Online O'Reilly book on using 348 DocBook. Contains an excellent element reference. May be 349 too formal for a beginner. 350 </p></li><li style="list-style-type: disc"><p><a name="id2918577"></a> 351 <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> 352 - The Open Source Writers Group's introduction to using 353 DocBook. This is an excellent HOW-TO type article on 354 getting started. 355 </p></li><li style="list-style-type: disc"><p><a name="id2918619"></a> 356 <a href="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html" target="_top">Getting Going with DocBook: Notes for 357 Hackers</a> - Mark Galassi's introduction to DocBook 358 for hackers. This has to be one of the first 359 introductions to DocBook ever - still as good as it ever 360 was. 361 </p></li><li style="list-style-type: disc"><p><a name="id2918658"></a> 362 <a href="http://www.freebsd.org/tutorials/docproj-primer/" target="_top"> 363 FreeBSD Documentation Project Primer for New 364 Contributors</a> - FreeBSD documentation project 365 primer. Chapter 4.2 provides a very good introduction to 366 writing documentation using DocBook. Note that it also 367 describes some custom extensions of DocBook; 368 fortunately, they are clearly marked as such. 369 </p></li></ul></div><p> 370 Norman Walsh's book is also available in print. 371 </p><p> 372 The following sections of this document are designed to help 373 documentation authors write correct and consistent DocBook: 374 </p><div class="itemizedlist"><ul><li style="list-style-type: disc"><p><a name="id2918733"></a> 375 <a href="#docbookbasics" title="DocBook Basics ">the section called “DocBook Basics ”</a> - Descriptions of 376 commonly used DocBook tags. 377 </p></li></ul></div><p> 378 You may also discuss specific DocBook questions with GDP 379 members on the #docs IRC channel at irc.gnome.org and on the 380 gnome-doc-list mailing list. 381 </p></div></div><div class="sect2"><a name="gdptemplates"></a><div class="titlepage"><div><h3 class="title"><a name="gdptemplates"></a>GDP Document Templates</h3></div></div><p> 382 Templates for various types of GNOME documents are found in 383 <a href="#templates" title="A. Document Templates">Appendix A. Document Templates</a>. They are kept in CVS in 384 gnome-docu/gdp/templates. The easiest source to get them from 385 is probably the <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP 386 Document Templates</a> web page, which is typically kept 387 completely up-to-date with CVS and has a basic description of 388 each file from CVS. 389 </p></div><div class="sect2"><a name="screenshots"></a><div class="titlepage"><div><h3 class="title"><a name="screenshots"></a>Screenshots</h3></div></div><p> 390 Most GNOME documents will have screenshots of the particular 391 applet, application, GNOME component, or widget being 392 discussed. As discussed above in <a href="#gdpdtd" title="GDP DTD (PNG Image Support)">the section called “GDP DTD (PNG Image Support)”</a> you 393 will need to install the special GDP DocBook DTD which 394 supports PNG images, the format used for all images in GNOME 395 documentation. For the basic DocBook structure used to insert 396 images in a document, see <a href="#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a> above. 397 </p><div class="sect3"><a name="screenshotappearance"></a><div class="titlepage"><div><h4 class="title"><a name="screenshotappearance"></a>Screenshot Appearance</h4></div></div><p> 398 For all screenshots of windows that typically have border 399 decorations (e.g. applications and dialogs, but not applets 400 in a panel), GDP standards dictate 401 the appearance of the window. (This is to minimize possible 402 confusion to the reader, improve the appearance of GNOME 403 documents, and guarantee the screenshot is readable when 404 printed.) All screenshots should be taken with the SawFish 405 (formerly known as Sawmill) window manager using the 406 MicroGui theme and Helvetica 12pt font. (A different window 407 manager can be used provided the MicroGui theme is available 408 for this window manager and the appearance is identical to 409 that when using the SawFish window manager.) The default 410 GTK+ theme(gtk) and font (Helvetica 12 pt) should be used 411 for all screenshots. If you are unable to provide 412 screenshots in this form, you should create screenshots as 413 you wish them to appear and send them to the 414 <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top"> 415 <i>gnome-doc-list mailing list</i> </a> 416 requesting a GDP member reproduce these screenshots in the 417 correct format and email them to you. 418 </p></div><div class="sect3"><a name="screenshottools"></a><div class="titlepage"><div><h4 class="title"><a name="screenshottools"></a>Screenshot Tools</h4></div></div><p> 419 There are many tools for taking screenshots in 420 GNOME/Linux. Perhaps the most convenient is the 421 Screen-Shooter Applet. Just click 422 on the window icon in the applet and then on the window you 423 would like to take a screenshot of. (Note that 424 at the time of this writing, PNG images taken by 425 screenshooter do not appear properly in 426 Netscape or the 427 GNOME Help Browser. You 428 should save your screenshot as a GIF and 429 then use <b>convert filename.gif 430 filename.png</b>.) For applets 431 in a Panel, 432 xv can be used to crop the 433 screenshot to only include the relevant portion of the 434 Panel. Note that 435 xv and 436 gimp can both be used for taking 437 screenshots, cropping screenshots, and converting image 438 formats. 439 </p></div><div class="sect3"><a name="screenshotfiles"></a><div class="titlepage"><div><h4 class="title"><a name="screenshotfiles"></a>Screenshot Files</h4></div></div><p> 440 Screenshots should be kept in the main documentation 441 directory with your SGML file for applets, or should be 442 kept in a directory called "figs" for application and other 443 documentation. After you use <b>db2html</b> to 444 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 445 screenshots (either the individual PNG files for applet 446 documentation, or the whole "figs" directory for other 447 documentation) into the newly created HTML directory. Note 448 that every time you use <b>db2html</b> the HTML 449 directory is erased and rewritten, so do not store your only 450 copy of the screenshots in that directory. If you wish to 451 create PostScript or PDF output, you will need to manually 452 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 453 images from their default location, as they are included 454 directly into the output(PostScript of PDF) file. 455 </p></div></div><div class="sect2"><a name="applicationbugs"></a><div class="titlepage"><div><h3 class="title"><a name="applicationbugs"></a>Application Bugs</h3></div></div><p> 456 Documentation authors tend to investigate and test applets and 457 applications more thoroughly than most 458 users. Often documentation authors will discover one or 459 more bugs in the software. These bugs vary from small ones, 460 such as mis-spelled words or missing 461 About dialogs in the menu, to large 462 ones which cause the applet to crash. As all users, you 463 should be sure to report these bugs so that application 464 developers know of them and can fix them. The easiest way to 465 submit a bug report is by using the Bug 466 Buddy applet which is part of the gnome-applets 467 package. 468 </p></div><div class="sect2"><a name="cvs"></a><div class="titlepage"><div><h3 class="title"><a name="cvs"></a>Using CVS</h3></div></div><p> 469 CVS (Concurrent Versions System) is a tool that allows 470 multiple developers to concurrently work on a set of 471 documents, keeping track of the modifications made by each 472 person. The files are stored on a server and each developer 473 checks files out, modifies them, and then checks in their 474 modified version of the files. Many GNOME programs and 475 documents are stored in CVS. The GNOME CVS server allows 476 users to anonymously check out CVS files. Most GDP members 477 will need to use anonymous CVS to download the most up-to-date 478 version of documentation or programs. Modified documents will 479 typically be emailed to the the application developer. Core 480 GDP members may also be granted login CVS privileges so they 481 may commit modified files directly to CVS. 482 </p><div class="sect3"><a name="anonymouscvs"></a><div class="titlepage"><div><h4 class="title"><a name="anonymouscvs"></a>Anonymous CVS</h4></div></div><p> 483 To anonymously check out documents from CVS, you must first 484 log in. From the bash shell, you should set your CVSROOT 485 shell variable with <b> export 486 CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</b> 487 and then login with <b>cvs login</b>(there is no 488 password, just hit return). As an example, we will use the 489 "gnome-docu/gdp" module which contains this and several 490 other documents. To check these documents out for the first 491 time, type <b>cvs -z3 checkout 492 gnome-docu/gdp</b>. After you have this document 493 checked out and you would like to download any updates on 494 the CVS server, use <b>cvs -z3 update -Pd</b>. 495 </p></div><div class="sect3"><a name="logincvs"></a><div class="titlepage"><div><h4 class="title"><a name="logincvs"></a>Login CVS</h4></div></div><p> If you have been given a 496 login for the GNOME CVS server, you may commit your file 497 modifications to CVS. Be sure to read the following section 498 on CVS etiquette before making any commits to CVS. To log in 499 to the CVS server as user 500 <b><i><tt>username</tt></i></b> with a 501 password, you must first set your CVSROOT shell variable with 502 <b> export 503 CVSROOT=':pserver:<i><tt>username</tt></i>@cvs.gnome.org:/cvs/gnome'</b>. 504 Log in with <b>cvs login</b> and enter your 505 password. You may check out and update modules as described 506 above for anonymous CVS access. As a login CVS user, you may 507 also check modified versions of a file into the CVS server. 508 To check 509 <b><i><tt>filename</tt></i></b> into 510 the CVS server, type <b>cvs -z3 commit 511 <i><tt>filename</tt></i></b>. You will be 512 given a vi editor window to type in a brief log entry, 513 summarizing your changes. The default editor can be changed 514 using the <tt>EDITOR</tt> environment variable or 515 with the <b><tt>-e</tt></b> option. You 516 may also check in any modifications to files in the working 517 directory and subdirectories using <b>cvs -z3 518 commit</b>. To 519 add a new file to the CVS server, use <b>cvs -z3 add 520 <i><tt>filename</tt></i></b>, followed by the 521 commit command. 522 </p></div><div class="sect3"><a name="cvsetiquette"></a><div class="titlepage"><div><h4 class="title"><a name="cvsetiquette"></a>CVS Etiquette</h4></div></div><p> 523 Because files in CVS are typically used and modified by 524 multiple developers and documentation authors, users should 525 exercise a few simple practices out of courtesy towards the 526 other CVS users and the project leader. First, you should 527 not make CVS commits to a package without first discussing 528 your plans with the project leader. This way, the project 529 leader knows who is modifying the files and generally, what 530 sort of changes/development is being done. Also, whenever a 531 CVS user commits a file to CVS, they should make an entry in 532 the CVS log and in the <tt>ChangeLog</tt> so 533 that other users know who is making modifications and what 534 is being modified. When modifying files created by others, 535 you should follow the indentation scheme used by the initial 536 author. 537 </p></div></div></div><div class="sect1"><a name="gnomedocsystem"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="gnomedocsystem"></a>The GNOME Documentation System</h2></div></div><div class="sect2"><a name="gnomehelpbrowser"></a><div class="titlepage"><div><h3 class="title"><a name="gnomehelpbrowser"></a>The GNOME Help Browser</h3></div></div><p> 538 At the core of the GNOME help system is the GNOME 539 Help Browser. The Help 540 Browser provides a unified interface to several 541 distinct documentation systems on Linux/Unix systems: man 542 pages, texinfo pages, Linux Documentation Project(LDP) 543 documents, GNOME application documentation, and other GNOME 544 documents. 545 </p><p> 546 The GNOME Help Browser works by 547 searching standard directories for documents which are to be 548 presented. Thus, the documentation that appears in the GHB is 549 specific to each computer and will typically only represent 550 software that is installed on the computer. 551 </p></div><div class="sect2"><a name="gnomehelpbrowser2"></a><div class="titlepage"><div><h3 class="title"><a name="gnomehelpbrowser2"></a>The GNOME Help Browser (GNOME-2.0)</h3></div></div><p> In 552 GNOME 2.0, the GNOME Help Browser 553 will be replaced by Nautilus. 554 Nautilus will be the file manager/graphical shell for GNOME 2.0 555 and will also implement a more sophisticated help system than 556 that used by the GNOME Help Browser 557 used in GNOME 1.0. It will read and display DocBook files 558 directly, avoiding the need for duplicating documents in both 559 DocBook and HTML formats. Its display engine for DocBook will 560 be much faster than running jade to 561 convert to HTML for rendering. Because it uses the original 562 DocBook source for documentation, it will be possible to do more 563 sophisticated searching using the meta information included in 564 the documents. And since Nautilus is a virtual file system 565 layer which is Internet-capable, it will be able to find and 566 display documents which are on the web as well as those on the 567 local file system. For more information on 568 Nautilus, visit the #nautilus IRC 569 channel on irc.gnome.org. </p></div><div class="sect2"><a name="gnomehelponthefly"></a><div class="titlepage"><div><h3 class="title"><a name="gnomehelponthefly"></a>Dynamic Document Synthesis(GNOME-2.0)</h3></div></div><p> 570 GNOME uses the documentation presented by all the various 571 GNOME components and applications installed on the system to 572 present a complete and customized documentation environment 573 describing only components which are currently installed on a 574 users system. Some of this documentation, such as the manuals 575 for applets, will be combined in such a way that it appears to 576 be a single document. 577 </p><p> 578 By using such a system, you can be sure that any GNOME app you 579 install that has documentation will show up in the index, 580 table of contents, any search you do in the help browser. 581 </p></div><div class="sect2"><a name="gnomehelpcomponents"></a><div class="titlepage"><div><h3 class="title"><a name="gnomehelpcomponents"></a>The GNOME Documentation Components</h3></div></div><div class="sect3"><a name="applicationmanualsintro"></a><div class="titlepage"><div><h4 class="title"><a name="applicationmanualsintro"></a>Application Manuals</h4></div></div><p> 582 Every GNOME application should have an application manual. 583 An application manual is a document specific to the 584 particular application which explains the various windows 585 and features of the application. Application Manuals 586 typically use screenshots (PNG format) for clarity. Writing 587 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. 588 </p></div><div class="sect3"><a name="applicationhelpintro"></a><div class="titlepage"><div><h4 class="title"><a name="applicationhelpintro"></a>Application Help</h4></div></div><p> 589 Applications should have a Help 590 button on screens on which users may need help. These 591 Help buttons should pull up the 592 default help browser, determined by the 593 <tt>ghelp</tt> URL Handler (configured using the 594 Control Center), typically the 595 GNOME Help Browser. The help 596 browser should show either the first page of the application 597 manual, or else the relevant page thereof. Application help 598 is described in more detail in <a href="#applicationhelpbuttons" title="Application Help Buttons">the section called “Application Help Buttons”</a> below. 599 </p></div><div class="sect3"><a name="contextsensitivehelpintro"></a><div class="titlepage"><div><h4 class="title"><a name="contextsensitivehelpintro"></a>Application Context Sensitive Help (coming in 600 GNOME-2.0)</h4></div></div><p> 601 Context sensitive help is a system which will allow the user 602 to query any part (button, widget, etc.) of an application 603 window. This is done by either entering a CS Help mode by 604 clicking on an icon or by right clicking on the application 605 part and selecting "What's This" or whatever is decided on 606 at the time. Context sensitive help is described in more 607 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> 608 below. 609 </p></div><div class="sect3"><a name="userguide"></a><div class="titlepage"><div><h4 class="title"><a name="userguide"></a>The GNOME User Guide</h4></div></div><p> 610 The <i>GNOME User Guide</i> describes the 611 GNOME desktop environment and core components of GNOME such 612 as the panel and 613 control center. In GNOME 1.x this 614 was the main and only source of documentation. In GNOME 2.0 615 this will become a document for the web and for printing 616 that is derived from various parts chosen in the system that 617 are necessary for the new user to understand. 618 </p></div><div class="sect3"><a name="userdocs"></a><div class="titlepage"><div><h4 class="title"><a name="userdocs"></a>User Documents</h4></div></div><p> 619 Aside from the <i>GNOME User Guide</i>, 620 there are several other documents to help GNOME users learn 621 GNOME, including the <i>GNOME FAQ</i>, 622 <i>GNOME Installation and Configuration 623 Guide</i>, and the <i>GNOME Administrators 624 Guide</i>. 625 </p></div><div class="sect3"><a name="developerdocs"></a><div class="titlepage"><div><h4 class="title"><a name="developerdocs"></a>Developer Documents</h4></div></div><p> 626 There are many White Papers, Tutorials, HOWTO's and FAQ's to 627 make programming GNOME and GNOME applications as easy as 628 possible. 629 </p><p> 630 API documentation is also available for the GNOME libraries. This is 631 detailed documentation of the code that is used to build GNOME 632 apps. You can keep up with the GNOME API docs on the <a href="http://developer.gnome.org/doc/API/" target="_top">GNOME API 633 Reference</a> page. 634 </p></div><div class="sect3"><a name="projectdocs"></a><div class="titlepage"><div><h4 class="title"><a name="projectdocs"></a>Project Documents</h4></div></div><p> 635 Some GNOME projects have documentation to maintain 636 consistency in their product and to help new contributors 637 get up to speed quickly. Among these are the GDP documents, 638 such as the one you are reading now. 639 </p></div></div></div><div class="sect1"><a name="docbookbasics"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="docbookbasics"></a>DocBook Basics </h2></div></div><div class="sect2"><a name="introtodocbook"></a><div class="titlepage"><div><h3 class="title"><a name="introtodocbook"></a>Introduction to DocBook</h3></div></div><p> 640 To understand DocBook, a basic understanding of SGML is 641 helpful. SGML stands for Standard General Markup Language and 642 is one of the first markup languages every created. HTML is 643 actually derived from SGML and XML is a subset of SGML. SGML 644 uses what is called a Document Type Definition to specify 645 <i>elements</i> which are contained between 646 brackets, < and >. Text is marked by both beginning and 647 ending elements, for example in the DocBook DTD, one denotes a 648 title with <tt><title></tt>The 649 Title<tt></title></tt>. 650 </p><p> 651 The DTD (in the case of the GDP, DocBook) defines rules for how the 652 elements can be used. For example, if one element can only be used when 653 embedded within another, this is defined in the DTD. 654 </p><p> 655 An SGML file is just a plain ASCII file containing the text 656 with the markup specified above. To convert it to some easily 657 readable format, you need special tools. The GDP uses <i>DocBook 658 Tools</i>, a free package of utilities for working with DocBook 659 which includes <i>Jade</i>, which does the SGML/DSSL 660 parsing. You can read more about DocBook Tools in <a href="#installingdocbook" title="Installing DocBook">the section called “Installing DocBook”</a>. 661 </p><p> 662 The final appearance of the output (e.g. PostScript or HTML) 663 is determined by a 664 <i>stylesheet</i>. Stylesheets are files, 665 written in a special language (DSSSL -- Document Style 666 Semantics and Specification Language), which specify the 667 appearance of various DocBook elements, for example, 668 what fonts to use for titles and various inline elements, page 669 numbering style, and much more. DocBook tools come with a 670 collection of stylesheets (Norman Walsh's modular 671 stylesheets); GNOME Document Project uses some customized 672 version of this stylesheets -- see <a href="#gdpstylesheets" title="GDP Stylesheets">the section called “GDP Stylesheets”</a>. 673 </p><p> 674 The advantage of specifying the <i>structure</i> 675 of a document with SGML instead of specifying the 676 <i>appearance</i> of the document with a typical 677 word processor, or with html, is that the resulting document 678 can be processed in a variety of ways using the structural 679 information. Whereas formatting a document for appearance 680 assumes a medium (typically written text on a standard-sized 681 piece of paper), SGML can be processed to produce output for a 682 large variety of media such as text, postscript, HTML, 683 Braille, audio, and potentially many other formats. 684 </p><p> 685 Using 'content' as the elements to define the text of a document also 686 allows for search engines to make use of the actual elements to make a 687 "smarter search". For example, if you are searching for all documents 688 written by the author "Susie" your search engine could be made smart 689 enough to only search <author> elements, making for a faster and more 690 accurate search. 691 </p><p> 692 Since the overall appearance of the output is determined not by the DTD 693 or the SGML document, but rather by a stylesheet, the appearance of a 694 document can be easily changed just by changing the stylesheet. This 695 allows everyone in the project to create documents that all look the 696 same. 697 </p><p> 698 As stated before, the GDP uses the DocBook DTD. For a list of 699 introductory and reference resources on DocBook, see <a href="#resources" title="Resources">the section called “Resources”</a>. The following sections also provide 700 convenient instructions on which markup tags to use in various 701 circumstances. Be sure to read <a href="#conventions" title="GDP Documentation Conventions ">the section called “GDP Documentation Conventions ”</a> 702 for GDP documentation-specific guidelines. 703 </p></div><div class="sect2"><a name="xml"></a><div class="titlepage"><div><h3 class="title"><a name="xml"></a>XML and SGML</h3></div></div><p> In not so distant future (probably before GNOME 2.0), 704 DocBook itself and GNOME Documentation project will migrate from 705 SGML to XML. This transition should be relatively painless: 706 (almost) all DocBook tags will remain the same. However, XML has 707 stricter syntax rules than SGML; thus, some constructions which 708 are valid in SGML will not be valid in XML. Therefore, to be 709 ready for this transistion, it is <i>strongly 710 advised</i> that the documentation writers conform to XML 711 syntax rules. Here are most important differences: 712 </p><div class="variablelist"><dl><dt><a name="id2921045"></a><span class="term"> <i>Minimization</i></span></dt><dd><p><a name="id2921063"></a> 713 It is possible with some implementations of SGML to use 714 minimizations to close elements in a document by using 715 </>, for example: 716 <tt><tt><title></tt>The 717 Title<tt></></tt></tt>. This is not 718 allowed in XML. You can use <b>sgmlnorm</b> command, 719 included in DocBook Tools package, to expand minimized tags; 720 if you are using Emacs with psgml 721 mode, you can also use menu command 722 Modify->Normalize. 723 </p></dd><dt><a name="id2921179"></a><span class="term"> <i>Self-closing tags</i></span></dt><dd><p><a name="id2921197"></a> 724 Also, in SGML some tags are allowed not to have closing 725 tags. For example, it is legal for 726 <tt><xref></tt> not to have a closing tag: 727 <tt><tt><xref 728 linkend="someid"></tt></tt>. In 729 XML, it is illegal; instead, you should use 730 <tt><tt><xref 731 linkend="someid"/></tt></tt> (note the 732 slash!). 733 </p></dd><dt><a name="id2921264"></a><span class="term"> <i>Case sensitive tags</i></span></dt><dd><p><a name="id2921281"></a> 734 In XML, unlike SGML, tags are case-senstive 735 <tt><title></tt> and 736 <tt><TITLE></tt> are different tags! 737 Therefore, please always use lowercase tags (except for 738 things like <tt>DOCTYPE, CDATA</tt> and 739 <tt>ENTITY</tt>, which are not DocBook tags). 740 </p></dd></dl></div></div><div class="sect2"><a name="structure"></a><div class="titlepage"><div><h3 class="title"><a name="structure"></a> Structure Elements</h3></div></div><div class="sect3"><a name="section"></a><div class="titlepage"><div><h4 class="title"><a name="section"></a>Sections and paragraphs</h4></div></div><p> 741 Top-level element of a book body must be 742 <tt><chapter></tt>; it may contain one or more 743 <tt><sect1></tt>, each of them may contain 744 <tt><sect2></tt> and so on up to 745 <tt><sect5></tt>. The top-level element of an 746 article body is always 747 <tt><sect1></tt>. Regardless of which elements 748 you use, give each structural element a unique id, so that 749 you can link to it. For usage example, see the template. 750 </p><p> Please try to avoid using deeply nested sections; for 751 most situations, <tt><sect1></tt> and 752 <tt><sect2></tt> should be sufficient. If not, 753 you probably should split your <tt><sect1></tt> 754 into several smaller ones. 755 </p><p> Use the tag <tt><para></tt> for 756 paragraphs, even if there is only one paragraph in a 757 section--see template for examples. 758 </p></div><div class="sect3"><a name="notes"></a><div class="titlepage"><div><h4 class="title"><a name="notes"></a>Notes, Warnings, And Tips</h4></div></div><p> 759 For notes, tips, warnings, and important information, which 760 should be set apart from the main text (usually as a 761 paragraph with some warning sign on the margin), use tags 762 <tt><note></tt>, <tt><tip></tt>, 763 <tt><warning></tt>, 764 <tt><important></tt> respectively. For example: 765 <pre class="programlisting"> 766 767<tip> 768 <title>TIP</title> 769 <para> 770 To speed up program compilation, use <application>gcc</application> 771 compiler with Pentium optimization. 772 </para> 773</tip> </pre> produces 774 </p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="extip"></a>TIP</h3><p> 775 To speed up program compilation, use 776 gcc compiler with Pentium 777 optimization. </p></div><p> 778 Note that this should not be inside a 779 <tt><para></tt> but between paragraphs. 780 </p></div><div class="sect3"><a name="figures"></a><div class="titlepage"><div><h4 class="title"><a name="figures"></a> Screenshots and other figures</h4></div></div><p> 781 To include screenshots and other figures, use the following 782 tags: 783 784 <pre class="programlisting"> 785 786<figure id="shot1"> 787 <title>Screenshot</title> 788 <screenshot> 789 <screeninfo>Screenshot of a program</screeninfo> 790 <graphic format="PNG" fileref="figures/example_screenshot" srccredit="ME"> 791 </graphic> 792 </screenshot> 793</figure> 794 </pre> 795 replacing <tt>example_screenshot</tt> with the 796 actual file name (without extension). The result will look like this: 797 798 <div class="figure"><p><a name="shot1"></a><b>Figure 1. Screenshot</b></p><div class="screenshot"><p><img src="figures/example_screenshot"></p></div></div> 799 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2921804"></a>NOTE</h3><p> 800 Notice in this example that the screenshot file name does 801 not include the file type extension -- to find out 802 why, please read <a href="#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a>. 803 </p></div></div><div class="sect3"><a name="listing"></a><div class="titlepage"><div><h4 class="title"><a name="listing"></a>Program listings and terminal session</h4></div></div><p> 804 To show a file fragment--for example, program 805 listing--use <tt><programlisting></tt> tag: 806 <pre class="programlisting"> 807 808<programlisting> 809[Desktop Entry] 810Name=Gnumeric spreadsheet 811Exec=gnumeric 812Icon=gnome-gnumeric.png 813Terminal=0 814Type=Application 815</programlisting> 816 </pre> 817 which produces 818 <pre class="programlisting"> 819[Desktop Entry] 820Name=Gnumeric spreadsheet 821Exec=gnumeric 822Icon=gnome-gnumeric.png 823Terminal=0 824Type=Application 825 </pre> 826 As a matter of fact, all examples in this document were 827 produced using <tt><programlisting></tt>. 828 </p><p> 829 To show a record of terminal session--i.e., sequence of 830 commands entered at the command line--use 831 <tt><screen></tt> tag: 832 <pre class="programlisting"> 833 834<screen> 835<prompt>bash$</prompt><userinput>make love</userinput> 836make: *** No rule to make target `love'. Stop. 837</screen> 838 </pre> 839 which produces 840 <pre class="screen"> 841<tt>bash$</tt><b><tt>make love</tt></b> 842make: *** No rule to make target `love'. Stop. 843 </pre> 844 Note the use of tags <tt><prompt></tt> and 845 <tt><userinput></tt> for marking system prompt 846 and commands entered by user. 847 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2922020"></a>NOTE</h3><p> 848 Note that both <tt><programlisting></tt> 849 and <tt><screen></tt> preserve linebreaks, 850 but interpret SGML tags (unlike LaTeX 851 verbatim environment). Take a look at 852 the source of this document to see how you can have SGML 853 tags literally shown but not interpreted, 854 </p></div> 855 </p></div><div class="sect3"><a name="lists"></a><div class="titlepage"><div><h4 class="title"><a name="lists"></a> Lists</h4></div></div><p> 856 The most common list types in DocBook are 857 <tt><itemizedlist></tt>, 858 <tt><orderedlist></tt>, and 859 <tt><variablelist></tt>. 860 </p><div class="variablelist"><dl><dt><a name="id2922139"></a><span class="term"> <tt><itemizedlist></tt></span></dt><dd><p><a name="id2922158"></a> 861 This is the simplest unnumbered list, parallel to 862 <tt><ul></tt> in HTML. Here is an example: 863 <pre class="programlisting"> 864 865<itemizedlist> 866 <listitem> 867 <para> 868 <guilabel>Show backup files</guilabel> &mdash; This will 869 show any backup file that might be on your system. 870 </para> 871 </listitem> 872 <listitem> 873 <para> 874 <guilabel>Show hidden files</guilabel> &mdash; This will 875 show all "dot files" or files that begin with a dot. This 876 files typically include configuration files and directories. 877 </para> 878 </listitem> 879 <listitem> 880 <para> 881 <guilabel>Mix files and directories</guilabel> &mdash; This 882 option will display files and directories in the order you 883 sort them instead of 884 always having directories shown above files. 885 </para> 886 </listitem> 887</itemizedlist> 888 889 </pre> 890 and output: 891 </p><div class="itemizedlist"><ul><li><p><a name="id2922197"></a> 892 Show backup files -- 893 This will show any backup file that might be on 894 your system. 895 </p></li><li><p><a name="id2922257"></a> 896 Show hidden files -- 897 This will show all "dot files" or files that 898 begin with a dot. This files typically include 899 configuration files and directories. 900 </p></li><li><p><a name="id2922289"></a> 901 Mix files and directories 902 -- This option will display files and 903 directories in the order you sort them instead 904 of always having directories shown above files. 905 </p></li></ul></div><p> Note the use of <tt>&mdash;</tt> 906 for long dash (see <a href="#specsymb" title=" Special symbols ">the section called “ Special symbols ”</a>). Also, 907 please note that the result looks much nicer because the 908 terms being explained (Show backup 909 files, etc.) are set in a different font. In 910 this case, it was achieved by using <a href="#gui" title="GUI elements"><tt><guilabel></tt></a> 911 tag. In other cases, use appropriate tags such as 912 <a href="#gui" title="GUI elements"><tt><guimenuitem></tt></a>, 913 <a href="#filenames" title="Filenames, commands, and other 914 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="id2922461"></a><span class="term"> <tt><orderedlist></tt></span></dt><dd><p><a name="id2922479"></a> 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="id2922560"></a><span class="term"> <tt><variablelist></tt></span></dt><dd><p><a name="id2922579"></a> 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"></a><div class="titlepage"><div><h3 class="title"><a name="inline"></a>Inline Elements</h3></div></div><div class="sect3"><a name="gui"></a><div class="titlepage"><div><h4 class="title"><a name="gui"></a>GUI elements</h4></div></div><div class="itemizedlist"><ul><li><p><a name="id2922748"></a> 973 <tt><guibutton></tt> -- used for 974 buttons, including checkbuttons and radio buttons 975 </p></li><li><p><a name="id2922775"></a> 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="id2922825"></a> 983 <tt><guimenuitem></tt>--an entry in a 984 menu 985 </p></li><li><p><a name="id2922849"></a> 986 <tt><guiicon></tt>--an icon 987 </p></li><li><p><a name="id2922874"></a> 988 <tt><guilabel></tt>--for items which have 989 labels, like tabs, or bounding boxes. 990 </p></li><li><p><a name="id2922899"></a> 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"></a><div class="titlepage"><div><h4 class="title"><a name="links"></a>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"></a><div class="titlepage"><div><h4 class="title"><a name="filenames"></a>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="id2923288"></a> <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="id2923345"></a> <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="id2923408"></a> 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="id2923463"></a> 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="id2923505"></a> 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="id2923561"></a> 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"></a><div class="titlepage"><div><h4 class="title"><a name="keys"></a>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"></a><div class="titlepage"><div><h4 class="title"><a name="email"></a>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"></a><div class="titlepage"><div><h4 class="title"><a name="specsymb"></a> 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="id2924022"></a> 1135 <tt>&amp;</tt> -- ampersend (&) 1136 </p></li><li><p><a name="id2924043"></a> 1137 <tt>&lt;</tt> -- left angle bracket (<) 1138 </p></li><li><p><a name="id2924062"></a> 1139 <tt>&copy;</tt> -- copyright sign (�) 1140 </p></li><li><p><a name="id2924080"></a> 1141 <tt>&mdash;</tt> -- long dash (--) 1142 </p></li><li><p><a name="id2924106"></a> 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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="conventions"></a>GDP Documentation Conventions </h2></div></div><div class="sect2"><a name="conventionsalldocs"></a><div class="titlepage"><div><h3 class="title"><a name="conventionsalldocs"></a>Conventions for All GDP Documentation</h3></div></div><div class="sect3"><a name="xmlcomp"></a><div class="titlepage"><div><h4 class="title"><a name="xmlcomp"></a> 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"></a><div class="titlepage"><div><h4 class="title"><a name="authorsnames"></a> 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"></a><div class="titlepage"><div><h3 class="title"><a name="conventionsappdocs"></a>Conventions for Application Documentation</h3></div></div><div class="sect3"><a name="applicationversionid"></a><div class="titlepage"><div><h4 class="title"><a name="applicationversionid"></a>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"></a><div class="titlepage"><div><h4 class="title"><a name="license"></a> 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"></a><div class="titlepage"><div><h4 class="title"><a name="license2"></a>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"></a><div class="titlepage"><div><h4 class="title"><a name="bugtraq"></a> 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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="writingapplicationmanuals"></a>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="id2924548"></a>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="id2924643"></a>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="id2924700"></a>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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="listingdocsinhelpmenu"></a>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="id2924823"></a>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="id2925011"></a>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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="applicationhelpbuttons"></a>Application Help Buttons</h2></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2925176"></a>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="id2925314"></a>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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="packagingappletdocs"></a>Packaging Applet Documentation</h2></div></div><div class="sect2"><a name="appletfiles"></a><div class="titlepage"><div><h3 class="title"><a name="appletfiles"></a>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"></a><div class="titlepage"><div><h3 class="title"><a name="appletmenu"></a>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="id2925561"></a>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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="writingcontextsensitivehelp"></a>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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="referring"></a>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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="basics"></a>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"></a><div class="titlepage"><div><h3 class="title"><a name="styleplanning"></a>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"></a><div class="titlepage"><div><h3 class="title"><a name="balance"></a>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="id2926120"></a> 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="id2926147"></a> 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="id2926185"></a> 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="id2926209"></a> 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"></a><div class="titlepage"><div><h3 class="title"><a name="stylestructure"></a>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"></a><div class="titlepage"><div><h3 class="title"><a name="stylegrammar"></a>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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="teamwork"></a>Teamwork</h2></div></div><div class="sect2"><a name="teamworkgdp"></a><div class="titlepage"><div><h3 class="title"><a name="teamworkgdp"></a>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"></a><div class="titlepage"><div><h3 class="title"><a name="teamworkdevelopers"></a>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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="finishing"></a>Finishing A Document</h2></div></div><div class="sect2"><a name="editting"></a><div class="titlepage"><div><h3 class="title"><a name="editting"></a>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"></a><div class="titlepage"><div><h3 class="title"><a name="submitting"></a>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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="resources"></a>Resources</h2></div></div><div class="sect2"><a name="resourcesweb"></a><div class="titlepage"><div><h3 class="title"><a name="resourcesweb"></a>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"></a><div class="titlepage"><div><h3 class="title"><a name="resourcesbooks"></a>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"></a><div class="titlepage"><div><h3 class="title"><a name="mailinglists"></a>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"></a><div class="titlepage"><div><h3 class="title"><a name="irc"></a>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>A. Document Templates</h2><div class="sect1"><a name="template1"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="template1"></a>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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="template2-1x"></a>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"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="template2-2x"></a>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
