Annotation of embedaddon/libxml2/test/relaxng/docbook_0.xml, revision 1.1.1.1
1.1 misho 1: <?xml version="1.0"?>
2: <!DOCTYPE article [
3: <!ENTITY version "1.0.53">
4: <!ENTITY mdash "--">
5: <!ENTITY hellip "...">
6: <!ENTITY copy "©"> <!-- COPYRIGHT SIGN -->
7: <!-- replace version above with actual application version number-->
8: <!-- Template Version: 1.0.1 (do not remove this line) -->
9:
10:
11:
12: <!ENTITY APPLET-TEMPLATE-1x-SHELL SYSTEM
13: "templates/applet_template_1-applet.sgml.cdata">
14: <!ENTITY APPLET-TEMPLATE-1x SYSTEM
15: "templates/applet_template_1.sgml.cdata">
16: ]>
17:
18: <!-- Version: 1.0.1 -->
19:
20: <article id="index">
21: <articleinfo>
22:
23: <authorgroup>
24:
25: <author>
26: <firstname>David</firstname>
27: <surname>Mason</surname>
28: <affiliation>
29: <orgname>Red Hat, Inc.</orgname>
30: <address>
31: <email>dcm@redhat.com</email>
32: </address>
33: </affiliation>
34: </author>
35:
36: <author>
37: <firstname>Daniel</firstname>
38: <surname>Mueth</surname>
39: <affiliation>
40: <address>
41: <email>d-mueth@uchicago.edu</email>
42: </address>
43: </affiliation>
44: </author>
45:
46: <author>
47: <firstname>Alexander</firstname>
48: <surname>Kirillov</surname>
49: <affiliation>
50: <address>
51: <email>kirillov@math.sunysb.edu</email>
52: </address>
53: </affiliation>
54: </author>
55:
56: </authorgroup>
57:
58: <releaseinfo>
59: This is a pre-release!
60: </releaseinfo>
61:
62: <revhistory>
63: <revision>
64: <revnumber>
65: 0.99
66: </revnumber>
67: <date>
68: 04.10.2000
69: </date>
70: </revision>
71: </revhistory>
72:
73: <copyright>
74: <year>2000</year>
75: <holder>Red Hat, Inc., Daniel Mueth, and Alexander Kirillov</holder>
76: </copyright>
77:
78: <legalnotice>
79: <para>
80: Permission is granted to copy, distribute and/or modify this
81: document under the terms of the <citetitle>GNU Free Documentation
82: License</citetitle>, Version 1.1 or any later version published
83: by the Free Software Foundation with no Invariant Sections, no
84: Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
85: of the <citetitle>GNU Free Documentation License</citetitle> from
86: the Free Software Foundation by visiting <ulink type="http"
87: url="http://www.fsf.org">their Web site</ulink> or by writing to:
88: Free Software Foundation, Inc., 59 Temple Place - Suite 330,
89: Boston, MA 02111-1307, USA.
90: </para>
91: <para>
92: Many of the names used by companies to distinguish their products and
93: services are claimed as trademarks. Where those names appear in any
94: GNOME documentation, and those trademarks are made aware to the members
95: of the GNOME Documentation Project, the names have been printed in caps
96: or initial caps.
97: </para>
98: </legalnotice>
99:
100: <title>The GNOME Handbook of Writing Software Documentation</title>
101:
102: </articleinfo>
103:
104: <!-- ################# Introduction ############### -->
105:
106: <sect1 id="intro">
107: <title>Introduction</title>
108:
109: <!-- ####### Introduction | The GNOME Documentation Project ####### -->
110:
111: <sect2 id="gdp">
112: <title>The GNOME Documentation Project</title>
113:
114: <sect3 id="goals">
115: <title>Goals</title>
116: <para>
117: The GNOME Documentation Project (GDP) aims to provide GNOME
118: and GNOME applications with a complete, intuitive, and clear
119: documentation system. At the center of the GDP is the
120: <application>GNOME Help Browser</application>, which
121: presents a unified interface to GNOME-specific documentation
122: as well as other Linux documentation such as man pages and
123: texinfo documents. The GNOME Help System provides a
124: comprehensive view of documentation on a machine by
125: dynamically assembling the documentation of GNOME
126: applications and components which are installed. The GDP is
127: responsible for writing numerous GNOME-related documents,
128: both for developers and for users. Developer documentation
129: includes <ulink url="http://developer.gnome.org/doc/API/"
130: type="http">APIs for the GNOME libraries</ulink>, <ulink
131: url="http://developer.gnome.org/doc/whitepapers/"
132: type="http"><citetitle>GNOME White
133: Papers</citetitle></ulink>, GNOME developer <ulink
134: url="http://developer.gnome.org/doc/tutorials/"
135: type="http">tutorials</ulink>, the <ulink
136: url="http://developer.gnome.org/doc/FAQ/"
137: type="http"><citetitle>GNOME Developer
138: FAQ</citetitle></ulink>, the <ulink
139: url="http://developer.gnome.org" type="http">GNOME
140: Developer's Website</ulink>, and <citetitle>GNOME
141: Handbook</citetitle>'s, such as the one you are reading.
142: User documentation include the <ulink
143: url="http://www.gnome.org/learn/"
144: type="http"><citetitle>GNOME User's
145: Guide</citetitle></ulink>, the <ulink
146: url="http://www.gnome.org/learn/"
147: type="http"><citetitle>GNOME FAQ</citetitle></ulink>, and
148: GNOME application documentation. Most GNOME applications
149: have their own manual in addition to context sensitive help.
150: </para>
151: </sect3>
152:
153: <sect3 id="joining">
154: <title>Joining the GDP</title>
155: <para>
156: Documenting GNOME and all the numerous GNOME applications is
157: a very large project. The GDP is always looking for people
158: to help write, update, and edit documentation. If you are
159: interested in joining the GDP team, you should join the
160: <ulink url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
161: <citetitle>gnome-doc-list mailing list</citetitle> </ulink>.
162: Read <xref linkend="gettingstarted" />, for help selecting a
163: project to work on. Feel free to introduce yourself on the
164: gnome-doc-list mailing list and indicate which project you
165: intend to work on, or else ask for suggestions of important
166: documents which need work done. You may also want to join the
167: #docs IRC channel on irc.gnome.org to meet other GDP members
168: and discuss any questions you may have. For a list of GDP
169: projects and members, see the
170: <ulink url="http://developer.gnome.org/projects/gdp">
171: <citetitle>GDP Website</citetitle></ulink>.
172: </para>
173: </sect3>
174:
175: <sect3 id="collaborating">
176: <title>Collaborating with the GDP</title>
177: <para>
178: GNOME developers, packagers, and translators may not be
179: writing GNOME documentation but will want to understand how
180: the GNOME documentation system works and will need to
181: collaborate with GDP members. This document should help to
182: outline the structure of how the GNOME documentation system
183: works. Developers who do not write the documentation for
184: their applications are encouraged to find a GDP member to
185: write the documentation. This is best done by sending an
186: email to the <ulink
187: url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
188: <citetitle>gnome-doc-list mailing list</citetitle> </ulink>
189: describing the application, where it can be downloaded from,
190: and that the developer(s) would like a GDP member to write
191: documentation for the application. The #docs IRC channel on
192: irc.gnome.org is another option for contacting GDP members.
193: </para>
194: </sect3>
195: </sect2>
196:
197: <!-- ####### Introduction | Notation and Conventions ####### -->
198:
199: <sect2 id="notation">
200: <title>Notation and Conventions</title>
201: <para>
202: This Handbook uses the following notation:
203: <informaltable frame="none">
204: <tgroup cols="2">
205: <tbody>
206: <row>
207: <entry>
208: <filename class="directory">/usr/bin</filename>
209: </entry>
210: <entry>
211: Directory
212: </entry>
213: </row>
214: <row>
215: <entry>
216: <filename>foo.sgml</filename>
217: </entry>
218: <entry>
219: Filename
220: </entry>
221: </row>
222: <row>
223: <entry>
224: <command>command</command>
225: </entry>
226: <entry>
227: Command or text that would be typed.
228: </entry>
229: </row>
230: <row>
231: <entry>
232: <command><replaceable>replaceable</replaceable></command>
233: </entry>
234: <entry>
235: "Variable" text that can be replaced.
236: </entry>
237: </row>
238: <row>
239: <entry>
240: <literal>Program or Doc Code</literal>
241: </entry>
242: <entry>Program or document code</entry>
243: </row>
244: </tbody>
245: </tgroup>
246: </informaltable>
247: </para>
248: </sect2>
249:
250: <!-- ####### Introduction | About This Handbook ####### -->
251:
252: <sect2 id="about">
253: <title>About This Handbook</title>
254: <para>
255: This Handbook is a guide for both writing documentation for
256: GNOME components and applications and for properly binding and
257: packaging documentation into GNOME applications.
258: </para>
259: <para>
260: This Handbook, like all GNOME documentation, was written in
261: DocBook(SGML) and is available in several formats including
262: SGML, HTML, PostScript, and PDF. For the latest version, see
263: <ulink
264: url="http://developer.gnome.org/projects/gdp/handbook.html">
265: <citetitle>Getting The GNOME Handbook of Writing Software
266: Documentation</citetitle> </ulink>. Alternately, one may
267: download it anonymously from GNOME CVS under <filename
268: class="directory">gnome-docu/gdp</filename>.
269: </para>
270: </sect2>
271: </sect1>
272:
273: <!-- ################# Getting Started ############### -->
274:
275: <sect1 id="gettingstarted">
276: <title>Getting Started Writing GNOME Documentation</title>
277:
278: <!--####### Getting Started | Selecting A Document ####### -->
279:
280: <sect2 id="selecting">
281: <title>Selecting A Document</title>
282:
283: <sect3 id="know">
284: <title>Document Something You Know</title>
285: <para>
286: The most frequently asked question of new contributors who
287: join the GDP is "which document should I start
288: with?". Because most people involved are volunteers, we do
289: not <emphasis>assign</emphasis> projects and applications to
290: write documents for. The first step is all yours - you must
291: decide what about GNOME interests you most and find out if
292: it has complete documents or not.
293: </para>
294: <para>
295: It is also important to spend some time with GNOME to make
296: sure you are familiar enough with it to be
297: <emphasis>authoritative</emphasis> in your writing. The
298: best way to do this is to just sit down and play with GNOME
299: as much as possible before starting to write.
300: </para>
301: <para>
302: The easiest way to get started is to improve existing
303: documentation. If you notice some inaccuracies or omissions
304: in the documentation, or you think that you can explain the
305: material more clearly, just send your suggestions to the
306: author of the original documentation or to the GNOME
307: documentation project at <email>docs@gnome.org</email>.
308: </para>
309: </sect3>
310:
311: <sect3 id="doctable">
312: <title>The GNOME Documentation Status Table</title>
313: <para>
314: The <citetitle>GDP Documentation Status Table</citetitle>
315: (<citetitle>DocTable</citetitle>) (<ulink
316: url="http://www.gnome.org/gdp/doctable/"
317: type="http">http://www.gnome.org/gdp/doctable/</ulink>) is a
318: web page which tracks the status of all the various
319: documentation components of GNOME. These components include
320: application documentation, internal GNOME component
321: documentation, user documentation, and developer
322: documentation. For each documentation item, it tracks the
323: current status of the documentation, who is working on the
324: particular document, where the documentation can be found,
325: and provides a forum for the discussion of each item.
326: </para>
327: <para>
328: You should use the <citetitle>DocTable</citetitle> to help
329: you select a documentation item which needs work done. Once
330: you have selected an item to work on, please register
331: yourself as an author so that other authors do not duplicate
332: your work and may contact you to help or offer suggestions.
333: Also be sure to keep the status icons up-to-date so that
334: the GDP team can easily identify which items need additional
335: help. The <citetitle>DocTable</citetitle> also allows
336: people to make announcements and suggestions and to discuss
337: issues in the comments section.
338: </para>
339: <note>
340: <title>Note</title>
341: <para>
342: Note that the information in the
343: <citetitle>DocTable</citetitle> may not always be up-to-date
344: or accurate. When you assign yourself to documenting an
345: application, make sure you find out the latest status of
346: documentation by contacting the application author.
347: </para>
348: </note>
349: </sect3>
350: </sect2>
351:
352: <!-- ####### Getting Started | Installing And Using DocBook ####### -->
353:
354: <sect2 id="docbook">
355: <title>Installing and Using DocBook</title>
356: <para>
357: All documentation for the GNOME project is written in SGML
358: using the DocBook DTD. There are many advantages to using
359: this for documentation, not least of which is the single
360: source nature of SGML. To contribute to the GDP you should
361: learn to use DocBook.
362: </para>
363: <note>
364: <title>NOTE</title>
365: <para>
366: To get started writing for the GDP you do not need to rush
367: out and learn DocBook - if you feel it is too much to handle
368: for now, you can submit plain ASCII text to the <ulink
369: url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
370: <citetitle>gnome-doc-list mailing list</citetitle>
371: </ulink>and a volunteer will mark it up for you. Seeing your
372: document marked up will also be a great way for you to start
373: learning DocBook.
374: </para>
375: </note>
376: <sect3 id="installingdocbook">
377: <title>Installing DocBook</title>
378: <para>
379: Download and install the following <ulink
380: url="ftp://sourceware.cygnus.com:/pub/docbook-tools/"
381: type="ftp">DocBook Tools packages</ulink>: jade, docbook,
382: jadetex, sgml-common, and stylesheets. (RPM users should note
383: that jade is platform dependent (eg. i386), while the other packages
384: are in the <filename class="directory">noarch</filename>
385: directory.) You can find more
386: information on DocBook Tools <ulink url="
387: http://sourceware.cygnus.com/docbook-tools/"
388: type="http">here</ulink>.
389: </para>
390: <para>
391: If you are an <application>Emacs</application> user you may
392: want to grab the psgml package as well. This is a major mode
393: for editing sgml files in <application>Emacs</application>.
394: </para>
395: </sect3>
396:
397: <sect3 id="gdpstylesheets">
398: <title>GDP Stylesheets</title>
399: <para>
400: The GDP uses its own DocBook stylesheets. To use the GDP
401: stylesheets, you should download the file
402: <filename>gdp-both.dsl</filename> from the <filename
403: class="directory">gnome-docu/gdp/dsssl</filename> module in
404: CVS (or from <ulink
405: url="http://developer.gnome.org/projects/gdp/stylesheets.html">
406: GDP Custom DSSSL Stylesheet</ulink>)and copy it
407: <!-- into <filename
408: class="directory">/usr/lib/sgml/stylesheets</filename>. You
409: will need to point DocBook Tools to this stylesheet with the
410: <command><option>-d</option></command> option:
411: <command>db2html -d /usr/lib/sgml/stylesheets/gdp-both.dsl
412: <replaceable>foo.sgml</replaceable></command>. (Creating an
413: alias to include this option and path is convenient.)
414: Alternately, you could overwrite
415: <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>
416: with <filename>gdp-both.dsl</filename>.
417: -->
418: over the file
419: <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>.
420: Alternately, you can download and install the
421: <ulink url="http://people.redhat.com/dcm/software.html"
422: type="http">gnome-doc-tools package</ulink> which will set
423: up the stylesheets as well as the DTD discussed below.
424: </para>
425:
426: <!-- <note>
427: <para>
428: The current version of the DocBook Tools command
429: <command>db2ps</command> does not have a
430: <command><option>-d</option></command> option. In order to
431: create PostScript output, you must overwrite
432: <filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>
433: with <filename>gdp-both.dsl</filename>.
434: </para>
435: </note>
436: -->
437: </sect3>
438:
439: <sect3 id="gdpdtd">
440: <title>GDP DTD (PNG Image Support)</title>
441: <para>
442: Due to some license issues involved with the creation of
443: gifs, the GNOME Documentation Project has decided to use the
444: PNG image format for all images in GNOME documentation. You
445: can read more about the issues involved with gifs at <ulink
446: url="http://www.gnu.org/philosophy/gif.html"
447: type="http">http://www.gnu.org/philosophy/gif.html</ulink>.
448: </para>
449: <para>
450: The current DocBook DTD(3.1) does not include support for
451: embedding PNG images in your documents. Since the GDP uses
452: many screenshots in its documentation, we use our own
453: variation on the DocBook DTD which has PNG image support.
454: We encourage everybody to use this DTD instead of the
455: default DocBook DTD since your source document header and
456: your output document appearance subtly vary between the two
457: DTD's. To install the GDP custom DTD with PNG image support
458: by hand:
459: </para>
460: <itemizedlist mark="opencircle">
461: <listitem>
462: <para>
463: Download <ulink
464: url="http://www.labs.redhat.com/png/png-support.html">the
465: GDP DocBook DTD for PNG support</ulink> and install it
466: where you keep your DTD's. (On Red Hat use <filename
467: class="directory">/usr/lib/sgml/</filename>.) Note that
468: the 3.0 DTD is missing support for the
469: <sgmltag><legalnotice></sgmltag> tag, so it is
470: recommended that you use version 3.1
471: </para>
472: </listitem>
473: <listitem override="bullet">
474: <para>
475: Add the new DTD to your SGML CATALOG file. The location
476: of your SGML CATALOG file may vary depending upon your
477: distribution. (On Red Hat it is usually in
478: /usr/lib/sgml/CATALOG.) Add the following line to this
479: file:
480: <programlisting>
481: PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd"
482: </programlisting>
483: If you are using the 3.1 DTD, use:
484: <programlisting>
485: PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd"
486: </programlisting>
487: </para>
488: </listitem>
489: </itemizedlist>
490: <para>
491: Alternately, you can download and install the
492: <ulink url="http://people.redhat.com/dcm/software.html"
493: type="http">gnome-doc-tools package</ulink> which will set
494: up the custom stylesheets and DTD for you.
495: </para>
496: <para>
497: To include PNG files in your documents, you will need to
498: indicate that you are using this special DTD. To do
499: this, use the following headers:
500: </para>
501: <para>
502: Articles:
503: <programlisting>
504: <![CDATA[<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant
505: V1.1//EN"[]>]]>
506: </programlisting>
507: </para>
508: <para>
509: Books:
510: <programlisting>
511: <![CDATA[<!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant
512: V1.1//EN"[]>]]>
513: </programlisting>
514: </para>
515:
516: </sect3>
517:
518: <sect3 id="editors">
519: <title>Editors</title>
520: <para>
521: There are many editors on Linux and UNIX systems available
522: to you. Which editor you use to work on the sgml documents
523: is completely up to you, as long as the editor is able to
524: preserve sgml and produce the source in a format that is
525: readable by everyone.
526: </para>
527: <para>
528: Probably the two most popular editors available are
529: <application>Emacs</application> and
530: <application>vi</application>. These and other editors are
531: used regularly by members of the GDP. Emacs has a major
532: mode, psgml, for editing sgml files which can save you time
533: and effort in adding and closing tags. You will find the
534: psgml package in DocBook Tools, which is the standard set of
535: tools for the GDP. You may find out more about DocBook Tools
536: in <xref linkend="installingdocbook" />.
537: </para>
538: </sect3>
539:
540: <sect3 id="make-output">
541: <title>Creating Something Useful with your Docs</title>
542: <para>
543: The tools available in DocBook Tools allow you to convert
544: your sgml document to many different formats including html
545: and Postscript. The primary tool used to do the conversion
546: is an application called <application>Jade</application>. In
547: most cases you will not have to work directly with
548: <application>Jade</application>; Instead, you will use the
549: scripts provided by DocBook Tools.
550: </para>
551: <para>
552: To preview your DocBook document, it is easiest to convert
553: it to <filename>html</filename>. If you have installed the
554: DocBook tools described above, all you have to do is to run
555: the command <prompt>$</prompt><command>db2html
556: mydocument.sgml</command>. If there are no sgml syntax
557: errors, this will create a directory <filename
558: class="directory">mydocument</filename> and place the
559: resulting html files in it. The title page of the document
560: will typically be
561: <filename>mydocument/index.html</filename>. If you have
562: screenshots in your document, you will have to copy these
563: files into the <filename
564: class="directory">mydocument</filename> directory by
565: hand. You can use any web browser to view your document.
566: Note that every time you run <command>db2html</command>, it
567: creates the <filename
568: class="directory">mydocument</filename> directory over, so
569: you will have to copy the screenshots over each time.
570: </para>
571: <para>
572: You can also convert your document to PostScript by running
573: the command <prompt>$</prompt><command>db2ps
574: mydocument.sgml</command>, after which you can print out or
575: view the resulting .ps file.
576: </para>
577: <note>
578: <title>NOTE</title>
579: <para>
580: The html files you get will not look quite the same as the
581: documentation distributed with GNOME unless you have the
582: custom stylesheets installed on your machine. DocBook
583: Tools' default stylesheets will produce a different look
584: to your docs. You can read more about the GDP stylesheets
585: in <xref linkend="gdpstylesheets" />.
586: </para>
587: </note>
588: </sect3>
589:
590: <sect3 id="jadeimages">
591: <title>Images in DocBook Tools</title>
592: <para>
593: If your document uses images you will need to take note of a
594: few things that should take place in order for you to make
595: use of those images in your output.
596: </para>
597: <para>
598: The DocBook Tools scripts and applications are smart enough
599: to know that when you are creating html you will be using
600: PNG files and when you are creating Postscript you will be
601: using EPS files (you must use EPS with Postscript).
602: </para>
603: <para>
604: Thus, you should never explicitly
605: include the extension of the image file, since DocBook
606: Tools will automatically insert it for you. For example:
607: </para>
608: <programlisting>
609: <![CDATA[
610: <figure>
611: <title>My Image</title>
612: <screenshot>
613: <screeninfo>Sample GNOME Display</screeninfo>
614: <graphic format="png" fileref="myfile" srccredit="me">
615: </graphic>
616: </screenshot>
617: </figure>
618: ]]> </programlisting>
619: <para>
620: You will notice in this example that the file
621: <filename>myfile.png</filename> was referred to as simply
622: <filename>myfile</filename>. Now when you run
623: <command>db2html</command> to create an html file, it will
624: automatically look for <filename>myfile.png</filename> in
625: the directory.
626: </para>
627: <para>
628: If you want to create PostScript ouput, you will need to create an
629: EPS version of your image file to be displayed in the
630: PostScript file. There is a simple script available which
631: allows you to change a PNG image into an EPS file
632: easily. You can download this file - img2eps - from <ulink
633: url="http://people.redhat.com/dcm/sgml.html"
634: type="html">http://people.redhat.com/dcm/sgml.html</ulink>
635: (look for the img2eps section). Note that this script is
636: included in the gnome-doc-tools package, so if you are using
637: this package, you should already have
638: <command>img2eps</command> on you system.
639: </para>
640: </sect3>
641:
642: <sect3 id="moredocbookinfo">
643: <title>Learning DocBook</title>
644: <para>
645: There are many resources available to help you learn DocBook.
646: The following resources on the web are useful for learning
647: DocBook:
648: </para>
649: <itemizedlist mark="bullet">
650: <listitem>
651: <para>
652: <ulink url="http://www.docbook.org"
653: type="http">http://www.docbook.org</ulink> - Norman
654: Walsh's <citetitle>DocBook: The Definitive
655: Guide</citetitle>. Online O'Reilly book on using
656: DocBook. Contains an excellent element reference. May be
657: too formal for a beginner.
658: </para>
659: </listitem>
660: <listitem>
661: <para>
662: <ulink
663: url="http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html"
664: type="http">A Practical Introduction to DocBook</ulink>
665: - The Open Source Writers Group's introduction to using
666: DocBook. This is an excellent HOW-TO type article on
667: getting started.
668: </para>
669: </listitem>
670: <listitem>
671: <para>
672: <ulink
673: url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html"
674: type="http">Getting Going with DocBook: Notes for
675: Hackers</ulink> - Mark Galassi's introduction to DocBook
676: for hackers. This has to be one of the first
677: introductions to DocBook ever - still as good as it ever
678: was.
679: </para>
680: </listitem>
681: <listitem>
682: <para>
683: <ulink type="http" url="http://www.freebsd.org/tutorials/docproj-primer/">
684: FreeBSD Documentation Project Primer for New
685: Contributors</ulink> - FreeBSD documentation project
686: primer. Chapter 4.2 provides a very good introduction to
687: writing documentation using DocBook. Note that it also
688: describes some custom extensions of DocBook;
689: fortunately, they are clearly marked as such.
690: </para>
691: </listitem>
692: </itemizedlist>
693: <para>
694: Norman Walsh's book is also available in print.
695: </para>
696: <para>
697: The following sections of this document are designed to help
698: documentation authors write correct and consistent DocBook:
699: </para>
700: <itemizedlist mark="bullet">
701: <listitem>
702: <para>
703: <xref linkend="docbookbasics" /> - Descriptions of
704: commonly used DocBook tags.
705: </para>
706: </listitem>
707: </itemizedlist>
708: <para>
709: You may also discuss specific DocBook questions with GDP
710: members on the #docs IRC channel at irc.gnome.org and on the
711: gnome-doc-list mailing list.
712: </para>
713: </sect3>
714: </sect2>
715:
716: <!-- ####### Getting Started | GDP Document Examples ####### -->
717: <!--
718: <sect2 id="examples">
719: <title>GDP Document Examples</title>
720: <para>
721: Examples of various types of GNOME documents are found in
722: <xref linkend="examples" />. There is also an example GNOME
723: application with documentation called
724: <application>gnome-hello</application> in GNOME cvs.
725: </para>
726: </sect2>
727: -->
728: <!-- ####### Getting Started | GDP Document Templates ####### -->
729:
730: <sect2 id="gdptemplates">
731: <title>GDP Document Templates</title>
732: <para>
733: Templates for various types of GNOME documents are found in
734: <xref linkend="templates" />. They are kept in CVS in
735: gnome-docu/gdp/templates. The easiest source to get them from
736: is probably the <ulink
737: url="http://developer.gnome.org/projects/gdp/templates.html"
738: type="http">GDP
739: Document Templates</ulink> web page, which is typically kept
740: completely up-to-date with CVS and has a basic description of
741: each file from CVS.
742: </para>
743: </sect2>
744:
745: <!-- ####### Getting Started | Screenshots ####### -->
746:
747: <sect2 id="screenshots">
748: <title>Screenshots</title>
749: <para>
750: Most GNOME documents will have screenshots of the particular
751: applet, application, GNOME component, or widget being
752: discussed. As discussed above in <xref linkend="gdpdtd"/> you
753: will need to install the special GDP DocBook DTD which
754: supports PNG images, the format used for all images in GNOME
755: documentation. For the basic DocBook structure used to insert
756: images in a document, see <xref linkend="jadeimages"/> above.
757: </para>
758: <sect3 id="screenshotappearance">
759: <title>Screenshot Appearance</title>
760: <para>
761: For all screenshots of windows that typically have border
762: decorations (e.g. applications and dialogs, but not applets
763: in a <interface>panel</interface>), GDP standards dictate
764: the appearance of the window. (This is to minimize possible
765: confusion to the reader, improve the appearance of GNOME
766: documents, and guarantee the screenshot is readable when
767: printed.) All screenshots should be taken with the SawFish
768: (formerly known as Sawmill) window manager using the
769: MicroGui theme and Helvetica 12pt font. (A different window
770: manager can be used provided the MicroGui theme is available
771: for this window manager and the appearance is identical to
772: that when using the SawFish window manager.) The default
773: GTK+ theme(gtk) and font (Helvetica 12 pt) should be used
774: for all screenshots. If you are unable to provide
775: screenshots in this form, you should create screenshots as
776: you wish them to appear and send them to the
777: <ulink url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
778: <citetitle>gnome-doc-list mailing list</citetitle> </ulink>
779: requesting a GDP member reproduce these screenshots in the
780: correct format and email them to you.
781: </para>
782: </sect3>
783: <sect3 id="screenshottools">
784: <title>Screenshot Tools</title>
785: <para>
786: There are many tools for taking screenshots in
787: GNOME/Linux. Perhaps the most convenient is the
788: <application>Screen-Shooter Applet</application>. Just click
789: on the window icon in the applet and then on the window you
790: would like to take a screenshot of. (Note that
791: at the time of this writing, PNG images taken by
792: screenshooter do not appear properly in
793: <application>Netscape</application> or the
794: <application>GNOME Help Browser</application>. You
795: should save your screenshot as a GIF and
796: then use <command>convert filename.gif
797: filename.png</command>.) For applets
798: in a <interface>Panel</interface>,
799: <application>xv</application> can be used to crop the
800: screenshot to only include the relevant portion of the
801: <interface>Panel</interface>. Note that
802: <application>xv</application> and
803: <application>gimp</application> can both be used for taking
804: screenshots, cropping screenshots, and converting image
805: formats.
806: </para>
807: </sect3>
808: <sect3 id="screenshotfiles">
809: <title>Screenshot Files</title>
810: <para>
811: Screenshots should be kept in the main documentation
812: directory with your SGML file for applets, or should be
813: kept in a directory called "figs" for application and other
814: documentation. After you use <command>db2html</command> to
815: convert your SGML file to HTML (see <xref
816: linkend="make-output"/>), you will need to copy your
817: screenshots (either the individual PNG files for applet
818: documentation, or the whole "figs" directory for other
819: documentation) into the newly created HTML directory. Note
820: that every time you use <command>db2html</command> the HTML
821: directory is erased and rewritten, so do not store your only
822: copy of the screenshots in that directory. If you wish to
823: create PostScript or PDF output, you will need to manually
824: convert the PNG images to EPS as described in <xref
825: linkend="jadeimages"/>, but will not need to copy these
826: images from their default location, as they are included
827: directly into the output(PostScript of PDF) file.
828: </para>
829: </sect3>
830: </sect2>
831:
832:
833: <!-- ####### Getting Started | Application Bugs ####### -->
834:
835: <sect2 id="applicationbugs">
836: <title>Application Bugs</title>
837: <para>
838: Documentation authors tend to investigate and test applets and
839: applications more thoroughly than most
840: users. Often documentation authors will discover one or
841: more bugs in the software. These bugs vary from small ones,
842: such as mis-spelled words or missing
843: <interface>About</interface> dialogs in the menu, to large
844: ones which cause the applet to crash. As all users, you
845: should be sure to report these bugs so that application
846: developers know of them and can fix them. The easiest way to
847: submit a bug report is by using the <application>Bug
848: Buddy</application> applet which is part of the gnome-applets
849: package.
850: </para>
851: </sect2>
852:
853:
854: <!-- ####### Getting Started | Using CVS ####### -->
855:
856: <sect2 id="cvs">
857: <title>Using CVS</title>
858: <para>
859: CVS (Concurrent Versions System) is a tool that allows
860: multiple developers to concurrently work on a set of
861: documents, keeping track of the modifications made by each
862: person. The files are stored on a server and each developer
863: checks files out, modifies them, and then checks in their
864: modified version of the files. Many GNOME programs and
865: documents are stored in CVS. The GNOME CVS server allows
866: users to anonymously check out CVS files. Most GDP members
867: will need to use anonymous CVS to download the most up-to-date
868: version of documentation or programs. Modified documents will
869: typically be emailed to the the application developer. Core
870: GDP members may also be granted login CVS privileges so they
871: may commit modified files directly to CVS.
872: </para>
873:
874: <sect3 id="anonymouscvs">
875: <title>Anonymous CVS</title>
876: <para>
877: To anonymously check out documents from CVS, you must first
878: log in. From the bash shell, you should set your CVSROOT
879: shell variable with <command> export
880: CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</command>
881: and then login with <command>cvs login</command>(there is no
882: password, just hit return). As an example, we will use the
883: "gnome-docu/gdp" module which contains this and several
884: other documents. To check these documents out for the first
885: time, type <command>cvs -z3 checkout
886: gnome-docu/gdp</command>. After you have this document
887: checked out and you would like to download any updates on
888: the CVS server, use <command>cvs -z3 update -Pd</command>.
889: </para>
890: </sect3>
891:
892: <sect3 id="logincvs">
893: <title>Login CVS</title> <para> If you have been given a
894: login for the GNOME CVS server, you may commit your file
895: modifications to CVS. Be sure to read the following section
896: on CVS etiquette before making any commits to CVS. To log in
897: to the CVS server as user
898: <command><replaceable>username</replaceable></command> with a
899: password, you must first set your CVSROOT shell variable with
900: <command> export
901: CVSROOT=':pserver:<replaceable>username</replaceable>@cvs.gnome.org:/cvs/gnome'</command>.
902: Log in with <command>cvs login</command> and enter your
903: password. You may check out and update modules as described
904: above for anonymous CVS access. As a login CVS user, you may
905: also check modified versions of a file into the CVS server.
906: To check
907: <command><replaceable>filename</replaceable></command> into
908: the CVS server, type <command>cvs -z3 commit
909: <replaceable>filename</replaceable></command>. You will be
910: given a vi editor window to type in a brief log entry,
911: summarizing your changes. The default editor can be changed
912: using the <varname>EDITOR</varname> environment variable or
913: with the <command><option>-e</option></command> option. You
914: may also check in any modifications to files in the working
915: directory and subdirectories using <command>cvs -z3
916: commit</command>. To
917: add a new file to the CVS server, use <command>cvs -z3 add
918: <replaceable>filename</replaceable></command>, followed by the
919: commit command.
920: </para>
921: </sect3>
922:
923: <sect3 id="cvsetiquette">
924: <title>CVS Etiquette</title>
925: <para>
926: Because files in CVS are typically used and modified by
927: multiple developers and documentation authors, users should
928: exercise a few simple practices out of courtesy towards the
929: other CVS users and the project leader. First, you should
930: not make CVS commits to a package without first discussing
931: your plans with the project leader. This way, the project
932: leader knows who is modifying the files and generally, what
933: sort of changes/development is being done. Also, whenever a
934: CVS user commits a file to CVS, they should make an entry in
935: the CVS log and in the <filename>ChangeLog</filename> so
936: that other users know who is making modifications and what
937: is being modified. When modifying files created by others,
938: you should follow the indentation scheme used by the initial
939: author.
940: </para>
941: </sect3>
942: </sect2>
943: </sect1>
944:
945: <!-- ################# The GNOME Documentation System###############
946: -->
947:
948: <sect1 id="gnomedocsystem">
949: <title>The GNOME Documentation System</title>
950:
951: <!-- ####### The GNOME Documentation System | The GNOME Help Browser
952: ####### -->
953:
954: <sect2 id="gnomehelpbrowser">
955: <title>The GNOME Help Browser</title>
956: <para>
957: At the core of the GNOME help system is the <application>GNOME
958: Help Browser</application>. The <application>Help
959: Browser</application> provides a unified interface to several
960: distinct documentation systems on Linux/Unix systems: man
961: pages, texinfo pages, Linux Documentation Project(LDP)
962: documents, GNOME application documentation, and other GNOME
963: documents.
964: </para>
965: <para>
966: The <application>GNOME Help Browser</application> works by
967: searching standard directories for documents which are to be
968: presented. Thus, the documentation that appears in the GHB is
969: specific to each computer and will typically only represent
970: software that is installed on the computer.
971: </para>
972: </sect2>
973:
974: <!-- ####### The GNOME Documentation System | The GNOME Help Browser
975: ####### -->
976:
977: <sect2 id="gnomehelpbrowser2">
978: <title>The GNOME Help Browser (GNOME-2.0)</title> <para> In
979: GNOME 2.0, the <application>GNOME Help Browser</application>
980: will be replaced by <application>Nautilus</application>.
981: Nautilus will be the file manager/graphical shell for GNOME 2.0
982: and will also implement a more sophisticated help system than
983: that used by the <application>GNOME Help Browser</application>
984: used in GNOME 1.0. It will read and display DocBook files
985: directly, avoiding the need for duplicating documents in both
986: DocBook and HTML formats. Its display engine for DocBook will
987: be much faster than running <application>jade</application> to
988: convert to HTML for rendering. Because it uses the original
989: DocBook source for documentation, it will be possible to do more
990: sophisticated searching using the meta information included in
991: the documents. And since Nautilus is a virtual file system
992: layer which is Internet-capable, it will be able to find and
993: display documents which are on the web as well as those on the
994: local file system. For more information on
995: <application>Nautilus</application>, visit the #nautilus IRC
996: channel on irc.gnome.org. </para>
997: </sect2>
998:
999: <!-- ####### The GNOME Documentation System | GNOME On-The-Fly
1000: Documentation Generation ####### -->
1001:
1002: <sect2 id="gnomehelponthefly">
1003: <title>Dynamic Document Synthesis(GNOME-2.0)</title>
1004: <para>
1005: GNOME uses the documentation presented by all the various
1006: GNOME components and applications installed on the system to
1007: present a complete and customized documentation environment
1008: describing only components which are currently installed on a
1009: users system. Some of this documentation, such as the manuals
1010: for applets, will be combined in such a way that it appears to
1011: be a single document.
1012: </para>
1013: <para>
1014: By using such a system, you can be sure that any GNOME app you
1015: install that has documentation will show up in the index,
1016: table of contents, any search you do in the help browser.
1017: </para>
1018: </sect2>
1019:
1020: <!-- ####### The GNOME Documentation System | The GNOME Documentation
1021: Components ####### -->
1022:
1023: <sect2 id="gnomehelpcomponents">
1024: <title>The GNOME Documentation Components</title>
1025:
1026: <sect3 id="applicationmanualsintro">
1027: <title>Application Manuals</title>
1028: <para>
1029: Every GNOME application should have an application manual.
1030: An application manual is a document specific to the
1031: particular application which explains the various windows
1032: and features of the application. Application Manuals
1033: typically use screenshots (PNG format) for clarity. Writing
1034: application manuals is discussed in more detail in <xref
1035: linkend="writingapplicationmanuals" /> below.
1036: </para>
1037: </sect3>
1038:
1039: <sect3 id="applicationhelpintro">
1040: <title>Application Help</title>
1041: <para>
1042: Applications should have a <guibutton>Help</guibutton>
1043: button on screens on which users may need help. These
1044: <guibutton>Help</guibutton> buttons should pull up the
1045: default help browser, determined by the
1046: <varname>ghelp</varname> URL Handler (configured using the
1047: <application>Control Center</application>), typically the
1048: <application>GNOME Help Browser</application>. The help
1049: browser should show either the first page of the application
1050: manual, or else the relevant page thereof. Application help
1051: is described in more detail in <xref
1052: linkend="applicationhelpbuttons" /> below.
1053: </para>
1054: </sect3>
1055:
1056: <sect3 id="contextsensitivehelpintro">
1057: <title>Application Context Sensitive Help (coming in
1058: GNOME-2.0)</title>
1059: <para>
1060: Context sensitive help is a system which will allow the user
1061: to query any part (button, widget, etc.) of an application
1062: window. This is done by either entering a CS Help mode by
1063: clicking on an icon or by right clicking on the application
1064: part and selecting "What's This" or whatever is decided on
1065: at the time. Context sensitive help is described in more
1066: detail in <xref linkend="writingcontextsensitivehelp" />
1067: below.
1068: </para>
1069: </sect3>
1070:
1071: <sect3 id="userguide">
1072: <title>The GNOME User Guide</title>
1073: <para>
1074: The <citetitle>GNOME User Guide</citetitle> describes the
1075: GNOME desktop environment and core components of GNOME such
1076: as the <application>panel</application> and
1077: <application>control center</application>. In GNOME 1.x this
1078: was the main and only source of documentation. In GNOME 2.0
1079: this will become a document for the web and for printing
1080: that is derived from various parts chosen in the system that
1081: are necessary for the new user to understand.
1082: </para>
1083: </sect3>
1084:
1085: <sect3 id="userdocs">
1086: <title>User Documents</title>
1087: <para>
1088: Aside from the <citetitle>GNOME User Guide</citetitle>,
1089: there are several other documents to help GNOME users learn
1090: GNOME, including the <citetitle>GNOME FAQ</citetitle>,
1091: <citetitle>GNOME Installation and Configuration
1092: Guide</citetitle>, and the <citetitle>GNOME Administrators
1093: Guide</citetitle>.
1094: </para>
1095: </sect3>
1096:
1097: <sect3 id="developerdocs">
1098: <title>Developer Documents</title>
1099: <para>
1100: There are many White Papers, Tutorials, HOWTO's and FAQ's to
1101: make programming GNOME and GNOME applications as easy as
1102: possible.
1103: </para>
1104: <para>
1105: API documentation is also available for the GNOME libraries. This is
1106: detailed documentation of the code that is used to build GNOME
1107: apps. You can keep up with the GNOME API docs on the <ulink
1108: url="http://developer.gnome.org/doc/API/" type="http">GNOME API
1109: Reference</ulink> page.
1110: </para>
1111: </sect3>
1112:
1113: <sect3 id="projectdocs">
1114: <title>Project Documents</title>
1115: <para>
1116: Some GNOME projects have documentation to maintain
1117: consistency in their product and to help new contributors
1118: get up to speed quickly. Among these are the GDP documents,
1119: such as the one you are reading now.
1120: </para>
1121: </sect3>
1122: </sect2>
1123: </sect1>
1124:
1125:
1126: <!-- ################# DocBook Basics ############### -->
1127:
1128: <sect1 id="docbookbasics">
1129: <title>DocBook Basics </title>
1130: <!-- ####### DocBook Basics | Introduction to DocBook ####### -->
1131:
1132: <sect2 id="introtodocbook">
1133: <title>Introduction to DocBook</title>
1134: <para>
1135: To understand DocBook, a basic understanding of SGML is
1136: helpful. SGML stands for Standard General Markup Language and
1137: is one of the first markup languages every created. HTML is
1138: actually derived from SGML and XML is a subset of SGML. SGML
1139: uses what is called a Document Type Definition to specify
1140: <emphasis>elements</emphasis> which are contained between
1141: brackets, < and >. Text is marked by both beginning and
1142: ending elements, for example in the DocBook DTD, one denotes a
1143: title with <sgmltag><title></sgmltag>The
1144: Title<sgmltag></title></sgmltag>.
1145: </para>
1146: <para>
1147: The DTD (in the case of the GDP, DocBook) defines rules for how the
1148: elements can be used. For example, if one element can only be used when
1149: embedded within another, this is defined in the DTD.
1150: </para>
1151: <para>
1152: An SGML file is just a plain ASCII file containing the text
1153: with the markup specified above. To convert it to some easily
1154: readable format, you need special tools. The GDP uses <emphasis>DocBook
1155: Tools</emphasis>, a free package of utilities for working with DocBook
1156: which includes <emphasis>Jade</emphasis>, which does the SGML/DSSL
1157: parsing. You can read more about DocBook Tools in <xref
1158: linkend="installingdocbook" />.
1159: </para>
1160: <para>
1161: The final appearance of the output (e.g. PostScript or HTML)
1162: is determined by a
1163: <emphasis>stylesheet</emphasis>. Stylesheets are files,
1164: written in a special language (DSSSL — Document Style
1165: Semantics and Specification Language), which specify the
1166: appearance of various DocBook elements, for example,
1167: what fonts to use for titles and various inline elements, page
1168: numbering style, and much more. DocBook tools come with a
1169: collection of stylesheets (Norman Walsh's modular
1170: stylesheets); GNOME Document Project uses some customized
1171: version of this stylesheets — see <xref
1172: linkend="gdpstylesheets"/>.
1173: </para>
1174: <para>
1175: The advantage of specifying the <emphasis>structure</emphasis>
1176: of a document with SGML instead of specifying the
1177: <emphasis>appearance</emphasis> of the document with a typical
1178: word processor, or with html, is that the resulting document
1179: can be processed in a variety of ways using the structural
1180: information. Whereas formatting a document for appearance
1181: assumes a medium (typically written text on a standard-sized
1182: piece of paper), SGML can be processed to produce output for a
1183: large variety of media such as text, postscript, HTML,
1184: Braille, audio, and potentially many other formats.
1185: </para>
1186: <para>
1187: Using 'content' as the elements to define the text of a document also
1188: allows for search engines to make use of the actual elements to make a
1189: "smarter search". For example, if you are searching for all documents
1190: written by the author "Susie" your search engine could be made smart
1191: enough to only search <author> elements, making for a faster and more
1192: accurate search.
1193: </para>
1194: <para>
1195: Since the overall appearance of the output is determined not by the DTD
1196: or the SGML document, but rather by a stylesheet, the appearance of a
1197: document can be easily changed just by changing the stylesheet. This
1198: allows everyone in the project to create documents that all look the
1199: same.
1200: </para>
1201: <para>
1202: As stated before, the GDP uses the DocBook DTD. For a list of
1203: introductory and reference resources on DocBook, see <xref
1204: linkend="resources" />. The following sections also provide
1205: convenient instructions on which markup tags to use in various
1206: circumstances. Be sure to read <xref linkend="conventions" />
1207: for GDP documentation-specific guidelines.
1208: </para>
1209: </sect2>
1210:
1211: <!-- ###### DocBook Basics | XML and SGML ########-->
1212: <sect2 id="xml">
1213: <title>XML and SGML</title>
1214:
1215: <para> In not so distant future (probably before GNOME 2.0),
1216: DocBook itself and GNOME Documentation project will migrate from
1217: SGML to XML. This transition should be relatively painless:
1218: (almost) all DocBook tags will remain the same. However, XML has
1219: stricter syntax rules than SGML; thus, some constructions which
1220: are valid in SGML will not be valid in XML. Therefore, to be
1221: ready for this transistion, it is <emphasis>strongly
1222: advised</emphasis> that the documentation writers conform to XML
1223: syntax rules. Here are most important differences:
1224: </para>
1225:
1226: <variablelist>
1227: <varlistentry>
1228: <term> <emphasis>Minimization</emphasis></term>
1229: <listitem>
1230:
1231: <para>
1232: It is possible with some implementations of SGML to use
1233: minimizations to close elements in a document by using
1234: </>, for example:
1235: <literal><sgmltag><title></sgmltag>The
1236: Title<sgmltag></></sgmltag></literal>. This is not
1237: allowed in XML. You can use <command>sgmlnorm</command> command,
1238: included in DocBook Tools package, to expand minimized tags;
1239: if you are using <application>Emacs</application> with psgml
1240: mode, you can also use menu command
1241: <menuchoice>
1242: <guimenu>Modify</guimenu>
1243: <guimenuitem>Normalize</guimenuitem>
1244: </menuchoice>.
1245: </para>
1246: </listitem>
1247: </varlistentry>
1248: <varlistentry>
1249: <term> <emphasis>Self-closing tags</emphasis></term>
1250: <listitem>
1251:
1252: <para>
1253: Also, in SGML some tags are allowed not to have closing
1254: tags. For example, it is legal for
1255: <sgmltag><xref></sgmltag> not to have a closing tag:
1256: <literal><sgmltag><xref
1257: linkend="someid"></sgmltag></literal>. In
1258: XML, it is illegal; instead, you should use
1259: <literal><sgmltag><xref
1260: linkend="someid"/></sgmltag></literal> (note the
1261: slash!).
1262: </para>
1263: </listitem>
1264: </varlistentry>
1265:
1266: <varlistentry>
1267: <term> <emphasis>Case sensitive tags</emphasis></term>
1268: <listitem>
1269: <para>
1270: In XML, unlike SGML, tags are case-senstive
1271: <sgmltag><title></sgmltag> and
1272: <sgmltag><TITLE></sgmltag> are different tags!
1273: Therefore, please always use lowercase tags (except for
1274: things like <literal>DOCTYPE, CDATA</literal> and
1275: <literal>ENTITY</literal>, which are not DocBook tags).
1276: </para>
1277: </listitem>
1278: </varlistentry>
1279:
1280:
1281:
1282: </variablelist>
1283: </sect2>
1284:
1285:
1286:
1287: <!-- ####### DocBook Basics | Structure Elements ####### -->
1288:
1289:
1290: <sect2 id="structure"> <title> Structure Elements</title>
1291:
1292: <sect3 id="section">
1293: <title>Sections and paragraphs</title>
1294: <para>
1295: Top-level element of a book body must be
1296: <sgmltag><chapter></sgmltag>; it may contain one or more
1297: <sgmltag><sect1></sgmltag>, each of them may contain
1298: <sgmltag><sect2></sgmltag> and so on up to
1299: <sgmltag><sect5></sgmltag>. The top-level element of an
1300: article body is always
1301: <sgmltag><sect1></sgmltag>. Regardless of which elements
1302: you use, give each structural element a unique id, so that
1303: you can link to it. For usage example, see the template.
1304: </para>
1305: <para> Please try to avoid using deeply nested sections; for
1306: most situations, <sgmltag><sect1></sgmltag> and
1307: <sgmltag><sect2></sgmltag> should be sufficient. If not,
1308: you probably should split your <sgmltag><sect1></sgmltag>
1309: into several smaller ones.
1310: </para>
1311: <para> Use the tag <sgmltag><para></sgmltag> for
1312: paragraphs, even if there is only one paragraph in a
1313: section—see template for examples.
1314: </para>
1315: </sect3>
1316:
1317: <sect3 id="notes">
1318: <title>Notes, Warnings, And Tips</title>
1319: <para>
1320: For notes, tips, warnings, and important information, which
1321: should be set apart from the main text (usually as a
1322: paragraph with some warning sign on the margin), use tags
1323: <sgmltag><note></sgmltag>, <sgmltag><tip></sgmltag>,
1324: <sgmltag><warning></sgmltag>,
1325: <sgmltag><important></sgmltag> respectively. For example:
1326: <programlisting>
1327: <![CDATA[
1328: <tip>
1329: <title>TIP</title>
1330: <para>
1331: To speed up program compilation, use <application>gcc</application>
1332: compiler with Pentium optimization.
1333: </para>
1334: </tip>]]> </programlisting> produces
1335: </para>
1336: <tip id="extip">
1337: <title>TIP</title>
1338: <para>
1339: To speed up program compilation, use
1340: <application>gcc</application> compiler with Pentium
1341: optimization. </para>
1342: </tip>
1343: <para>
1344: Note that this should not be inside a
1345: <sgmltag><para></sgmltag> but between paragraphs.
1346: </para>
1347: </sect3>
1348: <sect3 id="figures">
1349: <title> Screenshots and other figures</title>
1350: <para>
1351: To include screenshots and other figures, use the following
1352: tags:
1353:
1354: <programlisting>
1355: <![CDATA[
1356: <figure id="shot1">
1357: <title>Screenshot</title>
1358: <screenshot>
1359: <screeninfo>Screenshot of a program</screeninfo>
1360: <graphic format="PNG" fileref="figures/example_screenshot" srccredit="ME">
1361: </graphic>
1362: </screenshot>
1363: </figure>]]>
1364: </programlisting>
1365: replacing <filename>example_screenshot</filename> with the
1366: actual file name (without extension). The result will look like this:
1367:
1368: <figure id="shot1">
1369: <title>Screenshot</title>
1370: <screenshot>
1371: <screeninfo>Screenshot of a program</screeninfo>
1372: <graphic format="PNG"
1373: fileref="figures/example_screenshot" srccredit="ME"/>
1374:
1375: </screenshot>
1376: </figure>
1377: </para>
1378: <note>
1379: <title>NOTE</title>
1380: <para>
1381: Notice in this example that the screenshot file name does
1382: not include the file type extension — to find out
1383: why, please read <xref linkend="jadeimages" />.
1384: </para>
1385: </note>
1386: </sect3>
1387: <sect3 id="listing">
1388: <title>Program listings and terminal session</title> <para>
1389: To show a file fragment—for example, program
1390: listing—use <sgmltag><programlisting></sgmltag> tag:
1391: <programlisting>
1392: <![CDATA[
1393: <programlisting>
1394: [Desktop Entry]
1395: Name=Gnumeric spreadsheet
1396: Exec=gnumeric
1397: Icon=gnome-gnumeric.png
1398: Terminal=0
1399: Type=Application
1400: </programlisting>]]>
1401: </programlisting>
1402: which produces
1403: <programlisting>
1404: [Desktop Entry]
1405: Name=Gnumeric spreadsheet
1406: Exec=gnumeric
1407: Icon=gnome-gnumeric.png
1408: Terminal=0
1409: Type=Application
1410: </programlisting>
1411: As a matter of fact, all examples in this document were
1412: produced using <sgmltag><programlisting></sgmltag>.
1413: </para>
1414: <para>
1415: To show a record of terminal session—i.e., sequence of
1416: commands entered at the command line—use
1417: <sgmltag><screen></sgmltag> tag:
1418: <programlisting>
1419: <![CDATA[
1420: <screen>
1421: <prompt>bash$</prompt><userinput>make love</userinput>
1422: make: *** No rule to make target `love'. Stop.
1423: </screen>]]>
1424: </programlisting>
1425: which produces
1426: <screen>
1427: <prompt>bash$</prompt><userinput>make love</userinput>
1428: make: *** No rule to make target `love'. Stop.
1429: </screen>
1430: Note the use of tags <sgmltag><prompt></sgmltag> and
1431: <sgmltag><userinput></sgmltag> for marking system prompt
1432: and commands entered by user.
1433: <note>
1434: <title>NOTE</title>
1435: <para>
1436: Note that both <sgmltag><programlisting></sgmltag>
1437: and <sgmltag><screen></sgmltag> preserve linebreaks,
1438: but interpret SGML tags (unlike LaTeX
1439: <markup>verbatim</markup> environment). Take a look at
1440: the source of this document to see how you can have SGML
1441: tags literally shown but not interpreted,
1442: </para>
1443: </note>
1444: </para>
1445: </sect3>
1446: <sect3 id="lists">
1447: <title> Lists</title>
1448: <para>
1449: The most common list types in DocBook are
1450: <sgmltag><itemizedlist></sgmltag>,
1451: <sgmltag><orderedlist></sgmltag>, and
1452: <sgmltag><variablelist></sgmltag>.
1453: </para>
1454: <variablelist>
1455: <varlistentry>
1456: <term> <sgmltag><itemizedlist></sgmltag></term>
1457: <listitem><para>
1458: This is the simplest unnumbered list, parallel to
1459: <sgmltag><ul></sgmltag> in HTML. Here is an example:
1460: <programlisting>
1461: <![CDATA[
1462: <itemizedlist>
1463: <listitem>
1464: <para>
1465: <guilabel>Show backup files</guilabel> — This will
1466: show any backup file that might be on your system.
1467: </para>
1468: </listitem>
1469: <listitem>
1470: <para>
1471: <guilabel>Show hidden files</guilabel> — This will
1472: show all "dot files" or files that begin with a dot. This
1473: files typically include configuration files and directories.
1474: </para>
1475: </listitem>
1476: <listitem>
1477: <para>
1478: <guilabel>Mix files and directories</guilabel> — This
1479: option will display files and directories in the order you
1480: sort them instead of
1481: always having directories shown above files.
1482: </para>
1483: </listitem>
1484: </itemizedlist>
1485: ]]>
1486: </programlisting>
1487: and output:
1488: </para>
1489: <itemizedlist>
1490: <listitem>
1491: <para>
1492: <guilabel>Show backup files</guilabel> —
1493: This will show any backup file that might be on
1494: your system.
1495: </para>
1496: </listitem>
1497:
1498: <listitem>
1499: <para>
1500: <guilabel>Show hidden files</guilabel> —
1501: This will show all "dot files" or files that
1502: begin with a dot. This files typically include
1503: configuration files and directories.
1504: </para>
1505: </listitem>
1506:
1507: <listitem>
1508: <para>
1509: <guilabel>Mix files and directories</guilabel>
1510: — This option will display files and
1511: directories in the order you sort them instead
1512: of always having directories shown above files.
1513: </para>
1514: </listitem>
1515: </itemizedlist>
1516: <para> Note the use of <sgmltag>&mdash;</sgmltag>
1517: for long dash (see <xref linkend="specsymb" />). Also,
1518: please note that the result looks much nicer because the
1519: terms being explained (<guilabel>Show backup
1520: files</guilabel>, etc.) are set in a different font. In
1521: this case, it was achieved by using <link
1522: linkend="gui"><sgmltag><guilabel></sgmltag></link>
1523: tag. In other cases, use appropriate tags such as
1524: <link linkend="gui"><sgmltag><guimenuitem></sgmltag></link>,
1525: <link
1526: linkend="filenames"><sgmltag><command></sgmltag></link>,
1527: or — if none of
1528: this applies — use
1529: <link linkend="gui"><sgmltag><emphasis></sgmltag></link>.
1530: </para>
1531: </listitem>
1532: </varlistentry>
1533: <varlistentry>
1534: <term> <sgmltag><orderedlist></sgmltag></term>
1535: <listitem><para>
1536: This list is completely analogous to
1537: <sgmltag><itemizedlist></sgmltag> and has the same
1538: syntax, but it produces numbered list. By default,
1539: this list uses Arabic numerals for numbering entries;
1540: you can override this using <sgmltag>numeration</sgmltag>,
1541: for example <sgmltag><orderedlist
1542: numeration="lowerroman"></sgmltag>. Possible values of
1543: these attribute are <sgmltag>arabic</sgmltag>,
1544: <sgmltag>upperalpha</sgmltag>,
1545: <sgmltag>loweralpha</sgmltag>,
1546: <sgmltag>upperroman</sgmltag>,
1547: <sgmltag>lowerroman</sgmltag>.
1548: </para></listitem>
1549: </varlistentry>
1550:
1551: <varlistentry>
1552: <term> <sgmltag><variablelist></sgmltag></term>
1553: <listitem><para> This list is used when each entry is
1554: rather long, so it should be formatted as a block of text
1555: with some subtitle, like a small subsection. The
1556: <sgmltag><variablelist></sgmltag> is more complicated
1557: than itemizedlists, but for larger blocks of text, or when
1558: you're explaining or defining something, it's best to use
1559: them. Their greatest advantage is that it's easier for a
1560: computer to search. The lines you are reading now were
1561: produced by <sgmltag><variablelist></sgmltag>. The
1562: source looked liked this:
1563: <programlisting>
1564: <![CDATA[
1565: <variablelist>
1566: <varlistentry>
1567: <term> <sgmltag><itemizedlist></sgmltag></term>
1568: <listitem><para>
1569: This is the simplest unnumbered list, parallel to
1570: <sgmltag><ul></sgmltag> in HTML. Here is an example:...
1571: </para></listitem>
1572: </varlistentry>
1573: <varlistentry>
1574: <term> <sgmltag><orderedlist></sgmltag></term>
1575: <listitem><para>
1576: This list is completely analogous to
1577: <sgmltag><itemizedlist></sgmltag>
1578: </para></listitem>
1579: </varlistentry>
1580: <varlistentry>
1581: <term> <sgmltag><variablelist></sgmltag></term>
1582: <listitem><para>
1583: This list is used when each entry is rather long,...
1584: </para></listitem>
1585: </varlistentry>
1586: </variablelist>
1587: ]]>
1588: </programlisting>
1589: </para>
1590: </listitem>
1591: </varlistentry>
1592: </variablelist>
1593: <para>
1594: Lists can be nested; in this case, the stylesheets
1595: are smart enough to change the numeration (for
1596: <sgmltag><orderedlist></sgmltag>) or marks of each entry
1597: (in <sgmltag><itemizedlist></sgmltag>) for sub-lists
1598: </para>
1599: </sect3>
1600:
1601: </sect2>
1602:
1603: <!-- ####### DocBook Basics | Inline Elements ####### -->
1604:
1605: <sect2 id="inline">
1606: <title>Inline Elements</title>
1607:
1608: <sect3 id="gui">
1609: <title>GUI elements</title>
1610: <itemizedlist>
1611: <listitem>
1612: <para>
1613: <sgmltag><guibutton></sgmltag> — used for
1614: buttons, including checkbuttons and radio buttons
1615: </para>
1616: </listitem>
1617:
1618: <listitem>
1619: <para>
1620: <sgmltag><guimenu></sgmltag>,
1621: <sgmltag><guisubmenu></sgmltag> —used for
1622: top-level menus and submenus
1623: respectively, for example <literal><![CDATA[
1624: <guisubmenu>Utilities</guisubmenu> submenu of the
1625: <guimenu>Main Menu</guimenu>]]></literal>
1626: </para>
1627: </listitem>
1628:
1629: <listitem>
1630: <para>
1631: <sgmltag><guimenuitem></sgmltag>—an entry in a
1632: menu
1633: </para>
1634: </listitem>
1635:
1636: <listitem>
1637: <para>
1638: <sgmltag><guiicon></sgmltag>—an icon
1639: </para>
1640: </listitem>
1641:
1642: <listitem>
1643: <para>
1644: <sgmltag><guilabel></sgmltag>—for items which have
1645: labels, like tabs, or bounding boxes.
1646: </para>
1647: </listitem>
1648: <listitem>
1649: <para>
1650: <sgmltag><interface></sgmltag>— for most everything
1651: else... a window, a dialog box, the Panel, etc.
1652: </para>
1653: </listitem>
1654: </itemizedlist>
1655: <para>
1656: If you need to refer to a sequence of menu choices, such as
1657: <menuchoice>
1658: <guimenu>Main Menu</guimenu>
1659: <guisubmenu>Utilities</guisubmenu> <guimenuitem>GNOME
1660: terminal</guimenuitem>
1661: </menuchoice>
1662: there is a special construction for this, too:
1663: <programlisting>
1664: <![CDATA[
1665: <menuchoice>
1666: <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
1667: <guimenuitem>GNOME terminal</guimenuitem> </menuchoice>]]>
1668: </programlisting>
1669: </para>
1670: </sect3>
1671:
1672: <sect3 id="links">
1673: <title>Links and references</title>
1674: <para>
1675: To refer to another place in the same document, you can use
1676: tags <sgmltag><xref></sgmltag> and
1677: <sgmltag><link></sgmltag>. The first of them
1678: automatically inserts the full name of the element you refer
1679: to (section, figure, etc.), while the second just creates a
1680: link (in HTML output). Here is an example:
1681: <programlisting>
1682: <![CDATA[An example of a <link linkend="extip">tip</link> was given in
1683: <xref linkend="notes" />. ]]>
1684: </programlisting>
1685: which produces: An example of a <link
1686: linkend="extip">tip</link> was given in <xref
1687: linkend="notes" />.
1688: </para>
1689: <para>
1690: Here <sgmltag>notes</sgmltag> and <sgmltag>extip</sgmltag>
1691: are the id attributes of <xref linkend="notes" /> and of the
1692: example of a tip in it.
1693: </para>
1694: <para> To produce a link to an external source, such as a
1695: Web page or a local file, use <sgmltag><ulink></sgmltag>
1696: tag, for example:
1697: <programlisting>
1698: <![CDATA[ To find more about GNOME, please visit <ulink type="http"
1699: url="http://www.gnome.org">GNOME Web page</ulink> ]]>
1700: </programlisting>
1701: which produces: To find more about GNOME, please visit
1702: <ulink type="http" url="http://www.gnome.org">The GNOME Web
1703: Site</ulink> You can use any of the standard URL types, such
1704: as <literal>http, ftp, file, telnet, mailto</literal> (in
1705: most cases, however, use of <literal>mailto</literal> is
1706: unnecessary—see discussion of
1707: <sgmltag><email></sgmltag> tag).
1708: </para>
1709: </sect3>
1710:
1711: <sect3 id="filenames"> <title>Filenames, commands, and other
1712: computer-related things</title>
1713: <para>
1714: Here are some tags used to describe operating system-related
1715: things:
1716: </para>
1717: <itemizedlist>
1718: <listitem>
1719: <para> <sgmltag><filename></sgmltag> — used
1720: for filenames,
1721: e.g.<sgmltag><filename></sgmltag>
1722: foo.sgml
1723: <sgmltag></filename></sgmltag>
1724: produces: <filename>foo.sgml</filename>.
1725: </para>
1726: </listitem>
1727: <listitem>
1728: <para> <sgmltag><filename
1729: class="directory"></sgmltag> — used for
1730: directories, e.g.<sgmltag><filename
1731: class="directory"></sgmltag>/usr/bin
1732: <sgmltag></filename></sgmltag>
1733: produces: <filename
1734: class="directory">/usr/bin</filename>.
1735: </para>
1736: </listitem>
1737: <listitem>
1738: <para>
1739: <sgmltag><application></sgmltag> — used for
1740: application names,
1741: e.g. <sgmltag><application></sgmltag>Gnumeric
1742: <sgmltag></application></sgmltag> produces:
1743: <application>Gnumeric</application>.
1744: </para>
1745: </listitem>
1746: <listitem>
1747: <para>
1748: <sgmltag><envar></sgmltag> — used for
1749: environment variables, e.g.
1750: <sgmltag><envar></sgmltag>PATH<sgmltag></envar></sgmltag>.
1751: </para>
1752: </listitem>
1753:
1754: <listitem>
1755: <para>
1756: <sgmltag><command></sgmltag> — used for
1757: commands entered on command line, e.g.
1758: <sgmltag><command></sgmltag>make install
1759: <sgmltag></command></sgmltag> produces:
1760: <command>make install</command>.
1761: </para>
1762: </listitem>
1763: <listitem>
1764: <para>
1765: <sgmltag><replaceable></sgmltag> — used for
1766: replaceable text, e.g.
1767: <sgmltag><command></sgmltag>db2html<sgmltag><replaceable></sgmltag>
1768: foo.sgml
1769: <sgmltag></replaceable></sgmltag><sgmltag></command></sgmltag>
1770: produces: <command>db2html
1771: <replaceable>foo.sgml</replaceable></command>.
1772: </para>
1773: </listitem>
1774: </itemizedlist>
1775: </sect3>
1776:
1777: <sect3 id="keys">
1778: <title>Keyboard input</title>
1779: <para> To mark up text input by the user, use
1780: <sgmltag><userinput></sgmltag>.
1781: </para>
1782: <para> To mark keystrokes such as shortcuts and other
1783: commands, use <sgmltag><keycap></sgmltag>.
1784: This is used for marking up what is printed on the top
1785: of the physical key on the keyboard. There are a couple of
1786: other tags for keys, too: <sgmltag><keysym></sgmltag>
1787: and <sgmltag><keycode></sgmltag>. However you are
1788: unlikely to need these for most documentation. For reference,
1789: <sgmltag><keysym></sgmltag> is for the <quote>symbolic
1790: name</quote> of a key. <sgmltag><keycode></sgmltag> is
1791: for the <quote>scan code</quote> of a key. These are not
1792: terms commonly required in <acronym>GNOME</acronym> documentation,
1793: although <sgmltag><keysym></sgmltag> is useful for marking
1794: up control codes.
1795: </para>
1796: <para>
1797: To mark up a combination of keystrokes, use the
1798: <sgmltag><keycombo></sgmltag> wrapper:
1799: <programlisting>
1800: <![CDATA[
1801: <keycombo>
1802: <keycap>Ctrl</keycap>
1803: <keycap>Alt</keycap>
1804: <keycap>F1</keycap>
1805: </keycombo>]]>
1806: </programlisting>
1807: </para>
1808: <para>
1809: Finally, if you want to show a shortcut for some menu
1810: command, here are the appropriate tags (rather long):
1811: <programlisting>
1812: <![CDATA[
1813: <menuchoice>
1814: <shortcut>
1815: <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
1816: </shortcut>
1817: <guimenuitem> Quit</guimenuitem>
1818: </menuchoice>]]>
1819: </programlisting>
1820: which produces simply
1821: <menuchoice>
1822: <shortcut> <keysym>Ctrl-q</keysym> </shortcut>
1823: <guimenuitem> Quit</guimenuitem>
1824: </menuchoice>
1825: </para>
1826: </sect3>
1827:
1828: <sect3 id="email">
1829: <title>E-mail addresses</title> <para> To mark up e-mail
1830: address, use <sgmltag><email></sgmltag>:
1831: <programlisting>
1832: <![CDATA[ The easiest way to get in touch with me is by e-mail
1833: (<email>me@mydomain.com</email>)]]>
1834: </programlisting>
1835: which produces: The easiest way to get in touch with me is
1836: by e-mail (<email>me@mydomain.com</email>) Note that
1837: <sgmltag><email></sgmltag> automatically produces a link
1838: in html version.
1839: </para>
1840: </sect3>
1841:
1842: <sect3 id="specsymb">
1843: <title> Special symbols </title>
1844: <para>
1845: DocBook also provides special means for entering
1846: typographic symbols which can not be entered directly
1847: form the keyboard (such as copyright sign). This is done using
1848: <emphasis>entities</emphasis>, which is SGML analogue of
1849: macros, or commands, of LaTeX. They generally have the form
1850: <sgmltag>&entityname;</sgmltag>. Note that the semicolon
1851: is required.
1852: </para>
1853: <para>
1854: here is partial list of most commonly used enitites:
1855: </para>
1856: <itemizedlist>
1857: <listitem><para>
1858: <sgmltag>&amp;</sgmltag> — ampersend (&)
1859: </para></listitem>
1860: <listitem><para>
1861: <sgmltag>&lt;</sgmltag> — left angle bracket (<)
1862: </para></listitem>
1863: <listitem><para>
1864: <sgmltag>&copy;</sgmltag> — copyright sign (©)
1865: </para></listitem>
1866: <listitem><para>
1867: <sgmltag>&mdash;</sgmltag> — long dash (—)
1868: </para></listitem>
1869: <listitem><para>
1870: <sgmltag>&hellip;</sgmltag> — ellipsis (…)
1871: </para></listitem>
1872: </itemizedlist>
1873: <para>
1874: Note that the actual look of the resulting symbols depends
1875: on the fonts used by your browser; for example, it might
1876: happen that long dash (<sgmltag>&mdash;</sgmltag>) looks
1877: exactly like the usual dash (-). However, in the PostScript
1878: (and thus, in print) the output will look markedly better if
1879: you use appropriate tags.
1880: </para>
1881: </sect3>
1882: </sect2>
1883: </sect1>
1884:
1885: <!-- ################# GDP Documentation Conventions ############### -->
1886:
1887: <sect1 id="conventions">
1888: <title>GDP Documentation Conventions </title>
1889:
1890: <!-- ####### GDP Documentation Conventions | All Documentation ####### -->
1891:
1892: <sect2 id="conventionsalldocs">
1893: <title>Conventions for All GDP Documentation</title>
1894: <sect3 id="xmlcomp">
1895: <title> XML compatibility </title>
1896: <para>
1897: All GNOME documentation should conform to XML syntax
1898: requirements, which are stricter than SGML ones — see
1899: <xref linkend="xml" /> for more informaion.
1900: </para>
1901: </sect3>
1902:
1903: <sect3 id="authorsnames">
1904: <title> Authors' names</title>
1905: <para>
1906: All GNOME documentation should contain the names of both the
1907: application authors and documentation authors, as well as a
1908: link to the application web page (if it exists) and
1909: information for bug submission — see templates for an
1910: example.
1911: </para>
1912: </sect3>
1913: </sect2>
1914:
1915: <!-- ####### GDP Documentation Conventions | All Documentation ####### -->
1916:
1917: <sect2 id="conventionsappdocs">
1918: <title>Conventions for Application Documentation</title>
1919:
1920: <sect3 id="applicationversionid">
1921: <title>Application Version Identification</title>
1922: <para>
1923: Application documentation should identify the version of the
1924: application for which the documentation is written:
1925: <programlisting>
1926: <![CDATA[
1927: <sect1 id="intro">
1928: <title>Introduction</title>
1929: <para>
1930: blah-blah-blah This document describes version 1.0.53 of gfoo.
1931: </para>
1932: </sect1>]]>
1933: </programlisting>
1934: </para>
1935: </sect3>
1936: <sect3 id="license">
1937: <title> Copyright information </title>
1938: <para> Application
1939: documentation should contain a copyright notice, stating the
1940: licensing terms. It is suggested that you use the GNU Free
1941: Documentation License. You could also use some other license
1942: allowing free redistribution, such as GPL or Open Content
1943: license. If documentation uses some trademarks (such as UNIX,
1944: Linux, Windows, etc.), proper legal junk should also be
1945: included (see templates).
1946: </para>
1947: </sect3>
1948: <sect3 id="license2">
1949: <title>Software license</title>
1950: <para>
1951: All GNOME applications must contain information about the
1952: license (for software, not for documentation), either in the
1953: "About" box or in the manual.
1954: </para>
1955: </sect3>
1956:
1957: <sect3 id="bugtraq">
1958: <title> Bug reporting</title>
1959: <para>
1960: Application documentation should give an address for
1961: reporting bugs and for submitting comments about the
1962: documentaion (see templates for an example).
1963: </para>
1964: </sect3>
1965: </sect2>
1966: </sect1>
1967:
1968: <!-- ################# Writing Application Manuals ###############-->
1969:
1970: <sect1 id="writingapplicationmanuals">
1971: <title>Writing Application and Applet Manuals</title>
1972: <para>
1973: Every GNOME application or applet should have a manual specific
1974: to that particular application. This manual should be a complete
1975: and authoritative guide. The manual should describe what the
1976: program does and how to use it. Manuals will typically describe
1977: each window or panel presented to the user using screenshots (in
1978: PNG format only) when appropriate. They should also describe
1979: each feature and preference option available.
1980: </para>
1981: <note>
1982: <title>Documentation Availability</title>
1983: <para>
1984: Applications and applets should not rely on documentation
1985: which is only available on the internet. All manuals and
1986: other documentation should be packaged with the application or
1987: applet and be made available to the user through the standard
1988: GNOME help system methods described below.
1989: </para>
1990: </note>
1991: <para> Application manuals should be based on the template in
1992: <xref linkend="template1" />. Applet manuals should be based on
1993: the templates in <xref linkend="template2-1x" /> for GNOME
1994: versions 1.x and the templates in <xref linkend="template2-2x" />
1995: for GNOME versions 2.x.
1996: </para>
1997: <note>
1998: <title>Manuals For Large Applications</title>
1999: <para>
2000: Manuals for very large applications, such as GNOME Workshop
2001: components should be a <sgmltag><book></sgmltag> (and thus
2002: use <sgmltag><chapter></sgmltag> for each primary section)
2003: , instead of <sgmltag><article></sgmltag> which most
2004: applications use(with each primary section being a
2005: <sgmltag><sect1></sgmltag>).
2006: </para>
2007: </note>
2008: <note>
2009: <title>Applet Manuals in GNOME 2.0</title>
2010: <para>
2011: Note that applet manuals in GNOME 2.0 are treated in a special
2012: way. The manuals for all applets are merged into a single
2013: virtual document by Nautilus. For this reason, the header
2014: information for applet manuals is omitted and the first
2015: section of each applet is
2016: <sgmltag><sect1></sgmltag>. Applet manuals will typically
2017: have several sections, each of which is
2018: <sgmltag><sect2></sgmltag>.
2019: </para>
2020: </note>
2021: <para>
2022: Application manuals should be made available by having a
2023: "Manual" entry in the <guimenu>Help</guimenu> pull-down menu
2024: at the top of the
2025: application, as described in <xref linkend="listingdocsinhelpmenu" />.
2026: Applets should make their manuals available by
2027: right-clicking on the applet.
2028: </para>
2029: </sect1>
2030:
2031:
2032: <!-- ############### Listing Documents in the Help Menu ############# -->
2033:
2034: <sect1 id="listingdocsinhelpmenu">
2035: <title>Listing Documents in the Help Menu</title>
2036:
2037: <note>
2038: <title>Developer Information</title>
2039: <para>
2040: This section is for developers. Documentation authors
2041: generally do not need to know this material.
2042: </para>
2043: </note>
2044: <para>
2045: Typically the application manual and possibly additional help
2046: documents will be made available to the user under the
2047: <guimenu>Help</guimenu> menu at the top right of the
2048: application. To do this, you must first write a
2049: <filename>topic.dat</filename> file. The format for this file is:
2050: <programlisting>
2051: One line for each 'topic'.
2052:
2053: Two columns, as defined by perl -e 'split(/\s+/,$aline,2)'
2054:
2055: First column is the HTML file (and optional section) for the topic,
2056: relative to the app's help file dir.
2057:
2058: Second column is the user-visible topic name.
2059: </programlisting>
2060: For example, <application>Gnumeric</application>'s
2061: <filename>topic.dat</filename> file is:
2062: <programlisting>
2063: gnumeric.html Gnumeric manual
2064: function-reference.html Gnumeric function reference
2065: </programlisting>
2066: When the application is installed, the
2067: <filename>topic.dat</filename> file should be placed in the
2068: <filename
2069: class="directory">$prefix/share/gnome/help/<replaceable>appname</replaceable>/C/</filename> directory
2070: where <replaceable>appname</replaceable> is replaced by the
2071: application's name. The application documentation (converted
2072: from SGML into HTML with <command>db2html</command>) should be
2073: placed in this directory too.
2074: </para>
2075: <note>
2076: <para>
2077: If the help files are not present in the correct directory, the
2078: menu items will NOT appear when the program is run.
2079: </para>
2080: </note>
2081: <para>
2082: The <filename>topic.dat</filename> file is used by the GNOME
2083: menu building code to generate the <guimenu>Help</guimenu>
2084: menu. When you define your menu:
2085: <programlisting>
2086: GnomeUIInfo helpmenu[] = {
2087: {GNOME_APP_UI_ITEM,
2088: N_("About"), N_("Info about this program"),
2089: about_cb, NULL, NULL,
2090: GNOME_APP_PIXMAP_STOCK, GNOME_STOCK_MENU_ABOUT,
2091: 0, 0, NULL},
2092: GNOMEUIINFO_SEPARATOR,
2093: GNOMEUIINFO_HELP("<emphasis>appname</emphasis>"),
2094: GNOMEUIINFO_END
2095: };
2096: </programlisting>
2097: the line specifying <varname>GNOMEUIINFO_HELP</varname> causes
2098: GNOME to create a menu entry which is tied to the documentation
2099: in the directory mentioned above. Also, all the topics in the
2100: <filename>topic.dat</filename> file will get menu entries in the
2101: <guimenu>Help</guimenu> menu. When the user selects any of these
2102: topics from the <guimenu>Help</guimenu> menu, a help browser
2103: will be started with the associated HTML documentation.
2104: </para>
2105: </sect1>
2106:
2107:
2108: <!-- ################# Application Help Buttons ############### -->
2109:
2110: <sect1 id="applicationhelpbuttons">
2111: <title>Application Help Buttons</title>
2112:
2113: <note>
2114: <title>Developer Information</title>
2115: <para>
2116: This section is for developers. Documentation authors
2117: generally do not need to know this material.
2118: </para>
2119: </note>
2120: <para>
2121: Most GNOME applications will have <guibutton>Help</guibutton>
2122: buttons. These are most often seen in Preference windows. (All
2123: Preference windows should have <guibutton>Help</guibutton>
2124: buttons.) Most <guibutton>Help</guibutton> buttons will connect
2125: to the application manual, although some may connect to special
2126: documents. Because the <guibutton>Help</guibutton> buttons do
2127: not generally have their own special documentation, the
2128: documentation author(s) do not need to do very much. However,
2129: the application author must be careful to guarantee that the
2130: application correctly opens the help documentation when the
2131: <guibutton>Help</guibutton> buttons are pressed.
2132: </para>
2133: <para>
2134: To make the Help buttons call the correct document in the GNOME Help
2135: Browser the developer should add code based on the following example:
2136: </para>
2137: <programlisting>
2138: gchar *tmp;
2139: tmp = gnome_help_file_find_file ("module", "page.html");
2140: if (tmp) {
2141: gnome_help_goto(0, tmp);
2142: g_free(tmp);
2143: }
2144: </programlisting>
2145: <note>
2146: <title>NOTE</title>
2147: <para>
2148: The example above is in the C language, please refer to other
2149: documentation or forums for other GNOME language bindings.
2150: </para>
2151: </note>
2152: </sect1>
2153:
2154: <!-- ################# Packaging Applet Documentation ############### -->
2155:
2156: <sect1 id="packagingappletdocs">
2157: <title>Packaging Applet Documentation</title>
2158: <sect2 id="appletfiles">
2159: <title>Applet Documentation Files</title>
2160: <para>
2161: In GNOME 2.0 each applet will have its own documentation
2162: installed separately, and the GNOME 2.0 help
2163: browser (<application>Nautilus</application>) will dynamically
2164: merge the applet documents into a single virtual book
2165: called <citetitle>GNOME Applets</citetitle>. During the
2166: transitionary stage between GNOME 1.0 and GNOME 2.0, each
2167: applet in the gnome-applets package has its own manual(stored
2168: with the applet in CVS), but they are merged together manually
2169: to create the <citetitle>GNOME Applets</citetitle> book before
2170: distribution. Telsa
2171: <email>hobbit@aloss.ukuu.org.uk</email> is the maintainer of
2172: this document. Applet documentation should be sent to Telsa
2173: (or placed in CVS) who will make sure they are correctly
2174: packaged with the applets. The applet author should be
2175: contacted to modify the menu items and help buttons to bind to
2176: the applet documentation if necessary.
2177: </para>
2178: <para>
2179: Images which are part of the applet documentation should be in
2180: PNG format and should reside in the same directory as the SGML
2181: document file in CVS(gnome-applets/APPLETNAME/help/C).
2182: </para>
2183: <para>
2184: Applets which are not part of the gnome-applets package must
2185: package their documentation with the particular applet
2186: package. They should use the same applet template as other
2187: applets. However, the <sgmltag><xref></sgmltag> links to
2188: the introductory chapter of the <citetitle>GNOME
2189: Applets</citetitle> book must be removed (as the 1.x
2190: <application>GNOME Help Browser</application> does not allow
2191: you to create links between separate documents) and replaced
2192: with suitable text. Note that since this document is not part
2193: of the <citetitle>GNOME Applets</citetitle> book, you must
2194: remember to add <sgmltag><legalnotice></sgmltag> and
2195: <sgmltag><copyright></sgmltag> sections.
2196: </para>
2197: </sect2>
2198:
2199: <sect2 id="appletmenu">
2200: <title>Adding Documentation to an Applet Menu</title>
2201: <note>
2202: <title>Developer Information</title>
2203: <para>
2204: This section is for developers. Documentation authors
2205: generally do not need to know this material.
2206: </para>
2207: </note>
2208: <para>
2209: Applets should have <guimenu>About</guimenu> and
2210: <guimenu>Manual</guimenu> menu items, typically as the first
2211: and second top-most items in the menu respectively. This
2212: section describes how the developer creates these menu items
2213: and links them to the documentation.
2214: </para>
2215: <para>
2216: To add an applet's manual to its applet menu, use:
2217: <programlisting>
2218: /* add an item to the applet menu */
2219: applet_widget_register_callback(APPLET_WIDGET(applet), "manual",
2220: _("Manual"), &open_manual, NULL);
2221: </programlisting>
2222: Here the second argument is an arbitrary name for the
2223: callback, the third argument is the label which will appear
2224: when the user right clicks on the applet, and the fourth
2225: argument is the callback function.
2226: </para>
2227: <para>
2228: You will need to write a simple callback function to open the
2229: help browser to the appropriate document. This is done using
2230: the <function>gnome_help_file_find_file</function> function,
2231: as described in <xref linkend="applicationhelpbuttons" />.
2232: </para>
2233: <para>
2234: You will also want to add an <guimenu>About</guimenu> menu
2235: item to the applet's menu. This is a
2236: stock menu item and is done:
2237: <programlisting>
2238: applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about",
2239: GNOME_STOCK_MENU_ABOUT, _("About"), &my_applet_cb_about,
2240: NULL);
2241: </programlisting>
2242: </para>
2243: <para>
2244: More information can be found at <ulink type="http"
2245: url="http://developer.gnome.org/doc/tutorials/applet/index.html">Writing
2246: GNOME panel applets using the GTK+/GTK-- widget set</ulink>.
2247: </para>
2248: </sect2>
2249: </sect1>
2250:
2251:
2252: <!-- ################# Writing Context Sensitive Help ###############
2253: -->
2254:
2255: <sect1 id="writingcontextsensitivehelp">
2256: <title>Writing Context Sensitive Help (coming in GNOME-2.0)</title>
2257: <para>
2258: Context sensitive help, also known as "pop-up" help, will allow
2259: a user to obtain help information about specific buttons or
2260: parts of an application.
2261: </para>
2262: <para>
2263: Context sensitive help is still under development and not all
2264: the details are available at this time. However, the basics can
2265: be shown here so that you can understand how the system will
2266: work.
2267: </para>
2268: <para>
2269: The Context Sensitive Help system is designed to allow the
2270: developer to give an id to a particular portion of the User
2271: Interface, for example, a button. Once the interface is complete
2272: a Perl script can then be run against the interface code to
2273: create a "map" file. This map file allows the developer or
2274: writer to associate particular paragraph sections from an XML
2275: document to the interface items.
2276: </para>
2277: <para>
2278: The XML used for the document is a small XML DTD that is being
2279: developed to use the same tags (albeit, much fewer) as DocBook
2280: so that writers do not have to re-learn a new DTD.
2281: </para>
2282: <para>
2283: Once the document is written and map file is complete, when the
2284: user launches context sensitive help on the interface (either by
2285: pressing a button and then clicking on the interface item they
2286: want information on, or by right mouse clicking on the interface
2287: item and selecting a pop-up menu item like "What's This") a
2288: small transient window will appear with brief but detailed
2289: information on the interface item.
2290: </para>
2291: </sect1>
2292:
2293: <!-- ################# Referring to Other GNOME Documentation
2294: ############# -->
2295:
2296: <sect1 id="referring">
2297: <title>Referring to Other GNOME Documentation (coming in
2298: GNOME-2.0)</title>
2299: <para>
2300: In the GNOME 2.0 Help System, you will be able to create links
2301: from one document to another. The exact mechanism for doing
2302: this is in development.
2303: </para>
2304: </sect1>
2305:
2306:
2307: <!-- ################# Basics of Documentation Style ############### -->
2308:
2309: <sect1 id="basics">
2310: <title>Basics of Documentation Style</title>
2311: <para>
2312: Most people have never enjoyed reading a software manual, and
2313: they probably never will. Many times, they'll read the
2314: documentation only when they run into problems, and they'll be
2315: frustrated and upset before they even read a word. On the
2316: other hand, some readers will read the manual all the way
2317: through, or at least look at the introduction before they
2318: start. Your document might serve as a reference for an expert
2319: or a guide to a beginner, and it must have enough depth to
2320: satisfy the first without overwhelming the second. Ideally, it
2321: will serve beginners as they <emphasis>become</emphasis>
2322: experts. Remember, your goal is to produce <emphasis>complete,
2323: intuitive and clear</emphasis> documentation.
2324: </para>
2325: <para>
2326: In order to write useful documentation, you'll have to know who
2327: your audience is likely to be. Then, you can look for the
2328: problems they're likely to run into, and solve them. It will
2329: also help if you focus on the tasks users will perform, and
2330: group features accordingly, rather than simply describing
2331: features at random.
2332: </para>
2333:
2334: <!-- *********** Basics of Documentation Style: planning -->
2335:
2336: <sect2 id="styleplanning">
2337: <title>Planning</title>
2338: <para>
2339: Begin documenting by learning how to use the application and
2340: reading over any existing documentation. Pay attention to
2341: places where your document will differ from the template. It
2342: may help to develop a document skeleton: a valid XML or SGML
2343: document that has little or no content. For very large
2344: applications, you will need to make significant departures
2345: from the templates, since you'll be using the
2346: <sgmltag><book></sgmltag> tag instead of
2347: <sgmltag><chapter></sgmltag> or
2348: <sgmltag><article></sgmltag>.
2349: </para>
2350: </sect2>
2351:
2352:
2353: <!-- ####### Basics of Documentation Style | Balance ####### -->
2354: <sect2 id="balance">
2355: <title>Achieving a Balanced Style</title>
2356:
2357: <para>
2358: Just as you need to juggle expert and novice readers,
2359: you'll have to juggle a number of other extremes as you write:
2360: <itemizedlist>
2361: <listitem>
2362: <para>
2363: Documents should be complete, yet concise. You should
2364: describe every feature, but you'll have decide how much
2365: detail is really necessary. It's not, for example,
2366: necessary to describe every button and form field in a
2367: dialog box, but you should make sure that your readers
2368: know how to bring up the dialog and what it does. If
2369: you spend fewer words on the obvious, you can spend more
2370: time clarifying the ambiguous labels and explaining
2371: items that are more complex.
2372: </para>
2373: </listitem>
2374: <listitem>
2375: <para>
2376: Be engaging and friendly, yet professional. Games
2377: documents may be less formal than productivity
2378: application documents (people don't
2379: <emphasis>use</emphasis> games, they
2380: <emphasis>play</emphasis> them), but all of them should
2381: maintain a standard of style which holds the reader's
2382: interest without resorting to jokes and untranslatable
2383: allusions or puns.
2384: </para>
2385: </listitem>
2386:
2387: <listitem>
2388: <para>
2389: Examples, tips, notes, and screenshots are useful to
2390: break up long stretches of text, but too many can get in
2391: the way, and make your documents too choppy to read.
2392: It's good to provide a screenshot of any dialog windows
2393: a user might run into, but if a dialog box has several
2394: tabs, it's not usually necessary to have one for each.
2395: </para>
2396: </listitem>
2397:
2398: <listitem>
2399: <para>
2400: The GDP strives to have all of its documentation conform
2401: to certain standards of style and content, but every
2402: document (and every writer) is different. You will need
2403: to use your judgement, and write documents to fit with
2404: the rest of the project, without compromising the
2405: individual needs of your subject, or your own
2406: individuality as a writer.
2407: </para>
2408: </listitem>
2409:
2410: </itemizedlist>
2411: </para>
2412: </sect2>
2413:
2414:
2415: <!-- ####### Basics of Documentation Style | Structure ####### -->
2416:
2417: <sect2 id="stylestructure">
2418: <title>Structure</title>
2419: <para>
2420: In general, you won't have to worry too much about structure,
2421: because the templates provide you with an excellent example.
2422: As a general rule, try to follow that structural example.
2423: That means using links, hierarchical nesting, and, if
2424: necessary, a glossary or index. You probably won't need to
2425: use every available structural tag, but take advantage of
2426: what DocBook provides you.
2427: </para>
2428: <para>
2429: As to linking, there's some disagreement about whether to use
2430: <sgmltag><xref></sgmltag> <sgmltag><link></sgmltag>
2431: when you make links within your documents. You'll have to
2432: decide, based on the different ways that they are presented
2433: in output, which is more appropriate given the context.
2434: Regardless of which you use, you should not forget to use
2435: them. Help your readers find information that relevant to
2436: the issue at hand.
2437: </para>
2438: <para>
2439: The table of contents will be generated automatically, but
2440: you will probably have to develop your own index if you wish
2441: to have one. The Nautilus Help Browser will have new, and
2442: currently unknown, indexing capabilities, so index style and
2443: structure are still under discussion. The GNOME User's Guide
2444: will contain a glossary in its next versions; unless you're
2445: writing a<sgmltag><book></sgmltag>, it will probably be best to
2446: contribute to that rather than developing your own.
2447: </para>
2448: </sect2>
2449: <!-- ####### Basics of Documentation Style | Grammar & Spelling ####### -->
2450:
2451: <sect2 id="stylegrammar">
2452: <title>Grammar and Spelling</title>
2453: <para>
2454: Nobody expects you to be perfect; they just expect the
2455: documentation for their software to be error-free. That means
2456: that, in the same way that developers look for bugs and accept
2457: bug reports, writers must check for errors in their documents.
2458: Poor grammar, bad spelling, and gross technical errors in
2459: draft documents are fine. However, if those problems show up
2460: in a "real" release, they can count against the credibility of
2461: GNOME and Linux. They'll also make you look bad.
2462: </para>
2463: <para>
2464: There is no substitute for a human proofreader; use a
2465: spell-check program, then read it over yourself, and then find
2466: someone else to help you. Other GDP members are, of course,
2467: willing and able to help you, but non-writers are often at
2468: least as helpful.
2469: </para>
2470: <para>
2471: Proofreading documents is both a also a good way to
2472: familiarize yourself with documentation, and it certainly
2473: makes you valuable to the GDP. Help other writers proof their
2474: documents, and they will help you with yours.
2475: </para>
2476: </sect2>
2477: </sect1>
2478:
2479: <!-- ################# Teamwork ############### -->
2480:
2481: <sect1 id="teamwork">
2482: <title>Teamwork</title> <!-- ####### Teamwork | Working With The
2483: GDP Team ####### -->
2484:
2485: <sect2 id="teamworkgdp">
2486: <title>Working With The GDP Team</title>
2487: <para>
2488: The GDP team is a valuable resource for any documentation
2489: author. GDP members can answer most questions documentation
2490: authors have during the course of their work. It is also
2491: important to make sure you are not duplicating work of other
2492: GDP members by visiting the <citetitle>GDP Documentation
2493: Status Table</citetitle> (<ulink
2494: url="http://www.gnome.org/gdp/doctable/"
2495: type="http">http://www.gnome.org/gdp/doctable/</ulink>) and
2496: assigning a documentation item to yourself. This table also
2497: provides a forum for making suggestions and announcements for
2498: each documentation item. The best way to get in touch with
2499: GDP members is on the #docs IRC channel at irc.gnome.org or
2500: else by emailing the <ulink type="http"
2501: url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
2502: <citetitle>gnome-doc-list mailing list</citetitle></ulink>.
2503: </para>
2504: <para>
2505: After an author has finished a document (or even a draft
2506: version of the document), it is a good idea to ask a member of
2507: the GDP team to read the document, checking it for grammar,
2508: proper DocBook markup, and clarity. One may typically find
2509: another author to do this by either asking on the #docs IRC
2510: channel at irc.gnome.org or by emailing the <ulink type="http"
2511: url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
2512: <citetitle>gnome-doc-list mailing list</citetitle></ulink>.
2513: </para>
2514: </sect2>
2515:
2516: <!-- ####### Teamwork | Working With Developers ####### -->
2517:
2518: <sect2 id="teamworkdevelopers">
2519: <title>Working With Developers</title>
2520: <para>
2521: Writing documentation typically involves a certain amount of
2522: interaction with the developers of GNOME or the application
2523: which is being documented. Often a document author will need
2524: to ask the developer technical questions during the course of
2525: writing a document. After the document is finished, it is good
2526: idea to ask the developer to read the document to make sure it
2527: is technically correct. The documentation author should also
2528: make sure that the application author correctly binds and
2529: packages the documentation with the application.
2530: </para>
2531: </sect2>
2532:
2533: <!-- ####### Teamwork | Working With Users #######
2534:
2535: <sect2 id="teamworkusers">
2536: <title>Working With Users</title>
2537: <para>
2538: Some document authors may wish to get feedback on their
2539: documents directly from users. This may be done by ...
2540: </para>
2541: </sect2>-->
2542: </sect1>
2543:
2544: <!-- ################# Finishing a Document ############### -->
2545:
2546: <sect1 id="finishing">
2547: <title>Finishing A Document</title>
2548:
2549: <!-- ####### Finishing a Document | Editting the Document ####### -->
2550:
2551: <sect2 id="editting">
2552: <title>Editing The Document</title>
2553: <para>
2554: When the document is finished, the document should be edited
2555: by another member of the GDP for spelling, clarity, and
2556: DocBook markup. It should also be read by an application
2557: author to make sure the document is technically accurate.
2558: </para>
2559: </sect2>
2560:
2561: <!-- ####### Finishing a Document | Submitting the Document ####### -->
2562:
2563: <sect2 id="submitting">
2564: <title>Submitting The Document</title>
2565: <para>
2566: After the document has been edited and checked for technical
2567: accuracy, it is ready to be combined with the application or
2568: documentation package. This is typically done by passing the
2569: document to the application or package developer. In some
2570: cases, the documents can be committed directly into CVS,
2571: however this should only be done after obtaining permission to
2572: make CVS commits from the developer. Note that in many cases,
2573: the application may need to be modified to correctly link to
2574: the documentation. The packaging system (tarballs and binary
2575: packages) may also need to be modified to include the
2576: documentation in the package. Generally, this should be done
2577: by the developers.
2578: </para>
2579: <para>
2580: The final step is to email the GNOME Translation Team at
2581: <email>gnome-i18n@nuclecu.unam.mx</email> to notify them that
2582: there is a new document for them to translate.
2583: </para>
2584: </sect2>
2585: </sect1>
2586:
2587: <!-- ################# Resources ############### -->
2588:
2589: <sect1 id="resources">
2590: <title>Resources</title>
2591: <!-- ####### Resources | Resources on the Web ####### -->
2592:
2593: <sect2 id="resourcesweb">
2594: <title>Resources On The Web</title> <para> The <ulink
2595: type="http" url="http://developer.gnome.org/projects/gdp/">GNOME
2596: Documentation Project Web page</ulink> lists current GDP
2597: projects and members.
2598: </para>
2599: <para>
2600: The <ulink url="http://www.gnome.org/gdp/doctable/"
2601: type="http">GDP Documentation Status Table</ulink> tracks the
2602: status of all the various documentation components of GNOME.
2603: </para>
2604: <para>
2605: Norman Walsh's <ulink url="http://www.docbook.org"
2606: type="http"> <citetitle>DocBook: The Definitive
2607: Guide</citetitle></ulink> in an excellent book on DocBook,
2608: available both online and in print.
2609: </para>
2610: </sect2>
2611:
2612: <!-- ####### Resources | Books ####### -->
2613:
2614: <sect2 id="resourcesbooks">
2615: <title>Books</title>
2616: <para>
2617: Docbook: The Definitive Guide is available in both printed
2618: form and on the web at:
2619: <ulink url="http://www.docbook.org/tdg/index.html">
2620: <citetitle>Docbook: The Definitive Guide</citetitle>
2621: </ulink>
2622: </para>
2623: </sect2>
2624:
2625: <!-- ####### Resources | Mailing Lists ####### -->
2626:
2627: <sect2 id="mailinglists">
2628: <title>Mailing Lists</title>
2629: <para>
2630: The <emphasis>gnome-docs-list</emphasis> mailing list is the
2631: main discussion area for all contributors to the GNOME
2632: Documentation Project. You can find out how to subscribe to
2633: this list on <ulink
2634: url="http://www.gnome.org/resources/mailing-lists.html"
2635: type="http">GNOME Mailing Lists</ulink>. This is a rather
2636: low-volume list, so you will not be flooded with messages.
2637: </para>
2638: </sect2>
2639:
2640: <!-- ####### Resources | IRC ####### -->
2641:
2642: <sect2 id="irc">
2643: <title>IRC</title>
2644: <para>
2645: Internet Relay Chat (IRC) is a fast and easy way to get in
2646: touch with other GDP members. There are generally at least a
2647: few members here who can answer questions or discuss
2648: documentation issues. The IRC channel is #docs at
2649: irc.gnome.org.
2650: </para>
2651: </sect2>
2652: </sect1>
2653:
2654: <!-- ################# Example Docs ###############
2655:
2656: <appendix id="exampledocs">
2657: <title>Example Docs</title>
2658:
2659: ####### Example Docs | Example 1: Application Manual #######
2660:
2661: <sect1 id="ex1">
2662: <title>Example 1: Application Manual</title>
2663: <programlisting>
2664: <![CDATA[ (Put sgml here.)]]> </programlisting>
2665: </sect1>
2666:
2667: ####### Example Docs | Example 2: Applet Manual #######
2668:
2669: <sect1 id="ex2">
2670: <title>Example 2: Applet Manual</title>
2671: <programlisting>
2672: <![CDATA[(Put sgml here.)]]> </programlisting>
2673: </sect1>
2674:
2675: ##### Example Docs | Example 3: Application Context Sensitive Help ####
2676:
2677: <sect1 id="ex3">
2678: <title>Example 3: Application Context Sensitive Help</title>
2679: <programlisting>
2680: <![CDATA[(Put sgml here.)]]> </programlisting>
2681: </sect1>
2682:
2683: ####### Example Docs | Example 4: Complete Application: gnome-hello #######
2684:
2685: <sect1 id="ex4">
2686: <title>Example 4: Complete Application: gnome-hello</title>
2687: <programlisting>
2688: <![CDATA[(Put sgml here.)]]> </programlisting>
2689: </sect1>
2690:
2691: ####### Example Docs | Example 5: Tutorial #######
2692:
2693: <sect1 id="ex5">
2694: <title>Example 5: Tutorial</title>
2695: <programlisting>
2696: <![CDATA[(Put sgml here.)]]> </programlisting>
2697: </sect1>
2698: </appendix>-->
2699:
2700: <!-- ################# Document Templates ############### -->
2701:
2702: <appendix id="templates">
2703: <title>Document Templates</title>
2704: <!-- ####### Document Templates | Templates 1: Application Manual ####### -->
2705:
2706: <sect1 id="template1">
2707: <title>Template 1: Application Manual</title>
2708: <para>
2709: The following template should be used for all application
2710: manuals. You can always get the latest copy of this
2711: template from <ulink type="http"
2712: url="http://developer.gnome.org/projects/gdp/templates.html">GDP
2713: Documentation Templates</ulink>.
2714: <programlisting>
2715:
2716: <![CDATA[
2717: <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
2718: <!-- if not using PNG graphic, replace reference above with
2719: .....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
2720: -->
2721: <!ENTITY version "1.0.53">
2722: <!-- replace version above with actual application version number-->
2723: <!-- Template Version: 1.0.1 (do not remove this line) -->
2724: ]>
2725:
2726:
2727: <!-- This is a GNOME documentation template, designed by the GNOME
2728: Documentation Project Team. Please use it for writing GNOME
2729: documentation, making obvious changes. In particular, all the words
2730: written in UPPERCASE (with the exception of GNOME) should be
2731: replaced. As for "legalnotice", please leave the reference
2732: unchanged.
2733:
2734: Remember that this is a guide, rather than a perfect model to follow
2735: slavishly. Make your manual logical and readable. And don't forget
2736: to remove these comments in your final documentation! ;-)
2737: -->
2738:
2739: <!-- =============Document Header ============================= -->
2740:
2741: <article id="index"> <!-- please do not change the id -->
2742:
2743: <artheader>
2744: <title>MY-GNOME-APP</title>
2745: <copyright>
2746: <year>2000</year>
2747: <holder>ME-THE-AUTHOR</holder>
2748: </copyright>
2749:
2750: <!-- translators: uncomment this:
2751:
2752: <copyright>
2753: <year>2000</year>
2754: <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
2755: </copyright>
2756:
2757: -->
2758:
2759: <!-- do not put authorname in the header except in copyright - use
2760: section "authors" below -->
2761:
2762: <legalnotice>
2763: <para>
2764: Permission is granted to copy, distribute and/or modify this
2765: document under the terms of the <citetitle>GNU Free
2766: Documentation License</citetitle>, Version 1.1 or any later
2767: version published by the Free Software Foundation with no
2768: Invariant Sections, no Front-Cover Texts, and no Back-Cover
2769: Texts. You may obtain a copy of the <citetitle>GNU Free
2770: Documentation License</citetitle> from the Free Software
2771: Foundation by visiting <ulink type="http"
2772: url="http://www.fsf.org">their Web site</ulink> or by writing
2773: to: Free Software Foundation, Inc., 59 Temple Place - Suite
2774: 330, Boston, MA 02111-1307, USA.
2775: </para>
2776: <para>
2777: Many of the names used by companies to distinguish their
2778: products and services are claimed as trademarks. Where those
2779: names appear in any GNOME documentation, and those trademarks
2780: are made aware to the members of the GNOME Documentation
2781: Project, the names have been printed in caps or initial caps.
2782: </para>
2783: </legalnotice>
2784:
2785: <!-- this is the version of manual, not application -->
2786: <releaseinfo>
2787: This is version 1.0 of MY-GNOME-APP manual.
2788: </releaseinfo>
2789:
2790: </artheader>
2791:
2792: <!-- ============= Document Body ============================= -->
2793:
2794: <!-- ============= Introduction ============================== -->
2795: <sect1 id="intro">
2796: <title>Introduction</title>
2797:
2798: <para>
2799: <application>MY-GNOME-APP</application> is an application which
2800: proves mathematical theorems. It has all the basic features
2801: expected from a mathematical theorem prover, as well as a number
2802: of advanced ones, such as proof by confusion. In fact, many of
2803: the proofs produced by <application>MY-GNOME-APP</application>
2804: are so complex that they are capable of proving almost anything
2805: with a virtually null likelihood of being disproven. It also has
2806: the very popular predecessor of proof by confusion, proof by
2807: dialog, first implemented by Plato.
2808: </para>
2809: <para>
2810: It also allows you to save and print theorem proofs and to add
2811: comments to the proofs it produces.
2812: </para>
2813:
2814: <para>
2815: To run <application>MY-GNOME-APP</application>, select
2816: <menuchoice>
2817: <guisubmenu>SUBMENU</guisubmenu>
2818: <guimenuitem>MY-GNOME-APP</guimenuitem>
2819: </menuchoice>
2820: from the <guimenu>Main Menu</guimenu>, or type
2821: <command>MYGNOMEAPP</command> on the command line.
2822: </para>
2823:
2824: <para>
2825: <application>MY-GNOME-APP</application> is included in the
2826: <filename>GNOME-PACKAGE</filename> package, which is part of the
2827: GNOME desktop environment. This document describes version
2828: &version; of <application>MY-GNOME-APP</application>.
2829: </para>
2830: </sect1>
2831:
2832:
2833: <!-- ================ Usage ================================ -->
2834: <!-- This section should describe basic usage of the application. -->
2835:
2836: <sect1 id="usage">
2837: <title>Using MY-GNOME-APP</title>
2838: <para>
2839: <application>MY-GNOME-APP</application> can be used to produce a
2840: perfect proof of <emphasis>any</emphasis> mathematical theorem
2841: (provided, of course, that this theorem is correct), thus
2842: providing for new users an easy-to-use graphical interface to
2843: modern mathematics. This section describes basic usage of
2844: <application>MY-GNOME-APP</application>.
2845: </para>
2846:
2847: <!-- ========= Basic Usage =========================== -->
2848: <sect2 id="mainwin">
2849: <title>Basic usage</title>
2850: <para>
2851: Starting <application>MY-GNOME-APP</application> opens the
2852: <interface>Main window</interface>, shown in <xref
2853: linkend="mainwindow-fig">. The window is at first empty.
2854:
2855: <!-- ==== Figure ==== -->
2856: <figure id="mainwindow-fig">
2857: <title>MY-GNOME-APP Main Window</title>
2858: <screenshot>
2859: <screeninfo>MY-GNOME-APP Main Window</screeninfo>
2860: <graphic fileref="SCREENSHOT" format="png" srccredit="ME">
2861: </graphic>
2862: </screenshot>
2863: </figure>
2864: <!-- ==== End of Figure ==== -->
2865: </para>
2866:
2867:
2868: <!-- For this app, one could put "proving" or "edit" (probably even
2869: both of them) as sect2's seperate from the main window
2870: section. Since they were both so closely involved with the main
2871: window, I decided to have them as sect3's isntead. Judgement
2872: call. -->
2873:
2874: <sect3 id="proving">
2875: <title>Proving a Theorem</title>
2876: <para>
2877: To get a proof of a theorem, select
2878: <menuchoice>
2879: <guisubmenu>File</guisubmenu>
2880: <guimenuitem>New</guimenuitem>
2881: </menuchoice>,
2882: which will
2883: bring up the <interface>New Proof</interface> dialog box.
2884: Enter the statement of the theorem in the
2885: <guilabel>Theorem statement</guilabel> field, select your
2886: desired proof type from the drop-down menu, and and press
2887: <guibutton>Prove!</guibutton>.
2888: </para>
2889: <para>
2890: If <application>MY-GNOME-APP</application> cannot prove the
2891: theorem by the method you have chosen, or if you have not
2892: selected a proof type at all,
2893: <application>MY-GNOME-APP</application> will attempt to
2894: choose the one that it thinks is most conclusive. In order,
2895: it will attempt to prove the theorem with the following techniques:
2896:
2897: <variablelist>
2898: <varlistentry>
2899: <term>Deduction</term>
2900: <listitem>
2901: <para>
2902: This is a proof method that is generally accepted
2903: for full credit by Logic professors.
2904: </para>
2905: </listitem>
2906: </varlistentry>
2907: <varlistentry>
2908: <term>Induction</term>
2909: <listitem>
2910: <para>
2911: This logical style will also earn you full credit on
2912: your homework.
2913: </para>
2914: </listitem>
2915: </varlistentry>
2916: <varlistentry>
2917: <term>Dialog</term>
2918: <listitem>
2919: <para>
2920: This logical method is best for Philosophy classes,
2921: and will probably only merit partial credit on Logic
2922: or Mathematics homework.
2923: </para>
2924: </listitem>
2925: </varlistentry>
2926: <varlistentry>
2927: <term>Confusion</term>
2928: <listitem>
2929: <para>
2930: Suitable only for political debates, battles of wits
2931: against the unarmed, and Philosophy classes focusing
2932: on the works of Kant. Use with caution.
2933: </para>
2934: </listitem>
2935: </varlistentry>
2936: </variablelist>
2937: </para>
2938:
2939: <!-- You might want to include a note, warning, or tip, e.g. -->
2940:
2941: <warning>
2942: <title>Proving Incorrect Theorms</title>
2943: <para>
2944: <application>MY-GNOME-APP</application> cannot prove
2945: incorrect theorems. If the theorem you have entered is not
2946: demonstrably true, you will get a message to that effect
2947: in the main window. To disprove a theorem, ask
2948: <application>MY-GNOME-APP</application> to prove its
2949: logical inverse.
2950: </para>
2951: </warning>
2952: </sect3>
2953: <sect3 id="editing">
2954: <title>Editing Proofs</title>
2955: <para>
2956: Once you have proven the theorem, it will be displayed in
2957: the <interface>main window</interface>. There, you can read
2958: it over, choose text styles for different portions of it,
2959: and make comments on it. This section will guide you through
2960: that process.
2961: </para>
2962: <para>
2963: To alter text styles, first select the statement you wish to
2964: change by clicking on it once. You can select several
2965: statements by Then, choose the style you want to apply from
2966: the <guisubmenu>Style</guisubmenu> submenu of the
2967: <guimenu>Edit</guimenu> menu.
2968: <application>MY-GNOME-APP</application> will convert the
2969: text to that style.
2970: </para>
2971: <para>
2972: You can also enter comments on a statement by selecting that
2973: statement, and then beginning to type. Comments will appear
2974: after the statement you have selected.
2975: </para>
2976:
2977: <note>
2978: <title>Altering The Proofs Themselves</title>
2979: <para>
2980: <application>MY-GNOME-APP</application> does not allow you
2981: to alter a proof it has produced itself. You can, save
2982: your proof as a plain text file (using the
2983: <guimenuitem>Save as...</guimenuitem> menu), and alter it
2984: that way. Be aware, however, that
2985: <application>MY-GNOME-APP</application> uses its own file
2986: format for saved proofs, and cannot re-open a file unless
2987: it is in the .mga format.
2988: </para>
2989: </note>
2990: </sect3>
2991:
2992:
2993: <!-- If there are other functions performed from the main window,
2994: they belong here. -->
2995:
2996: </sect2>
2997:
2998: <!-- =========================================================
2999: Additional Sect2's should describe additional windows, such as
3000: larger dialog boxes, or functionality that differs significantly
3001: from the most immediate functions of the application. Make the
3002: structure logical.
3003: ============================================================= -->
3004:
3005:
3006: <sect2 id="toolbar">
3007: <title>Toolbar</title>
3008: <para>
3009: The toolbar (shown in <xref linkend="figure-usage-toolbar">)
3010: provides access to several commonly used routines.
3011: <figure id="figure-usage-toolbar">
3012: <title>MY-GNOME-APP Toolbar</title>
3013: <screenshot>
3014: <screeninfo>MY-GNOME-APP Toolbar</screeninfo>
3015: <graphic fileref="usage-toolbar.png" format="png"></graphic>
3016: </screenshot>
3017: </figure>
3018: <variablelist>
3019: <varlistentry>
3020: <term>New</term>
3021: <listitem>
3022: <para>
3023: Brings up the <interface>New Theorem</interface>
3024: dialog.
3025: </para>
3026: </listitem>
3027: </varlistentry>
3028: <varlistentry>
3029: <term>Open</term>
3030: <listitem>
3031: <para>
3032: Open an exisiting theorem you want to prove, or a
3033: completed proof you wish to print or format.
3034: </para>
3035: </listitem>
3036: </varlistentry>
3037: <varlistentry>
3038: <term>Save</term>
3039: <listitem>
3040: <para>
3041: Save the current theorem permanently in a
3042: file.
3043: </para>
3044: </listitem>
3045: </varlistentry>
3046: </variablelist>
3047: </para>
3048: </sect2>
3049: <!-- ========= Menus =========================== -->
3050:
3051: <sect2 id="menubar">
3052:
3053: <!-- Describing the menubar ensures comprehensive feature
3054: coverage. Nest itemizedlists inside variablelists so that each
3055: menu is easily located by indexing software. Proper indentation
3056: makes it easier! -->
3057:
3058: <title>Menus</title>
3059: <para>
3060: The menu bar, located at the top of the <interface>Main
3061: Window</interface>, contains the following menus:
3062: </para>
3063: <variablelist>
3064: <varlistentry>
3065: <term><guimenu>File</guimenu></term>
3066: <listitem>
3067: <para>
3068: This menu contains:
3069: <itemizedlist>
3070: <listitem>
3071: <para>
3072: <menuchoice>
3073: <shortcut>
3074: <keycap>F3</keycap>
3075: </shortcut>
3076: <guimenuitem>Open</guimenuitem>
3077: </menuchoice>
3078: — This opens a file which is saved on your computer.
3079: </para>
3080: </listitem>
3081: <listitem>
3082: <para>
3083: <menuchoice>
3084: <shortcut>
3085: <keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
3086: </shortcut>
3087: <guimenuitem>Save</guimenuitem>
3088: </menuchoice>
3089: — This saves your file.
3090: </para>
3091: </listitem>
3092: <listitem>
3093: <para>
3094: <menuchoice>
3095: <shortcut>
3096: <keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo>
3097: </shortcut>
3098: <guimenuitem>Close</guimenuitem>
3099: </menuchoice>
3100: — This closes your file.
3101: </para>
3102: </listitem>
3103: <listitem>
3104: <para>
3105: <menuchoice>
3106: <shortcut>
3107: <keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
3108: </shortcut>
3109: <guimenuitem>Exit</guimenuitem>
3110: </menuchoice>
3111: — This quits the application.
3112: </para>
3113: </listitem>
3114: </itemizedlist>
3115: </para>
3116: </listitem>
3117: </varlistentry>
3118:
3119: <varlistentry>
3120: <term><guimenu>Edit</guimenu></term>
3121: <listitem>
3122: <para>
3123: This menu contains:
3124: <itemizedlist>
3125: <listitem>
3126: <para>
3127: <menuchoice>
3128: <shortcut>
3129: <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo>
3130: </shortcut>
3131: <guimenuitem>Cut</guimenuitem>
3132: </menuchoice>
3133: — This removes any text or data which is selected and
3134: places it in the buffer.
3135: </para>
3136: </listitem>
3137: <listitem>
3138: <para>
3139: <menuchoice>
3140: <shortcut>
3141: <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
3142: </shortcut>
3143: <guimenuitem>Copy</guimenuitem>
3144: </menuchoice>
3145: — This copies any text or data which is selected into
3146: the buffer.
3147: </para>
3148: </listitem>
3149: <listitem>
3150: <para>
3151: <menuchoice>
3152: <shortcut>
3153: <keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo>
3154: </shortcut>
3155: <guimenuitem>Paste</guimenuitem>
3156: </menuchoice>
3157: — This pastes any text or data which is copied into
3158: the buffer.
3159: </para>
3160: </listitem>
3161: <listitem>
3162: <para>
3163: <guimenuitem>COMMAND1…</guimenuitem>
3164: — This opens the <interface>COMMAND1</interface>
3165: dialog, which is used to ....
3166: </para>
3167: </listitem>
3168: <listitem>
3169: <para>
3170: <guimenuitem>COMMAND2</guimenuitem>
3171: — This ....
3172: </para>
3173: </listitem>
3174: </itemizedlist>
3175: </para>
3176: </listitem>
3177: </varlistentry>
3178:
3179:
3180: <varlistentry>
3181: <term><guimenu>Settings</guimenu></term>
3182: <listitem>
3183: <para>
3184: This menu contains:
3185: <itemizedlist>
3186: <listitem>
3187: <para>
3188: <guimenuitem>Preferences…</guimenuitem>
3189: — This opens the <link
3190: linkend="prefs"><interface>Preferences
3191: Dialog</interface></link>, which allows you to configure
3192: many settings.
3193: </para>
3194: </listitem>
3195: <listitem>
3196: <para>
3197: <guimenuitem>COMMAND3</guimenuitem> —
3198: This command does something.
3199: </para>
3200: </listitem>
3201: </itemizedlist>
3202: </para>
3203: </listitem>
3204: </varlistentry>
3205:
3206: <varlistentry>
3207: <term><guimenu>Help</guimenu></term>
3208: <listitem>
3209: <para>
3210: This menu contains:
3211: <itemizedlist>
3212: <listitem>
3213: <para>
3214: <guimenuitem>Manual</guimenuitem> — This
3215: opens the <application>GNOME Help
3216: Browser</application> and displays this manual.
3217: </para>
3218: </listitem>
3219:
3220: <listitem>
3221: <para>
3222: <guimenuitem>About</guimenuitem> — This
3223: opens the <interface>About</interface> dialog
3224: which shows basic information about
3225: <application>MY-GNOME-APP</application>, such as
3226: the author's name, the application version number,
3227: and the URL for the application's Web page if one
3228: exists.
3229: </para>
3230: </listitem>
3231: </itemizedlist>
3232: </para>
3233: </listitem>
3234: </varlistentry>
3235: </variablelist>
3236: </sect2>
3237: </sect1>
3238:
3239:
3240:
3241: <!-- ============= Customization ============================= -->
3242:
3243: <sect1 id="prefs">
3244: <title>Customization</title>
3245: <para>
3246: To change the application settings, select
3247: <menuchoice>
3248: <guimenu>Settings</guimenu>
3249: <guimenuitem>Preferences...</guimenuitem>
3250: </menuchoice>. This opens the
3251: <interface>Preferences</interface> dialog, shown in <xref
3252: linkend="preferences-fig">.
3253: </para>
3254:
3255: <figure id="preferences-fig">
3256: <title>Preferences Dialog</title>
3257: <screenshot>
3258: <screeninfo>Preferences Dialog</screeninfo>
3259: <graphic fileref="SCREENSHOT" format="png"
3260: srccredit="ME">
3261: </graphic>
3262: </screenshot>
3263: </figure>
3264:
3265: <para>
3266: The properties in the <guilabel>PREFSTABNAME</guilabel> tab are:
3267:
3268: <!--many people use itemizedlists in cases like this. Variablelists
3269: are more appropriate -->
3270:
3271: <variablelist>
3272: <varlistentry>
3273: <term> <guilabel>Default Text Style</guilabel></term>
3274: <listitem>
3275: <para>
3276: Select the default text style for statements in your
3277: proof. You can still change the style for individual
3278: proofs or sections of a proof at a later date.
3279: </para>
3280: </listitem>
3281: </varlistentry>
3282: <varlistentry>
3283: <term>(Configuration Item Label)</term>
3284: <listitem>
3285: <para>
3286: (Description of Configuration)
3287: </para>
3288: </listitem>
3289: </varlistentry>
3290: <varlistentry>
3291: <term>(Configuration Item Label)</term>
3292: <listitem>
3293: <para>
3294: (Description of Configuration)
3295: </para>
3296: </listitem>
3297: </varlistentry>
3298: </variablelist>
3299: </para>
3300:
3301: <para>
3302: The properties in the <guilabel>SECONDTABNAME</guilabel> tab are:
3303: <variablelist>
3304: <varlistentry>
3305: <term>(Configuration Item Label)</term>
3306: <listitem>
3307: <para>
3308: (Description of Configuration)
3309: </para>
3310: </listitem>
3311: </varlistentry>
3312: <varlistentry>
3313: <term>(Configuration Item Label)</term>
3314: <listitem>
3315: <para>
3316: (Description of Configuration)
3317: </para>
3318: </listitem>
3319: </varlistentry>
3320: </variablelist>
3321: </para>
3322:
3323: <para>
3324: After you have made all the changes you want, click on
3325: <guibutton>OK</guibutton> to apply the changes and close the
3326: <interface>Properties</interface> dialog. To cancel the changes
3327: and return to previous values, click the
3328: <guibutton>Close</guibutton> button.
3329: </para>
3330:
3331: </sect1>
3332:
3333:
3334: <!-- ============= Various Sections ============================= -->
3335:
3336: <!-- Here you should add, if necessary, several more sect1's,
3337: describing other windows (besides the main one), file formats,
3338: preferences dialogs, etc. as appropriate. Try not to make any of
3339: these sections too long. -->
3340:
3341:
3342: <!-- ============= Bugs ================================== -->
3343: <!-- This section should describe known bugs and limitations of
3344: the program if there are any - please be frank and list all
3345: problems you know of. -->
3346: <sect1 id="bugs">
3347: <title>Known Bugs and Limitations</title>
3348: <para>
3349: This application has no known bugs.
3350: </para>
3351: </sect1>
3352:
3353:
3354: <!-- ============= Authors ================================ -->
3355:
3356: <sect1 id="authors">
3357: <title>Authors</title>
3358: <para>
3359: <application>MY-GNOME-APP</application> was written by GNOME-HACKER
3360: (<email>hacker@gnome.org</email>). To find more information about
3361: <application>MY-GNOME-APP</application>, please visit the <ulink
3362: url="http://www.my-gnome-app.org" type="http">MY-GNOME-APP Web
3363: page</ulink>. Please send all comments, suggestions, and bug
3364: reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
3365: bug tracking database</ulink>. (Instructions for submitting bug
3366: reports can be found <ulink
3367: url="http://bugs.gnome.org/Reporting.html" type="http">
3368: on-line</ulink>.) You can also use <application>Bug Report
3369: Tool</application> (<command>bug-buddy</command>), available in the
3370: <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
3371: Menu</guimenu>, for submitting bug reports.
3372: </para>
3373:
3374: <para>
3375: This manual was written by ME
3376: (<email>MYNAME@MYADDRESS</email>). Please send all comments and
3377: suggestions regarding this manual to the <ulink type="http"
3378: url="http://developer.gnome.org/projects/gdp">GNOME Documentation
3379: Project</ulink> by sending an email to
3380: <email>docs@gnome.org</email>. You can also add your comments online
3381: by using the <ulink type="http"
3382: url="http://www.gnome.org/gdp/doctable/">GNOME Documentation Status
3383: Table</ulink>.
3384: </para>
3385:
3386: <!-- For translations: uncomment this:
3387:
3388: <para>
3389: Latin translation was done by ME
3390: (<email>MYNAME@MYADDRESS</email>). Please send all comments and
3391: suggestions regarding this translation to SOMEWHERE.
3392: </para>
3393:
3394: -->
3395:
3396: </sect1>
3397:
3398:
3399: <!-- ============= Application License ============================= -->
3400:
3401: <sect1 id="license">
3402: <title>License</title>
3403: <para>
3404: This program is free software; you can redistribute it and/or
3405: modify it under the terms of the <citetitle>GNU General Public
3406: License</citetitle> as published by the Free Software Foundation;
3407: either version 2 of the License, or (at your option) any later
3408: version.
3409: </para>
3410: <para>
3411: This program is distributed in the hope that it will be useful, but
3412: WITHOUT ANY WARRANTY; without even the implied warranty of
3413: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3414: <citetitle>GNU General Public License</citetitle> for more details.
3415: </para>
3416: <para>
3417: A copy of the <citetitle>GNU General Public License</citetitle> is
3418: included as an appendix to the <citetitle>GNOME Users
3419: Guide</citetitle>. You may also obtain a copy of the
3420: <citetitle>GNU General Public License</citetitle> from the Free
3421: Software Foundation by visiting <ulink type="http"
3422: url="http://www.fsf.org">their Web site</ulink> or by writing to
3423: <address>
3424: Free Software Foundation, Inc.
3425: <street>59 Temple Place</street> - Suite 330
3426: <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
3427: <country>USA</country>
3428: </address>
3429: </para>
3430: </sect1>
3431: </article>
3432:
3433:
3434:
3435:
3436:
3437:
3438:
3439:
3440:
3441: ]]>
3442:
3443:
3444: </programlisting>
3445: </para>
3446: </sect1>
3447:
3448: <!-- ####### Document Templates | Templates 2-1.x: Applet Manual ####### -->
3449:
3450: <sect1 id="template2-1x">
3451: <title>Template 2: Applet Manual For GNOME 1.x</title>
3452: <para>
3453: The following templates should be used for all applet
3454: manuals in GNOME 1.x releases. You can always get the latest
3455: copy of these templates from <ulink type="http"
3456: url="http://developer.gnome.org/projects/gdp/templates.html">GDP
3457: Documentation Templates</ulink>. Note that the template
3458: consists of two files; the first file calls the second as an
3459: entity. You should name the first file
3460: <filename><replaceable>appletname</replaceable>-applet.sgml</filename>
3461: and the second file should be named
3462: <filename><replaceable>appletname</replaceable>.sgml</filename>,
3463: where
3464: <filename><replaceable>appletname</replaceable></filename> is
3465: the name of the applet.
3466: <programlisting>
3467:
3468: <![CDATA[
3469: <!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
3470: <!entity APPLETNAME.sgml SYSTEM "applet_template_1.sgml">
3471: <!-- Template Version: 1.0.1 (do not remove this line) -->
3472: ]>
3473:
3474: <!-- This is a GNOME documentation template, designed by the GNOME
3475: Documentation Project Team. Please use it for writing GNOME
3476: documentation, making obvious changes. In particular, all the words
3477: written in UPPERCASE (with the exception of GNOME) should be
3478: replaced. As for "legalnotice", please leave the reference
3479: unchanged,make sure to add/remove trademarks to the list as
3480: appropriate for your document.
3481:
3482: Please don't forget to remove these comments in your final documentation,
3483: thanks ;-).
3484: -->
3485:
3486: <article id="index"> <!-- please do not change the id -->
3487:
3488: <!-- ============= Document Header ============================= -->
3489: <artheader>
3490: <title>APPLETNAME Applet</title>
3491: <copyright>
3492: <year>2000</year>
3493: <holder>YOURFULLNAME</holder>
3494: </copyright>
3495:
3496: <!-- translators: uncomment this:
3497:
3498: <copyright>
3499: <year>2000</year>
3500: <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
3501: </copyright>
3502:
3503: -->
3504:
3505: <!-- do not put authorname in the header except in copyright - use
3506: section "authors" below -->
3507:
3508: <legalnotice>
3509: <para>
3510: Permission is granted to copy, distribute and/or modify this
3511: document under the terms of the <citetitle>GNU Free Documentation
3512: License</citetitle>, Version 1.1 or any later version published
3513: by the Free Software Foundation with no Invariant Sections, no
3514: Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
3515: of the <citetitle>GNU Free Documentation License</citetitle> from
3516: the Free Software Foundation by visiting <ulink type="http"
3517: url="http://www.fsf.org">their Web site</ulink> or by writing to:
3518: Free Software Foundation, Inc., 59 Temple Place - Suite 330,
3519: Boston, MA 02111-1307, USA.
3520: </para>
3521: <para>
3522: Many of the names used by companies to distinguish their products and
3523: services are claimed as trademarks. Where those names appear in any
3524: GNOME documentation, and those trademarks are made aware to the members
3525: of the GNOME Documentation Project, the names have been printed in caps
3526: or initial caps.
3527: </para>
3528: </legalnotice>
3529:
3530: <releaseinfo>
3531: This is version XXX of the APPLETNAME applet manual.
3532: </releaseinfo>
3533: </artheader>
3534:
3535: <!-- ============= Document Body ============================= -->
3536:
3537: &APPLETNAME.sgml;
3538:
3539: </article>
3540:
3541:
3542: ]]>
3543:
3544:
3545: </programlisting>
3546: <programlisting>
3547: <![CDATA[
3548: <!-- Template Version: 1.0.1 (do not remove this line) -->
3549:
3550: <sect1 id="APPLET">
3551: <title>APPLET Applet</title>
3552:
3553: <para>
3554: <application>APPLET</application> applet, shown in <xref
3555: linkend="APPLETapplet-fig">, allows you to …. To add this
3556: applet to a <interface>Panel</interface>,
3557: right-click on the <interface>Panel</interface> and choose
3558: <menuchoice>
3559: <guimenu>Panel</guimenu>
3560: <guisubmenu>Add to panel</guisubmenu>
3561: <guisubmenu>Applet</guisubmenu>
3562: <guisubmenu>SECTION</guisubmenu>
3563: <guimenuitem>APPLET</guimenuitem>
3564: </menuchoice>.
3565: </para>
3566:
3567: <figure id="APPLETapplet-fig">
3568: <title>APPLET Applet</title>
3569: <screenshot>
3570: <screeninfo>APPLET Applet</screeninfo>
3571: <graphic format="png" fileref="APPLET_applet"
3572: srccredit="YOURNAME">
3573: </graphic>
3574: </screenshot>
3575: </figure>
3576:
3577: <!-- ============= Usage ================================ -->
3578: <sect2 id="APPLET-usage">
3579: <title>Usage</title>
3580: <para>
3581: (Place a short description of how to use the applet here.)
3582: </para>
3583:
3584: <para>
3585: Right-clicking on the applet brings up a menu containing the
3586: following items:
3587: <itemizedlist>
3588:
3589: <listitem>
3590: <para>
3591: <guimenuitem>Properties…</guimenuitem> —
3592: opens the <link linkend="APPLET-prefs">
3593: <guilabel>Properties</guilabel></link> dialog.
3594: </para>
3595: </listitem>
3596:
3597: <listitem>
3598: <para>
3599: <guimenuitem>Help</guimenuitem> —
3600: displays this document.
3601: </para>
3602: </listitem>
3603:
3604: <listitem>
3605: <para>
3606: <guimenuitem>About…</guimenuitem> —
3607: shows basic information about <application>APPLET
3608: Applet</application>, including the applet's version and the
3609: author's name.
3610: </para>
3611: </listitem>
3612:
3613: </itemizedlist>
3614: </para>
3615: </sect2>
3616:
3617:
3618: <!-- ============= Customization ============================= -->
3619: <sect2 id="APPLET-prefs">
3620: <title>Customization</title>
3621: <para>
3622: You can customize <application>APPLET</application>
3623: applet by right-clicking on it and choosing
3624: <guimenuitem>Properties…</guimenuitem>. This will open the
3625: <interface>Properties</interface> dialog(shown in <xref
3626: linkend="APPLET-settings-fig">), which allows you to
3627: change various settings.
3628: </para>
3629:
3630: <figure id="APPLET-settings-fig">
3631: <title>Properties dialog</title>
3632: <screenshot>
3633: <screeninfo>Properties dialog</screeninfo>
3634: <graphic format="png" fileref="APPLET_settings"
3635: srccredit="YOURNAME">
3636: </graphic>
3637: </screenshot>
3638: </figure>
3639:
3640: <para>
3641: The properties are:
3642: <itemizedlist>
3643:
3644: <listitem>
3645: <para>
3646: (Configuration Item Label) — If this button is
3647: checked…(description)
3648: </para>
3649: </listitem>
3650:
3651: <listitem>
3652: <para>
3653: (Configuration Item Label) — Selecting this
3654: button…(description)
3655: </para>
3656: </listitem>
3657:
3658: <listitem>
3659: <para>
3660: (Configuration Item Label) — Enter the name of
3661: …(description)
3662: </para>
3663: </listitem>
3664: </itemizedlist>
3665: </para>
3666:
3667: <para>
3668: After you have made all the changes you want, click on
3669: <guibutton>OK</guibutton> to apply the changes and close the
3670: <interface>Properties</interface> dialog. To cancel the changes
3671: and return to previous values, click the
3672: <guibutton>Close</guibutton> button.
3673: </para>
3674: </sect2>
3675:
3676:
3677: <!-- ============= Bugs ================================== -->
3678: <!-- This section should describe known bugs and limitations of
3679: the program if there are any - please be frank and list all
3680: problems you know of -->
3681: <sect2 id="bugs">
3682: <title>Known Bugs and Limitations</title>
3683: <para>
3684: This applet has no known bugs.
3685: </para>
3686: </sect2>
3687:
3688:
3689: <!-- ============= Authors ================================ -->
3690:
3691: <sect2 id="authors">
3692: <title>Authors</title>
3693: <para>
3694: <application>APPLET</application> was written by GNOME-HACKER
3695: (<email>hacker@gnome.org</email>). Please send all comments,
3696: suggestions, and bug
3697: reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
3698: bug tracking database</ulink>. (Instructions for submitting bug
3699: reports can be found <ulink
3700: url="http://bugs.gnome.org/Reporting.html" type="http">
3701: on-line</ulink>. You can also use <application>Bug Report
3702: Tool</application> (<command>bug-buddy</command>), available in the
3703: <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
3704: Menu</guimenu>, for submitting bug reports.
3705: </para>
3706:
3707: <para>
3708: This manual was written by ME
3709: (<email>MYNAME@MYADDRESS</email>). Please send all comments and
3710: suggestions regarding this manual to the <ulink type="http"
3711: url="http://developer.gnome.org/projects/gdp">GNOME Documentation
3712: Project</ulink> by sending an email to
3713: <email>docs@gnome.org</email>. You can also submit comments online
3714: by using the <ulink type="http"
3715: url="http://www.gnome.org/gdp/doctable/">GNOME Documentation
3716: Status Table</ulink>.
3717: </para>
3718:
3719: <!-- For translations: uncomment this:
3720:
3721: <para>
3722: Latin translation was done by ME
3723: (<email>MYNAME@MYADDRESS</email>). Please send all comments and
3724: suggestions regarding this translation to SOMEWHERE.
3725: </para>
3726:
3727: -->
3728:
3729: </sect2>
3730:
3731:
3732: <!-- ============= Application License ============================= -->
3733:
3734: <sect2 id="license">
3735: <title>License</title>
3736: <para>
3737: This program is free software; you can redistribute it and/or
3738: modify it under the terms of the <citetitle>GNU General Public
3739: License</citetitle> as published by the Free Software Foundation;
3740: either version 2 of the License, or (at your option) any later
3741: version.
3742: </para>
3743: <para>
3744: This program is distributed in the hope that it will be useful, but
3745: WITHOUT ANY WARRANTY; without even the implied warranty of
3746: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3747: <citetitle>GNU General Public License</citetitle> for more details.
3748: </para>
3749: <para>
3750: A copy of the <citetitle>GNU General Public License</citetitle> is
3751: included as an appendix to the <citetitle>GNOME Users
3752: Guide</citetitle>. You may also obtain a copy of the
3753: <citetitle>GNU General Public License</citetitle> from the Free
3754: Software Foundation by visiting <ulink type="http"
3755: url="http://www.fsf.org">their Web site</ulink> or by writing to
3756: <address>
3757: Free Software Foundation, Inc.
3758: <street>59 Temple Place</street> - Suite 330
3759: <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
3760: <country>USA</country>
3761: </address>
3762: </para>
3763: </sect2>
3764:
3765: </sect1>
3766:
3767:
3768:
3769:
3770: ]]>
3771:
3772:
3773:
3774: </programlisting>
3775: </para>
3776: </sect1>
3777:
3778: <!-- ####### Document Templates | Templates 2-2.x: Applet Manual ####### -->
3779:
3780: <sect1 id="template2-2x">
3781: <title>Template 2: Applet Manual For GNOME 2.x</title>
3782: <para>
3783: The following templates should be used for all applet
3784: manuals in GNOME 2.x releases. You can always get the latest
3785: copy of these templates from <ulink type="http"
3786: url="http://developer.gnome.org/projects/gdp/templates.html">GDP
3787: Documentation Templates</ulink>.
3788: </para>
3789: <para>
3790: Note that this template consists of two files. The first file
3791: is an introductory chapter. You should not modify this
3792: chapter. The second file is the actual applet document, which
3793: you should modify to describe the applet you are documenting.
3794: You can name the first file whatever you like, such as
3795: <filename>gnome-applets.sgml</filename>. Name the second file
3796: according to the applet's name:
3797: <filename><replaceable>appletname</replaceable>-applet.sgml</filename>.
3798: Make sure you update the entity
3799: at the top of the shell document to reflect the new name of
3800: the applet document.
3801: </para>
3802: <para>
3803: <programlisting>
3804: <![CDATA[
3805: <!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
3806: <!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part">
3807:
3808: ]>
3809:
3810: <book id="gnome-applets">
3811:
3812: <bookinfo>
3813: <title>GNOME Applets</title>
3814: <authorgroup>
3815: <author><firstname>Telsa</firstname><surname>Gwynne</surname></author>
3816: <author><firstname>John</firstname><surname>Fleck</surname></author>
3817: <author><firstname>David</firstname><surname>Mason</surname>
3818: <affiliation><orgname>Red Hat, Inc.</orgname></affiliation>
3819: </author>
3820: <author><firstname>Dan</firstname><surname>Mueth</surname></author>
3821: <author><firstname>Alexander</firstname><surname>Kirillov</surname></author>
3822: </authorgroup>
3823: <edition>GNOME Applets version 0.1 for GNOME 1.1.5</edition>
3824: <pubdate>2000</pubdate>
3825: <copyright>
3826: <year>2000</year>
3827: <holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and
3828: Alexander Kirillov</holder>
3829: </copyright>
3830: <legalnotice>
3831: <para>
3832: Permission is granted to make and distribute verbatim copies of this
3833: manual provided the copyright notice and this permission notice are
3834: preserved on all copies.
3835: </para>
3836: <para>
3837: Permission is granted to copy and distribute modified versions of
3838: this manual under the conditions for verbatim copying, provided that
3839: the entire resulting derived work is distributed under the terms of a
3840: permission notice identical to this one.
3841: </para>
3842: <para>
3843: Permission is granted to copy and distribute translations of this
3844: manual into another language, under the above conditions for modified
3845: versions, except that this permission notice may be stated in a
3846: translation approved by the Free Software Foundation.
3847: </para>
3848: <para>
3849: Many of the names used by companies to distinguish their products and
3850: services are claimed as trademarks. Where those names appear in any
3851: GNOME documentation, and those trademarks are made aware to the members
3852: of the GNOME Documentation Project, the names have been printed in caps
3853: or initial caps.
3854: </para>
3855: </legalnotice>
3856: </bookinfo>
3857:
3858: <!-- #### Introduction ###### -->
3859: <chapter id="applets-intro">
3860: <title>Introduction</title>
3861:
3862: <!-- #### Intro | What Are Applets? ###### -->
3863: <sect1 id="applets-what-are">
3864: <title>What Are Applets?</title>
3865: <para>
3866: Applets are one of the most popular and useful objects you can add
3867: to your <interface>Panel</interface> to customize your desktop.
3868: An applet is a small application which runs inside a small area of
3869: your <interface>Panel</interface>. Applets have been written for
3870: a wide range of purposes. Some are very powerful interactive
3871: tools, such as the <application>Tasklist</application> Applet
3872: which allows you to easily
3873: control all of your main applications. Others are simple system
3874: monitors, displaying information such as the amount of power left
3875: in the battery on your laptop (see <application>Battery Charge
3876: Monitor</application>) or weather
3877: information(see <application>GNOME Weather</application>). Some
3878: are simply for amusement(see <application>Fish</application>).
3879: </para>
3880:
3881: <para>
3882: Applets are similar to swallowed applications in that both of them
3883: reside within the <interface>Panel</interface>. However,
3884: swallowed applications are generally applications which were
3885: not designed to run within the <interface>Panel</interface>.
3886: Typically one will swallow an application which already exists in
3887: the main <interface>desktop</interface> area, putting it into your
3888: <interface>Panel</interface>. The application will continue to
3889: run in the <interface>Panel</interface> until you end the
3890: application or unswallow it, placing it back onto the main part of
3891: your desktop when you need to.
3892: </para>
3893:
3894: <para>
3895: <figure id="example-applets-fig">
3896: <title>Example Applets</title>
3897: <screenshot>
3898: <screeninfo>Example Applets</screeninfo>
3899: <graphic fileref="example_applets" format="png"
3900: srccredit="muet">
3901: </graphic>
3902: </screenshot>
3903: </figure>
3904: Several example applets are shown in <xref
3905: linkend="example-applets-fig">. From left to right, they are: (1)
3906: <application>Mixer Applet</application>, which allows you to turn
3907: on/off sound and control its volume by clicking on the applet. (2)
3908: <application>Sound Monitor</application> Applet, which displays
3909: the current volume of sound being played and allows you to control
3910: various sound features. (3) <application>GTCD</application>
3911: Applet, a CD player which has all its controls
3912: available in the applet and displays the track and time. (4)
3913: <application>Drive Mount</application> Applet, used to mount and
3914: unmount drives with a single click of the mouse. (5)
3915: <application>Desk Guide</application> which allows you to view
3916: and control multiple virtual screens. (6)
3917: <application>Tasklist</application> Applet which allows you to
3918: control your various windows and applications.
3919: </para>
3920: <para>
3921: There are many other applets to choose from. The rest of this
3922: chapter will explain the basic information to get you started
3923: adding, moving, and removing applets from your
3924: <interface>Panels</interface> and using them. The following
3925: chapters go through each of the standard GNOME applets describing
3926: them in detail. There are also additional applets which can be
3927: downloaded off the Web. See <ulink type="http"
3928: url="http://www.gnome.org/applist/list-martin.phtml">The GNOME
3929: Software Map</ulink> for lists of additional GNOME applications
3930: and applets.
3931: </para>
3932: <para>
3933: As you read through the the rest of this chapter, you should try
3934: adding and removing applets from your <interface>Panel</interface> and
3935: experiment with them freely.
3936: </para>
3937: </sect1>
3938:
3939: <!-- #### Intro | Adding, Moving, and Removing Applets ###### -->
3940: <sect1 id="applet-add-move-replace">
3941: <title>Adding, Moving, and Removing Applets</title>
3942:
3943: <sect2 id="adding-applets">
3944: <title>Adding Applets to a Panel</title>
3945: <para>
3946: To add an applet to a <interface>Panel</interface>, right-click
3947: on the <interface>Panel</interface> and select
3948: <menuchoice><guimenu>Panel</guimenu><guisubmenu>Add to panel</guisubmenu>
3949: <guisubmenu>Applet</guisubmenu></menuchoice>. This will show you
3950: the menu of all the applets on your system, divided into
3951: categories. Choosing any applet from this menu will add it to the
3952: <interface>Panel</interface>.
3953: </para>
3954: </sect2>
3955:
3956: <sect2 id="moving-applets">
3957: <title>Moving Applets In or Between Panels</title>
3958: <para>
3959: It is easy to move applets in a <interface>Panel</interface> or
3960: between two <interface>Panels</interface>. If you have a
3961: three-button mouse, just move the mouse over the applet, depress
3962: the middle mouse button and drag the applet to its new location,
3963: releasing the middle mouse button when you are finished. Note
3964: that you can drag applets within a <interface>Panel</interface>
3965: or between two <interface>Panels</interface> this way. If you
3966: don't have a three-button mouse, just
3967: right-click on the applet and choose
3968: <guimenuitem>Move</guimenuitem>. The cursor will turn into a
3969: cross and the applet will move with your mouse until you press
3970: any mouse button to indicate you are finished moving it.
3971: If, in the course of this movement, it hits
3972: other objects, the behavior depends on the global preferences
3973: you have set for your <interface>Panels</interface> in the
3974: <application>GNOME Control Center</application>: the applet you are
3975: moving can switch places with other objects, "push" all objects
3976: it meets, or "jump" over all other objects without disturbing
3977: them. You can also override the default behavior by holding
3978: <keycap>Shift</keycap> button (for "push" mode),
3979: <keycap>Ctrl</keycap> (for "switched" mode), or
3980: <keycap>Alt</keycap> (for "free" mode, i.e. jumping other other
3981: objects without disturbing them) button while dragging.
3982: </para>
3983: <para>
3984: To change the global Panel preferences, right-click on any applet
3985: or <interface>Panel</interface> and select
3986: <menuchoice>
3987: <guimenu>Panel</guimenu>
3988: <guimenuitem>Global Preferences...</guimenuitem>
3989: </menuchoice>.
3990: The <guilabel>Default movement mode</guilabel> is set under the
3991: <guilabel>Applets</guilabel> tab.
3992: </para>
3993: </sect2>
3994:
3995: <sect2 id="removing-applets">
3996: <title>Removing Applets from a Panel</title>
3997: <para>
3998: To remove an applet from a <interface>Panel</interface>,
3999: right-click on the applet and select <guimenuitem>Remove from
4000: panel...</guimenuitem>.
4001: </para>
4002: </sect2>
4003: </sect1>
4004:
4005:
4006: <!-- #### Intro | The Right-Click Pop-Up Menu ###### -->
4007: <sect1 id="right-click-pop-up-menu">
4008: <title>The Right-Click Pop-Up Menu</title>
4009: <para>
4010: Clicking the right mouse button on any applet brings up
4011: a <guimenu>pop-up menu</guimenu>. This
4012: menu always has certain standard menu items in it and
4013: often has additional items which vary depending on the particular
4014: applet.
4015: </para>
4016: <sect2 id="standard-right-click-items">
4017: <title>Standard Pop-Up Items</title>
4018: <para>
4019: All applets should have the following items in their right-click
4020: <guimenu>pop-up menu</guimenu>:
4021: <variablelist>
4022: <varlistentry>
4023: <term>Remove from panel</term>
4024: <listitem>
4025: <para>
4026: The <guimenuitem>Remove from panel</guimenuitem> menu item
4027: removes the applet from the <interface>Panel</interface>.
4028: </para>
4029: </listitem>
4030: </varlistentry>
4031:
4032: <varlistentry>
4033: <term>Move</term>
4034: <listitem>
4035: <para>
4036: After selecting <guimenuitem>Move</guimenuitem>, your mouse
4037: pointer will change appearance (typically to a cross with
4038: arrows in each direction). As you move your mouse, the applet
4039: will move with it. When you have finished moving the applet,
4040: click any mouse button and the applet will anchor in its
4041: current position. Note that applets can be moved between two
4042: <interface>Panels</interface> this way.
4043: </para>
4044: </listitem>
4045: </varlistentry>
4046:
4047: <varlistentry>
4048: <term>Panel</term>
4049: <listitem>
4050: <para>
4051: The <guisubmenu>Panel</guisubmenu> submenu contains various
4052: items and submenus for adding and removing
4053: <interface>Panels</interface> and applets and for changing
4054: the configuration.
4055: </para>
4056: </listitem>
4057: </varlistentry>
4058:
4059: <varlistentry>
4060: <term>About</term>
4061: <listitem>
4062: <para>
4063: The <guimenuitem>About...</guimenuitem> menu item brings up a
4064: dialogue box containing various information about the applet,
4065: typically including the applet's name, version, author,
4066: copyright, license and desciption.
4067: </para>
4068: </listitem>
4069: </varlistentry>
4070:
4071: <varlistentry>
4072: <term>Help</term>
4073: <listitem>
4074: <para>
4075: The <guimenuitem>Help</guimenuitem> menu item brings up the help
4076: manual for the applet.
4077: </para>
4078: </listitem>
4079: </varlistentry>
4080: </variablelist>
4081: </para>
4082: </sect2>
4083:
4084: <sect2 id="applet-properties-dialog">
4085: <title>The Applet Properties Dialog</title>
4086: <para>
4087: Many applets have customizable properties. These applets will
4088: have a <guimenuitem>Properties...</guimenuitem> menu item in their
4089: right-click <guimenu>pop-up menu</guimenu> which brings up the
4090: <interface>Properties</interface> dialog where you can alter the
4091: appearance or behaviour of the applet.
4092: <figure id="example-props-dialog-fig">
4093: <title>An Example Applet Properties Dialog</title>
4094: <screenshot>
4095: <screeninfo>An Example Applets Properties Dialog</screeninfo>
4096: <graphic fileref="applet_props_dialog" format="png"
4097: srccredit="muet">
4098: </graphic>
4099: </screenshot>
4100: </figure>
4101: All <interface>Properties</interface> dialogs have the following
4102: buttons at the bottom of the dialog:
4103: <itemizedlist>
4104: <listitem>
4105: <para>
4106: <guibutton>OK</guibutton> —
4107: Pressing <guibutton>OK</guibutton> will activate any changes
4108: in the properties you have made and close the
4109: <interface>Properties</interface> dialog.
4110: </para>
4111: </listitem>
4112: <listitem>
4113: <para>
4114: <guibutton>Apply</guibutton> —
4115: Pressing <guibutton>Apply</guibutton> at any time will
4116: make your changes active without closing the
4117: <interface>Properties</interface> dialog. This is helpful if
4118: you would like to test the effects of the changes you have
4119: made but may want to continue changing the properties.
4120: </para>
4121: </listitem>
4122: <listitem>
4123: <para>
4124: <guibutton>Close</guibutton> —
4125: Pressing <guibutton>Close</guibutton> will close the
4126: <interface>Properties</interface> dialog. Only changes in the
4127: configuration which were previously applied with the
4128: <guibutton>Apply</guibutton> button will persist. Other
4129: changes will not be made active.
4130: </para>
4131: </listitem>
4132: <listitem>
4133: <para>
4134: <guibutton>Help</guibutton> —
4135: Pressing <guibutton>Help</guibutton> brings up the manual for
4136: the application, opening it to the page describing the
4137: <interface>Properties</interface> dialog.
4138: </para>
4139: </listitem>
4140: </itemizedlist>
4141: </para>
4142: </sect2>
4143:
4144: <sect2 id="common-right-click-items">
4145: <title>Other Common Pop-Up Items</title>
4146: <para>
4147: Many applets also have one or more of the following items in their
4148: right-click pop-up menu:
4149: <variablelist>
4150: <varlistentry>
4151: <term>Run...</term>
4152: <listitem>
4153: <para>
4154: The <guimenuitem>Run...</guimenuitem> menu item generally
4155: invokes a program which is related to the applet in some way
4156: but which runs in its own window rather than in the
4157: panel. For example:
4158: </para>
4159: <orderedlist>
4160: <listitem>
4161: <para>
4162: The <application>CPU Load</application> applet, which monitors
4163: what programs are running, has a <guimenuitem>Run
4164: gtop...</guimenuitem> menu item. Selecting this menu item
4165: starts <application>GTop</application>, which allows you to
4166: view and control programs which are running.
4167: </para>
4168: </listitem>
4169: <listitem>
4170: <para>
4171: The <application>CD Player</application> applet has a
4172: <guimenuitem>Run gtcd...</guimenuitem> menu item which
4173: starts the GNOME <application>CD Player</application> when
4174: selected, which has more capabilities than the applet.
4175: </para>
4176: </listitem>
4177: </orderedlist>
4178: </listitem>
4179: </varlistentry>
4180: </variablelist>
4181: </para>
4182: </sect2>
4183: </sect1>
4184:
4185: <sect1 id="feedback">
4186: <title>Feedback</title>
4187: <sect2 id="reporting-bugs">
4188: <title>Reporting Applet Bugs</title>
4189: <para>
4190: GNOME users are encouraged to report bugs to <ulink type="http"
4191: url="http://bugs.gnome.org">The GNOME Bug Tracking
4192: System</ulink>. The easiest way to submit bugs is to use the
4193: <application>Bug Report Tool</application> program by selecting
4194: <menuchoice>
4195: <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
4196: <guimenuitem>Bug Report Tool</guimenuitem>
4197: </menuchoice>.
4198: Be sure to be complete in describing what you did to cause the
4199: bug to surface and, if possible, describe how the developer can
4200: reproduce the the scenario.
4201: </para>
4202: </sect2>
4203: <sect2 id="documentation-feedback">
4204: <title>Providing Feedback</title>
4205: <para>
4206: GNOME users are welcome to provide suggestions for how
4207: applications and documentation can be improved. Suggestions for
4208: application changes should be submitted using the
4209: <application>Bug Report Tool</application> discussed above.
4210: Suggestions for documentation changes can be emailed directly to
4211: the documentation author (whose email should be included in the
4212: "Authors" section of the document) or by sending an email to
4213: <email>docs@gnome.org</email>.
4214: </para>
4215: </sect2>
4216: <sect2 id="joining-gnome">
4217: <title>Joining GNOME</title>
4218: <para>
4219: GNOME is a community project, created by hundreds of programmers,
4220: documentation writers, icon design artists, web masters, and
4221: other people, most of whom work on a volunteer basis. New GNOME
4222: contributors are always welcome. To join the GNOME team, visit
4223: these web sites: developers — <ulink type="http"
4224: url="http://developer.gnome.org">The GNOME Development
4225: Site</ulink>, documentation writers — <ulink type="http"
4226: url="http://developer.gnome.org/projects/gdp">The GNOME Documentation
4227: Project</ulink>, icon design artists — <ulink type="http"
4228: url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>,
4229: general — <ulink type="http"
4230: url="http://developer.gnome.org/helping/">Helping GNOME</ulink>,
4231: or just join the gnome-list email list (see <ulink type="http"
4232: url="http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing
4233: Lists</ulink>) to discuss what you are interested in doing.
4234: </para>
4235: </sect2>
4236: </sect1>
4237: </chapter>
4238:
4239: <!-- ############### Template Applets ##################### -->
4240: <chapter id="template-applets">
4241: <title>Template Applets</title>
4242:
4243: &TEMPLATE-APPLET
4244:
4245: </chapter>
4246:
4247: </book>
4248:
4249:
4250:
4251:
4252:
4253:
4254:
4255: ]]>
4256: </programlisting>
4257:
4258: <programlisting>
4259: <![CDATA[
4260:
4261: <!-- Please replace everywhere below GNOMEAPPLET with the name of -->
4262: <!-- your applet. Most importantly, all id attributes should start -->
4263: <!-- with the name of your applet - this is necessary to avoid name -->
4264: <!-- conflict among different applets -->
4265: <!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email-->
4266: <!-- Please replace HACKER-NAME with the applet author's name and -->
4267: <!-- HACKER-EMAIL with the applet author's email -->
4268:
4269: <!-- You should name your file: GNOMEAPPLET-applet.sgml -->
4270: <!-- Screenshots should be in PNG format and placed in the -->
4271: <!-- same directory as GNOMEAPPLET-applet.sgml -->
4272:
4273: <!-- Applet docs will be merged into <chapter>'s inside a -->
4274: <!-- <book>. Thus, the indentation below (2 spaces before the <sect1>) is -->
4275: <!-- correct.-->
4276:
4277: <!-- Permission is granted to make and distribute verbatim copies of -->
4278: <!-- this manual provided the copyright notice and this permission -->
4279: <!-- notice are preserved on all copies. -->
4280: <!-- -->
4281: <!-- Permission is granted to copy and distribute modified versions of -->
4282: <!-- this manual under the conditions for verbatim copying, provided -->
4283: <!-- that the entire resulting derived work is distributed under the -->
4284: <!-- terms of a permission notice identical to this one. -->
4285: <!-- -->
4286: <!-- Permission is granted to copy and distribute translations of this -->
4287: <!-- manual into another language, under the above conditions for -->
4288: <!-- modified versions, except that this permission notice may be -->
4289: <!-- stated in a translation approved by the Foundation. -->
4290:
4291: <!-- ############### GNOMEAPPLET ############### -->
4292: <sect1 id="GNOMEAPPLET">
4293: <title>GNOMEAPPLET Applet</title>
4294:
4295: <para>
4296: <application>GNOMEAPPLET</application> applet, shown in <xref
4297: linkend="GNOMEAPPLET-fig">, does this and that. To learn how to
4298: add this applet to a <interface>Panel</interface>, see <xref
4299: linkend="adding-applets">.
4300: </para>
4301:
4302:
4303: <figure id="GNOMEAPPLET-fig">
4304: <title>GNOMEAPPLET</title>
4305: <screenshot>
4306: <screeninfo>GNOMEAPPLET</screeninfo>
4307: <graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME">
4308: </graphic>
4309: </screenshot>
4310: </figure>
4311:
4312: <sect2 id="GNOMEAPPLET-usage">
4313: <title>Usage</title>
4314: <para>
4315: This applet does nothing. To use it, just
4316: left-click on it and it will instantly do nothing.
4317: </para>
4318: </sect2>
4319:
4320: <sect2 id="GNOMEAPPLET-right-click">
4321: <title>Right-Click Pop-Up Menu Items</title>
4322: <para>
4323: In addition to the standard menu items (see <xref
4324: linkend="standard-right-click-items">), the right-click pop-up menu has
4325: the following items:
4326: <itemizedlist>
4327: <listitem>
4328: <para>
4329: <guimenuitem>Properties...</guimenuitem> — This menu
4330: item opens the <interface>Properties</interface> dialog (see
4331: <xref linkend="GNOMEAPPLET-properties">) which allows you to
4332: customize the appearance and behavior of this applet.
4333: </para>
4334: </listitem>
4335: <listitem>
4336: <para>
4337: <guimenuitem>Run Hello World...</guimenuitem> — This
4338: menu item starts the program <application>Hello
4339: World</application>, used to say "hello" to the world.
4340: </para>
4341: </listitem>
4342: </itemizedlist>
4343: </para>
4344: </sect2>
4345:
4346: <sect2 id="GNOMEAPPLET-properties">
4347: <title>Properties</title>
4348: <para>
4349: You can configure <application>GNOMEAPPLET</application> applet by
4350: right-clicking on the applet and choosing the
4351: <guimenuitem>Properties...</guimenuitem> menu item. This will open the
4352: <interface>Properties</interface> dialog, shown in <xref
4353: linkend="GNOMEAPPLET-properties-fig">.
4354: </para>
4355: <figure id="GNOMEAPPLET-properties-fig">
4356: <title>Properties Dialog</title>
4357: <screenshot>
4358: <screeninfo>Properties Dialog</screeninfo>
4359: <graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME">
4360: </graphic>
4361: </screenshot>
4362: </figure>
4363:
4364: <para>
4365: To change the color of the applet, click on the
4366: <guibutton>color</guibutton> button. To change other properties,
4367: click on other buttons.
4368: </para>
4369:
4370: <para>
4371: For more information on the <interface>Properties</interface>
4372: dialog, including descriptions of the <guibutton>OK</guibutton>,
4373: <guibutton>Apply</guibutton>, <guibutton>Cancel</guibutton>, and
4374: <guibutton>Help</guibutton> buttons, see <xref
4375: linkend="applet-properties-dialog">.
4376: </para>
4377: </sect2>
4378:
4379: <sect2 id="GNOMEAPPLET-bugs">
4380: <title> Known Bugs and Limitations</title>
4381: <para>
4382: There are no known bugs in the
4383: <application>GNOMEAPPLET</application> applet.
4384: </para>
4385: </sect2>
4386:
4387: <sect2 id="GNOMEAPPLET-authors">
4388: <title>Authors</title>
4389: <para>
4390: This applet was writen by HACKER-NAME
4391: <email>HACKER-EMAIL</email>. The documentation for this applet
4392: which you are reading now was written by
4393: YOUR-NAME <email>YOUR-EMAIL</email>. For information on submitting
4394: bug reports and suggestions for improvements, see <xref
4395: linkend="feedback">.
4396: </para>
4397: </sect2>
4398:
4399: </sect1>
4400:
4401:
4402:
4403:
4404:
4405: ]]>
4406:
4407:
4408: </programlisting>
4409: </para>
4410: </sect1>
4411:
4412: <!-- ####### Document Templates | Templates 3: Application Help #######
4413:
4414: <sect1 id="template3">
4415: <title>Template 2: Application Help</title>
4416: <programlisting>
4417: <![CDATA[(Put sgml here.)]]> </programlisting>
4418: </sect1>
4419:
4420: ####### Document Templates | Templates 4: Application Context Sensitive Help #######
4421:
4422: <sect1 id="template4">
4423: <title>Template 3: Application Context Sensitive Help</title>
4424: <para>
4425: Context sensitive help is still in development.
4426: </para>
4427: </sect1>
4428:
4429: ####### Document Templates | Templates 5: Complete Application: gnome-hello #######
4430:
4431: <sect1 id="template5">
4432: <title>Template 4: Complete Application: gnome-hello</title>
4433: <programlisting>
4434: <![CDATA[(Put sgml here.)]]>
4435: </programlisting>
4436: </sect1>
4437:
4438: ####### Document Templates | Templates 6: Tutorial #######
4439:
4440: <sect1 id="template6">
4441: <title>Template 5: Tutorial</title>
4442: <programlisting>
4443: <![CDATA[(Put sgml here.)]]>
4444: </programlisting>
4445: </sect1>-->
4446: </appendix>
4447:
4448: </article>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to docbook_0.xml CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libxml2 / test / relaxng