Alessandro Bonazzi
8c43d5cf2f
Files correlati : cg0.exe cg0700a.msk cg0700b.msk cg3.exe cg4.exe Bug : Commento: Merge 1.0 libraries
3301 lines
173 KiB
HTML
3301 lines
173 KiB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>The GNOME Handbook of Writing Software Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.40"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article"><div class="titlepage"><div><h2 class="title"><a name="index"></a>The GNOME Handbook of Writing Software Documentation</h2></div><div><h3 class="author">David Mason</h3><div class="affiliation"><span class="orgname">Red Hat, Inc.<br></span><div class="address"><br>
|
||
<tt><<a href="mailto:dcm@redhat.com">dcm@redhat.com</a>></tt><br>
|
||
</div></div><h3 class="author">Daniel Mueth</h3><div class="affiliation"><div class="address"><br>
|
||
<tt><<a href="mailto:d-mueth@uchicago.edu">d-mueth@uchicago.edu</a>></tt><br>
|
||
</div></div><h3 class="author">Alexander Kirillov</h3><div class="affiliation"><div class="address"><br>
|
||
<tt><<a href="mailto:kirillov@math.sunysb.edu">kirillov@math.sunysb.edu</a>></tt><br>
|
||
</div></div></div><div><p class="releaseinfo">
|
||
This is a pre-release!
|
||
</p></div><div><p class="copyright">Copyright © 2000 Red Hat, Inc., Daniel Mueth, and Alexander Kirillov</p></div><div><div class="legalnotice"><p>
|
||
Permission is granted to copy, distribute and/or modify this
|
||
document under the terms of the <i>GNU Free Documentation
|
||
License</i>, Version 1.1 or any later version published
|
||
by the Free Software Foundation with no Invariant Sections, no
|
||
Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
|
||
of the <i>GNU Free Documentation License</i> from
|
||
the Free Software Foundation by visiting <a href="http://www.fsf.org" target="_top">their Web site</a> or by writing to:
|
||
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
||
Boston, MA 02111-1307, USA.
|
||
</p><p>
|
||
Many of the names used by companies to distinguish their products and
|
||
services are claimed as trademarks. Where those names appear in any
|
||
GNOME documentation, and those trademarks are made aware to the members
|
||
of the GNOME Documentation Project, the names have been printed in caps
|
||
or initial caps.
|
||
</p></div></div><div><div class="revhistory"><table border="1" width="100%" summary="Revision history"><tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr><tr><td align="left">Revision
|
||
0.99
|
||
</td><td align="left">
|
||
04.10.2000
|
||
</td></tr></table></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt> <a href="#intro">Introduction</a></dt><dd><dl><dt> <a href="#gdp">The GNOME Documentation Project</a></dt><dt> <a href="#notation">Notation and Conventions</a></dt><dt> <a href="#about">About This Handbook</a></dt></dl></dd><dt> <a href="#gettingstarted">Getting Started Writing GNOME Documentation</a></dt><dd><dl><dt> <a href="#selecting">Selecting A Document</a></dt><dt> <a href="#docbook">Installing and Using DocBook</a></dt><dt> <a href="#gdptemplates">GDP Document Templates</a></dt><dt> <a href="#screenshots">Screenshots</a></dt><dt> <a href="#applicationbugs">Application Bugs</a></dt><dt> <a href="#cvs">Using CVS</a></dt></dl></dd><dt> <a href="#gnomedocsystem">The GNOME Documentation System</a></dt><dd><dl><dt> <a href="#gnomehelpbrowser">The GNOME Help Browser</a></dt><dt> <a href="#gnomehelpbrowser2">The GNOME Help Browser (GNOME-2.0)</a></dt><dt> <a href="#gnomehelponthefly">Dynamic Document Synthesis(GNOME-2.0)</a></dt><dt> <a href="#gnomehelpcomponents">The GNOME Documentation Components</a></dt></dl></dd><dt> <a href="#docbookbasics">DocBook Basics </a></dt><dd><dl><dt> <a href="#introtodocbook">Introduction to DocBook</a></dt><dt> <a href="#xml">XML and SGML</a></dt><dt> <a href="#structure"> Structure Elements</a></dt><dt> <a href="#inline">Inline Elements</a></dt></dl></dd><dt> <a href="#conventions">GDP Documentation Conventions </a></dt><dd><dl><dt> <a href="#conventionsalldocs">Conventions for All GDP Documentation</a></dt><dt> <a href="#conventionsappdocs">Conventions for Application Documentation</a></dt></dl></dd><dt> <a href="#writingapplicationmanuals">Writing Application and Applet Manuals</a></dt><dt> <a href="#listingdocsinhelpmenu">Listing Documents in the Help Menu</a></dt><dt> <a href="#applicationhelpbuttons">Application Help Buttons</a></dt><dt> <a href="#packagingappletdocs">Packaging Applet Documentation</a></dt><dd><dl><dt> <a href="#appletfiles">Applet Documentation Files</a></dt><dt> <a href="#appletmenu">Adding Documentation to an Applet Menu</a></dt></dl></dd><dt> <a href="#writingcontextsensitivehelp">Writing Context Sensitive Help (coming in GNOME-2.0)</a></dt><dt> <a href="#referring">Referring to Other GNOME Documentation (coming in
|
||
GNOME-2.0)</a></dt><dt> <a href="#basics">Basics of Documentation Style</a></dt><dd><dl><dt> <a href="#styleplanning">Planning</a></dt><dt> <a href="#balance">Achieving a Balanced Style</a></dt><dt> <a href="#stylestructure">Structure</a></dt><dt> <a href="#stylegrammar">Grammar and Spelling</a></dt></dl></dd><dt> <a href="#teamwork">Teamwork</a></dt><dd><dl><dt> <a href="#teamworkgdp">Working With The GDP Team</a></dt><dt> <a href="#teamworkdevelopers">Working With Developers</a></dt></dl></dd><dt> <a href="#finishing">Finishing A Document</a></dt><dd><dl><dt> <a href="#editting">Editing The Document</a></dt><dt> <a href="#submitting">Submitting The Document</a></dt></dl></dd><dt> <a href="#resources">Resources</a></dt><dd><dl><dt> <a href="#resourcesweb">Resources On The Web</a></dt><dt> <a href="#resourcesbooks">Books</a></dt><dt> <a href="#mailinglists">Mailing Lists</a></dt><dt> <a href="#irc">IRC</a></dt></dl></dd><dt>A <a href="#templates">Document Templates</a></dt><dd><dl><dt> <a href="#template1">Template 1: Application Manual</a></dt><dt> <a href="#template2-1x">Template 2: Applet Manual For GNOME 1.x</a></dt><dt> <a href="#template2-2x">Template 2: Applet Manual For GNOME 2.x</a></dt></dl></dd></dl></div><div class="sect1"><a name="intro"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="intro"></a>Introduction</h2></div></div><div class="sect2"><a name="gdp"></a><div class="titlepage"><div><h3 class="title"><a name="gdp"></a>The GNOME Documentation Project</h3></div></div><div class="sect3"><a name="goals"></a><div class="titlepage"><div><h4 class="title"><a name="goals"></a>Goals</h4></div></div><p>
|
||
The GNOME Documentation Project (GDP) aims to provide GNOME
|
||
and GNOME applications with a complete, intuitive, and clear
|
||
documentation system. At the center of the GDP is the
|
||
GNOME Help Browser, which
|
||
presents a unified interface to GNOME-specific documentation
|
||
as well as other Linux documentation such as man pages and
|
||
texinfo documents. The GNOME Help System provides a
|
||
comprehensive view of documentation on a machine by
|
||
dynamically assembling the documentation of GNOME
|
||
applications and components which are installed. The GDP is
|
||
responsible for writing numerous GNOME-related documents,
|
||
both for developers and for users. Developer documentation
|
||
includes <a href="http://developer.gnome.org/doc/API/" target="_top">APIs for the GNOME libraries</a>, <a href="http://developer.gnome.org/doc/whitepapers/" target="_top"><i>GNOME White
|
||
Papers</i></a>, GNOME developer <a href="http://developer.gnome.org/doc/tutorials/" target="_top">tutorials</a>, the <a href="http://developer.gnome.org/doc/FAQ/" target="_top"><i>GNOME Developer
|
||
FAQ</i></a>, the <a href="http://developer.gnome.org" target="_top">GNOME
|
||
Developer's Website</a>, and <i>GNOME
|
||
Handbook</i>'s, such as the one you are reading.
|
||
User documentation include the <a href="http://www.gnome.org/learn/" target="_top"><i>GNOME User's
|
||
Guide</i></a>, the <a href="http://www.gnome.org/learn/" target="_top"><i>GNOME FAQ</i></a>, and
|
||
GNOME application documentation. Most GNOME applications
|
||
have their own manual in addition to context sensitive help.
|
||
</p></div><div class="sect3"><a name="joining"></a><div class="titlepage"><div><h4 class="title"><a name="joining"></a>Joining the GDP</h4></div></div><p>
|
||
Documenting GNOME and all the numerous GNOME applications is
|
||
a very large project. The GDP is always looking for people
|
||
to help write, update, and edit documentation. If you are
|
||
interested in joining the GDP team, you should join the
|
||
<a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
|
||
<i>gnome-doc-list mailing list</i> </a>.
|
||
Read <a href="#gettingstarted" title="Getting Started Writing GNOME Documentation">the section called “Getting Started Writing GNOME Documentation”</a>, for help selecting a
|
||
project to work on. Feel free to introduce yourself on the
|
||
gnome-doc-list mailing list and indicate which project you
|
||
intend to work on, or else ask for suggestions of important
|
||
documents which need work done. You may also want to join the
|
||
#docs IRC channel on irc.gnome.org to meet other GDP members
|
||
and discuss any questions you may have. For a list of GDP
|
||
projects and members, see the
|
||
<a href="http://developer.gnome.org/projects/gdp" target="_top">
|
||
<i>GDP Website</i></a>.
|
||
</p></div><div class="sect3"><a name="collaborating"></a><div class="titlepage"><div><h4 class="title"><a name="collaborating"></a>Collaborating with the GDP</h4></div></div><p>
|
||
GNOME developers, packagers, and translators may not be
|
||
writing GNOME documentation but will want to understand how
|
||
the GNOME documentation system works and will need to
|
||
collaborate with GDP members. This document should help to
|
||
outline the structure of how the GNOME documentation system
|
||
works. Developers who do not write the documentation for
|
||
their applications are encouraged to find a GDP member to
|
||
write the documentation. This is best done by sending an
|
||
email to the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
|
||
<i>gnome-doc-list mailing list</i> </a>
|
||
describing the application, where it can be downloaded from,
|
||
and that the developer(s) would like a GDP member to write
|
||
documentation for the application. The #docs IRC channel on
|
||
irc.gnome.org is another option for contacting GDP members.
|
||
</p></div></div><div class="sect2"><a name="notation"></a><div class="titlepage"><div><h3 class="title"><a name="notation"></a>Notation and Conventions</h3></div></div><p>
|
||
This Handbook uses the following notation:
|
||
<div class="informaltable" id="id2797678"><a name="id2797678"></a><table border="0"><colgroup><col><col></colgroup><tbody><tr><td><tt>/usr/bin</tt></td><td>
|
||
Directory
|
||
</td></tr><tr><td><tt>foo.sgml</tt></td><td>
|
||
Filename
|
||
</td></tr><tr><td><b>command</b></td><td>
|
||
Command or text that would be typed.
|
||
</td></tr><tr><td><b><i><tt>replaceable</tt></i></b></td><td>
|
||
"Variable" text that can be replaced.
|
||
</td></tr><tr><td><tt>Program or Doc Code</tt></td><td>Program or document code</td></tr></tbody></table></div>
|
||
</p></div><div class="sect2"><a name="about"></a><div class="titlepage"><div><h3 class="title"><a name="about"></a>About This Handbook</h3></div></div><p>
|
||
This Handbook is a guide for both writing documentation for
|
||
GNOME components and applications and for properly binding and
|
||
packaging documentation into GNOME applications.
|
||
</p><p>
|
||
This Handbook, like all GNOME documentation, was written in
|
||
DocBook(SGML) and is available in several formats including
|
||
SGML, HTML, PostScript, and PDF. For the latest version, see
|
||
<a href="http://developer.gnome.org/projects/gdp/handbook.html" target="_top">
|
||
<i>Getting The GNOME Handbook of Writing Software
|
||
Documentation</i> </a>. Alternately, one may
|
||
download it anonymously from GNOME CVS under <tt>gnome-docu/gdp</tt>.
|
||
</p></div></div><div class="sect1"><a name="gettingstarted"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="gettingstarted"></a>Getting Started Writing GNOME Documentation</h2></div></div><div class="sect2"><a name="selecting"></a><div class="titlepage"><div><h3 class="title"><a name="selecting"></a>Selecting A Document</h3></div></div><div class="sect3"><a name="know"></a><div class="titlepage"><div><h4 class="title"><a name="know"></a>Document Something You Know</h4></div></div><p>
|
||
The most frequently asked question of new contributors who
|
||
join the GDP is "which document should I start
|
||
with?". Because most people involved are volunteers, we do
|
||
not <i>assign</i> projects and applications to
|
||
write documents for. The first step is all yours - you must
|
||
decide what about GNOME interests you most and find out if
|
||
it has complete documents or not.
|
||
</p><p>
|
||
It is also important to spend some time with GNOME to make
|
||
sure you are familiar enough with it to be
|
||
<i>authoritative</i> in your writing. The
|
||
best way to do this is to just sit down and play with GNOME
|
||
as much as possible before starting to write.
|
||
</p><p>
|
||
The easiest way to get started is to improve existing
|
||
documentation. If you notice some inaccuracies or omissions
|
||
in the documentation, or you think that you can explain the
|
||
material more clearly, just send your suggestions to the
|
||
author of the original documentation or to the GNOME
|
||
documentation project at <tt><<a href="mailto:docs@gnome.org">docs@gnome.org</a>></tt>.
|
||
</p></div><div class="sect3"><a name="doctable"></a><div class="titlepage"><div><h4 class="title"><a name="doctable"></a>The GNOME Documentation Status Table</h4></div></div><p>
|
||
The <i>GDP Documentation Status Table</i>
|
||
(<i>DocTable</i>) (<a href="http://www.gnome.org/gdp/doctable/" target="_top">http://www.gnome.org/gdp/doctable/</a>) is a
|
||
web page which tracks the status of all the various
|
||
documentation components of GNOME. These components include
|
||
application documentation, internal GNOME component
|
||
documentation, user documentation, and developer
|
||
documentation. For each documentation item, it tracks the
|
||
current status of the documentation, who is working on the
|
||
particular document, where the documentation can be found,
|
||
and provides a forum for the discussion of each item.
|
||
</p><p>
|
||
You should use the <i>DocTable</i> to help
|
||
you select a documentation item which needs work done. Once
|
||
you have selected an item to work on, please register
|
||
yourself as an author so that other authors do not duplicate
|
||
your work and may contact you to help or offer suggestions.
|
||
Also be sure to keep the status icons up-to-date so that
|
||
the GDP team can easily identify which items need additional
|
||
help. The <i>DocTable</i> also allows
|
||
people to make announcements and suggestions and to discuss
|
||
issues in the comments section.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2795548"></a>Note</h3><p>
|
||
Note that the information in the
|
||
<i>DocTable</i> may not always be up-to-date
|
||
or accurate. When you assign yourself to documenting an
|
||
application, make sure you find out the latest status of
|
||
documentation by contacting the application author.
|
||
</p></div></div></div><div class="sect2"><a name="docbook"></a><div class="titlepage"><div><h3 class="title"><a name="docbook"></a>Installing and Using DocBook</h3></div></div><p>
|
||
All documentation for the GNOME project is written in SGML
|
||
using the DocBook DTD. There are many advantages to using
|
||
this for documentation, not least of which is the single
|
||
source nature of SGML. To contribute to the GDP you should
|
||
learn to use DocBook.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2795631"></a>NOTE</h3><p>
|
||
To get started writing for the GDP you do not need to rush
|
||
out and learn DocBook - if you feel it is too much to handle
|
||
for now, you can submit plain ASCII text to the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
|
||
<i>gnome-doc-list mailing list</i>
|
||
</a>and a volunteer will mark it up for you. Seeing your
|
||
document marked up will also be a great way for you to start
|
||
learning DocBook.
|
||
</p></div><div class="sect3"><a name="installingdocbook"></a><div class="titlepage"><div><h4 class="title"><a name="installingdocbook"></a>Installing DocBook</h4></div></div><p>
|
||
Download and install the following <a href="ftp://sourceware.cygnus.com:/pub/docbook-tools/" target="_top">DocBook Tools packages</a>: jade, docbook,
|
||
jadetex, sgml-common, and stylesheets. (RPM users should note
|
||
that jade is platform dependent (eg. i386), while the other packages
|
||
are in the <tt>noarch</tt>
|
||
directory.) You can find more
|
||
information on DocBook Tools <a href="http://sourceware.cygnus.com/docbook-tools/" target="_top">here</a>.
|
||
</p><p>
|
||
If you are an Emacs user you may
|
||
want to grab the psgml package as well. This is a major mode
|
||
for editing sgml files in Emacs.
|
||
</p></div><div class="sect3"><a name="gdpstylesheets"></a><div class="titlepage"><div><h4 class="title"><a name="gdpstylesheets"></a>GDP Stylesheets</h4></div></div><p>
|
||
The GDP uses its own DocBook stylesheets. To use the GDP
|
||
stylesheets, you should download the file
|
||
<tt>gdp-both.dsl</tt> from the <tt>gnome-docu/gdp/dsssl</tt> module in
|
||
CVS (or from <a href="http://developer.gnome.org/projects/gdp/stylesheets.html" target="_top">
|
||
GDP Custom DSSSL Stylesheet</a>)and copy it
|
||
|
||
over the file
|
||
<tt>/usr/lib/sgml/stylesheets/cygnus-both.dsl</tt>.
|
||
Alternately, you can download and install the
|
||
<a href="http://people.redhat.com/dcm/software.html" target="_top">gnome-doc-tools package</a> which will set
|
||
up the stylesheets as well as the DTD discussed below.
|
||
</p></div><div class="sect3"><a name="gdpdtd"></a><div class="titlepage"><div><h4 class="title"><a name="gdpdtd"></a>GDP DTD (PNG Image Support)</h4></div></div><p>
|
||
Due to some license issues involved with the creation of
|
||
gifs, the GNOME Documentation Project has decided to use the
|
||
PNG image format for all images in GNOME documentation. You
|
||
can read more about the issues involved with gifs at <a href="http://www.gnu.org/philosophy/gif.html" target="_top">http://www.gnu.org/philosophy/gif.html</a>.
|
||
</p><p>
|
||
The current DocBook DTD(3.1) does not include support for
|
||
embedding PNG images in your documents. Since the GDP uses
|
||
many screenshots in its documentation, we use our own
|
||
variation on the DocBook DTD which has PNG image support.
|
||
We encourage everybody to use this DTD instead of the
|
||
default DocBook DTD since your source document header and
|
||
your output document appearance subtly vary between the two
|
||
DTD's. To install the GDP custom DTD with PNG image support
|
||
by hand:
|
||
</p><div class="itemizedlist"><ul><li style="list-style-type: opencircle"><p><a name="id2796045"></a>
|
||
Download <a href="http://www.labs.redhat.com/png/png-support.html" target="_top">the
|
||
GDP DocBook DTD for PNG support</a> and install it
|
||
where you keep your DTD's. (On Red Hat use <tt>/usr/lib/sgml/</tt>.) Note that
|
||
the 3.0 DTD is missing support for the
|
||
<tt><legalnotice></tt> tag, so it is
|
||
recommended that you use version 3.1
|
||
</p></li><li style="list-style-type: disc"><p><a name="id2796107"></a>
|
||
Add the new DTD to your SGML CATALOG file. The location
|
||
of your SGML CATALOG file may vary depending upon your
|
||
distribution. (On Red Hat it is usually in
|
||
/usr/lib/sgml/CATALOG.) Add the following line to this
|
||
file:
|
||
<pre class="programlisting">
|
||
PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd"
|
||
</pre>
|
||
If you are using the 3.1 DTD, use:
|
||
<pre class="programlisting">
|
||
PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd"
|
||
</pre>
|
||
</p></li></ul></div><p>
|
||
Alternately, you can download and install the
|
||
<a href="http://people.redhat.com/dcm/software.html" target="_top">gnome-doc-tools package</a> which will set
|
||
up the custom stylesheets and DTD for you.
|
||
</p><p>
|
||
To include PNG files in your documents, you will need to
|
||
indicate that you are using this special DTD. To do
|
||
this, use the following headers:
|
||
</p><p>
|
||
Articles:
|
||
<pre class="programlisting">
|
||
<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant
|
||
V1.1//EN"[]>
|
||
</pre>
|
||
</p><p>
|
||
Books:
|
||
<pre class="programlisting">
|
||
<!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant
|
||
V1.1//EN"[]>
|
||
</pre>
|
||
</p></div><div class="sect3"><a name="editors"></a><div class="titlepage"><div><h4 class="title"><a name="editors"></a>Editors</h4></div></div><p>
|
||
There are many editors on Linux and UNIX systems available
|
||
to you. Which editor you use to work on the sgml documents
|
||
is completely up to you, as long as the editor is able to
|
||
preserve sgml and produce the source in a format that is
|
||
readable by everyone.
|
||
</p><p>
|
||
Probably the two most popular editors available are
|
||
Emacs and
|
||
vi. These and other editors are
|
||
used regularly by members of the GDP. Emacs has a major
|
||
mode, psgml, for editing sgml files which can save you time
|
||
and effort in adding and closing tags. You will find the
|
||
psgml package in DocBook Tools, which is the standard set of
|
||
tools for the GDP. You may find out more about DocBook Tools
|
||
in <a href="#installingdocbook" title="Installing DocBook">the section called “Installing DocBook”</a>.
|
||
</p></div><div class="sect3"><a name="make-output"></a><div class="titlepage"><div><h4 class="title"><a name="make-output"></a>Creating Something Useful with your Docs</h4></div></div><p>
|
||
The tools available in DocBook Tools allow you to convert
|
||
your sgml document to many different formats including html
|
||
and Postscript. The primary tool used to do the conversion
|
||
is an application called Jade. In
|
||
most cases you will not have to work directly with
|
||
Jade; Instead, you will use the
|
||
scripts provided by DocBook Tools.
|
||
</p><p>
|
||
To preview your DocBook document, it is easiest to convert
|
||
it to <tt>html</tt>. If you have installed the
|
||
DocBook tools described above, all you have to do is to run
|
||
the command <tt>$</tt><b>db2html
|
||
mydocument.sgml</b>. If there are no sgml syntax
|
||
errors, this will create a directory <tt>mydocument</tt> and place the
|
||
resulting html files in it. The title page of the document
|
||
will typically be
|
||
<tt>mydocument/index.html</tt>. If you have
|
||
screenshots in your document, you will have to copy these
|
||
files into the <tt>mydocument</tt> directory by
|
||
hand. You can use any web browser to view your document.
|
||
Note that every time you run <b>db2html</b>, it
|
||
creates the <tt>mydocument</tt> directory over, so
|
||
you will have to copy the screenshots over each time.
|
||
</p><p>
|
||
You can also convert your document to PostScript by running
|
||
the command <tt>$</tt><b>db2ps
|
||
mydocument.sgml</b>, after which you can print out or
|
||
view the resulting .ps file.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2796585"></a>NOTE</h3><p>
|
||
The html files you get will not look quite the same as the
|
||
documentation distributed with GNOME unless you have the
|
||
custom stylesheets installed on your machine. DocBook
|
||
Tools' default stylesheets will produce a different look
|
||
to your docs. You can read more about the GDP stylesheets
|
||
in <a href="#gdpstylesheets" title="GDP Stylesheets">the section called “GDP Stylesheets”</a>.
|
||
</p></div></div><div class="sect3"><a name="jadeimages"></a><div class="titlepage"><div><h4 class="title"><a name="jadeimages"></a>Images in DocBook Tools</h4></div></div><p>
|
||
If your document uses images you will need to take note of a
|
||
few things that should take place in order for you to make
|
||
use of those images in your output.
|
||
</p><p>
|
||
The DocBook Tools scripts and applications are smart enough
|
||
to know that when you are creating html you will be using
|
||
PNG files and when you are creating Postscript you will be
|
||
using EPS files (you must use EPS with Postscript).
|
||
</p><p>
|
||
Thus, you should never explicitly
|
||
include the extension of the image file, since DocBook
|
||
Tools will automatically insert it for you. For example:
|
||
</p><pre class="programlisting">
|
||
|
||
<figure>
|
||
<title>My Image</title>
|
||
<screenshot>
|
||
<screeninfo>Sample GNOME Display</screeninfo>
|
||
<graphic format="png" fileref="myfile" srccredit="me">
|
||
</graphic>
|
||
</screenshot>
|
||
</figure>
|
||
</pre><p>
|
||
You will notice in this example that the file
|
||
<tt>myfile.png</tt> was referred to as simply
|
||
<tt>myfile</tt>. Now when you run
|
||
<b>db2html</b> to create an html file, it will
|
||
automatically look for <tt>myfile.png</tt> in
|
||
the directory.
|
||
</p><p>
|
||
If you want to create PostScript output, you will need to create an
|
||
EPS version of your image file to be displayed in the
|
||
PostScript file. There is a simple script available which
|
||
allows you to change a PNG image into an EPS file
|
||
easily. You can download this file - img2eps - from <a href="http://people.redhat.com/dcm/sgml.html" target="_top">http://people.redhat.com/dcm/sgml.html</a>
|
||
(look for the img2eps section). Note that this script is
|
||
included in the gnome-doc-tools package, so if you are using
|
||
this package, you should already have
|
||
<b>img2eps</b> on you system.
|
||
</p></div><div class="sect3"><a name="moredocbookinfo"></a><div class="titlepage"><div><h4 class="title"><a name="moredocbookinfo"></a>Learning DocBook</h4></div></div><p>
|
||
There are many resources available to help you learn DocBook.
|
||
The following resources on the web are useful for learning
|
||
DocBook:
|
||
</p><div class="itemizedlist"><ul><li style="list-style-type: disc"><p><a name="id2918531"></a>
|
||
<a href="http://www.docbook.org" target="_top">http://www.docbook.org</a> - Norman
|
||
Walsh's <i>DocBook: The Definitive
|
||
Guide</i>. Online O'Reilly book on using
|
||
DocBook. Contains an excellent element reference. May be
|
||
too formal for a beginner.
|
||
</p></li><li style="list-style-type: disc"><p><a name="id2918577"></a>
|
||
<a href="http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html" target="_top">A Practical Introduction to DocBook</a>
|
||
- The Open Source Writers Group's introduction to using
|
||
DocBook. This is an excellent HOW-TO type article on
|
||
getting started.
|
||
</p></li><li style="list-style-type: disc"><p><a name="id2918619"></a>
|
||
<a href="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html" target="_top">Getting Going with DocBook: Notes for
|
||
Hackers</a> - Mark Galassi's introduction to DocBook
|
||
for hackers. This has to be one of the first
|
||
introductions to DocBook ever - still as good as it ever
|
||
was.
|
||
</p></li><li style="list-style-type: disc"><p><a name="id2918658"></a>
|
||
<a href="http://www.freebsd.org/tutorials/docproj-primer/" target="_top">
|
||
FreeBSD Documentation Project Primer for New
|
||
Contributors</a> - FreeBSD documentation project
|
||
primer. Chapter 4.2 provides a very good introduction to
|
||
writing documentation using DocBook. Note that it also
|
||
describes some custom extensions of DocBook;
|
||
fortunately, they are clearly marked as such.
|
||
</p></li></ul></div><p>
|
||
Norman Walsh's book is also available in print.
|
||
</p><p>
|
||
The following sections of this document are designed to help
|
||
documentation authors write correct and consistent DocBook:
|
||
</p><div class="itemizedlist"><ul><li style="list-style-type: disc"><p><a name="id2918733"></a>
|
||
<a href="#docbookbasics" title="DocBook Basics ">the section called “DocBook Basics ”</a> - Descriptions of
|
||
commonly used DocBook tags.
|
||
</p></li></ul></div><p>
|
||
You may also discuss specific DocBook questions with GDP
|
||
members on the #docs IRC channel at irc.gnome.org and on the
|
||
gnome-doc-list mailing list.
|
||
</p></div></div><div class="sect2"><a name="gdptemplates"></a><div class="titlepage"><div><h3 class="title"><a name="gdptemplates"></a>GDP Document Templates</h3></div></div><p>
|
||
Templates for various types of GNOME documents are found in
|
||
<a href="#templates" title="A. Document Templates">Appendix A. Document Templates</a>. They are kept in CVS in
|
||
gnome-docu/gdp/templates. The easiest source to get them from
|
||
is probably the <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
|
||
Document Templates</a> web page, which is typically kept
|
||
completely up-to-date with CVS and has a basic description of
|
||
each file from CVS.
|
||
</p></div><div class="sect2"><a name="screenshots"></a><div class="titlepage"><div><h3 class="title"><a name="screenshots"></a>Screenshots</h3></div></div><p>
|
||
Most GNOME documents will have screenshots of the particular
|
||
applet, application, GNOME component, or widget being
|
||
discussed. As discussed above in <a href="#gdpdtd" title="GDP DTD (PNG Image Support)">the section called “GDP DTD (PNG Image Support)”</a> you
|
||
will need to install the special GDP DocBook DTD which
|
||
supports PNG images, the format used for all images in GNOME
|
||
documentation. For the basic DocBook structure used to insert
|
||
images in a document, see <a href="#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a> above.
|
||
</p><div class="sect3"><a name="screenshotappearance"></a><div class="titlepage"><div><h4 class="title"><a name="screenshotappearance"></a>Screenshot Appearance</h4></div></div><p>
|
||
For all screenshots of windows that typically have border
|
||
decorations (e.g. applications and dialogs, but not applets
|
||
in a panel), GDP standards dictate
|
||
the appearance of the window. (This is to minimize possible
|
||
confusion to the reader, improve the appearance of GNOME
|
||
documents, and guarantee the screenshot is readable when
|
||
printed.) All screenshots should be taken with the SawFish
|
||
(formerly known as Sawmill) window manager using the
|
||
MicroGui theme and Helvetica 12pt font. (A different window
|
||
manager can be used provided the MicroGui theme is available
|
||
for this window manager and the appearance is identical to
|
||
that when using the SawFish window manager.) The default
|
||
GTK+ theme(gtk) and font (Helvetica 12 pt) should be used
|
||
for all screenshots. If you are unable to provide
|
||
screenshots in this form, you should create screenshots as
|
||
you wish them to appear and send them to the
|
||
<a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
|
||
<i>gnome-doc-list mailing list</i> </a>
|
||
requesting a GDP member reproduce these screenshots in the
|
||
correct format and email them to you.
|
||
</p></div><div class="sect3"><a name="screenshottools"></a><div class="titlepage"><div><h4 class="title"><a name="screenshottools"></a>Screenshot Tools</h4></div></div><p>
|
||
There are many tools for taking screenshots in
|
||
GNOME/Linux. Perhaps the most convenient is the
|
||
Screen-Shooter Applet. Just click
|
||
on the window icon in the applet and then on the window you
|
||
would like to take a screenshot of. (Note that
|
||
at the time of this writing, PNG images taken by
|
||
screenshooter do not appear properly in
|
||
Netscape or the
|
||
GNOME Help Browser. You
|
||
should save your screenshot as a GIF and
|
||
then use <b>convert filename.gif
|
||
filename.png</b>.) For applets
|
||
in a Panel,
|
||
xv can be used to crop the
|
||
screenshot to only include the relevant portion of the
|
||
Panel. Note that
|
||
xv and
|
||
gimp can both be used for taking
|
||
screenshots, cropping screenshots, and converting image
|
||
formats.
|
||
</p></div><div class="sect3"><a name="screenshotfiles"></a><div class="titlepage"><div><h4 class="title"><a name="screenshotfiles"></a>Screenshot Files</h4></div></div><p>
|
||
Screenshots should be kept in the main documentation
|
||
directory with your SGML file for applets, or should be
|
||
kept in a directory called "figs" for application and other
|
||
documentation. After you use <b>db2html</b> to
|
||
convert your SGML file to HTML (see <a href="#make-output" title="Creating Something Useful with your Docs">the section called “Creating Something Useful with your Docs”</a>), you will need to copy your
|
||
screenshots (either the individual PNG files for applet
|
||
documentation, or the whole "figs" directory for other
|
||
documentation) into the newly created HTML directory. Note
|
||
that every time you use <b>db2html</b> the HTML
|
||
directory is erased and rewritten, so do not store your only
|
||
copy of the screenshots in that directory. If you wish to
|
||
create PostScript or PDF output, you will need to manually
|
||
convert the PNG images to EPS as described in <a href="#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a>, but will not need to copy these
|
||
images from their default location, as they are included
|
||
directly into the output(PostScript of PDF) file.
|
||
</p></div></div><div class="sect2"><a name="applicationbugs"></a><div class="titlepage"><div><h3 class="title"><a name="applicationbugs"></a>Application Bugs</h3></div></div><p>
|
||
Documentation authors tend to investigate and test applets and
|
||
applications more thoroughly than most
|
||
users. Often documentation authors will discover one or
|
||
more bugs in the software. These bugs vary from small ones,
|
||
such as mis-spelled words or missing
|
||
About dialogs in the menu, to large
|
||
ones which cause the applet to crash. As all users, you
|
||
should be sure to report these bugs so that application
|
||
developers know of them and can fix them. The easiest way to
|
||
submit a bug report is by using the Bug
|
||
Buddy applet which is part of the gnome-applets
|
||
package.
|
||
</p></div><div class="sect2"><a name="cvs"></a><div class="titlepage"><div><h3 class="title"><a name="cvs"></a>Using CVS</h3></div></div><p>
|
||
CVS (Concurrent Versions System) is a tool that allows
|
||
multiple developers to concurrently work on a set of
|
||
documents, keeping track of the modifications made by each
|
||
person. The files are stored on a server and each developer
|
||
checks files out, modifies them, and then checks in their
|
||
modified version of the files. Many GNOME programs and
|
||
documents are stored in CVS. The GNOME CVS server allows
|
||
users to anonymously check out CVS files. Most GDP members
|
||
will need to use anonymous CVS to download the most up-to-date
|
||
version of documentation or programs. Modified documents will
|
||
typically be emailed to the the application developer. Core
|
||
GDP members may also be granted login CVS privileges so they
|
||
may commit modified files directly to CVS.
|
||
</p><div class="sect3"><a name="anonymouscvs"></a><div class="titlepage"><div><h4 class="title"><a name="anonymouscvs"></a>Anonymous CVS</h4></div></div><p>
|
||
To anonymously check out documents from CVS, you must first
|
||
log in. From the bash shell, you should set your CVSROOT
|
||
shell variable with <b> export
|
||
CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</b>
|
||
and then login with <b>cvs login</b>(there is no
|
||
password, just hit return). As an example, we will use the
|
||
"gnome-docu/gdp" module which contains this and several
|
||
other documents. To check these documents out for the first
|
||
time, type <b>cvs -z3 checkout
|
||
gnome-docu/gdp</b>. After you have this document
|
||
checked out and you would like to download any updates on
|
||
the CVS server, use <b>cvs -z3 update -Pd</b>.
|
||
</p></div><div class="sect3"><a name="logincvs"></a><div class="titlepage"><div><h4 class="title"><a name="logincvs"></a>Login CVS</h4></div></div><p> If you have been given a
|
||
login for the GNOME CVS server, you may commit your file
|
||
modifications to CVS. Be sure to read the following section
|
||
on CVS etiquette before making any commits to CVS. To log in
|
||
to the CVS server as user
|
||
<b><i><tt>username</tt></i></b> with a
|
||
password, you must first set your CVSROOT shell variable with
|
||
<b> export
|
||
CVSROOT=':pserver:<i><tt>username</tt></i>@cvs.gnome.org:/cvs/gnome'</b>.
|
||
Log in with <b>cvs login</b> and enter your
|
||
password. You may check out and update modules as described
|
||
above for anonymous CVS access. As a login CVS user, you may
|
||
also check modified versions of a file into the CVS server.
|
||
To check
|
||
<b><i><tt>filename</tt></i></b> into
|
||
the CVS server, type <b>cvs -z3 commit
|
||
<i><tt>filename</tt></i></b>. You will be
|
||
given a vi editor window to type in a brief log entry,
|
||
summarizing your changes. The default editor can be changed
|
||
using the <tt>EDITOR</tt> environment variable or
|
||
with the <b><tt>-e</tt></b> option. You
|
||
may also check in any modifications to files in the working
|
||
directory and subdirectories using <b>cvs -z3
|
||
commit</b>. To
|
||
add a new file to the CVS server, use <b>cvs -z3 add
|
||
<i><tt>filename</tt></i></b>, followed by the
|
||
commit command.
|
||
</p></div><div class="sect3"><a name="cvsetiquette"></a><div class="titlepage"><div><h4 class="title"><a name="cvsetiquette"></a>CVS Etiquette</h4></div></div><p>
|
||
Because files in CVS are typically used and modified by
|
||
multiple developers and documentation authors, users should
|
||
exercise a few simple practices out of courtesy towards the
|
||
other CVS users and the project leader. First, you should
|
||
not make CVS commits to a package without first discussing
|
||
your plans with the project leader. This way, the project
|
||
leader knows who is modifying the files and generally, what
|
||
sort of changes/development is being done. Also, whenever a
|
||
CVS user commits a file to CVS, they should make an entry in
|
||
the CVS log and in the <tt>ChangeLog</tt> so
|
||
that other users know who is making modifications and what
|
||
is being modified. When modifying files created by others,
|
||
you should follow the indentation scheme used by the initial
|
||
author.
|
||
</p></div></div></div><div class="sect1"><a name="gnomedocsystem"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="gnomedocsystem"></a>The GNOME Documentation System</h2></div></div><div class="sect2"><a name="gnomehelpbrowser"></a><div class="titlepage"><div><h3 class="title"><a name="gnomehelpbrowser"></a>The GNOME Help Browser</h3></div></div><p>
|
||
At the core of the GNOME help system is the GNOME
|
||
Help Browser. The Help
|
||
Browser provides a unified interface to several
|
||
distinct documentation systems on Linux/Unix systems: man
|
||
pages, texinfo pages, Linux Documentation Project(LDP)
|
||
documents, GNOME application documentation, and other GNOME
|
||
documents.
|
||
</p><p>
|
||
The GNOME Help Browser works by
|
||
searching standard directories for documents which are to be
|
||
presented. Thus, the documentation that appears in the GHB is
|
||
specific to each computer and will typically only represent
|
||
software that is installed on the computer.
|
||
</p></div><div class="sect2"><a name="gnomehelpbrowser2"></a><div class="titlepage"><div><h3 class="title"><a name="gnomehelpbrowser2"></a>The GNOME Help Browser (GNOME-2.0)</h3></div></div><p> In
|
||
GNOME 2.0, the GNOME Help Browser
|
||
will be replaced by Nautilus.
|
||
Nautilus will be the file manager/graphical shell for GNOME 2.0
|
||
and will also implement a more sophisticated help system than
|
||
that used by the GNOME Help Browser
|
||
used in GNOME 1.0. It will read and display DocBook files
|
||
directly, avoiding the need for duplicating documents in both
|
||
DocBook and HTML formats. Its display engine for DocBook will
|
||
be much faster than running jade to
|
||
convert to HTML for rendering. Because it uses the original
|
||
DocBook source for documentation, it will be possible to do more
|
||
sophisticated searching using the meta information included in
|
||
the documents. And since Nautilus is a virtual file system
|
||
layer which is Internet-capable, it will be able to find and
|
||
display documents which are on the web as well as those on the
|
||
local file system. For more information on
|
||
Nautilus, visit the #nautilus IRC
|
||
channel on irc.gnome.org. </p></div><div class="sect2"><a name="gnomehelponthefly"></a><div class="titlepage"><div><h3 class="title"><a name="gnomehelponthefly"></a>Dynamic Document Synthesis(GNOME-2.0)</h3></div></div><p>
|
||
GNOME uses the documentation presented by all the various
|
||
GNOME components and applications installed on the system to
|
||
present a complete and customized documentation environment
|
||
describing only components which are currently installed on a
|
||
users system. Some of this documentation, such as the manuals
|
||
for applets, will be combined in such a way that it appears to
|
||
be a single document.
|
||
</p><p>
|
||
By using such a system, you can be sure that any GNOME app you
|
||
install that has documentation will show up in the index,
|
||
table of contents, any search you do in the help browser.
|
||
</p></div><div class="sect2"><a name="gnomehelpcomponents"></a><div class="titlepage"><div><h3 class="title"><a name="gnomehelpcomponents"></a>The GNOME Documentation Components</h3></div></div><div class="sect3"><a name="applicationmanualsintro"></a><div class="titlepage"><div><h4 class="title"><a name="applicationmanualsintro"></a>Application Manuals</h4></div></div><p>
|
||
Every GNOME application should have an application manual.
|
||
An application manual is a document specific to the
|
||
particular application which explains the various windows
|
||
and features of the application. Application Manuals
|
||
typically use screenshots (PNG format) for clarity. Writing
|
||
application manuals is discussed in more detail in <a href="#writingapplicationmanuals" title="Writing Application and Applet Manuals">the section called “Writing Application and Applet Manuals”</a> below.
|
||
</p></div><div class="sect3"><a name="applicationhelpintro"></a><div class="titlepage"><div><h4 class="title"><a name="applicationhelpintro"></a>Application Help</h4></div></div><p>
|
||
Applications should have a Help
|
||
button on screens on which users may need help. These
|
||
Help buttons should pull up the
|
||
default help browser, determined by the
|
||
<tt>ghelp</tt> URL Handler (configured using the
|
||
Control Center), typically the
|
||
GNOME Help Browser. The help
|
||
browser should show either the first page of the application
|
||
manual, or else the relevant page thereof. Application help
|
||
is described in more detail in <a href="#applicationhelpbuttons" title="Application Help Buttons">the section called “Application Help Buttons”</a> below.
|
||
</p></div><div class="sect3"><a name="contextsensitivehelpintro"></a><div class="titlepage"><div><h4 class="title"><a name="contextsensitivehelpintro"></a>Application Context Sensitive Help (coming in
|
||
GNOME-2.0)</h4></div></div><p>
|
||
Context sensitive help is a system which will allow the user
|
||
to query any part (button, widget, etc.) of an application
|
||
window. This is done by either entering a CS Help mode by
|
||
clicking on an icon or by right clicking on the application
|
||
part and selecting "What's This" or whatever is decided on
|
||
at the time. Context sensitive help is described in more
|
||
detail in <a href="#writingcontextsensitivehelp" title="Writing Context Sensitive Help (coming in GNOME-2.0)">the section called “Writing Context Sensitive Help (coming in GNOME-2.0)”</a>
|
||
below.
|
||
</p></div><div class="sect3"><a name="userguide"></a><div class="titlepage"><div><h4 class="title"><a name="userguide"></a>The GNOME User Guide</h4></div></div><p>
|
||
The <i>GNOME User Guide</i> describes the
|
||
GNOME desktop environment and core components of GNOME such
|
||
as the panel and
|
||
control center. In GNOME 1.x this
|
||
was the main and only source of documentation. In GNOME 2.0
|
||
this will become a document for the web and for printing
|
||
that is derived from various parts chosen in the system that
|
||
are necessary for the new user to understand.
|
||
</p></div><div class="sect3"><a name="userdocs"></a><div class="titlepage"><div><h4 class="title"><a name="userdocs"></a>User Documents</h4></div></div><p>
|
||
Aside from the <i>GNOME User Guide</i>,
|
||
there are several other documents to help GNOME users learn
|
||
GNOME, including the <i>GNOME FAQ</i>,
|
||
<i>GNOME Installation and Configuration
|
||
Guide</i>, and the <i>GNOME Administrators
|
||
Guide</i>.
|
||
</p></div><div class="sect3"><a name="developerdocs"></a><div class="titlepage"><div><h4 class="title"><a name="developerdocs"></a>Developer Documents</h4></div></div><p>
|
||
There are many White Papers, Tutorials, HOWTO's and FAQ's to
|
||
make programming GNOME and GNOME applications as easy as
|
||
possible.
|
||
</p><p>
|
||
API documentation is also available for the GNOME libraries. This is
|
||
detailed documentation of the code that is used to build GNOME
|
||
apps. You can keep up with the GNOME API docs on the <a href="http://developer.gnome.org/doc/API/" target="_top">GNOME API
|
||
Reference</a> page.
|
||
</p></div><div class="sect3"><a name="projectdocs"></a><div class="titlepage"><div><h4 class="title"><a name="projectdocs"></a>Project Documents</h4></div></div><p>
|
||
Some GNOME projects have documentation to maintain
|
||
consistency in their product and to help new contributors
|
||
get up to speed quickly. Among these are the GDP documents,
|
||
such as the one you are reading now.
|
||
</p></div></div></div><div class="sect1"><a name="docbookbasics"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="docbookbasics"></a>DocBook Basics </h2></div></div><div class="sect2"><a name="introtodocbook"></a><div class="titlepage"><div><h3 class="title"><a name="introtodocbook"></a>Introduction to DocBook</h3></div></div><p>
|
||
To understand DocBook, a basic understanding of SGML is
|
||
helpful. SGML stands for Standard General Markup Language and
|
||
is one of the first markup languages every created. HTML is
|
||
actually derived from SGML and XML is a subset of SGML. SGML
|
||
uses what is called a Document Type Definition to specify
|
||
<i>elements</i> which are contained between
|
||
brackets, < and >. Text is marked by both beginning and
|
||
ending elements, for example in the DocBook DTD, one denotes a
|
||
title with <tt><title></tt>The
|
||
Title<tt></title></tt>.
|
||
</p><p>
|
||
The DTD (in the case of the GDP, DocBook) defines rules for how the
|
||
elements can be used. For example, if one element can only be used when
|
||
embedded within another, this is defined in the DTD.
|
||
</p><p>
|
||
An SGML file is just a plain ASCII file containing the text
|
||
with the markup specified above. To convert it to some easily
|
||
readable format, you need special tools. The GDP uses <i>DocBook
|
||
Tools</i>, a free package of utilities for working with DocBook
|
||
which includes <i>Jade</i>, which does the SGML/DSSL
|
||
parsing. You can read more about DocBook Tools in <a href="#installingdocbook" title="Installing DocBook">the section called “Installing DocBook”</a>.
|
||
</p><p>
|
||
The final appearance of the output (e.g. PostScript or HTML)
|
||
is determined by a
|
||
<i>stylesheet</i>. Stylesheets are files,
|
||
written in a special language (DSSSL -- Document Style
|
||
Semantics and Specification Language), which specify the
|
||
appearance of various DocBook elements, for example,
|
||
what fonts to use for titles and various inline elements, page
|
||
numbering style, and much more. DocBook tools come with a
|
||
collection of stylesheets (Norman Walsh's modular
|
||
stylesheets); GNOME Document Project uses some customized
|
||
version of this stylesheets -- see <a href="#gdpstylesheets" title="GDP Stylesheets">the section called “GDP Stylesheets”</a>.
|
||
</p><p>
|
||
The advantage of specifying the <i>structure</i>
|
||
of a document with SGML instead of specifying the
|
||
<i>appearance</i> of the document with a typical
|
||
word processor, or with html, is that the resulting document
|
||
can be processed in a variety of ways using the structural
|
||
information. Whereas formatting a document for appearance
|
||
assumes a medium (typically written text on a standard-sized
|
||
piece of paper), SGML can be processed to produce output for a
|
||
large variety of media such as text, postscript, HTML,
|
||
Braille, audio, and potentially many other formats.
|
||
</p><p>
|
||
Using 'content' as the elements to define the text of a document also
|
||
allows for search engines to make use of the actual elements to make a
|
||
"smarter search". For example, if you are searching for all documents
|
||
written by the author "Susie" your search engine could be made smart
|
||
enough to only search <author> elements, making for a faster and more
|
||
accurate search.
|
||
</p><p>
|
||
Since the overall appearance of the output is determined not by the DTD
|
||
or the SGML document, but rather by a stylesheet, the appearance of a
|
||
document can be easily changed just by changing the stylesheet. This
|
||
allows everyone in the project to create documents that all look the
|
||
same.
|
||
</p><p>
|
||
As stated before, the GDP uses the DocBook DTD. For a list of
|
||
introductory and reference resources on DocBook, see <a href="#resources" title="Resources">the section called “Resources”</a>. The following sections also provide
|
||
convenient instructions on which markup tags to use in various
|
||
circumstances. Be sure to read <a href="#conventions" title="GDP Documentation Conventions ">the section called “GDP Documentation Conventions ”</a>
|
||
for GDP documentation-specific guidelines.
|
||
</p></div><div class="sect2"><a name="xml"></a><div class="titlepage"><div><h3 class="title"><a name="xml"></a>XML and SGML</h3></div></div><p> In not so distant future (probably before GNOME 2.0),
|
||
DocBook itself and GNOME Documentation project will migrate from
|
||
SGML to XML. This transition should be relatively painless:
|
||
(almost) all DocBook tags will remain the same. However, XML has
|
||
stricter syntax rules than SGML; thus, some constructions which
|
||
are valid in SGML will not be valid in XML. Therefore, to be
|
||
ready for this transistion, it is <i>strongly
|
||
advised</i> that the documentation writers conform to XML
|
||
syntax rules. Here are most important differences:
|
||
</p><div class="variablelist"><dl><dt><a name="id2921045"></a><span class="term"> <i>Minimization</i></span></dt><dd><p><a name="id2921063"></a>
|
||
It is possible with some implementations of SGML to use
|
||
minimizations to close elements in a document by using
|
||
</>, for example:
|
||
<tt><tt><title></tt>The
|
||
Title<tt></></tt></tt>. This is not
|
||
allowed in XML. You can use <b>sgmlnorm</b> command,
|
||
included in DocBook Tools package, to expand minimized tags;
|
||
if you are using Emacs with psgml
|
||
mode, you can also use menu command
|
||
Modify->Normalize.
|
||
</p></dd><dt><a name="id2921179"></a><span class="term"> <i>Self-closing tags</i></span></dt><dd><p><a name="id2921197"></a>
|
||
Also, in SGML some tags are allowed not to have closing
|
||
tags. For example, it is legal for
|
||
<tt><xref></tt> not to have a closing tag:
|
||
<tt><tt><xref
|
||
linkend="someid"></tt></tt>. In
|
||
XML, it is illegal; instead, you should use
|
||
<tt><tt><xref
|
||
linkend="someid"/></tt></tt> (note the
|
||
slash!).
|
||
</p></dd><dt><a name="id2921264"></a><span class="term"> <i>Case sensitive tags</i></span></dt><dd><p><a name="id2921281"></a>
|
||
In XML, unlike SGML, tags are case-senstive
|
||
<tt><title></tt> and
|
||
<tt><TITLE></tt> are different tags!
|
||
Therefore, please always use lowercase tags (except for
|
||
things like <tt>DOCTYPE, CDATA</tt> and
|
||
<tt>ENTITY</tt>, which are not DocBook tags).
|
||
</p></dd></dl></div></div><div class="sect2"><a name="structure"></a><div class="titlepage"><div><h3 class="title"><a name="structure"></a> Structure Elements</h3></div></div><div class="sect3"><a name="section"></a><div class="titlepage"><div><h4 class="title"><a name="section"></a>Sections and paragraphs</h4></div></div><p>
|
||
Top-level element of a book body must be
|
||
<tt><chapter></tt>; it may contain one or more
|
||
<tt><sect1></tt>, each of them may contain
|
||
<tt><sect2></tt> and so on up to
|
||
<tt><sect5></tt>. The top-level element of an
|
||
article body is always
|
||
<tt><sect1></tt>. Regardless of which elements
|
||
you use, give each structural element a unique id, so that
|
||
you can link to it. For usage example, see the template.
|
||
</p><p> Please try to avoid using deeply nested sections; for
|
||
most situations, <tt><sect1></tt> and
|
||
<tt><sect2></tt> should be sufficient. If not,
|
||
you probably should split your <tt><sect1></tt>
|
||
into several smaller ones.
|
||
</p><p> Use the tag <tt><para></tt> for
|
||
paragraphs, even if there is only one paragraph in a
|
||
section--see template for examples.
|
||
</p></div><div class="sect3"><a name="notes"></a><div class="titlepage"><div><h4 class="title"><a name="notes"></a>Notes, Warnings, And Tips</h4></div></div><p>
|
||
For notes, tips, warnings, and important information, which
|
||
should be set apart from the main text (usually as a
|
||
paragraph with some warning sign on the margin), use tags
|
||
<tt><note></tt>, <tt><tip></tt>,
|
||
<tt><warning></tt>,
|
||
<tt><important></tt> respectively. For example:
|
||
<pre class="programlisting">
|
||
|
||
<tip>
|
||
<title>TIP</title>
|
||
<para>
|
||
To speed up program compilation, use <application>gcc</application>
|
||
compiler with Pentium optimization.
|
||
</para>
|
||
</tip> </pre> produces
|
||
</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="extip"></a>TIP</h3><p>
|
||
To speed up program compilation, use
|
||
gcc compiler with Pentium
|
||
optimization. </p></div><p>
|
||
Note that this should not be inside a
|
||
<tt><para></tt> but between paragraphs.
|
||
</p></div><div class="sect3"><a name="figures"></a><div class="titlepage"><div><h4 class="title"><a name="figures"></a> Screenshots and other figures</h4></div></div><p>
|
||
To include screenshots and other figures, use the following
|
||
tags:
|
||
|
||
<pre class="programlisting">
|
||
|
||
<figure id="shot1">
|
||
<title>Screenshot</title>
|
||
<screenshot>
|
||
<screeninfo>Screenshot of a program</screeninfo>
|
||
<graphic format="PNG" fileref="figures/example_screenshot" srccredit="ME">
|
||
</graphic>
|
||
</screenshot>
|
||
</figure>
|
||
</pre>
|
||
replacing <tt>example_screenshot</tt> with the
|
||
actual file name (without extension). The result will look like this:
|
||
|
||
<div class="figure"><p><a name="shot1"></a><b>Figure 1. Screenshot</b></p><div class="screenshot"><p><img src="figures/example_screenshot"></p></div></div>
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2921804"></a>NOTE</h3><p>
|
||
Notice in this example that the screenshot file name does
|
||
not include the file type extension -- to find out
|
||
why, please read <a href="#jadeimages" title="Images in DocBook Tools">the section called “Images in DocBook Tools”</a>.
|
||
</p></div></div><div class="sect3"><a name="listing"></a><div class="titlepage"><div><h4 class="title"><a name="listing"></a>Program listings and terminal session</h4></div></div><p>
|
||
To show a file fragment--for example, program
|
||
listing--use <tt><programlisting></tt> tag:
|
||
<pre class="programlisting">
|
||
|
||
<programlisting>
|
||
[Desktop Entry]
|
||
Name=Gnumeric spreadsheet
|
||
Exec=gnumeric
|
||
Icon=gnome-gnumeric.png
|
||
Terminal=0
|
||
Type=Application
|
||
</programlisting>
|
||
</pre>
|
||
which produces
|
||
<pre class="programlisting">
|
||
[Desktop Entry]
|
||
Name=Gnumeric spreadsheet
|
||
Exec=gnumeric
|
||
Icon=gnome-gnumeric.png
|
||
Terminal=0
|
||
Type=Application
|
||
</pre>
|
||
As a matter of fact, all examples in this document were
|
||
produced using <tt><programlisting></tt>.
|
||
</p><p>
|
||
To show a record of terminal session--i.e., sequence of
|
||
commands entered at the command line--use
|
||
<tt><screen></tt> tag:
|
||
<pre class="programlisting">
|
||
|
||
<screen>
|
||
<prompt>bash$</prompt><userinput>make love</userinput>
|
||
make: *** No rule to make target `love'. Stop.
|
||
</screen>
|
||
</pre>
|
||
which produces
|
||
<pre class="screen">
|
||
<tt>bash$</tt><b><tt>make love</tt></b>
|
||
make: *** No rule to make target `love'. Stop.
|
||
</pre>
|
||
Note the use of tags <tt><prompt></tt> and
|
||
<tt><userinput></tt> for marking system prompt
|
||
and commands entered by user.
|
||
<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2922020"></a>NOTE</h3><p>
|
||
Note that both <tt><programlisting></tt>
|
||
and <tt><screen></tt> preserve linebreaks,
|
||
but interpret SGML tags (unlike LaTeX
|
||
verbatim environment). Take a look at
|
||
the source of this document to see how you can have SGML
|
||
tags literally shown but not interpreted,
|
||
</p></div>
|
||
</p></div><div class="sect3"><a name="lists"></a><div class="titlepage"><div><h4 class="title"><a name="lists"></a> Lists</h4></div></div><p>
|
||
The most common list types in DocBook are
|
||
<tt><itemizedlist></tt>,
|
||
<tt><orderedlist></tt>, and
|
||
<tt><variablelist></tt>.
|
||
</p><div class="variablelist"><dl><dt><a name="id2922139"></a><span class="term"> <tt><itemizedlist></tt></span></dt><dd><p><a name="id2922158"></a>
|
||
This is the simplest unnumbered list, parallel to
|
||
<tt><ul></tt> in HTML. Here is an example:
|
||
<pre class="programlisting">
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<guilabel>Show backup files</guilabel> &mdash; This will
|
||
show any backup file that might be on your system.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<guilabel>Show hidden files</guilabel> &mdash; This will
|
||
show all "dot files" or files that begin with a dot. This
|
||
files typically include configuration files and directories.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<guilabel>Mix files and directories</guilabel> &mdash; This
|
||
option will display files and directories in the order you
|
||
sort them instead of
|
||
always having directories shown above files.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
</pre>
|
||
and output:
|
||
</p><div class="itemizedlist"><ul><li><p><a name="id2922197"></a>
|
||
Show backup files --
|
||
This will show any backup file that might be on
|
||
your system.
|
||
</p></li><li><p><a name="id2922257"></a>
|
||
Show hidden files --
|
||
This will show all "dot files" or files that
|
||
begin with a dot. This files typically include
|
||
configuration files and directories.
|
||
</p></li><li><p><a name="id2922289"></a>
|
||
Mix files and directories
|
||
-- This option will display files and
|
||
directories in the order you sort them instead
|
||
of always having directories shown above files.
|
||
</p></li></ul></div><p> Note the use of <tt>&mdash;</tt>
|
||
for long dash (see <a href="#specsymb" title=" Special symbols ">the section called “ Special symbols ”</a>). Also,
|
||
please note that the result looks much nicer because the
|
||
terms being explained (Show backup
|
||
files, etc.) are set in a different font. In
|
||
this case, it was achieved by using <a href="#gui" title="GUI elements"><tt><guilabel></tt></a>
|
||
tag. In other cases, use appropriate tags such as
|
||
<a href="#gui" title="GUI elements"><tt><guimenuitem></tt></a>,
|
||
<a href="#filenames" title="Filenames, commands, and other
|
||
computer-related things"><tt><command></tt></a>,
|
||
or -- if none of
|
||
this applies -- use
|
||
<a href="#gui" title="GUI elements"><tt><emphasis></tt></a>.
|
||
</p></dd><dt><a name="id2922461"></a><span class="term"> <tt><orderedlist></tt></span></dt><dd><p><a name="id2922479"></a>
|
||
This list is completely analogous to
|
||
<tt><itemizedlist></tt> and has the same
|
||
syntax, but it produces numbered list. By default,
|
||
this list uses Arabic numerals for numbering entries;
|
||
you can override this using <tt>numeration</tt>,
|
||
for example <tt><orderedlist
|
||
numeration="lowerroman"></tt>. Possible values of
|
||
these attribute are <tt>arabic</tt>,
|
||
<tt>upperalpha</tt>,
|
||
<tt>loweralpha</tt>,
|
||
<tt>upperroman</tt>,
|
||
<tt>lowerroman</tt>.
|
||
</p></dd><dt><a name="id2922560"></a><span class="term"> <tt><variablelist></tt></span></dt><dd><p><a name="id2922579"></a> This list is used when each entry is
|
||
rather long, so it should be formatted as a block of text
|
||
with some subtitle, like a small subsection. The
|
||
<tt><variablelist></tt> is more complicated
|
||
than itemizedlists, but for larger blocks of text, or when
|
||
you're explaining or defining something, it's best to use
|
||
them. Their greatest advantage is that it's easier for a
|
||
computer to search. The lines you are reading now were
|
||
produced by <tt><variablelist></tt>. The
|
||
source looked liked this:
|
||
<pre class="programlisting">
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term> <sgmltag>&lt;itemizedlist></sgmltag></term>
|
||
<listitem><para>
|
||
This is the simplest unnumbered list, parallel to
|
||
<sgmltag>&lt;ul></sgmltag> in HTML. Here is an example:...
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term> <sgmltag>&lt;orderedlist></sgmltag></term>
|
||
<listitem><para>
|
||
This list is completely analogous to
|
||
<sgmltag>&lt;itemizedlist></sgmltag>
|
||
</para></listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term> <sgmltag>&lt;variablelist></sgmltag></term>
|
||
<listitem><para>
|
||
This list is used when each entry is rather long,...
|
||
</para></listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
|
||
</pre>
|
||
</p></dd></dl></div><p>
|
||
Lists can be nested; in this case, the stylesheets
|
||
are smart enough to change the numeration (for
|
||
<tt><orderedlist></tt>) or marks of each entry
|
||
(in <tt><itemizedlist></tt>) for sub-lists
|
||
</p></div></div><div class="sect2"><a name="inline"></a><div class="titlepage"><div><h3 class="title"><a name="inline"></a>Inline Elements</h3></div></div><div class="sect3"><a name="gui"></a><div class="titlepage"><div><h4 class="title"><a name="gui"></a>GUI elements</h4></div></div><div class="itemizedlist"><ul><li><p><a name="id2922748"></a>
|
||
<tt><guibutton></tt> -- used for
|
||
buttons, including checkbuttons and radio buttons
|
||
</p></li><li><p><a name="id2922775"></a>
|
||
<tt><guimenu></tt>,
|
||
<tt><guisubmenu></tt> --used for
|
||
top-level menus and submenus
|
||
respectively, for example <tt>
|
||
<guisubmenu>Utilities</guisubmenu> submenu of the
|
||
<guimenu>Main Menu</guimenu></tt>
|
||
</p></li><li><p><a name="id2922825"></a>
|
||
<tt><guimenuitem></tt>--an entry in a
|
||
menu
|
||
</p></li><li><p><a name="id2922849"></a>
|
||
<tt><guiicon></tt>--an icon
|
||
</p></li><li><p><a name="id2922874"></a>
|
||
<tt><guilabel></tt>--for items which have
|
||
labels, like tabs, or bounding boxes.
|
||
</p></li><li><p><a name="id2922899"></a>
|
||
<tt><interface></tt>-- for most everything
|
||
else... a window, a dialog box, the Panel, etc.
|
||
</p></li></ul></div><p>
|
||
If you need to refer to a sequence of menu choices, such as
|
||
Main Menu->Utilities->GNOME
|
||
terminal
|
||
there is a special construction for this, too:
|
||
<pre class="programlisting">
|
||
|
||
<menuchoice>
|
||
<guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
|
||
<guimenuitem>GNOME terminal</guimenuitem> </menuchoice>
|
||
</pre>
|
||
</p></div><div class="sect3"><a name="links"></a><div class="titlepage"><div><h4 class="title"><a name="links"></a>Links and references</h4></div></div><p>
|
||
To refer to another place in the same document, you can use
|
||
tags <tt><xref></tt> and
|
||
<tt><link></tt>. The first of them
|
||
automatically inserts the full name of the element you refer
|
||
to (section, figure, etc.), while the second just creates a
|
||
link (in HTML output). Here is an example:
|
||
<pre class="programlisting">
|
||
An example of a <link linkend="extip">tip</link> was given in
|
||
<xref linkend="notes" />.
|
||
</pre>
|
||
which produces: An example of a <a href="#extip">tip</a> was given in <a href="#notes" title="Notes, Warnings, And Tips">the section called “Notes, Warnings, And Tips”</a>.
|
||
</p><p>
|
||
Here <tt>notes</tt> and <tt>extip</tt>
|
||
are the id attributes of <a href="#notes" title="Notes, Warnings, And Tips">the section called “Notes, Warnings, And Tips”</a> and of the
|
||
example of a tip in it.
|
||
</p><p> To produce a link to an external source, such as a
|
||
Web page or a local file, use <tt><ulink></tt>
|
||
tag, for example:
|
||
<pre class="programlisting">
|
||
To find more about GNOME, please visit <ulink type="http"
|
||
url="http://www.gnome.org">GNOME Web page</ulink>
|
||
</pre>
|
||
which produces: To find more about GNOME, please visit
|
||
<a href="http://www.gnome.org" target="_top">The GNOME Web
|
||
Site</a> You can use any of the standard URL types, such
|
||
as <tt>http, ftp, file, telnet, mailto</tt> (in
|
||
most cases, however, use of <tt>mailto</tt> is
|
||
unnecessary--see discussion of
|
||
<tt><email></tt> tag).
|
||
</p></div><div class="sect3"><a name="filenames"></a><div class="titlepage"><div><h4 class="title"><a name="filenames"></a>Filenames, commands, and other
|
||
computer-related things</h4></div></div><p>
|
||
Here are some tags used to describe operating system-related
|
||
things:
|
||
</p><div class="itemizedlist"><ul><li><p><a name="id2923288"></a> <tt><filename></tt> -- used
|
||
for filenames,
|
||
e.g.<tt><filename></tt>
|
||
foo.sgml
|
||
<tt></filename></tt>
|
||
produces: <tt>foo.sgml</tt>.
|
||
</p></li><li><p><a name="id2923345"></a> <tt><filename
|
||
class="directory"></tt> -- used for
|
||
directories, e.g.<tt><filename
|
||
class="directory"></tt>/usr/bin
|
||
<tt></filename></tt>
|
||
produces: <tt>/usr/bin</tt>.
|
||
</p></li><li><p><a name="id2923408"></a>
|
||
<tt><application></tt> -- used for
|
||
application names,
|
||
e.g. <tt><application></tt>Gnumeric
|
||
<tt></application></tt> produces:
|
||
Gnumeric.
|
||
</p></li><li><p><a name="id2923463"></a>
|
||
<tt><envar></tt> -- used for
|
||
environment variables, e.g.
|
||
<tt><envar></tt>PATH<tt></envar></tt>.
|
||
</p></li><li><p><a name="id2923505"></a>
|
||
<tt><command></tt> -- used for
|
||
commands entered on command line, e.g.
|
||
<tt><command></tt>make install
|
||
<tt></command></tt> produces:
|
||
<b>make install</b>.
|
||
</p></li><li><p><a name="id2923561"></a>
|
||
<tt><replaceable></tt> -- used for
|
||
replaceable text, e.g.
|
||
<tt><command></tt>db2html<tt><replaceable></tt>
|
||
foo.sgml
|
||
<tt></replaceable></tt><tt></command></tt>
|
||
produces: <b>db2html
|
||
<i><tt>foo.sgml</tt></i></b>.
|
||
</p></li></ul></div></div><div class="sect3"><a name="keys"></a><div class="titlepage"><div><h4 class="title"><a name="keys"></a>Keyboard input</h4></div></div><p> To mark up text input by the user, use
|
||
<tt><userinput></tt>.
|
||
</p><p> To mark keystrokes such as shortcuts and other
|
||
commands, use <tt><keycap></tt>.
|
||
This is used for marking up what is printed on the top
|
||
of the physical key on the keyboard. There are a couple of
|
||
other tags for keys, too: <tt><keysym></tt>
|
||
and <tt><keycode></tt>. However you are
|
||
unlikely to need these for most documentation. For reference,
|
||
<tt><keysym></tt> is for the “symbolic
|
||
name” of a key. <tt><keycode></tt> is
|
||
for the “scan code” of a key. These are not
|
||
terms commonly required in GNOME documentation,
|
||
although <tt><keysym></tt> is useful for marking
|
||
up control codes.
|
||
</p><p>
|
||
To mark up a combination of keystrokes, use the
|
||
<tt><keycombo></tt> wrapper:
|
||
<pre class="programlisting">
|
||
|
||
<keycombo>
|
||
<keycap>Ctrl</keycap>
|
||
<keycap>Alt</keycap>
|
||
<keycap>F1</keycap>
|
||
</keycombo>
|
||
</pre>
|
||
</p><p>
|
||
Finally, if you want to show a shortcut for some menu
|
||
command, here are the appropriate tags (rather long):
|
||
<pre class="programlisting">
|
||
|
||
<menuchoice>
|
||
<shortcut>
|
||
<keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
|
||
</shortcut>
|
||
<guimenuitem> Quit</guimenuitem>
|
||
</menuchoice>
|
||
</pre>
|
||
which produces simply
|
||
Quit (<b>Ctrl-q</b>)
|
||
</p></div><div class="sect3"><a name="email"></a><div class="titlepage"><div><h4 class="title"><a name="email"></a>E-mail addresses</h4></div></div><p> To mark up e-mail
|
||
address, use <tt><email></tt>:
|
||
<pre class="programlisting">
|
||
The easiest way to get in touch with me is by e-mail
|
||
(<email>me@mydomain.com</email>)
|
||
</pre>
|
||
which produces: The easiest way to get in touch with me is
|
||
by e-mail (<tt><<a href="mailto:me@mydomain.com">me@mydomain.com</a>></tt>) Note that
|
||
<tt><email></tt> automatically produces a link
|
||
in html version.
|
||
</p></div><div class="sect3"><a name="specsymb"></a><div class="titlepage"><div><h4 class="title"><a name="specsymb"></a> Special symbols </h4></div></div><p>
|
||
DocBook also provides special means for entering
|
||
typographic symbols which can not be entered directly
|
||
form the keyboard (such as copyright sign). This is done using
|
||
<i>entities</i>, which is SGML analogue of
|
||
macros, or commands, of LaTeX. They generally have the form
|
||
<tt>&entityname;</tt>. Note that the semicolon
|
||
is required.
|
||
</p><p>
|
||
here is partial list of most commonly used enitites:
|
||
</p><div class="itemizedlist"><ul><li><p><a name="id2924022"></a>
|
||
<tt>&amp;</tt> -- ampersend (&)
|
||
</p></li><li><p><a name="id2924043"></a>
|
||
<tt>&lt;</tt> -- left angle bracket (<)
|
||
</p></li><li><p><a name="id2924062"></a>
|
||
<tt>&copy;</tt> -- copyright sign (©)
|
||
</p></li><li><p><a name="id2924080"></a>
|
||
<tt>&mdash;</tt> -- long dash (--)
|
||
</p></li><li><p><a name="id2924106"></a>
|
||
<tt>&hellip;</tt> -- ellipsis (...)
|
||
</p></li></ul></div><p>
|
||
Note that the actual look of the resulting symbols depends
|
||
on the fonts used by your browser; for example, it might
|
||
happen that long dash (<tt>&mdash;</tt>) looks
|
||
exactly like the usual dash (-). However, in the PostScript
|
||
(and thus, in print) the output will look markedly better if
|
||
you use appropriate tags.
|
||
</p></div></div></div><div class="sect1"><a name="conventions"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="conventions"></a>GDP Documentation Conventions </h2></div></div><div class="sect2"><a name="conventionsalldocs"></a><div class="titlepage"><div><h3 class="title"><a name="conventionsalldocs"></a>Conventions for All GDP Documentation</h3></div></div><div class="sect3"><a name="xmlcomp"></a><div class="titlepage"><div><h4 class="title"><a name="xmlcomp"></a> XML compatibility </h4></div></div><p>
|
||
All GNOME documentation should conform to XML syntax
|
||
requirements, which are stricter than SGML ones -- see
|
||
<a href="#xml" title="XML and SGML">the section called “XML and SGML”</a> for more informaion.
|
||
</p></div><div class="sect3"><a name="authorsnames"></a><div class="titlepage"><div><h4 class="title"><a name="authorsnames"></a> Authors' names</h4></div></div><p>
|
||
All GNOME documentation should contain the names of both the
|
||
application authors and documentation authors, as well as a
|
||
link to the application web page (if it exists) and
|
||
information for bug submission -- see templates for an
|
||
example.
|
||
</p></div></div><div class="sect2"><a name="conventionsappdocs"></a><div class="titlepage"><div><h3 class="title"><a name="conventionsappdocs"></a>Conventions for Application Documentation</h3></div></div><div class="sect3"><a name="applicationversionid"></a><div class="titlepage"><div><h4 class="title"><a name="applicationversionid"></a>Application Version Identification</h4></div></div><p>
|
||
Application documentation should identify the version of the
|
||
application for which the documentation is written:
|
||
<pre class="programlisting">
|
||
|
||
<sect1 id="intro">
|
||
<title>Introduction</title>
|
||
<para>
|
||
blah-blah-blah This document describes version 1.0.53 of gfoo.
|
||
</para>
|
||
</sect1>
|
||
</pre>
|
||
</p></div><div class="sect3"><a name="license"></a><div class="titlepage"><div><h4 class="title"><a name="license"></a> Copyright information </h4></div></div><p> Application
|
||
documentation should contain a copyright notice, stating the
|
||
licensing terms. It is suggested that you use the GNU Free
|
||
Documentation License. You could also use some other license
|
||
allowing free redistribution, such as GPL or Open Content
|
||
license. If documentation uses some trademarks (such as UNIX,
|
||
Linux, Windows, etc.), proper legal junk should also be
|
||
included (see templates).
|
||
</p></div><div class="sect3"><a name="license2"></a><div class="titlepage"><div><h4 class="title"><a name="license2"></a>Software license</h4></div></div><p>
|
||
All GNOME applications must contain information about the
|
||
license (for software, not for documentation), either in the
|
||
"About" box or in the manual.
|
||
</p></div><div class="sect3"><a name="bugtraq"></a><div class="titlepage"><div><h4 class="title"><a name="bugtraq"></a> Bug reporting</h4></div></div><p>
|
||
Application documentation should give an address for
|
||
reporting bugs and for submitting comments about the
|
||
documentaion (see templates for an example).
|
||
</p></div></div></div><div class="sect1"><a name="writingapplicationmanuals"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="writingapplicationmanuals"></a>Writing Application and Applet Manuals</h2></div></div><p>
|
||
Every GNOME application or applet should have a manual specific
|
||
to that particular application. This manual should be a complete
|
||
and authoritative guide. The manual should describe what the
|
||
program does and how to use it. Manuals will typically describe
|
||
each window or panel presented to the user using screenshots (in
|
||
PNG format only) when appropriate. They should also describe
|
||
each feature and preference option available.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2924548"></a>Documentation Availability</h3><p>
|
||
Applications and applets should not rely on documentation
|
||
which is only available on the internet. All manuals and
|
||
other documentation should be packaged with the application or
|
||
applet and be made available to the user through the standard
|
||
GNOME help system methods described below.
|
||
</p></div><p> Application manuals should be based on the template in
|
||
<a href="#template1" title="Template 1: Application Manual">the section called “Template 1: Application Manual”</a>. Applet manuals should be based on
|
||
the templates in <a href="#template2-1x" title="Template 2: Applet Manual For GNOME 1.x">the section called “Template 2: Applet Manual For GNOME 1.x”</a> for GNOME
|
||
versions 1.x and the templates in <a href="#template2-2x" title="Template 2: Applet Manual For GNOME 2.x">the section called “Template 2: Applet Manual For GNOME 2.x”</a>
|
||
for GNOME versions 2.x.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2924643"></a>Manuals For Large Applications</h3><p>
|
||
Manuals for very large applications, such as GNOME Workshop
|
||
components should be a <tt><book></tt> (and thus
|
||
use <tt><chapter></tt> for each primary section)
|
||
, instead of <tt><article></tt> which most
|
||
applications use(with each primary section being a
|
||
<tt><sect1></tt>).
|
||
</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2924700"></a>Applet Manuals in GNOME 2.0</h3><p>
|
||
Note that applet manuals in GNOME 2.0 are treated in a special
|
||
way. The manuals for all applets are merged into a single
|
||
virtual document by Nautilus. For this reason, the header
|
||
information for applet manuals is omitted and the first
|
||
section of each applet is
|
||
<tt><sect1></tt>. Applet manuals will typically
|
||
have several sections, each of which is
|
||
<tt><sect2></tt>.
|
||
</p></div><p>
|
||
Application manuals should be made available by having a
|
||
"Manual" entry in the Help pull-down menu
|
||
at the top of the
|
||
application, as described in <a href="#listingdocsinhelpmenu" title="Listing Documents in the Help Menu">the section called “Listing Documents in the Help Menu”</a>.
|
||
Applets should make their manuals available by
|
||
right-clicking on the applet.
|
||
</p></div><div class="sect1"><a name="listingdocsinhelpmenu"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="listingdocsinhelpmenu"></a>Listing Documents in the Help Menu</h2></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2924823"></a>Developer Information</h3><p>
|
||
This section is for developers. Documentation authors
|
||
generally do not need to know this material.
|
||
</p></div><p>
|
||
Typically the application manual and possibly additional help
|
||
documents will be made available to the user under the
|
||
Help menu at the top right of the
|
||
application. To do this, you must first write a
|
||
<tt>topic.dat</tt> file. The format for this file is:
|
||
<pre class="programlisting">
|
||
One line for each 'topic'.
|
||
|
||
Two columns, as defined by perl -e 'split(/\s+/,$aline,2)'
|
||
|
||
First column is the HTML file (and optional section) for the topic,
|
||
relative to the app's help file dir.
|
||
|
||
Second column is the user-visible topic name.
|
||
</pre>
|
||
For example, Gnumeric's
|
||
<tt>topic.dat</tt> file is:
|
||
<pre class="programlisting">
|
||
gnumeric.html Gnumeric manual
|
||
function-reference.html Gnumeric function reference
|
||
</pre>
|
||
When the application is installed, the
|
||
<tt>topic.dat</tt> file should be placed in the
|
||
<tt>$prefix/share/gnome/help/<i><tt>appname</tt></i>/C/</tt> directory
|
||
where <i><tt>appname</tt></i> is replaced by the
|
||
application's name. The application documentation (converted
|
||
from SGML into HTML with <b>db2html</b>) should be
|
||
placed in this directory too.
|
||
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2925011"></a>Note</h3><p>
|
||
If the help files are not present in the correct directory, the
|
||
menu items will NOT appear when the program is run.
|
||
</p></div><p>
|
||
The <tt>topic.dat</tt> file is used by the GNOME
|
||
menu building code to generate the Help
|
||
menu. When you define your menu:
|
||
<pre class="programlisting">
|
||
GnomeUIInfo helpmenu[] = {
|
||
{GNOME_APP_UI_ITEM,
|
||
N_("About"), N_("Info about this program"),
|
||
about_cb, NULL, NULL,
|
||
GNOME_APP_PIXMAP_STOCK, GNOME_STOCK_MENU_ABOUT,
|
||
0, 0, NULL},
|
||
GNOMEUIINFO_SEPARATOR,
|
||
GNOMEUIINFO_HELP("<i>appname</i>"),
|
||
GNOMEUIINFO_END
|
||
};
|
||
</pre>
|
||
the line specifying <tt>GNOMEUIINFO_HELP</tt> causes
|
||
GNOME to create a menu entry which is tied to the documentation
|
||
in the directory mentioned above. Also, all the topics in the
|
||
<tt>topic.dat</tt> file will get menu entries in the
|
||
Help menu. When the user selects any of these
|
||
topics from the Help menu, a help browser
|
||
will be started with the associated HTML documentation.
|
||
</p></div><div class="sect1"><a name="applicationhelpbuttons"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="applicationhelpbuttons"></a>Application Help Buttons</h2></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2925176"></a>Developer Information</h3><p>
|
||
This section is for developers. Documentation authors
|
||
generally do not need to know this material.
|
||
</p></div><p>
|
||
Most GNOME applications will have Help
|
||
buttons. These are most often seen in Preference windows. (All
|
||
Preference windows should have Help
|
||
buttons.) Most Help buttons will connect
|
||
to the application manual, although some may connect to special
|
||
documents. Because the Help buttons do
|
||
not generally have their own special documentation, the
|
||
documentation author(s) do not need to do very much. However,
|
||
the application author must be careful to guarantee that the
|
||
application correctly opens the help documentation when the
|
||
Help buttons are pressed.
|
||
</p><p>
|
||
To make the Help buttons call the correct document in the GNOME Help
|
||
Browser the developer should add code based on the following example:
|
||
</p><pre class="programlisting">
|
||
gchar *tmp;
|
||
tmp = gnome_help_file_find_file ("module", "page.html");
|
||
if (tmp) {
|
||
gnome_help_goto(0, tmp);
|
||
g_free(tmp);
|
||
}
|
||
</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2925314"></a>NOTE</h3><p>
|
||
The example above is in the C language, please refer to other
|
||
documentation or forums for other GNOME language bindings.
|
||
</p></div></div><div class="sect1"><a name="packagingappletdocs"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="packagingappletdocs"></a>Packaging Applet Documentation</h2></div></div><div class="sect2"><a name="appletfiles"></a><div class="titlepage"><div><h3 class="title"><a name="appletfiles"></a>Applet Documentation Files</h3></div></div><p>
|
||
In GNOME 2.0 each applet will have its own documentation
|
||
installed separately, and the GNOME 2.0 help
|
||
browser (Nautilus) will dynamically
|
||
merge the applet documents into a single virtual book
|
||
called <i>GNOME Applets</i>. During the
|
||
transitionary stage between GNOME 1.0 and GNOME 2.0, each
|
||
applet in the gnome-applets package has its own manual(stored
|
||
with the applet in CVS), but they are merged together manually
|
||
to create the <i>GNOME Applets</i> book before
|
||
distribution. Telsa
|
||
<tt><<a href="mailto:hobbit@aloss.ukuu.org.uk">hobbit@aloss.ukuu.org.uk</a>></tt> is the maintainer of
|
||
this document. Applet documentation should be sent to Telsa
|
||
(or placed in CVS) who will make sure they are correctly
|
||
packaged with the applets. The applet author should be
|
||
contacted to modify the menu items and help buttons to bind to
|
||
the applet documentation if necessary.
|
||
</p><p>
|
||
Images which are part of the applet documentation should be in
|
||
PNG format and should reside in the same directory as the SGML
|
||
document file in CVS(gnome-applets/APPLETNAME/help/C).
|
||
</p><p>
|
||
Applets which are not part of the gnome-applets package must
|
||
package their documentation with the particular applet
|
||
package. They should use the same applet template as other
|
||
applets. However, the <tt><xref></tt> links to
|
||
the introductory chapter of the <i>GNOME
|
||
Applets</i> book must be removed (as the 1.x
|
||
GNOME Help Browser does not allow
|
||
you to create links between separate documents) and replaced
|
||
with suitable text. Note that since this document is not part
|
||
of the <i>GNOME Applets</i> book, you must
|
||
remember to add <tt><legalnotice></tt> and
|
||
<tt><copyright></tt> sections.
|
||
</p></div><div class="sect2"><a name="appletmenu"></a><div class="titlepage"><div><h3 class="title"><a name="appletmenu"></a>Adding Documentation to an Applet Menu</h3></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><a name="id2925561"></a>Developer Information</h3><p>
|
||
This section is for developers. Documentation authors
|
||
generally do not need to know this material.
|
||
</p></div><p>
|
||
Applets should have About and
|
||
Manual menu items, typically as the first
|
||
and second top-most items in the menu respectively. This
|
||
section describes how the developer creates these menu items
|
||
and links them to the documentation.
|
||
</p><p>
|
||
To add an applet's manual to its applet menu, use:
|
||
<pre class="programlisting">
|
||
/* add an item to the applet menu */
|
||
applet_widget_register_callback(APPLET_WIDGET(applet), "manual",
|
||
_("Manual"), &open_manual, NULL);
|
||
</pre>
|
||
Here the second argument is an arbitrary name for the
|
||
callback, the third argument is the label which will appear
|
||
when the user right clicks on the applet, and the fourth
|
||
argument is the callback function.
|
||
</p><p>
|
||
You will need to write a simple callback function to open the
|
||
help browser to the appropriate document. This is done using
|
||
the <tt>gnome_help_file_find_file</tt> function,
|
||
as described in <a href="#applicationhelpbuttons" title="Application Help Buttons">the section called “Application Help Buttons”</a>.
|
||
</p><p>
|
||
You will also want to add an About menu
|
||
item to the applet's menu. This is a
|
||
stock menu item and is done:
|
||
<pre class="programlisting">
|
||
applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about",
|
||
GNOME_STOCK_MENU_ABOUT, _("About"), &my_applet_cb_about,
|
||
NULL);
|
||
</pre>
|
||
</p><p>
|
||
More information can be found at <a href="http://developer.gnome.org/doc/tutorials/applet/index.html" target="_top">Writing
|
||
GNOME panel applets using the GTK+/GTK-- widget set</a>.
|
||
</p></div></div><div class="sect1"><a name="writingcontextsensitivehelp"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="writingcontextsensitivehelp"></a>Writing Context Sensitive Help (coming in GNOME-2.0)</h2></div></div><p>
|
||
Context sensitive help, also known as "pop-up" help, will allow
|
||
a user to obtain help information about specific buttons or
|
||
parts of an application.
|
||
</p><p>
|
||
Context sensitive help is still under development and not all
|
||
the details are available at this time. However, the basics can
|
||
be shown here so that you can understand how the system will
|
||
work.
|
||
</p><p>
|
||
The Context Sensitive Help system is designed to allow the
|
||
developer to give an id to a particular portion of the User
|
||
Interface, for example, a button. Once the interface is complete
|
||
a Perl script can then be run against the interface code to
|
||
create a "map" file. This map file allows the developer or
|
||
writer to associate particular paragraph sections from an XML
|
||
document to the interface items.
|
||
</p><p>
|
||
The XML used for the document is a small XML DTD that is being
|
||
developed to use the same tags (albeit, much fewer) as DocBook
|
||
so that writers do not have to re-learn a new DTD.
|
||
</p><p>
|
||
Once the document is written and map file is complete, when the
|
||
user launches context sensitive help on the interface (either by
|
||
pressing a button and then clicking on the interface item they
|
||
want information on, or by right mouse clicking on the interface
|
||
item and selecting a pop-up menu item like "What's This") a
|
||
small transient window will appear with brief but detailed
|
||
information on the interface item.
|
||
</p></div><div class="sect1"><a name="referring"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="referring"></a>Referring to Other GNOME Documentation (coming in
|
||
GNOME-2.0)</h2></div></div><p>
|
||
In the GNOME 2.0 Help System, you will be able to create links
|
||
from one document to another. The exact mechanism for doing
|
||
this is in development.
|
||
</p></div><div class="sect1"><a name="basics"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="basics"></a>Basics of Documentation Style</h2></div></div><p>
|
||
Most people have never enjoyed reading a software manual, and
|
||
they probably never will. Many times, they'll read the
|
||
documentation only when they run into problems, and they'll be
|
||
frustrated and upset before they even read a word. On the
|
||
other hand, some readers will read the manual all the way
|
||
through, or at least look at the introduction before they
|
||
start. Your document might serve as a reference for an expert
|
||
or a guide to a beginner, and it must have enough depth to
|
||
satisfy the first without overwhelming the second. Ideally, it
|
||
will serve beginners as they <i>become</i>
|
||
experts. Remember, your goal is to produce <i>complete,
|
||
intuitive and clear</i> documentation.
|
||
</p><p>
|
||
In order to write useful documentation, you'll have to know who
|
||
your audience is likely to be. Then, you can look for the
|
||
problems they're likely to run into, and solve them. It will
|
||
also help if you focus on the tasks users will perform, and
|
||
group features accordingly, rather than simply describing
|
||
features at random.
|
||
</p><div class="sect2"><a name="styleplanning"></a><div class="titlepage"><div><h3 class="title"><a name="styleplanning"></a>Planning</h3></div></div><p>
|
||
Begin documenting by learning how to use the application and
|
||
reading over any existing documentation. Pay attention to
|
||
places where your document will differ from the template. It
|
||
may help to develop a document skeleton: a valid XML or SGML
|
||
document that has little or no content. For very large
|
||
applications, you will need to make significant departures
|
||
from the templates, since you'll be using the
|
||
<tt><book></tt> tag instead of
|
||
<tt><chapter></tt> or
|
||
<tt><article></tt>.
|
||
</p></div><div class="sect2"><a name="balance"></a><div class="titlepage"><div><h3 class="title"><a name="balance"></a>Achieving a Balanced Style</h3></div></div><p>
|
||
Just as you need to juggle expert and novice readers,
|
||
you'll have to juggle a number of other extremes as you write:
|
||
<div class="itemizedlist"><ul><li><p><a name="id2926120"></a>
|
||
Documents should be complete, yet concise. You should
|
||
describe every feature, but you'll have decide how much
|
||
detail is really necessary. It's not, for example,
|
||
necessary to describe every button and form field in a
|
||
dialog box, but you should make sure that your readers
|
||
know how to bring up the dialog and what it does. If
|
||
you spend fewer words on the obvious, you can spend more
|
||
time clarifying the ambiguous labels and explaining
|
||
items that are more complex.
|
||
</p></li><li><p><a name="id2926147"></a>
|
||
Be engaging and friendly, yet professional. Games
|
||
documents may be less formal than productivity
|
||
application documents (people don't
|
||
<i>use</i> games, they
|
||
<i>play</i> them), but all of them should
|
||
maintain a standard of style which holds the reader's
|
||
interest without resorting to jokes and untranslatable
|
||
allusions or puns.
|
||
</p></li><li><p><a name="id2926185"></a>
|
||
Examples, tips, notes, and screenshots are useful to
|
||
break up long stretches of text, but too many can get in
|
||
the way, and make your documents too choppy to read.
|
||
It's good to provide a screenshot of any dialog windows
|
||
a user might run into, but if a dialog box has several
|
||
tabs, it's not usually necessary to have one for each.
|
||
</p></li><li><p><a name="id2926209"></a>
|
||
The GDP strives to have all of its documentation conform
|
||
to certain standards of style and content, but every
|
||
document (and every writer) is different. You will need
|
||
to use your judgement, and write documents to fit with
|
||
the rest of the project, without compromising the
|
||
individual needs of your subject, or your own
|
||
individuality as a writer.
|
||
</p></li></ul></div>
|
||
</p></div><div class="sect2"><a name="stylestructure"></a><div class="titlepage"><div><h3 class="title"><a name="stylestructure"></a>Structure</h3></div></div><p>
|
||
In general, you won't have to worry too much about structure,
|
||
because the templates provide you with an excellent example.
|
||
As a general rule, try to follow that structural example.
|
||
That means using links, hierarchical nesting, and, if
|
||
necessary, a glossary or index. You probably won't need to
|
||
use every available structural tag, but take advantage of
|
||
what DocBook provides you.
|
||
</p><p>
|
||
As to linking, there's some disagreement about whether to use
|
||
<tt><xref></tt> <tt><link></tt>
|
||
when you make links within your documents. You'll have to
|
||
decide, based on the different ways that they are presented
|
||
in output, which is more appropriate given the context.
|
||
Regardless of which you use, you should not forget to use
|
||
them. Help your readers find information that relevant to
|
||
the issue at hand.
|
||
</p><p>
|
||
The table of contents will be generated automatically, but
|
||
you will probably have to develop your own index if you wish
|
||
to have one. The Nautilus Help Browser will have new, and
|
||
currently unknown, indexing capabilities, so index style and
|
||
structure are still under discussion. The GNOME User's Guide
|
||
will contain a glossary in its next versions; unless you're
|
||
writing a<tt><book></tt>, it will probably be best to
|
||
contribute to that rather than developing your own.
|
||
</p></div><div class="sect2"><a name="stylegrammar"></a><div class="titlepage"><div><h3 class="title"><a name="stylegrammar"></a>Grammar and Spelling</h3></div></div><p>
|
||
Nobody expects you to be perfect; they just expect the
|
||
documentation for their software to be error-free. That means
|
||
that, in the same way that developers look for bugs and accept
|
||
bug reports, writers must check for errors in their documents.
|
||
Poor grammar, bad spelling, and gross technical errors in
|
||
draft documents are fine. However, if those problems show up
|
||
in a "real" release, they can count against the credibility of
|
||
GNOME and Linux. They'll also make you look bad.
|
||
</p><p>
|
||
There is no substitute for a human proofreader; use a
|
||
spell-check program, then read it over yourself, and then find
|
||
someone else to help you. Other GDP members are, of course,
|
||
willing and able to help you, but non-writers are often at
|
||
least as helpful.
|
||
</p><p>
|
||
Proofreading documents is both a also a good way to
|
||
familiarize yourself with documentation, and it certainly
|
||
makes you valuable to the GDP. Help other writers proof their
|
||
documents, and they will help you with yours.
|
||
</p></div></div><div class="sect1"><a name="teamwork"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="teamwork"></a>Teamwork</h2></div></div><div class="sect2"><a name="teamworkgdp"></a><div class="titlepage"><div><h3 class="title"><a name="teamworkgdp"></a>Working With The GDP Team</h3></div></div><p>
|
||
The GDP team is a valuable resource for any documentation
|
||
author. GDP members can answer most questions documentation
|
||
authors have during the course of their work. It is also
|
||
important to make sure you are not duplicating work of other
|
||
GDP members by visiting the <i>GDP Documentation
|
||
Status Table</i> (<a href="http://www.gnome.org/gdp/doctable/" target="_top">http://www.gnome.org/gdp/doctable/</a>) and
|
||
assigning a documentation item to yourself. This table also
|
||
provides a forum for making suggestions and announcements for
|
||
each documentation item. The best way to get in touch with
|
||
GDP members is on the #docs IRC channel at irc.gnome.org or
|
||
else by emailing the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
|
||
<i>gnome-doc-list mailing list</i></a>.
|
||
</p><p>
|
||
After an author has finished a document (or even a draft
|
||
version of the document), it is a good idea to ask a member of
|
||
the GDP team to read the document, checking it for grammar,
|
||
proper DocBook markup, and clarity. One may typically find
|
||
another author to do this by either asking on the #docs IRC
|
||
channel at irc.gnome.org or by emailing the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
|
||
<i>gnome-doc-list mailing list</i></a>.
|
||
</p></div><div class="sect2"><a name="teamworkdevelopers"></a><div class="titlepage"><div><h3 class="title"><a name="teamworkdevelopers"></a>Working With Developers</h3></div></div><p>
|
||
Writing documentation typically involves a certain amount of
|
||
interaction with the developers of GNOME or the application
|
||
which is being documented. Often a document author will need
|
||
to ask the developer technical questions during the course of
|
||
writing a document. After the document is finished, it is good
|
||
idea to ask the developer to read the document to make sure it
|
||
is technically correct. The documentation author should also
|
||
make sure that the application author correctly binds and
|
||
packages the documentation with the application.
|
||
</p></div></div><div class="sect1"><a name="finishing"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="finishing"></a>Finishing A Document</h2></div></div><div class="sect2"><a name="editting"></a><div class="titlepage"><div><h3 class="title"><a name="editting"></a>Editing The Document</h3></div></div><p>
|
||
When the document is finished, the document should be edited
|
||
by another member of the GDP for spelling, clarity, and
|
||
DocBook markup. It should also be read by an application
|
||
author to make sure the document is technically accurate.
|
||
</p></div><div class="sect2"><a name="submitting"></a><div class="titlepage"><div><h3 class="title"><a name="submitting"></a>Submitting The Document</h3></div></div><p>
|
||
After the document has been edited and checked for technical
|
||
accuracy, it is ready to be combined with the application or
|
||
documentation package. This is typically done by passing the
|
||
document to the application or package developer. In some
|
||
cases, the documents can be committed directly into CVS,
|
||
however this should only be done after obtaining permission to
|
||
make CVS commits from the developer. Note that in many cases,
|
||
the application may need to be modified to correctly link to
|
||
the documentation. The packaging system (tarballs and binary
|
||
packages) may also need to be modified to include the
|
||
documentation in the package. Generally, this should be done
|
||
by the developers.
|
||
</p><p>
|
||
The final step is to email the GNOME Translation Team at
|
||
<tt><<a href="mailto:gnome-i18n@nuclecu.unam.mx">gnome-i18n@nuclecu.unam.mx</a>></tt> to notify them that
|
||
there is a new document for them to translate.
|
||
</p></div></div><div class="sect1"><a name="resources"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="resources"></a>Resources</h2></div></div><div class="sect2"><a name="resourcesweb"></a><div class="titlepage"><div><h3 class="title"><a name="resourcesweb"></a>Resources On The Web</h3></div></div><p> The <a href="http://developer.gnome.org/projects/gdp/" target="_top">GNOME
|
||
Documentation Project Web page</a> lists current GDP
|
||
projects and members.
|
||
</p><p>
|
||
The <a href="http://www.gnome.org/gdp/doctable/" target="_top">GDP Documentation Status Table</a> tracks the
|
||
status of all the various documentation components of GNOME.
|
||
</p><p>
|
||
Norman Walsh's <a href="http://www.docbook.org" target="_top"> <i>DocBook: The Definitive
|
||
Guide</i></a> in an excellent book on DocBook,
|
||
available both online and in print.
|
||
</p></div><div class="sect2"><a name="resourcesbooks"></a><div class="titlepage"><div><h3 class="title"><a name="resourcesbooks"></a>Books</h3></div></div><p>
|
||
Docbook: The Definitive Guide is available in both printed
|
||
form and on the web at:
|
||
<a href="http://www.docbook.org/tdg/index.html" target="_top">
|
||
<i>Docbook: The Definitive Guide</i>
|
||
</a>
|
||
</p></div><div class="sect2"><a name="mailinglists"></a><div class="titlepage"><div><h3 class="title"><a name="mailinglists"></a>Mailing Lists</h3></div></div><p>
|
||
The <i>gnome-docs-list</i> mailing list is the
|
||
main discussion area for all contributors to the GNOME
|
||
Documentation Project. You can find out how to subscribe to
|
||
this list on <a href="http://www.gnome.org/resources/mailing-lists.html" target="_top">GNOME Mailing Lists</a>. This is a rather
|
||
low-volume list, so you will not be flooded with messages.
|
||
</p></div><div class="sect2"><a name="irc"></a><div class="titlepage"><div><h3 class="title"><a name="irc"></a>IRC</h3></div></div><p>
|
||
Internet Relay Chat (IRC) is a fast and easy way to get in
|
||
touch with other GDP members. There are generally at least a
|
||
few members here who can answer questions or discuss
|
||
documentation issues. The IRC channel is #docs at
|
||
irc.gnome.org.
|
||
</p></div></div><div class="appendix"><h2 class="title" style="clear: both"><a name="templates"></a>A. Document Templates</h2><div class="sect1"><a name="template1"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="template1"></a>Template 1: Application Manual</h2></div></div><p>
|
||
The following template should be used for all application
|
||
manuals. You can always get the latest copy of this
|
||
template from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
|
||
Documentation Templates</a>.
|
||
<pre class="programlisting">
|
||
|
||
|
||
<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
|
||
<!-- if not using PNG graphic, replace reference above with
|
||
.....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
|
||
-->
|
||
<!ENTITY version "1.0.53">
|
||
<!-- replace version above with actual application version number-->
|
||
<!-- Template Version: 1.0.1 (do not remove this line) -->
|
||
]>
|
||
|
||
|
||
<!-- This is a GNOME documentation template, designed by the GNOME
|
||
Documentation Project Team. Please use it for writing GNOME
|
||
documentation, making obvious changes. In particular, all the words
|
||
written in UPPERCASE (with the exception of GNOME) should be
|
||
replaced. As for "legalnotice", please leave the reference
|
||
unchanged.
|
||
|
||
Remember that this is a guide, rather than a perfect model to follow
|
||
slavishly. Make your manual logical and readable. And don't forget
|
||
to remove these comments in your final documentation! ;-)
|
||
-->
|
||
|
||
<!-- =============Document Header ============================= -->
|
||
|
||
<article id="index"> <!-- please do not change the id -->
|
||
|
||
<artheader>
|
||
<title>MY-GNOME-APP</title>
|
||
<copyright>
|
||
<year>2000</year>
|
||
<holder>ME-THE-AUTHOR</holder>
|
||
</copyright>
|
||
|
||
<!-- translators: uncomment this:
|
||
|
||
<copyright>
|
||
<year>2000</year>
|
||
<holder>ME-THE-TRANSLATOR (Latin translation)</holder>
|
||
</copyright>
|
||
|
||
-->
|
||
|
||
<!-- do not put authorname in the header except in copyright - use
|
||
section "authors" below -->
|
||
|
||
<legalnotice>
|
||
<para>
|
||
Permission is granted to copy, distribute and/or modify this
|
||
document under the terms of the <citetitle>GNU Free
|
||
Documentation License</citetitle>, Version 1.1 or any later
|
||
version published by the Free Software Foundation with no
|
||
Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
||
Texts. You may obtain a copy of the <citetitle>GNU Free
|
||
Documentation License</citetitle> from the Free Software
|
||
Foundation by visiting <ulink type="http"
|
||
url="http://www.fsf.org">their Web site</ulink> or by writing
|
||
to: Free Software Foundation, Inc., 59 Temple Place - Suite
|
||
330, Boston, MA 02111-1307, USA.
|
||
</para>
|
||
<para>
|
||
Many of the names used by companies to distinguish their
|
||
products and services are claimed as trademarks. Where those
|
||
names appear in any GNOME documentation, and those trademarks
|
||
are made aware to the members of the GNOME Documentation
|
||
Project, the names have been printed in caps or initial caps.
|
||
</para>
|
||
</legalnotice>
|
||
|
||
<!-- this is the version of manual, not application -->
|
||
<releaseinfo>
|
||
This is version 1.0 of MY-GNOME-APP manual.
|
||
</releaseinfo>
|
||
|
||
</artheader>
|
||
|
||
<!-- ============= Document Body ============================= -->
|
||
|
||
<!-- ============= Introduction ============================== -->
|
||
<sect1 id="intro">
|
||
<title>Introduction</title>
|
||
|
||
<para>
|
||
<application>MY-GNOME-APP</application> is an application which
|
||
proves mathematical theorems. It has all the basic features
|
||
expected from a mathematical theorem prover, as well as a number
|
||
of advanced ones, such as proof by confusion. In fact, many of
|
||
the proofs produced by <application>MY-GNOME-APP</application>
|
||
are so complex that they are capable of proving almost anything
|
||
with a virtually null likelihood of being disproven. It also has
|
||
the very popular predecessor of proof by confusion, proof by
|
||
dialog, first implemented by Plato.
|
||
</para>
|
||
<para>
|
||
It also allows you to save and print theorem proofs and to add
|
||
comments to the proofs it produces.
|
||
</para>
|
||
|
||
<para>
|
||
To run <application>MY-GNOME-APP</application>, select
|
||
<menuchoice>
|
||
<guisubmenu>SUBMENU</guisubmenu>
|
||
<guimenuitem>MY-GNOME-APP</guimenuitem>
|
||
</menuchoice>
|
||
from the <guimenu>Main Menu</guimenu>, or type
|
||
<command>MYGNOMEAPP</command> on the command line.
|
||
</para>
|
||
|
||
<para>
|
||
<application>MY-GNOME-APP</application> is included in the
|
||
<filename>GNOME-PACKAGE</filename> package, which is part of the
|
||
GNOME desktop environment. This document describes version
|
||
&version; of <application>MY-GNOME-APP</application>.
|
||
</para>
|
||
</sect1>
|
||
|
||
|
||
<!-- ================ Usage ================================ -->
|
||
<!-- This section should describe basic usage of the application. -->
|
||
|
||
<sect1 id="usage">
|
||
<title>Using MY-GNOME-APP</title>
|
||
<para>
|
||
<application>MY-GNOME-APP</application> can be used to produce a
|
||
perfect proof of <emphasis>any</emphasis> mathematical theorem
|
||
(provided, of course, that this theorem is correct), thus
|
||
providing for new users an easy-to-use graphical interface to
|
||
modern mathematics. This section describes basic usage of
|
||
<application>MY-GNOME-APP</application>.
|
||
</para>
|
||
|
||
<!-- ========= Basic Usage =========================== -->
|
||
<sect2 id="mainwin">
|
||
<title>Basic usage</title>
|
||
<para>
|
||
Starting <application>MY-GNOME-APP</application> opens the
|
||
<interface>Main window</interface>, shown in <xref
|
||
linkend="mainwindow-fig">. The window is at first empty.
|
||
|
||
<!-- ==== Figure ==== -->
|
||
<figure id="mainwindow-fig">
|
||
<title>MY-GNOME-APP Main Window</title>
|
||
<screenshot>
|
||
<screeninfo>MY-GNOME-APP Main Window</screeninfo>
|
||
<graphic fileref="SCREENSHOT" format="png" srccredit="ME">
|
||
</graphic>
|
||
</screenshot>
|
||
</figure>
|
||
<!-- ==== End of Figure ==== -->
|
||
</para>
|
||
|
||
|
||
<!-- For this app, one could put "proving" or "edit" (probably even
|
||
both of them) as sect2's seperate from the main window
|
||
section. Since they were both so closely involved with the main
|
||
window, I decided to have them as sect3's isntead. Judgement
|
||
call. -->
|
||
|
||
<sect3 id="proving">
|
||
<title>Proving a Theorem</title>
|
||
<para>
|
||
To get a proof of a theorem, select
|
||
<menuchoice>
|
||
<guisubmenu>File</guisubmenu>
|
||
<guimenuitem>New</guimenuitem>
|
||
</menuchoice>,
|
||
which will
|
||
bring up the <interface>New Proof</interface> dialog box.
|
||
Enter the statement of the theorem in the
|
||
<guilabel>Theorem statement</guilabel> field, select your
|
||
desired proof type from the drop-down menu, and and press
|
||
<guibutton>Prove!</guibutton>.
|
||
</para>
|
||
<para>
|
||
If <application>MY-GNOME-APP</application> cannot prove the
|
||
theorem by the method you have chosen, or if you have not
|
||
selected a proof type at all,
|
||
<application>MY-GNOME-APP</application> will attempt to
|
||
choose the one that it thinks is most conclusive. In order,
|
||
it will attempt to prove the theorem with the following techniques:
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>Deduction</term>
|
||
<listitem>
|
||
<para>
|
||
This is a proof method that is generally accepted
|
||
for full credit by Logic professors.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>Induction</term>
|
||
<listitem>
|
||
<para>
|
||
This logical style will also earn you full credit on
|
||
your homework.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>Dialog</term>
|
||
<listitem>
|
||
<para>
|
||
This logical method is best for Philosophy classes,
|
||
and will probably only merit partial credit on Logic
|
||
or Mathematics homework.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>Confusion</term>
|
||
<listitem>
|
||
<para>
|
||
Suitable only for political debates, battles of wits
|
||
against the unarmed, and Philosophy classes focusing
|
||
on the works of Kant. Use with caution.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
|
||
<!-- You might want to include a note, warning, or tip, e.g. -->
|
||
|
||
<warning>
|
||
<title>Proving Incorrect Theorms</title>
|
||
<para>
|
||
<application>MY-GNOME-APP</application> cannot prove
|
||
incorrect theorems. If the theorem you have entered is not
|
||
demonstrably true, you will get a message to that effect
|
||
in the main window. To disprove a theorem, ask
|
||
<application>MY-GNOME-APP</application> to prove its
|
||
logical inverse.
|
||
</para>
|
||
</warning>
|
||
</sect3>
|
||
<sect3 id="editing">
|
||
<title>Editing Proofs</title>
|
||
<para>
|
||
Once you have proven the theorem, it will be displayed in
|
||
the <interface>main window</interface>. There, you can read
|
||
it over, choose text styles for different portions of it,
|
||
and make comments on it. This section will guide you through
|
||
that process.
|
||
</para>
|
||
<para>
|
||
To alter text styles, first select the statement you wish to
|
||
change by clicking on it once. You can select several
|
||
statements by Then, choose the style you want to apply from
|
||
the <guisubmenu>Style</guisubmenu> submenu of the
|
||
<guimenu>Edit</guimenu> menu.
|
||
<application>MY-GNOME-APP</application> will convert the
|
||
text to that style.
|
||
</para>
|
||
<para>
|
||
You can also enter comments on a statement by selecting that
|
||
statement, and then beginning to type. Comments will appear
|
||
after the statement you have selected.
|
||
</para>
|
||
|
||
<note>
|
||
<title>Altering The Proofs Themselves</title>
|
||
<para>
|
||
<application>MY-GNOME-APP</application> does not allow you
|
||
to alter a proof it has produced itself. You can, save
|
||
your proof as a plain text file (using the
|
||
<guimenuitem>Save as...</guimenuitem> menu), and alter it
|
||
that way. Be aware, however, that
|
||
<application>MY-GNOME-APP</application> uses its own file
|
||
format for saved proofs, and cannot re-open a file unless
|
||
it is in the .mga format.
|
||
</para>
|
||
</note>
|
||
</sect3>
|
||
|
||
|
||
<!-- If there are other functions performed from the main window,
|
||
they belong here. -->
|
||
|
||
</sect2>
|
||
|
||
<!-- =========================================================
|
||
Additional Sect2's should describe additional windows, such as
|
||
larger dialog boxes, or functionality that differs significantly
|
||
from the most immediate functions of the application. Make the
|
||
structure logical.
|
||
============================================================= -->
|
||
|
||
|
||
<sect2 id="toolbar">
|
||
<title>Toolbar</title>
|
||
<para>
|
||
The toolbar (shown in <xref linkend="figure-usage-toolbar">)
|
||
provides access to several commonly used routines.
|
||
<figure id="figure-usage-toolbar">
|
||
<title>MY-GNOME-APP Toolbar</title>
|
||
<screenshot>
|
||
<screeninfo>MY-GNOME-APP Toolbar</screeninfo>
|
||
<graphic fileref="usage-toolbar.png" format="png"></graphic>
|
||
</screenshot>
|
||
</figure>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>New</term>
|
||
<listitem>
|
||
<para>
|
||
Brings up the <interface>New Theorem</interface>
|
||
dialog.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>Open</term>
|
||
<listitem>
|
||
<para>
|
||
Open an exisiting theorem you want to prove, or a
|
||
completed proof you wish to print or format.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>Save</term>
|
||
<listitem>
|
||
<para>
|
||
Save the current theorem permanently in a
|
||
file.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</sect2>
|
||
<!-- ========= Menus =========================== -->
|
||
|
||
<sect2 id="menubar">
|
||
|
||
<!-- Describing the menubar ensures comprehensive feature
|
||
coverage. Nest itemizedlists inside variablelists so that each
|
||
menu is easily located by indexing software. Proper indentation
|
||
makes it easier! -->
|
||
|
||
<title>Menus</title>
|
||
<para>
|
||
The menu bar, located at the top of the <interface>Main
|
||
Window</interface>, contains the following menus:
|
||
</para>
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term><guimenu>File</guimenu></term>
|
||
<listitem>
|
||
<para>
|
||
This menu contains:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<menuchoice>
|
||
<shortcut>
|
||
<keycap>F3</keycap>
|
||
</shortcut>
|
||
<guimenuitem>Open</guimenuitem>
|
||
</menuchoice>
|
||
&mdash; This opens a file which is saved on your computer.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<menuchoice>
|
||
<shortcut>
|
||
<keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
|
||
</shortcut>
|
||
<guimenuitem>Save</guimenuitem>
|
||
</menuchoice>
|
||
&mdash; This saves your file.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<menuchoice>
|
||
<shortcut>
|
||
<keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo>
|
||
</shortcut>
|
||
<guimenuitem>Close</guimenuitem>
|
||
</menuchoice>
|
||
&mdash; This closes your file.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<menuchoice>
|
||
<shortcut>
|
||
<keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
|
||
</shortcut>
|
||
<guimenuitem>Exit</guimenuitem>
|
||
</menuchoice>
|
||
&mdash; This quits the application.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><guimenu>Edit</guimenu></term>
|
||
<listitem>
|
||
<para>
|
||
This menu contains:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<menuchoice>
|
||
<shortcut>
|
||
<keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo>
|
||
</shortcut>
|
||
<guimenuitem>Cut</guimenuitem>
|
||
</menuchoice>
|
||
&mdash; This removes any text or data which is selected and
|
||
places it in the buffer.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<menuchoice>
|
||
<shortcut>
|
||
<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
|
||
</shortcut>
|
||
<guimenuitem>Copy</guimenuitem>
|
||
</menuchoice>
|
||
&mdash; This copies any text or data which is selected into
|
||
the buffer.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<menuchoice>
|
||
<shortcut>
|
||
<keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo>
|
||
</shortcut>
|
||
<guimenuitem>Paste</guimenuitem>
|
||
</menuchoice>
|
||
&mdash; This pastes any text or data which is copied into
|
||
the buffer.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<guimenuitem>COMMAND1&hellip;</guimenuitem>
|
||
&mdash; This opens the <interface>COMMAND1</interface>
|
||
dialog, which is used to ....
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<guimenuitem>COMMAND2</guimenuitem>
|
||
&mdash; This ....
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
|
||
<varlistentry>
|
||
<term><guimenu>Settings</guimenu></term>
|
||
<listitem>
|
||
<para>
|
||
This menu contains:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<guimenuitem>Preferences&hellip;</guimenuitem>
|
||
&mdash; This opens the <link
|
||
linkend="prefs"><interface>Preferences
|
||
Dialog</interface></link>, which allows you to configure
|
||
many settings.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<guimenuitem>COMMAND3</guimenuitem> &mdash;
|
||
This command does something.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term><guimenu>Help</guimenu></term>
|
||
<listitem>
|
||
<para>
|
||
This menu contains:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<guimenuitem>Manual</guimenuitem> &mdash; This
|
||
opens the <application>GNOME Help
|
||
Browser</application> and displays this manual.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
<guimenuitem>About</guimenuitem> &mdash; This
|
||
opens the <interface>About</interface> dialog
|
||
which shows basic information about
|
||
<application>MY-GNOME-APP</application>, such as
|
||
the author's name, the application version number,
|
||
and the URL for the application's Web page if one
|
||
exists.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
|
||
|
||
<!-- ============= Customization ============================= -->
|
||
|
||
<sect1 id="prefs">
|
||
<title>Customization</title>
|
||
<para>
|
||
To change the application settings, select
|
||
<menuchoice>
|
||
<guimenu>Settings</guimenu>
|
||
<guimenuitem>Preferences...</guimenuitem>
|
||
</menuchoice>. This opens the
|
||
<interface>Preferences</interface> dialog, shown in <xref
|
||
linkend="preferences-fig">.
|
||
</para>
|
||
|
||
<figure id="preferences-fig">
|
||
<title>Preferences Dialog</title>
|
||
<screenshot>
|
||
<screeninfo>Preferences Dialog</screeninfo>
|
||
<graphic fileref="SCREENSHOT" format="png"
|
||
srccredit="ME">
|
||
</graphic>
|
||
</screenshot>
|
||
</figure>
|
||
|
||
<para>
|
||
The properties in the <guilabel>PREFSTABNAME</guilabel> tab are:
|
||
|
||
<!--many people use itemizedlists in cases like this. Variablelists
|
||
are more appropriate -->
|
||
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term> <guilabel>Default Text Style</guilabel></term>
|
||
<listitem>
|
||
<para>
|
||
Select the default text style for statements in your
|
||
proof. You can still change the style for individual
|
||
proofs or sections of a proof at a later date.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>(Configuration Item Label)</term>
|
||
<listitem>
|
||
<para>
|
||
(Description of Configuration)
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>(Configuration Item Label)</term>
|
||
<listitem>
|
||
<para>
|
||
(Description of Configuration)
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
|
||
<para>
|
||
The properties in the <guilabel>SECONDTABNAME</guilabel> tab are:
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>(Configuration Item Label)</term>
|
||
<listitem>
|
||
<para>
|
||
(Description of Configuration)
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
<varlistentry>
|
||
<term>(Configuration Item Label)</term>
|
||
<listitem>
|
||
<para>
|
||
(Description of Configuration)
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
|
||
<para>
|
||
After you have made all the changes you want, click on
|
||
<guibutton>OK</guibutton> to apply the changes and close the
|
||
<interface>Properties</interface> dialog. To cancel the changes
|
||
and return to previous values, click the
|
||
<guibutton>Close</guibutton> button.
|
||
</para>
|
||
|
||
</sect1>
|
||
|
||
|
||
<!-- ============= Various Sections ============================= -->
|
||
|
||
<!-- Here you should add, if necessary, several more sect1's,
|
||
describing other windows (besides the main one), file formats,
|
||
preferences dialogs, etc. as appropriate. Try not to make any of
|
||
these sections too long. -->
|
||
|
||
|
||
<!-- ============= Bugs ================================== -->
|
||
<!-- This section should describe known bugs and limitations of
|
||
the program if there are any - please be frank and list all
|
||
problems you know of. -->
|
||
<sect1 id="bugs">
|
||
<title>Known Bugs and Limitations</title>
|
||
<para>
|
||
This application has no known bugs.
|
||
</para>
|
||
</sect1>
|
||
|
||
|
||
<!-- ============= Authors ================================ -->
|
||
|
||
<sect1 id="authors">
|
||
<title>Authors</title>
|
||
<para>
|
||
<application>MY-GNOME-APP</application> was written by GNOME-HACKER
|
||
(<email>hacker@gnome.org</email>). To find more information about
|
||
<application>MY-GNOME-APP</application>, please visit the <ulink
|
||
url="http://www.my-gnome-app.org" type="http">MY-GNOME-APP Web
|
||
page</ulink>. Please send all comments, suggestions, and bug
|
||
reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
|
||
bug tracking database</ulink>. (Instructions for submitting bug
|
||
reports can be found <ulink
|
||
url="http://bugs.gnome.org/Reporting.html" type="http">
|
||
on-line</ulink>.) You can also use <application>Bug Report
|
||
Tool</application> (<command>bug-buddy</command>), available in the
|
||
<guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
|
||
Menu</guimenu>, for submitting bug reports.
|
||
</para>
|
||
|
||
<para>
|
||
This manual was written by ME
|
||
(<email>MYNAME@MYADDRESS</email>). Please send all comments and
|
||
suggestions regarding this manual to the <ulink type="http"
|
||
url="http://developer.gnome.org/projects/gdp">GNOME Documentation
|
||
Project</ulink> by sending an email to
|
||
<email>docs@gnome.org</email>. You can also add your comments online
|
||
by using the <ulink type="http"
|
||
url="http://www.gnome.org/gdp/doctable/">GNOME Documentation Status
|
||
Table</ulink>.
|
||
</para>
|
||
|
||
<!-- For translations: uncomment this:
|
||
|
||
<para>
|
||
Latin translation was done by ME
|
||
(<email>MYNAME@MYADDRESS</email>). Please send all comments and
|
||
suggestions regarding this translation to SOMEWHERE.
|
||
</para>
|
||
|
||
-->
|
||
|
||
</sect1>
|
||
|
||
|
||
<!-- ============= Application License ============================= -->
|
||
|
||
<sect1 id="license">
|
||
<title>License</title>
|
||
<para>
|
||
This program is free software; you can redistribute it and/or
|
||
modify it under the terms of the <citetitle>GNU General Public
|
||
License</citetitle> as published by the Free Software Foundation;
|
||
either version 2 of the License, or (at your option) any later
|
||
version.
|
||
</para>
|
||
<para>
|
||
This program is distributed in the hope that it will be useful, but
|
||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
<citetitle>GNU General Public License</citetitle> for more details.
|
||
</para>
|
||
<para>
|
||
A copy of the <citetitle>GNU General Public License</citetitle> is
|
||
included as an appendix to the <citetitle>GNOME Users
|
||
Guide</citetitle>. You may also obtain a copy of the
|
||
<citetitle>GNU General Public License</citetitle> from the Free
|
||
Software Foundation by visiting <ulink type="http"
|
||
url="http://www.fsf.org">their Web site</ulink> or by writing to
|
||
<address>
|
||
Free Software Foundation, Inc.
|
||
<street>59 Temple Place</street> - Suite 330
|
||
<city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
|
||
<country>USA</country>
|
||
</address>
|
||
</para>
|
||
</sect1>
|
||
</article>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</pre>
|
||
</p></div><div class="sect1"><a name="template2-1x"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="template2-1x"></a>Template 2: Applet Manual For GNOME 1.x</h2></div></div><p>
|
||
The following templates should be used for all applet
|
||
manuals in GNOME 1.x releases. You can always get the latest
|
||
copy of these templates from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
|
||
Documentation Templates</a>. Note that the template
|
||
consists of two files; the first file calls the second as an
|
||
entity. You should name the first file
|
||
<tt><i><tt>appletname</tt></i>-applet.sgml</tt>
|
||
and the second file should be named
|
||
<tt><i><tt>appletname</tt></i>.sgml</tt>,
|
||
where
|
||
<tt><i><tt>appletname</tt></i></tt> is
|
||
the name of the applet.
|
||
<pre class="programlisting">
|
||
|
||
|
||
<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
|
||
<!entity APPLETNAME.sgml SYSTEM "applet_template_1.sgml">
|
||
<!-- Template Version: 1.0.1 (do not remove this line) -->
|
||
]>
|
||
|
||
<!-- This is a GNOME documentation template, designed by the GNOME
|
||
Documentation Project Team. Please use it for writing GNOME
|
||
documentation, making obvious changes. In particular, all the words
|
||
written in UPPERCASE (with the exception of GNOME) should be
|
||
replaced. As for "legalnotice", please leave the reference
|
||
unchanged,make sure to add/remove trademarks to the list as
|
||
appropriate for your document.
|
||
|
||
Please don't forget to remove these comments in your final documentation,
|
||
thanks ;-).
|
||
-->
|
||
|
||
<article id="index"> <!-- please do not change the id -->
|
||
|
||
<!-- ============= Document Header ============================= -->
|
||
<artheader>
|
||
<title>APPLETNAME Applet</title>
|
||
<copyright>
|
||
<year>2000</year>
|
||
<holder>YOURFULLNAME</holder>
|
||
</copyright>
|
||
|
||
<!-- translators: uncomment this:
|
||
|
||
<copyright>
|
||
<year>2000</year>
|
||
<holder>ME-THE-TRANSLATOR (Latin translation)</holder>
|
||
</copyright>
|
||
|
||
-->
|
||
|
||
<!-- do not put authorname in the header except in copyright - use
|
||
section "authors" below -->
|
||
|
||
<legalnotice>
|
||
<para>
|
||
Permission is granted to copy, distribute and/or modify this
|
||
document under the terms of the <citetitle>GNU Free Documentation
|
||
License</citetitle>, Version 1.1 or any later version published
|
||
by the Free Software Foundation with no Invariant Sections, no
|
||
Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
|
||
of the <citetitle>GNU Free Documentation License</citetitle> from
|
||
the Free Software Foundation by visiting <ulink type="http"
|
||
url="http://www.fsf.org">their Web site</ulink> or by writing to:
|
||
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
|
||
Boston, MA 02111-1307, USA.
|
||
</para>
|
||
<para>
|
||
Many of the names used by companies to distinguish their products and
|
||
services are claimed as trademarks. Where those names appear in any
|
||
GNOME documentation, and those trademarks are made aware to the members
|
||
of the GNOME Documentation Project, the names have been printed in caps
|
||
or initial caps.
|
||
</para>
|
||
</legalnotice>
|
||
|
||
<releaseinfo>
|
||
This is version XXX of the APPLETNAME applet manual.
|
||
</releaseinfo>
|
||
</artheader>
|
||
|
||
<!-- ============= Document Body ============================= -->
|
||
|
||
&APPLETNAME.sgml;
|
||
|
||
</article>
|
||
|
||
|
||
|
||
|
||
|
||
</pre>
|
||
<pre class="programlisting">
|
||
|
||
<!-- Template Version: 1.0.1 (do not remove this line) -->
|
||
|
||
<sect1 id="APPLET">
|
||
<title>APPLET Applet</title>
|
||
|
||
<para>
|
||
<application>APPLET</application> applet, shown in <xref
|
||
linkend="APPLETapplet-fig">, allows you to &hellip;. To add this
|
||
applet to a <interface>Panel</interface>,
|
||
right-click on the <interface>Panel</interface> and choose
|
||
<menuchoice>
|
||
<guimenu>Panel</guimenu>
|
||
<guisubmenu>Add to panel</guisubmenu>
|
||
<guisubmenu>Applet</guisubmenu>
|
||
<guisubmenu>SECTION</guisubmenu>
|
||
<guimenuitem>APPLET</guimenuitem>
|
||
</menuchoice>.
|
||
</para>
|
||
|
||
<figure id="APPLETapplet-fig">
|
||
<title>APPLET Applet</title>
|
||
<screenshot>
|
||
<screeninfo>APPLET Applet</screeninfo>
|
||
<graphic format="png" fileref="APPLET_applet"
|
||
srccredit="YOURNAME">
|
||
</graphic>
|
||
</screenshot>
|
||
</figure>
|
||
|
||
<!-- ============= Usage ================================ -->
|
||
<sect2 id="APPLET-usage">
|
||
<title>Usage</title>
|
||
<para>
|
||
(Place a short description of how to use the applet here.)
|
||
</para>
|
||
|
||
<para>
|
||
Right-clicking on the applet brings up a menu containing the
|
||
following items:
|
||
<itemizedlist>
|
||
|
||
<listitem>
|
||
<para>
|
||
<guimenuitem>Properties&hellip;</guimenuitem> &mdash;
|
||
opens the <link linkend="APPLET-prefs">
|
||
<guilabel>Properties</guilabel></link> dialog.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
<guimenuitem>Help</guimenuitem> &mdash;
|
||
displays this document.
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
<guimenuitem>About&hellip;</guimenuitem> &mdash;
|
||
shows basic information about <application>APPLET
|
||
Applet</application>, including the applet's version and the
|
||
author's name.
|
||
</para>
|
||
</listitem>
|
||
|
||
</itemizedlist>
|
||
</para>
|
||
</sect2>
|
||
|
||
|
||
<!-- ============= Customization ============================= -->
|
||
<sect2 id="APPLET-prefs">
|
||
<title>Customization</title>
|
||
<para>
|
||
You can customize <application>APPLET</application>
|
||
applet by right-clicking on it and choosing
|
||
<guimenuitem>Properties&hellip;</guimenuitem>. This will open the
|
||
<interface>Properties</interface> dialog(shown in <xref
|
||
linkend="APPLET-settings-fig">), which allows you to
|
||
change various settings.
|
||
</para>
|
||
|
||
<figure id="APPLET-settings-fig">
|
||
<title>Properties dialog</title>
|
||
<screenshot>
|
||
<screeninfo>Properties dialog</screeninfo>
|
||
<graphic format="png" fileref="APPLET_settings"
|
||
srccredit="YOURNAME">
|
||
</graphic>
|
||
</screenshot>
|
||
</figure>
|
||
|
||
<para>
|
||
The properties are:
|
||
<itemizedlist>
|
||
|
||
<listitem>
|
||
<para>
|
||
(Configuration Item Label) &mdash; If this button is
|
||
checked&hellip;(description)
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
(Configuration Item Label) &mdash; Selecting this
|
||
button&hellip;(description)
|
||
</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
(Configuration Item Label) &mdash; Enter the name of
|
||
&hellip;(description)
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
|
||
<para>
|
||
After you have made all the changes you want, click on
|
||
<guibutton>OK</guibutton> to apply the changes and close the
|
||
<interface>Properties</interface> dialog. To cancel the changes
|
||
and return to previous values, click the
|
||
<guibutton>Close</guibutton> button.
|
||
</para>
|
||
</sect2>
|
||
|
||
|
||
<!-- ============= Bugs ================================== -->
|
||
<!-- This section should describe known bugs and limitations of
|
||
the program if there are any - please be frank and list all
|
||
problems you know of -->
|
||
<sect2 id="bugs">
|
||
<title>Known Bugs and Limitations</title>
|
||
<para>
|
||
This applet has no known bugs.
|
||
</para>
|
||
</sect2>
|
||
|
||
|
||
<!-- ============= Authors ================================ -->
|
||
|
||
<sect2 id="authors">
|
||
<title>Authors</title>
|
||
<para>
|
||
<application>APPLET</application> was written by GNOME-HACKER
|
||
(<email>hacker@gnome.org</email>). Please send all comments,
|
||
suggestions, and bug
|
||
reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
|
||
bug tracking database</ulink>. (Instructions for submitting bug
|
||
reports can be found <ulink
|
||
url="http://bugs.gnome.org/Reporting.html" type="http">
|
||
on-line</ulink>. You can also use <application>Bug Report
|
||
Tool</application> (<command>bug-buddy</command>), available in the
|
||
<guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
|
||
Menu</guimenu>, for submitting bug reports.
|
||
</para>
|
||
|
||
<para>
|
||
This manual was written by ME
|
||
(<email>MYNAME@MYADDRESS</email>). Please send all comments and
|
||
suggestions regarding this manual to the <ulink type="http"
|
||
url="http://developer.gnome.org/projects/gdp">GNOME Documentation
|
||
Project</ulink> by sending an email to
|
||
<email>docs@gnome.org</email>. You can also submit comments online
|
||
by using the <ulink type="http"
|
||
url="http://www.gnome.org/gdp/doctable/">GNOME Documentation
|
||
Status Table</ulink>.
|
||
</para>
|
||
|
||
<!-- For translations: uncomment this:
|
||
|
||
<para>
|
||
Latin translation was done by ME
|
||
(<email>MYNAME@MYADDRESS</email>). Please send all comments and
|
||
suggestions regarding this translation to SOMEWHERE.
|
||
</para>
|
||
|
||
-->
|
||
|
||
</sect2>
|
||
|
||
|
||
<!-- ============= Application License ============================= -->
|
||
|
||
<sect2 id="license">
|
||
<title>License</title>
|
||
<para>
|
||
This program is free software; you can redistribute it and/or
|
||
modify it under the terms of the <citetitle>GNU General Public
|
||
License</citetitle> as published by the Free Software Foundation;
|
||
either version 2 of the License, or (at your option) any later
|
||
version.
|
||
</para>
|
||
<para>
|
||
This program is distributed in the hope that it will be useful, but
|
||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||
<citetitle>GNU General Public License</citetitle> for more details.
|
||
</para>
|
||
<para>
|
||
A copy of the <citetitle>GNU General Public License</citetitle> is
|
||
included as an appendix to the <citetitle>GNOME Users
|
||
Guide</citetitle>. You may also obtain a copy of the
|
||
<citetitle>GNU General Public License</citetitle> from the Free
|
||
Software Foundation by visiting <ulink type="http"
|
||
url="http://www.fsf.org">their Web site</ulink> or by writing to
|
||
<address>
|
||
Free Software Foundation, Inc.
|
||
<street>59 Temple Place</street> - Suite 330
|
||
<city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
|
||
<country>USA</country>
|
||
</address>
|
||
</para>
|
||
</sect2>
|
||
|
||
</sect1>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</pre>
|
||
</p></div><div class="sect1"><a name="template2-2x"></a><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="template2-2x"></a>Template 2: Applet Manual For GNOME 2.x</h2></div></div><p>
|
||
The following templates should be used for all applet
|
||
manuals in GNOME 2.x releases. You can always get the latest
|
||
copy of these templates from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
|
||
Documentation Templates</a>.
|
||
</p><p>
|
||
Note that this template consists of two files. The first file
|
||
is an introductory chapter. You should not modify this
|
||
chapter. The second file is the actual applet document, which
|
||
you should modify to describe the applet you are documenting.
|
||
You can name the first file whatever you like, such as
|
||
<tt>gnome-applets.sgml</tt>. Name the second file
|
||
according to the applet's name:
|
||
<tt><i><tt>appletname</tt></i>-applet.sgml</tt>.
|
||
Make sure you update the entity
|
||
at the top of the shell document to reflect the new name of
|
||
the applet document.
|
||
</p><p>
|
||
<pre class="programlisting">
|
||
|
||
<!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
|
||
<!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part">
|
||
|
||
]>
|
||
|
||
<book id="gnome-applets">
|
||
|
||
<bookinfo>
|
||
<title>GNOME Applets</title>
|
||
<authorgroup>
|
||
<author><firstname>Telsa</firstname><surname>Gwynne</surname></author>
|
||
<author><firstname>John</firstname><surname>Fleck</surname></author>
|
||
<author><firstname>David</firstname><surname>Mason</surname>
|
||
<affiliation><orgname>Red Hat, Inc.</orgname></affiliation>
|
||
</author>
|
||
<author><firstname>Dan</firstname><surname>Mueth</surname></author>
|
||
<author><firstname>Alexander</firstname><surname>Kirillov</surname></author>
|
||
</authorgroup>
|
||
<edition>GNOME Applets version 0.1 for GNOME 1.1.5</edition>
|
||
<pubdate>2000</pubdate>
|
||
<copyright>
|
||
<year>2000</year>
|
||
<holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and
|
||
Alexander Kirillov</holder>
|
||
</copyright>
|
||
<legalnotice>
|
||
<para>
|
||
Permission is granted to make and distribute verbatim copies of this
|
||
manual provided the copyright notice and this permission notice are
|
||
preserved on all copies.
|
||
</para>
|
||
<para>
|
||
Permission is granted to copy and distribute modified versions of
|
||
this manual under the conditions for verbatim copying, provided that
|
||
the entire resulting derived work is distributed under the terms of a
|
||
permission notice identical to this one.
|
||
</para>
|
||
<para>
|
||
Permission is granted to copy and distribute translations of this
|
||
manual into another language, under the above conditions for modified
|
||
versions, except that this permission notice may be stated in a
|
||
translation approved by the Free Software Foundation.
|
||
</para>
|
||
<para>
|
||
Many of the names used by companies to distinguish their products and
|
||
services are claimed as trademarks. Where those names appear in any
|
||
GNOME documentation, and those trademarks are made aware to the members
|
||
of the GNOME Documentation Project, the names have been printed in caps
|
||
or initial caps.
|
||
</para>
|
||
</legalnotice>
|
||
</bookinfo>
|
||
|
||
<!-- #### Introduction ###### -->
|
||
<chapter id="applets-intro">
|
||
<title>Introduction</title>
|
||
|
||
<!-- #### Intro | What Are Applets? ###### -->
|
||
<sect1 id="applets-what-are">
|
||
<title>What Are Applets?</title>
|
||
<para>
|
||
Applets are one of the most popular and useful objects you can add
|
||
to your <interface>Panel</interface> to customize your desktop.
|
||
An applet is a small application which runs inside a small area of
|
||
your <interface>Panel</interface>. Applets have been written for
|
||
a wide range of purposes. Some are very powerful interactive
|
||
tools, such as the <application>Tasklist</application> Applet
|
||
which allows you to easily
|
||
control all of your main applications. Others are simple system
|
||
monitors, displaying information such as the amount of power left
|
||
in the battery on your laptop (see <application>Battery Charge
|
||
Monitor</application>) or weather
|
||
information(see <application>GNOME Weather</application>). Some
|
||
are simply for amusement(see <application>Fish</application>).
|
||
</para>
|
||
|
||
<para>
|
||
Applets are similar to swallowed applications in that both of them
|
||
reside within the <interface>Panel</interface>. However,
|
||
swallowed applications are generally applications which were
|
||
not designed to run within the <interface>Panel</interface>.
|
||
Typically one will swallow an application which already exists in
|
||
the main <interface>desktop</interface> area, putting it into your
|
||
<interface>Panel</interface>. The application will continue to
|
||
run in the <interface>Panel</interface> until you end the
|
||
application or unswallow it, placing it back onto the main part of
|
||
your desktop when you need to.
|
||
</para>
|
||
|
||
<para>
|
||
<figure id="example-applets-fig">
|
||
<title>Example Applets</title>
|
||
<screenshot>
|
||
<screeninfo>Example Applets</screeninfo>
|
||
<graphic fileref="example_applets" format="png"
|
||
srccredit="muet">
|
||
</graphic>
|
||
</screenshot>
|
||
</figure>
|
||
Several example applets are shown in <xref
|
||
linkend="example-applets-fig">. From left to right, they are: (1)
|
||
<application>Mixer Applet</application>, which allows you to turn
|
||
on/off sound and control its volume by clicking on the applet. (2)
|
||
<application>Sound Monitor</application> Applet, which displays
|
||
the current volume of sound being played and allows you to control
|
||
various sound features. (3) <application>GTCD</application>
|
||
Applet, a CD player which has all its controls
|
||
available in the applet and displays the track and time. (4)
|
||
<application>Drive Mount</application> Applet, used to mount and
|
||
unmount drives with a single click of the mouse. (5)
|
||
<application>Desk Guide</application> which allows you to view
|
||
and control multiple virtual screens. (6)
|
||
<application>Tasklist</application> Applet which allows you to
|
||
control your various windows and applications.
|
||
</para>
|
||
<para>
|
||
There are many other applets to choose from. The rest of this
|
||
chapter will explain the basic information to get you started
|
||
adding, moving, and removing applets from your
|
||
<interface>Panels</interface> and using them. The following
|
||
chapters go through each of the standard GNOME applets describing
|
||
them in detail. There are also additional applets which can be
|
||
downloaded off the Web. See <ulink type="http"
|
||
url="http://www.gnome.org/applist/list-martin.phtml">The GNOME
|
||
Software Map</ulink> for lists of additional GNOME applications
|
||
and applets.
|
||
</para>
|
||
<para>
|
||
As you read through the the rest of this chapter, you should try
|
||
adding and removing applets from your <interface>Panel</interface> and
|
||
experiment with them freely.
|
||
</para>
|
||
</sect1>
|
||
|
||
<!-- #### Intro | Adding, Moving, and Removing Applets ###### -->
|
||
<sect1 id="applet-add-move-replace">
|
||
<title>Adding, Moving, and Removing Applets</title>
|
||
|
||
<sect2 id="adding-applets">
|
||
<title>Adding Applets to a Panel</title>
|
||
<para>
|
||
To add an applet to a <interface>Panel</interface>, right-click
|
||
on the <interface>Panel</interface> and select
|
||
<menuchoice><guimenu>Panel</guimenu><guisubmenu>Add to panel</guisubmenu>
|
||
<guisubmenu>Applet</guisubmenu></menuchoice>. This will show you
|
||
the menu of all the applets on your system, divided into
|
||
categories. Choosing any applet from this menu will add it to the
|
||
<interface>Panel</interface>.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="moving-applets">
|
||
<title>Moving Applets In or Between Panels</title>
|
||
<para>
|
||
It is easy to move applets in a <interface>Panel</interface> or
|
||
between two <interface>Panels</interface>. If you have a
|
||
three-button mouse, just move the mouse over the applet, depress
|
||
the middle mouse button and drag the applet to its new location,
|
||
releasing the middle mouse button when you are finished. Note
|
||
that you can drag applets within a <interface>Panel</interface>
|
||
or between two <interface>Panels</interface> this way. If you
|
||
don't have a three-button mouse, just
|
||
right-click on the applet and choose
|
||
<guimenuitem>Move</guimenuitem>. The cursor will turn into a
|
||
cross and the applet will move with your mouse until you press
|
||
any mouse button to indicate you are finished moving it.
|
||
If, in the course of this movement, it hits
|
||
other objects, the behavior depends on the global preferences
|
||
you have set for your <interface>Panels</interface> in the
|
||
<application>GNOME Control Center</application>: the applet you are
|
||
moving can switch places with other objects, "push" all objects
|
||
it meets, or "jump" over all other objects without disturbing
|
||
them. You can also override the default behavior by holding
|
||
<keycap>Shift</keycap> button (for "push" mode),
|
||
<keycap>Ctrl</keycap> (for "switched" mode), or
|
||
<keycap>Alt</keycap> (for "free" mode, i.e. jumping other other
|
||
objects without disturbing them) button while dragging.
|
||
</para>
|
||
<para>
|
||
To change the global Panel preferences, right-click on any applet
|
||
or <interface>Panel</interface> and select
|
||
<menuchoice>
|
||
<guimenu>Panel</guimenu>
|
||
<guimenuitem>Global Preferences...</guimenuitem>
|
||
</menuchoice>.
|
||
The <guilabel>Default movement mode</guilabel> is set under the
|
||
<guilabel>Applets</guilabel> tab.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="removing-applets">
|
||
<title>Removing Applets from a Panel</title>
|
||
<para>
|
||
To remove an applet from a <interface>Panel</interface>,
|
||
right-click on the applet and select <guimenuitem>Remove from
|
||
panel...</guimenuitem>.
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
|
||
<!-- #### Intro | The Right-Click Pop-Up Menu ###### -->
|
||
<sect1 id="right-click-pop-up-menu">
|
||
<title>The Right-Click Pop-Up Menu</title>
|
||
<para>
|
||
Clicking the right mouse button on any applet brings up
|
||
a <guimenu>pop-up menu</guimenu>. This
|
||
menu always has certain standard menu items in it and
|
||
often has additional items which vary depending on the particular
|
||
applet.
|
||
</para>
|
||
<sect2 id="standard-right-click-items">
|
||
<title>Standard Pop-Up Items</title>
|
||
<para>
|
||
All applets should have the following items in their right-click
|
||
<guimenu>pop-up menu</guimenu>:
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>Remove from panel</term>
|
||
<listitem>
|
||
<para>
|
||
The <guimenuitem>Remove from panel</guimenuitem> menu item
|
||
removes the applet from the <interface>Panel</interface>.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>Move</term>
|
||
<listitem>
|
||
<para>
|
||
After selecting <guimenuitem>Move</guimenuitem>, your mouse
|
||
pointer will change appearance (typically to a cross with
|
||
arrows in each direction). As you move your mouse, the applet
|
||
will move with it. When you have finished moving the applet,
|
||
click any mouse button and the applet will anchor in its
|
||
current position. Note that applets can be moved between two
|
||
<interface>Panels</interface> this way.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>Panel</term>
|
||
<listitem>
|
||
<para>
|
||
The <guisubmenu>Panel</guisubmenu> submenu contains various
|
||
items and submenus for adding and removing
|
||
<interface>Panels</interface> and applets and for changing
|
||
the configuration.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>About</term>
|
||
<listitem>
|
||
<para>
|
||
The <guimenuitem>About...</guimenuitem> menu item brings up a
|
||
dialogue box containing various information about the applet,
|
||
typically including the applet's name, version, author,
|
||
copyright, license and desciption.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
|
||
<varlistentry>
|
||
<term>Help</term>
|
||
<listitem>
|
||
<para>
|
||
The <guimenuitem>Help</guimenuitem> menu item brings up the help
|
||
manual for the applet.
|
||
</para>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="applet-properties-dialog">
|
||
<title>The Applet Properties Dialog</title>
|
||
<para>
|
||
Many applets have customizable properties. These applets will
|
||
have a <guimenuitem>Properties...</guimenuitem> menu item in their
|
||
right-click <guimenu>pop-up menu</guimenu> which brings up the
|
||
<interface>Properties</interface> dialog where you can alter the
|
||
appearance or behaviour of the applet.
|
||
<figure id="example-props-dialog-fig">
|
||
<title>An Example Applet Properties Dialog</title>
|
||
<screenshot>
|
||
<screeninfo>An Example Applets Properties Dialog</screeninfo>
|
||
<graphic fileref="applet_props_dialog" format="png"
|
||
srccredit="muet">
|
||
</graphic>
|
||
</screenshot>
|
||
</figure>
|
||
All <interface>Properties</interface> dialogs have the following
|
||
buttons at the bottom of the dialog:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<guibutton>OK</guibutton> &mdash;
|
||
Pressing <guibutton>OK</guibutton> will activate any changes
|
||
in the properties you have made and close the
|
||
<interface>Properties</interface> dialog.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<guibutton>Apply</guibutton> &mdash;
|
||
Pressing <guibutton>Apply</guibutton> at any time will
|
||
make your changes active without closing the
|
||
<interface>Properties</interface> dialog. This is helpful if
|
||
you would like to test the effects of the changes you have
|
||
made but may want to continue changing the properties.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<guibutton>Close</guibutton> &mdash;
|
||
Pressing <guibutton>Close</guibutton> will close the
|
||
<interface>Properties</interface> dialog. Only changes in the
|
||
configuration which were previously applied with the
|
||
<guibutton>Apply</guibutton> button will persist. Other
|
||
changes will not be made active.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<guibutton>Help</guibutton> &mdash;
|
||
Pressing <guibutton>Help</guibutton> brings up the manual for
|
||
the application, opening it to the page describing the
|
||
<interface>Properties</interface> dialog.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="common-right-click-items">
|
||
<title>Other Common Pop-Up Items</title>
|
||
<para>
|
||
Many applets also have one or more of the following items in their
|
||
right-click pop-up menu:
|
||
<variablelist>
|
||
<varlistentry>
|
||
<term>Run...</term>
|
||
<listitem>
|
||
<para>
|
||
The <guimenuitem>Run...</guimenuitem> menu item generally
|
||
invokes a program which is related to the applet in some way
|
||
but which runs in its own window rather than in the
|
||
panel. For example:
|
||
</para>
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>
|
||
The <application>CPU Load</application> applet, which monitors
|
||
what programs are running, has a <guimenuitem>Run
|
||
gtop...</guimenuitem> menu item. Selecting this menu item
|
||
starts <application>GTop</application>, which allows you to
|
||
view and control programs which are running.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
The <application>CD Player</application> applet has a
|
||
<guimenuitem>Run gtcd...</guimenuitem> menu item which
|
||
starts the GNOME <application>CD Player</application> when
|
||
selected, which has more capabilities than the applet.
|
||
</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
</listitem>
|
||
</varlistentry>
|
||
</variablelist>
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
|
||
<sect1 id="feedback">
|
||
<title>Feedback</title>
|
||
<sect2 id="reporting-bugs">
|
||
<title>Reporting Applet Bugs</title>
|
||
<para>
|
||
GNOME users are encouraged to report bugs to <ulink type="http"
|
||
url="http://bugs.gnome.org">The GNOME Bug Tracking
|
||
System</ulink>. The easiest way to submit bugs is to use the
|
||
<application>Bug Report Tool</application> program by selecting
|
||
<menuchoice>
|
||
<guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
|
||
<guimenuitem>Bug Report Tool</guimenuitem>
|
||
</menuchoice>.
|
||
Be sure to be complete in describing what you did to cause the
|
||
bug to surface and, if possible, describe how the developer can
|
||
reproduce the the scenario.
|
||
</para>
|
||
</sect2>
|
||
<sect2 id="documentation-feedback">
|
||
<title>Providing Feedback</title>
|
||
<para>
|
||
GNOME users are welcome to provide suggestions for how
|
||
applications and documentation can be improved. Suggestions for
|
||
application changes should be submitted using the
|
||
<application>Bug Report Tool</application> discussed above.
|
||
Suggestions for documentation changes can be emailed directly to
|
||
the documentation author (whose email should be included in the
|
||
"Authors" section of the document) or by sending an email to
|
||
<email>docs@gnome.org</email>.
|
||
</para>
|
||
</sect2>
|
||
<sect2 id="joining-gnome">
|
||
<title>Joining GNOME</title>
|
||
<para>
|
||
GNOME is a community project, created by hundreds of programmers,
|
||
documentation writers, icon design artists, web masters, and
|
||
other people, most of whom work on a volunteer basis. New GNOME
|
||
contributors are always welcome. To join the GNOME team, visit
|
||
these web sites: developers &mdash; <ulink type="http"
|
||
url="http://developer.gnome.org">The GNOME Development
|
||
Site</ulink>, documentation writers &mdash; <ulink type="http"
|
||
url="http://developer.gnome.org/projects/gdp">The GNOME Documentation
|
||
Project</ulink>, icon design artists &mdash; <ulink type="http"
|
||
url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>,
|
||
general &mdash; <ulink type="http"
|
||
url="http://developer.gnome.org/helping/">Helping GNOME</ulink>,
|
||
or just join the gnome-list email list (see <ulink type="http"
|
||
url="http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing
|
||
Lists</ulink>) to discuss what you are interested in doing.
|
||
</para>
|
||
</sect2>
|
||
</sect1>
|
||
</chapter>
|
||
|
||
<!-- ############### Template Applets ##################### -->
|
||
<chapter id="template-applets">
|
||
<title>Template Applets</title>
|
||
|
||
&TEMPLATE-APPLET
|
||
|
||
</chapter>
|
||
|
||
</book>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</pre>
|
||
|
||
<pre class="programlisting">
|
||
|
||
|
||
<!-- Please replace everywhere below GNOMEAPPLET with the name of -->
|
||
<!-- your applet. Most importantly, all id attributes should start -->
|
||
<!-- with the name of your applet - this is necessary to avoid name -->
|
||
<!-- conflict among different applets -->
|
||
<!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email-->
|
||
<!-- Please replace HACKER-NAME with the applet author's name and -->
|
||
<!-- HACKER-EMAIL with the applet author's email -->
|
||
|
||
<!-- You should name your file: GNOMEAPPLET-applet.sgml -->
|
||
<!-- Screenshots should be in PNG format and placed in the -->
|
||
<!-- same directory as GNOMEAPPLET-applet.sgml -->
|
||
|
||
<!-- Applet docs will be merged into <chapter>'s inside a -->
|
||
<!-- <book>. Thus, the indentation below (2 spaces before the <sect1>) is -->
|
||
<!-- correct.-->
|
||
|
||
<!-- Permission is granted to make and distribute verbatim copies of -->
|
||
<!-- this manual provided the copyright notice and this permission -->
|
||
<!-- notice are preserved on all copies. -->
|
||
<!-- -->
|
||
<!-- Permission is granted to copy and distribute modified versions of -->
|
||
<!-- this manual under the conditions for verbatim copying, provided -->
|
||
<!-- that the entire resulting derived work is distributed under the -->
|
||
<!-- terms of a permission notice identical to this one. -->
|
||
<!-- -->
|
||
<!-- Permission is granted to copy and distribute translations of this -->
|
||
<!-- manual into another language, under the above conditions for -->
|
||
<!-- modified versions, except that this permission notice may be -->
|
||
<!-- stated in a translation approved by the Foundation. -->
|
||
|
||
<!-- ############### GNOMEAPPLET ############### -->
|
||
<sect1 id="GNOMEAPPLET">
|
||
<title>GNOMEAPPLET Applet</title>
|
||
|
||
<para>
|
||
<application>GNOMEAPPLET</application> applet, shown in <xref
|
||
linkend="GNOMEAPPLET-fig">, does this and that. To learn how to
|
||
add this applet to a <interface>Panel</interface>, see <xref
|
||
linkend="adding-applets">.
|
||
</para>
|
||
|
||
|
||
<figure id="GNOMEAPPLET-fig">
|
||
<title>GNOMEAPPLET</title>
|
||
<screenshot>
|
||
<screeninfo>GNOMEAPPLET</screeninfo>
|
||
<graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME">
|
||
</graphic>
|
||
</screenshot>
|
||
</figure>
|
||
|
||
<sect2 id="GNOMEAPPLET-usage">
|
||
<title>Usage</title>
|
||
<para>
|
||
This applet does nothing. To use it, just
|
||
left-click on it and it will instantly do nothing.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="GNOMEAPPLET-right-click">
|
||
<title>Right-Click Pop-Up Menu Items</title>
|
||
<para>
|
||
In addition to the standard menu items (see <xref
|
||
linkend="standard-right-click-items">), the right-click pop-up menu has
|
||
the following items:
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>
|
||
<guimenuitem>Properties...</guimenuitem> &mdash; This menu
|
||
item opens the <interface>Properties</interface> dialog (see
|
||
<xref linkend="GNOMEAPPLET-properties">) which allows you to
|
||
customize the appearance and behavior of this applet.
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
<guimenuitem>Run Hello World...</guimenuitem> &mdash; This
|
||
menu item starts the program <application>Hello
|
||
World</application>, used to say "hello" to the world.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="GNOMEAPPLET-properties">
|
||
<title>Properties</title>
|
||
<para>
|
||
You can configure <application>GNOMEAPPLET</application> applet by
|
||
right-clicking on the applet and choosing the
|
||
<guimenuitem>Properties...</guimenuitem> menu item. This will open the
|
||
<interface>Properties</interface> dialog, shown in <xref
|
||
linkend="GNOMEAPPLET-properties-fig">.
|
||
</para>
|
||
<figure id="GNOMEAPPLET-properties-fig">
|
||
<title>Properties Dialog</title>
|
||
<screenshot>
|
||
<screeninfo>Properties Dialog</screeninfo>
|
||
<graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME">
|
||
</graphic>
|
||
</screenshot>
|
||
</figure>
|
||
|
||
<para>
|
||
To change the color of the applet, click on the
|
||
<guibutton>color</guibutton> button. To change other properties,
|
||
click on other buttons.
|
||
</para>
|
||
|
||
<para>
|
||
For more information on the <interface>Properties</interface>
|
||
dialog, including descriptions of the <guibutton>OK</guibutton>,
|
||
<guibutton>Apply</guibutton>, <guibutton>Cancel</guibutton>, and
|
||
<guibutton>Help</guibutton> buttons, see <xref
|
||
linkend="applet-properties-dialog">.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="GNOMEAPPLET-bugs">
|
||
<title> Known Bugs and Limitations</title>
|
||
<para>
|
||
There are no known bugs in the
|
||
<application>GNOMEAPPLET</application> applet.
|
||
</para>
|
||
</sect2>
|
||
|
||
<sect2 id="GNOMEAPPLET-authors">
|
||
<title>Authors</title>
|
||
<para>
|
||
This applet was writen by HACKER-NAME
|
||
<email>HACKER-EMAIL</email>. The documentation for this applet
|
||
which you are reading now was written by
|
||
YOUR-NAME <email>YOUR-EMAIL</email>. For information on submitting
|
||
bug reports and suggestions for improvements, see <xref
|
||
linkend="feedback">.
|
||
</para>
|
||
</sect2>
|
||
|
||
</sect1>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</pre>
|
||
</p></div></div></div></body></html>
|