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 <!ENTITY copy
"©"> <!-- COPYRIGHT SIGN -->
8 <!-- replace version above with actual application version number-->
9 <!-- Template Version: 1.0.1 (do not remove this line) -->
13 <!ENTITY APPLET-TEMPLATE-
1x-SHELL SYSTEM
14 "templates/applet_template_1-applet.sgml.cdata">
15 <!ENTITY APPLET-TEMPLATE-
1x SYSTEM
16 "templates/applet_template_1.sgml.cdata">
19 <!-- Version: 1.0.1 -->
27 <firstname>David
</firstname>
28 <surname>Mason
</surname>
30 <orgname>Red Hat, Inc.
</orgname>
32 <email>dcm@redhat.com
</email>
38 <firstname>Daniel
</firstname>
39 <surname>Mueth
</surname>
42 <email>d-mueth@uchicago.edu
</email>
48 <firstname>Alexander
</firstname>
49 <surname>Kirillov
</surname>
52 <email>kirillov@math.sunysb.edu
</email>
60 This is a pre-release!
76 <holder>Red Hat, Inc., Daniel Mueth, and Alexander Kirillov
</holder>
81 Permission is granted to copy, distribute and/or modify this
82 document under the terms of the
<citetitle>GNU Free Documentation
83 License
</citetitle>, Version
1.1 or any later version published
84 by the Free Software Foundation with no Invariant Sections, no
85 Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
86 of the
<citetitle>GNU Free Documentation License
</citetitle> from
87 the Free Software Foundation by visiting
<ulink type=
"http"
88 url=
"http://www.fsf.org">their Web site
</ulink> or by writing to:
89 Free Software Foundation, Inc.,
59 Temple Place - Suite
330,
90 Boston, MA
02111-
1307, USA.
93 Many of the names used by companies to distinguish their products and
94 services are claimed as trademarks. Where those names appear in any
95 GNOME documentation, and those trademarks are made aware to the members
96 of the GNOME Documentation Project, the names have been printed in caps
101 <title>The GNOME Handbook of Writing Software Documentation
</title>
105 <!-- ################# Introduction ############### -->
108 <title>Introduction
</title>
110 <!-- ####### Introduction | The GNOME Documentation Project ####### -->
113 <title>The GNOME Documentation Project
</title>
118 The GNOME Documentation Project (GDP) aims to provide GNOME
119 and GNOME applications with a complete, intuitive, and clear
120 documentation system. At the center of the GDP is the
121 <application>GNOME Help Browser
</application>, which
122 presents a unified interface to GNOME-specific documentation
123 as well as other Linux documentation such as man pages and
124 texinfo documents. The GNOME Help System provides a
125 comprehensive view of documentation on a machine by
126 dynamically assembling the documentation of GNOME
127 applications and components which are installed. The GDP is
128 responsible for writing numerous GNOME-related documents,
129 both for developers and for users. Developer documentation
130 includes
<ulink url=
"http://developer.gnome.org/doc/API/"
131 type=
"http">APIs for the GNOME libraries
</ulink>,
<ulink
132 url=
"http://developer.gnome.org/doc/whitepapers/"
133 type=
"http"><citetitle>GNOME White
134 Papers
</citetitle></ulink>, GNOME developer
<ulink
135 url=
"http://developer.gnome.org/doc/tutorials/"
136 type=
"http">tutorials
</ulink>, the
<ulink
137 url=
"http://developer.gnome.org/doc/FAQ/"
138 type=
"http"><citetitle>GNOME Developer
139 FAQ
</citetitle></ulink>, the
<ulink
140 url=
"http://developer.gnome.org" type=
"http">GNOME
141 Developer's Website
</ulink>, and
<citetitle>GNOME
142 Handbook
</citetitle>'s, such as the one you are reading.
143 User documentation include the
<ulink
144 url=
"http://www.gnome.org/learn/"
145 type=
"http"><citetitle>GNOME User's
146 Guide
</citetitle></ulink>, the
<ulink
147 url=
"http://www.gnome.org/learn/"
148 type=
"http"><citetitle>GNOME FAQ
</citetitle></ulink>, and
149 GNOME application documentation. Most GNOME applications
150 have their own manual in addition to context sensitive help.
155 <title>Joining the GDP
</title>
157 Documenting GNOME and all the numerous GNOME applications is
158 a very large project. The GDP is always looking for people
159 to help write, update, and edit documentation. If you are
160 interested in joining the GDP team, you should join the
161 <ulink url=
"http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
162 <citetitle>gnome-doc-list mailing list
</citetitle> </ulink>.
163 Read
<xref linkend=
"gettingstarted" />, for help selecting a
164 project to work on. Feel free to introduce yourself on the
165 gnome-doc-list mailing list and indicate which project you
166 intend to work on, or else ask for suggestions of important
167 documents which need work done. You may also want to join the
168 #docs IRC channel on irc.gnome.org to meet other GDP members
169 and discuss any questions you may have. For a list of GDP
170 projects and members, see the
171 <ulink url=
"http://developer.gnome.org/projects/gdp">
172 <citetitle>GDP Website
</citetitle></ulink>.
176 <sect3 id=
"collaborating">
177 <title>Collaborating with the GDP
</title>
179 GNOME developers, packagers, and translators may not be
180 writing GNOME documentation but will want to understand how
181 the GNOME documentation system works and will need to
182 collaborate with GDP members. This document should help to
183 outline the structure of how the GNOME documentation system
184 works. Developers who do not write the documentation for
185 their applications are encouraged to find a GDP member to
186 write the documentation. This is best done by sending an
188 url=
"http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
189 <citetitle>gnome-doc-list mailing list
</citetitle> </ulink>
190 describing the application, where it can be downloaded from,
191 and that the developer(s) would like a GDP member to write
192 documentation for the application. The #docs IRC channel on
193 irc.gnome.org is another option for contacting GDP members.
198 <!-- ####### Introduction | Notation and Conventions ####### -->
200 <sect2 id=
"notation">
201 <title>Notation and Conventions
</title>
203 This Handbook uses the following notation:
204 <informaltable frame=
"none">
209 <filename class=
"directory">/usr/bin
</filename>
217 <filename>foo.sgml
</filename>
225 <command>command
</command>
228 Command or text that would be typed.
233 <command><replaceable>replaceable
</replaceable></command>
236 "Variable" text that can be replaced.
241 <literal>Program or Doc Code
</literal>
243 <entry>Program or document code
</entry>
251 <!-- ####### Introduction | About This Handbook ####### -->
254 <title>About This Handbook
</title>
256 This Handbook is a guide for both writing documentation for
257 GNOME components and applications and for properly binding and
258 packaging documentation into GNOME applications.
261 This Handbook, like all GNOME documentation, was written in
262 DocBook(SGML) and is available in several formats including
263 SGML, HTML, PostScript, and PDF. For the latest version, see
265 url=
"http://developer.gnome.org/projects/gdp/handbook.html">
266 <citetitle>Getting The GNOME Handbook of Writing Software
267 Documentation
</citetitle> </ulink>. Alternately, one may
268 download it anonymously from GNOME CVS under
<filename
269 class=
"directory">gnome-docu/gdp
</filename>.
274 <!-- ################# Getting Started ############### -->
276 <sect1 id=
"gettingstarted">
277 <title>Getting Started Writing GNOME Documentation
</title>
279 <!--####### Getting Started | Selecting A Document ####### -->
281 <sect2 id=
"selecting">
282 <title>Selecting A Document
</title>
285 <title>Document Something You Know
</title>
287 The most frequently asked question of new contributors who
288 join the GDP is
"which document should I start
289 with?". Because most people involved are volunteers, we do
290 not
<emphasis>assign
</emphasis> projects and applications to
291 write documents for. The first step is all yours - you must
292 decide what about GNOME interests you most and find out if
293 it has complete documents or not.
296 It is also important to spend some time with GNOME to make
297 sure you are familiar enough with it to be
298 <emphasis>authoritative
</emphasis> in your writing. The
299 best way to do this is to just sit down and play with GNOME
300 as much as possible before starting to write.
303 The easiest way to get started is to improve existing
304 documentation. If you notice some inaccuracies or omissions
305 in the documentation, or you think that you can explain the
306 material more clearly, just send your suggestions to the
307 author of the original documentation or to the GNOME
308 documentation project at
<email>docs@gnome.org
</email>.
312 <sect3 id=
"doctable">
313 <title>The GNOME Documentation Status Table
</title>
315 The
<citetitle>GDP Documentation Status Table
</citetitle>
316 (
<citetitle>DocTable
</citetitle>) (
<ulink
317 url=
"http://www.gnome.org/gdp/doctable/"
318 type=
"http">http://www.gnome.org/gdp/doctable/
</ulink>) is a
319 web page which tracks the status of all the various
320 documentation components of GNOME. These components include
321 application documentation, internal GNOME component
322 documentation, user documentation, and developer
323 documentation. For each documentation item, it tracks the
324 current status of the documentation, who is working on the
325 particular document, where the documentation can be found,
326 and provides a forum for the discussion of each item.
329 You should use the
<citetitle>DocTable
</citetitle> to help
330 you select a documentation item which needs work done. Once
331 you have selected an item to work on, please register
332 yourself as an author so that other authors do not duplicate
333 your work and may contact you to help or offer suggestions.
334 Also be sure to keep the status icons up-to-date so that
335 the GDP team can easily identify which items need additional
336 help. The
<citetitle>DocTable
</citetitle> also allows
337 people to make announcements and suggestions and to discuss
338 issues in the comments section.
343 Note that the information in the
344 <citetitle>DocTable
</citetitle> may not always be up-to-date
345 or accurate. When you assign yourself to documenting an
346 application, make sure you find out the latest status of
347 documentation by contacting the application author.
353 <!-- ####### Getting Started | Installing And Using DocBook ####### -->
356 <title>Installing and Using DocBook
</title>
358 All documentation for the GNOME project is written in SGML
359 using the DocBook DTD. There are many advantages to using
360 this for documentation, not least of which is the single
361 source nature of SGML. To contribute to the GDP you should
362 learn to use DocBook.
367 To get started writing for the GDP you do not need to rush
368 out and learn DocBook - if you feel it is too much to handle
369 for now, you can submit plain ASCII text to the
<ulink
370 url=
"http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
371 <citetitle>gnome-doc-list mailing list
</citetitle>
372 </ulink>and a volunteer will mark it up for you. Seeing your
373 document marked up will also be a great way for you to start
377 <sect3 id=
"installingdocbook">
378 <title>Installing DocBook
</title>
380 Download and install the following
<ulink
381 url=
"ftp://sourceware.cygnus.com:/pub/docbook-tools/"
382 type=
"ftp">DocBook Tools packages
</ulink>: jade, docbook,
383 jadetex, sgml-common, and stylesheets. (RPM users should note
384 that jade is platform dependent (eg. i386), while the other packages
385 are in the
<filename class=
"directory">noarch
</filename>
386 directory.) You can find more
387 information on DocBook Tools
<ulink url=
"
388 http://sourceware.cygnus.com/docbook-tools/"
389 type=
"http">here
</ulink>.
392 If you are an
<application>Emacs
</application> user you may
393 want to grab the psgml package as well. This is a major mode
394 for editing sgml files in
<application>Emacs
</application>.
398 <sect3 id=
"gdpstylesheets">
399 <title>GDP Stylesheets
</title>
401 The GDP uses its own DocBook stylesheets. To use the GDP
402 stylesheets, you should download the file
403 <filename>gdp-both.dsl
</filename> from the
<filename
404 class=
"directory">gnome-docu/gdp/dsssl
</filename> module in
406 url=
"http://developer.gnome.org/projects/gdp/stylesheets.html">
407 GDP Custom DSSSL Stylesheet
</ulink>)and copy it
409 class="directory">/usr/lib/sgml/stylesheets</filename>. You
410 will need to point DocBook Tools to this stylesheet with the
411 <command><option>-d</option></command> option:
412 <command>db2html -d /usr/lib/sgml/stylesheets/gdp-both.dsl
413 <replaceable>foo.sgml</replaceable></command>. (Creating an
414 alias to include this option and path is convenient.)
415 Alternately, you could overwrite
416 <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>
417 with <filename>gdp-both.dsl</filename>.
420 <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl
</filename>.
421 Alternately, you can download and install the
422 <ulink url=
"http://people.redhat.com/dcm/software.html"
423 type=
"http">gnome-doc-tools package
</ulink> which will set
424 up the stylesheets as well as the DTD discussed below.
429 The current version of the DocBook Tools command
430 <command>db2ps</command> does not have a
431 <command><option>-d</option></command> option. In order to
432 create PostScript output, you must overwrite
433 <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>
434 with <filename>gdp-both.dsl</filename>.
441 <title>GDP DTD (PNG Image Support)
</title>
443 Due to some license issues involved with the creation of
444 gifs, the GNOME Documentation Project has decided to use the
445 PNG image format for all images in GNOME documentation. You
446 can read more about the issues involved with gifs at
<ulink
447 url=
"http://www.gnu.org/philosophy/gif.html"
448 type=
"http">http://www.gnu.org/philosophy/gif.html
</ulink>.
451 The current DocBook DTD(
3.1) does not include support for
452 embedding PNG images in your documents. Since the GDP uses
453 many screenshots in its documentation, we use our own
454 variation on the DocBook DTD which has PNG image support.
455 We encourage everybody to use this DTD instead of the
456 default DocBook DTD since your source document header and
457 your output document appearance subtly vary between the two
458 DTD's. To install the GDP custom DTD with PNG image support
461 <itemizedlist mark=
"opencircle">
465 url=
"http://www.labs.redhat.com/png/png-support.html">the
466 GDP DocBook DTD for PNG support
</ulink> and install it
467 where you keep your DTD's. (On Red Hat use
<filename
468 class=
"directory">/usr/lib/sgml/
</filename>.) Note that
469 the
3.0 DTD is missing support for the
470 <sgmltag><legalnotice
></sgmltag> tag, so it is
471 recommended that you use version
3.1
474 <listitem override=
"bullet">
476 Add the new DTD to your SGML CATALOG file. The location
477 of your SGML CATALOG file may vary depending upon your
478 distribution. (On Red Hat it is usually in
479 /usr/lib/sgml/CATALOG.) Add the following line to this
482 PUBLIC
"-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd"
484 If you are using the
3.1 DTD, use:
486 PUBLIC
"-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd"
492 Alternately, you can download and install the
493 <ulink url=
"http://people.redhat.com/dcm/software.html"
494 type=
"http">gnome-doc-tools package
</ulink> which will set
495 up the custom stylesheets and DTD for you.
498 To include PNG files in your documents, you will need to
499 indicate that you are using this special DTD. To do
500 this, use the following headers:
505 <![CDATA[
<!DOCTYPE Article PUBLIC
"-//GNOME//DTD DocBook PNG Variant
512 <![CDATA[
<!DOCTYPE Book PUBLIC
"-//GNOME//DTD DocBook PNG Variant
520 <title>Editors
</title>
522 There are many editors on Linux and UNIX systems available
523 to you. Which editor you use to work on the sgml documents
524 is completely up to you, as long as the editor is able to
525 preserve sgml and produce the source in a format that is
526 readable by everyone.
529 Probably the two most popular editors available are
530 <application>Emacs
</application> and
531 <application>vi
</application>. These and other editors are
532 used regularly by members of the GDP. Emacs has a major
533 mode, psgml, for editing sgml files which can save you time
534 and effort in adding and closing tags. You will find the
535 psgml package in DocBook Tools, which is the standard set of
536 tools for the GDP. You may find out more about DocBook Tools
537 in
<xref linkend=
"installingdocbook" />.
541 <sect3 id=
"make-output">
542 <title>Creating Something Useful with your Docs
</title>
544 The tools available in DocBook Tools allow you to convert
545 your sgml document to many different formats including html
546 and Postscript. The primary tool used to do the conversion
547 is an application called
<application>Jade
</application>. In
548 most cases you will not have to work directly with
549 <application>Jade
</application>; Instead, you will use the
550 scripts provided by DocBook Tools.
553 To preview your DocBook document, it is easiest to convert
554 it to
<filename>html
</filename>. If you have installed the
555 DocBook tools described above, all you have to do is to run
556 the command
<prompt>$
</prompt><command>db2html
557 mydocument.sgml
</command>. If there are no sgml syntax
558 errors, this will create a directory
<filename
559 class=
"directory">mydocument
</filename> and place the
560 resulting html files in it. The title page of the document
562 <filename>mydocument/index.html
</filename>. If you have
563 screenshots in your document, you will have to copy these
564 files into the
<filename
565 class=
"directory">mydocument
</filename> directory by
566 hand. You can use any web browser to view your document.
567 Note that every time you run
<command>db2html
</command>, it
568 creates the
<filename
569 class=
"directory">mydocument
</filename> directory over, so
570 you will have to copy the screenshots over each time.
573 You can also convert your document to PostScript by running
574 the command
<prompt>$
</prompt><command>db2ps
575 mydocument.sgml
</command>, after which you can print out or
576 view the resulting .ps file.
581 The html files you get will not look quite the same as the
582 documentation distributed with GNOME unless you have the
583 custom stylesheets installed on your machine. DocBook
584 Tools' default stylesheets will produce a different look
585 to your docs. You can read more about the GDP stylesheets
586 in
<xref linkend=
"gdpstylesheets" />.
591 <sect3 id=
"jadeimages">
592 <title>Images in DocBook Tools
</title>
594 If your document uses images you will need to take note of a
595 few things that should take place in order for you to make
596 use of those images in your output.
599 The DocBook Tools scripts and applications are smart enough
600 to know that when you are creating html you will be using
601 PNG files and when you are creating Postscript you will be
602 using EPS files (you must use EPS with Postscript).
605 Thus, you should never explicitly
606 include the extension of the image file, since DocBook
607 Tools will automatically insert it for you. For example:
612 <title>My Image
</title>
614 <screeninfo>Sample GNOME Display
</screeninfo>
615 <graphic format=
"png" fileref=
"myfile" srccredit=
"me">
619 ]]
> </programlisting>
621 You will notice in this example that the file
622 <filename>myfile.png
</filename> was referred to as simply
623 <filename>myfile
</filename>. Now when you run
624 <command>db2html
</command> to create an html file, it will
625 automatically look for
<filename>myfile.png
</filename> in
629 If you want to create PostScript ouput, you will need to create an
630 EPS version of your image file to be displayed in the
631 PostScript file. There is a simple script available which
632 allows you to change a PNG image into an EPS file
633 easily. You can download this file - img2eps - from
<ulink
634 url=
"http://people.redhat.com/dcm/sgml.html"
635 type=
"html">http://people.redhat.com/dcm/sgml.html
</ulink>
636 (look for the img2eps section). Note that this script is
637 included in the gnome-doc-tools package, so if you are using
638 this package, you should already have
639 <command>img2eps
</command> on you system.
643 <sect3 id=
"moredocbookinfo">
644 <title>Learning DocBook
</title>
646 There are many resources available to help you learn DocBook.
647 The following resources on the web are useful for learning
650 <itemizedlist mark=
"bullet">
653 <ulink url=
"http://www.docbook.org"
654 type=
"http">http://www.docbook.org
</ulink> - Norman
655 Walsh's
<citetitle>DocBook: The Definitive
656 Guide
</citetitle>. Online O'Reilly book on using
657 DocBook. Contains an excellent element reference. May be
658 too formal for a beginner.
664 url=
"http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html"
665 type=
"http">A Practical Introduction to DocBook
</ulink>
666 - The Open Source Writers Group's introduction to using
667 DocBook. This is an excellent HOW-TO type article on
674 url=
"http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html"
675 type=
"http">Getting Going with DocBook: Notes for
676 Hackers
</ulink> - Mark Galassi's introduction to DocBook
677 for hackers. This has to be one of the first
678 introductions to DocBook ever - still as good as it ever
684 <ulink type=
"http" url=
"http://www.freebsd.org/tutorials/docproj-primer/">
685 FreeBSD Documentation Project Primer for New
686 Contributors
</ulink> - FreeBSD documentation project
687 primer. Chapter
4.2 provides a very good introduction to
688 writing documentation using DocBook. Note that it also
689 describes some custom extensions of DocBook;
690 fortunately, they are clearly marked as such.
695 Norman Walsh's book is also available in print.
698 The following sections of this document are designed to help
699 documentation authors write correct and consistent DocBook:
701 <itemizedlist mark=
"bullet">
704 <xref linkend=
"docbookbasics" /> - Descriptions of
705 commonly used DocBook tags.
710 You may also discuss specific DocBook questions with GDP
711 members on the #docs IRC channel at irc.gnome.org and on the
712 gnome-doc-list mailing list.
717 <!-- ####### Getting Started | GDP Document Examples ####### -->
719 <sect2 id="examples">
720 <title>GDP Document Examples</title>
722 Examples of various types of GNOME documents are found in
723 <xref linkend="examples" />. There is also an example GNOME
724 application with documentation called
725 <application>gnome-hello</application> in GNOME cvs.
729 <!-- ####### Getting Started | GDP Document Templates ####### -->
731 <sect2 id=
"gdptemplates">
732 <title>GDP Document Templates
</title>
734 Templates for various types of GNOME documents are found in
735 <xref linkend=
"templates" />. They are kept in CVS in
736 gnome-docu/gdp/templates. The easiest source to get them from
737 is probably the
<ulink
738 url=
"http://developer.gnome.org/projects/gdp/templates.html"
740 Document Templates
</ulink> web page, which is typically kept
741 completely up-to-date with CVS and has a basic description of
746 <!-- ####### Getting Started | Screenshots ####### -->
748 <sect2 id=
"screenshots">
749 <title>Screenshots
</title>
751 Most GNOME documents will have screenshots of the particular
752 applet, application, GNOME component, or widget being
753 discussed. As discussed above in
<xref linkend=
"gdpdtd"/> you
754 will need to install the special GDP DocBook DTD which
755 supports PNG images, the format used for all images in GNOME
756 documentation. For the basic DocBook structure used to insert
757 images in a document, see
<xref linkend=
"jadeimages"/> above.
759 <sect3 id=
"screenshotappearance">
760 <title>Screenshot Appearance
</title>
762 For all screenshots of windows that typically have border
763 decorations (e.g. applications and dialogs, but not applets
764 in a
<interface>panel
</interface>), GDP standards dictate
765 the appearance of the window. (This is to minimize possible
766 confusion to the reader, improve the appearance of GNOME
767 documents, and guarantee the screenshot is readable when
768 printed.) All screenshots should be taken with the SawFish
769 (formerly known as Sawmill) window manager using the
770 MicroGui theme and Helvetica
12pt font. (A different window
771 manager can be used provided the MicroGui theme is available
772 for this window manager and the appearance is identical to
773 that when using the SawFish window manager.) The default
774 GTK+ theme(gtk) and font (Helvetica
12 pt) should be used
775 for all screenshots. If you are unable to provide
776 screenshots in this form, you should create screenshots as
777 you wish them to appear and send them to the
778 <ulink url=
"http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
779 <citetitle>gnome-doc-list mailing list
</citetitle> </ulink>
780 requesting a GDP member reproduce these screenshots in the
781 correct format and email them to you.
784 <sect3 id=
"screenshottools">
785 <title>Screenshot Tools
</title>
787 There are many tools for taking screenshots in
788 GNOME/Linux. Perhaps the most convenient is the
789 <application>Screen-Shooter Applet
</application>. Just click
790 on the window icon in the applet and then on the window you
791 would like to take a screenshot of. (Note that
792 at the time of this writing, PNG images taken by
793 screenshooter do not appear properly in
794 <application>Netscape
</application> or the
795 <application>GNOME Help Browser
</application>. You
796 should save your screenshot as a GIF and
797 then use
<command>convert filename.gif
798 filename.png
</command>.) For applets
799 in a
<interface>Panel
</interface>,
800 <application>xv
</application> can be used to crop the
801 screenshot to only include the relevant portion of the
802 <interface>Panel
</interface>. Note that
803 <application>xv
</application> and
804 <application>gimp
</application> can both be used for taking
805 screenshots, cropping screenshots, and converting image
809 <sect3 id=
"screenshotfiles">
810 <title>Screenshot Files
</title>
812 Screenshots should be kept in the main documentation
813 directory with your SGML file for applets, or should be
814 kept in a directory called
"figs" for application and other
815 documentation. After you use
<command>db2html
</command> to
816 convert your SGML file to HTML (see
<xref
817 linkend=
"make-output"/>), you will need to copy your
818 screenshots (either the individual PNG files for applet
819 documentation, or the whole
"figs" directory for other
820 documentation) into the newly created HTML directory. Note
821 that every time you use
<command>db2html
</command> the HTML
822 directory is erased and rewritten, so do not store your only
823 copy of the screenshots in that directory. If you wish to
824 create PostScript or PDF output, you will need to manually
825 convert the PNG images to EPS as described in
<xref
826 linkend=
"jadeimages"/>, but will not need to copy these
827 images from their default location, as they are included
828 directly into the output(PostScript of PDF) file.
834 <!-- ####### Getting Started | Application Bugs ####### -->
836 <sect2 id=
"applicationbugs">
837 <title>Application Bugs
</title>
839 Documentation authors tend to investigate and test applets and
840 applications more thoroughly than most
841 users. Often documentation authors will discover one or
842 more bugs in the software. These bugs vary from small ones,
843 such as mis-spelled words or missing
844 <interface>About
</interface> dialogs in the menu, to large
845 ones which cause the applet to crash. As all users, you
846 should be sure to report these bugs so that application
847 developers know of them and can fix them. The easiest way to
848 submit a bug report is by using the
<application>Bug
849 Buddy
</application> applet which is part of the gnome-applets
855 <!-- ####### Getting Started | Using CVS ####### -->
858 <title>Using CVS
</title>
860 CVS (Concurrent Versions System) is a tool that allows
861 multiple developers to concurrently work on a set of
862 documents, keeping track of the modifications made by each
863 person. The files are stored on a server and each developer
864 checks files out, modifies them, and then checks in their
865 modified version of the files. Many GNOME programs and
866 documents are stored in CVS. The GNOME CVS server allows
867 users to anonymously check out CVS files. Most GDP members
868 will need to use anonymous CVS to download the most up-to-date
869 version of documentation or programs. Modified documents will
870 typically be emailed to the the application developer. Core
871 GDP members may also be granted login CVS privileges so they
872 may commit modified files directly to CVS.
875 <sect3 id=
"anonymouscvs">
876 <title>Anonymous CVS
</title>
878 To anonymously check out documents from CVS, you must first
879 log in. From the bash shell, you should set your CVSROOT
880 shell variable with
<command> export
881 CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'
</command>
882 and then login with
<command>cvs login
</command>(there is no
883 password, just hit return). As an example, we will use the
884 "gnome-docu/gdp" module which contains this and several
885 other documents. To check these documents out for the first
886 time, type
<command>cvs -z3 checkout
887 gnome-docu/gdp
</command>. After you have this document
888 checked out and you would like to download any updates on
889 the CVS server, use
<command>cvs -z3 update -Pd
</command>.
893 <sect3 id=
"logincvs">
894 <title>Login CVS
</title> <para> If you have been given a
895 login for the GNOME CVS server, you may commit your file
896 modifications to CVS. Be sure to read the following section
897 on CVS etiquette before making any commits to CVS. To log in
898 to the CVS server as user
899 <command><replaceable>username
</replaceable></command> with a
900 password, you must first set your CVSROOT shell variable with
902 CVSROOT=':pserver:
<replaceable>username
</replaceable>@cvs.gnome.org:/cvs/gnome'
</command>.
903 Log in with
<command>cvs login
</command> and enter your
904 password. You may check out and update modules as described
905 above for anonymous CVS access. As a login CVS user, you may
906 also check modified versions of a file into the CVS server.
908 <command><replaceable>filename
</replaceable></command> into
909 the CVS server, type
<command>cvs -z3 commit
910 <replaceable>filename
</replaceable></command>. You will be
911 given a vi editor window to type in a brief log entry,
912 summarizing your changes. The default editor can be changed
913 using the
<varname>EDITOR
</varname> environment variable or
914 with the
<command><option>-e
</option></command> option. You
915 may also check in any modifications to files in the working
916 directory and subdirectories using
<command>cvs -z3
918 add a new file to the CVS server, use
<command>cvs -z3 add
919 <replaceable>filename
</replaceable></command>, followed by the
924 <sect3 id=
"cvsetiquette">
925 <title>CVS Etiquette
</title>
927 Because files in CVS are typically used and modified by
928 multiple developers and documentation authors, users should
929 exercise a few simple practices out of courtesy towards the
930 other CVS users and the project leader. First, you should
931 not make CVS commits to a package without first discussing
932 your plans with the project leader. This way, the project
933 leader knows who is modifying the files and generally, what
934 sort of changes/development is being done. Also, whenever a
935 CVS user commits a file to CVS, they should make an entry in
936 the CVS log and in the
<filename>ChangeLog
</filename> so
937 that other users know who is making modifications and what
938 is being modified. When modifying files created by others,
939 you should follow the indentation scheme used by the initial
946 <!-- ################# The GNOME Documentation System###############
949 <sect1 id=
"gnomedocsystem">
950 <title>The GNOME Documentation System
</title>
952 <!-- ####### The GNOME Documentation System | The GNOME Help Browser
955 <sect2 id=
"gnomehelpbrowser">
956 <title>The GNOME Help Browser
</title>
958 At the core of the GNOME help system is the
<application>GNOME
959 Help Browser
</application>. The
<application>Help
960 Browser
</application> provides a unified interface to several
961 distinct documentation systems on Linux/Unix systems: man
962 pages, texinfo pages, Linux Documentation Project(LDP)
963 documents, GNOME application documentation, and other GNOME
967 The
<application>GNOME Help Browser
</application> works by
968 searching standard directories for documents which are to be
969 presented. Thus, the documentation that appears in the GHB is
970 specific to each computer and will typically only represent
971 software that is installed on the computer.
975 <!-- ####### The GNOME Documentation System | The GNOME Help Browser
978 <sect2 id=
"gnomehelpbrowser2">
979 <title>The GNOME Help Browser (GNOME-
2.0)
</title> <para> In
980 GNOME
2.0, the
<application>GNOME Help Browser
</application>
981 will be replaced by
<application>Nautilus
</application>.
982 Nautilus will be the file manager/graphical shell for GNOME
2.0
983 and will also implement a more sophisticated help system than
984 that used by the
<application>GNOME Help Browser
</application>
985 used in GNOME
1.0. It will read and display DocBook files
986 directly, avoiding the need for duplicating documents in both
987 DocBook and HTML formats. Its display engine for DocBook will
988 be much faster than running
<application>jade
</application> to
989 convert to HTML for rendering. Because it uses the original
990 DocBook source for documentation, it will be possible to do more
991 sophisticated searching using the meta information included in
992 the documents. And since Nautilus is a virtual file system
993 layer which is Internet-capable, it will be able to find and
994 display documents which are on the web as well as those on the
995 local file system. For more information on
996 <application>Nautilus
</application>, visit the #nautilus IRC
997 channel on irc.gnome.org.
</para>
1000 <!-- ####### The GNOME Documentation System | GNOME On-The-Fly
1001 Documentation Generation ####### -->
1003 <sect2 id=
"gnomehelponthefly">
1004 <title>Dynamic Document Synthesis(GNOME-
2.0)
</title>
1006 GNOME uses the documentation presented by all the various
1007 GNOME components and applications installed on the system to
1008 present a complete and customized documentation environment
1009 describing only components which are currently installed on a
1010 users system. Some of this documentation, such as the manuals
1011 for applets, will be combined in such a way that it appears to
1012 be a single document.
1015 By using such a system, you can be sure that any GNOME app you
1016 install that has documentation will show up in the index,
1017 table of contents, any search you do in the help browser.
1021 <!-- ####### The GNOME Documentation System | The GNOME Documentation
1022 Components ####### -->
1024 <sect2 id=
"gnomehelpcomponents">
1025 <title>The GNOME Documentation Components
</title>
1027 <sect3 id=
"applicationmanualsintro">
1028 <title>Application Manuals
</title>
1030 Every GNOME application should have an application manual.
1031 An application manual is a document specific to the
1032 particular application which explains the various windows
1033 and features of the application. Application Manuals
1034 typically use screenshots (PNG format) for clarity. Writing
1035 application manuals is discussed in more detail in
<xref
1036 linkend=
"writingapplicationmanuals" /> below.
1040 <sect3 id=
"applicationhelpintro">
1041 <title>Application Help
</title>
1043 Applications should have a
<guibutton>Help
</guibutton>
1044 button on screens on which users may need help. These
1045 <guibutton>Help
</guibutton> buttons should pull up the
1046 default help browser, determined by the
1047 <varname>ghelp
</varname> URL Handler (configured using the
1048 <application>Control Center
</application>), typically the
1049 <application>GNOME Help Browser
</application>. The help
1050 browser should show either the first page of the application
1051 manual, or else the relevant page thereof. Application help
1052 is described in more detail in
<xref
1053 linkend=
"applicationhelpbuttons" /> below.
1057 <sect3 id=
"contextsensitivehelpintro">
1058 <title>Application Context Sensitive Help (coming in
1061 Context sensitive help is a system which will allow the user
1062 to query any part (button, widget, etc.) of an application
1063 window. This is done by either entering a CS Help mode by
1064 clicking on an icon or by right clicking on the application
1065 part and selecting
"What's This" or whatever is decided on
1066 at the time. Context sensitive help is described in more
1067 detail in
<xref linkend=
"writingcontextsensitivehelp" />
1072 <sect3 id=
"userguide">
1073 <title>The GNOME User Guide
</title>
1075 The
<citetitle>GNOME User Guide
</citetitle> describes the
1076 GNOME desktop environment and core components of GNOME such
1077 as the
<application>panel
</application> and
1078 <application>control center
</application>. In GNOME
1.x this
1079 was the main and only source of documentation. In GNOME
2.0
1080 this will become a document for the web and for printing
1081 that is derived from various parts chosen in the system that
1082 are necessary for the new user to understand.
1086 <sect3 id=
"userdocs">
1087 <title>User Documents
</title>
1089 Aside from the
<citetitle>GNOME User Guide
</citetitle>,
1090 there are several other documents to help GNOME users learn
1091 GNOME, including the
<citetitle>GNOME FAQ
</citetitle>,
1092 <citetitle>GNOME Installation and Configuration
1093 Guide
</citetitle>, and the
<citetitle>GNOME Administrators
1098 <sect3 id=
"developerdocs">
1099 <title>Developer Documents
</title>
1101 There are many White Papers, Tutorials, HOWTO's and FAQ's to
1102 make programming GNOME and GNOME applications as easy as
1106 API documentation is also available for the GNOME libraries. This is
1107 detailed documentation of the code that is used to build GNOME
1108 apps. You can keep up with the GNOME API docs on the
<ulink
1109 url=
"http://developer.gnome.org/doc/API/" type=
"http">GNOME API
1110 Reference
</ulink> page.
1114 <sect3 id=
"projectdocs">
1115 <title>Project Documents
</title>
1117 Some GNOME projects have documentation to maintain
1118 consistency in their product and to help new contributors
1119 get up to speed quickly. Among these are the GDP documents,
1120 such as the one you are reading now.
1127 <!-- ################# DocBook Basics ############### -->
1129 <sect1 id=
"docbookbasics">
1130 <title>DocBook Basics
</title>
1131 <!-- ####### DocBook Basics | Introduction to DocBook ####### -->
1133 <sect2 id=
"introtodocbook">
1134 <title>Introduction to DocBook
</title>
1136 To understand DocBook, a basic understanding of SGML is
1137 helpful. SGML stands for Standard General Markup Language and
1138 is one of the first markup languages every created. HTML is
1139 actually derived from SGML and XML is a subset of SGML. SGML
1140 uses what is called a Document Type Definition to specify
1141 <emphasis>elements
</emphasis> which are contained between
1142 brackets,
< and
>. Text is marked by both beginning and
1143 ending elements, for example in the DocBook DTD, one denotes a
1144 title with
<sgmltag><title
></sgmltag>The
1145 Title
<sgmltag></title
></sgmltag>.
1148 The DTD (in the case of the GDP, DocBook) defines rules for how the
1149 elements can be used. For example, if one element can only be used when
1150 embedded within another, this is defined in the DTD.
1153 An SGML file is just a plain ASCII file containing the text
1154 with the markup specified above. To convert it to some easily
1155 readable format, you need special tools. The GDP uses
<emphasis>DocBook
1156 Tools
</emphasis>, a free package of utilities for working with DocBook
1157 which includes
<emphasis>Jade
</emphasis>, which does the SGML/DSSL
1158 parsing. You can read more about DocBook Tools in
<xref
1159 linkend=
"installingdocbook" />.
1162 The final appearance of the output (e.g. PostScript or HTML)
1164 <emphasis>stylesheet
</emphasis>. Stylesheets are files,
1165 written in a special language (DSSSL
— Document Style
1166 Semantics and Specification Language), which specify the
1167 appearance of various DocBook elements, for example,
1168 what fonts to use for titles and various inline elements, page
1169 numbering style, and much more. DocBook tools come with a
1170 collection of stylesheets (Norman Walsh's modular
1171 stylesheets); GNOME Document Project uses some customized
1172 version of this stylesheets
— see
<xref
1173 linkend=
"gdpstylesheets"/>.
1176 The advantage of specifying the
<emphasis>structure
</emphasis>
1177 of a document with SGML instead of specifying the
1178 <emphasis>appearance
</emphasis> of the document with a typical
1179 word processor, or with html, is that the resulting document
1180 can be processed in a variety of ways using the structural
1181 information. Whereas formatting a document for appearance
1182 assumes a medium (typically written text on a standard-sized
1183 piece of paper), SGML can be processed to produce output for a
1184 large variety of media such as text, postscript, HTML,
1185 Braille, audio, and potentially many other formats.
1188 Using 'content' as the elements to define the text of a document also
1189 allows for search engines to make use of the actual elements to make a
1190 "smarter search". For example, if you are searching for all documents
1191 written by the author
"Susie" your search engine could be made smart
1192 enough to only search
<author
> elements, making for a faster and more
1196 Since the overall appearance of the output is determined not by the DTD
1197 or the SGML document, but rather by a stylesheet, the appearance of a
1198 document can be easily changed just by changing the stylesheet. This
1199 allows everyone in the project to create documents that all look the
1203 As stated before, the GDP uses the DocBook DTD. For a list of
1204 introductory and reference resources on DocBook, see
<xref
1205 linkend=
"resources" />. The following sections also provide
1206 convenient instructions on which markup tags to use in various
1207 circumstances. Be sure to read
<xref linkend=
"conventions" />
1208 for GDP documentation-specific guidelines.
1212 <!-- ###### DocBook Basics | XML and SGML ########-->
1214 <title>XML and SGML
</title>
1216 <para> In not so distant future (probably before GNOME
2.0),
1217 DocBook itself and GNOME Documentation project will migrate from
1218 SGML to XML. This transition should be relatively painless:
1219 (almost) all DocBook tags will remain the same. However, XML has
1220 stricter syntax rules than SGML; thus, some constructions which
1221 are valid in SGML will not be valid in XML. Therefore, to be
1222 ready for this transistion, it is
<emphasis>strongly
1223 advised
</emphasis> that the documentation writers conform to XML
1224 syntax rules. Here are most important differences:
1229 <term> <emphasis>Minimization
</emphasis></term>
1233 It is possible with some implementations of SGML to use
1234 minimizations to close elements in a document by using
1235 </>, for example:
1236 <literal><sgmltag><title
></sgmltag>The
1237 Title
<sgmltag></></sgmltag></literal>. This is not
1238 allowed in XML. You can use
<command>sgmlnorm
</command> command,
1239 included in DocBook Tools package, to expand minimized tags;
1240 if you are using
<application>Emacs
</application> with psgml
1241 mode, you can also use menu command
1243 <guimenu>Modify
</guimenu>
1244 <guimenuitem>Normalize
</guimenuitem>
1250 <term> <emphasis>Self-closing tags
</emphasis></term>
1254 Also, in SGML some tags are allowed not to have closing
1255 tags. For example, it is legal for
1256 <sgmltag><xref
></sgmltag> not to have a closing tag:
1257 <literal><sgmltag><xref
1258 linkend=
"someid"></sgmltag></literal>. In
1259 XML, it is illegal; instead, you should use
1260 <literal><sgmltag><xref
1261 linkend=
"someid"/></sgmltag></literal> (note the
1268 <term> <emphasis>Case sensitive tags
</emphasis></term>
1271 In XML, unlike SGML, tags are case-senstive
1272 <sgmltag><title
></sgmltag> and
1273 <sgmltag><TITLE
></sgmltag> are different tags!
1274 Therefore, please always use lowercase tags (except for
1275 things like
<literal>DOCTYPE, CDATA
</literal> and
1276 <literal>ENTITY
</literal>, which are not DocBook tags).
1288 <!-- ####### DocBook Basics | Structure Elements ####### -->
1291 <sect2 id=
"structure"> <title> Structure Elements
</title>
1293 <sect3 id=
"section">
1294 <title>Sections and paragraphs
</title>
1296 Top-level element of a book body must be
1297 <sgmltag><chapter
></sgmltag>; it may contain one or more
1298 <sgmltag><sect1
></sgmltag>, each of them may contain
1299 <sgmltag><sect2
></sgmltag> and so on up to
1300 <sgmltag><sect5
></sgmltag>. The top-level element of an
1301 article body is always
1302 <sgmltag><sect1
></sgmltag>. Regardless of which elements
1303 you use, give each structural element a unique id, so that
1304 you can link to it. For usage example, see the template.
1306 <para> Please try to avoid using deeply nested sections; for
1307 most situations,
<sgmltag><sect1
></sgmltag> and
1308 <sgmltag><sect2
></sgmltag> should be sufficient. If not,
1309 you probably should split your
<sgmltag><sect1
></sgmltag>
1310 into several smaller ones.
1312 <para> Use the tag
<sgmltag><para
></sgmltag> for
1313 paragraphs, even if there is only one paragraph in a
1314 section
—see template for examples.
1319 <title>Notes, Warnings, And Tips
</title>
1321 For notes, tips, warnings, and important information, which
1322 should be set apart from the main text (usually as a
1323 paragraph with some warning sign on the margin), use tags
1324 <sgmltag><note
></sgmltag>,
<sgmltag><tip
></sgmltag>,
1325 <sgmltag><warning
></sgmltag>,
1326 <sgmltag><important
></sgmltag> respectively. For example:
1332 To speed up program compilation, use
<application>gcc
</application>
1333 compiler with Pentium optimization.
1335 </tip>]]
> </programlisting> produces
1340 To speed up program compilation, use
1341 <application>gcc
</application> compiler with Pentium
1342 optimization.
</para>
1345 Note that this should not be inside a
1346 <sgmltag><para
></sgmltag> but between paragraphs.
1349 <sect3 id=
"figures">
1350 <title> Screenshots and other figures
</title>
1352 To include screenshots and other figures, use the following
1358 <title>Screenshot
</title>
1360 <screeninfo>Screenshot of a program
</screeninfo>
1361 <graphic format=
"PNG" fileref=
"figures/example_screenshot" srccredit=
"ME">
1366 replacing
<filename>example_screenshot
</filename> with the
1367 actual file name (without extension). The result will look like this:
1370 <title>Screenshot
</title>
1372 <screeninfo>Screenshot of a program
</screeninfo>
1373 <graphic format=
"PNG"
1374 fileref=
"figures/example_screenshot" srccredit=
"ME"/>
1382 Notice in this example that the screenshot file name does
1383 not include the file type extension
— to find out
1384 why, please read
<xref linkend=
"jadeimages" />.
1388 <sect3 id=
"listing">
1389 <title>Program listings and terminal session
</title> <para>
1390 To show a file fragment
—for example, program
1391 listing
—use
<sgmltag><programlisting
></sgmltag> tag:
1396 Name=Gnumeric spreadsheet
1398 Icon=gnome-gnumeric.png
1401 </programlisting>]]
>
1406 Name=Gnumeric spreadsheet
1408 Icon=gnome-gnumeric.png
1412 As a matter of fact, all examples in this document were
1413 produced using
<sgmltag><programlisting
></sgmltag>.
1416 To show a record of terminal session
—i.e., sequence of
1417 commands entered at the command line
—use
1418 <sgmltag><screen
></sgmltag> tag:
1422 <prompt>bash$
</prompt><userinput>make love
</userinput>
1423 make: *** No rule to make target `love'. Stop.
1428 <prompt>bash$
</prompt><userinput>make love
</userinput>
1429 make: *** No rule to make target `love'. Stop.
1431 Note the use of tags
<sgmltag><prompt
></sgmltag> and
1432 <sgmltag><userinput
></sgmltag> for marking system prompt
1433 and commands entered by user.
1437 Note that both
<sgmltag><programlisting
></sgmltag>
1438 and
<sgmltag><screen
></sgmltag> preserve linebreaks,
1439 but interpret SGML tags (unlike LaTeX
1440 <markup>verbatim
</markup> environment). Take a look at
1441 the source of this document to see how you can have SGML
1442 tags literally shown but not interpreted,
1448 <title> Lists
</title>
1450 The most common list types in DocBook are
1451 <sgmltag><itemizedlist
></sgmltag>,
1452 <sgmltag><orderedlist
></sgmltag>, and
1453 <sgmltag><variablelist
></sgmltag>.
1457 <term> <sgmltag><itemizedlist
></sgmltag></term>
1459 This is the simplest unnumbered list, parallel to
1460 <sgmltag><ul
></sgmltag> in HTML. Here is an example:
1466 <guilabel>Show backup files
</guilabel> — This will
1467 show any backup file that might be on your system.
1472 <guilabel>Show hidden files
</guilabel> — This will
1473 show all
"dot files" or files that begin with a dot. This
1474 files typically include configuration files and directories.
1479 <guilabel>Mix files and directories
</guilabel> — This
1480 option will display files and directories in the order you
1481 sort them instead of
1482 always having directories shown above files.
1493 <guilabel>Show backup files
</guilabel> —
1494 This will show any backup file that might be on
1501 <guilabel>Show hidden files
</guilabel> —
1502 This will show all
"dot files" or files that
1503 begin with a dot. This files typically include
1504 configuration files and directories.
1510 <guilabel>Mix files and directories
</guilabel>
1511 — This option will display files and
1512 directories in the order you sort them instead
1513 of always having directories shown above files.
1517 <para> Note the use of
<sgmltag>&mdash;
</sgmltag>
1518 for long dash (see
<xref linkend=
"specsymb" />). Also,
1519 please note that the result looks much nicer because the
1520 terms being explained (
<guilabel>Show backup
1521 files
</guilabel>, etc.) are set in a different font. In
1522 this case, it was achieved by using
<link
1523 linkend=
"gui"><sgmltag><guilabel
></sgmltag></link>
1524 tag. In other cases, use appropriate tags such as
1525 <link linkend=
"gui"><sgmltag><guimenuitem
></sgmltag></link>,
1527 linkend=
"filenames"><sgmltag><command
></sgmltag></link>,
1528 or
— if none of
1529 this applies
— use
1530 <link linkend=
"gui"><sgmltag><emphasis
></sgmltag></link>.
1535 <term> <sgmltag><orderedlist
></sgmltag></term>
1537 This list is completely analogous to
1538 <sgmltag><itemizedlist
></sgmltag> and has the same
1539 syntax, but it produces numbered list. By default,
1540 this list uses Arabic numerals for numbering entries;
1541 you can override this using
<sgmltag>numeration
</sgmltag>,
1542 for example
<sgmltag><orderedlist
1543 numeration=
"lowerroman"></sgmltag>. Possible values of
1544 these attribute are
<sgmltag>arabic
</sgmltag>,
1545 <sgmltag>upperalpha
</sgmltag>,
1546 <sgmltag>loweralpha
</sgmltag>,
1547 <sgmltag>upperroman
</sgmltag>,
1548 <sgmltag>lowerroman
</sgmltag>.
1553 <term> <sgmltag><variablelist
></sgmltag></term>
1554 <listitem><para> This list is used when each entry is
1555 rather long, so it should be formatted as a block of text
1556 with some subtitle, like a small subsection. The
1557 <sgmltag><variablelist
></sgmltag> is more complicated
1558 than itemizedlists, but for larger blocks of text, or when
1559 you're explaining or defining something, it's best to use
1560 them. Their greatest advantage is that it's easier for a
1561 computer to search. The lines you are reading now were
1562 produced by
<sgmltag><variablelist
></sgmltag>. The
1563 source looked liked this:
1568 <term> <sgmltag><itemizedlist
></sgmltag></term>
1570 This is the simplest unnumbered list, parallel to
1571 <sgmltag><ul
></sgmltag> in HTML. Here is an example:...
1575 <term> <sgmltag><orderedlist
></sgmltag></term>
1577 This list is completely analogous to
1578 <sgmltag><itemizedlist
></sgmltag>
1582 <term> <sgmltag><variablelist
></sgmltag></term>
1584 This list is used when each entry is rather long,...
1595 Lists can be nested; in this case, the stylesheets
1596 are smart enough to change the numeration (for
1597 <sgmltag><orderedlist
></sgmltag>) or marks of each entry
1598 (in
<sgmltag><itemizedlist
></sgmltag>) for sub-lists
1604 <!-- ####### DocBook Basics | Inline Elements ####### -->
1607 <title>Inline Elements
</title>
1610 <title>GUI elements
</title>
1614 <sgmltag><guibutton
></sgmltag> — used for
1615 buttons, including checkbuttons and radio buttons
1621 <sgmltag><guimenu
></sgmltag>,
1622 <sgmltag><guisubmenu
></sgmltag> —used for
1623 top-level menus and submenus
1624 respectively, for example
<literal><![CDATA[
1625 <guisubmenu>Utilities
</guisubmenu> submenu of the
1626 <guimenu>Main Menu
</guimenu>]]
></literal>
1632 <sgmltag><guimenuitem
></sgmltag>—an entry in a
1639 <sgmltag><guiicon
></sgmltag>—an icon
1645 <sgmltag><guilabel
></sgmltag>—for items which have
1646 labels, like tabs, or bounding boxes.
1651 <sgmltag><interface
></sgmltag>— for most everything
1652 else... a window, a dialog box, the Panel, etc.
1657 If you need to refer to a sequence of menu choices, such as
1659 <guimenu>Main Menu
</guimenu>
1660 <guisubmenu>Utilities
</guisubmenu> <guimenuitem>GNOME
1661 terminal
</guimenuitem>
1663 there is a special construction for this, too:
1667 <guimenu>Main Menu
</guimenu> <guisubmenu>Utilities
</guisubmenu>
1668 <guimenuitem>GNOME terminal
</guimenuitem> </menuchoice>]]
>
1674 <title>Links and references
</title>
1676 To refer to another place in the same document, you can use
1677 tags
<sgmltag><xref
></sgmltag> and
1678 <sgmltag><link
></sgmltag>. The first of them
1679 automatically inserts the full name of the element you refer
1680 to (section, figure, etc.), while the second just creates a
1681 link (in HTML output). Here is an example:
1683 <![CDATA[An example of a
<link linkend=
"extip">tip
</link> was given in
1684 <xref linkend=
"notes" />. ]]
>
1686 which produces: An example of a
<link
1687 linkend=
"extip">tip
</link> was given in
<xref
1691 Here
<sgmltag>notes
</sgmltag> and
<sgmltag>extip
</sgmltag>
1692 are the id attributes of
<xref linkend=
"notes" /> and of the
1693 example of a tip in it.
1695 <para> To produce a link to an external source, such as a
1696 Web page or a local file, use
<sgmltag><ulink
></sgmltag>
1699 <![CDATA[ To find more about GNOME, please visit
<ulink type=
"http"
1700 url=
"http://www.gnome.org">GNOME Web page
</ulink> ]]
>
1702 which produces: To find more about GNOME, please visit
1703 <ulink type=
"http" url=
"http://www.gnome.org">The GNOME Web
1704 Site
</ulink> You can use any of the standard URL types, such
1705 as
<literal>http, ftp, file, telnet, mailto
</literal> (in
1706 most cases, however, use of
<literal>mailto
</literal> is
1707 unnecessary
—see discussion of
1708 <sgmltag><email
></sgmltag> tag).
1712 <sect3 id=
"filenames"> <title>Filenames, commands, and other
1713 computer-related things
</title>
1715 Here are some tags used to describe operating system-related
1720 <para> <sgmltag><filename
></sgmltag> — used
1722 e.g.
<sgmltag><filename
></sgmltag>
1724 <sgmltag></filename
></sgmltag>
1725 produces:
<filename>foo.sgml
</filename>.
1729 <para> <sgmltag><filename
1730 class=
"directory"></sgmltag> — used for
1731 directories, e.g.
<sgmltag><filename
1732 class=
"directory"></sgmltag>/usr/bin
1733 <sgmltag></filename
></sgmltag>
1735 class=
"directory">/usr/bin
</filename>.
1740 <sgmltag><application
></sgmltag> — used for
1742 e.g.
<sgmltag><application
></sgmltag>Gnumeric
1743 <sgmltag></application
></sgmltag> produces:
1744 <application>Gnumeric
</application>.
1749 <sgmltag><envar
></sgmltag> — used for
1750 environment variables, e.g.
1751 <sgmltag><envar
></sgmltag>PATH
<sgmltag></envar
></sgmltag>.
1757 <sgmltag><command
></sgmltag> — used for
1758 commands entered on command line, e.g.
1759 <sgmltag><command
></sgmltag>make install
1760 <sgmltag></command
></sgmltag> produces:
1761 <command>make install
</command>.
1766 <sgmltag><replaceable
></sgmltag> — used for
1767 replaceable text, e.g.
1768 <sgmltag><command
></sgmltag>db2html
<sgmltag><replaceable
></sgmltag>
1770 <sgmltag></replaceable
></sgmltag><sgmltag></command
></sgmltag>
1771 produces:
<command>db2html
1772 <replaceable>foo.sgml
</replaceable></command>.
1779 <title>Keyboard input
</title>
1780 <para> To mark up text input by the user, use
1781 <sgmltag><userinput
></sgmltag>.
1783 <para> To mark keystrokes such as shortcuts and other
1784 commands, use
<sgmltag><keycap
></sgmltag>.
1785 This is used for marking up what is printed on the top
1786 of the physical key on the keyboard. There are a couple of
1787 other tags for keys, too:
<sgmltag><keysym
></sgmltag>
1788 and
<sgmltag><keycode
></sgmltag>. However you are
1789 unlikely to need these for most documentation. For reference,
1790 <sgmltag><keysym
></sgmltag> is for the
<quote>symbolic
1791 name
</quote> of a key.
<sgmltag><keycode
></sgmltag> is
1792 for the
<quote>scan code
</quote> of a key. These are not
1793 terms commonly required in
<acronym>GNOME
</acronym> documentation,
1794 although
<sgmltag><keysym
></sgmltag> is useful for marking
1798 To mark up a combination of keystrokes, use the
1799 <sgmltag><keycombo
></sgmltag> wrapper:
1803 <keycap>Ctrl
</keycap>
1804 <keycap>Alt
</keycap>
1810 Finally, if you want to show a shortcut for some menu
1811 command, here are the appropriate tags (rather long):
1816 <keycombo><keycap>Ctrl
</keycap><keycap>q
</keycap></keycombo>
1818 <guimenuitem> Quit
</guimenuitem>
1821 which produces simply
1823 <shortcut> <keysym>Ctrl-q
</keysym> </shortcut>
1824 <guimenuitem> Quit
</guimenuitem>
1830 <title>E-mail addresses
</title> <para> To mark up e-mail
1831 address, use
<sgmltag><email
></sgmltag>:
1833 <![CDATA[ The easiest way to get in touch with me is by e-mail
1834 (
<email>me@mydomain.com
</email>)]]
>
1836 which produces: The easiest way to get in touch with me is
1837 by e-mail (
<email>me@mydomain.com
</email>) Note that
1838 <sgmltag><email
></sgmltag> automatically produces a link
1843 <sect3 id=
"specsymb">
1844 <title> Special symbols
</title>
1846 DocBook also provides special means for entering
1847 typographic symbols which can not be entered directly
1848 form the keyboard (such as copyright sign). This is done using
1849 <emphasis>entities
</emphasis>, which is SGML analogue of
1850 macros, or commands, of LaTeX. They generally have the form
1851 <sgmltag>&entityname;
</sgmltag>. Note that the semicolon
1855 here is partial list of most commonly used enitites:
1859 <sgmltag>&amp;
</sgmltag> — ampersend (
&)
1862 <sgmltag>&lt;
</sgmltag> — left angle bracket (
<)
1865 <sgmltag>&copy;
</sgmltag> — copyright sign (
©)
1868 <sgmltag>&mdash;
</sgmltag> — long dash (
—)
1871 <sgmltag>&hellip;
</sgmltag> — ellipsis (
…)
1875 Note that the actual look of the resulting symbols depends
1876 on the fonts used by your browser; for example, it might
1877 happen that long dash (
<sgmltag>&mdash;
</sgmltag>) looks
1878 exactly like the usual dash (-). However, in the PostScript
1879 (and thus, in print) the output will look markedly better if
1880 you use appropriate tags.
1886 <!-- ################# GDP Documentation Conventions ############### -->
1888 <sect1 id=
"conventions">
1889 <title>GDP Documentation Conventions
</title>
1891 <!-- ####### GDP Documentation Conventions | All Documentation ####### -->
1893 <sect2 id=
"conventionsalldocs">
1894 <title>Conventions for All GDP Documentation
</title>
1895 <sect3 id=
"xmlcomp">
1896 <title> XML compatibility
</title>
1898 All GNOME documentation should conform to XML syntax
1899 requirements, which are stricter than SGML ones
— see
1900 <xref linkend=
"xml" /> for more informaion.
1904 <sect3 id=
"authorsnames">
1905 <title> Authors' names
</title>
1907 All GNOME documentation should contain the names of both the
1908 application authors and documentation authors, as well as a
1909 link to the application web page (if it exists) and
1910 information for bug submission
— see templates for an
1916 <!-- ####### GDP Documentation Conventions | All Documentation ####### -->
1918 <sect2 id=
"conventionsappdocs">
1919 <title>Conventions for Application Documentation
</title>
1921 <sect3 id=
"applicationversionid">
1922 <title>Application Version Identification
</title>
1924 Application documentation should identify the version of the
1925 application for which the documentation is written:
1929 <title>Introduction
</title>
1931 blah-blah-blah This document describes version
1.0.53 of gfoo.
1937 <sect3 id=
"license">
1938 <title> Copyright information
</title>
1940 documentation should contain a copyright notice, stating the
1941 licensing terms. It is suggested that you use the GNU Free
1942 Documentation License. You could also use some other license
1943 allowing free redistribution, such as GPL or Open Content
1944 license. If documentation uses some trademarks (such as UNIX,
1945 Linux, Windows, etc.), proper legal junk should also be
1946 included (see templates).
1949 <sect3 id=
"license2">
1950 <title>Software license
</title>
1952 All GNOME applications must contain information about the
1953 license (for software, not for documentation), either in the
1954 "About" box or in the manual.
1958 <sect3 id=
"bugtraq">
1959 <title> Bug reporting
</title>
1961 Application documentation should give an address for
1962 reporting bugs and for submitting comments about the
1963 documentaion (see templates for an example).
1969 <!-- ################# Writing Application Manuals ###############-->
1971 <sect1 id=
"writingapplicationmanuals">
1972 <title>Writing Application and Applet Manuals
</title>
1974 Every GNOME application or applet should have a manual specific
1975 to that particular application. This manual should be a complete
1976 and authoritative guide. The manual should describe what the
1977 program does and how to use it. Manuals will typically describe
1978 each window or panel presented to the user using screenshots (in
1979 PNG format only) when appropriate. They should also describe
1980 each feature and preference option available.
1983 <title>Documentation Availability
</title>
1985 Applications and applets should not rely on documentation
1986 which is only available on the internet. All manuals and
1987 other documentation should be packaged with the application or
1988 applet and be made available to the user through the standard
1989 GNOME help system methods described below.
1992 <para> Application manuals should be based on the template in
1993 <xref linkend=
"template1" />. Applet manuals should be based on
1994 the templates in
<xref linkend=
"template2-1x" /> for GNOME
1995 versions
1.x and the templates in
<xref linkend=
"template2-2x" />
1996 for GNOME versions
2.x.
1999 <title>Manuals For Large Applications
</title>
2001 Manuals for very large applications, such as GNOME Workshop
2002 components should be a
<sgmltag><book
></sgmltag> (and thus
2003 use
<sgmltag><chapter
></sgmltag> for each primary section)
2004 , instead of
<sgmltag><article
></sgmltag> which most
2005 applications use(with each primary section being a
2006 <sgmltag><sect1
></sgmltag>).
2010 <title>Applet Manuals in GNOME
2.0</title>
2012 Note that applet manuals in GNOME
2.0 are treated in a special
2013 way. The manuals for all applets are merged into a single
2014 virtual document by Nautilus. For this reason, the header
2015 information for applet manuals is omitted and the first
2016 section of each applet is
2017 <sgmltag><sect1
></sgmltag>. Applet manuals will typically
2018 have several sections, each of which is
2019 <sgmltag><sect2
></sgmltag>.
2023 Application manuals should be made available by having a
2024 "Manual" entry in the
<guimenu>Help
</guimenu> pull-down menu
2026 application, as described in
<xref linkend=
"listingdocsinhelpmenu" />.
2027 Applets should make their manuals available by
2028 right-clicking on the applet.
2033 <!-- ############### Listing Documents in the Help Menu ############# -->
2035 <sect1 id=
"listingdocsinhelpmenu">
2036 <title>Listing Documents in the Help Menu
</title>
2039 <title>Developer Information
</title>
2041 This section is for developers. Documentation authors
2042 generally do not need to know this material.
2046 Typically the application manual and possibly additional help
2047 documents will be made available to the user under the
2048 <guimenu>Help
</guimenu> menu at the top right of the
2049 application. To do this, you must first write a
2050 <filename>topic.dat
</filename> file. The format for this file is:
2052 One line for each 'topic'.
2054 Two columns, as defined by perl -e 'split(/\s+/,$aline,
2)'
2056 First column is the HTML file (and optional section) for the topic,
2057 relative to the app's help file dir.
2059 Second column is the user-visible topic name.
2061 For example,
<application>Gnumeric
</application>'s
2062 <filename>topic.dat
</filename> file is:
2064 gnumeric.html Gnumeric manual
2065 function-reference.html Gnumeric function reference
2067 When the application is installed, the
2068 <filename>topic.dat
</filename> file should be placed in the
2070 class=
"directory">$prefix/share/gnome/help/
<replaceable>appname
</replaceable>/C/
</filename> directory
2071 where
<replaceable>appname
</replaceable> is replaced by the
2072 application's name. The application documentation (converted
2073 from SGML into HTML with
<command>db2html
</command>) should be
2074 placed in this directory too.
2078 If the help files are not present in the correct directory, the
2079 menu items will NOT appear when the program is run.
2083 The
<filename>topic.dat
</filename> file is used by the GNOME
2084 menu building code to generate the
<guimenu>Help
</guimenu>
2085 menu. When you define your menu:
2087 GnomeUIInfo helpmenu[] = {
2089 N_(
"About"), N_(
"Info about this program"),
2090 about_cb, NULL, NULL,
2091 GNOME_APP_PIXMAP_STOCK, GNOME_STOCK_MENU_ABOUT,
2093 GNOMEUIINFO_SEPARATOR,
2094 GNOMEUIINFO_HELP(
"<emphasis>appname</emphasis>"),
2098 the line specifying
<varname>GNOMEUIINFO_HELP
</varname> causes
2099 GNOME to create a menu entry which is tied to the documentation
2100 in the directory mentioned above. Also, all the topics in the
2101 <filename>topic.dat
</filename> file will get menu entries in the
2102 <guimenu>Help
</guimenu> menu. When the user selects any of these
2103 topics from the
<guimenu>Help
</guimenu> menu, a help browser
2104 will be started with the associated HTML documentation.
2109 <!-- ################# Application Help Buttons ############### -->
2111 <sect1 id=
"applicationhelpbuttons">
2112 <title>Application Help Buttons
</title>
2115 <title>Developer Information
</title>
2117 This section is for developers. Documentation authors
2118 generally do not need to know this material.
2122 Most GNOME applications will have
<guibutton>Help
</guibutton>
2123 buttons. These are most often seen in Preference windows. (All
2124 Preference windows should have
<guibutton>Help
</guibutton>
2125 buttons.) Most
<guibutton>Help
</guibutton> buttons will connect
2126 to the application manual, although some may connect to special
2127 documents. Because the
<guibutton>Help
</guibutton> buttons do
2128 not generally have their own special documentation, the
2129 documentation author(s) do not need to do very much. However,
2130 the application author must be careful to guarantee that the
2131 application correctly opens the help documentation when the
2132 <guibutton>Help
</guibutton> buttons are pressed.
2135 To make the Help buttons call the correct document in the GNOME Help
2136 Browser the developer should add code based on the following example:
2140 tmp = gnome_help_file_find_file (
"module",
"page.html");
2142 gnome_help_goto(
0, tmp);
2149 The example above is in the C language, please refer to other
2150 documentation or forums for other GNOME language bindings.
2155 <!-- ################# Packaging Applet Documentation ############### -->
2157 <sect1 id=
"packagingappletdocs">
2158 <title>Packaging Applet Documentation
</title>
2159 <sect2 id=
"appletfiles">
2160 <title>Applet Documentation Files
</title>
2162 In GNOME
2.0 each applet will have its own documentation
2163 installed separately, and the GNOME
2.0 help
2164 browser (
<application>Nautilus
</application>) will dynamically
2165 merge the applet documents into a single virtual book
2166 called
<citetitle>GNOME Applets
</citetitle>. During the
2167 transitionary stage between GNOME
1.0 and GNOME
2.0, each
2168 applet in the gnome-applets package has its own manual(stored
2169 with the applet in CVS), but they are merged together manually
2170 to create the
<citetitle>GNOME Applets
</citetitle> book before
2172 <email>hobbit@aloss.ukuu.org.uk
</email> is the maintainer of
2173 this document. Applet documentation should be sent to Telsa
2174 (or placed in CVS) who will make sure they are correctly
2175 packaged with the applets. The applet author should be
2176 contacted to modify the menu items and help buttons to bind to
2177 the applet documentation if necessary.
2180 Images which are part of the applet documentation should be in
2181 PNG format and should reside in the same directory as the SGML
2182 document file in CVS(gnome-applets/APPLETNAME/help/C).
2185 Applets which are not part of the gnome-applets package must
2186 package their documentation with the particular applet
2187 package. They should use the same applet template as other
2188 applets. However, the
<sgmltag><xref
></sgmltag> links to
2189 the introductory chapter of the
<citetitle>GNOME
2190 Applets
</citetitle> book must be removed (as the
1.x
2191 <application>GNOME Help Browser
</application> does not allow
2192 you to create links between separate documents) and replaced
2193 with suitable text. Note that since this document is not part
2194 of the
<citetitle>GNOME Applets
</citetitle> book, you must
2195 remember to add
<sgmltag><legalnotice
></sgmltag> and
2196 <sgmltag><copyright
></sgmltag> sections.
2200 <sect2 id=
"appletmenu">
2201 <title>Adding Documentation to an Applet Menu
</title>
2203 <title>Developer Information
</title>
2205 This section is for developers. Documentation authors
2206 generally do not need to know this material.
2210 Applets should have
<guimenu>About
</guimenu> and
2211 <guimenu>Manual
</guimenu> menu items, typically as the first
2212 and second top-most items in the menu respectively. This
2213 section describes how the developer creates these menu items
2214 and links them to the documentation.
2217 To add an applet's manual to its applet menu, use:
2219 /* add an item to the applet menu */
2220 applet_widget_register_callback(APPLET_WIDGET(applet),
"manual",
2221 _(
"Manual"),
&open_manual, NULL);
2223 Here the second argument is an arbitrary name for the
2224 callback, the third argument is the label which will appear
2225 when the user right clicks on the applet, and the fourth
2226 argument is the callback function.
2229 You will need to write a simple callback function to open the
2230 help browser to the appropriate document. This is done using
2231 the
<function>gnome_help_file_find_file
</function> function,
2232 as described in
<xref linkend=
"applicationhelpbuttons" />.
2235 You will also want to add an
<guimenu>About
</guimenu> menu
2236 item to the applet's menu. This is a
2237 stock menu item and is done:
2239 applet_widget_register_stock_callback (APPLET_WIDGET(applet),
"about",
2240 GNOME_STOCK_MENU_ABOUT, _(
"About"),
&my_applet_cb_about,
2245 More information can be found at
<ulink type=
"http"
2246 url=
"http://developer.gnome.org/doc/tutorials/applet/index.html">Writing
2247 GNOME panel applets using the GTK+/GTK-- widget set
</ulink>.
2253 <!-- ################# Writing Context Sensitive Help ###############
2256 <sect1 id=
"writingcontextsensitivehelp">
2257 <title>Writing Context Sensitive Help (coming in GNOME-
2.0)
</title>
2259 Context sensitive help, also known as
"pop-up" help, will allow
2260 a user to obtain help information about specific buttons or
2261 parts of an application.
2264 Context sensitive help is still under development and not all
2265 the details are available at this time. However, the basics can
2266 be shown here so that you can understand how the system will
2270 The Context Sensitive Help system is designed to allow the
2271 developer to give an id to a particular portion of the User
2272 Interface, for example, a button. Once the interface is complete
2273 a Perl script can then be run against the interface code to
2274 create a
"map" file. This map file allows the developer or
2275 writer to associate particular paragraph sections from an XML
2276 document to the interface items.
2279 The XML used for the document is a small XML DTD that is being
2280 developed to use the same tags (albeit, much fewer) as DocBook
2281 so that writers do not have to re-learn a new DTD.
2284 Once the document is written and map file is complete, when the
2285 user launches context sensitive help on the interface (either by
2286 pressing a button and then clicking on the interface item they
2287 want information on, or by right mouse clicking on the interface
2288 item and selecting a pop-up menu item like
"What's This") a
2289 small transient window will appear with brief but detailed
2290 information on the interface item.
2294 <!-- ################# Referring to Other GNOME Documentation
2297 <sect1 id=
"referring">
2298 <title>Referring to Other GNOME Documentation (coming in
2301 In the GNOME
2.0 Help System, you will be able to create links
2302 from one document to another. The exact mechanism for doing
2303 this is in development.
2308 <!-- ################# Basics of Documentation Style ############### -->
2311 <title>Basics of Documentation Style
</title>
2313 Most people have never enjoyed reading a software manual, and
2314 they probably never will. Many times, they'll read the
2315 documentation only when they run into problems, and they'll be
2316 frustrated and upset before they even read a word. On the
2317 other hand, some readers will read the manual all the way
2318 through, or at least look at the introduction before they
2319 start. Your document might serve as a reference for an expert
2320 or a guide to a beginner, and it must have enough depth to
2321 satisfy the first without overwhelming the second. Ideally, it
2322 will serve beginners as they
<emphasis>become
</emphasis>
2323 experts. Remember, your goal is to produce
<emphasis>complete,
2324 intuitive and clear
</emphasis> documentation.
2327 In order to write useful documentation, you'll have to know who
2328 your audience is likely to be. Then, you can look for the
2329 problems they're likely to run into, and solve them. It will
2330 also help if you focus on the tasks users will perform, and
2331 group features accordingly, rather than simply describing
2335 <!-- *********** Basics of Documentation Style: planning -->
2337 <sect2 id=
"styleplanning">
2338 <title>Planning
</title>
2340 Begin documenting by learning how to use the application and
2341 reading over any existing documentation. Pay attention to
2342 places where your document will differ from the template. It
2343 may help to develop a document skeleton: a valid XML or SGML
2344 document that has little or no content. For very large
2345 applications, you will need to make significant departures
2346 from the templates, since you'll be using the
2347 <sgmltag><book
></sgmltag> tag instead of
2348 <sgmltag><chapter
></sgmltag> or
2349 <sgmltag><article
></sgmltag>.
2354 <!-- ####### Basics of Documentation Style | Balance ####### -->
2355 <sect2 id=
"balance">
2356 <title>Achieving a Balanced Style
</title>
2359 Just as you need to juggle expert and novice readers,
2360 you'll have to juggle a number of other extremes as you write:
2364 Documents should be complete, yet concise. You should
2365 describe every feature, but you'll have decide how much
2366 detail is really necessary. It's not, for example,
2367 necessary to describe every button and form field in a
2368 dialog box, but you should make sure that your readers
2369 know how to bring up the dialog and what it does. If
2370 you spend fewer words on the obvious, you can spend more
2371 time clarifying the ambiguous labels and explaining
2372 items that are more complex.
2377 Be engaging and friendly, yet professional. Games
2378 documents may be less formal than productivity
2379 application documents (people don't
2380 <emphasis>use
</emphasis> games, they
2381 <emphasis>play
</emphasis> them), but all of them should
2382 maintain a standard of style which holds the reader's
2383 interest without resorting to jokes and untranslatable
2390 Examples, tips, notes, and screenshots are useful to
2391 break up long stretches of text, but too many can get in
2392 the way, and make your documents too choppy to read.
2393 It's good to provide a screenshot of any dialog windows
2394 a user might run into, but if a dialog box has several
2395 tabs, it's not usually necessary to have one for each.
2401 The GDP strives to have all of its documentation conform
2402 to certain standards of style and content, but every
2403 document (and every writer) is different. You will need
2404 to use your judgement, and write documents to fit with
2405 the rest of the project, without compromising the
2406 individual needs of your subject, or your own
2407 individuality as a writer.
2416 <!-- ####### Basics of Documentation Style | Structure ####### -->
2418 <sect2 id=
"stylestructure">
2419 <title>Structure
</title>
2421 In general, you won't have to worry too much about structure,
2422 because the templates provide you with an excellent example.
2423 As a general rule, try to follow that structural example.
2424 That means using links, hierarchical nesting, and, if
2425 necessary, a glossary or index. You probably won't need to
2426 use every available structural tag, but take advantage of
2427 what DocBook provides you.
2430 As to linking, there's some disagreement about whether to use
2431 <sgmltag><xref
></sgmltag> <sgmltag><link
></sgmltag>
2432 when you make links within your documents. You'll have to
2433 decide, based on the different ways that they are presented
2434 in output, which is more appropriate given the context.
2435 Regardless of which you use, you should not forget to use
2436 them. Help your readers find information that relevant to
2440 The table of contents will be generated automatically, but
2441 you will probably have to develop your own index if you wish
2442 to have one. The Nautilus Help Browser will have new, and
2443 currently unknown, indexing capabilities, so index style and
2444 structure are still under discussion. The GNOME User's Guide
2445 will contain a glossary in its next versions; unless you're
2446 writing a
<sgmltag><book
></sgmltag>, it will probably be best to
2447 contribute to that rather than developing your own.
2450 <!-- ####### Basics of Documentation Style | Grammar & Spelling ####### -->
2452 <sect2 id=
"stylegrammar">
2453 <title>Grammar and Spelling
</title>
2455 Nobody expects you to be perfect; they just expect the
2456 documentation for their software to be error-free. That means
2457 that, in the same way that developers look for bugs and accept
2458 bug reports, writers must check for errors in their documents.
2459 Poor grammar, bad spelling, and gross technical errors in
2460 draft documents are fine. However, if those problems show up
2461 in a
"real" release, they can count against the credibility of
2462 GNOME and Linux. They'll also make you look bad.
2465 There is no substitute for a human proofreader; use a
2466 spell-check program, then read it over yourself, and then find
2467 someone else to help you. Other GDP members are, of course,
2468 willing and able to help you, but non-writers are often at
2472 Proofreading documents is both a also a good way to
2473 familiarize yourself with documentation, and it certainly
2474 makes you valuable to the GDP. Help other writers proof their
2475 documents, and they will help you with yours.
2480 <!-- ################# Teamwork ############### -->
2482 <sect1 id=
"teamwork">
2483 <title>Teamwork
</title> <!-- ####### Teamwork | Working With The
2484 GDP Team ####### -->
2486 <sect2 id=
"teamworkgdp">
2487 <title>Working With The GDP Team
</title>
2489 The GDP team is a valuable resource for any documentation
2490 author. GDP members can answer most questions documentation
2491 authors have during the course of their work. It is also
2492 important to make sure you are not duplicating work of other
2493 GDP members by visiting the
<citetitle>GDP Documentation
2494 Status Table
</citetitle> (
<ulink
2495 url=
"http://www.gnome.org/gdp/doctable/"
2496 type=
"http">http://www.gnome.org/gdp/doctable/
</ulink>) and
2497 assigning a documentation item to yourself. This table also
2498 provides a forum for making suggestions and announcements for
2499 each documentation item. The best way to get in touch with
2500 GDP members is on the #docs IRC channel at irc.gnome.org or
2501 else by emailing the
<ulink type=
"http"
2502 url=
"http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
2503 <citetitle>gnome-doc-list mailing list
</citetitle></ulink>.
2506 After an author has finished a document (or even a draft
2507 version of the document), it is a good idea to ask a member of
2508 the GDP team to read the document, checking it for grammar,
2509 proper DocBook markup, and clarity. One may typically find
2510 another author to do this by either asking on the #docs IRC
2511 channel at irc.gnome.org or by emailing the
<ulink type=
"http"
2512 url=
"http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
2513 <citetitle>gnome-doc-list mailing list
</citetitle></ulink>.
2517 <!-- ####### Teamwork | Working With Developers ####### -->
2519 <sect2 id=
"teamworkdevelopers">
2520 <title>Working With Developers
</title>
2522 Writing documentation typically involves a certain amount of
2523 interaction with the developers of GNOME or the application
2524 which is being documented. Often a document author will need
2525 to ask the developer technical questions during the course of
2526 writing a document. After the document is finished, it is good
2527 idea to ask the developer to read the document to make sure it
2528 is technically correct. The documentation author should also
2529 make sure that the application author correctly binds and
2530 packages the documentation with the application.
2534 <!-- ####### Teamwork | Working With Users #######
2536 <sect2 id="teamworkusers">
2537 <title>Working With Users</title>
2539 Some document authors may wish to get feedback on their
2540 documents directly from users. This may be done by ...
2545 <!-- ################# Finishing a Document ############### -->
2547 <sect1 id=
"finishing">
2548 <title>Finishing A Document
</title>
2550 <!-- ####### Finishing a Document | Editting the Document ####### -->
2552 <sect2 id=
"editting">
2553 <title>Editing The Document
</title>
2555 When the document is finished, the document should be edited
2556 by another member of the GDP for spelling, clarity, and
2557 DocBook markup. It should also be read by an application
2558 author to make sure the document is technically accurate.
2562 <!-- ####### Finishing a Document | Submitting the Document ####### -->
2564 <sect2 id=
"submitting">
2565 <title>Submitting The Document
</title>
2567 After the document has been edited and checked for technical
2568 accuracy, it is ready to be combined with the application or
2569 documentation package. This is typically done by passing the
2570 document to the application or package developer. In some
2571 cases, the documents can be committed directly into CVS,
2572 however this should only be done after obtaining permission to
2573 make CVS commits from the developer. Note that in many cases,
2574 the application may need to be modified to correctly link to
2575 the documentation. The packaging system (tarballs and binary
2576 packages) may also need to be modified to include the
2577 documentation in the package. Generally, this should be done
2581 The final step is to email the GNOME Translation Team at
2582 <email>gnome-i18n@nuclecu.unam.mx
</email> to notify them that
2583 there is a new document for them to translate.
2588 <!-- ################# Resources ############### -->
2590 <sect1 id=
"resources">
2591 <title>Resources
</title>
2592 <!-- ####### Resources | Resources on the Web ####### -->
2594 <sect2 id=
"resourcesweb">
2595 <title>Resources On The Web
</title> <para> The
<ulink
2596 type=
"http" url=
"http://developer.gnome.org/projects/gdp/">GNOME
2597 Documentation Project Web page
</ulink> lists current GDP
2598 projects and members.
2601 The
<ulink url=
"http://www.gnome.org/gdp/doctable/"
2602 type=
"http">GDP Documentation Status Table
</ulink> tracks the
2603 status of all the various documentation components of GNOME.
2606 Norman Walsh's
<ulink url=
"http://www.docbook.org"
2607 type=
"http"> <citetitle>DocBook: The Definitive
2608 Guide
</citetitle></ulink> in an excellent book on DocBook,
2609 available both online and in print.
2613 <!-- ####### Resources | Books ####### -->
2615 <sect2 id=
"resourcesbooks">
2616 <title>Books
</title>
2618 Docbook: The Definitive Guide is available in both printed
2619 form and on the web at:
2620 <ulink url=
"http://www.docbook.org/tdg/index.html">
2621 <citetitle>Docbook: The Definitive Guide
</citetitle>
2626 <!-- ####### Resources | Mailing Lists ####### -->
2628 <sect2 id=
"mailinglists">
2629 <title>Mailing Lists
</title>
2631 The
<emphasis>gnome-docs-list
</emphasis> mailing list is the
2632 main discussion area for all contributors to the GNOME
2633 Documentation Project. You can find out how to subscribe to
2635 url=
"http://www.gnome.org/resources/mailing-lists.html"
2636 type=
"http">GNOME Mailing Lists
</ulink>. This is a rather
2637 low-volume list, so you will not be flooded with messages.
2641 <!-- ####### Resources | IRC ####### -->
2646 Internet Relay Chat (IRC) is a fast and easy way to get in
2647 touch with other GDP members. There are generally at least a
2648 few members here who can answer questions or discuss
2649 documentation issues. The IRC channel is #docs at
2655 <!-- ################# Example Docs ###############
2657 <appendix id="exampledocs">
2658 <title>Example Docs</title>
2660 ####### Example Docs | Example 1: Application Manual #######
2663 <title>Example 1: Application Manual</title>
2665 <![CDATA[ (Put sgml here.)]]> </programlisting>
2668 ####### Example Docs | Example 2: Applet Manual #######
2671 <title>Example 2: Applet Manual</title>
2673 <![CDATA[(Put sgml here.)]]> </programlisting>
2676 ##### Example Docs | Example 3: Application Context Sensitive Help ####
2679 <title>Example 3: Application Context Sensitive Help</title>
2681 <![CDATA[(Put sgml here.)]]> </programlisting>
2684 ####### Example Docs | Example 4: Complete Application: gnome-hello #######
2687 <title>Example 4: Complete Application: gnome-hello</title>
2689 <![CDATA[(Put sgml here.)]]> </programlisting>
2692 ####### Example Docs | Example 5: Tutorial #######
2695 <title>Example 5: Tutorial</title>
2697 <![CDATA[(Put sgml here.)]]> </programlisting>
2701 <!-- ################# Document Templates ############### -->
2703 <appendix id=
"templates">
2704 <title>Document Templates
</title>
2705 <!-- ####### Document Templates | Templates 1: Application Manual ####### -->
2707 <sect1 id=
"template1">
2708 <title>Template
1: Application Manual
</title>
2710 The following template should be used for all application
2711 manuals. You can always get the latest copy of this
2712 template from
<ulink type=
"http"
2713 url=
"http://developer.gnome.org/projects/gdp/templates.html">GDP
2714 Documentation Templates
</ulink>.
2718 <!DOCTYPE Article PUBLIC
"-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
2719 <!-- if not using PNG graphic, replace reference above with
2720 .....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
2722 <!ENTITY version
"1.0.53">
2723 <!-- replace version above with actual application version number-->
2724 <!-- Template Version: 1.0.1 (do not remove this line) -->
2728 <!-- This is a GNOME documentation template, designed by the GNOME
2729 Documentation Project Team. Please use it for writing GNOME
2730 documentation, making obvious changes. In particular, all the words
2731 written in UPPERCASE (with the exception of GNOME) should be
2732 replaced. As for "legalnotice", please leave the reference
2735 Remember that this is a guide, rather than a perfect model to follow
2736 slavishly. Make your manual logical and readable. And don't forget
2737 to remove these comments in your final documentation! ;-)
2740 <!-- =============Document Header ============================= -->
2742 <article id=
"index"> <!-- please do not change the id -->
2745 <title>MY-GNOME-APP
</title>
2748 <holder>ME-THE-AUTHOR
</holder>
2751 <!-- translators: uncomment this:
2755 <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
2760 <!-- do not put authorname in the header except in copyright - use
2761 section "authors" below -->
2765 Permission is granted to copy, distribute and/or modify this
2766 document under the terms of the
<citetitle>GNU Free
2767 Documentation License
</citetitle>, Version
1.1 or any later
2768 version published by the Free Software Foundation with no
2769 Invariant Sections, no Front-Cover Texts, and no Back-Cover
2770 Texts. You may obtain a copy of the
<citetitle>GNU Free
2771 Documentation License
</citetitle> from the Free Software
2772 Foundation by visiting
<ulink type=
"http"
2773 url=
"http://www.fsf.org">their Web site
</ulink> or by writing
2774 to: Free Software Foundation, Inc.,
59 Temple Place - Suite
2775 330, Boston, MA
02111-
1307, USA.
2778 Many of the names used by companies to distinguish their
2779 products and services are claimed as trademarks. Where those
2780 names appear in any GNOME documentation, and those trademarks
2781 are made aware to the members of the GNOME Documentation
2782 Project, the names have been printed in caps or initial caps.
2786 <!-- this is the version of manual, not application -->
2788 This is version
1.0 of MY-GNOME-APP manual.
2793 <!-- ============= Document Body ============================= -->
2795 <!-- ============= Introduction ============================== -->
2797 <title>Introduction
</title>
2800 <application>MY-GNOME-APP
</application> is an application which
2801 proves mathematical theorems. It has all the basic features
2802 expected from a mathematical theorem prover, as well as a number
2803 of advanced ones, such as proof by confusion. In fact, many of
2804 the proofs produced by
<application>MY-GNOME-APP
</application>
2805 are so complex that they are capable of proving almost anything
2806 with a virtually null likelihood of being disproven. It also has
2807 the very popular predecessor of proof by confusion, proof by
2808 dialog, first implemented by Plato.
2811 It also allows you to save and print theorem proofs and to add
2812 comments to the proofs it produces.
2816 To run
<application>MY-GNOME-APP
</application>, select
2818 <guisubmenu>SUBMENU
</guisubmenu>
2819 <guimenuitem>MY-GNOME-APP
</guimenuitem>
2821 from the
<guimenu>Main Menu
</guimenu>, or type
2822 <command>MYGNOMEAPP
</command> on the command line.
2826 <application>MY-GNOME-APP
</application> is included in the
2827 <filename>GNOME-PACKAGE
</filename> package, which is part of the
2828 GNOME desktop environment. This document describes version
2829 &version; of
<application>MY-GNOME-APP
</application>.
2834 <!-- ================ Usage ================================ -->
2835 <!-- This section should describe basic usage of the application. -->
2838 <title>Using MY-GNOME-APP
</title>
2840 <application>MY-GNOME-APP
</application> can be used to produce a
2841 perfect proof of
<emphasis>any
</emphasis> mathematical theorem
2842 (provided, of course, that this theorem is correct), thus
2843 providing for new users an easy-to-use graphical interface to
2844 modern mathematics. This section describes basic usage of
2845 <application>MY-GNOME-APP
</application>.
2848 <!-- ========= Basic Usage =========================== -->
2849 <sect2 id=
"mainwin">
2850 <title>Basic usage
</title>
2852 Starting
<application>MY-GNOME-APP
</application> opens the
2853 <interface>Main window
</interface>, shown in
<xref
2854 linkend=
"mainwindow-fig">. The window is at first empty.
2856 <!-- ==== Figure ==== -->
2857 <figure id=
"mainwindow-fig">
2858 <title>MY-GNOME-APP Main Window
</title>
2860 <screeninfo>MY-GNOME-APP Main Window
</screeninfo>
2861 <graphic fileref=
"SCREENSHOT" format=
"png" srccredit=
"ME">
2865 <!-- ==== End of Figure ==== -->
2869 <!-- For this app, one could put "proving" or "edit" (probably even
2870 both of them) as sect2's seperate from the main window
2871 section. Since they were both so closely involved with the main
2872 window, I decided to have them as sect3's isntead. Judgement
2875 <sect3 id=
"proving">
2876 <title>Proving a Theorem
</title>
2878 To get a proof of a theorem, select
2880 <guisubmenu>File
</guisubmenu>
2881 <guimenuitem>New
</guimenuitem>
2884 bring up the
<interface>New Proof
</interface> dialog box.
2885 Enter the statement of the theorem in the
2886 <guilabel>Theorem statement
</guilabel> field, select your
2887 desired proof type from the drop-down menu, and and press
2888 <guibutton>Prove!
</guibutton>.
2891 If
<application>MY-GNOME-APP
</application> cannot prove the
2892 theorem by the method you have chosen, or if you have not
2893 selected a proof type at all,
2894 <application>MY-GNOME-APP
</application> will attempt to
2895 choose the one that it thinks is most conclusive. In order,
2896 it will attempt to prove the theorem with the following techniques:
2900 <term>Deduction
</term>
2903 This is a proof method that is generally accepted
2904 for full credit by Logic professors.
2909 <term>Induction
</term>
2912 This logical style will also earn you full credit on
2921 This logical method is best for Philosophy classes,
2922 and will probably only merit partial credit on Logic
2923 or Mathematics homework.
2928 <term>Confusion
</term>
2931 Suitable only for political debates, battles of wits
2932 against the unarmed, and Philosophy classes focusing
2933 on the works of Kant. Use with caution.
2940 <!-- You might want to include a note, warning, or tip, e.g. -->
2943 <title>Proving Incorrect Theorms
</title>
2945 <application>MY-GNOME-APP
</application> cannot prove
2946 incorrect theorems. If the theorem you have entered is not
2947 demonstrably true, you will get a message to that effect
2948 in the main window. To disprove a theorem, ask
2949 <application>MY-GNOME-APP
</application> to prove its
2954 <sect3 id=
"editing">
2955 <title>Editing Proofs
</title>
2957 Once you have proven the theorem, it will be displayed in
2958 the
<interface>main window
</interface>. There, you can read
2959 it over, choose text styles for different portions of it,
2960 and make comments on it. This section will guide you through
2964 To alter text styles, first select the statement you wish to
2965 change by clicking on it once. You can select several
2966 statements by Then, choose the style you want to apply from
2967 the
<guisubmenu>Style
</guisubmenu> submenu of the
2968 <guimenu>Edit
</guimenu> menu.
2969 <application>MY-GNOME-APP
</application> will convert the
2973 You can also enter comments on a statement by selecting that
2974 statement, and then beginning to type. Comments will appear
2975 after the statement you have selected.
2979 <title>Altering The Proofs Themselves
</title>
2981 <application>MY-GNOME-APP
</application> does not allow you
2982 to alter a proof it has produced itself. You can, save
2983 your proof as a plain text file (using the
2984 <guimenuitem>Save as...
</guimenuitem> menu), and alter it
2985 that way. Be aware, however, that
2986 <application>MY-GNOME-APP
</application> uses its own file
2987 format for saved proofs, and cannot re-open a file unless
2988 it is in the .mga format.
2994 <!-- If there are other functions performed from the main window,
2995 they belong here. -->
2999 <!-- =========================================================
3000 Additional Sect2's should describe additional windows, such as
3001 larger dialog boxes, or functionality that differs significantly
3002 from the most immediate functions of the application. Make the
3004 ============================================================= -->
3007 <sect2 id=
"toolbar">
3008 <title>Toolbar
</title>
3010 The toolbar (shown in
<xref linkend=
"figure-usage-toolbar">)
3011 provides access to several commonly used routines.
3012 <figure id=
"figure-usage-toolbar">
3013 <title>MY-GNOME-APP Toolbar
</title>
3015 <screeninfo>MY-GNOME-APP Toolbar
</screeninfo>
3016 <graphic fileref=
"usage-toolbar.png" format=
"png"></graphic>
3024 Brings up the
<interface>New Theorem
</interface>
3033 Open an exisiting theorem you want to prove, or a
3034 completed proof you wish to print or format.
3042 Save the current theorem permanently in a
3050 <!-- ========= Menus =========================== -->
3052 <sect2 id=
"menubar">
3054 <!-- Describing the menubar ensures comprehensive feature
3055 coverage. Nest itemizedlists inside variablelists so that each
3056 menu is easily located by indexing software. Proper indentation
3057 makes it easier! -->
3059 <title>Menus
</title>
3061 The menu bar, located at the top of the
<interface>Main
3062 Window
</interface>, contains the following menus:
3066 <term><guimenu>File
</guimenu></term>
3077 <guimenuitem>Open
</guimenuitem>
3079 — This opens a file which is saved on your computer.
3086 <keycombo><keycap>Ctrl
</keycap><keycap>S
</keycap></keycombo>
3088 <guimenuitem>Save
</guimenuitem>
3090 — This saves your file.
3097 <keycombo><keycap>Ctrl
</keycap><keycap>W
</keycap></keycombo>
3099 <guimenuitem>Close
</guimenuitem>
3101 — This closes your file.
3108 <keycombo><keycap>Ctrl
</keycap><keycap>Q
</keycap></keycombo>
3110 <guimenuitem>Exit
</guimenuitem>
3112 — This quits the application.
3121 <term><guimenu>Edit
</guimenu></term>
3130 <keycombo><keycap>Ctrl
</keycap><keycap>X
</keycap></keycombo>
3132 <guimenuitem>Cut
</guimenuitem>
3134 — This removes any text or data which is selected and
3135 places it in the buffer.
3142 <keycombo><keycap>Ctrl
</keycap><keycap>C
</keycap></keycombo>
3144 <guimenuitem>Copy
</guimenuitem>
3146 — This copies any text or data which is selected into
3154 <keycombo><keycap>Ctrl
</keycap><keycap>V
</keycap></keycombo>
3156 <guimenuitem>Paste
</guimenuitem>
3158 — This pastes any text or data which is copied into
3164 <guimenuitem>COMMAND1
…</guimenuitem>
3165 — This opens the
<interface>COMMAND1
</interface>
3166 dialog, which is used to ....
3171 <guimenuitem>COMMAND2
</guimenuitem>
3182 <term><guimenu>Settings
</guimenu></term>
3189 <guimenuitem>Preferences
…</guimenuitem>
3190 — This opens the
<link
3191 linkend=
"prefs"><interface>Preferences
3192 Dialog
</interface></link>, which allows you to configure
3198 <guimenuitem>COMMAND3
</guimenuitem> —
3199 This command does something.
3208 <term><guimenu>Help
</guimenu></term>
3215 <guimenuitem>Manual
</guimenuitem> — This
3216 opens the
<application>GNOME Help
3217 Browser
</application> and displays this manual.
3223 <guimenuitem>About
</guimenuitem> — This
3224 opens the
<interface>About
</interface> dialog
3225 which shows basic information about
3226 <application>MY-GNOME-APP
</application>, such as
3227 the author's name, the application version number,
3228 and the URL for the application's Web page if one
3242 <!-- ============= Customization ============================= -->
3245 <title>Customization
</title>
3247 To change the application settings, select
3249 <guimenu>Settings
</guimenu>
3250 <guimenuitem>Preferences...
</guimenuitem>
3251 </menuchoice>. This opens the
3252 <interface>Preferences
</interface> dialog, shown in
<xref
3253 linkend=
"preferences-fig">.
3256 <figure id=
"preferences-fig">
3257 <title>Preferences Dialog
</title>
3259 <screeninfo>Preferences Dialog
</screeninfo>
3260 <graphic fileref=
"SCREENSHOT" format=
"png"
3267 The properties in the
<guilabel>PREFSTABNAME
</guilabel> tab are:
3269 <!--many people use itemizedlists in cases like this. Variablelists
3270 are more appropriate -->
3274 <term> <guilabel>Default Text Style
</guilabel></term>
3277 Select the default text style for statements in your
3278 proof. You can still change the style for individual
3279 proofs or sections of a proof at a later date.
3284 <term>(Configuration Item Label)
</term>
3287 (Description of Configuration)
3292 <term>(Configuration Item Label)
</term>
3295 (Description of Configuration)
3303 The properties in the
<guilabel>SECONDTABNAME
</guilabel> tab are:
3306 <term>(Configuration Item Label)
</term>
3309 (Description of Configuration)
3314 <term>(Configuration Item Label)
</term>
3317 (Description of Configuration)
3325 After you have made all the changes you want, click on
3326 <guibutton>OK
</guibutton> to apply the changes and close the
3327 <interface>Properties
</interface> dialog. To cancel the changes
3328 and return to previous values, click the
3329 <guibutton>Close
</guibutton> button.
3335 <!-- ============= Various Sections ============================= -->
3337 <!-- Here you should add, if necessary, several more sect1's,
3338 describing other windows (besides the main one), file formats,
3339 preferences dialogs, etc. as appropriate. Try not to make any of
3340 these sections too long. -->
3343 <!-- ============= Bugs ================================== -->
3344 <!-- This section should describe known bugs and limitations of
3345 the program if there are any - please be frank and list all
3346 problems you know of. -->
3348 <title>Known Bugs and Limitations
</title>
3350 This application has no known bugs.
3355 <!-- ============= Authors ================================ -->
3357 <sect1 id=
"authors">
3358 <title>Authors
</title>
3360 <application>MY-GNOME-APP
</application> was written by GNOME-HACKER
3361 (
<email>hacker@gnome.org
</email>). To find more information about
3362 <application>MY-GNOME-APP
</application>, please visit the
<ulink
3363 url=
"http://www.my-gnome-app.org" type=
"http">MY-GNOME-APP Web
3364 page
</ulink>. Please send all comments, suggestions, and bug
3365 reports to the
<ulink url=
"http://bugs.gnome.org" type=
"http">GNOME
3366 bug tracking database
</ulink>. (Instructions for submitting bug
3367 reports can be found
<ulink
3368 url=
"http://bugs.gnome.org/Reporting.html" type=
"http">
3369 on-line
</ulink>.) You can also use
<application>Bug Report
3370 Tool
</application> (
<command>bug-buddy
</command>), available in the
3371 <guisubmenu>Utilities
</guisubmenu> submenu of
<guimenu>Main
3372 Menu
</guimenu>, for submitting bug reports.
3376 This manual was written by ME
3377 (
<email>MYNAME@MYADDRESS
</email>). Please send all comments and
3378 suggestions regarding this manual to the
<ulink type=
"http"
3379 url=
"http://developer.gnome.org/projects/gdp">GNOME Documentation
3380 Project
</ulink> by sending an email to
3381 <email>docs@gnome.org
</email>. You can also add your comments online
3382 by using the
<ulink type=
"http"
3383 url=
"http://www.gnome.org/gdp/doctable/">GNOME Documentation Status
3387 <!-- For translations: uncomment this:
3390 Latin translation was done by ME
3391 (<email>MYNAME@MYADDRESS</email>). Please send all comments and
3392 suggestions regarding this translation to SOMEWHERE.
3400 <!-- ============= Application License ============================= -->
3402 <sect1 id=
"license">
3403 <title>License
</title>
3405 This program is free software; you can redistribute it and/or
3406 modify it under the terms of the
<citetitle>GNU General Public
3407 License
</citetitle> as published by the Free Software Foundation;
3408 either version
2 of the License, or (at your option) any later
3412 This program is distributed in the hope that it will be useful, but
3413 WITHOUT ANY WARRANTY; without even the implied warranty of
3414 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3415 <citetitle>GNU General Public License
</citetitle> for more details.
3418 A copy of the
<citetitle>GNU General Public License
</citetitle> is
3419 included as an appendix to the
<citetitle>GNOME Users
3420 Guide
</citetitle>. You may also obtain a copy of the
3421 <citetitle>GNU General Public License
</citetitle> from the Free
3422 Software Foundation by visiting
<ulink type=
"http"
3423 url=
"http://www.fsf.org">their Web site
</ulink> or by writing to
3425 Free Software Foundation, Inc.
3426 <street>59 Temple Place
</street> - Suite
330
3427 <city>Boston
</city>,
<state>MA
</state> <postcode>02111-
1307</postcode>
3428 <country>USA
</country>
3449 <!-- ####### Document Templates | Templates 2-1.x: Applet Manual ####### -->
3451 <sect1 id=
"template2-1x">
3452 <title>Template
2: Applet Manual For GNOME
1.x
</title>
3454 The following templates should be used for all applet
3455 manuals in GNOME
1.x releases. You can always get the latest
3456 copy of these templates from
<ulink type=
"http"
3457 url=
"http://developer.gnome.org/projects/gdp/templates.html">GDP
3458 Documentation Templates
</ulink>. Note that the template
3459 consists of two files; the first file calls the second as an
3460 entity. You should name the first file
3461 <filename><replaceable>appletname
</replaceable>-applet.sgml
</filename>
3462 and the second file should be named
3463 <filename><replaceable>appletname
</replaceable>.sgml
</filename>,
3465 <filename><replaceable>appletname
</replaceable></filename> is
3466 the name of the applet.
3470 <!DOCTYPE Article PUBLIC
"-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
3471 <!entity APPLETNAME.sgml SYSTEM
"applet_template_1.sgml">
3472 <!-- Template Version: 1.0.1 (do not remove this line) -->
3475 <!-- This is a GNOME documentation template, designed by the GNOME
3476 Documentation Project Team. Please use it for writing GNOME
3477 documentation, making obvious changes. In particular, all the words
3478 written in UPPERCASE (with the exception of GNOME) should be
3479 replaced. As for "legalnotice", please leave the reference
3480 unchanged,make sure to add/remove trademarks to the list as
3481 appropriate for your document.
3483 Please don't forget to remove these comments in your final documentation,
3487 <article id=
"index"> <!-- please do not change the id -->
3489 <!-- ============= Document Header ============================= -->
3491 <title>APPLETNAME Applet
</title>
3494 <holder>YOURFULLNAME
</holder>
3497 <!-- translators: uncomment this:
3501 <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
3506 <!-- do not put authorname in the header except in copyright - use
3507 section "authors" below -->
3511 Permission is granted to copy, distribute and/or modify this
3512 document under the terms of the
<citetitle>GNU Free Documentation
3513 License
</citetitle>, Version
1.1 or any later version published
3514 by the Free Software Foundation with no Invariant Sections, no
3515 Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
3516 of the
<citetitle>GNU Free Documentation License
</citetitle> from
3517 the Free Software Foundation by visiting
<ulink type=
"http"
3518 url=
"http://www.fsf.org">their Web site
</ulink> or by writing to:
3519 Free Software Foundation, Inc.,
59 Temple Place - Suite
330,
3520 Boston, MA
02111-
1307, USA.
3523 Many of the names used by companies to distinguish their products and
3524 services are claimed as trademarks. Where those names appear in any
3525 GNOME documentation, and those trademarks are made aware to the members
3526 of the GNOME Documentation Project, the names have been printed in caps
3532 This is version XXX of the APPLETNAME applet manual.
3536 <!-- ============= Document Body ============================= -->
3549 <!-- Template Version: 1.0.1 (do not remove this line) -->
3552 <title>APPLET Applet
</title>
3555 <application>APPLET
</application> applet, shown in
<xref
3556 linkend=
"APPLETapplet-fig">, allows you to
…. To add this
3557 applet to a
<interface>Panel
</interface>,
3558 right-click on the
<interface>Panel
</interface> and choose
3560 <guimenu>Panel
</guimenu>
3561 <guisubmenu>Add to panel
</guisubmenu>
3562 <guisubmenu>Applet
</guisubmenu>
3563 <guisubmenu>SECTION
</guisubmenu>
3564 <guimenuitem>APPLET
</guimenuitem>
3568 <figure id=
"APPLETapplet-fig">
3569 <title>APPLET Applet
</title>
3571 <screeninfo>APPLET Applet
</screeninfo>
3572 <graphic format=
"png" fileref=
"APPLET_applet"
3573 srccredit=
"YOURNAME">
3578 <!-- ============= Usage ================================ -->
3579 <sect2 id=
"APPLET-usage">
3580 <title>Usage
</title>
3582 (Place a short description of how to use the applet here.)
3586 Right-clicking on the applet brings up a menu containing the
3592 <guimenuitem>Properties
…</guimenuitem> —
3593 opens the
<link linkend=
"APPLET-prefs">
3594 <guilabel>Properties
</guilabel></link> dialog.
3600 <guimenuitem>Help
</guimenuitem> —
3601 displays this document.
3607 <guimenuitem>About
…</guimenuitem> —
3608 shows basic information about
<application>APPLET
3609 Applet
</application>, including the applet's version and the
3619 <!-- ============= Customization ============================= -->
3620 <sect2 id=
"APPLET-prefs">
3621 <title>Customization
</title>
3623 You can customize
<application>APPLET
</application>
3624 applet by right-clicking on it and choosing
3625 <guimenuitem>Properties
…</guimenuitem>. This will open the
3626 <interface>Properties
</interface> dialog(shown in
<xref
3627 linkend=
"APPLET-settings-fig">), which allows you to
3628 change various settings.
3631 <figure id=
"APPLET-settings-fig">
3632 <title>Properties dialog
</title>
3634 <screeninfo>Properties dialog
</screeninfo>
3635 <graphic format=
"png" fileref=
"APPLET_settings"
3636 srccredit=
"YOURNAME">
3647 (Configuration Item Label)
— If this button is
3648 checked
…(description)
3654 (Configuration Item Label)
— Selecting this
3655 button
…(description)
3661 (Configuration Item Label)
— Enter the name of
3662 …(description)
3669 After you have made all the changes you want, click on
3670 <guibutton>OK
</guibutton> to apply the changes and close the
3671 <interface>Properties
</interface> dialog. To cancel the changes
3672 and return to previous values, click the
3673 <guibutton>Close
</guibutton> button.
3678 <!-- ============= Bugs ================================== -->
3679 <!-- This section should describe known bugs and limitations of
3680 the program if there are any - please be frank and list all
3681 problems you know of -->
3683 <title>Known Bugs and Limitations
</title>
3685 This applet has no known bugs.
3690 <!-- ============= Authors ================================ -->
3692 <sect2 id=
"authors">
3693 <title>Authors
</title>
3695 <application>APPLET
</application> was written by GNOME-HACKER
3696 (
<email>hacker@gnome.org
</email>). Please send all comments,
3697 suggestions, and bug
3698 reports to the
<ulink url=
"http://bugs.gnome.org" type=
"http">GNOME
3699 bug tracking database
</ulink>. (Instructions for submitting bug
3700 reports can be found
<ulink
3701 url=
"http://bugs.gnome.org/Reporting.html" type=
"http">
3702 on-line
</ulink>. You can also use
<application>Bug Report
3703 Tool
</application> (
<command>bug-buddy
</command>), available in the
3704 <guisubmenu>Utilities
</guisubmenu> submenu of
<guimenu>Main
3705 Menu
</guimenu>, for submitting bug reports.
3709 This manual was written by ME
3710 (
<email>MYNAME@MYADDRESS
</email>). Please send all comments and
3711 suggestions regarding this manual to the
<ulink type=
"http"
3712 url=
"http://developer.gnome.org/projects/gdp">GNOME Documentation
3713 Project
</ulink> by sending an email to
3714 <email>docs@gnome.org
</email>. You can also submit comments online
3715 by using the
<ulink type=
"http"
3716 url=
"http://www.gnome.org/gdp/doctable/">GNOME Documentation
3717 Status Table
</ulink>.
3720 <!-- For translations: uncomment this:
3723 Latin translation was done by ME
3724 (<email>MYNAME@MYADDRESS</email>). Please send all comments and
3725 suggestions regarding this translation to SOMEWHERE.
3733 <!-- ============= Application License ============================= -->
3735 <sect2 id=
"license">
3736 <title>License
</title>
3738 This program is free software; you can redistribute it and/or
3739 modify it under the terms of the
<citetitle>GNU General Public
3740 License
</citetitle> as published by the Free Software Foundation;
3741 either version
2 of the License, or (at your option) any later
3745 This program is distributed in the hope that it will be useful, but
3746 WITHOUT ANY WARRANTY; without even the implied warranty of
3747 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3748 <citetitle>GNU General Public License
</citetitle> for more details.
3751 A copy of the
<citetitle>GNU General Public License
</citetitle> is
3752 included as an appendix to the
<citetitle>GNOME Users
3753 Guide
</citetitle>. You may also obtain a copy of the
3754 <citetitle>GNU General Public License
</citetitle> from the Free
3755 Software Foundation by visiting
<ulink type=
"http"
3756 url=
"http://www.fsf.org">their Web site
</ulink> or by writing to
3758 Free Software Foundation, Inc.
3759 <street>59 Temple Place
</street> - Suite
330
3760 <city>Boston
</city>,
<state>MA
</state> <postcode>02111-
1307</postcode>
3761 <country>USA
</country>
3779 <!-- ####### Document Templates | Templates 2-2.x: Applet Manual ####### -->
3781 <sect1 id=
"template2-2x">
3782 <title>Template
2: Applet Manual For GNOME
2.x
</title>
3784 The following templates should be used for all applet
3785 manuals in GNOME
2.x releases. You can always get the latest
3786 copy of these templates from
<ulink type=
"http"
3787 url=
"http://developer.gnome.org/projects/gdp/templates.html">GDP
3788 Documentation Templates
</ulink>.
3791 Note that this template consists of two files. The first file
3792 is an introductory chapter. You should not modify this
3793 chapter. The second file is the actual applet document, which
3794 you should modify to describe the applet you are documenting.
3795 You can name the first file whatever you like, such as
3796 <filename>gnome-applets.sgml
</filename>. Name the second file
3797 according to the applet's name:
3798 <filename><replaceable>appletname
</replaceable>-applet.sgml
</filename>.
3799 Make sure you update the entity
3800 at the top of the shell document to reflect the new name of
3801 the applet document.
3806 <!DOCTYPE book PUBLIC
"-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
3807 <!ENTITY TEMPLATE-APPLET SYSTEM
"gnome-applet-template.sgml.part">
3811 <book id=
"gnome-applets">
3814 <title>GNOME Applets
</title>
3816 <author><firstname>Telsa
</firstname><surname>Gwynne
</surname></author>
3817 <author><firstname>John
</firstname><surname>Fleck
</surname></author>
3818 <author><firstname>David
</firstname><surname>Mason
</surname>
3819 <affiliation><orgname>Red Hat, Inc.
</orgname></affiliation>
3821 <author><firstname>Dan
</firstname><surname>Mueth
</surname></author>
3822 <author><firstname>Alexander
</firstname><surname>Kirillov
</surname></author>
3824 <edition>GNOME Applets version
0.1 for GNOME
1.1.5</edition>
3825 <pubdate>2000</pubdate>
3828 <holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and
3829 Alexander Kirillov
</holder>
3833 Permission is granted to make and distribute verbatim copies of this
3834 manual provided the copyright notice and this permission notice are
3835 preserved on all copies.
3838 Permission is granted to copy and distribute modified versions of
3839 this manual under the conditions for verbatim copying, provided that
3840 the entire resulting derived work is distributed under the terms of a
3841 permission notice identical to this one.
3844 Permission is granted to copy and distribute translations of this
3845 manual into another language, under the above conditions for modified
3846 versions, except that this permission notice may be stated in a
3847 translation approved by the Free Software Foundation.
3850 Many of the names used by companies to distinguish their products and
3851 services are claimed as trademarks. Where those names appear in any
3852 GNOME documentation, and those trademarks are made aware to the members
3853 of the GNOME Documentation Project, the names have been printed in caps
3859 <!-- #### Introduction ###### -->
3860 <chapter id=
"applets-intro">
3861 <title>Introduction
</title>
3863 <!-- #### Intro | What Are Applets? ###### -->
3864 <sect1 id=
"applets-what-are">
3865 <title>What Are Applets?
</title>
3867 Applets are one of the most popular and useful objects you can add
3868 to your
<interface>Panel
</interface> to customize your desktop.
3869 An applet is a small application which runs inside a small area of
3870 your
<interface>Panel
</interface>. Applets have been written for
3871 a wide range of purposes. Some are very powerful interactive
3872 tools, such as the
<application>Tasklist
</application> Applet
3873 which allows you to easily
3874 control all of your main applications. Others are simple system
3875 monitors, displaying information such as the amount of power left
3876 in the battery on your laptop (see
<application>Battery Charge
3877 Monitor
</application>) or weather
3878 information(see
<application>GNOME Weather
</application>). Some
3879 are simply for amusement(see
<application>Fish
</application>).
3883 Applets are similar to swallowed applications in that both of them
3884 reside within the
<interface>Panel
</interface>. However,
3885 swallowed applications are generally applications which were
3886 not designed to run within the
<interface>Panel
</interface>.
3887 Typically one will swallow an application which already exists in
3888 the main
<interface>desktop
</interface> area, putting it into your
3889 <interface>Panel
</interface>. The application will continue to
3890 run in the
<interface>Panel
</interface> until you end the
3891 application or unswallow it, placing it back onto the main part of
3892 your desktop when you need to.
3896 <figure id=
"example-applets-fig">
3897 <title>Example Applets
</title>
3899 <screeninfo>Example Applets
</screeninfo>
3900 <graphic fileref=
"example_applets" format=
"png"
3905 Several example applets are shown in
<xref
3906 linkend=
"example-applets-fig">. From left to right, they are: (
1)
3907 <application>Mixer Applet
</application>, which allows you to turn
3908 on/off sound and control its volume by clicking on the applet. (
2)
3909 <application>Sound Monitor
</application> Applet, which displays
3910 the current volume of sound being played and allows you to control
3911 various sound features. (
3)
<application>GTCD
</application>
3912 Applet, a CD player which has all its controls
3913 available in the applet and displays the track and time. (
4)
3914 <application>Drive Mount
</application> Applet, used to mount and
3915 unmount drives with a single click of the mouse. (
5)
3916 <application>Desk Guide
</application> which allows you to view
3917 and control multiple virtual screens. (
6)
3918 <application>Tasklist
</application> Applet which allows you to
3919 control your various windows and applications.
3922 There are many other applets to choose from. The rest of this
3923 chapter will explain the basic information to get you started
3924 adding, moving, and removing applets from your
3925 <interface>Panels
</interface> and using them. The following
3926 chapters go through each of the standard GNOME applets describing
3927 them in detail. There are also additional applets which can be
3928 downloaded off the Web. See
<ulink type=
"http"
3929 url=
"http://www.gnome.org/applist/list-martin.phtml">The GNOME
3930 Software Map
</ulink> for lists of additional GNOME applications
3934 As you read through the the rest of this chapter, you should try
3935 adding and removing applets from your
<interface>Panel
</interface> and
3936 experiment with them freely.
3940 <!-- #### Intro | Adding, Moving, and Removing Applets ###### -->
3941 <sect1 id=
"applet-add-move-replace">
3942 <title>Adding, Moving, and Removing Applets
</title>
3944 <sect2 id=
"adding-applets">
3945 <title>Adding Applets to a Panel
</title>
3947 To add an applet to a
<interface>Panel
</interface>, right-click
3948 on the
<interface>Panel
</interface> and select
3949 <menuchoice><guimenu>Panel
</guimenu><guisubmenu>Add to panel
</guisubmenu>
3950 <guisubmenu>Applet
</guisubmenu></menuchoice>. This will show you
3951 the menu of all the applets on your system, divided into
3952 categories. Choosing any applet from this menu will add it to the
3953 <interface>Panel
</interface>.
3957 <sect2 id=
"moving-applets">
3958 <title>Moving Applets In or Between Panels
</title>
3960 It is easy to move applets in a
<interface>Panel
</interface> or
3961 between two
<interface>Panels
</interface>. If you have a
3962 three-button mouse, just move the mouse over the applet, depress
3963 the middle mouse button and drag the applet to its new location,
3964 releasing the middle mouse button when you are finished. Note
3965 that you can drag applets within a
<interface>Panel
</interface>
3966 or between two
<interface>Panels
</interface> this way. If you
3967 don't have a three-button mouse, just
3968 right-click on the applet and choose
3969 <guimenuitem>Move
</guimenuitem>. The cursor will turn into a
3970 cross and the applet will move with your mouse until you press
3971 any mouse button to indicate you are finished moving it.
3972 If, in the course of this movement, it hits
3973 other objects, the behavior depends on the global preferences
3974 you have set for your
<interface>Panels
</interface> in the
3975 <application>GNOME Control Center
</application>: the applet you are
3976 moving can switch places with other objects,
"push" all objects
3977 it meets, or
"jump" over all other objects without disturbing
3978 them. You can also override the default behavior by holding
3979 <keycap>Shift
</keycap> button (for
"push" mode),
3980 <keycap>Ctrl
</keycap> (for
"switched" mode), or
3981 <keycap>Alt
</keycap> (for
"free" mode, i.e. jumping other other
3982 objects without disturbing them) button while dragging.
3985 To change the global Panel preferences, right-click on any applet
3986 or
<interface>Panel
</interface> and select
3988 <guimenu>Panel
</guimenu>
3989 <guimenuitem>Global Preferences...
</guimenuitem>
3991 The
<guilabel>Default movement mode
</guilabel> is set under the
3992 <guilabel>Applets
</guilabel> tab.
3996 <sect2 id=
"removing-applets">
3997 <title>Removing Applets from a Panel
</title>
3999 To remove an applet from a
<interface>Panel
</interface>,
4000 right-click on the applet and select
<guimenuitem>Remove from
4001 panel...
</guimenuitem>.
4007 <!-- #### Intro | The Right-Click Pop-Up Menu ###### -->
4008 <sect1 id=
"right-click-pop-up-menu">
4009 <title>The Right-Click Pop-Up Menu
</title>
4011 Clicking the right mouse button on any applet brings up
4012 a
<guimenu>pop-up menu
</guimenu>. This
4013 menu always has certain standard menu items in it and
4014 often has additional items which vary depending on the particular
4017 <sect2 id=
"standard-right-click-items">
4018 <title>Standard Pop-Up Items
</title>
4020 All applets should have the following items in their right-click
4021 <guimenu>pop-up menu
</guimenu>:
4024 <term>Remove from panel
</term>
4027 The
<guimenuitem>Remove from panel
</guimenuitem> menu item
4028 removes the applet from the
<interface>Panel
</interface>.
4037 After selecting
<guimenuitem>Move
</guimenuitem>, your mouse
4038 pointer will change appearance (typically to a cross with
4039 arrows in each direction). As you move your mouse, the applet
4040 will move with it. When you have finished moving the applet,
4041 click any mouse button and the applet will anchor in its
4042 current position. Note that applets can be moved between two
4043 <interface>Panels
</interface> this way.
4052 The
<guisubmenu>Panel
</guisubmenu> submenu contains various
4053 items and submenus for adding and removing
4054 <interface>Panels
</interface> and applets and for changing
4064 The
<guimenuitem>About...
</guimenuitem> menu item brings up a
4065 dialogue box containing various information about the applet,
4066 typically including the applet's name, version, author,
4067 copyright, license and desciption.
4076 The
<guimenuitem>Help
</guimenuitem> menu item brings up the help
4077 manual for the applet.
4085 <sect2 id=
"applet-properties-dialog">
4086 <title>The Applet Properties Dialog
</title>
4088 Many applets have customizable properties. These applets will
4089 have a
<guimenuitem>Properties...
</guimenuitem> menu item in their
4090 right-click
<guimenu>pop-up menu
</guimenu> which brings up the
4091 <interface>Properties
</interface> dialog where you can alter the
4092 appearance or behaviour of the applet.
4093 <figure id=
"example-props-dialog-fig">
4094 <title>An Example Applet Properties Dialog
</title>
4096 <screeninfo>An Example Applets Properties Dialog
</screeninfo>
4097 <graphic fileref=
"applet_props_dialog" format=
"png"
4102 All
<interface>Properties
</interface> dialogs have the following
4103 buttons at the bottom of the dialog:
4107 <guibutton>OK
</guibutton> —
4108 Pressing
<guibutton>OK
</guibutton> will activate any changes
4109 in the properties you have made and close the
4110 <interface>Properties
</interface> dialog.
4115 <guibutton>Apply
</guibutton> —
4116 Pressing
<guibutton>Apply
</guibutton> at any time will
4117 make your changes active without closing the
4118 <interface>Properties
</interface> dialog. This is helpful if
4119 you would like to test the effects of the changes you have
4120 made but may want to continue changing the properties.
4125 <guibutton>Close
</guibutton> —
4126 Pressing
<guibutton>Close
</guibutton> will close the
4127 <interface>Properties
</interface> dialog. Only changes in the
4128 configuration which were previously applied with the
4129 <guibutton>Apply
</guibutton> button will persist. Other
4130 changes will not be made active.
4135 <guibutton>Help
</guibutton> —
4136 Pressing
<guibutton>Help
</guibutton> brings up the manual for
4137 the application, opening it to the page describing the
4138 <interface>Properties
</interface> dialog.
4145 <sect2 id=
"common-right-click-items">
4146 <title>Other Common Pop-Up Items
</title>
4148 Many applets also have one or more of the following items in their
4149 right-click pop-up menu:
4155 The
<guimenuitem>Run...
</guimenuitem> menu item generally
4156 invokes a program which is related to the applet in some way
4157 but which runs in its own window rather than in the
4163 The
<application>CPU Load
</application> applet, which monitors
4164 what programs are running, has a
<guimenuitem>Run
4165 gtop...
</guimenuitem> menu item. Selecting this menu item
4166 starts
<application>GTop
</application>, which allows you to
4167 view and control programs which are running.
4172 The
<application>CD Player
</application> applet has a
4173 <guimenuitem>Run gtcd...
</guimenuitem> menu item which
4174 starts the GNOME
<application>CD Player
</application> when
4175 selected, which has more capabilities than the applet.
4186 <sect1 id=
"feedback">
4187 <title>Feedback
</title>
4188 <sect2 id=
"reporting-bugs">
4189 <title>Reporting Applet Bugs
</title>
4191 GNOME users are encouraged to report bugs to
<ulink type=
"http"
4192 url=
"http://bugs.gnome.org">The GNOME Bug Tracking
4193 System
</ulink>. The easiest way to submit bugs is to use the
4194 <application>Bug Report Tool
</application> program by selecting
4196 <guimenu>Main Menu
</guimenu> <guisubmenu>Utilities
</guisubmenu>
4197 <guimenuitem>Bug Report Tool
</guimenuitem>
4199 Be sure to be complete in describing what you did to cause the
4200 bug to surface and, if possible, describe how the developer can
4201 reproduce the the scenario.
4204 <sect2 id=
"documentation-feedback">
4205 <title>Providing Feedback
</title>
4207 GNOME users are welcome to provide suggestions for how
4208 applications and documentation can be improved. Suggestions for
4209 application changes should be submitted using the
4210 <application>Bug Report Tool
</application> discussed above.
4211 Suggestions for documentation changes can be emailed directly to
4212 the documentation author (whose email should be included in the
4213 "Authors" section of the document) or by sending an email to
4214 <email>docs@gnome.org
</email>.
4217 <sect2 id=
"joining-gnome">
4218 <title>Joining GNOME
</title>
4220 GNOME is a community project, created by hundreds of programmers,
4221 documentation writers, icon design artists, web masters, and
4222 other people, most of whom work on a volunteer basis. New GNOME
4223 contributors are always welcome. To join the GNOME team, visit
4224 these web sites: developers
— <ulink type=
"http"
4225 url=
"http://developer.gnome.org">The GNOME Development
4226 Site
</ulink>, documentation writers
— <ulink type=
"http"
4227 url=
"http://developer.gnome.org/projects/gdp">The GNOME Documentation
4228 Project
</ulink>, icon design artists
— <ulink type=
"http"
4229 url=
"http://gnome-icons.sourceforge.net/">Gnome Icon Web
</ulink>,
4230 general
— <ulink type=
"http"
4231 url=
"http://developer.gnome.org/helping/">Helping GNOME
</ulink>,
4232 or just join the gnome-list email list (see
<ulink type=
"http"
4233 url=
"http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing
4234 Lists
</ulink>) to discuss what you are interested in doing.
4240 <!-- ############### Template Applets ##################### -->
4241 <chapter id=
"template-applets">
4242 <title>Template Applets
</title>
4262 <!-- Please replace everywhere below GNOMEAPPLET with the name of -->
4263 <!-- your applet. Most importantly, all id attributes should start -->
4264 <!-- with the name of your applet - this is necessary to avoid name -->
4265 <!-- conflict among different applets -->
4266 <!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email-->
4267 <!-- Please replace HACKER-NAME with the applet author's name and -->
4268 <!-- HACKER-EMAIL with the applet author's email -->
4270 <!-- You should name your file: GNOMEAPPLET-applet.sgml -->
4271 <!-- Screenshots should be in PNG format and placed in the -->
4272 <!-- same directory as GNOMEAPPLET-applet.sgml -->
4274 <!-- Applet docs will be merged into <chapter>'s inside a -->
4275 <!-- <book>. Thus, the indentation below (2 spaces before the <sect1>) is -->
4278 <!-- Permission is granted to make and distribute verbatim copies of -->
4279 <!-- this manual provided the copyright notice and this permission -->
4280 <!-- notice are preserved on all copies. -->
4282 <!-- Permission is granted to copy and distribute modified versions of -->
4283 <!-- this manual under the conditions for verbatim copying, provided -->
4284 <!-- that the entire resulting derived work is distributed under the -->
4285 <!-- terms of a permission notice identical to this one. -->
4287 <!-- Permission is granted to copy and distribute translations of this -->
4288 <!-- manual into another language, under the above conditions for -->
4289 <!-- modified versions, except that this permission notice may be -->
4290 <!-- stated in a translation approved by the Foundation. -->
4292 <!-- ############### GNOMEAPPLET ############### -->
4293 <sect1 id=
"GNOMEAPPLET">
4294 <title>GNOMEAPPLET Applet
</title>
4297 <application>GNOMEAPPLET
</application> applet, shown in
<xref
4298 linkend=
"GNOMEAPPLET-fig">, does this and that. To learn how to
4299 add this applet to a
<interface>Panel
</interface>, see
<xref
4300 linkend=
"adding-applets">.
4304 <figure id=
"GNOMEAPPLET-fig">
4305 <title>GNOMEAPPLET
</title>
4307 <screeninfo>GNOMEAPPLET
</screeninfo>
4308 <graphic format=
"png" fileref=
"GNOMEAPPLET-fig" srccredit=
"ME">
4313 <sect2 id=
"GNOMEAPPLET-usage">
4314 <title>Usage
</title>
4316 This applet does nothing. To use it, just
4317 left-click on it and it will instantly do nothing.
4321 <sect2 id=
"GNOMEAPPLET-right-click">
4322 <title>Right-Click Pop-Up Menu Items
</title>
4324 In addition to the standard menu items (see
<xref
4325 linkend=
"standard-right-click-items">), the right-click pop-up menu has
4326 the following items:
4330 <guimenuitem>Properties...
</guimenuitem> — This menu
4331 item opens the
<interface>Properties
</interface> dialog (see
4332 <xref linkend=
"GNOMEAPPLET-properties">) which allows you to
4333 customize the appearance and behavior of this applet.
4338 <guimenuitem>Run Hello World...
</guimenuitem> — This
4339 menu item starts the program
<application>Hello
4340 World
</application>, used to say
"hello" to the world.
4347 <sect2 id=
"GNOMEAPPLET-properties">
4348 <title>Properties
</title>
4350 You can configure
<application>GNOMEAPPLET
</application> applet by
4351 right-clicking on the applet and choosing the
4352 <guimenuitem>Properties...
</guimenuitem> menu item. This will open the
4353 <interface>Properties
</interface> dialog, shown in
<xref
4354 linkend=
"GNOMEAPPLET-properties-fig">.
4356 <figure id=
"GNOMEAPPLET-properties-fig">
4357 <title>Properties Dialog
</title>
4359 <screeninfo>Properties Dialog
</screeninfo>
4360 <graphic format=
"png" fileref=
"GNOMEAPPLET-properties" srccredit=
"ME">
4366 To change the color of the applet, click on the
4367 <guibutton>color
</guibutton> button. To change other properties,
4368 click on other buttons.
4372 For more information on the
<interface>Properties
</interface>
4373 dialog, including descriptions of the
<guibutton>OK
</guibutton>,
4374 <guibutton>Apply
</guibutton>,
<guibutton>Cancel
</guibutton>, and
4375 <guibutton>Help
</guibutton> buttons, see
<xref
4376 linkend=
"applet-properties-dialog">.
4380 <sect2 id=
"GNOMEAPPLET-bugs">
4381 <title> Known Bugs and Limitations
</title>
4383 There are no known bugs in the
4384 <application>GNOMEAPPLET
</application> applet.
4388 <sect2 id=
"GNOMEAPPLET-authors">
4389 <title>Authors
</title>
4391 This applet was writen by HACKER-NAME
4392 <email>HACKER-EMAIL
</email>. The documentation for this applet
4393 which you are reading now was written by
4394 YOUR-NAME
<email>YOUR-EMAIL
</email>. For information on submitting
4395 bug reports and suggestions for improvements, see
<xref
4396 linkend=
"feedback">.
4413 <!-- ####### Document Templates | Templates 3: Application Help #######
4415 <sect1 id="template3">
4416 <title>Template 2: Application Help</title>
4418 <![CDATA[(Put sgml here.)]]> </programlisting>
4421 ####### Document Templates | Templates 4: Application Context Sensitive Help #######
4423 <sect1 id="template4">
4424 <title>Template 3: Application Context Sensitive Help</title>
4426 Context sensitive help is still in development.
4430 ####### Document Templates | Templates 5: Complete Application: gnome-hello #######
4432 <sect1 id="template5">
4433 <title>Template 4: Complete Application: gnome-hello</title>
4435 <![CDATA[(Put sgml here.)]]>
4439 ####### Document Templates | Templates 6: Tutorial #######
4441 <sect1 id="template6">
4442 <title>Template 5: Tutorial</title>
4444 <![CDATA[(Put sgml here.)]]>
projects / reactos.git / blob