You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
4449 lines
166 KiB
4449 lines
166 KiB
<?xml version="1.0"?>
|
|
<!DOCTYPE article [
|
|
<!ENTITY version "1.0.53">
|
|
<!ENTITY mdash "--">
|
|
<!ENTITY hellip "...">
|
|
<!ENTITY copy "©"> <!-- COPYRIGHT SIGN -->
|
|
<!-- replace version above with actual application version number-->
|
|
<!-- Template Version: 1.0.1 (do not remove this line) -->
|
|
|
|
|
|
|
|
<!ENTITY APPLET-TEMPLATE-1x-SHELL SYSTEM
|
|
"templates/applet_template_1-applet.sgml.cdata">
|
|
<!ENTITY APPLET-TEMPLATE-1x SYSTEM
|
|
"templates/applet_template_1.sgml.cdata">
|
|
]>
|
|
|
|
<!-- Version: 1.0.1 -->
|
|
|
|
<article id="index">
|
|
<articleinfo>
|
|
|
|
<authorgroup>
|
|
|
|
<author>
|
|
<firstname>David</firstname>
|
|
<surname>Mason</surname>
|
|
<affiliation>
|
|
<orgname>Red Hat, Inc.</orgname>
|
|
<address>
|
|
<email>dcm@redhat.com</email>
|
|
</address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<author>
|
|
<firstname>Daniel</firstname>
|
|
<surname>Mueth</surname>
|
|
<affiliation>
|
|
<address>
|
|
<email>d-mueth@uchicago.edu</email>
|
|
</address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
<author>
|
|
<firstname>Alexander</firstname>
|
|
<surname>Kirillov</surname>
|
|
<affiliation>
|
|
<address>
|
|
<email>kirillov@math.sunysb.edu</email>
|
|
</address>
|
|
</affiliation>
|
|
</author>
|
|
|
|
</authorgroup>
|
|
|
|
<releaseinfo>
|
|
This is a pre-release!
|
|
</releaseinfo>
|
|
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>
|
|
0.99
|
|
</revnumber>
|
|
<date>
|
|
04.10.2000
|
|
</date>
|
|
</revision>
|
|
</revhistory>
|
|
|
|
<copyright>
|
|
<year>2000</year>
|
|
<holder>Red Hat, Inc., Daniel Mueth, and Alexander Kirillov</holder>
|
|
</copyright>
|
|
|
|
<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>
|
|
|
|
<title>The GNOME Handbook of Writing Software Documentation</title>
|
|
|
|
</articleinfo>
|
|
|
|
<!-- ################# Introduction ############### -->
|
|
|
|
<sect1 id="intro">
|
|
<title>Introduction</title>
|
|
|
|
<!-- ####### Introduction | The GNOME Documentation Project ####### -->
|
|
|
|
<sect2 id="gdp">
|
|
<title>The GNOME Documentation Project</title>
|
|
|
|
<sect3 id="goals">
|
|
<title>Goals</title>
|
|
<para>
|
|
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
|
|
<application>GNOME Help Browser</application>, 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 <ulink url="http://developer.gnome.org/doc/API/"
|
|
type="http">APIs for the GNOME libraries</ulink>, <ulink
|
|
url="http://developer.gnome.org/doc/whitepapers/"
|
|
type="http"><citetitle>GNOME White
|
|
Papers</citetitle></ulink>, GNOME developer <ulink
|
|
url="http://developer.gnome.org/doc/tutorials/"
|
|
type="http">tutorials</ulink>, the <ulink
|
|
url="http://developer.gnome.org/doc/FAQ/"
|
|
type="http"><citetitle>GNOME Developer
|
|
FAQ</citetitle></ulink>, the <ulink
|
|
url="http://developer.gnome.org" type="http">GNOME
|
|
Developer's Website</ulink>, and <citetitle>GNOME
|
|
Handbook</citetitle>'s, such as the one you are reading.
|
|
User documentation include the <ulink
|
|
url="http://www.gnome.org/learn/"
|
|
type="http"><citetitle>GNOME User's
|
|
Guide</citetitle></ulink>, the <ulink
|
|
url="http://www.gnome.org/learn/"
|
|
type="http"><citetitle>GNOME FAQ</citetitle></ulink>, and
|
|
GNOME application documentation. Most GNOME applications
|
|
have their own manual in addition to context sensitive help.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="joining">
|
|
<title>Joining the GDP</title>
|
|
<para>
|
|
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
|
|
<ulink url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
|
|
<citetitle>gnome-doc-list mailing list</citetitle> </ulink>.
|
|
Read <xref linkend="gettingstarted" />, 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
|
|
<ulink url="http://developer.gnome.org/projects/gdp">
|
|
<citetitle>GDP Website</citetitle></ulink>.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="collaborating">
|
|
<title>Collaborating with the GDP</title>
|
|
<para>
|
|
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 <ulink
|
|
url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
|
|
<citetitle>gnome-doc-list mailing list</citetitle> </ulink>
|
|
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.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<!-- ####### Introduction | Notation and Conventions ####### -->
|
|
|
|
<sect2 id="notation">
|
|
<title>Notation and Conventions</title>
|
|
<para>
|
|
This Handbook uses the following notation:
|
|
<informaltable frame="none">
|
|
<tgroup cols="2">
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<filename class="directory">/usr/bin</filename>
|
|
</entry>
|
|
<entry>
|
|
Directory
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<filename>foo.sgml</filename>
|
|
</entry>
|
|
<entry>
|
|
Filename
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<command>command</command>
|
|
</entry>
|
|
<entry>
|
|
Command or text that would be typed.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<command><replaceable>replaceable</replaceable></command>
|
|
</entry>
|
|
<entry>
|
|
"Variable" text that can be replaced.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>Program or Doc Code</literal>
|
|
</entry>
|
|
<entry>Program or document code</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- ####### Introduction | About This Handbook ####### -->
|
|
|
|
<sect2 id="about">
|
|
<title>About This Handbook</title>
|
|
<para>
|
|
This Handbook is a guide for both writing documentation for
|
|
GNOME components and applications and for properly binding and
|
|
packaging documentation into GNOME applications.
|
|
</para>
|
|
<para>
|
|
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
|
|
<ulink
|
|
url="http://developer.gnome.org/projects/gdp/handbook.html">
|
|
<citetitle>Getting The GNOME Handbook of Writing Software
|
|
Documentation</citetitle> </ulink>. Alternately, one may
|
|
download it anonymously from GNOME CVS under <filename
|
|
class="directory">gnome-docu/gdp</filename>.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!-- ################# Getting Started ############### -->
|
|
|
|
<sect1 id="gettingstarted">
|
|
<title>Getting Started Writing GNOME Documentation</title>
|
|
|
|
<!--####### Getting Started | Selecting A Document ####### -->
|
|
|
|
<sect2 id="selecting">
|
|
<title>Selecting A Document</title>
|
|
|
|
<sect3 id="know">
|
|
<title>Document Something You Know</title>
|
|
<para>
|
|
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 <emphasis>assign</emphasis> 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.
|
|
</para>
|
|
<para>
|
|
It is also important to spend some time with GNOME to make
|
|
sure you are familiar enough with it to be
|
|
<emphasis>authoritative</emphasis> 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.
|
|
</para>
|
|
<para>
|
|
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 <email>docs@gnome.org</email>.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="doctable">
|
|
<title>The GNOME Documentation Status Table</title>
|
|
<para>
|
|
The <citetitle>GDP Documentation Status Table</citetitle>
|
|
(<citetitle>DocTable</citetitle>) (<ulink
|
|
url="http://www.gnome.org/gdp/doctable/"
|
|
type="http">http://www.gnome.org/gdp/doctable/</ulink>) 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.
|
|
</para>
|
|
<para>
|
|
You should use the <citetitle>DocTable</citetitle> 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 <citetitle>DocTable</citetitle> also allows
|
|
people to make announcements and suggestions and to discuss
|
|
issues in the comments section.
|
|
</para>
|
|
<note>
|
|
<title>Note</title>
|
|
<para>
|
|
Note that the information in the
|
|
<citetitle>DocTable</citetitle> 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.
|
|
</para>
|
|
</note>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<!-- ####### Getting Started | Installing And Using DocBook ####### -->
|
|
|
|
<sect2 id="docbook">
|
|
<title>Installing and Using DocBook</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<note>
|
|
<title>NOTE</title>
|
|
<para>
|
|
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 <ulink
|
|
url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
|
|
<citetitle>gnome-doc-list mailing list</citetitle>
|
|
</ulink>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.
|
|
</para>
|
|
</note>
|
|
<sect3 id="installingdocbook">
|
|
<title>Installing DocBook</title>
|
|
<para>
|
|
Download and install the following <ulink
|
|
url="ftp://sourceware.cygnus.com:/pub/docbook-tools/"
|
|
type="ftp">DocBook Tools packages</ulink>: 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 <filename class="directory">noarch</filename>
|
|
directory.) You can find more
|
|
information on DocBook Tools <ulink url="
|
|
http://sourceware.cygnus.com/docbook-tools/"
|
|
type="http">here</ulink>.
|
|
</para>
|
|
<para>
|
|
If you are an <application>Emacs</application> user you may
|
|
want to grab the psgml package as well. This is a major mode
|
|
for editing sgml files in <application>Emacs</application>.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="gdpstylesheets">
|
|
<title>GDP Stylesheets</title>
|
|
<para>
|
|
The GDP uses its own DocBook stylesheets. To use the GDP
|
|
stylesheets, you should download the file
|
|
<filename>gdp-both.dsl</filename> from the <filename
|
|
class="directory">gnome-docu/gdp/dsssl</filename> module in
|
|
CVS (or from <ulink
|
|
url="http://developer.gnome.org/projects/gdp/stylesheets.html">
|
|
GDP Custom DSSSL Stylesheet</ulink>)and copy it
|
|
<!-- into <filename
|
|
class="directory">/usr/lib/sgml/stylesheets</filename>. You
|
|
will need to point DocBook Tools to this stylesheet with the
|
|
<command><option>-d</option></command> option:
|
|
<command>db2html -d /usr/lib/sgml/stylesheets/gdp-both.dsl
|
|
<replaceable>foo.sgml</replaceable></command>. (Creating an
|
|
alias to include this option and path is convenient.)
|
|
Alternately, you could overwrite
|
|
<filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>
|
|
with <filename>gdp-both.dsl</filename>.
|
|
-->
|
|
over the file
|
|
<filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>.
|
|
Alternately, you can download and install the
|
|
<ulink url="http://people.redhat.com/dcm/software.html"
|
|
type="http">gnome-doc-tools package</ulink> which will set
|
|
up the stylesheets as well as the DTD discussed below.
|
|
</para>
|
|
|
|
<!-- <note>
|
|
<para>
|
|
The current version of the DocBook Tools command
|
|
<command>db2ps</command> does not have a
|
|
<command><option>-d</option></command> option. In order to
|
|
create PostScript output, you must overwrite
|
|
<filename>/usr/lib/sgml/stylesheets/cygnus-both.dsl</filename>
|
|
with <filename>gdp-both.dsl</filename>.
|
|
</para>
|
|
</note>
|
|
-->
|
|
</sect3>
|
|
|
|
<sect3 id="gdpdtd">
|
|
<title>GDP DTD (PNG Image Support)</title>
|
|
<para>
|
|
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 <ulink
|
|
url="http://www.gnu.org/philosophy/gif.html"
|
|
type="http">http://www.gnu.org/philosophy/gif.html</ulink>.
|
|
</para>
|
|
<para>
|
|
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:
|
|
</para>
|
|
<itemizedlist mark="opencircle">
|
|
<listitem>
|
|
<para>
|
|
Download <ulink
|
|
url="http://www.labs.redhat.com/png/png-support.html">the
|
|
GDP DocBook DTD for PNG support</ulink> and install it
|
|
where you keep your DTD's. (On Red Hat use <filename
|
|
class="directory">/usr/lib/sgml/</filename>.) Note that
|
|
the 3.0 DTD is missing support for the
|
|
<sgmltag><legalnotice></sgmltag> tag, so it is
|
|
recommended that you use version 3.1
|
|
</para>
|
|
</listitem>
|
|
<listitem override="bullet">
|
|
<para>
|
|
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:
|
|
<programlisting>
|
|
PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd"
|
|
</programlisting>
|
|
If you are using the 3.1 DTD, use:
|
|
<programlisting>
|
|
PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd"
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Alternately, you can download and install the
|
|
<ulink url="http://people.redhat.com/dcm/software.html"
|
|
type="http">gnome-doc-tools package</ulink> which will set
|
|
up the custom stylesheets and DTD for you.
|
|
</para>
|
|
<para>
|
|
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:
|
|
</para>
|
|
<para>
|
|
Articles:
|
|
<programlisting>
|
|
<![CDATA[<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant
|
|
V1.1//EN"[]>]]>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Books:
|
|
<programlisting>
|
|
<![CDATA[<!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant
|
|
V1.1//EN"[]>]]>
|
|
</programlisting>
|
|
</para>
|
|
|
|
</sect3>
|
|
|
|
<sect3 id="editors">
|
|
<title>Editors</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
Probably the two most popular editors available are
|
|
<application>Emacs</application> and
|
|
<application>vi</application>. 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 <xref linkend="installingdocbook" />.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="make-output">
|
|
<title>Creating Something Useful with your Docs</title>
|
|
<para>
|
|
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 <application>Jade</application>. In
|
|
most cases you will not have to work directly with
|
|
<application>Jade</application>; Instead, you will use the
|
|
scripts provided by DocBook Tools.
|
|
</para>
|
|
<para>
|
|
To preview your DocBook document, it is easiest to convert
|
|
it to <filename>html</filename>. If you have installed the
|
|
DocBook tools described above, all you have to do is to run
|
|
the command <prompt>$</prompt><command>db2html
|
|
mydocument.sgml</command>. If there are no sgml syntax
|
|
errors, this will create a directory <filename
|
|
class="directory">mydocument</filename> and place the
|
|
resulting html files in it. The title page of the document
|
|
will typically be
|
|
<filename>mydocument/index.html</filename>. If you have
|
|
screenshots in your document, you will have to copy these
|
|
files into the <filename
|
|
class="directory">mydocument</filename> directory by
|
|
hand. You can use any web browser to view your document.
|
|
Note that every time you run <command>db2html</command>, it
|
|
creates the <filename
|
|
class="directory">mydocument</filename> directory over, so
|
|
you will have to copy the screenshots over each time.
|
|
</para>
|
|
<para>
|
|
You can also convert your document to PostScript by running
|
|
the command <prompt>$</prompt><command>db2ps
|
|
mydocument.sgml</command>, after which you can print out or
|
|
view the resulting .ps file.
|
|
</para>
|
|
<note>
|
|
<title>NOTE</title>
|
|
<para>
|
|
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 <xref linkend="gdpstylesheets" />.
|
|
</para>
|
|
</note>
|
|
</sect3>
|
|
|
|
<sect3 id="jadeimages">
|
|
<title>Images in DocBook Tools</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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).
|
|
</para>
|
|
<para>
|
|
Thus, you should never explicitly
|
|
include the extension of the image file, since DocBook
|
|
Tools will automatically insert it for you. For example:
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
<figure>
|
|
<title>My Image</title>
|
|
<screenshot>
|
|
<screeninfo>Sample GNOME Display</screeninfo>
|
|
<graphic format="png" fileref="myfile" srccredit="me">
|
|
</graphic>
|
|
</screenshot>
|
|
</figure>
|
|
]]> </programlisting>
|
|
<para>
|
|
You will notice in this example that the file
|
|
<filename>myfile.png</filename> was referred to as simply
|
|
<filename>myfile</filename>. Now when you run
|
|
<command>db2html</command> to create an html file, it will
|
|
automatically look for <filename>myfile.png</filename> in
|
|
the directory.
|
|
</para>
|
|
<para>
|
|
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 <ulink
|
|
url="http://people.redhat.com/dcm/sgml.html"
|
|
type="html">http://people.redhat.com/dcm/sgml.html</ulink>
|
|
(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
|
|
<command>img2eps</command> on you system.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="moredocbookinfo">
|
|
<title>Learning DocBook</title>
|
|
<para>
|
|
There are many resources available to help you learn DocBook.
|
|
The following resources on the web are useful for learning
|
|
DocBook:
|
|
</para>
|
|
<itemizedlist mark="bullet">
|
|
<listitem>
|
|
<para>
|
|
<ulink url="http://www.docbook.org"
|
|
type="http">http://www.docbook.org</ulink> - Norman
|
|
Walsh's <citetitle>DocBook: The Definitive
|
|
Guide</citetitle>. Online O'Reilly book on using
|
|
DocBook. Contains an excellent element reference. May be
|
|
too formal for a beginner.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<ulink
|
|
url="http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html"
|
|
type="http">A Practical Introduction to DocBook</ulink>
|
|
- The Open Source Writers Group's introduction to using
|
|
DocBook. This is an excellent HOW-TO type article on
|
|
getting started.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<ulink
|
|
url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html"
|
|
type="http">Getting Going with DocBook: Notes for
|
|
Hackers</ulink> - 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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<ulink type="http" url="http://www.freebsd.org/tutorials/docproj-primer/">
|
|
FreeBSD Documentation Project Primer for New
|
|
Contributors</ulink> - 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.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Norman Walsh's book is also available in print.
|
|
</para>
|
|
<para>
|
|
The following sections of this document are designed to help
|
|
documentation authors write correct and consistent DocBook:
|
|
</para>
|
|
<itemizedlist mark="bullet">
|
|
<listitem>
|
|
<para>
|
|
<xref linkend="docbookbasics" /> - Descriptions of
|
|
commonly used DocBook tags.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<!-- ####### Getting Started | GDP Document Examples ####### -->
|
|
<!--
|
|
<sect2 id="examples">
|
|
<title>GDP Document Examples</title>
|
|
<para>
|
|
Examples of various types of GNOME documents are found in
|
|
<xref linkend="examples" />. There is also an example GNOME
|
|
application with documentation called
|
|
<application>gnome-hello</application> in GNOME cvs.
|
|
</para>
|
|
</sect2>
|
|
-->
|
|
<!-- ####### Getting Started | GDP Document Templates ####### -->
|
|
|
|
<sect2 id="gdptemplates">
|
|
<title>GDP Document Templates</title>
|
|
<para>
|
|
Templates for various types of GNOME documents are found in
|
|
<xref linkend="templates" />. They are kept in CVS in
|
|
gnome-docu/gdp/templates. The easiest source to get them from
|
|
is probably the <ulink
|
|
url="http://developer.gnome.org/projects/gdp/templates.html"
|
|
type="http">GDP
|
|
Document Templates</ulink> web page, which is typically kept
|
|
completely up-to-date with CVS and has a basic description of
|
|
each file from CVS.
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- ####### Getting Started | Screenshots ####### -->
|
|
|
|
<sect2 id="screenshots">
|
|
<title>Screenshots</title>
|
|
<para>
|
|
Most GNOME documents will have screenshots of the particular
|
|
applet, application, GNOME component, or widget being
|
|
discussed. As discussed above in <xref linkend="gdpdtd"/> 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 <xref linkend="jadeimages"/> above.
|
|
</para>
|
|
<sect3 id="screenshotappearance">
|
|
<title>Screenshot Appearance</title>
|
|
<para>
|
|
For all screenshots of windows that typically have border
|
|
decorations (e.g. applications and dialogs, but not applets
|
|
in a <interface>panel</interface>), 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
|
|
<ulink url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
|
|
<citetitle>gnome-doc-list mailing list</citetitle> </ulink>
|
|
requesting a GDP member reproduce these screenshots in the
|
|
correct format and email them to you.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="screenshottools">
|
|
<title>Screenshot Tools</title>
|
|
<para>
|
|
There are many tools for taking screenshots in
|
|
GNOME/Linux. Perhaps the most convenient is the
|
|
<application>Screen-Shooter Applet</application>. 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
|
|
<application>Netscape</application> or the
|
|
<application>GNOME Help Browser</application>. You
|
|
should save your screenshot as a GIF and
|
|
then use <command>convert filename.gif
|
|
filename.png</command>.) For applets
|
|
in a <interface>Panel</interface>,
|
|
<application>xv</application> can be used to crop the
|
|
screenshot to only include the relevant portion of the
|
|
<interface>Panel</interface>. Note that
|
|
<application>xv</application> and
|
|
<application>gimp</application> can both be used for taking
|
|
screenshots, cropping screenshots, and converting image
|
|
formats.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="screenshotfiles">
|
|
<title>Screenshot Files</title>
|
|
<para>
|
|
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 <command>db2html</command> to
|
|
convert your SGML file to HTML (see <xref
|
|
linkend="make-output"/>), 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 <command>db2html</command> 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 <xref
|
|
linkend="jadeimages"/>, but will not need to copy these
|
|
images from their default location, as they are included
|
|
directly into the output(PostScript of PDF) file.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
|
|
<!-- ####### Getting Started | Application Bugs ####### -->
|
|
|
|
<sect2 id="applicationbugs">
|
|
<title>Application Bugs</title>
|
|
<para>
|
|
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
|
|
<interface>About</interface> 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 <application>Bug
|
|
Buddy</application> applet which is part of the gnome-applets
|
|
package.
|
|
</para>
|
|
</sect2>
|
|
|
|
|
|
<!-- ####### Getting Started | Using CVS ####### -->
|
|
|
|
<sect2 id="cvs">
|
|
<title>Using CVS</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<sect3 id="anonymouscvs">
|
|
<title>Anonymous CVS</title>
|
|
<para>
|
|
To anonymously check out documents from CVS, you must first
|
|
log in. From the bash shell, you should set your CVSROOT
|
|
shell variable with <command> export
|
|
CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</command>
|
|
and then login with <command>cvs login</command>(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 <command>cvs -z3 checkout
|
|
gnome-docu/gdp</command>. After you have this document
|
|
checked out and you would like to download any updates on
|
|
the CVS server, use <command>cvs -z3 update -Pd</command>.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="logincvs">
|
|
<title>Login CVS</title> <para> 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
|
|
<command><replaceable>username</replaceable></command> with a
|
|
password, you must first set your CVSROOT shell variable with
|
|
<command> export
|
|
CVSROOT=':pserver:<replaceable>username</replaceable>@cvs.gnome.org:/cvs/gnome'</command>.
|
|
Log in with <command>cvs login</command> 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
|
|
<command><replaceable>filename</replaceable></command> into
|
|
the CVS server, type <command>cvs -z3 commit
|
|
<replaceable>filename</replaceable></command>. 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 <varname>EDITOR</varname> environment variable or
|
|
with the <command><option>-e</option></command> option. You
|
|
may also check in any modifications to files in the working
|
|
directory and subdirectories using <command>cvs -z3
|
|
commit</command>. To
|
|
add a new file to the CVS server, use <command>cvs -z3 add
|
|
<replaceable>filename</replaceable></command>, followed by the
|
|
commit command.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="cvsetiquette">
|
|
<title>CVS Etiquette</title>
|
|
<para>
|
|
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 <filename>ChangeLog</filename> 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.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!-- ################# The GNOME Documentation System###############
|
|
-->
|
|
|
|
<sect1 id="gnomedocsystem">
|
|
<title>The GNOME Documentation System</title>
|
|
|
|
<!-- ####### The GNOME Documentation System | The GNOME Help Browser
|
|
####### -->
|
|
|
|
<sect2 id="gnomehelpbrowser">
|
|
<title>The GNOME Help Browser</title>
|
|
<para>
|
|
At the core of the GNOME help system is the <application>GNOME
|
|
Help Browser</application>. The <application>Help
|
|
Browser</application> 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.
|
|
</para>
|
|
<para>
|
|
The <application>GNOME Help Browser</application> 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.
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- ####### The GNOME Documentation System | The GNOME Help Browser
|
|
####### -->
|
|
|
|
<sect2 id="gnomehelpbrowser2">
|
|
<title>The GNOME Help Browser (GNOME-2.0)</title> <para> In
|
|
GNOME 2.0, the <application>GNOME Help Browser</application>
|
|
will be replaced by <application>Nautilus</application>.
|
|
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 <application>GNOME Help Browser</application>
|
|
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 <application>jade</application> 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
|
|
<application>Nautilus</application>, visit the #nautilus IRC
|
|
channel on irc.gnome.org. </para>
|
|
</sect2>
|
|
|
|
<!-- ####### The GNOME Documentation System | GNOME On-The-Fly
|
|
Documentation Generation ####### -->
|
|
|
|
<sect2 id="gnomehelponthefly">
|
|
<title>Dynamic Document Synthesis(GNOME-2.0)</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- ####### The GNOME Documentation System | The GNOME Documentation
|
|
Components ####### -->
|
|
|
|
<sect2 id="gnomehelpcomponents">
|
|
<title>The GNOME Documentation Components</title>
|
|
|
|
<sect3 id="applicationmanualsintro">
|
|
<title>Application Manuals</title>
|
|
<para>
|
|
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 <xref
|
|
linkend="writingapplicationmanuals" /> below.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="applicationhelpintro">
|
|
<title>Application Help</title>
|
|
<para>
|
|
Applications should have a <guibutton>Help</guibutton>
|
|
button on screens on which users may need help. These
|
|
<guibutton>Help</guibutton> buttons should pull up the
|
|
default help browser, determined by the
|
|
<varname>ghelp</varname> URL Handler (configured using the
|
|
<application>Control Center</application>), typically the
|
|
<application>GNOME Help Browser</application>. 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 <xref
|
|
linkend="applicationhelpbuttons" /> below.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="contextsensitivehelpintro">
|
|
<title>Application Context Sensitive Help (coming in
|
|
GNOME-2.0)</title>
|
|
<para>
|
|
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 <xref linkend="writingcontextsensitivehelp" />
|
|
below.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="userguide">
|
|
<title>The GNOME User Guide</title>
|
|
<para>
|
|
The <citetitle>GNOME User Guide</citetitle> describes the
|
|
GNOME desktop environment and core components of GNOME such
|
|
as the <application>panel</application> and
|
|
<application>control center</application>. 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.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="userdocs">
|
|
<title>User Documents</title>
|
|
<para>
|
|
Aside from the <citetitle>GNOME User Guide</citetitle>,
|
|
there are several other documents to help GNOME users learn
|
|
GNOME, including the <citetitle>GNOME FAQ</citetitle>,
|
|
<citetitle>GNOME Installation and Configuration
|
|
Guide</citetitle>, and the <citetitle>GNOME Administrators
|
|
Guide</citetitle>.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="developerdocs">
|
|
<title>Developer Documents</title>
|
|
<para>
|
|
There are many White Papers, Tutorials, HOWTO's and FAQ's to
|
|
make programming GNOME and GNOME applications as easy as
|
|
possible.
|
|
</para>
|
|
<para>
|
|
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 <ulink
|
|
url="http://developer.gnome.org/doc/API/" type="http">GNOME API
|
|
Reference</ulink> page.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="projectdocs">
|
|
<title>Project Documents</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
<!-- ################# DocBook Basics ############### -->
|
|
|
|
<sect1 id="docbookbasics">
|
|
<title>DocBook Basics </title>
|
|
<!-- ####### DocBook Basics | Introduction to DocBook ####### -->
|
|
|
|
<sect2 id="introtodocbook">
|
|
<title>Introduction to DocBook</title>
|
|
<para>
|
|
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
|
|
<emphasis>elements</emphasis> 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 <sgmltag><title></sgmltag>The
|
|
Title<sgmltag></title></sgmltag>.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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 <emphasis>DocBook
|
|
Tools</emphasis>, a free package of utilities for working with DocBook
|
|
which includes <emphasis>Jade</emphasis>, which does the SGML/DSSL
|
|
parsing. You can read more about DocBook Tools in <xref
|
|
linkend="installingdocbook" />.
|
|
</para>
|
|
<para>
|
|
The final appearance of the output (e.g. PostScript or HTML)
|
|
is determined by a
|
|
<emphasis>stylesheet</emphasis>. 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 <xref
|
|
linkend="gdpstylesheets"/>.
|
|
</para>
|
|
<para>
|
|
The advantage of specifying the <emphasis>structure</emphasis>
|
|
of a document with SGML instead of specifying the
|
|
<emphasis>appearance</emphasis> 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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
As stated before, the GDP uses the DocBook DTD. For a list of
|
|
introductory and reference resources on DocBook, see <xref
|
|
linkend="resources" />. The following sections also provide
|
|
convenient instructions on which markup tags to use in various
|
|
circumstances. Be sure to read <xref linkend="conventions" />
|
|
for GDP documentation-specific guidelines.
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- ###### DocBook Basics | XML and SGML ########-->
|
|
<sect2 id="xml">
|
|
<title>XML and SGML</title>
|
|
|
|
<para> 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 <emphasis>strongly
|
|
advised</emphasis> that the documentation writers conform to XML
|
|
syntax rules. Here are most important differences:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term> <emphasis>Minimization</emphasis></term>
|
|
<listitem>
|
|
|
|
<para>
|
|
It is possible with some implementations of SGML to use
|
|
minimizations to close elements in a document by using
|
|
</>, for example:
|
|
<literal><sgmltag><title></sgmltag>The
|
|
Title<sgmltag></></sgmltag></literal>. This is not
|
|
allowed in XML. You can use <command>sgmlnorm</command> command,
|
|
included in DocBook Tools package, to expand minimized tags;
|
|
if you are using <application>Emacs</application> with psgml
|
|
mode, you can also use menu command
|
|
<menuchoice>
|
|
<guimenu>Modify</guimenu>
|
|
<guimenuitem>Normalize</guimenuitem>
|
|
</menuchoice>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term> <emphasis>Self-closing tags</emphasis></term>
|
|
<listitem>
|
|
|
|
<para>
|
|
Also, in SGML some tags are allowed not to have closing
|
|
tags. For example, it is legal for
|
|
<sgmltag><xref></sgmltag> not to have a closing tag:
|
|
<literal><sgmltag><xref
|
|
linkend="someid"></sgmltag></literal>. In
|
|
XML, it is illegal; instead, you should use
|
|
<literal><sgmltag><xref
|
|
linkend="someid"/></sgmltag></literal> (note the
|
|
slash!).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term> <emphasis>Case sensitive tags</emphasis></term>
|
|
<listitem>
|
|
<para>
|
|
In XML, unlike SGML, tags are case-senstive
|
|
<sgmltag><title></sgmltag> and
|
|
<sgmltag><TITLE></sgmltag> are different tags!
|
|
Therefore, please always use lowercase tags (except for
|
|
things like <literal>DOCTYPE, CDATA</literal> and
|
|
<literal>ENTITY</literal>, which are not DocBook tags).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
|
|
</variablelist>
|
|
</sect2>
|
|
|
|
|
|
|
|
<!-- ####### DocBook Basics | Structure Elements ####### -->
|
|
|
|
|
|
<sect2 id="structure"> <title> Structure Elements</title>
|
|
|
|
<sect3 id="section">
|
|
<title>Sections and paragraphs</title>
|
|
<para>
|
|
Top-level element of a book body must be
|
|
<sgmltag><chapter></sgmltag>; it may contain one or more
|
|
<sgmltag><sect1></sgmltag>, each of them may contain
|
|
<sgmltag><sect2></sgmltag> and so on up to
|
|
<sgmltag><sect5></sgmltag>. The top-level element of an
|
|
article body is always
|
|
<sgmltag><sect1></sgmltag>. 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.
|
|
</para>
|
|
<para> Please try to avoid using deeply nested sections; for
|
|
most situations, <sgmltag><sect1></sgmltag> and
|
|
<sgmltag><sect2></sgmltag> should be sufficient. If not,
|
|
you probably should split your <sgmltag><sect1></sgmltag>
|
|
into several smaller ones.
|
|
</para>
|
|
<para> Use the tag <sgmltag><para></sgmltag> for
|
|
paragraphs, even if there is only one paragraph in a
|
|
section—see template for examples.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="notes">
|
|
<title>Notes, Warnings, And Tips</title>
|
|
<para>
|
|
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
|
|
<sgmltag><note></sgmltag>, <sgmltag><tip></sgmltag>,
|
|
<sgmltag><warning></sgmltag>,
|
|
<sgmltag><important></sgmltag> respectively. For example:
|
|
<programlisting>
|
|
<![CDATA[
|
|
<tip>
|
|
<title>TIP</title>
|
|
<para>
|
|
To speed up program compilation, use <application>gcc</application>
|
|
compiler with Pentium optimization.
|
|
</para>
|
|
</tip>]]> </programlisting> produces
|
|
</para>
|
|
<tip id="extip">
|
|
<title>TIP</title>
|
|
<para>
|
|
To speed up program compilation, use
|
|
<application>gcc</application> compiler with Pentium
|
|
optimization. </para>
|
|
</tip>
|
|
<para>
|
|
Note that this should not be inside a
|
|
<sgmltag><para></sgmltag> but between paragraphs.
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="figures">
|
|
<title> Screenshots and other figures</title>
|
|
<para>
|
|
To include screenshots and other figures, use the following
|
|
tags:
|
|
|
|
<programlisting>
|
|
<![CDATA[
|
|
<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>]]>
|
|
</programlisting>
|
|
replacing <filename>example_screenshot</filename> with the
|
|
actual file name (without extension). The result will look like this:
|
|
|
|
<figure id="shot1">
|
|
<title>Screenshot</title>
|
|
<screenshot>
|
|
<screeninfo>Screenshot of a program</screeninfo>
|
|
<graphic format="PNG"
|
|
fileref="figures/example_screenshot" srccredit="ME"/>
|
|
|
|
</screenshot>
|
|
</figure>
|
|
</para>
|
|
<note>
|
|
<title>NOTE</title>
|
|
<para>
|
|
Notice in this example that the screenshot file name does
|
|
not include the file type extension — to find out
|
|
why, please read <xref linkend="jadeimages" />.
|
|
</para>
|
|
</note>
|
|
</sect3>
|
|
<sect3 id="listing">
|
|
<title>Program listings and terminal session</title> <para>
|
|
To show a file fragment—for example, program
|
|
listing—use <sgmltag><programlisting></sgmltag> tag:
|
|
<programlisting>
|
|
<![CDATA[
|
|
<programlisting>
|
|
[Desktop Entry]
|
|
Name=Gnumeric spreadsheet
|
|
Exec=gnumeric
|
|
Icon=gnome-gnumeric.png
|
|
Terminal=0
|
|
Type=Application
|
|
</programlisting>]]>
|
|
</programlisting>
|
|
which produces
|
|
<programlisting>
|
|
[Desktop Entry]
|
|
Name=Gnumeric spreadsheet
|
|
Exec=gnumeric
|
|
Icon=gnome-gnumeric.png
|
|
Terminal=0
|
|
Type=Application
|
|
</programlisting>
|
|
As a matter of fact, all examples in this document were
|
|
produced using <sgmltag><programlisting></sgmltag>.
|
|
</para>
|
|
<para>
|
|
To show a record of terminal session—i.e., sequence of
|
|
commands entered at the command line—use
|
|
<sgmltag><screen></sgmltag> tag:
|
|
<programlisting>
|
|
<![CDATA[
|
|
<screen>
|
|
<prompt>bash$</prompt><userinput>make love</userinput>
|
|
make: *** No rule to make target `love'. Stop.
|
|
</screen>]]>
|
|
</programlisting>
|
|
which produces
|
|
<screen>
|
|
<prompt>bash$</prompt><userinput>make love</userinput>
|
|
make: *** No rule to make target `love'. Stop.
|
|
</screen>
|
|
Note the use of tags <sgmltag><prompt></sgmltag> and
|
|
<sgmltag><userinput></sgmltag> for marking system prompt
|
|
and commands entered by user.
|
|
<note>
|
|
<title>NOTE</title>
|
|
<para>
|
|
Note that both <sgmltag><programlisting></sgmltag>
|
|
and <sgmltag><screen></sgmltag> preserve linebreaks,
|
|
but interpret SGML tags (unlike LaTeX
|
|
<markup>verbatim</markup> environment). Take a look at
|
|
the source of this document to see how you can have SGML
|
|
tags literally shown but not interpreted,
|
|
</para>
|
|
</note>
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="lists">
|
|
<title> Lists</title>
|
|
<para>
|
|
The most common list types in DocBook are
|
|
<sgmltag><itemizedlist></sgmltag>,
|
|
<sgmltag><orderedlist></sgmltag>, and
|
|
<sgmltag><variablelist></sgmltag>.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term> <sgmltag><itemizedlist></sgmltag></term>
|
|
<listitem><para>
|
|
This is the simplest unnumbered list, parallel to
|
|
<sgmltag><ul></sgmltag> in HTML. Here is an example:
|
|
<programlisting>
|
|
<![CDATA[
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<guilabel>Show backup files</guilabel> — This will
|
|
show any backup file that might be on your system.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<guilabel>Show hidden files</guilabel> — 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> — This
|
|
option will display files and directories in the order you
|
|
sort them instead of
|
|
always having directories shown above files.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
]]>
|
|
</programlisting>
|
|
and output:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<guilabel>Show backup files</guilabel> —
|
|
This will show any backup file that might be on
|
|
your system.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<guilabel>Show hidden files</guilabel> —
|
|
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>
|
|
— This option will display files and
|
|
directories in the order you sort them instead
|
|
of always having directories shown above files.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para> Note the use of <sgmltag>&mdash;</sgmltag>
|
|
for long dash (see <xref linkend="specsymb" />). Also,
|
|
please note that the result looks much nicer because the
|
|
terms being explained (<guilabel>Show backup
|
|
files</guilabel>, etc.) are set in a different font. In
|
|
this case, it was achieved by using <link
|
|
linkend="gui"><sgmltag><guilabel></sgmltag></link>
|
|
tag. In other cases, use appropriate tags such as
|
|
<link linkend="gui"><sgmltag><guimenuitem></sgmltag></link>,
|
|
<link
|
|
linkend="filenames"><sgmltag><command></sgmltag></link>,
|
|
or — if none of
|
|
this applies — use
|
|
<link linkend="gui"><sgmltag><emphasis></sgmltag></link>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term> <sgmltag><orderedlist></sgmltag></term>
|
|
<listitem><para>
|
|
This list is completely analogous to
|
|
<sgmltag><itemizedlist></sgmltag> 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 <sgmltag>numeration</sgmltag>,
|
|
for example <sgmltag><orderedlist
|
|
numeration="lowerroman"></sgmltag>. Possible values of
|
|
these attribute are <sgmltag>arabic</sgmltag>,
|
|
<sgmltag>upperalpha</sgmltag>,
|
|
<sgmltag>loweralpha</sgmltag>,
|
|
<sgmltag>upperroman</sgmltag>,
|
|
<sgmltag>lowerroman</sgmltag>.
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term> <sgmltag><variablelist></sgmltag></term>
|
|
<listitem><para> 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
|
|
<sgmltag><variablelist></sgmltag> 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 <sgmltag><variablelist></sgmltag>. The
|
|
source looked liked this:
|
|
<programlisting>
|
|
<![CDATA[
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term> <sgmltag><itemizedlist></sgmltag></term>
|
|
<listitem><para>
|
|
This is the simplest unnumbered list, parallel to
|
|
<sgmltag><ul></sgmltag> in HTML. Here is an example:...
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term> <sgmltag><orderedlist></sgmltag></term>
|
|
<listitem><para>
|
|
This list is completely analogous to
|
|
<sgmltag><itemizedlist></sgmltag>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term> <sgmltag><variablelist></sgmltag></term>
|
|
<listitem><para>
|
|
This list is used when each entry is rather long,...
|
|
</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
Lists can be nested; in this case, the stylesheets
|
|
are smart enough to change the numeration (for
|
|
<sgmltag><orderedlist></sgmltag>) or marks of each entry
|
|
(in <sgmltag><itemizedlist></sgmltag>) for sub-lists
|
|
</para>
|
|
</sect3>
|
|
|
|
</sect2>
|
|
|
|
<!-- ####### DocBook Basics | Inline Elements ####### -->
|
|
|
|
<sect2 id="inline">
|
|
<title>Inline Elements</title>
|
|
|
|
<sect3 id="gui">
|
|
<title>GUI elements</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<sgmltag><guibutton></sgmltag> — used for
|
|
buttons, including checkbuttons and radio buttons
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<sgmltag><guimenu></sgmltag>,
|
|
<sgmltag><guisubmenu></sgmltag> —used for
|
|
top-level menus and submenus
|
|
respectively, for example <literal><![CDATA[
|
|
<guisubmenu>Utilities</guisubmenu> submenu of the
|
|
<guimenu>Main Menu</guimenu>]]></literal>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<sgmltag><guimenuitem></sgmltag>—an entry in a
|
|
menu
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<sgmltag><guiicon></sgmltag>—an icon
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<sgmltag><guilabel></sgmltag>—for items which have
|
|
labels, like tabs, or bounding boxes.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<sgmltag><interface></sgmltag>— for most everything
|
|
else... a window, a dialog box, the Panel, etc.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
If you need to refer to a sequence of menu choices, such as
|
|
<menuchoice>
|
|
<guimenu>Main Menu</guimenu>
|
|
<guisubmenu>Utilities</guisubmenu> <guimenuitem>GNOME
|
|
terminal</guimenuitem>
|
|
</menuchoice>
|
|
there is a special construction for this, too:
|
|
<programlisting>
|
|
<![CDATA[
|
|
<menuchoice>
|
|
<guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
|
|
<guimenuitem>GNOME terminal</guimenuitem> </menuchoice>]]>
|
|
</programlisting>
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="links">
|
|
<title>Links and references</title>
|
|
<para>
|
|
To refer to another place in the same document, you can use
|
|
tags <sgmltag><xref></sgmltag> and
|
|
<sgmltag><link></sgmltag>. 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:
|
|
<programlisting>
|
|
<![CDATA[An example of a <link linkend="extip">tip</link> was given in
|
|
<xref linkend="notes" />. ]]>
|
|
</programlisting>
|
|
which produces: An example of a <link
|
|
linkend="extip">tip</link> was given in <xref
|
|
linkend="notes" />.
|
|
</para>
|
|
<para>
|
|
Here <sgmltag>notes</sgmltag> and <sgmltag>extip</sgmltag>
|
|
are the id attributes of <xref linkend="notes" /> and of the
|
|
example of a tip in it.
|
|
</para>
|
|
<para> To produce a link to an external source, such as a
|
|
Web page or a local file, use <sgmltag><ulink></sgmltag>
|
|
tag, for example:
|
|
<programlisting>
|
|
<![CDATA[ To find more about GNOME, please visit <ulink type="http"
|
|
url="http://www.gnome.org">GNOME Web page</ulink> ]]>
|
|
</programlisting>
|
|
which produces: To find more about GNOME, please visit
|
|
<ulink type="http" url="http://www.gnome.org">The GNOME Web
|
|
Site</ulink> You can use any of the standard URL types, such
|
|
as <literal>http, ftp, file, telnet, mailto</literal> (in
|
|
most cases, however, use of <literal>mailto</literal> is
|
|
unnecessary—see discussion of
|
|
<sgmltag><email></sgmltag> tag).
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="filenames"> <title>Filenames, commands, and other
|
|
computer-related things</title>
|
|
<para>
|
|
Here are some tags used to describe operating system-related
|
|
things:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para> <sgmltag><filename></sgmltag> — used
|
|
for filenames,
|
|
e.g.<sgmltag><filename></sgmltag>
|
|
foo.sgml
|
|
<sgmltag></filename></sgmltag>
|
|
produces: <filename>foo.sgml</filename>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para> <sgmltag><filename
|
|
class="directory"></sgmltag> — used for
|
|
directories, e.g.<sgmltag><filename
|
|
class="directory"></sgmltag>/usr/bin
|
|
<sgmltag></filename></sgmltag>
|
|
produces: <filename
|
|
class="directory">/usr/bin</filename>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<sgmltag><application></sgmltag> — used for
|
|
application names,
|
|
e.g. <sgmltag><application></sgmltag>Gnumeric
|
|
<sgmltag></application></sgmltag> produces:
|
|
<application>Gnumeric</application>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<sgmltag><envar></sgmltag> — used for
|
|
environment variables, e.g.
|
|
<sgmltag><envar></sgmltag>PATH<sgmltag></envar></sgmltag>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<sgmltag><command></sgmltag> — used for
|
|
commands entered on command line, e.g.
|
|
<sgmltag><command></sgmltag>make install
|
|
<sgmltag></command></sgmltag> produces:
|
|
<command>make install</command>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<sgmltag><replaceable></sgmltag> — used for
|
|
replaceable text, e.g.
|
|
<sgmltag><command></sgmltag>db2html<sgmltag><replaceable></sgmltag>
|
|
foo.sgml
|
|
<sgmltag></replaceable></sgmltag><sgmltag></command></sgmltag>
|
|
produces: <command>db2html
|
|
<replaceable>foo.sgml</replaceable></command>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</sect3>
|
|
|
|
<sect3 id="keys">
|
|
<title>Keyboard input</title>
|
|
<para> To mark up text input by the user, use
|
|
<sgmltag><userinput></sgmltag>.
|
|
</para>
|
|
<para> To mark keystrokes such as shortcuts and other
|
|
commands, use <sgmltag><keycap></sgmltag>.
|
|
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: <sgmltag><keysym></sgmltag>
|
|
and <sgmltag><keycode></sgmltag>. However you are
|
|
unlikely to need these for most documentation. For reference,
|
|
<sgmltag><keysym></sgmltag> is for the <quote>symbolic
|
|
name</quote> of a key. <sgmltag><keycode></sgmltag> is
|
|
for the <quote>scan code</quote> of a key. These are not
|
|
terms commonly required in <acronym>GNOME</acronym> documentation,
|
|
although <sgmltag><keysym></sgmltag> is useful for marking
|
|
up control codes.
|
|
</para>
|
|
<para>
|
|
To mark up a combination of keystrokes, use the
|
|
<sgmltag><keycombo></sgmltag> wrapper:
|
|
<programlisting>
|
|
<![CDATA[
|
|
<keycombo>
|
|
<keycap>Ctrl</keycap>
|
|
<keycap>Alt</keycap>
|
|
<keycap>F1</keycap>
|
|
</keycombo>]]>
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
Finally, if you want to show a shortcut for some menu
|
|
command, here are the appropriate tags (rather long):
|
|
<programlisting>
|
|
<![CDATA[
|
|
<menuchoice>
|
|
<shortcut>
|
|
<keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
|
|
</shortcut>
|
|
<guimenuitem> Quit</guimenuitem>
|
|
</menuchoice>]]>
|
|
</programlisting>
|
|
which produces simply
|
|
<menuchoice>
|
|
<shortcut> <keysym>Ctrl-q</keysym> </shortcut>
|
|
<guimenuitem> Quit</guimenuitem>
|
|
</menuchoice>
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="email">
|
|
<title>E-mail addresses</title> <para> To mark up e-mail
|
|
address, use <sgmltag><email></sgmltag>:
|
|
<programlisting>
|
|
<![CDATA[ The easiest way to get in touch with me is by e-mail
|
|
(<email>me@mydomain.com</email>)]]>
|
|
</programlisting>
|
|
which produces: The easiest way to get in touch with me is
|
|
by e-mail (<email>me@mydomain.com</email>) Note that
|
|
<sgmltag><email></sgmltag> automatically produces a link
|
|
in html version.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="specsymb">
|
|
<title> Special symbols </title>
|
|
<para>
|
|
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
|
|
<emphasis>entities</emphasis>, which is SGML analogue of
|
|
macros, or commands, of LaTeX. They generally have the form
|
|
<sgmltag>&entityname;</sgmltag>. Note that the semicolon
|
|
is required.
|
|
</para>
|
|
<para>
|
|
here is partial list of most commonly used enitites:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<sgmltag>&amp;</sgmltag> — ampersend (&)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<sgmltag>&lt;</sgmltag> — left angle bracket (<)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<sgmltag>&copy;</sgmltag> — copyright sign (©)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<sgmltag>&mdash;</sgmltag> — long dash (—)
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<sgmltag>&hellip;</sgmltag> — ellipsis (…)
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
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 (<sgmltag>&mdash;</sgmltag>) 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.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!-- ################# GDP Documentation Conventions ############### -->
|
|
|
|
<sect1 id="conventions">
|
|
<title>GDP Documentation Conventions </title>
|
|
|
|
<!-- ####### GDP Documentation Conventions | All Documentation ####### -->
|
|
|
|
<sect2 id="conventionsalldocs">
|
|
<title>Conventions for All GDP Documentation</title>
|
|
<sect3 id="xmlcomp">
|
|
<title> XML compatibility </title>
|
|
<para>
|
|
All GNOME documentation should conform to XML syntax
|
|
requirements, which are stricter than SGML ones — see
|
|
<xref linkend="xml" /> for more informaion.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="authorsnames">
|
|
<title> Authors' names</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<!-- ####### GDP Documentation Conventions | All Documentation ####### -->
|
|
|
|
<sect2 id="conventionsappdocs">
|
|
<title>Conventions for Application Documentation</title>
|
|
|
|
<sect3 id="applicationversionid">
|
|
<title>Application Version Identification</title>
|
|
<para>
|
|
Application documentation should identify the version of the
|
|
application for which the documentation is written:
|
|
<programlisting>
|
|
<![CDATA[
|
|
<sect1 id="intro">
|
|
<title>Introduction</title>
|
|
<para>
|
|
blah-blah-blah This document describes version 1.0.53 of gfoo.
|
|
</para>
|
|
</sect1>]]>
|
|
</programlisting>
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="license">
|
|
<title> Copyright information </title>
|
|
<para> 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).
|
|
</para>
|
|
</sect3>
|
|
<sect3 id="license2">
|
|
<title>Software license</title>
|
|
<para>
|
|
All GNOME applications must contain information about the
|
|
license (for software, not for documentation), either in the
|
|
"About" box or in the manual.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="bugtraq">
|
|
<title> Bug reporting</title>
|
|
<para>
|
|
Application documentation should give an address for
|
|
reporting bugs and for submitting comments about the
|
|
documentaion (see templates for an example).
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!-- ################# Writing Application Manuals ###############-->
|
|
|
|
<sect1 id="writingapplicationmanuals">
|
|
<title>Writing Application and Applet Manuals</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<note>
|
|
<title>Documentation Availability</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</note>
|
|
<para> Application manuals should be based on the template in
|
|
<xref linkend="template1" />. Applet manuals should be based on
|
|
the templates in <xref linkend="template2-1x" /> for GNOME
|
|
versions 1.x and the templates in <xref linkend="template2-2x" />
|
|
for GNOME versions 2.x.
|
|
</para>
|
|
<note>
|
|
<title>Manuals For Large Applications</title>
|
|
<para>
|
|
Manuals for very large applications, such as GNOME Workshop
|
|
components should be a <sgmltag><book></sgmltag> (and thus
|
|
use <sgmltag><chapter></sgmltag> for each primary section)
|
|
, instead of <sgmltag><article></sgmltag> which most
|
|
applications use(with each primary section being a
|
|
<sgmltag><sect1></sgmltag>).
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<title>Applet Manuals in GNOME 2.0</title>
|
|
<para>
|
|
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
|
|
<sgmltag><sect1></sgmltag>. Applet manuals will typically
|
|
have several sections, each of which is
|
|
<sgmltag><sect2></sgmltag>.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
Application manuals should be made available by having a
|
|
"Manual" entry in the <guimenu>Help</guimenu> pull-down menu
|
|
at the top of the
|
|
application, as described in <xref linkend="listingdocsinhelpmenu" />.
|
|
Applets should make their manuals available by
|
|
right-clicking on the applet.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<!-- ############### Listing Documents in the Help Menu ############# -->
|
|
|
|
<sect1 id="listingdocsinhelpmenu">
|
|
<title>Listing Documents in the Help Menu</title>
|
|
|
|
<note>
|
|
<title>Developer Information</title>
|
|
<para>
|
|
This section is for developers. Documentation authors
|
|
generally do not need to know this material.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
Typically the application manual and possibly additional help
|
|
documents will be made available to the user under the
|
|
<guimenu>Help</guimenu> menu at the top right of the
|
|
application. To do this, you must first write a
|
|
<filename>topic.dat</filename> file. The format for this file is:
|
|
<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.
|
|
</programlisting>
|
|
For example, <application>Gnumeric</application>'s
|
|
<filename>topic.dat</filename> file is:
|
|
<programlisting>
|
|
gnumeric.html Gnumeric manual
|
|
function-reference.html Gnumeric function reference
|
|
</programlisting>
|
|
When the application is installed, the
|
|
<filename>topic.dat</filename> file should be placed in the
|
|
<filename
|
|
class="directory">$prefix/share/gnome/help/<replaceable>appname</replaceable>/C/</filename> directory
|
|
where <replaceable>appname</replaceable> is replaced by the
|
|
application's name. The application documentation (converted
|
|
from SGML into HTML with <command>db2html</command>) should be
|
|
placed in this directory too.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
If the help files are not present in the correct directory, the
|
|
menu items will NOT appear when the program is run.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
The <filename>topic.dat</filename> file is used by the GNOME
|
|
menu building code to generate the <guimenu>Help</guimenu>
|
|
menu. When you define your menu:
|
|
<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("<emphasis>appname</emphasis>"),
|
|
GNOMEUIINFO_END
|
|
};
|
|
</programlisting>
|
|
the line specifying <varname>GNOMEUIINFO_HELP</varname> causes
|
|
GNOME to create a menu entry which is tied to the documentation
|
|
in the directory mentioned above. Also, all the topics in the
|
|
<filename>topic.dat</filename> file will get menu entries in the
|
|
<guimenu>Help</guimenu> menu. When the user selects any of these
|
|
topics from the <guimenu>Help</guimenu> menu, a help browser
|
|
will be started with the associated HTML documentation.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<!-- ################# Application Help Buttons ############### -->
|
|
|
|
<sect1 id="applicationhelpbuttons">
|
|
<title>Application Help Buttons</title>
|
|
|
|
<note>
|
|
<title>Developer Information</title>
|
|
<para>
|
|
This section is for developers. Documentation authors
|
|
generally do not need to know this material.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
Most GNOME applications will have <guibutton>Help</guibutton>
|
|
buttons. These are most often seen in Preference windows. (All
|
|
Preference windows should have <guibutton>Help</guibutton>
|
|
buttons.) Most <guibutton>Help</guibutton> buttons will connect
|
|
to the application manual, although some may connect to special
|
|
documents. Because the <guibutton>Help</guibutton> 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
|
|
<guibutton>Help</guibutton> buttons are pressed.
|
|
</para>
|
|
<para>
|
|
To make the Help buttons call the correct document in the GNOME Help
|
|
Browser the developer should add code based on the following example:
|
|
</para>
|
|
<programlisting>
|
|
gchar *tmp;
|
|
tmp = gnome_help_file_find_file ("module", "page.html");
|
|
if (tmp) {
|
|
gnome_help_goto(0, tmp);
|
|
g_free(tmp);
|
|
}
|
|
</programlisting>
|
|
<note>
|
|
<title>NOTE</title>
|
|
<para>
|
|
The example above is in the C language, please refer to other
|
|
documentation or forums for other GNOME language bindings.
|
|
</para>
|
|
</note>
|
|
</sect1>
|
|
|
|
<!-- ################# Packaging Applet Documentation ############### -->
|
|
|
|
<sect1 id="packagingappletdocs">
|
|
<title>Packaging Applet Documentation</title>
|
|
<sect2 id="appletfiles">
|
|
<title>Applet Documentation Files</title>
|
|
<para>
|
|
In GNOME 2.0 each applet will have its own documentation
|
|
installed separately, and the GNOME 2.0 help
|
|
browser (<application>Nautilus</application>) will dynamically
|
|
merge the applet documents into a single virtual book
|
|
called <citetitle>GNOME Applets</citetitle>. 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 <citetitle>GNOME Applets</citetitle> book before
|
|
distribution. Telsa
|
|
<email>hobbit@aloss.ukuu.org.uk</email> 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.
|
|
</para>
|
|
<para>
|
|
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).
|
|
</para>
|
|
<para>
|
|
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 <sgmltag><xref></sgmltag> links to
|
|
the introductory chapter of the <citetitle>GNOME
|
|
Applets</citetitle> book must be removed (as the 1.x
|
|
<application>GNOME Help Browser</application> 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 <citetitle>GNOME Applets</citetitle> book, you must
|
|
remember to add <sgmltag><legalnotice></sgmltag> and
|
|
<sgmltag><copyright></sgmltag> sections.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="appletmenu">
|
|
<title>Adding Documentation to an Applet Menu</title>
|
|
<note>
|
|
<title>Developer Information</title>
|
|
<para>
|
|
This section is for developers. Documentation authors
|
|
generally do not need to know this material.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
Applets should have <guimenu>About</guimenu> and
|
|
<guimenu>Manual</guimenu> 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.
|
|
</para>
|
|
<para>
|
|
To add an applet's manual to its applet menu, use:
|
|
<programlisting>
|
|
/* add an item to the applet menu */
|
|
applet_widget_register_callback(APPLET_WIDGET(applet), "manual",
|
|
_("Manual"), &open_manual, NULL);
|
|
</programlisting>
|
|
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.
|
|
</para>
|
|
<para>
|
|
You will need to write a simple callback function to open the
|
|
help browser to the appropriate document. This is done using
|
|
the <function>gnome_help_file_find_file</function> function,
|
|
as described in <xref linkend="applicationhelpbuttons" />.
|
|
</para>
|
|
<para>
|
|
You will also want to add an <guimenu>About</guimenu> menu
|
|
item to the applet's menu. This is a
|
|
stock menu item and is done:
|
|
<programlisting>
|
|
applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about",
|
|
GNOME_STOCK_MENU_ABOUT, _("About"), &my_applet_cb_about,
|
|
NULL);
|
|
</programlisting>
|
|
</para>
|
|
<para>
|
|
More information can be found at <ulink type="http"
|
|
url="http://developer.gnome.org/doc/tutorials/applet/index.html">Writing
|
|
GNOME panel applets using the GTK+/GTK-- widget set</ulink>.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
|
|
<!-- ################# Writing Context Sensitive Help ###############
|
|
-->
|
|
|
|
<sect1 id="writingcontextsensitivehelp">
|
|
<title>Writing Context Sensitive Help (coming in GNOME-2.0)</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect1>
|
|
|
|
<!-- ################# Referring to Other GNOME Documentation
|
|
############# -->
|
|
|
|
<sect1 id="referring">
|
|
<title>Referring to Other GNOME Documentation (coming in
|
|
GNOME-2.0)</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect1>
|
|
|
|
|
|
<!-- ################# Basics of Documentation Style ############### -->
|
|
|
|
<sect1 id="basics">
|
|
<title>Basics of Documentation Style</title>
|
|
<para>
|
|
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 <emphasis>become</emphasis>
|
|
experts. Remember, your goal is to produce <emphasis>complete,
|
|
intuitive and clear</emphasis> documentation.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<!-- *********** Basics of Documentation Style: planning -->
|
|
|
|
<sect2 id="styleplanning">
|
|
<title>Planning</title>
|
|
<para>
|
|
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
|
|
<sgmltag><book></sgmltag> tag instead of
|
|
<sgmltag><chapter></sgmltag> or
|
|
<sgmltag><article></sgmltag>.
|
|
</para>
|
|
</sect2>
|
|
|
|
|
|
<!-- ####### Basics of Documentation Style | Balance ####### -->
|
|
<sect2 id="balance">
|
|
<title>Achieving a Balanced Style</title>
|
|
|
|
<para>
|
|
Just as you need to juggle expert and novice readers,
|
|
you'll have to juggle a number of other extremes as you write:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Be engaging and friendly, yet professional. Games
|
|
documents may be less formal than productivity
|
|
application documents (people don't
|
|
<emphasis>use</emphasis> games, they
|
|
<emphasis>play</emphasis> 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.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
</para>
|
|
</sect2>
|
|
|
|
|
|
<!-- ####### Basics of Documentation Style | Structure ####### -->
|
|
|
|
<sect2 id="stylestructure">
|
|
<title>Structure</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
As to linking, there's some disagreement about whether to use
|
|
<sgmltag><xref></sgmltag> <sgmltag><link></sgmltag>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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<sgmltag><book></sgmltag>, it will probably be best to
|
|
contribute to that rather than developing your own.
|
|
</para>
|
|
</sect2>
|
|
<!-- ####### Basics of Documentation Style | Grammar & Spelling ####### -->
|
|
|
|
<sect2 id="stylegrammar">
|
|
<title>Grammar and Spelling</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!-- ################# Teamwork ############### -->
|
|
|
|
<sect1 id="teamwork">
|
|
<title>Teamwork</title> <!-- ####### Teamwork | Working With The
|
|
GDP Team ####### -->
|
|
|
|
<sect2 id="teamworkgdp">
|
|
<title>Working With The GDP Team</title>
|
|
<para>
|
|
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 <citetitle>GDP Documentation
|
|
Status Table</citetitle> (<ulink
|
|
url="http://www.gnome.org/gdp/doctable/"
|
|
type="http">http://www.gnome.org/gdp/doctable/</ulink>) 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 <ulink type="http"
|
|
url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
|
|
<citetitle>gnome-doc-list mailing list</citetitle></ulink>.
|
|
</para>
|
|
<para>
|
|
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 <ulink type="http"
|
|
url="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/">
|
|
<citetitle>gnome-doc-list mailing list</citetitle></ulink>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- ####### Teamwork | Working With Developers ####### -->
|
|
|
|
<sect2 id="teamworkdevelopers">
|
|
<title>Working With Developers</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- ####### Teamwork | Working With Users #######
|
|
|
|
<sect2 id="teamworkusers">
|
|
<title>Working With Users</title>
|
|
<para>
|
|
Some document authors may wish to get feedback on their
|
|
documents directly from users. This may be done by ...
|
|
</para>
|
|
</sect2>-->
|
|
</sect1>
|
|
|
|
<!-- ################# Finishing a Document ############### -->
|
|
|
|
<sect1 id="finishing">
|
|
<title>Finishing A Document</title>
|
|
|
|
<!-- ####### Finishing a Document | Editting the Document ####### -->
|
|
|
|
<sect2 id="editting">
|
|
<title>Editing The Document</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- ####### Finishing a Document | Submitting the Document ####### -->
|
|
|
|
<sect2 id="submitting">
|
|
<title>Submitting The Document</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
The final step is to email the GNOME Translation Team at
|
|
<email>gnome-i18n@nuclecu.unam.mx</email> to notify them that
|
|
there is a new document for them to translate.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!-- ################# Resources ############### -->
|
|
|
|
<sect1 id="resources">
|
|
<title>Resources</title>
|
|
<!-- ####### Resources | Resources on the Web ####### -->
|
|
|
|
<sect2 id="resourcesweb">
|
|
<title>Resources On The Web</title> <para> The <ulink
|
|
type="http" url="http://developer.gnome.org/projects/gdp/">GNOME
|
|
Documentation Project Web page</ulink> lists current GDP
|
|
projects and members.
|
|
</para>
|
|
<para>
|
|
The <ulink url="http://www.gnome.org/gdp/doctable/"
|
|
type="http">GDP Documentation Status Table</ulink> tracks the
|
|
status of all the various documentation components of GNOME.
|
|
</para>
|
|
<para>
|
|
Norman Walsh's <ulink url="http://www.docbook.org"
|
|
type="http"> <citetitle>DocBook: The Definitive
|
|
Guide</citetitle></ulink> in an excellent book on DocBook,
|
|
available both online and in print.
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- ####### Resources | Books ####### -->
|
|
|
|
<sect2 id="resourcesbooks">
|
|
<title>Books</title>
|
|
<para>
|
|
Docbook: The Definitive Guide is available in both printed
|
|
form and on the web at:
|
|
<ulink url="http://www.docbook.org/tdg/index.html">
|
|
<citetitle>Docbook: The Definitive Guide</citetitle>
|
|
</ulink>
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- ####### Resources | Mailing Lists ####### -->
|
|
|
|
<sect2 id="mailinglists">
|
|
<title>Mailing Lists</title>
|
|
<para>
|
|
The <emphasis>gnome-docs-list</emphasis> 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 <ulink
|
|
url="http://www.gnome.org/resources/mailing-lists.html"
|
|
type="http">GNOME Mailing Lists</ulink>. This is a rather
|
|
low-volume list, so you will not be flooded with messages.
|
|
</para>
|
|
</sect2>
|
|
|
|
<!-- ####### Resources | IRC ####### -->
|
|
|
|
<sect2 id="irc">
|
|
<title>IRC</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<!-- ################# Example Docs ###############
|
|
|
|
<appendix id="exampledocs">
|
|
<title>Example Docs</title>
|
|
|
|
####### Example Docs | Example 1: Application Manual #######
|
|
|
|
<sect1 id="ex1">
|
|
<title>Example 1: Application Manual</title>
|
|
<programlisting>
|
|
<![CDATA[ (Put sgml here.)]]> </programlisting>
|
|
</sect1>
|
|
|
|
####### Example Docs | Example 2: Applet Manual #######
|
|
|
|
<sect1 id="ex2">
|
|
<title>Example 2: Applet Manual</title>
|
|
<programlisting>
|
|
<![CDATA[(Put sgml here.)]]> </programlisting>
|
|
</sect1>
|
|
|
|
##### Example Docs | Example 3: Application Context Sensitive Help ####
|
|
|
|
<sect1 id="ex3">
|
|
<title>Example 3: Application Context Sensitive Help</title>
|
|
<programlisting>
|
|
<![CDATA[(Put sgml here.)]]> </programlisting>
|
|
</sect1>
|
|
|
|
####### Example Docs | Example 4: Complete Application: gnome-hello #######
|
|
|
|
<sect1 id="ex4">
|
|
<title>Example 4: Complete Application: gnome-hello</title>
|
|
<programlisting>
|
|
<![CDATA[(Put sgml here.)]]> </programlisting>
|
|
</sect1>
|
|
|
|
####### Example Docs | Example 5: Tutorial #######
|
|
|
|
<sect1 id="ex5">
|
|
<title>Example 5: Tutorial</title>
|
|
<programlisting>
|
|
<![CDATA[(Put sgml here.)]]> </programlisting>
|
|
</sect1>
|
|
</appendix>-->
|
|
|
|
<!-- ################# Document Templates ############### -->
|
|
|
|
<appendix id="templates">
|
|
<title>Document Templates</title>
|
|
<!-- ####### Document Templates | Templates 1: Application Manual ####### -->
|
|
|
|
<sect1 id="template1">
|
|
<title>Template 1: Application Manual</title>
|
|
<para>
|
|
The following template should be used for all application
|
|
manuals. You can always get the latest copy of this
|
|
template from <ulink type="http"
|
|
url="http://developer.gnome.org/projects/gdp/templates.html">GDP
|
|
Documentation Templates</ulink>.
|
|
<programlisting>
|
|
|
|
<![CDATA[
|
|
<!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 separate from the main window
|
|
section. Since they were both so closely involved with the main
|
|
window, I decided to have them as sect3's instead. 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 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>
|
|
— 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>
|
|
— This saves your file.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<menuchoice>
|
|
<shortcut>
|
|
<keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo>
|
|
</shortcut>
|
|
<guimenuitem>Close</guimenuitem>
|
|
</menuchoice>
|
|
— This closes your file.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<menuchoice>
|
|
<shortcut>
|
|
<keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
|
|
</shortcut>
|
|
<guimenuitem>Exit</guimenuitem>
|
|
</menuchoice>
|
|
— 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>
|
|
— 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>
|
|
— 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>
|
|
— This pastes any text or data which is copied into
|
|
the buffer.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<guimenuitem>COMMAND1…</guimenuitem>
|
|
— This opens the <interface>COMMAND1</interface>
|
|
dialog, which is used to ....
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<guimenuitem>COMMAND2</guimenuitem>
|
|
— This ....
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry>
|
|
<term><guimenu>Settings</guimenu></term>
|
|
<listitem>
|
|
<para>
|
|
This menu contains:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<guimenuitem>Preferences…</guimenuitem>
|
|
— 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> —
|
|
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> — This
|
|
opens the <application>GNOME Help
|
|
Browser</application> and displays this manual.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<guimenuitem>About</guimenuitem> — 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>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
]]>
|
|
|
|
|
|
</programlisting>
|
|
</para>
|
|
</sect1>
|
|
|
|
<!-- ####### Document Templates | Templates 2-1.x: Applet Manual ####### -->
|
|
|
|
<sect1 id="template2-1x">
|
|
<title>Template 2: Applet Manual For GNOME 1.x</title>
|
|
<para>
|
|
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 <ulink type="http"
|
|
url="http://developer.gnome.org/projects/gdp/templates.html">GDP
|
|
Documentation Templates</ulink>. Note that the template
|
|
consists of two files; the first file calls the second as an
|
|
entity. You should name the first file
|
|
<filename><replaceable>appletname</replaceable>-applet.sgml</filename>
|
|
and the second file should be named
|
|
<filename><replaceable>appletname</replaceable>.sgml</filename>,
|
|
where
|
|
<filename><replaceable>appletname</replaceable></filename> is
|
|
the name of the applet.
|
|
<programlisting>
|
|
|
|
<![CDATA[
|
|
<!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>
|
|
|
|
|
|
]]>
|
|
|
|
|
|
</programlisting>
|
|
<programlisting>
|
|
<![CDATA[
|
|
<!-- 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 …. 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…</guimenuitem> —
|
|
opens the <link linkend="APPLET-prefs">
|
|
<guilabel>Properties</guilabel></link> dialog.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<guimenuitem>Help</guimenuitem> —
|
|
displays this document.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<guimenuitem>About…</guimenuitem> —
|
|
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…</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) — If this button is
|
|
checked…(description)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
(Configuration Item Label) — Selecting this
|
|
button…(description)
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
(Configuration Item Label) — Enter the name of
|
|
…(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>
|
|
|
|
|
|
|
|
|
|
]]>
|
|
|
|
|
|
|
|
</programlisting>
|
|
</para>
|
|
</sect1>
|
|
|
|
<!-- ####### Document Templates | Templates 2-2.x: Applet Manual ####### -->
|
|
|
|
<sect1 id="template2-2x">
|
|
<title>Template 2: Applet Manual For GNOME 2.x</title>
|
|
<para>
|
|
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 <ulink type="http"
|
|
url="http://developer.gnome.org/projects/gdp/templates.html">GDP
|
|
Documentation Templates</ulink>.
|
|
</para>
|
|
<para>
|
|
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
|
|
<filename>gnome-applets.sgml</filename>. Name the second file
|
|
according to the applet's name:
|
|
<filename><replaceable>appletname</replaceable>-applet.sgml</filename>.
|
|
Make sure you update the entity
|
|
at the top of the shell document to reflect the new name of
|
|
the applet document.
|
|
</para>
|
|
<para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
<!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> —
|
|
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> —
|
|
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> —
|
|
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> —
|
|
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 — <ulink type="http"
|
|
url="http://developer.gnome.org">The GNOME Development
|
|
Site</ulink>, documentation writers — <ulink type="http"
|
|
url="http://developer.gnome.org/projects/gdp">The GNOME Documentation
|
|
Project</ulink>, icon design artists — <ulink type="http"
|
|
url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>,
|
|
general — <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>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
]]>
|
|
</programlisting>
|
|
|
|
<programlisting>
|
|
<![CDATA[
|
|
|
|
<!-- 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> — 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> — 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>
|
|
|
|
|
|
|
|
|
|
|
|
]]>
|
|
|
|
|
|
</programlisting>
|
|
</para>
|
|
</sect1>
|
|
|
|
<!-- ####### Document Templates | Templates 3: Application Help #######
|
|
|
|
<sect1 id="template3">
|
|
<title>Template 2: Application Help</title>
|
|
<programlisting>
|
|
<![CDATA[(Put sgml here.)]]> </programlisting>
|
|
</sect1>
|
|
|
|
####### Document Templates | Templates 4: Application Context Sensitive Help #######
|
|
|
|
<sect1 id="template4">
|
|
<title>Template 3: Application Context Sensitive Help</title>
|
|
<para>
|
|
Context sensitive help is still in development.
|
|
</para>
|
|
</sect1>
|
|
|
|
####### Document Templates | Templates 5: Complete Application: gnome-hello #######
|
|
|
|
<sect1 id="template5">
|
|
<title>Template 4: Complete Application: gnome-hello</title>
|
|
<programlisting>
|
|
<![CDATA[(Put sgml here.)]]>
|
|
</programlisting>
|
|
</sect1>
|
|
|
|
####### Document Templates | Templates 6: Tutorial #######
|
|
|
|
<sect1 id="template6">
|
|
<title>Template 5: Tutorial</title>
|
|
<programlisting>
|
|
<![CDATA[(Put sgml here.)]]>
|
|
</programlisting>
|
|
</sect1>-->
|
|
</appendix>
|
|
|
|
</article>
|