2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "../dtd/4.1.2/docbookx.dtd" [
4 <!ENTITY version "1.0.53">
7 <!-- replace version above with actual application version number-->
8 <!-- Template Version: 1.0.1 (do not remove this line) -->
12 <!ENTITY APPLET-TEMPLATE-1x-SHELL SYSTEM
13 "templates/applet_template_1-applet.sgml.cdata">
14 <!ENTITY APPLET-TEMPLATE-1x SYSTEM
15 "templates/applet_template_1.sgml.cdata">
18 <!-- Version: 1.0.1 -->
26 <firstname>David</firstname>
27 <surname>Mason</surname>
29 <orgname>Red Hat, Inc.</orgname>
31 <email>dcm@redhat.com</email>
37 <firstname>Daniel</firstname>
38 <surname>Mueth</surname>
41 <email>d-mueth@uchicago.edu</email>
47 <firstname>Alexander</firstname>
48 <surname>Kirillov</surname>
51 <email>kirillov@math.sunysb.edu</email>
59 This is a pre-release!
75 <holder>Red Hat, Inc., Daniel Mueth, and Alexander Kirillov</holder>
80 Permission is granted to copy, distribute and/or modify this
81 document under the terms of the <citetitle>GNU Free Documentation
82 License</citetitle>, Version 1.1 or any later version published
83 by the Free Software Foundation with no Invariant Sections, no
84 Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
85 of the <citetitle>GNU Free Documentation License</citetitle> from
86 the Free Software Foundation by visiting <ulink type="http"
87 url="http://www.fsf.org">their Web site</ulink> or by writing to:
88 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
89 Boston, MA 02111-1307, USA.
92 Many of the names used by companies to distinguish their products and
93 services are claimed as trademarks. Where those names appear in any
94 GNOME documentation, and those trademarks are made aware to the members
95 of the GNOME Documentation Project, the names have been printed in caps
100 <title>The GNOME Handbook of Writing Software Documentation</title>
104 <!-- ################# Introduction ############### -->
107 <title>Introduction</title>
109 <!-- ####### Introduction | The GNOME Documentation Project ####### -->
112 <title>The GNOME Documentation Project</title>
117 The GNOME Documentation Project (GDP) aims to provide GNOME
118 and GNOME applications with a complete, intuitive, and clear
119 documentation system. At the center of the GDP is the
120 <application>GNOME Help Browser</application>, which
121 presents a unified interface to GNOME-specific documentation
122 as well as other Linux documentation such as man pages and
123 texinfo documents. The GNOME Help System provides a
124 comprehensive view of documentation on a machine by
125 dynamically assembling the documentation of GNOME
126 applications and components which are installed. The GDP is
127 responsible for writing numerous GNOME-related documents,
128 both for developers and for users. Developer documentation
129 includes <ulink url="http://developer.gnome.org/doc/API/"
130 type="http">APIs for the GNOME libraries</ulink>, <ulink
131 url="http://developer.gnome.org/doc/whitepapers/"
132 type="http"><citetitle>GNOME White
133 Papers</citetitle></ulink>, GNOME developer <ulink
134 url="http://developer.gnome.org/doc/tutorials/"
135 type="http">tutorials</ulink>, the <ulink
136 url="http://developer.gnome.org/doc/FAQ/"
137 type="http"><citetitle>GNOME Developer
138 FAQ</citetitle></ulink>, the <ulink
139 url="http://developer.gnome.org" type="http">GNOME
140 Developer's Website</ulink>, and <citetitle>GNOME
141 Handbook</citetitle>'s, such as the one you are reading.
142 User documentation include the <ulink
143 url="http://www.gnome.org/learn/"
144 type="http"><citetitle>GNOME User's
145 Guide</citetitle></ulink>, the <ulink
146 url="http://www.gnome.org/learn/"
147 type="http"><citetitle>GNOME FAQ</citetitle></ulink>, and
148 GNOME application documentation. Most GNOME applications
149 have their own manual in addition to context sensitive help.
154 <title>Joining the GDP</title>
156 Documenting GNOME and all the numerous GNOME applications is
157 a very large project. The GDP is always looking for people
158 to help write, update, and edit documentation. If you are
159 interested in joining the GDP team, you should join the
160 <ulink url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
161 <citetitle>gnome-doc-list mailing list</citetitle> </ulink>.
162 Read <xref linkend="gettingstarted" />, for help selecting a
163 project to work on. Feel free to introduce yourself on the
164 gnome-doc-list mailing list and indicate which project you
165 intend to work on, or else ask for suggestions of important
166 documents which need work done. You may also want to join the
167 #docs IRC channel on irc.gnome.org to meet other GDP members
168 and discuss any questions you may have. For a list of GDP
169 projects and members, see the
170 <ulink url="http://developer.gnome.org/projects/gdp">
171 <citetitle>GDP Website</citetitle></ulink>.
175 <sect3 id="collaborating">
176 <title>Collaborating with the GDP</title>
178 GNOME developers, packagers, and translators may not be
179 writing GNOME documentation but will want to understand how
180 the GNOME documentation system works and will need to
181 collaborate with GDP members. This document should help to
182 outline the structure of how the GNOME documentation system
183 works. Developers who do not write the documentation for
184 their applications are encouraged to find a GDP member to
185 write the documentation. This is best done by sending an
187 url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
188 <citetitle>gnome-doc-list mailing list</citetitle> </ulink>
189 describing the application, where it can be downloaded from,
190 and that the developer(s) would like a GDP member to write
191 documentation for the application. The #docs IRC channel on
192 irc.gnome.org is another option for contacting GDP members.
197 <!-- ####### Introduction | Notation and Conventions ####### -->
199 <sect2 id="notation">
200 <title>Notation and Conventions</title>
202 This Handbook uses the following notation:
203 <informaltable frame="none">
208 <filename class="directory">/usr/bin</filename>
216 <filename>foo.sgml</filename>
224 <command>command</command>
227 Command or text that would be typed.
232 <command><replaceable>replaceable</replaceable></command>
235 "Variable" text that can be replaced.
240 <literal>Program or Doc Code</literal>
242 <entry>Program or document code</entry>
250 <!-- ####### Introduction | About This Handbook ####### -->
253 <title>About This Handbook</title>
255 This Handbook is a guide for both writing documentation for
256 GNOME components and applications and for properly binding and
257 packaging documentation into GNOME applications.
260 This Handbook, like all GNOME documentation, was written in
261 DocBook(SGML) and is available in several formats including
262 SGML, HTML, PostScript, and PDF. For the latest version, see
264 url="http://developer.gnome.org/projects/gdp/handbook.html">
265 <citetitle>Getting The GNOME Handbook of Writing Software
266 Documentation</citetitle> </ulink>. Alternately, one may
267 download it anonymously from GNOME CVS under <filename
268 class="directory">gnome-docu/gdp</filename>.
273 <!-- ################# Getting Started ############### -->
275 <sect1 id="gettingstarted">
276 <title>Getting Started Writing GNOME Documentation</title>
278 <!--####### Getting Started | Selecting A Document ####### -->
280 <sect2 id="selecting">
281 <title>Selecting A Document</title>
284 <title>Document Something You Know</title>
286 The most frequently asked question of new contributors who
287 join the GDP is "which document should I start
288 with?". Because most people involved are volunteers, we do
289 not <emphasis>assign</emphasis> projects and applications to
290 write documents for. The first step is all yours - you must
291 decide what about GNOME interests you most and find out if
292 it has complete documents or not.
295 It is also important to spend some time with GNOME to make
296 sure you are familiar enough with it to be
297 <emphasis>authoritative</emphasis> in your writing. The
298 best way to do this is to just sit down and play with GNOME
299 as much as possible before starting to write.
302 The easiest way to get started is to improve existing
303 documentation. If you notice some inaccuracies or omissions
304 in the documentation, or you think that you can explain the
305 material more clearly, just send your suggestions to the
306 author of the original documentation or to the GNOME
307 documentation project at <email>docs@gnome.org</email>.
311 <sect3 id="doctable">
312 <title>The GNOME Documentation Status Table</title>
314 The <citetitle>GDP Documentation Status Table</citetitle>
315 (<citetitle>DocTable</citetitle>) (<ulink
316 url="http://www.gnome.org/gdp/doctable/"
317 type="http">http://www.gnome.org/gdp/doctable/</ulink>) is a
318 web page which tracks the status of all the various
319 documentation components of GNOME. These components include
320 application documentation, internal GNOME component
321 documentation, user documentation, and developer
322 documentation. For each documentation item, it tracks the
323 current status of the documentation, who is working on the
324 particular document, where the documentation can be found,
325 and provides a forum for the discussion of each item.
328 You should use the <citetitle>DocTable</citetitle> to help
329 you select a documentation item which needs work done. Once
330 you have selected an item to work on, please register
331 yourself as an author so that other authors do not duplicate
332 your work and may contact you to help or offer suggestions.
333 Also be sure to keep the status icons up-to-date so that
334 the GDP team can easily identify which items need additional
335 help. The <citetitle>DocTable</citetitle> also allows
336 people to make announcements and suggestions and to discuss
337 issues in the comments section.
342 Note that the information in the
343 <citetitle>DocTable</citetitle> may not always be up-to-date
344 or accurate. When you assign yourself to documenting an
345 application, make sure you find out the latest status of
346 documentation by contacting the application author.
352 <!-- ####### Getting Started | Installing And Using DocBook ####### -->
355 <title>Installing and Using DocBook</title>
357 All documentation for the GNOME project is written in SGML
358 using the DocBook DTD. There are many advantages to using
359 this for documentation, not least of which is the single
360 source nature of SGML. To contribute to the GDP you should
361 learn to use DocBook.
366 To get started writing for the GDP you do not need to rush
367 out and learn DocBook - if you feel it is too much to handle
368 for now, you can submit plain ASCII text to the <ulink
369 url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
370 <citetitle>gnome-doc-list mailing list</citetitle>
371 </ulink>and a volunteer will mark it up for you. Seeing your
372 document marked up will also be a great way for you to start
376 <sect3 id="installingdocbook">
377 <title>Installing DocBook</title>
379 Download and install the following <ulink
380 url="ftp://sourceware.cygnus.com:/pub/docbook-tools/"
381 type="ftp">DocBook Tools packages</ulink>: jade, docbook,
382 jadetex, sgml-common, and stylesheets. (RPM users should note
383 that jade is platform dependent (eg. i386), while the other packages
384 are in the <filename class="directory">noarch</filename>
385 directory.) You can find more
386 information on DocBook Tools <ulink url="
387 http://sourceware.cygnus.com/docbook-tools/"
388 type="http">here</ulink>.
391 If you are an <application>Emacs</application> user you may
392 want to grab the psgml package as well. This is a major mode
393 for editing sgml files in <application>Emacs</application>.
397 <sect3 id="gdpstylesheets">
398 <title>GDP Stylesheets</title>
400 The GDP uses its own DocBook stylesheets. To use the GDP
401 stylesheets, you should download the file
402 <filename>gdp-both.dsl</filename> from the <filename
403 class="directory">gnome-docu/gdp/dsssl</filename> module in
405 url="http://developer.gnome.org/projects/gdp/stylesheets.html">
406 GDP Custom DSSSL Stylesheet</ulink>)and copy it
408 class="directory">/usr/lib/sgml/stylesheets</filename>. You
409 will need to point DocBook Tools to this stylesheet with the
410 <command><option>-d</option></command> option:
411 <command>db2html -d /usr/lib/sgml/stylesheets/gdp-both.dsl
412 <replaceable>foo.sgml</replaceable></command>. (Creating an
413 alias to include this option and path is convenient.)
414 Alternately, you could overwrite
415 <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>
416 with <filename>gdp-both.dsl</filename>.
419 <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>.
420 Alternately, you can download and install the
421 <ulink url="http://people.redhat.com/dcm/software.html"
422 type="http">gnome-doc-tools package</ulink> which will set
423 up the stylesheets as well as the DTD discussed below.
428 The current version of the DocBook Tools command
429 <command>db2ps</command> does not have a
430 <command><option>-d</option></command> option. In order to
431 create PostScript output, you must overwrite
432 <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>
433 with <filename>gdp-both.dsl</filename>.
440 <title>GDP DTD (PNG Image Support)</title>
442 Due to some license issues involved with the creation of
443 gifs, the GNOME Documentation Project has decided to use the
444 PNG image format for all images in GNOME documentation. You
445 can read more about the issues involved with gifs at <ulink
446 url="http://www.gnu.org/philosophy/gif.html"
447 type="http">http://www.gnu.org/philosophy/gif.html</ulink>.
450 The current DocBook DTD(3.1) does not include support for
451 embedding PNG images in your documents. Since the GDP uses
452 many screenshots in its documentation, we use our own
453 variation on the DocBook DTD which has PNG image support.
454 We encourage everybody to use this DTD instead of the
455 default DocBook DTD since your source document header and
456 your output document appearance subtly vary between the two
457 DTD's. To install the GDP custom DTD with PNG image support
460 <itemizedlist mark="opencircle">
464 url="http://www.labs.redhat.com/png/png-support.html">the
465 GDP DocBook DTD for PNG support</ulink> and install it
466 where you keep your DTD's. (On Red Hat use <filename
467 class="directory">/usr/lib/sgml/</filename>.) Note that
468 the 3.0 DTD is missing support for the
469 <sgmltag><legalnotice></sgmltag> tag, so it is
470 recommended that you use version 3.1
473 <listitem override="bullet">
475 Add the new DTD to your SGML CATALOG file. The location
476 of your SGML CATALOG file may vary depending upon your
477 distribution. (On Red Hat it is usually in
478 /usr/lib/sgml/CATALOG.) Add the following line to this
481 PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd"
483 If you are using the 3.1 DTD, use:
485 PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd"
491 Alternately, you can download and install the
492 <ulink url="http://people.redhat.com/dcm/software.html"
493 type="http">gnome-doc-tools package</ulink> which will set
494 up the custom stylesheets and DTD for you.
497 To include PNG files in your documents, you will need to
498 indicate that you are using this special DTD. To do
499 this, use the following headers:
504 <![CDATA[<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant
511 <![CDATA[<!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant
519 <title>Editors</title>
521 There are many editors on Linux and UNIX systems available
522 to you. Which editor you use to work on the sgml documents
523 is completely up to you, as long as the editor is able to
524 preserve sgml and produce the source in a format that is
525 readable by everyone.
528 Probably the two most popular editors available are
529 <application>Emacs</application> and
530 <application>vi</application>. These and other editors are
531 used regularly by members of the GDP. Emacs has a major
532 mode, psgml, for editing sgml files which can save you time
533 and effort in adding and closing tags. You will find the
534 psgml package in DocBook Tools, which is the standard set of
535 tools for the GDP. You may find out more about DocBook Tools
536 in <xref linkend="installingdocbook" />.
540 <sect3 id="make-output">
541 <title>Creating Something Useful with your Docs</title>
543 The tools available in DocBook Tools allow you to convert
544 your sgml document to many different formats including html
545 and Postscript. The primary tool used to do the conversion
546 is an application called <application>Jade</application>. In
547 most cases you will not have to work directly with
548 <application>Jade</application>; Instead, you will use the
549 scripts provided by DocBook Tools.
552 To preview your DocBook document, it is easiest to convert
553 it to <filename>html</filename>. If you have installed the
554 DocBook tools described above, all you have to do is to run
555 the command <prompt>$</prompt><command>db2html
556 mydocument.sgml</command>. If there are no sgml syntax
557 errors, this will create a directory <filename
558 class="directory">mydocument</filename> and place the
559 resulting html files in it. The title page of the document
561 <filename>mydocument/index.html</filename>. If you have
562 screenshots in your document, you will have to copy these
563 files into the <filename
564 class="directory">mydocument</filename> directory by
565 hand. You can use any web browser to view your document.
566 Note that every time you run <command>db2html</command>, it
567 creates the <filename
568 class="directory">mydocument</filename> directory over, so
569 you will have to copy the screenshots over each time.
572 You can also convert your document to PostScript by running
573 the command <prompt>$</prompt><command>db2ps
574 mydocument.sgml</command>, after which you can print out or
575 view the resulting .ps file.
580 The html files you get will not look quite the same as the
581 documentation distributed with GNOME unless you have the
582 custom stylesheets installed on your machine. DocBook
583 Tools' default stylesheets will produce a different look
584 to your docs. You can read more about the GDP stylesheets
585 in <xref linkend="gdpstylesheets" />.
590 <sect3 id="jadeimages">
591 <title>Images in DocBook Tools</title>
593 If your document uses images you will need to take note of a
594 few things that should take place in order for you to make
595 use of those images in your output.
598 The DocBook Tools scripts and applications are smart enough
599 to know that when you are creating html you will be using
600 PNG files and when you are creating Postscript you will be
601 using EPS files (you must use EPS with Postscript).
604 Thus, you should never explicitly
605 include the extension of the image file, since DocBook
606 Tools will automatically insert it for you. For example:
611 <title>My Image</title>
613 <screeninfo>Sample GNOME Display</screeninfo>
614 <graphic format="png" fileref="myfile" srccredit="me">
618 ]]> </programlisting>
620 You will notice in this example that the file
621 <filename>myfile.png</filename> was referred to as simply
622 <filename>myfile</filename>. Now when you run
623 <command>db2html</command> to create an html file, it will
624 automatically look for <filename>myfile.png</filename> in
628 If you want to create PostScript ouput, you will need to create an
629 EPS version of your image file to be displayed in the
630 PostScript file. There is a simple script available which
631 allows you to change a PNG image into an EPS file
632 easily. You can download this file - img2eps - from <ulink
633 url="http://people.redhat.com/dcm/sgml.html"
634 type="html">http://people.redhat.com/dcm/sgml.html</ulink>
635 (look for the img2eps section). Note that this script is
636 included in the gnome-doc-tools package, so if you are using
637 this package, you should already have
638 <command>img2eps</command> on you system.
642 <sect3 id="moredocbookinfo">
643 <title>Learning DocBook</title>
645 There are many resources available to help you learn DocBook.
646 The following resources on the web are useful for learning
649 <itemizedlist mark="bullet">
652 <ulink url="http://www.docbook.org"
653 type="http">http://www.docbook.org</ulink> - Norman
654 Walsh's <citetitle>DocBook: The Definitive
655 Guide</citetitle>. Online O'Reilly book on using
656 DocBook. Contains an excellent element reference. May be
657 too formal for a beginner.
663 url="http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html"
664 type="http">A Practical Introduction to DocBook</ulink>
665 - The Open Source Writers Group's introduction to using
666 DocBook. This is an excellent HOW-TO type article on
673 url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html"
674 type="http">Getting Going with DocBook: Notes for
675 Hackers</ulink> - Mark Galassi's introduction to DocBook
676 for hackers. This has to be one of the first
677 introductions to DocBook ever - still as good as it ever
683 <ulink type="http" url="http://www.freebsd.org/tutorials/docproj-primer/">
684 FreeBSD Documentation Project Primer for New
685 Contributors</ulink> - FreeBSD documentation project
686 primer. Chapter 4.2 provides a very good introduction to
687 writing documentation using DocBook. Note that it also
688 describes some custom extensions of DocBook;
689 fortunately, they are clearly marked as such.
694 Norman Walsh's book is also available in print.
697 The following sections of this document are designed to help
698 documentation authors write correct and consistent DocBook:
700 <itemizedlist mark="bullet">
703 <xref linkend="docbookbasics" /> - Descriptions of
704 commonly used DocBook tags.
709 You may also discuss specific DocBook questions with GDP
710 members on the #docs IRC channel at irc.gnome.org and on the
711 gnome-doc-list mailing list.
716 <!-- ####### Getting Started | GDP Document Examples ####### -->
718 <sect2 id="examples">
719 <title>GDP Document Examples</title>
721 Examples of various types of GNOME documents are found in
722 <xref linkend="examples" />. There is also an example GNOME
723 application with documentation called
724 <application>gnome-hello</application> in GNOME cvs.
728 <!-- ####### Getting Started | GDP Document Templates ####### -->
730 <sect2 id="gdptemplates">
731 <title>GDP Document Templates</title>
733 Templates for various types of GNOME documents are found in
734 <xref linkend="templates" />. They are kept in CVS in
735 gnome-docu/gdp/templates. The easiest source to get them from
736 is probably the <ulink
737 url="http://developer.gnome.org/projects/gdp/templates.html"
739 Document Templates</ulink> web page, which is typically kept
740 completely up-to-date with CVS and has a basic description of
745 <!-- ####### Getting Started | Screenshots ####### -->
747 <sect2 id="screenshots">
748 <title>Screenshots</title>
750 Most GNOME documents will have screenshots of the particular
751 applet, application, GNOME component, or widget being
752 discussed. As discussed above in <xref linkend="gdpdtd"/> you
753 will need to install the special GDP DocBook DTD which
754 supports PNG images, the format used for all images in GNOME
755 documentation. For the basic DocBook structure used to insert
756 images in a document, see <xref linkend="jadeimages"/> above.
758 <sect3 id="screenshotappearance">
759 <title>Screenshot Appearance</title>
761 For all screenshots of windows that typically have border
762 decorations (e.g. applications and dialogs, but not applets
763 in a <interface>panel</interface>), GDP standards dictate
764 the appearance of the window. (This is to minimize possible
765 confusion to the reader, improve the appearance of GNOME
766 documents, and guarantee the screenshot is readable when
767 printed.) All screenshots should be taken with the SawFish
768 (formerly known as Sawmill) window manager using the
769 MicroGui theme and Helvetica 12pt font. (A different window
770 manager can be used provided the MicroGui theme is available
771 for this window manager and the appearance is identical to
772 that when using the SawFish window manager.) The default
773 GTK+ theme(gtk) and font (Helvetica 12 pt) should be used
774 for all screenshots. If you are unable to provide
775 screenshots in this form, you should create screenshots as
776 you wish them to appear and send them to the
777 <ulink url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
778 <citetitle>gnome-doc-list mailing list</citetitle> </ulink>
779 requesting a GDP member reproduce these screenshots in the
780 correct format and email them to you.
783 <sect3 id="screenshottools">
784 <title>Screenshot Tools</title>
786 There are many tools for taking screenshots in
787 GNOME/Linux. Perhaps the most convenient is the
788 <application>Screen-Shooter Applet</application>. Just click
789 on the window icon in the applet and then on the window you
790 would like to take a screenshot of. (Note that
791 at the time of this writing, PNG images taken by
792 screenshooter do not appear properly in
793 <application>Netscape</application> or the
794 <application>GNOME Help Browser</application>. You
795 should save your screenshot as a GIF and
796 then use <command>convert filename.gif
797 filename.png</command>.) For applets
798 in a <interface>Panel</interface>,
799 <application>xv</application> can be used to crop the
800 screenshot to only include the relevant portion of the
801 <interface>Panel</interface>. Note that
802 <application>xv</application> and
803 <application>gimp</application> can both be used for taking
804 screenshots, cropping screenshots, and converting image
808 <sect3 id="screenshotfiles">
809 <title>Screenshot Files</title>
811 Screenshots should be kept in the main documentation
812 directory with your SGML file for applets, or should be
813 kept in a directory called "figs" for application and other
814 documentation. After you use <command>db2html</command> to
815 convert your SGML file to HTML (see <xref
816 linkend="make-output"/>), you will need to copy your
817 screenshots (either the individual PNG files for applet
818 documentation, or the whole "figs" directory for other
819 documentation) into the newly created HTML directory. Note
820 that every time you use <command>db2html</command> the HTML
821 directory is erased and rewritten, so do not store your only
822 copy of the screenshots in that directory. If you wish to
823 create PostScript or PDF output, you will need to manually
824 convert the PNG images to EPS as described in <xref
825 linkend="jadeimages"/>, but will not need to copy these
826 images from their default location, as they are included
827 directly into the output(PostScript of PDF) file.
833 <!-- ####### Getting Started | Application Bugs ####### -->
835 <sect2 id="applicationbugs">
836 <title>Application Bugs</title>
838 Documentation authors tend to investigate and test applets and
839 applications more thoroughly than most
840 users. Often documentation authors will discover one or
841 more bugs in the software. These bugs vary from small ones,
842 such as mis-spelled words or missing
843 <interface>About</interface> dialogs in the menu, to large
844 ones which cause the applet to crash. As all users, you
845 should be sure to report these bugs so that application
846 developers know of them and can fix them. The easiest way to
847 submit a bug report is by using the <application>Bug
848 Buddy</application> applet which is part of the gnome-applets
854 <!-- ####### Getting Started | Using CVS ####### -->
857 <title>Using CVS</title>
859 CVS (Concurrent Versions System) is a tool that allows
860 multiple developers to concurrently work on a set of
861 documents, keeping track of the modifications made by each
862 person. The files are stored on a server and each developer
863 checks files out, modifies them, and then checks in their
864 modified version of the files. Many GNOME programs and
865 documents are stored in CVS. The GNOME CVS server allows
866 users to anonymously check out CVS files. Most GDP members
867 will need to use anonymous CVS to download the most up-to-date
868 version of documentation or programs. Modified documents will
869 typically be emailed to the the application developer. Core
870 GDP members may also be granted login CVS privileges so they
871 may commit modified files directly to CVS.
874 <sect3 id="anonymouscvs">
875 <title>Anonymous CVS</title>
877 To anonymously check out documents from CVS, you must first
878 log in. From the bash shell, you should set your CVSROOT
879 shell variable with <command> export
880 CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</command>
881 and then login with <command>cvs login</command>(there is no
882 password, just hit return). As an example, we will use the
883 "gnome-docu/gdp" module which contains this and several
884 other documents. To check these documents out for the first
885 time, type <command>cvs -z3 checkout
886 gnome-docu/gdp</command>. After you have this document
887 checked out and you would like to download any updates on
888 the CVS server, use <command>cvs -z3 update -Pd</command>.
892 <sect3 id="logincvs">
893 <title>Login CVS</title> <para> If you have been given a
894 login for the GNOME CVS server, you may commit your file
895 modifications to CVS. Be sure to read the following section
896 on CVS etiquette before making any commits to CVS. To log in
897 to the CVS server as user
898 <command><replaceable>username</replaceable></command> with a
899 password, you must first set your CVSROOT shell variable with
901 CVSROOT=':pserver:<replaceable>username</replaceable>@cvs.gnome.org:/cvs/gnome'</command>.
902 Log in with <command>cvs login</command> and enter your
903 password. You may check out and update modules as described
904 above for anonymous CVS access. As a login CVS user, you may
905 also check modified versions of a file into the CVS server.
907 <command><replaceable>filename</replaceable></command> into
908 the CVS server, type <command>cvs -z3 commit
909 <replaceable>filename</replaceable></command>. You will be
910 given a vi editor window to type in a brief log entry,
911 summarizing your changes. The default editor can be changed
912 using the <varname>EDITOR</varname> environment variable or
913 with the <command><option>-e</option></command> option. You
914 may also check in any modifications to files in the working
915 directory and subdirectories using <command>cvs -z3
917 add a new file to the CVS server, use <command>cvs -z3 add
918 <replaceable>filename</replaceable></command>, followed by the
923 <sect3 id="cvsetiquette">
924 <title>CVS Etiquette</title>
926 Because files in CVS are typically used and modified by
927 multiple developers and documentation authors, users should
928 exercise a few simple practices out of courtesy towards the
929 other CVS users and the project leader. First, you should
930 not make CVS commits to a package without first discussing
931 your plans with the project leader. This way, the project
932 leader knows who is modifying the files and generally, what
933 sort of changes/development is being done. Also, whenever a
934 CVS user commits a file to CVS, they should make an entry in
935 the CVS log and in the <filename>ChangeLog</filename> so
936 that other users know who is making modifications and what
937 is being modified. When modifying files created by others,
938 you should follow the indentation scheme used by the initial
945 <!-- ################# The GNOME Documentation System###############
948 <sect1 id="gnomedocsystem">
949 <title>The GNOME Documentation System</title>
951 <!-- ####### The GNOME Documentation System | The GNOME Help Browser
954 <sect2 id="gnomehelpbrowser">
955 <title>The GNOME Help Browser</title>
957 At the core of the GNOME help system is the <application>GNOME
958 Help Browser</application>. The <application>Help
959 Browser</application> provides a unified interface to several
960 distinct documentation systems on Linux/Unix systems: man
961 pages, texinfo pages, Linux Documentation Project(LDP)
962 documents, GNOME application documentation, and other GNOME
966 The <application>GNOME Help Browser</application> works by
967 searching standard directories for documents which are to be
968 presented. Thus, the documentation that appears in the GHB is
969 specific to each computer and will typically only represent
970 software that is installed on the computer.
974 <!-- ####### The GNOME Documentation System | The GNOME Help Browser
977 <sect2 id="gnomehelpbrowser2">
978 <title>The GNOME Help Browser (GNOME-2.0)</title> <para> In
979 GNOME 2.0, the <application>GNOME Help Browser</application>
980 will be replaced by <application>Nautilus</application>.
981 Nautilus will be the file manager/graphical shell for GNOME 2.0
982 and will also implement a more sophisticated help system than
983 that used by the <application>GNOME Help Browser</application>
984 used in GNOME 1.0. It will read and display DocBook files
985 directly, avoiding the need for duplicating documents in both
986 DocBook and HTML formats. Its display engine for DocBook will
987 be much faster than running <application>jade</application> to
988 convert to HTML for rendering. Because it uses the original
989 DocBook source for documentation, it will be possible to do more
990 sophisticated searching using the meta information included in
991 the documents. And since Nautilus is a virtual file system
992 layer which is Internet-capable, it will be able to find and
993 display documents which are on the web as well as those on the
994 local file system. For more information on
995 <application>Nautilus</application>, visit the #nautilus IRC
996 channel on irc.gnome.org. </para>
999 <!-- ####### The GNOME Documentation System | GNOME On-The-Fly
1000 Documentation Generation ####### -->
1002 <sect2 id="gnomehelponthefly">
1003 <title>Dynamic Document Synthesis(GNOME-2.0)</title>
1005 GNOME uses the documentation presented by all the various
1006 GNOME components and applications installed on the system to
1007 present a complete and customized documentation environment
1008 describing only components which are currently installed on a
1009 users system. Some of this documentation, such as the manuals
1010 for applets, will be combined in such a way that it appears to
1011 be a single document.
1014 By using such a system, you can be sure that any GNOME app you
1015 install that has documentation will show up in the index,
1016 table of contents, any search you do in the help browser.
1020 <!-- ####### The GNOME Documentation System | The GNOME Documentation
1021 Components ####### -->
1023 <sect2 id="gnomehelpcomponents">
1024 <title>The GNOME Documentation Components</title>
1026 <sect3 id="applicationmanualsintro">
1027 <title>Application Manuals</title>
1029 Every GNOME application should have an application manual.
1030 An application manual is a document specific to the
1031 particular application which explains the various windows
1032 and features of the application. Application Manuals
1033 typically use screenshots (PNG format) for clarity. Writing
1034 application manuals is discussed in more detail in <xref
1035 linkend="writingapplicationmanuals" /> below.
1039 <sect3 id="applicationhelpintro">
1040 <title>Application Help</title>
1042 Applications should have a <guibutton>Help</guibutton>
1043 button on screens on which users may need help. These
1044 <guibutton>Help</guibutton> buttons should pull up the
1045 default help browser, determined by the
1046 <varname>ghelp</varname> URL Handler (configured using the
1047 <application>Control Center</application>), typically the
1048 <application>GNOME Help Browser</application>. The help
1049 browser should show either the first page of the application
1050 manual, or else the relevant page thereof. Application help
1051 is described in more detail in <xref
1052 linkend="applicationhelpbuttons" /> below.
1056 <sect3 id="contextsensitivehelpintro">
1057 <title>Application Context Sensitive Help (coming in
1060 Context sensitive help is a system which will allow the user
1061 to query any part (button, widget, etc.) of an application
1062 window. This is done by either entering a CS Help mode by
1063 clicking on an icon or by right clicking on the application
1064 part and selecting "What's This" or whatever is decided on
1065 at the time. Context sensitive help is described in more
1066 detail in <xref linkend="writingcontextsensitivehelp" />
1071 <sect3 id="userguide">
1072 <title>The GNOME User Guide</title>
1074 The <citetitle>GNOME User Guide</citetitle> describes the
1075 GNOME desktop environment and core components of GNOME such
1076 as the <application>panel</application> and
1077 <application>control center</application>. In GNOME 1.x this
1078 was the main and only source of documentation. In GNOME 2.0
1079 this will become a document for the web and for printing
1080 that is derived from various parts chosen in the system that
1081 are necessary for the new user to understand.
1085 <sect3 id="userdocs">
1086 <title>User Documents</title>
1088 Aside from the <citetitle>GNOME User Guide</citetitle>,
1089 there are several other documents to help GNOME users learn
1090 GNOME, including the <citetitle>GNOME FAQ</citetitle>,
1091 <citetitle>GNOME Installation and Configuration
1092 Guide</citetitle>, and the <citetitle>GNOME Administrators
1097 <sect3 id="developerdocs">
1098 <title>Developer Documents</title>
1100 There are many White Papers, Tutorials, HOWTO's and FAQ's to
1101 make programming GNOME and GNOME applications as easy as
1105 API documentation is also available for the GNOME libraries. This is
1106 detailed documentation of the code that is used to build GNOME
1107 apps. You can keep up with the GNOME API docs on the <ulink
1108 url="http://developer.gnome.org/doc/API/" type="http">GNOME API
1109 Reference</ulink> page.
1113 <sect3 id="projectdocs">
1114 <title>Project Documents</title>
1116 Some GNOME projects have documentation to maintain
1117 consistency in their product and to help new contributors
1118 get up to speed quickly. Among these are the GDP documents,
1119 such as the one you are reading now.
1126 <!-- ################# DocBook Basics ############### -->
1128 <sect1 id="docbookbasics">
1129 <title>DocBook Basics </title>
1130 <!-- ####### DocBook Basics | Introduction to DocBook ####### -->
1132 <sect2 id="introtodocbook">
1133 <title>Introduction to DocBook</title>
1135 To understand DocBook, a basic understanding of SGML is
1136 helpful. SGML stands for Standard General Markup Language and
1137 is one of the first markup languages every created. HTML is
1138 actually derived from SGML and XML is a subset of SGML. SGML
1139 uses what is called a Document Type Definition to specify
1140 <emphasis>elements</emphasis> which are contained between
1141 brackets, < and >. Text is marked by both beginning and
1142 ending elements, for example in the DocBook DTD, one denotes a
1143 title with <sgmltag><title></sgmltag>The
1144 Title<sgmltag></title></sgmltag>.
1147 The DTD (in the case of the GDP, DocBook) defines rules for how the
1148 elements can be used. For example, if one element can only be used when
1149 embedded within another, this is defined in the DTD.
1152 An SGML file is just a plain ASCII file containing the text
1153 with the markup specified above. To convert it to some easily
1154 readable format, you need special tools. The GDP uses <emphasis>DocBook
1155 Tools</emphasis>, a free package of utilities for working with DocBook
1156 which includes <emphasis>Jade</emphasis>, which does the SGML/DSSL
1157 parsing. You can read more about DocBook Tools in <xref
1158 linkend="installingdocbook" />.
1161 The final appearance of the output (e.g. PostScript or HTML)
1163 <emphasis>stylesheet</emphasis>. Stylesheets are files,
1164 written in a special language (DSSSL — Document Style
1165 Semantics and Specification Language), which specify the
1166 appearance of various DocBook elements, for example,
1167 what fonts to use for titles and various inline elements, page
1168 numbering style, and much more. DocBook tools come with a
1169 collection of stylesheets (Norman Walsh's modular
1170 stylesheets); GNOME Document Project uses some customized
1171 version of this stylesheets — see <xref
1172 linkend="gdpstylesheets"/>.
1175 The advantage of specifying the <emphasis>structure</emphasis>
1176 of a document with SGML instead of specifying the
1177 <emphasis>appearance</emphasis> of the document with a typical
1178 word processor, or with html, is that the resulting document
1179 can be processed in a variety of ways using the structural
1180 information. Whereas formatting a document for appearance
1181 assumes a medium (typically written text on a standard-sized
1182 piece of paper), SGML can be processed to produce output for a
1183 large variety of media such as text, postscript, HTML,
1184 Braille, audio, and potentially many other formats.
1187 Using 'content' as the elements to define the text of a document also
1188 allows for search engines to make use of the actual elements to make a
1189 "smarter search". For example, if you are searching for all documents
1190 written by the author "Susie" your search engine could be made smart
1191 enough to only search <author> elements, making for a faster and more
1195 Since the overall appearance of the output is determined not by the DTD
1196 or the SGML document, but rather by a stylesheet, the appearance of a
1197 document can be easily changed just by changing the stylesheet. This
1198 allows everyone in the project to create documents that all look the
1202 As stated before, the GDP uses the DocBook DTD. For a list of
1203 introductory and reference resources on DocBook, see <xref
1204 linkend="resources" />. The following sections also provide
1205 convenient instructions on which markup tags to use in various
1206 circumstances. Be sure to read <xref linkend="conventions" />
1207 for GDP documentation-specific guidelines.
1211 <!-- ###### DocBook Basics | XML and SGML ########-->
1213 <title>XML and SGML</title>
1215 <para> In not so distant future (probably before GNOME 2.0),
1216 DocBook itself and GNOME Documentation project will migrate from
1217 SGML to XML. This transition should be relatively painless:
1218 (almost) all DocBook tags will remain the same. However, XML has
1219 stricter syntax rules than SGML; thus, some constructions which
1220 are valid in SGML will not be valid in XML. Therefore, to be
1221 ready for this transistion, it is <emphasis>strongly
1222 advised</emphasis> that the documentation writers conform to XML
1223 syntax rules. Here are most important differences:
1228 <term> <emphasis>Minimization</emphasis></term>
1232 It is possible with some implementations of SGML to use
1233 minimizations to close elements in a document by using
1234 </>, for example:
1235 <literal><sgmltag><title></sgmltag>The
1236 Title<sgmltag></></sgmltag></literal>. This is not
1237 allowed in XML. You can use <command>sgmlnorm</command> command,
1238 included in DocBook Tools package, to expand minimized tags;
1239 if you are using <application>Emacs</application> with psgml
1240 mode, you can also use menu command
1242 <guimenu>Modify</guimenu>
1243 <guimenuitem>Normalize</guimenuitem>
1249 <term> <emphasis>Self-closing tags</emphasis></term>
1253 Also, in SGML some tags are allowed not to have closing
1254 tags. For example, it is legal for
1255 <sgmltag><xref></sgmltag> not to have a closing tag:
1256 <literal><sgmltag><xref
1257 linkend="someid"></sgmltag></literal>. In
1258 XML, it is illegal; instead, you should use
1259 <literal><sgmltag><xref
1260 linkend="someid"/></sgmltag></literal> (note the
1267 <term> <emphasis>Case sensitive tags</emphasis></term>
1270 In XML, unlike SGML, tags are case-senstive
1271 <sgmltag><title></sgmltag> and
1272 <sgmltag><TITLE></sgmltag> are different tags!
1273 Therefore, please always use lowercase tags (except for
1274 things like <literal>DOCTYPE, CDATA</literal> and
1275 <literal>ENTITY</literal>, which are not DocBook tags).
1287 <!-- ####### DocBook Basics | Structure Elements ####### -->
1290 <sect2 id="structure"> <title> Structure Elements</title>
1292 <sect3 id="section">
1293 <title>Sections and paragraphs</title>
1295 Top-level element of a book body must be
1296 <sgmltag><chapter></sgmltag>; it may contain one or more
1297 <sgmltag><sect1></sgmltag>, each of them may contain
1298 <sgmltag><sect2></sgmltag> and so on up to
1299 <sgmltag><sect5></sgmltag>. The top-level element of an
1300 article body is always
1301 <sgmltag><sect1></sgmltag>. Regardless of which elements
1302 you use, give each structural element a unique id, so that
1303 you can link to it. For usage example, see the template.
1305 <para> Please try to avoid using deeply nested sections; for
1306 most situations, <sgmltag><sect1></sgmltag> and
1307 <sgmltag><sect2></sgmltag> should be sufficient. If not,
1308 you probably should split your <sgmltag><sect1></sgmltag>
1309 into several smaller ones.
1311 <para> Use the tag <sgmltag><para></sgmltag> for
1312 paragraphs, even if there is only one paragraph in a
1313 section—see template for examples.
1318 <title>Notes, Warnings, And Tips</title>
1320 For notes, tips, warnings, and important information, which
1321 should be set apart from the main text (usually as a
1322 paragraph with some warning sign on the margin), use tags
1323 <sgmltag><note></sgmltag>, <sgmltag><tip></sgmltag>,
1324 <sgmltag><warning></sgmltag>,
1325 <sgmltag><important></sgmltag> respectively. For example:
1331 To speed up program compilation, use <application>gcc</application>
1332 compiler with Pentium optimization.
1334 </tip>]]> </programlisting> produces
1339 To speed up program compilation, use
1340 <application>gcc</application> compiler with Pentium
1341 optimization. </para>
1344 Note that this should not be inside a
1345 <sgmltag><para></sgmltag> but between paragraphs.
1348 <sect3 id="figures">
1349 <title> Screenshots and other figures</title>
1351 To include screenshots and other figures, use the following
1357 <title>Screenshot</title>
1359 <screeninfo>Screenshot of a program</screeninfo>
1360 <graphic format="PNG" fileref="figures/example_screenshot" srccredit="ME">
1365 replacing <filename>example_screenshot</filename> with the
1366 actual file name (without extension). The result will look like this:
1369 <title>Screenshot</title>
1371 <screeninfo>Screenshot of a program</screeninfo>
1372 <graphic format="PNG"
1373 fileref="figures/example_screenshot" srccredit="ME"/>
1381 Notice in this example that the screenshot file name does
1382 not include the file type extension — to find out
1383 why, please read <xref linkend="jadeimages" />.
1387 <sect3 id="listing">
1388 <title>Program listings and terminal session</title> <para>
1389 To show a file fragment—for example, program
1390 listing—use <sgmltag><programlisting></sgmltag> tag:
1395 Name=Gnumeric spreadsheet
1397 Icon=gnome-gnumeric.png
1400 </programlisting>]]>
1405 Name=Gnumeric spreadsheet
1407 Icon=gnome-gnumeric.png
1411 As a matter of fact, all examples in this document were
1412 produced using <sgmltag><programlisting></sgmltag>.
1415 To show a record of terminal session—i.e., sequence of
1416 commands entered at the command line—use
1417 <sgmltag><screen></sgmltag> tag:
1421 <prompt>bash$</prompt><userinput>make love</userinput>
1422 make: *** No rule to make target `love'. Stop.
1427 <prompt>bash$</prompt><userinput>make love</userinput>
1428 make: *** No rule to make target `love'. Stop.
1430 Note the use of tags <sgmltag><prompt></sgmltag> and
1431 <sgmltag><userinput></sgmltag> for marking system prompt
1432 and commands entered by user.
1436 Note that both <sgmltag><programlisting></sgmltag>
1437 and <sgmltag><screen></sgmltag> preserve linebreaks,
1438 but interpret SGML tags (unlike LaTeX
1439 <markup>verbatim</markup> environment). Take a look at
1440 the source of this document to see how you can have SGML
1441 tags literally shown but not interpreted,
1447 <title> Lists</title>
1449 The most common list types in DocBook are
1450 <sgmltag><itemizedlist></sgmltag>,
1451 <sgmltag><orderedlist></sgmltag>, and
1452 <sgmltag><variablelist></sgmltag>.
1456 <term> <sgmltag><itemizedlist></sgmltag></term>
1458 This is the simplest unnumbered list, parallel to
1459 <sgmltag><ul></sgmltag> in HTML. Here is an example:
1465 <guilabel>Show backup files</guilabel> — This will
1466 show any backup file that might be on your system.
1471 <guilabel>Show hidden files</guilabel> — This will
1472 show all "dot files" or files that begin with a dot. This
1473 files typically include configuration files and directories.
1478 <guilabel>Mix files and directories</guilabel> — This
1479 option will display files and directories in the order you
1480 sort them instead of
1481 always having directories shown above files.
1492 <guilabel>Show backup files</guilabel> —
1493 This will show any backup file that might be on
1500 <guilabel>Show hidden files</guilabel> —
1501 This will show all "dot files" or files that
1502 begin with a dot. This files typically include
1503 configuration files and directories.
1509 <guilabel>Mix files and directories</guilabel>
1510 — This option will display files and
1511 directories in the order you sort them instead
1512 of always having directories shown above files.
1516 <para> Note the use of <sgmltag>&mdash;</sgmltag>
1517 for long dash (see <xref linkend="specsymb" />). Also,
1518 please note that the result looks much nicer because the
1519 terms being explained (<guilabel>Show backup
1520 files</guilabel>, etc.) are set in a different font. In
1521 this case, it was achieved by using <link
1522 linkend="gui"><sgmltag><guilabel></sgmltag></link>
1523 tag. In other cases, use appropriate tags such as
1524 <link linkend="gui"><sgmltag><guimenuitem></sgmltag></link>,
1526 linkend="filenames"><sgmltag><command></sgmltag></link>,
1527 or — if none of
1528 this applies — use
1529 <link linkend="gui"><sgmltag><emphasis></sgmltag></link>.
1534 <term> <sgmltag><orderedlist></sgmltag></term>
1536 This list is completely analogous to
1537 <sgmltag><itemizedlist></sgmltag> and has the same
1538 syntax, but it produces numbered list. By default,
1539 this list uses Arabic numerals for numbering entries;
1540 you can override this using <sgmltag>numeration</sgmltag>,
1541 for example <sgmltag><orderedlist
1542 numeration="lowerroman"></sgmltag>. Possible values of
1543 these attribute are <sgmltag>arabic</sgmltag>,
1544 <sgmltag>upperalpha</sgmltag>,
1545 <sgmltag>loweralpha</sgmltag>,
1546 <sgmltag>upperroman</sgmltag>,
1547 <sgmltag>lowerroman</sgmltag>.
1552 <term> <sgmltag><variablelist></sgmltag></term>
1553 <listitem><para> This list is used when each entry is
1554 rather long, so it should be formatted as a block of text
1555 with some subtitle, like a small subsection. The
1556 <sgmltag><variablelist></sgmltag> is more complicated
1557 than itemizedlists, but for larger blocks of text, or when
1558 you're explaining or defining something, it's best to use
1559 them. Their greatest advantage is that it's easier for a
1560 computer to search. The lines you are reading now were
1561 produced by <sgmltag><variablelist></sgmltag>. The
1562 source looked liked this:
1567 <term> <sgmltag><itemizedlist></sgmltag></term>
1569 This is the simplest unnumbered list, parallel to
1570 <sgmltag><ul></sgmltag> in HTML. Here is an example:...
1574 <term> <sgmltag><orderedlist></sgmltag></term>
1576 This list is completely analogous to
1577 <sgmltag><itemizedlist></sgmltag>
1581 <term> <sgmltag><variablelist></sgmltag></term>
1583 This list is used when each entry is rather long,...
1594 Lists can be nested; in this case, the stylesheets
1595 are smart enough to change the numeration (for
1596 <sgmltag><orderedlist></sgmltag>) or marks of each entry
1597 (in <sgmltag><itemizedlist></sgmltag>) for sub-lists
1603 <!-- ####### DocBook Basics | Inline Elements ####### -->
1606 <title>Inline Elements</title>
1609 <title>GUI elements</title>
1613 <sgmltag><guibutton></sgmltag> — used for
1614 buttons, including checkbuttons and radio buttons
1620 <sgmltag><guimenu></sgmltag>,
1621 <sgmltag><guisubmenu></sgmltag> —used for
1622 top-level menus and submenus
1623 respectively, for example <literal><![CDATA[
1624 <guisubmenu>Utilities</guisubmenu> submenu of the
1625 <guimenu>Main Menu</guimenu>]]></literal>
1631 <sgmltag><guimenuitem></sgmltag>—an entry in a
1638 <sgmltag><guiicon></sgmltag>—an icon
1644 <sgmltag><guilabel></sgmltag>—for items which have
1645 labels, like tabs, or bounding boxes.
1650 <sgmltag><interface></sgmltag>— for most everything
1651 else... a window, a dialog box, the Panel, etc.
1656 If you need to refer to a sequence of menu choices, such as
1658 <guimenu>Main Menu</guimenu>
1659 <guisubmenu>Utilities</guisubmenu> <guimenuitem>GNOME
1660 terminal</guimenuitem>
1662 there is a special construction for this, too:
1666 <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
1667 <guimenuitem>GNOME terminal</guimenuitem> </menuchoice>]]>
1673 <title>Links and references</title>
1675 To refer to another place in the same document, you can use
1676 tags <sgmltag><xref></sgmltag> and
1677 <sgmltag><link></sgmltag>. The first of them
1678 automatically inserts the full name of the element you refer
1679 to (section, figure, etc.), while the second just creates a
1680 link (in HTML output). Here is an example:
1682 <![CDATA[An example of a <link linkend="extip">tip</link> was given in
1683 <xref linkend="notes" />. ]]>
1685 which produces: An example of a <link
1686 linkend="extip">tip</link> was given in <xref
1690 Here <sgmltag>notes</sgmltag> and <sgmltag>extip</sgmltag>
1691 are the id attributes of <xref linkend="notes" /> and of the
1692 example of a tip in it.
1694 <para> To produce a link to an external source, such as a
1695 Web page or a local file, use <sgmltag><ulink></sgmltag>
1698 <![CDATA[ To find more about GNOME, please visit <ulink type="http"
1699 url="http://www.gnome.org">GNOME Web page</ulink> ]]>
1701 which produces: To find more about GNOME, please visit
1702 <ulink type="http" url="http://www.gnome.org">The GNOME Web
1703 Site</ulink> You can use any of the standard URL types, such
1704 as <literal>http, ftp, file, telnet, mailto</literal> (in
1705 most cases, however, use of <literal>mailto</literal> is
1706 unnecessary—see discussion of
1707 <sgmltag><email></sgmltag> tag).
1711 <sect3 id="filenames"> <title>Filenames, commands, and other
1712 computer-related things</title>
1714 Here are some tags used to describe operating system-related
1719 <para> <sgmltag><filename></sgmltag> — used
1721 e.g.<sgmltag><filename></sgmltag>
1723 <sgmltag></filename></sgmltag>
1724 produces: <filename>foo.sgml</filename>.
1728 <para> <sgmltag><filename
1729 class="directory"></sgmltag> — used for
1730 directories, e.g.<sgmltag><filename
1731 class="directory"></sgmltag>/usr/bin
1732 <sgmltag></filename></sgmltag>
1734 class="directory">/usr/bin</filename>.
1739 <sgmltag><application></sgmltag> — used for
1741 e.g. <sgmltag><application></sgmltag>Gnumeric
1742 <sgmltag></application></sgmltag> produces:
1743 <application>Gnumeric</application>.
1748 <sgmltag><envar></sgmltag> — used for
1749 environment variables, e.g.
1750 <sgmltag><envar></sgmltag>PATH<sgmltag></envar></sgmltag>.
1756 <sgmltag><command></sgmltag> — used for
1757 commands entered on command line, e.g.
1758 <sgmltag><command></sgmltag>make install
1759 <sgmltag></command></sgmltag> produces:
1760 <command>make install</command>.
1765 <sgmltag><replaceable></sgmltag> — used for
1766 replaceable text, e.g.
1767 <sgmltag><command></sgmltag>db2html<sgmltag><replaceable></sgmltag>
1769 <sgmltag></replaceable></sgmltag><sgmltag></command></sgmltag>
1770 produces: <command>db2html
1771 <replaceable>foo.sgml</replaceable></command>.
1778 <title>Keyboard input</title>
1779 <para> To mark up text input by the user, use
1780 <sgmltag><userinput></sgmltag>.
1782 <para> To mark keystrokes such as shortcuts and other
1783 commands, use <sgmltag><keycap></sgmltag>.
1784 This is used for marking up what is printed on the top
1785 of the physical key on the keyboard. There are a couple of
1786 other tags for keys, too: <sgmltag><keysym></sgmltag>
1787 and <sgmltag><keycode></sgmltag>. However you are
1788 unlikely to need these for most documentation. For reference,
1789 <sgmltag><keysym></sgmltag> is for the <quote>symbolic
1790 name</quote> of a key. <sgmltag><keycode></sgmltag> is
1791 for the <quote>scan code</quote> of a key. These are not
1792 terms commonly required in <acronym>GNOME</acronym> documentation,
1793 although <sgmltag><keysym></sgmltag> is useful for marking
1797 To mark up a combination of keystrokes, use the
1798 <sgmltag><keycombo></sgmltag> wrapper:
1802 <keycap>Ctrl</keycap>
1803 <keycap>Alt</keycap>
1809 Finally, if you want to show a shortcut for some menu
1810 command, here are the appropriate tags (rather long):
1815 <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
1817 <guimenuitem> Quit</guimenuitem>
1820 which produces simply
1822 <shortcut> <keysym>Ctrl-q</keysym> </shortcut>
1823 <guimenuitem> Quit</guimenuitem>
1829 <title>E-mail addresses</title> <para> To mark up e-mail
1830 address, use <sgmltag><email></sgmltag>:
1832 <![CDATA[ The easiest way to get in touch with me is by e-mail
1833 (<email>me@mydomain.com</email>)]]>
1835 which produces: The easiest way to get in touch with me is
1836 by e-mail (<email>me@mydomain.com</email>) Note that
1837 <sgmltag><email></sgmltag> automatically produces a link
1842 <sect3 id="specsymb">
1843 <title> Special symbols </title>
1845 DocBook also provides special means for entering
1846 typographic symbols which can not be entered directly
1847 form the keyboard (such as copyright sign). This is done using
1848 <emphasis>entities</emphasis>, which is SGML analogue of
1849 macros, or commands, of LaTeX. They generally have the form
1850 <sgmltag>&entityname;</sgmltag>. Note that the semicolon
1854 here is partial list of most commonly used enitites:
1858 <sgmltag>&amp;</sgmltag> — ampersend (&)
1861 <sgmltag>&lt;</sgmltag> — left angle bracket (<)
1864 <sgmltag>&copy;</sgmltag> — copyright sign (©)
1867 <sgmltag>&mdash;</sgmltag> — long dash (—)
1870 <sgmltag>&hellip;</sgmltag> — ellipsis (…)
1874 Note that the actual look of the resulting symbols depends
1875 on the fonts used by your browser; for example, it might
1876 happen that long dash (<sgmltag>&mdash;</sgmltag>) looks
1877 exactly like the usual dash (-). However, in the PostScript
1878 (and thus, in print) the output will look markedly better if
1879 you use appropriate tags.
1885 <!-- ################# GDP Documentation Conventions ############### -->
1887 <sect1 id="conventions">
1888 <title>GDP Documentation Conventions </title>
1890 <!-- ####### GDP Documentation Conventions | All Documentation ####### -->
1892 <sect2 id="conventionsalldocs">
1893 <title>Conventions for All GDP Documentation</title>
1894 <sect3 id="xmlcomp">
1895 <title> XML compatibility </title>
1897 All GNOME documentation should conform to XML syntax
1898 requirements, which are stricter than SGML ones — see
1899 <xref linkend="xml" /> for more informaion.
1903 <sect3 id="authorsnames">
1904 <title> Authors' names</title>
1906 All GNOME documentation should contain the names of both the
1907 application authors and documentation authors, as well as a
1908 link to the application web page (if it exists) and
1909 information for bug submission — see templates for an
1915 <!-- ####### GDP Documentation Conventions | All Documentation ####### -->
1917 <sect2 id="conventionsappdocs">
1918 <title>Conventions for Application Documentation</title>
1920 <sect3 id="applicationversionid">
1921 <title>Application Version Identification</title>
1923 Application documentation should identify the version of the
1924 application for which the documentation is written:
1928 <title>Introduction</title>
1930 blah-blah-blah This document describes version 1.0.53 of gfoo.
1936 <sect3 id="license">
1937 <title> Copyright information </title>
1939 documentation should contain a copyright notice, stating the
1940 licensing terms. It is suggested that you use the GNU Free
1941 Documentation License. You could also use some other license
1942 allowing free redistribution, such as GPL or Open Content
1943 license. If documentation uses some trademarks (such as UNIX,
1944 Linux, Windows, etc.), proper legal junk should also be
1945 included (see templates).
1948 <sect3 id="license2">
1949 <title>Software license</title>
1951 All GNOME applications must contain information about the
1952 license (for software, not for documentation), either in the
1953 "About" box or in the manual.
1957 <sect3 id="bugtraq">
1958 <title> Bug reporting</title>
1960 Application documentation should give an address for
1961 reporting bugs and for submitting comments about the
1962 documentaion (see templates for an example).
1968 <!-- ################# Writing Application Manuals ###############-->
1970 <sect1 id="writingapplicationmanuals">
1971 <title>Writing Application and Applet Manuals</title>
1973 Every GNOME application or applet should have a manual specific
1974 to that particular application. This manual should be a complete
1975 and authoritative guide. The manual should describe what the
1976 program does and how to use it. Manuals will typically describe
1977 each window or panel presented to the user using screenshots (in
1978 PNG format only) when appropriate. They should also describe
1979 each feature and preference option available.
1982 <title>Documentation Availability</title>
1984 Applications and applets should not rely on documentation
1985 which is only available on the internet. All manuals and
1986 other documentation should be packaged with the application or
1987 applet and be made available to the user through the standard
1988 GNOME help system methods described below.
1991 <para> Application manuals should be based on the template in
1992 <xref linkend="template1" />. Applet manuals should be based on
1993 the templates in <xref linkend="template2-1x" /> for GNOME
1994 versions 1.x and the templates in <xref linkend="template2-2x" />
1995 for GNOME versions 2.x.
1998 <title>Manuals For Large Applications</title>
2000 Manuals for very large applications, such as GNOME Workshop
2001 components should be a <sgmltag><book></sgmltag> (and thus
2002 use <sgmltag><chapter></sgmltag> for each primary section)
2003 , instead of <sgmltag><article></sgmltag> which most
2004 applications use(with each primary section being a
2005 <sgmltag><sect1></sgmltag>).
2009 <title>Applet Manuals in GNOME 2.0</title>
2011 Note that applet manuals in GNOME 2.0 are treated in a special
2012 way. The manuals for all applets are merged into a single
2013 virtual document by Nautilus. For this reason, the header
2014 information for applet manuals is omitted and the first
2015 section of each applet is
2016 <sgmltag><sect1></sgmltag>. Applet manuals will typically
2017 have several sections, each of which is
2018 <sgmltag><sect2></sgmltag>.
2022 Application manuals should be made available by having a
2023 "Manual" entry in the <guimenu>Help</guimenu> pull-down menu
2025 application, as described in <xref linkend="listingdocsinhelpmenu" />.
2026 Applets should make their manuals available by
2027 right-clicking on the applet.
2032 <!-- ############### Listing Documents in the Help Menu ############# -->
2034 <sect1 id="listingdocsinhelpmenu">
2035 <title>Listing Documents in the Help Menu</title>
2038 <title>Developer Information</title>
2040 This section is for developers. Documentation authors
2041 generally do not need to know this material.
2045 Typically the application manual and possibly additional help
2046 documents will be made available to the user under the
2047 <guimenu>Help</guimenu> menu at the top right of the
2048 application. To do this, you must first write a
2049 <filename>topic.dat</filename> file. The format for this file is:
2051 One line for each 'topic'.
2053 Two columns, as defined by perl -e 'split(/\s+/,$aline,2)'
2055 First column is the HTML file (and optional section) for the topic,
2056 relative to the app's help file dir.
2058 Second column is the user-visible topic name.
2060 For example, <application>Gnumeric</application>'s
2061 <filename>topic.dat</filename> file is:
2063 gnumeric.html Gnumeric manual
2064 function-reference.html Gnumeric function reference
2066 When the application is installed, the
2067 <filename>topic.dat</filename> file should be placed in the
2069 class="directory">$prefix/share/gnome/help/<replaceable>appname</replaceable>/C/</filename> directory
2070 where <replaceable>appname</replaceable> is replaced by the
2071 application's name. The application documentation (converted
2072 from SGML into HTML with <command>db2html</command>) should be
2073 placed in this directory too.
2077 If the help files are not present in the correct directory, the
2078 menu items will NOT appear when the program is run.
2082 The <filename>topic.dat</filename> file is used by the GNOME
2083 menu building code to generate the <guimenu>Help</guimenu>
2084 menu. When you define your menu:
2086 GnomeUIInfo helpmenu[] = {
2088 N_("About"), N_("Info about this program"),
2089 about_cb, NULL, NULL,
2090 GNOME_APP_PIXMAP_STOCK, GNOME_STOCK_MENU_ABOUT,
2092 GNOMEUIINFO_SEPARATOR,
2093 GNOMEUIINFO_HELP("<emphasis>appname</emphasis>"),
2097 the line specifying <varname>GNOMEUIINFO_HELP</varname> causes
2098 GNOME to create a menu entry which is tied to the documentation
2099 in the directory mentioned above. Also, all the topics in the
2100 <filename>topic.dat</filename> file will get menu entries in the
2101 <guimenu>Help</guimenu> menu. When the user selects any of these
2102 topics from the <guimenu>Help</guimenu> menu, a help browser
2103 will be started with the associated HTML documentation.
2108 <!-- ################# Application Help Buttons ############### -->
2110 <sect1 id="applicationhelpbuttons">
2111 <title>Application Help Buttons</title>
2114 <title>Developer Information</title>
2116 This section is for developers. Documentation authors
2117 generally do not need to know this material.
2121 Most GNOME applications will have <guibutton>Help</guibutton>
2122 buttons. These are most often seen in Preference windows. (All
2123 Preference windows should have <guibutton>Help</guibutton>
2124 buttons.) Most <guibutton>Help</guibutton> buttons will connect
2125 to the application manual, although some may connect to special
2126 documents. Because the <guibutton>Help</guibutton> buttons do
2127 not generally have their own special documentation, the
2128 documentation author(s) do not need to do very much. However,
2129 the application author must be careful to guarantee that the
2130 application correctly opens the help documentation when the
2131 <guibutton>Help</guibutton> buttons are pressed.
2134 To make the Help buttons call the correct document in the GNOME Help
2135 Browser the developer should add code based on the following example:
2139 tmp = gnome_help_file_find_file ("module", "page.html");
2141 gnome_help_goto(0, tmp);
2148 The example above is in the C language, please refer to other
2149 documentation or forums for other GNOME language bindings.
2154 <!-- ################# Packaging Applet Documentation ############### -->
2156 <sect1 id="packagingappletdocs">
2157 <title>Packaging Applet Documentation</title>
2158 <sect2 id="appletfiles">
2159 <title>Applet Documentation Files</title>
2161 In GNOME 2.0 each applet will have its own documentation
2162 installed separately, and the GNOME 2.0 help
2163 browser (<application>Nautilus</application>) will dynamically
2164 merge the applet documents into a single virtual book
2165 called <citetitle>GNOME Applets</citetitle>. During the
2166 transitionary stage between GNOME 1.0 and GNOME 2.0, each
2167 applet in the gnome-applets package has its own manual(stored
2168 with the applet in CVS), but they are merged together manually
2169 to create the <citetitle>GNOME Applets</citetitle> book before
2171 <email>hobbit@aloss.ukuu.org.uk</email> is the maintainer of
2172 this document. Applet documentation should be sent to Telsa
2173 (or placed in CVS) who will make sure they are correctly
2174 packaged with the applets. The applet author should be
2175 contacted to modify the menu items and help buttons to bind to
2176 the applet documentation if necessary.
2179 Images which are part of the applet documentation should be in
2180 PNG format and should reside in the same directory as the SGML
2181 document file in CVS(gnome-applets/APPLETNAME/help/C).
2184 Applets which are not part of the gnome-applets package must
2185 package their documentation with the particular applet
2186 package. They should use the same applet template as other
2187 applets. However, the <sgmltag><xref></sgmltag> links to
2188 the introductory chapter of the <citetitle>GNOME
2189 Applets</citetitle> book must be removed (as the 1.x
2190 <application>GNOME Help Browser</application> does not allow
2191 you to create links between separate documents) and replaced
2192 with suitable text. Note that since this document is not part
2193 of the <citetitle>GNOME Applets</citetitle> book, you must
2194 remember to add <sgmltag><legalnotice></sgmltag> and
2195 <sgmltag><copyright></sgmltag> sections.
2199 <sect2 id="appletmenu">
2200 <title>Adding Documentation to an Applet Menu</title>
2202 <title>Developer Information</title>
2204 This section is for developers. Documentation authors
2205 generally do not need to know this material.
2209 Applets should have <guimenu>About</guimenu> and
2210 <guimenu>Manual</guimenu> menu items, typically as the first
2211 and second top-most items in the menu respectively. This
2212 section describes how the developer creates these menu items
2213 and links them to the documentation.
2216 To add an applet's manual to its applet menu, use:
2218 /* add an item to the applet menu */
2219 applet_widget_register_callback(APPLET_WIDGET(applet), "manual",
2220 _("Manual"), &open_manual, NULL);
2222 Here the second argument is an arbitrary name for the
2223 callback, the third argument is the label which will appear
2224 when the user right clicks on the applet, and the fourth
2225 argument is the callback function.
2228 You will need to write a simple callback function to open the
2229 help browser to the appropriate document. This is done using
2230 the <function>gnome_help_file_find_file</function> function,
2231 as described in <xref linkend="applicationhelpbuttons" />.
2234 You will also want to add an <guimenu>About</guimenu> menu
2235 item to the applet's menu. This is a
2236 stock menu item and is done:
2238 applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about",
2239 GNOME_STOCK_MENU_ABOUT, _("About"), &my_applet_cb_about,
2244 More information can be found at <ulink type="http"
2245 url="http://developer.gnome.org/doc/tutorials/applet/index.html">Writing
2246 GNOME panel applets using the GTK+/GTK-- widget set</ulink>.
2252 <!-- ################# Writing Context Sensitive Help ###############
2255 <sect1 id="writingcontextsensitivehelp">
2256 <title>Writing Context Sensitive Help (coming in GNOME-2.0)</title>
2258 Context sensitive help, also known as "pop-up" help, will allow
2259 a user to obtain help information about specific buttons or
2260 parts of an application.
2263 Context sensitive help is still under development and not all
2264 the details are available at this time. However, the basics can
2265 be shown here so that you can understand how the system will
2269 The Context Sensitive Help system is designed to allow the
2270 developer to give an id to a particular portion of the User
2271 Interface, for example, a button. Once the interface is complete
2272 a Perl script can then be run against the interface code to
2273 create a "map" file. This map file allows the developer or
2274 writer to associate particular paragraph sections from an XML
2275 document to the interface items.
2278 The XML used for the document is a small XML DTD that is being
2279 developed to use the same tags (albeit, much fewer) as DocBook
2280 so that writers do not have to re-learn a new DTD.
2283 Once the document is written and map file is complete, when the
2284 user launches context sensitive help on the interface (either by
2285 pressing a button and then clicking on the interface item they
2286 want information on, or by right mouse clicking on the interface
2287 item and selecting a pop-up menu item like "What's This") a
2288 small transient window will appear with brief but detailed
2289 information on the interface item.
2293 <!-- ################# Referring to Other GNOME Documentation
2296 <sect1 id="referring">
2297 <title>Referring to Other GNOME Documentation (coming in
2300 In the GNOME 2.0 Help System, you will be able to create links
2301 from one document to another. The exact mechanism for doing
2302 this is in development.
2307 <!-- ################# Basics of Documentation Style ############### -->
2310 <title>Basics of Documentation Style</title>
2312 Most people have never enjoyed reading a software manual, and
2313 they probably never will. Many times, they'll read the
2314 documentation only when they run into problems, and they'll be
2315 frustrated and upset before they even read a word. On the
2316 other hand, some readers will read the manual all the way
2317 through, or at least look at the introduction before they
2318 start. Your document might serve as a reference for an expert
2319 or a guide to a beginner, and it must have enough depth to
2320 satisfy the first without overwhelming the second. Ideally, it
2321 will serve beginners as they <emphasis>become</emphasis>
2322 experts. Remember, your goal is to produce <emphasis>complete,
2323 intuitive and clear</emphasis> documentation.
2326 In order to write useful documentation, you'll have to know who
2327 your audience is likely to be. Then, you can look for the
2328 problems they're likely to run into, and solve them. It will
2329 also help if you focus on the tasks users will perform, and
2330 group features accordingly, rather than simply describing
2334 <!-- *********** Basics of Documentation Style: planning -->
2336 <sect2 id="styleplanning">
2337 <title>Planning</title>
2339 Begin documenting by learning how to use the application and
2340 reading over any existing documentation. Pay attention to
2341 places where your document will differ from the template. It
2342 may help to develop a document skeleton: a valid XML or SGML
2343 document that has little or no content. For very large
2344 applications, you will need to make significant departures
2345 from the templates, since you'll be using the
2346 <sgmltag><book></sgmltag> tag instead of
2347 <sgmltag><chapter></sgmltag> or
2348 <sgmltag><article></sgmltag>.
2353 <!-- ####### Basics of Documentation Style | Balance ####### -->
2354 <sect2 id="balance">
2355 <title>Achieving a Balanced Style</title>
2358 Just as you need to juggle expert and novice readers,
2359 you'll have to juggle a number of other extremes as you write:
2363 Documents should be complete, yet concise. You should
2364 describe every feature, but you'll have decide how much
2365 detail is really necessary. It's not, for example,
2366 necessary to describe every button and form field in a
2367 dialog box, but you should make sure that your readers
2368 know how to bring up the dialog and what it does. If
2369 you spend fewer words on the obvious, you can spend more
2370 time clarifying the ambiguous labels and explaining
2371 items that are more complex.
2376 Be engaging and friendly, yet professional. Games
2377 documents may be less formal than productivity
2378 application documents (people don't
2379 <emphasis>use</emphasis> games, they
2380 <emphasis>play</emphasis> them), but all of them should
2381 maintain a standard of style which holds the reader's
2382 interest without resorting to jokes and untranslatable
2389 Examples, tips, notes, and screenshots are useful to
2390 break up long stretches of text, but too many can get in
2391 the way, and make your documents too choppy to read.
2392 It's good to provide a screenshot of any dialog windows
2393 a user might run into, but if a dialog box has several
2394 tabs, it's not usually necessary to have one for each.
2400 The GDP strives to have all of its documentation conform
2401 to certain standards of style and content, but every
2402 document (and every writer) is different. You will need
2403 to use your judgement, and write documents to fit with
2404 the rest of the project, without compromising the
2405 individual needs of your subject, or your own
2406 individuality as a writer.
2415 <!-- ####### Basics of Documentation Style | Structure ####### -->
2417 <sect2 id="stylestructure">
2418 <title>Structure</title>
2420 In general, you won't have to worry too much about structure,
2421 because the templates provide you with an excellent example.
2422 As a general rule, try to follow that structural example.
2423 That means using links, hierarchical nesting, and, if
2424 necessary, a glossary or index. You probably won't need to
2425 use every available structural tag, but take advantage of
2426 what DocBook provides you.
2429 As to linking, there's some disagreement about whether to use
2430 <sgmltag><xref></sgmltag> <sgmltag><link></sgmltag>
2431 when you make links within your documents. You'll have to
2432 decide, based on the different ways that they are presented
2433 in output, which is more appropriate given the context.
2434 Regardless of which you use, you should not forget to use
2435 them. Help your readers find information that relevant to
2439 The table of contents will be generated automatically, but
2440 you will probably have to develop your own index if you wish
2441 to have one. The Nautilus Help Browser will have new, and
2442 currently unknown, indexing capabilities, so index style and
2443 structure are still under discussion. The GNOME User's Guide
2444 will contain a glossary in its next versions; unless you're
2445 writing a<sgmltag><book></sgmltag>, it will probably be best to
2446 contribute to that rather than developing your own.
2449 <!-- ####### Basics of Documentation Style | Grammar & Spelling ####### -->
2451 <sect2 id="stylegrammar">
2452 <title>Grammar and Spelling</title>
2454 Nobody expects you to be perfect; they just expect the
2455 documentation for their software to be error-free. That means
2456 that, in the same way that developers look for bugs and accept
2457 bug reports, writers must check for errors in their documents.
2458 Poor grammar, bad spelling, and gross technical errors in
2459 draft documents are fine. However, if those problems show up
2460 in a "real" release, they can count against the credibility of
2461 GNOME and Linux. They'll also make you look bad.
2464 There is no substitute for a human proofreader; use a
2465 spell-check program, then read it over yourself, and then find
2466 someone else to help you. Other GDP members are, of course,
2467 willing and able to help you, but non-writers are often at
2471 Proofreading documents is both a also a good way to
2472 familiarize yourself with documentation, and it certainly
2473 makes you valuable to the GDP. Help other writers proof their
2474 documents, and they will help you with yours.
2479 <!-- ################# Teamwork ############### -->
2481 <sect1 id="teamwork">
2482 <title>Teamwork</title> <!-- ####### Teamwork | Working With The
2483 GDP Team ####### -->
2485 <sect2 id="teamworkgdp">
2486 <title>Working With The GDP Team</title>
2488 The GDP team is a valuable resource for any documentation
2489 author. GDP members can answer most questions documentation
2490 authors have during the course of their work. It is also
2491 important to make sure you are not duplicating work of other
2492 GDP members by visiting the <citetitle>GDP Documentation
2493 Status Table</citetitle> (<ulink
2494 url="http://www.gnome.org/gdp/doctable/"
2495 type="http">http://www.gnome.org/gdp/doctable/</ulink>) and
2496 assigning a documentation item to yourself. This table also
2497 provides a forum for making suggestions and announcements for
2498 each documentation item. The best way to get in touch with
2499 GDP members is on the #docs IRC channel at irc.gnome.org or
2500 else by emailing the <ulink type="http"
2501 url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
2502 <citetitle>gnome-doc-list mailing list</citetitle></ulink>.
2505 After an author has finished a document (or even a draft
2506 version of the document), it is a good idea to ask a member of
2507 the GDP team to read the document, checking it for grammar,
2508 proper DocBook markup, and clarity. One may typically find
2509 another author to do this by either asking on the #docs IRC
2510 channel at irc.gnome.org or by emailing the <ulink type="http"
2511 url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
2512 <citetitle>gnome-doc-list mailing list</citetitle></ulink>.
2516 <!-- ####### Teamwork | Working With Developers ####### -->
2518 <sect2 id="teamworkdevelopers">
2519 <title>Working With Developers</title>
2521 Writing documentation typically involves a certain amount of
2522 interaction with the developers of GNOME or the application
2523 which is being documented. Often a document author will need
2524 to ask the developer technical questions during the course of
2525 writing a document. After the document is finished, it is good
2526 idea to ask the developer to read the document to make sure it
2527 is technically correct. The documentation author should also
2528 make sure that the application author correctly binds and
2529 packages the documentation with the application.
2533 <!-- ####### Teamwork | Working With Users #######
2535 <sect2 id="teamworkusers">
2536 <title>Working With Users</title>
2538 Some document authors may wish to get feedback on their
2539 documents directly from users. This may be done by ...
2544 <!-- ################# Finishing a Document ############### -->
2546 <sect1 id="finishing">
2547 <title>Finishing A Document</title>
2549 <!-- ####### Finishing a Document | Editting the Document ####### -->
2551 <sect2 id="editting">
2552 <title>Editing The Document</title>
2554 When the document is finished, the document should be edited
2555 by another member of the GDP for spelling, clarity, and
2556 DocBook markup. It should also be read by an application
2557 author to make sure the document is technically accurate.
2561 <!-- ####### Finishing a Document | Submitting the Document ####### -->
2563 <sect2 id="submitting">
2564 <title>Submitting The Document</title>
2566 After the document has been edited and checked for technical
2567 accuracy, it is ready to be combined with the application or
2568 documentation package. This is typically done by passing the
2569 document to the application or package developer. In some
2570 cases, the documents can be committed directly into CVS,
2571 however this should only be done after obtaining permission to
2572 make CVS commits from the developer. Note that in many cases,
2573 the application may need to be modified to correctly link to
2574 the documentation. The packaging system (tarballs and binary
2575 packages) may also need to be modified to include the
2576 documentation in the package. Generally, this should be done
2580 The final step is to email the GNOME Translation Team at
2581 <email>gnome-i18n@nuclecu.unam.mx</email> to notify them that
2582 there is a new document for them to translate.
2587 <!-- ################# Resources ############### -->
2589 <sect1 id="resources">
2590 <title>Resources</title>
2591 <!-- ####### Resources | Resources on the Web ####### -->
2593 <sect2 id="resourcesweb">
2594 <title>Resources On The Web</title> <para> The <ulink
2595 type="http" url="http://developer.gnome.org/projects/gdp/">GNOME
2596 Documentation Project Web page</ulink> lists current GDP
2597 projects and members.
2600 The <ulink url="http://www.gnome.org/gdp/doctable/"
2601 type="http">GDP Documentation Status Table</ulink> tracks the
2602 status of all the various documentation components of GNOME.
2605 Norman Walsh's <ulink url="http://www.docbook.org"
2606 type="http"> <citetitle>DocBook: The Definitive
2607 Guide</citetitle></ulink> in an excellent book on DocBook,
2608 available both online and in print.
2612 <!-- ####### Resources | Books ####### -->
2614 <sect2 id="resourcesbooks">
2615 <title>Books</title>
2617 Docbook: The Definitive Guide is available in both printed
2618 form and on the web at:
2619 <ulink url="http://www.docbook.org/tdg/index.html">
2620 <citetitle>Docbook: The Definitive Guide</citetitle>
2625 <!-- ####### Resources | Mailing Lists ####### -->
2627 <sect2 id="mailinglists">
2628 <title>Mailing Lists</title>
2630 The <emphasis>gnome-docs-list</emphasis> mailing list is the
2631 main discussion area for all contributors to the GNOME
2632 Documentation Project. You can find out how to subscribe to
2634 url="http://www.gnome.org/resources/mailing-lists.html"
2635 type="http">GNOME Mailing Lists</ulink>. This is a rather
2636 low-volume list, so you will not be flooded with messages.
2640 <!-- ####### Resources | IRC ####### -->
2645 Internet Relay Chat (IRC) is a fast and easy way to get in
2646 touch with other GDP members. There are generally at least a
2647 few members here who can answer questions or discuss
2648 documentation issues. The IRC channel is #docs at
2654 <!-- ################# Example Docs ###############
2656 <appendix id="exampledocs">
2657 <title>Example Docs</title>
2659 ####### Example Docs | Example 1: Application Manual #######
2662 <title>Example 1: Application Manual</title>
2664 <![CDATA[ (Put sgml here.)]]> </programlisting>
2667 ####### Example Docs | Example 2: Applet Manual #######
2670 <title>Example 2: Applet Manual</title>
2672 <![CDATA[(Put sgml here.)]]> </programlisting>
2675 ##### Example Docs | Example 3: Application Context Sensitive Help ####
2678 <title>Example 3: Application Context Sensitive Help</title>
2680 <![CDATA[(Put sgml here.)]]> </programlisting>
2683 ####### Example Docs | Example 4: Complete Application: gnome-hello #######
2686 <title>Example 4: Complete Application: gnome-hello</title>
2688 <![CDATA[(Put sgml here.)]]> </programlisting>
2691 ####### Example Docs | Example 5: Tutorial #######
2694 <title>Example 5: Tutorial</title>
2696 <![CDATA[(Put sgml here.)]]> </programlisting>
2700 <!-- ################# Document Templates ############### -->
2702 <appendix id="templates">
2703 <title>Document Templates</title>
2704 <!-- ####### Document Templates | Templates 1: Application Manual ####### -->
2706 <sect1 id="template1">
2707 <title>Template 1: Application Manual</title>
2709 The following template should be used for all application
2710 manuals. You can always get the latest copy of this
2711 template from <ulink type="http"
2712 url="http://developer.gnome.org/projects/gdp/templates.html">GDP
2713 Documentation Templates</ulink>.
2717 <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
2718 <!-- if not using PNG graphic, replace reference above with
2719 .....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
2721 <!ENTITY version "1.0.53">
2722 <!-- replace version above with actual application version number-->
2723 <!-- Template Version: 1.0.1 (do not remove this line) -->
2727 <!-- This is a GNOME documentation template, designed by the GNOME
2728 Documentation Project Team. Please use it for writing GNOME
2729 documentation, making obvious changes. In particular, all the words
2730 written in UPPERCASE (with the exception of GNOME) should be
2731 replaced. As for "legalnotice", please leave the reference
2734 Remember that this is a guide, rather than a perfect model to follow
2735 slavishly. Make your manual logical and readable. And don't forget
2736 to remove these comments in your final documentation! ;-)
2739 <!-- =============Document Header ============================= -->
2741 <article id="index"> <!-- please do not change the id -->
2744 <title>MY-GNOME-APP</title>
2747 <holder>ME-THE-AUTHOR</holder>
2750 <!-- translators: uncomment this:
2754 <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
2759 <!-- do not put authorname in the header except in copyright - use
2760 section "authors" below -->
2764 Permission is granted to copy, distribute and/or modify this
2765 document under the terms of the <citetitle>GNU Free
2766 Documentation License</citetitle>, Version 1.1 or any later
2767 version published by the Free Software Foundation with no
2768 Invariant Sections, no Front-Cover Texts, and no Back-Cover
2769 Texts. You may obtain a copy of the <citetitle>GNU Free
2770 Documentation License</citetitle> from the Free Software
2771 Foundation by visiting <ulink type="http"
2772 url="http://www.fsf.org">their Web site</ulink> or by writing
2773 to: Free Software Foundation, Inc., 59 Temple Place - Suite
2774 330, Boston, MA 02111-1307, USA.
2777 Many of the names used by companies to distinguish their
2778 products and services are claimed as trademarks. Where those
2779 names appear in any GNOME documentation, and those trademarks
2780 are made aware to the members of the GNOME Documentation
2781 Project, the names have been printed in caps or initial caps.
2785 <!-- this is the version of manual, not application -->
2787 This is version 1.0 of MY-GNOME-APP manual.
2792 <!-- ============= Document Body ============================= -->
2794 <!-- ============= Introduction ============================== -->
2796 <title>Introduction</title>
2799 <application>MY-GNOME-APP</application> is an application which
2800 proves mathematical theorems. It has all the basic features
2801 expected from a mathematical theorem prover, as well as a number
2802 of advanced ones, such as proof by confusion. In fact, many of
2803 the proofs produced by <application>MY-GNOME-APP</application>
2804 are so complex that they are capable of proving almost anything
2805 with a virtually null likelihood of being disproven. It also has
2806 the very popular predecessor of proof by confusion, proof by
2807 dialog, first implemented by Plato.
2810 It also allows you to save and print theorem proofs and to add
2811 comments to the proofs it produces.
2815 To run <application>MY-GNOME-APP</application>, select
2817 <guisubmenu>SUBMENU</guisubmenu>
2818 <guimenuitem>MY-GNOME-APP</guimenuitem>
2820 from the <guimenu>Main Menu</guimenu>, or type
2821 <command>MYGNOMEAPP</command> on the command line.
2825 <application>MY-GNOME-APP</application> is included in the
2826 <filename>GNOME-PACKAGE</filename> package, which is part of the
2827 GNOME desktop environment. This document describes version
2828 &version; of <application>MY-GNOME-APP</application>.
2833 <!-- ================ Usage ================================ -->
2834 <!-- This section should describe basic usage of the application. -->
2837 <title>Using MY-GNOME-APP</title>
2839 <application>MY-GNOME-APP</application> can be used to produce a
2840 perfect proof of <emphasis>any</emphasis> mathematical theorem
2841 (provided, of course, that this theorem is correct), thus
2842 providing for new users an easy-to-use graphical interface to
2843 modern mathematics. This section describes basic usage of
2844 <application>MY-GNOME-APP</application>.
2847 <!-- ========= Basic Usage =========================== -->
2848 <sect2 id="mainwin">
2849 <title>Basic usage</title>
2851 Starting <application>MY-GNOME-APP</application> opens the
2852 <interface>Main window</interface>, shown in <xref
2853 linkend="mainwindow-fig">. The window is at first empty.
2855 <!-- ==== Figure ==== -->
2856 <figure id="mainwindow-fig">
2857 <title>MY-GNOME-APP Main Window</title>
2859 <screeninfo>MY-GNOME-APP Main Window</screeninfo>
2860 <graphic fileref="SCREENSHOT" format="png" srccredit="ME">
2864 <!-- ==== End of Figure ==== -->
2868 <!-- For this app, one could put "proving" or "edit" (probably even
2869 both of them) as sect2's seperate from the main window
2870 section. Since they were both so closely involved with the main
2871 window, I decided to have them as sect3's isntead. Judgement
2874 <sect3 id="proving">
2875 <title>Proving a Theorem</title>
2877 To get a proof of a theorem, select
2879 <guisubmenu>File</guisubmenu>
2880 <guimenuitem>New</guimenuitem>
2883 bring up the <interface>New Proof</interface> dialog box.
2884 Enter the statement of the theorem in the
2885 <guilabel>Theorem statement</guilabel> field, select your
2886 desired proof type from the drop-down menu, and and press
2887 <guibutton>Prove!</guibutton>.
2890 If <application>MY-GNOME-APP</application> cannot prove the
2891 theorem by the method you have chosen, or if you have not
2892 selected a proof type at all,
2893 <application>MY-GNOME-APP</application> will attempt to
2894 choose the one that it thinks is most conclusive. In order,
2895 it will attempt to prove the theorem with the following techniques:
2899 <term>Deduction</term>
2902 This is a proof method that is generally accepted
2903 for full credit by Logic professors.
2908 <term>Induction</term>
2911 This logical style will also earn you full credit on
2920 This logical method is best for Philosophy classes,
2921 and will probably only merit partial credit on Logic
2922 or Mathematics homework.
2927 <term>Confusion</term>
2930 Suitable only for political debates, battles of wits
2931 against the unarmed, and Philosophy classes focusing
2932 on the works of Kant. Use with caution.
2939 <!-- You might want to include a note, warning, or tip, e.g. -->
2942 <title>Proving Incorrect Theorms</title>
2944 <application>MY-GNOME-APP</application> cannot prove
2945 incorrect theorems. If the theorem you have entered is not
2946 demonstrably true, you will get a message to that effect
2947 in the main window. To disprove a theorem, ask
2948 <application>MY-GNOME-APP</application> to prove its
2953 <sect3 id="editing">
2954 <title>Editing Proofs</title>
2956 Once you have proven the theorem, it will be displayed in
2957 the <interface>main window</interface>. There, you can read
2958 it over, choose text styles for different portions of it,
2959 and make comments on it. This section will guide you through
2963 To alter text styles, first select the statement you wish to
2964 change by clicking on it once. You can select several
2965 statements by Then, choose the style you want to apply from
2966 the <guisubmenu>Style</guisubmenu> submenu of the
2967 <guimenu>Edit</guimenu> menu.
2968 <application>MY-GNOME-APP</application> will convert the
2972 You can also enter comments on a statement by selecting that
2973 statement, and then beginning to type. Comments will appear
2974 after the statement you have selected.
2978 <title>Altering The Proofs Themselves</title>
2980 <application>MY-GNOME-APP</application> does not allow you
2981 to alter a proof it has produced itself. You can, save
2982 your proof as a plain text file (using the
2983 <guimenuitem>Save as...</guimenuitem> menu), and alter it
2984 that way. Be aware, however, that
2985 <application>MY-GNOME-APP</application> uses its own file
2986 format for saved proofs, and cannot re-open a file unless
2987 it is in the .mga format.
2993 <!-- If there are other functions performed from the main window,
2994 they belong here. -->
2998 <!-- =========================================================
2999 Additional Sect2's should describe additional windows, such as
3000 larger dialog boxes, or functionality that differs significantly
3001 from the most immediate functions of the application. Make the
3003 ============================================================= -->
3006 <sect2 id="toolbar">
3007 <title>Toolbar</title>
3009 The toolbar (shown in <xref linkend="figure-usage-toolbar">)
3010 provides access to several commonly used routines.
3011 <figure id="figure-usage-toolbar">
3012 <title>MY-GNOME-APP Toolbar</title>
3014 <screeninfo>MY-GNOME-APP Toolbar</screeninfo>
3015 <graphic fileref="usage-toolbar.png" format="png"></graphic>
3023 Brings up the <interface>New Theorem</interface>
3032 Open an exisiting theorem you want to prove, or a
3033 completed proof you wish to print or format.
3041 Save the current theorem permanently in a
3049 <!-- ========= Menus =========================== -->
3051 <sect2 id="menubar">
3053 <!-- Describing the menubar ensures comprehensive feature
3054 coverage. Nest itemizedlists inside variablelists so that each
3055 menu is easily located by indexing software. Proper indentation
3056 makes it easier! -->
3058 <title>Menus</title>
3060 The menu bar, located at the top of the <interface>Main
3061 Window</interface>, contains the following menus:
3065 <term><guimenu>File</guimenu></term>
3076 <guimenuitem>Open</guimenuitem>
3078 — This opens a file which is saved on your computer.
3085 <keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
3087 <guimenuitem>Save</guimenuitem>
3089 — This saves your file.
3096 <keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo>
3098 <guimenuitem>Close</guimenuitem>
3100 — This closes your file.
3107 <keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
3109 <guimenuitem>Exit</guimenuitem>
3111 — This quits the application.
3120 <term><guimenu>Edit</guimenu></term>
3129 <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo>
3131 <guimenuitem>Cut</guimenuitem>
3133 — This removes any text or data which is selected and
3134 places it in the buffer.
3141 <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
3143 <guimenuitem>Copy</guimenuitem>
3145 — This copies any text or data which is selected into
3153 <keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo>
3155 <guimenuitem>Paste</guimenuitem>
3157 — This pastes any text or data which is copied into
3163 <guimenuitem>COMMAND1…</guimenuitem>
3164 — This opens the <interface>COMMAND1</interface>
3165 dialog, which is used to ....
3170 <guimenuitem>COMMAND2</guimenuitem>
3181 <term><guimenu>Settings</guimenu></term>
3188 <guimenuitem>Preferences…</guimenuitem>
3189 — This opens the <link
3190 linkend="prefs"><interface>Preferences
3191 Dialog</interface></link>, which allows you to configure
3197 <guimenuitem>COMMAND3</guimenuitem> —
3198 This command does something.
3207 <term><guimenu>Help</guimenu></term>
3214 <guimenuitem>Manual</guimenuitem> — This
3215 opens the <application>GNOME Help
3216 Browser</application> and displays this manual.
3222 <guimenuitem>About</guimenuitem> — This
3223 opens the <interface>About</interface> dialog
3224 which shows basic information about
3225 <application>MY-GNOME-APP</application>, such as
3226 the author's name, the application version number,
3227 and the URL for the application's Web page if one
3241 <!-- ============= Customization ============================= -->
3244 <title>Customization</title>
3246 To change the application settings, select
3248 <guimenu>Settings</guimenu>
3249 <guimenuitem>Preferences...</guimenuitem>
3250 </menuchoice>. This opens the
3251 <interface>Preferences</interface> dialog, shown in <xref
3252 linkend="preferences-fig">.
3255 <figure id="preferences-fig">
3256 <title>Preferences Dialog</title>
3258 <screeninfo>Preferences Dialog</screeninfo>
3259 <graphic fileref="SCREENSHOT" format="png"
3266 The properties in the <guilabel>PREFSTABNAME</guilabel> tab are:
3268 <!--many people use itemizedlists in cases like this. Variablelists
3269 are more appropriate -->
3273 <term> <guilabel>Default Text Style</guilabel></term>
3276 Select the default text style for statements in your
3277 proof. You can still change the style for individual
3278 proofs or sections of a proof at a later date.
3283 <term>(Configuration Item Label)</term>
3286 (Description of Configuration)
3291 <term>(Configuration Item Label)</term>
3294 (Description of Configuration)
3302 The properties in the <guilabel>SECONDTABNAME</guilabel> tab are:
3305 <term>(Configuration Item Label)</term>
3308 (Description of Configuration)
3313 <term>(Configuration Item Label)</term>
3316 (Description of Configuration)
3324 After you have made all the changes you want, click on
3325 <guibutton>OK</guibutton> to apply the changes and close the
3326 <interface>Properties</interface> dialog. To cancel the changes
3327 and return to previous values, click the
3328 <guibutton>Close</guibutton> button.
3334 <!-- ============= Various Sections ============================= -->
3336 <!-- Here you should add, if necessary, several more sect1's,
3337 describing other windows (besides the main one), file formats,
3338 preferences dialogs, etc. as appropriate. Try not to make any of
3339 these sections too long. -->
3342 <!-- ============= Bugs ================================== -->
3343 <!-- This section should describe known bugs and limitations of
3344 the program if there are any - please be frank and list all
3345 problems you know of. -->
3347 <title>Known Bugs and Limitations</title>
3349 This application has no known bugs.
3354 <!-- ============= Authors ================================ -->
3356 <sect1 id="authors">
3357 <title>Authors</title>
3359 <application>MY-GNOME-APP</application> was written by GNOME-HACKER
3360 (<email>hacker@gnome.org</email>). To find more information about
3361 <application>MY-GNOME-APP</application>, please visit the <ulink
3362 url="http://www.my-gnome-app.org" type="http">MY-GNOME-APP Web
3363 page</ulink>. Please send all comments, suggestions, and bug
3364 reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
3365 bug tracking database</ulink>. (Instructions for submitting bug
3366 reports can be found <ulink
3367 url="http://bugs.gnome.org/Reporting.html" type="http">
3368 on-line</ulink>.) You can also use <application>Bug Report
3369 Tool</application> (<command>bug-buddy</command>), available in the
3370 <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
3371 Menu</guimenu>, for submitting bug reports.
3375 This manual was written by ME
3376 (<email>MYNAME@MYADDRESS</email>). Please send all comments and
3377 suggestions regarding this manual to the <ulink type="http"
3378 url="http://developer.gnome.org/projects/gdp">GNOME Documentation
3379 Project</ulink> by sending an email to
3380 <email>docs@gnome.org</email>. You can also add your comments online
3381 by using the <ulink type="http"
3382 url="http://www.gnome.org/gdp/doctable/">GNOME Documentation Status
3386 <!-- For translations: uncomment this:
3389 Latin translation was done by ME
3390 (<email>MYNAME@MYADDRESS</email>). Please send all comments and
3391 suggestions regarding this translation to SOMEWHERE.
3399 <!-- ============= Application License ============================= -->
3401 <sect1 id="license">
3402 <title>License</title>
3404 This program is free software; you can redistribute it and/or
3405 modify it under the terms of the <citetitle>GNU General Public
3406 License</citetitle> as published by the Free Software Foundation;
3407 either version 2 of the License, or (at your option) any later
3411 This program is distributed in the hope that it will be useful, but
3412 WITHOUT ANY WARRANTY; without even the implied warranty of
3413 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3414 <citetitle>GNU General Public License</citetitle> for more details.
3417 A copy of the <citetitle>GNU General Public License</citetitle> is
3418 included as an appendix to the <citetitle>GNOME Users
3419 Guide</citetitle>. You may also obtain a copy of the
3420 <citetitle>GNU General Public License</citetitle> from the Free
3421 Software Foundation by visiting <ulink type="http"
3422 url="http://www.fsf.org">their Web site</ulink> or by writing to
3424 Free Software Foundation, Inc.
3425 <street>59 Temple Place</street> - Suite 330
3426 <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
3427 <country>USA</country>
3448 <!-- ####### Document Templates | Templates 2-1.x: Applet Manual ####### -->
3450 <sect1 id="template2-1x">
3451 <title>Template 2: Applet Manual For GNOME 1.x</title>
3453 The following templates should be used for all applet
3454 manuals in GNOME 1.x releases. You can always get the latest
3455 copy of these templates from <ulink type="http"
3456 url="http://developer.gnome.org/projects/gdp/templates.html">GDP
3457 Documentation Templates</ulink>. Note that the template
3458 consists of two files; the first file calls the second as an
3459 entity. You should name the first file
3460 <filename><replaceable>appletname</replaceable>-applet.sgml</filename>
3461 and the second file should be named
3462 <filename><replaceable>appletname</replaceable>.sgml</filename>,
3464 <filename><replaceable>appletname</replaceable></filename> is
3465 the name of the applet.
3469 <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
3470 <!entity APPLETNAME.sgml SYSTEM "applet_template_1.sgml">
3471 <!-- Template Version: 1.0.1 (do not remove this line) -->
3474 <!-- This is a GNOME documentation template, designed by the GNOME
3475 Documentation Project Team. Please use it for writing GNOME
3476 documentation, making obvious changes. In particular, all the words
3477 written in UPPERCASE (with the exception of GNOME) should be
3478 replaced. As for "legalnotice", please leave the reference
3479 unchanged,make sure to add/remove trademarks to the list as
3480 appropriate for your document.
3482 Please don't forget to remove these comments in your final documentation,
3486 <article id="index"> <!-- please do not change the id -->
3488 <!-- ============= Document Header ============================= -->
3490 <title>APPLETNAME Applet</title>
3493 <holder>YOURFULLNAME</holder>
3496 <!-- translators: uncomment this:
3500 <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
3505 <!-- do not put authorname in the header except in copyright - use
3506 section "authors" below -->
3510 Permission is granted to copy, distribute and/or modify this
3511 document under the terms of the <citetitle>GNU Free Documentation
3512 License</citetitle>, Version 1.1 or any later version published
3513 by the Free Software Foundation with no Invariant Sections, no
3514 Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
3515 of the <citetitle>GNU Free Documentation License</citetitle> from
3516 the Free Software Foundation by visiting <ulink type="http"
3517 url="http://www.fsf.org">their Web site</ulink> or by writing to:
3518 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
3519 Boston, MA 02111-1307, USA.
3522 Many of the names used by companies to distinguish their products and
3523 services are claimed as trademarks. Where those names appear in any
3524 GNOME documentation, and those trademarks are made aware to the members
3525 of the GNOME Documentation Project, the names have been printed in caps
3531 This is version XXX of the APPLETNAME applet manual.
3535 <!-- ============= Document Body ============================= -->
3548 <!-- Template Version: 1.0.1 (do not remove this line) -->
3551 <title>APPLET Applet</title>
3554 <application>APPLET</application> applet, shown in <xref
3555 linkend="APPLETapplet-fig">, allows you to …. To add this
3556 applet to a <interface>Panel</interface>,
3557 right-click on the <interface>Panel</interface> and choose
3559 <guimenu>Panel</guimenu>
3560 <guisubmenu>Add to panel</guisubmenu>
3561 <guisubmenu>Applet</guisubmenu>
3562 <guisubmenu>SECTION</guisubmenu>
3563 <guimenuitem>APPLET</guimenuitem>
3567 <figure id="APPLETapplet-fig">
3568 <title>APPLET Applet</title>
3570 <screeninfo>APPLET Applet</screeninfo>
3571 <graphic format="png" fileref="APPLET_applet"
3572 srccredit="YOURNAME">
3577 <!-- ============= Usage ================================ -->
3578 <sect2 id="APPLET-usage">
3579 <title>Usage</title>
3581 (Place a short description of how to use the applet here.)
3585 Right-clicking on the applet brings up a menu containing the
3591 <guimenuitem>Properties…</guimenuitem> —
3592 opens the <link linkend="APPLET-prefs">
3593 <guilabel>Properties</guilabel></link> dialog.
3599 <guimenuitem>Help</guimenuitem> —
3600 displays this document.
3606 <guimenuitem>About…</guimenuitem> —
3607 shows basic information about <application>APPLET
3608 Applet</application>, including the applet's version and the
3618 <!-- ============= Customization ============================= -->
3619 <sect2 id="APPLET-prefs">
3620 <title>Customization</title>
3622 You can customize <application>APPLET</application>
3623 applet by right-clicking on it and choosing
3624 <guimenuitem>Properties…</guimenuitem>. This will open the
3625 <interface>Properties</interface> dialog(shown in <xref
3626 linkend="APPLET-settings-fig">), which allows you to
3627 change various settings.
3630 <figure id="APPLET-settings-fig">
3631 <title>Properties dialog</title>
3633 <screeninfo>Properties dialog</screeninfo>
3634 <graphic format="png" fileref="APPLET_settings"
3635 srccredit="YOURNAME">
3646 (Configuration Item Label) — If this button is
3647 checked…(description)
3653 (Configuration Item Label) — Selecting this
3654 button…(description)
3660 (Configuration Item Label) — Enter the name of
3661 …(description)
3668 After you have made all the changes you want, click on
3669 <guibutton>OK</guibutton> to apply the changes and close the
3670 <interface>Properties</interface> dialog. To cancel the changes
3671 and return to previous values, click the
3672 <guibutton>Close</guibutton> button.
3677 <!-- ============= Bugs ================================== -->
3678 <!-- This section should describe known bugs and limitations of
3679 the program if there are any - please be frank and list all
3680 problems you know of -->
3682 <title>Known Bugs and Limitations</title>
3684 This applet has no known bugs.
3689 <!-- ============= Authors ================================ -->
3691 <sect2 id="authors">
3692 <title>Authors</title>
3694 <application>APPLET</application> was written by GNOME-HACKER
3695 (<email>hacker@gnome.org</email>). Please send all comments,
3696 suggestions, and bug
3697 reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
3698 bug tracking database</ulink>. (Instructions for submitting bug
3699 reports can be found <ulink
3700 url="http://bugs.gnome.org/Reporting.html" type="http">
3701 on-line</ulink>. You can also use <application>Bug Report
3702 Tool</application> (<command>bug-buddy</command>), available in the
3703 <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
3704 Menu</guimenu>, for submitting bug reports.
3708 This manual was written by ME
3709 (<email>MYNAME@MYADDRESS</email>). Please send all comments and
3710 suggestions regarding this manual to the <ulink type="http"
3711 url="http://developer.gnome.org/projects/gdp">GNOME Documentation
3712 Project</ulink> by sending an email to
3713 <email>docs@gnome.org</email>. You can also submit comments online
3714 by using the <ulink type="http"
3715 url="http://www.gnome.org/gdp/doctable/">GNOME Documentation
3716 Status Table</ulink>.
3719 <!-- For translations: uncomment this:
3722 Latin translation was done by ME
3723 (<email>MYNAME@MYADDRESS</email>). Please send all comments and
3724 suggestions regarding this translation to SOMEWHERE.
3732 <!-- ============= Application License ============================= -->
3734 <sect2 id="license">
3735 <title>License</title>
3737 This program is free software; you can redistribute it and/or
3738 modify it under the terms of the <citetitle>GNU General Public
3739 License</citetitle> as published by the Free Software Foundation;
3740 either version 2 of the License, or (at your option) any later
3744 This program is distributed in the hope that it will be useful, but
3745 WITHOUT ANY WARRANTY; without even the implied warranty of
3746 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3747 <citetitle>GNU General Public License</citetitle> for more details.
3750 A copy of the <citetitle>GNU General Public License</citetitle> is
3751 included as an appendix to the <citetitle>GNOME Users
3752 Guide</citetitle>. You may also obtain a copy of the
3753 <citetitle>GNU General Public License</citetitle> from the Free
3754 Software Foundation by visiting <ulink type="http"
3755 url="http://www.fsf.org">their Web site</ulink> or by writing to
3757 Free Software Foundation, Inc.
3758 <street>59 Temple Place</street> - Suite 330
3759 <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
3760 <country>USA</country>
3778 <!-- ####### Document Templates | Templates 2-2.x: Applet Manual ####### -->
3780 <sect1 id="template2-2x">
3781 <title>Template 2: Applet Manual For GNOME 2.x</title>
3783 The following templates should be used for all applet
3784 manuals in GNOME 2.x releases. You can always get the latest
3785 copy of these templates from <ulink type="http"
3786 url="http://developer.gnome.org/projects/gdp/templates.html">GDP
3787 Documentation Templates</ulink>.
3790 Note that this template consists of two files. The first file
3791 is an introductory chapter. You should not modify this
3792 chapter. The second file is the actual applet document, which
3793 you should modify to describe the applet you are documenting.
3794 You can name the first file whatever you like, such as
3795 <filename>gnome-applets.sgml</filename>. Name the second file
3796 according to the applet's name:
3797 <filename><replaceable>appletname</replaceable>-applet.sgml</filename>.
3798 Make sure you update the entity
3799 at the top of the shell document to reflect the new name of
3800 the applet document.
3805 <!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
3806 <!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part">
3810 <book id="gnome-applets">
3813 <title>GNOME Applets</title>
3815 <author><firstname>Telsa</firstname><surname>Gwynne</surname></author>
3816 <author><firstname>John</firstname><surname>Fleck</surname></author>
3817 <author><firstname>David</firstname><surname>Mason</surname>
3818 <affiliation><orgname>Red Hat, Inc.</orgname></affiliation>
3820 <author><firstname>Dan</firstname><surname>Mueth</surname></author>
3821 <author><firstname>Alexander</firstname><surname>Kirillov</surname></author>
3823 <edition>GNOME Applets version 0.1 for GNOME 1.1.5</edition>
3824 <pubdate>2000</pubdate>
3827 <holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and
3828 Alexander Kirillov</holder>
3832 Permission is granted to make and distribute verbatim copies of this
3833 manual provided the copyright notice and this permission notice are
3834 preserved on all copies.
3837 Permission is granted to copy and distribute modified versions of
3838 this manual under the conditions for verbatim copying, provided that
3839 the entire resulting derived work is distributed under the terms of a
3840 permission notice identical to this one.
3843 Permission is granted to copy and distribute translations of this
3844 manual into another language, under the above conditions for modified
3845 versions, except that this permission notice may be stated in a
3846 translation approved by the Free Software Foundation.
3849 Many of the names used by companies to distinguish their products and
3850 services are claimed as trademarks. Where those names appear in any
3851 GNOME documentation, and those trademarks are made aware to the members
3852 of the GNOME Documentation Project, the names have been printed in caps
3858 <!-- #### Introduction ###### -->
3859 <chapter id="applets-intro">
3860 <title>Introduction</title>
3862 <!-- #### Intro | What Are Applets? ###### -->
3863 <sect1 id="applets-what-are">
3864 <title>What Are Applets?</title>
3866 Applets are one of the most popular and useful objects you can add
3867 to your <interface>Panel</interface> to customize your desktop.
3868 An applet is a small application which runs inside a small area of
3869 your <interface>Panel</interface>. Applets have been written for
3870 a wide range of purposes. Some are very powerful interactive
3871 tools, such as the <application>Tasklist</application> Applet
3872 which allows you to easily
3873 control all of your main applications. Others are simple system
3874 monitors, displaying information such as the amount of power left
3875 in the battery on your laptop (see <application>Battery Charge
3876 Monitor</application>) or weather
3877 information(see <application>GNOME Weather</application>). Some
3878 are simply for amusement(see <application>Fish</application>).
3882 Applets are similar to swallowed applications in that both of them
3883 reside within the <interface>Panel</interface>. However,
3884 swallowed applications are generally applications which were
3885 not designed to run within the <interface>Panel</interface>.
3886 Typically one will swallow an application which already exists in
3887 the main <interface>desktop</interface> area, putting it into your
3888 <interface>Panel</interface>. The application will continue to
3889 run in the <interface>Panel</interface> until you end the
3890 application or unswallow it, placing it back onto the main part of
3891 your desktop when you need to.
3895 <figure id="example-applets-fig">
3896 <title>Example Applets</title>
3898 <screeninfo>Example Applets</screeninfo>
3899 <graphic fileref="example_applets" format="png"
3904 Several example applets are shown in <xref
3905 linkend="example-applets-fig">. From left to right, they are: (1)
3906 <application>Mixer Applet</application>, which allows you to turn
3907 on/off sound and control its volume by clicking on the applet. (2)
3908 <application>Sound Monitor</application> Applet, which displays
3909 the current volume of sound being played and allows you to control
3910 various sound features. (3) <application>GTCD</application>
3911 Applet, a CD player which has all its controls
3912 available in the applet and displays the track and time. (4)
3913 <application>Drive Mount</application> Applet, used to mount and
3914 unmount drives with a single click of the mouse. (5)
3915 <application>Desk Guide</application> which allows you to view
3916 and control multiple virtual screens. (6)
3917 <application>Tasklist</application> Applet which allows you to
3918 control your various windows and applications.
3921 There are many other applets to choose from. The rest of this
3922 chapter will explain the basic information to get you started
3923 adding, moving, and removing applets from your
3924 <interface>Panels</interface> and using them. The following
3925 chapters go through each of the standard GNOME applets describing
3926 them in detail. There are also additional applets which can be
3927 downloaded off the Web. See <ulink type="http"
3928 url="http://www.gnome.org/applist/list-martin.phtml">The GNOME
3929 Software Map</ulink> for lists of additional GNOME applications
3933 As you read through the the rest of this chapter, you should try
3934 adding and removing applets from your <interface>Panel</interface> and
3935 experiment with them freely.
3939 <!-- #### Intro | Adding, Moving, and Removing Applets ###### -->
3940 <sect1 id="applet-add-move-replace">
3941 <title>Adding, Moving, and Removing Applets</title>
3943 <sect2 id="adding-applets">
3944 <title>Adding Applets to a Panel</title>
3946 To add an applet to a <interface>Panel</interface>, right-click
3947 on the <interface>Panel</interface> and select
3948 <menuchoice><guimenu>Panel</guimenu><guisubmenu>Add to panel</guisubmenu>
3949 <guisubmenu>Applet</guisubmenu></menuchoice>. This will show you
3950 the menu of all the applets on your system, divided into
3951 categories. Choosing any applet from this menu will add it to the
3952 <interface>Panel</interface>.
3956 <sect2 id="moving-applets">
3957 <title>Moving Applets In or Between Panels</title>
3959 It is easy to move applets in a <interface>Panel</interface> or
3960 between two <interface>Panels</interface>. If you have a
3961 three-button mouse, just move the mouse over the applet, depress
3962 the middle mouse button and drag the applet to its new location,
3963 releasing the middle mouse button when you are finished. Note
3964 that you can drag applets within a <interface>Panel</interface>
3965 or between two <interface>Panels</interface> this way. If you
3966 don't have a three-button mouse, just
3967 right-click on the applet and choose
3968 <guimenuitem>Move</guimenuitem>. The cursor will turn into a
3969 cross and the applet will move with your mouse until you press
3970 any mouse button to indicate you are finished moving it.
3971 If, in the course of this movement, it hits
3972 other objects, the behavior depends on the global preferences
3973 you have set for your <interface>Panels</interface> in the
3974 <application>GNOME Control Center</application>: the applet you are
3975 moving can switch places with other objects, "push" all objects
3976 it meets, or "jump" over all other objects without disturbing
3977 them. You can also override the default behavior by holding
3978 <keycap>Shift</keycap> button (for "push" mode),
3979 <keycap>Ctrl</keycap> (for "switched" mode), or
3980 <keycap>Alt</keycap> (for "free" mode, i.e. jumping other other
3981 objects without disturbing them) button while dragging.
3984 To change the global Panel preferences, right-click on any applet
3985 or <interface>Panel</interface> and select
3987 <guimenu>Panel</guimenu>
3988 <guimenuitem>Global Preferences...</guimenuitem>
3990 The <guilabel>Default movement mode</guilabel> is set under the
3991 <guilabel>Applets</guilabel> tab.
3995 <sect2 id="removing-applets">
3996 <title>Removing Applets from a Panel</title>
3998 To remove an applet from a <interface>Panel</interface>,
3999 right-click on the applet and select <guimenuitem>Remove from
4000 panel...</guimenuitem>.
4006 <!-- #### Intro | The Right-Click Pop-Up Menu ###### -->
4007 <sect1 id="right-click-pop-up-menu">
4008 <title>The Right-Click Pop-Up Menu</title>
4010 Clicking the right mouse button on any applet brings up
4011 a <guimenu>pop-up menu</guimenu>. This
4012 menu always has certain standard menu items in it and
4013 often has additional items which vary depending on the particular
4016 <sect2 id="standard-right-click-items">
4017 <title>Standard Pop-Up Items</title>
4019 All applets should have the following items in their right-click
4020 <guimenu>pop-up menu</guimenu>:
4023 <term>Remove from panel</term>
4026 The <guimenuitem>Remove from panel</guimenuitem> menu item
4027 removes the applet from the <interface>Panel</interface>.
4036 After selecting <guimenuitem>Move</guimenuitem>, your mouse
4037 pointer will change appearance (typically to a cross with
4038 arrows in each direction). As you move your mouse, the applet
4039 will move with it. When you have finished moving the applet,
4040 click any mouse button and the applet will anchor in its
4041 current position. Note that applets can be moved between two
4042 <interface>Panels</interface> this way.
4051 The <guisubmenu>Panel</guisubmenu> submenu contains various
4052 items and submenus for adding and removing
4053 <interface>Panels</interface> and applets and for changing
4063 The <guimenuitem>About...</guimenuitem> menu item brings up a
4064 dialogue box containing various information about the applet,
4065 typically including the applet's name, version, author,
4066 copyright, license and desciption.
4075 The <guimenuitem>Help</guimenuitem> menu item brings up the help
4076 manual for the applet.
4084 <sect2 id="applet-properties-dialog">
4085 <title>The Applet Properties Dialog</title>
4087 Many applets have customizable properties. These applets will
4088 have a <guimenuitem>Properties...</guimenuitem> menu item in their
4089 right-click <guimenu>pop-up menu</guimenu> which brings up the
4090 <interface>Properties</interface> dialog where you can alter the
4091 appearance or behaviour of the applet.
4092 <figure id="example-props-dialog-fig">
4093 <title>An Example Applet Properties Dialog</title>
4095 <screeninfo>An Example Applets Properties Dialog</screeninfo>
4096 <graphic fileref="applet_props_dialog" format="png"
4101 All <interface>Properties</interface> dialogs have the following
4102 buttons at the bottom of the dialog:
4106 <guibutton>OK</guibutton> —
4107 Pressing <guibutton>OK</guibutton> will activate any changes
4108 in the properties you have made and close the
4109 <interface>Properties</interface> dialog.
4114 <guibutton>Apply</guibutton> —
4115 Pressing <guibutton>Apply</guibutton> at any time will
4116 make your changes active without closing the
4117 <interface>Properties</interface> dialog. This is helpful if
4118 you would like to test the effects of the changes you have
4119 made but may want to continue changing the properties.
4124 <guibutton>Close</guibutton> —
4125 Pressing <guibutton>Close</guibutton> will close the
4126 <interface>Properties</interface> dialog. Only changes in the
4127 configuration which were previously applied with the
4128 <guibutton>Apply</guibutton> button will persist. Other
4129 changes will not be made active.
4134 <guibutton>Help</guibutton> —
4135 Pressing <guibutton>Help</guibutton> brings up the manual for
4136 the application, opening it to the page describing the
4137 <interface>Properties</interface> dialog.
4144 <sect2 id="common-right-click-items">
4145 <title>Other Common Pop-Up Items</title>
4147 Many applets also have one or more of the following items in their
4148 right-click pop-up menu:
4154 The <guimenuitem>Run...</guimenuitem> menu item generally
4155 invokes a program which is related to the applet in some way
4156 but which runs in its own window rather than in the
4162 The <application>CPU Load</application> applet, which monitors
4163 what programs are running, has a <guimenuitem>Run
4164 gtop...</guimenuitem> menu item. Selecting this menu item
4165 starts <application>GTop</application>, which allows you to
4166 view and control programs which are running.
4171 The <application>CD Player</application> applet has a
4172 <guimenuitem>Run gtcd...</guimenuitem> menu item which
4173 starts the GNOME <application>CD Player</application> when
4174 selected, which has more capabilities than the applet.
4185 <sect1 id="feedback">
4186 <title>Feedback</title>
4187 <sect2 id="reporting-bugs">
4188 <title>Reporting Applet Bugs</title>
4190 GNOME users are encouraged to report bugs to <ulink type="http"
4191 url="http://bugs.gnome.org">The GNOME Bug Tracking
4192 System</ulink>. The easiest way to submit bugs is to use the
4193 <application>Bug Report Tool</application> program by selecting
4195 <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
4196 <guimenuitem>Bug Report Tool</guimenuitem>
4198 Be sure to be complete in describing what you did to cause the
4199 bug to surface and, if possible, describe how the developer can
4200 reproduce the the scenario.
4203 <sect2 id="documentation-feedback">
4204 <title>Providing Feedback</title>
4206 GNOME users are welcome to provide suggestions for how
4207 applications and documentation can be improved. Suggestions for
4208 application changes should be submitted using the
4209 <application>Bug Report Tool</application> discussed above.
4210 Suggestions for documentation changes can be emailed directly to
4211 the documentation author (whose email should be included in the
4212 "Authors" section of the document) or by sending an email to
4213 <email>docs@gnome.org</email>.
4216 <sect2 id="joining-gnome">
4217 <title>Joining GNOME</title>
4219 GNOME is a community project, created by hundreds of programmers,
4220 documentation writers, icon design artists, web masters, and
4221 other people, most of whom work on a volunteer basis. New GNOME
4222 contributors are always welcome. To join the GNOME team, visit
4223 these web sites: developers — <ulink type="http"
4224 url="http://developer.gnome.org">The GNOME Development
4225 Site</ulink>, documentation writers — <ulink type="http"
4226 url="http://developer.gnome.org/projects/gdp">The GNOME Documentation
4227 Project</ulink>, icon design artists — <ulink type="http"
4228 url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>,
4229 general — <ulink type="http"
4230 url="http://developer.gnome.org/helping/">Helping GNOME</ulink>,
4231 or just join the gnome-list email list (see <ulink type="http"
4232 url="http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing
4233 Lists</ulink>) to discuss what you are interested in doing.
4239 <!-- ############### Template Applets ##################### -->
4240 <chapter id="template-applets">
4241 <title>Template Applets</title>
4261 <!-- Please replace everywhere below GNOMEAPPLET with the name of -->
4262 <!-- your applet. Most importantly, all id attributes should start -->
4263 <!-- with the name of your applet - this is necessary to avoid name -->
4264 <!-- conflict among different applets -->
4265 <!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email-->
4266 <!-- Please replace HACKER-NAME with the applet author's name and -->
4267 <!-- HACKER-EMAIL with the applet author's email -->
4269 <!-- You should name your file: GNOMEAPPLET-applet.sgml -->
4270 <!-- Screenshots should be in PNG format and placed in the -->
4271 <!-- same directory as GNOMEAPPLET-applet.sgml -->
4273 <!-- Applet docs will be merged into <chapter>'s inside a -->
4274 <!-- <book>. Thus, the indentation below (2 spaces before the <sect1>) is -->
4277 <!-- Permission is granted to make and distribute verbatim copies of -->
4278 <!-- this manual provided the copyright notice and this permission -->
4279 <!-- notice are preserved on all copies. -->
4281 <!-- Permission is granted to copy and distribute modified versions of -->
4282 <!-- this manual under the conditions for verbatim copying, provided -->
4283 <!-- that the entire resulting derived work is distributed under the -->
4284 <!-- terms of a permission notice identical to this one. -->
4286 <!-- Permission is granted to copy and distribute translations of this -->
4287 <!-- manual into another language, under the above conditions for -->
4288 <!-- modified versions, except that this permission notice may be -->
4289 <!-- stated in a translation approved by the Foundation. -->
4291 <!-- ############### GNOMEAPPLET ############### -->
4292 <sect1 id="GNOMEAPPLET">
4293 <title>GNOMEAPPLET Applet</title>
4296 <application>GNOMEAPPLET</application> applet, shown in <xref
4297 linkend="GNOMEAPPLET-fig">, does this and that. To learn how to
4298 add this applet to a <interface>Panel</interface>, see <xref
4299 linkend="adding-applets">.
4303 <figure id="GNOMEAPPLET-fig">
4304 <title>GNOMEAPPLET</title>
4306 <screeninfo>GNOMEAPPLET</screeninfo>
4307 <graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME">
4312 <sect2 id="GNOMEAPPLET-usage">
4313 <title>Usage</title>
4315 This applet does nothing. To use it, just
4316 left-click on it and it will instantly do nothing.
4320 <sect2 id="GNOMEAPPLET-right-click">
4321 <title>Right-Click Pop-Up Menu Items</title>
4323 In addition to the standard menu items (see <xref
4324 linkend="standard-right-click-items">), the right-click pop-up menu has
4325 the following items:
4329 <guimenuitem>Properties...</guimenuitem> — This menu
4330 item opens the <interface>Properties</interface> dialog (see
4331 <xref linkend="GNOMEAPPLET-properties">) which allows you to
4332 customize the appearance and behavior of this applet.
4337 <guimenuitem>Run Hello World...</guimenuitem> — This
4338 menu item starts the program <application>Hello
4339 World</application>, used to say "hello" to the world.
4346 <sect2 id="GNOMEAPPLET-properties">
4347 <title>Properties</title>
4349 You can configure <application>GNOMEAPPLET</application> applet by
4350 right-clicking on the applet and choosing the
4351 <guimenuitem>Properties...</guimenuitem> menu item. This will open the
4352 <interface>Properties</interface> dialog, shown in <xref
4353 linkend="GNOMEAPPLET-properties-fig">.
4355 <figure id="GNOMEAPPLET-properties-fig">
4356 <title>Properties Dialog</title>
4358 <screeninfo>Properties Dialog</screeninfo>
4359 <graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME">
4365 To change the color of the applet, click on the
4366 <guibutton>color</guibutton> button. To change other properties,
4367 click on other buttons.
4371 For more information on the <interface>Properties</interface>
4372 dialog, including descriptions of the <guibutton>OK</guibutton>,
4373 <guibutton>Apply</guibutton>, <guibutton>Cancel</guibutton>, and
4374 <guibutton>Help</guibutton> buttons, see <xref
4375 linkend="applet-properties-dialog">.
4379 <sect2 id="GNOMEAPPLET-bugs">
4380 <title> Known Bugs and Limitations</title>
4382 There are no known bugs in the
4383 <application>GNOMEAPPLET</application> applet.
4387 <sect2 id="GNOMEAPPLET-authors">
4388 <title>Authors</title>
4390 This applet was writen by HACKER-NAME
4391 <email>HACKER-EMAIL</email>. The documentation for this applet
4392 which you are reading now was written by
4393 YOUR-NAME <email>YOUR-EMAIL</email>. For information on submitting
4394 bug reports and suggestions for improvements, see <xref
4395 linkend="feedback">.
4412 <!-- ####### Document Templates | Templates 3: Application Help #######
4414 <sect1 id="template3">
4415 <title>Template 2: Application Help</title>
4417 <![CDATA[(Put sgml here.)]]> </programlisting>
4420 ####### Document Templates | Templates 4: Application Context Sensitive Help #######
4422 <sect1 id="template4">
4423 <title>Template 3: Application Context Sensitive Help</title>
4425 Context sensitive help is still in development.
4429 ####### Document Templates | Templates 5: Complete Application: gnome-hello #######
4431 <sect1 id="template5">
4432 <title>Template 4: Complete Application: gnome-hello</title>
4434 <![CDATA[(Put sgml here.)]]>
4438 ####### Document Templates | Templates 6: Tutorial #######
4440 <sect1 id="template6">
4441 <title>Template 5: Tutorial</title>
4443 <![CDATA[(Put sgml here.)]]>
projects / TestXSLT.git / blob