+Fri May 11 16:20:40 CEST 2001 Daniel Veillard <Daniel.Veillard@imag.fr>
+
+ * configure.in tests/XSLTMark/Makefile.am: try to handle gracefully
+ the cases where perl is not in the path (nor in /usr/bin)
+ * tests/docbook/result/html/gdp-handbook.html
+ tests/docbook/result/html/kwrite.html
+ tests/docbook/test/gdp-handbook.xml
+ tests/docbook/test/kwrite.xml: commited a few more DocBook tests
+
Wed May 9 12:29:47 CEST 2001 Daniel Veillard <Daniel.Veillard@imag.fr>
* libxslt/xsltproc.c: added --nonet and --warnnet to catch
AC_CHECK_FUNC(fabs, , AC_CHECK_LIB(m, pow,
[M_LIBS="-lm"; AC_DEFINE(HAVE_FABS)]))
+dnl
+dnl Perl is just needed for generating some data for XSLtmark
+dnl
+
+AC_CHECK_PROG(perl_val, perl, true, false)
+AM_CONDITIONAL(WITH_PERL, $perl_val)
dnl
dnl Debug for DV
xslbench3.out xslbench3.xsl \
xslbenchdream.xml
+if WITH_PERL
+PERL = perl
+endif
+
$(top_builddir)/libxslt/xsltproc:
@(cd ../../libxslt ; make xsltproc)
clean:
rm -f *.tmp *~ core db100.xml db1000.xml db10000.xml
+
+if WITH_PERL
db100.xml: $(srcdir)/dbgen.pl
- $(srcdir)/dbgen.pl 100 > db100.xml
+ perl $(srcdir)/dbgen.pl 100 > db100.xml
db1000.xml: $(srcdir)/dbgen.pl
- $(srcdir)/dbgen.pl 1000 > db1000.xml
+ perl $(srcdir)/dbgen.pl 1000 > db1000.xml
db10000.xml: $(srcdir)/dbgen.pl
- $(srcdir)/dbgen.pl 10000 > db10000.xml
+ perl $(srcdir)/dbgen.pl 10000 > db10000.xml
alphabetize: db100.xml
@(rm -f .memdump ; touch .memdump)
else diff $(srcdir)/alphabetize.out alphabetize.tmp ; fi ; \
grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-# reference=alphabetize.ref
-
-attsets:
- @(rm -f .memdump ; touch .memdump)
- @(echo attsets)
- @($(top_builddir)/libxslt/xsltproc attsets.xsl chart.xml > attsets.tmp; \
- if [ ! -f $(srcdir)/attsets.out ] ; then cp attsets.tmp $(srcdir)/attsets.out ; \
- else diff $(srcdir)/attsets.out attsets.tmp ; fi ; \
- grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-# reference=attsets.ref
+# reference=alphabetize.ref
avts: db100.xml
@(rm -f .memdump ; touch .memdump)
# reference=avts.ref
+creation: db100.xml
+ @(rm -f .memdump ; touch .memdump)
+ @(echo creation)
+ @($(top_builddir)/libxslt/xsltproc creation.xsl db100.xml > creation.tmp; \
+ if [ ! -f $(srcdir)/creation.out ] ; then cp creation.tmp $(srcdir)/creation.out ; \
+ else diff $(srcdir)/creation.out creation.tmp ; fi ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
+
+# reference=creation.ref
+
+dbonerow: db10000.xml
+ @(rm -f .memdump ; touch .memdump)
+ @(echo dbonerow)
+ @($(top_builddir)/libxslt/xsltproc dbonerow.xsl db10000.xml > dbonerow.tmp; \
+ if [ ! -f $(srcdir)/dbonerow.out ] ; then cp dbonerow.tmp $(srcdir)/dbonerow.out ; \
+ else diff $(srcdir)/dbonerow.out dbonerow.tmp ; fi ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
+
+# reference=dbonerow.ref
+
+dbtail: db100.xml
+ @(rm -f .memdump ; touch .memdump)
+ @(echo dbtail)
+ @($(top_builddir)/libxslt/xsltproc dbtail.xsl db100.xml > dbtail.tmp; \
+ if [ ! -f $(srcdir)/dbtail.out ] ; then cp dbtail.tmp $(srcdir)/dbtail.out ; \
+ else diff $(srcdir)/dbtail.out dbtail.tmp ; fi ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
+
+# reference=dbtail.ref
+
+decoy: db100.xml
+ @(rm -f .memdump ; touch .memdump)
+ @(echo decoy)
+ @($(top_builddir)/libxslt/xsltproc decoy.xsl db100.xml > decoy.tmp; \
+ if [ ! -f $(srcdir)/decoy.out ] ; then cp decoy.tmp $(srcdir)/decoy.out ; \
+ else diff $(srcdir)/decoy.out decoy.tmp ; fi ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
+
+# reference=patterns.ref
+
+encrypt: db100.xml
+ @(rm -f .memdump ; touch .memdump)
+ @(echo encrypt)
+ @($(top_builddir)/libxslt/xsltproc encrypt.xsl db100.xml > encrypt.tmp; \
+ if [ ! -f $(srcdir)/encrypt.out ] ; then cp encrypt.tmp $(srcdir)/encrypt.out ; \
+ else diff $(srcdir)/encrypt.out encrypt.tmp ; fi ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
+
+# reference=encrypt.ref
+
+functions: db100.xml
+ @(rm -f .memdump ; touch .memdump)
+ @(echo functions)
+ @($(top_builddir)/libxslt/xsltproc functions.xsl db100.xml > functions.tmp; \
+ if [ ! -f $(srcdir)/functions.out ] ; then cp functions.tmp $(srcdir)/functions.out ; \
+ else diff $(srcdir)/functions.out functions.tmp ; fi ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
+
+# reference=functions.ref
+
+identity: db1000.xml
+ @(rm -f .memdump ; touch .memdump)
+ @(echo identity)
+ @($(top_builddir)/libxslt/xsltproc identity.xsl db1000.xml > identity.tmp; \
+ if [ ! -f $(srcdir)/identity.out ] ; then cp identity.tmp $(srcdir)/identity.out ; \
+ else diff $(srcdir)/identity.out identity.tmp ; fi ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
+
+# reference=identity.ref
+
+inventory:
+ @(rm -f .memdump ; touch .memdump)
+ @(echo inventory)
+ @($(top_builddir)/libxslt/xsltproc inventory.xsl inventory.xml > inventory.tmp; \
+ if [ ! -f $(srcdir)/inventory.out ] ; then cp inventory.tmp $(srcdir)/inventory.out ; \
+ else diff $(srcdir)/inventory.out inventory.tmp ; fi ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
+
+# reference=inventory.ref
+
+patterns: db100.xml
+ @(rm -f .memdump ; touch .memdump)
+ @(echo patterns)
+ @($(top_builddir)/libxslt/xsltproc patterns.xsl db100.xml > patterns.tmp; \
+ if [ ! -f $(srcdir)/patterns.out ] ; then cp patterns.tmp $(srcdir)/patterns.out ; \
+ else diff $(srcdir)/patterns.out patterns.tmp ; fi ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
+
+# reference=patterns.ref
+
+prettyprint: db100.xml
+ @(rm -f .memdump ; touch .memdump)
+ @(echo prettyprint)
+ @($(top_builddir)/libxslt/xsltproc prettyprint.xsl db100.xml > prettyprint.tmp; \
+ if [ ! -f $(srcdir)/prettyprint.out ] ; then cp prettyprint.tmp $(srcdir)/prettyprint.out ; \
+ else diff $(srcdir)/prettyprint.out prettyprint.tmp ; fi ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
+
+# reference=prettyprint.ref
+
+stringsort: db1000.xml
+ @(rm -f .memdump ; touch .memdump)
+ @(echo stringsort)
+ @($(top_builddir)/libxslt/xsltproc stringsort.xsl db1000.xml > stringsort.tmp; \
+ if [ ! -f $(srcdir)/stringsort.out ] ; then cp stringsort.tmp $(srcdir)/stringsort.out ; \
+ else diff $(srcdir)/stringsort.out stringsort.tmp ; fi ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
+
+# reference=stringsort.ref
+
+endif
+
+attsets:
+ @(rm -f .memdump ; touch .memdump)
+ @(echo attsets)
+ @($(top_builddir)/libxslt/xsltproc attsets.xsl chart.xml > attsets.tmp; \
+ if [ ! -f $(srcdir)/attsets.out ] ; then cp attsets.tmp $(srcdir)/attsets.out ; \
+ else diff $(srcdir)/attsets.out attsets.tmp ; fi ; \
+ grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
+
+# reference=attsets.ref
+
axis:
@(rm -f .memdump ; touch .memdump)
@(echo axis)
# reference=chart.ref
-creation: db100.xml
- @(rm -f .memdump ; touch .memdump)
- @(echo creation)
- @($(top_builddir)/libxslt/xsltproc creation.xsl db100.xml > creation.tmp; \
- if [ ! -f $(srcdir)/creation.out ] ; then cp creation.tmp $(srcdir)/creation.out ; \
- else diff $(srcdir)/creation.out creation.tmp ; fi ; \
- grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-
-# reference=creation.ref
-
current:
@(rm -f .memdump ; touch .memdump)
@(echo current)
# reference=current.ref
-dbonerow: db10000.xml
- @(rm -f .memdump ; touch .memdump)
- @(echo dbonerow)
- @($(top_builddir)/libxslt/xsltproc dbonerow.xsl db10000.xml > dbonerow.tmp; \
- if [ ! -f $(srcdir)/dbonerow.out ] ; then cp dbonerow.tmp $(srcdir)/dbonerow.out ; \
- else diff $(srcdir)/dbonerow.out dbonerow.tmp ; fi ; \
- grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-
-# reference=dbonerow.ref
-
-dbtail: db100.xml
- @(rm -f .memdump ; touch .memdump)
- @(echo dbtail)
- @($(top_builddir)/libxslt/xsltproc dbtail.xsl db100.xml > dbtail.tmp; \
- if [ ! -f $(srcdir)/dbtail.out ] ; then cp dbtail.tmp $(srcdir)/dbtail.out ; \
- else diff $(srcdir)/dbtail.out dbtail.tmp ; fi ; \
- grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-
-# reference=dbtail.ref
-
-decoy: db100.xml
- @(rm -f .memdump ; touch .memdump)
- @(echo decoy)
- @($(top_builddir)/libxslt/xsltproc decoy.xsl db100.xml > decoy.tmp; \
- if [ ! -f $(srcdir)/decoy.out ] ; then cp decoy.tmp $(srcdir)/decoy.out ; \
- else diff $(srcdir)/decoy.out decoy.tmp ; fi ; \
- grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-
-# reference=patterns.ref
-
depth:
@(rm -f .memdump ; touch .memdump)
@(echo depth)
# reference=depth.ref
-encrypt: db100.xml
- @(rm -f .memdump ; touch .memdump)
- @(echo encrypt)
- @($(top_builddir)/libxslt/xsltproc encrypt.xsl db100.xml > encrypt.tmp; \
- if [ ! -f $(srcdir)/encrypt.out ] ; then cp encrypt.tmp $(srcdir)/encrypt.out ; \
- else diff $(srcdir)/encrypt.out encrypt.tmp ; fi ; \
- grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-
-# reference=encrypt.ref
-
-functions: db100.xml
- @(rm -f .memdump ; touch .memdump)
- @(echo functions)
- @($(top_builddir)/libxslt/xsltproc functions.xsl db100.xml > functions.tmp; \
- if [ ! -f $(srcdir)/functions.out ] ; then cp functions.tmp $(srcdir)/functions.out ; \
- else diff $(srcdir)/functions.out functions.tmp ; fi ; \
- grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-
-# reference=functions.ref
-
game:
@(rm -f .memdump ; touch .memdump)
@(echo game)
# reference=html.ref
-identity: db1000.xml
- @(rm -f .memdump ; touch .memdump)
- @(echo identity)
- @($(top_builddir)/libxslt/xsltproc identity.xsl db1000.xml > identity.tmp; \
- if [ ! -f $(srcdir)/identity.out ] ; then cp identity.tmp $(srcdir)/identity.out ; \
- else diff $(srcdir)/identity.out identity.tmp ; fi ; \
- grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-
-# reference=identity.ref
-
-inventory:
- @(rm -f .memdump ; touch .memdump)
- @(echo inventory)
- @($(top_builddir)/libxslt/xsltproc inventory.xsl inventory.xml > inventory.tmp; \
- if [ ! -f $(srcdir)/inventory.out ] ; then cp inventory.tmp $(srcdir)/inventory.out ; \
- else diff $(srcdir)/inventory.out inventory.tmp ; fi ; \
- grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-
-# reference=inventory.ref
-
metric:
@(rm -f .memdump ; touch .memdump)
@(echo metric)
# reference=oddtemplate.ref
-patterns: db100.xml
- @(rm -f .memdump ; touch .memdump)
- @(echo patterns)
- @($(top_builddir)/libxslt/xsltproc patterns.xsl db100.xml > patterns.tmp; \
- if [ ! -f $(srcdir)/patterns.out ] ; then cp patterns.tmp $(srcdir)/patterns.out ; \
- else diff $(srcdir)/patterns.out patterns.tmp ; fi ; \
- grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-
-# reference=patterns.ref
-
-prettyprint: db100.xml
- @(rm -f .memdump ; touch .memdump)
- @(echo prettyprint)
- @($(top_builddir)/libxslt/xsltproc prettyprint.xsl db100.xml > prettyprint.tmp; \
- if [ ! -f $(srcdir)/prettyprint.out ] ; then cp prettyprint.tmp $(srcdir)/prettyprint.out ; \
- else diff $(srcdir)/prettyprint.out prettyprint.tmp ; fi ; \
- grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-
-# reference=prettyprint.ref
-
priority:
@(rm -f .memdump ; touch .memdump)
@(echo priority)
# reference=reverser.ref
-stringsort: db1000.xml
- @(rm -f .memdump ; touch .memdump)
- @(echo stringsort)
- @($(top_builddir)/libxslt/xsltproc stringsort.xsl db1000.xml > stringsort.tmp; \
- if [ ! -f $(srcdir)/stringsort.out ] ; then cp stringsort.tmp $(srcdir)/stringsort.out ; \
- else diff $(srcdir)/stringsort.out stringsort.tmp ; fi ; \
- grep "MORY ALLO" .memdump | grep -v "MEMORY ALLOCATED : 0" ; exit 0 )
-
-# reference=stringsort.ref
-
summarize:
@(rm -f .memdump ; touch .memdump)
@(echo summarize)
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
+<title>The GNOME Handbook of Writing Software Documentation</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.29">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div id="index" class="article">
+<div class="titlepage">
+<div><h1 class="title">
+<a name="index"></a>The GNOME Handbook of Writing Software Documentation</h1></div>
+<div>
+<h3 class="author">David Mason</h3>
+<div class="affiliation">
+<span class="orgname">Red Hat, Inc.<br>
+</span>
+<pre class="address">
+ <tt><<a href="mailto:dcm@redhat.com">dcm@redhat.com</a>></tt>
+ </pre>
+</div>
+<h3 class="author">Daniel Mueth</h3>
+<div class="affiliation"><pre class="address">
+ <tt><<a href="mailto:d-mueth@uchicago.edu">d-mueth@uchicago.edu</a>></tt>
+ </pre></div>
+<h3 class="author">Alexander Kirillov</h3>
+<div class="affiliation"><pre class="address">
+ <tt><<a href="mailto:kirillov@math.sunysb.edu">kirillov@math.sunysb.edu</a>></tt>
+ </pre></div>
+</div>
+<div><span class="releaseinfo">
+ This is a pre-release!
+ <br>
+</span></div>
+<div><p class="copyright">Copyright © 2000 by Red Hat, Inc., Daniel Mueth, and Alexander Kirillov</p></div>
+<div><div class="legalnotice">
+<p>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the <i>GNU Free Documentation
+ License</i>, Version 1.1 or any later version published
+ by the Free Software Foundation with no Invariant Sections, no
+ Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
+ of the <i>GNU Free Documentation License</i> from
+ the Free Software Foundation by visiting <a href="http://www.fsf.org" target="_top">their Web site</a> or by writing to:
+ Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
+ </p>
+<p>
+ Many of the names used by companies to distinguish their products and
+ services are claimed as trademarks. Where those names appear in any
+ GNOME documentation, and those trademarks are made aware to the members
+ of the GNOME Documentation Project, the names have been printed in caps
+ or initial caps.
+ </p>
+</div></div>
+<div><div class="revhistory"><table border="1" width="100%" summary="Revision history">
+<tr><th align="left" valign="top" colspan="2"><b>Revision History</b></th></tr>
+<tr>
+<td align="left">Revision
+ 0.99
+ </td>
+<td align="left">
+ 04.10.2000
+ </td>
+</tr>
+</table></div></div>
+<hr>
+</div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt> <a href="#intro">Introduction</a>
+</dt>
+<dd><dl>
+<dt> <a href="#gdp">The GNOME Documentation Project</a>
+</dt>
+<dt> <a href="#notation">Notation and Conventions</a>
+</dt>
+<dt> <a href="#about">About This Handbook</a>
+</dt>
+</dl></dd>
+<dt> <a href="#gettingstarted">Getting Started Writing GNOME Documentation</a>
+</dt>
+<dd><dl>
+<dt> <a href="#selecting">Selecting A Document</a>
+</dt>
+<dt> <a href="#docbook">Installing and Using DocBook</a>
+</dt>
+<dt> <a href="#gdptemplates">GDP Document Templates</a>
+</dt>
+<dt> <a href="#screenshots">Screenshots</a>
+</dt>
+<dt> <a href="#applicationbugs">Application Bugs</a>
+</dt>
+<dt> <a href="#cvs">Using CVS</a>
+</dt>
+</dl></dd>
+<dt> <a href="#gnomedocsystem">The GNOME Documentation System</a>
+</dt>
+<dd><dl>
+<dt> <a href="#gnomehelpbrowser">The GNOME Help Browser</a>
+</dt>
+<dt> <a href="#gnomehelpbrowser2">The GNOME Help Browser (GNOME-2.0)</a>
+</dt>
+<dt> <a href="#gnomehelponthefly">Dynamic Document Synthesis(GNOME-2.0)</a>
+</dt>
+<dt> <a href="#gnomehelpcomponents">The GNOME Documentation Components</a>
+</dt>
+</dl></dd>
+<dt> <a href="#docbookbasics">DocBook Basics </a>
+</dt>
+<dd><dl>
+<dt> <a href="#introtodocbook">Introduction to DocBook</a>
+</dt>
+<dt> <a href="#xml">XML and SGML</a>
+</dt>
+<dt> <a href="#structure"> Structure Elements</a>
+</dt>
+<dt> <a href="#inline">Inline Elements</a>
+</dt>
+</dl></dd>
+<dt> <a href="#conventions">GDP Documentation Conventions </a>
+</dt>
+<dd><dl>
+<dt> <a href="#conventionsalldocs">Conventions for All GDP Documentation</a>
+</dt>
+<dt> <a href="#conventionsappdocs">Conventions for Application Documentation</a>
+</dt>
+</dl></dd>
+<dt> <a href="#writingapplicationmanuals">Writing Application and Applet Manuals</a>
+</dt>
+<dt> <a href="#listingdocsinhelpmenu">Listing Documents in the Help Menu</a>
+</dt>
+<dt> <a href="#applicationhelpbuttons">Application Help Buttons</a>
+</dt>
+<dt> <a href="#packagingappletdocs">Packaging Applet Documentation</a>
+</dt>
+<dd><dl>
+<dt> <a href="#appletfiles">Applet Documentation Files</a>
+</dt>
+<dt> <a href="#appletmenu">Adding Documentation to an Applet Menu</a>
+</dt>
+</dl></dd>
+<dt> <a href="#writingcontextsensitivehelp">Writing Context Sensitive Help (coming in GNOME-2.0)</a>
+</dt>
+<dt> <a href="#referring">Referring to Other GNOME Documentation (coming in
+ GNOME-2.0)</a>
+</dt>
+<dt> <a href="#basics">Basics of Documentation Style</a>
+</dt>
+<dd><dl>
+<dt> <a href="#styleplanning">Planning</a>
+</dt>
+<dt> <a href="#balance">Achieving a Balanced Style</a>
+</dt>
+<dt> <a href="#stylestructure">Structure</a>
+</dt>
+<dt> <a href="#stylegrammar">Grammar and Spelling</a>
+</dt>
+</dl></dd>
+<dt> <a href="#teamwork">Teamwork</a>
+</dt>
+<dd><dl>
+<dt> <a href="#teamworkgdp">Working With The GDP Team</a>
+</dt>
+<dt> <a href="#teamworkdevelopers">Working With Developers</a>
+</dt>
+</dl></dd>
+<dt> <a href="#finishing">Finishing A Document</a>
+</dt>
+<dd><dl>
+<dt> <a href="#editting">Editing The Document</a>
+</dt>
+<dt> <a href="#submitting">Submitting The Document</a>
+</dt>
+</dl></dd>
+<dt> <a href="#resources">Resources</a>
+</dt>
+<dd><dl>
+<dt> <a href="#resourcesweb">Resources On The Web</a>
+</dt>
+<dt> <a href="#resourcesbooks">Books</a>
+</dt>
+<dt> <a href="#mailinglists">Mailing Lists</a>
+</dt>
+<dt> <a href="#irc">IRC</a>
+</dt>
+</dl></dd>
+</dl>
+</div>
+<div class="sect1">
+<a name="intro"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="intro"></a>
+<span class="title">Introduction</span>
+</h2></div></div>
+<div class="sect2">
+<a name="gdp"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="gdp"></a>
+<span class="title">The GNOME Documentation Project</span>
+</h3></div></div>
+<div class="sect3">
+<a name="goals"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="goals"></a>
+<span class="title">Goals</span>
+</h4></div></div>
+<p>
+ The GNOME Documentation Project (GDP) aims to provide GNOME
+ and GNOME applications with a complete, intuitive, and clear
+ documentation system. At the center of the GDP is the
+ GNOME Help Browser, which
+ presents a unified interface to GNOME-specific documentation
+ as well as other Linux documentation such as man pages and
+ texinfo documents. The GNOME Help System provides a
+ comprehensive view of documentation on a machine by
+ dynamically assembling the documentation of GNOME
+ applications and components which are installed. The GDP is
+ responsible for writing numerous GNOME-related documents,
+ both for developers and for users. Developer documentation
+ includes <a href="http://developer.gnome.org/doc/API/" target="_top">APIs for the GNOME libraries</a>, <a href="http://developer.gnome.org/doc/whitepapers/" target="_top"><i>GNOME White
+ Papers</i></a>, GNOME developer <a href="http://developer.gnome.org/doc/tutorials/" target="_top">tutorials</a>, the <a href="http://developer.gnome.org/doc/FAQ/" target="_top"><i>GNOME Developer
+ FAQ</i></a>, the <a href="http://developer.gnome.org" target="_top">GNOME
+ Developer's Website</a>, and <i>GNOME
+ Handbook</i>'s, such as the one you are reading.
+ User documentation include the <a href="http://www.gnome.org/learn/" target="_top"><i>GNOME User's
+ Guide</i></a>, the <a href="http://www.gnome.org/learn/" target="_top"><i>GNOME FAQ</i></a>, and
+ GNOME application documentation. Most GNOME applications
+ have their own manual in addition to context sensitive help.
+ </p>
+</div>
+<div class="sect3">
+<a name="joining"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="joining"></a>
+<span class="title">Joining the GDP</span>
+</h4></div></div>
+<p>
+ Documenting GNOME and all the numerous GNOME applications is
+ a very large project. The GDP is always looking for people
+ to help write, update, and edit documentation. If you are
+ interested in joining the GDP team, you should join the
+ <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
+ <i>gnome-doc-list mailing list</i> </a>.
+ Read <a href="#gettingstarted">the section called “Getting Started Writing GNOME Documentation”</a>, for help selecting a
+ project to work on. Feel free to introduce yourself on the
+ gnome-doc-list mailing list and indicate which project you
+ intend to work on, or else ask for suggestions of important
+ documents which need work done. You may also want to join the
+ #docs IRC channel on irc.gnome.org to meet other GDP members
+ and discuss any questions you may have. For a list of GDP
+ projects and members, see the
+ <a href="http://developer.gnome.org/projects/gdp" target="_top">
+ <i>GDP Website</i>
+</a>.
+ </p>
+</div>
+<div class="sect3">
+<a name="collaborating"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="collaborating"></a>
+<span class="title">Collaborating with the GDP</span>
+</h4></div></div>
+<p>
+ GNOME developers, packagers, and translators may not be
+ writing GNOME documentation but will want to understand how
+ the GNOME documentation system works and will need to
+ collaborate with GDP members. This document should help to
+ outline the structure of how the GNOME documentation system
+ works. Developers who do not write the documentation for
+ their applications are encouraged to find a GDP member to
+ write the documentation. This is best done by sending an
+ email to the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
+ <i>gnome-doc-list mailing list</i> </a>
+ describing the application, where it can be downloaded from,
+ and that the developer(s) would like a GDP member to write
+ documentation for the application. The #docs IRC channel on
+ irc.gnome.org is another option for contacting GDP members.
+ </p>
+</div>
+</div>
+<div class="sect2">
+<a name="notation"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="notation"></a>
+<span class="title">Notation and Conventions</span>
+</h3></div></div>
+<p>
+ This Handbook uses the following notation:
+ <div class="informaltable" id="id2727650">
+<p>
+<a name="id2727650"></a>
+<table border="0">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<tbody>
+<tr>
+<td><tt>/usr/bin</tt></td>
+<td>
+ Directory
+ </td>
+</tr>
+<tr>
+<td><tt>foo.sgml</tt></td>
+<td>
+ Filename
+ </td>
+</tr>
+<tr>
+<td><b>command</b></td>
+<td>
+ Command or text that would be typed.
+ </td>
+</tr>
+<tr>
+<td><b><i><tt>replaceable</tt></i></b></td>
+<td>
+ "Variable" text that can be replaced.
+ </td>
+</tr>
+<tr>
+<td><tt>Program or Doc Code</tt></td>
+<td>Program or document code</td>
+</tr>
+</tbody>
+</table>
+<p>
+</div>
+ </p>
+</div>
+<div class="sect2">
+<a name="about"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="about"></a>
+<span class="title">About This Handbook</span>
+</h3></div></div>
+<p>
+ This Handbook is a guide for both writing documentation for
+ GNOME components and applications and for properly binding and
+ packaging documentation into GNOME applications.
+ </p>
+<p>
+ This Handbook, like all GNOME documentation, was written in
+ DocBook(SGML) and is available in several formats including
+ SGML, HTML, PostScript, and PDF. For the latest version, see
+ <a href="http://developer.gnome.org/projects/gdp/handbook.html" target="_top">
+ <i>Getting The GNOME Handbook of Writing Software
+ Documentation</i> </a>. Alternately, one may
+ download it anonymously from GNOME CVS under <tt>gnome-docu/gdp</tt>.
+ </p>
+</div>
+</div>
+<div class="sect1">
+<a name="gettingstarted"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="gettingstarted"></a>
+<span class="title">Getting Started Writing GNOME Documentation</span>
+</h2></div></div>
+<div class="sect2">
+<a name="selecting"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="selecting"></a>
+<span class="title">Selecting A Document</span>
+</h3></div></div>
+<div class="sect3">
+<a name="know"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="know"></a>
+<span class="title">Document Something You Know</span>
+</h4></div></div>
+<p>
+ The most frequently asked question of new contributors who
+ join the GDP is "which document should I start
+ with?". Because most people involved are volunteers, we do
+ not <i>assign</i> projects and applications to
+ write documents for. The first step is all yours - you must
+ decide what about GNOME interests you most and find out if
+ it has complete documents or not.
+ </p>
+<p>
+ It is also important to spend some time with GNOME to make
+ sure you are familiar enough with it to be
+ <i>authoritative</i> in your writing. The
+ best way to do this is to just sit down and play with GNOME
+ as much as possible before starting to write.
+ </p>
+<p>
+ The easiest way to get started is to improve existing
+ documentation. If you notice some inaccuracies or omissions
+ in the documentation, or you think that you can explain the
+ material more clearly, just send your suggestions to the
+ author of the original documentation or to the GNOME
+ documentation project at <tt><<a href="mailto:docs@gnome.org">docs@gnome.org</a>></tt>.
+ </p>
+</div>
+<div class="sect3">
+<a name="doctable"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="doctable"></a>
+<span class="title">The GNOME Documentation Status Table</span>
+</h4></div></div>
+<p>
+ The <i>GDP Documentation Status Table</i>
+ (<i>DocTable</i>) (<a href="http://www.gnome.org/gdp/doctable/" target="_top">http://www.gnome.org/gdp/doctable/</a>) is a
+ web page which tracks the status of all the various
+ documentation components of GNOME. These components include
+ application documentation, internal GNOME component
+ documentation, user documentation, and developer
+ documentation. For each documentation item, it tracks the
+ current status of the documentation, who is working on the
+ particular document, where the documentation can be found,
+ and provides a forum for the discussion of each item.
+ </p>
+<p>
+ You should use the <i>DocTable</i> to help
+ you select a documentation item which needs work done. Once
+ you have selected an item to work on, please register
+ yourself as an author so that other authors do not duplicate
+ your work and may contact you to help or offer suggestions.
+ Also be sure to keep the status icons up-to-date so that
+ the GDP team can easily identify which items need additional
+ help. The <i>DocTable</i> also allows
+ people to make announcements and suggestions and to discuss
+ issues in the comments section.
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2719421">Note</a></h3>
+<p>
+ Note that the information in the
+ <i>DocTable</i> may not always be up-to-date
+ or accurate. When you assign yourself to documenting an
+ application, make sure you find out the latest status of
+ documentation by contacting the application author.
+ </p>
+</div>
+</div>
+</div>
+<div class="sect2">
+<a name="docbook"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="docbook"></a>
+<span class="title">Installing and Using DocBook</span>
+</h3></div></div>
+<p>
+ All documentation for the GNOME project is written in SGML
+ using the DocBook DTD. There are many advantages to using
+ this for documentation, not least of which is the single
+ source nature of SGML. To contribute to the GDP you should
+ learn to use DocBook.
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2719508">NOTE</a></h3>
+<p>
+ To get started writing for the GDP you do not need to rush
+ out and learn DocBook - if you feel it is too much to handle
+ for now, you can submit plain ASCII text to the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
+ <i>gnome-doc-list mailing list</i>
+ </a>and a volunteer will mark it up for you. Seeing your
+ document marked up will also be a great way for you to start
+ learning DocBook.
+ </p>
+</div>
+<div class="sect3">
+<a name="installingdocbook"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="installingdocbook"></a>
+<span class="title">Installing DocBook</span>
+</h4></div></div>
+<p>
+ Download and install the following <a href="ftp://sourceware.cygnus.com:/pub/docbook-tools/" target="_top">DocBook Tools packages</a>: jade, docbook,
+ jadetex, sgml-common, and stylesheets. (RPM users should note
+ that jade is platform dependent (eg. i386), while the other packages
+ are in the <tt>noarch</tt>
+ directory.) You can find more
+ information on DocBook Tools <a href=" http://sourceware.cygnus.com/docbook-tools/" target="_top">here</a>.
+ </p>
+<p>
+ If you are an Emacs user you may
+ want to grab the psgml package as well. This is a major mode
+ for editing sgml files in Emacs.
+ </p>
+</div>
+<div class="sect3">
+<a name="gdpstylesheets"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="gdpstylesheets"></a>
+<span class="title">GDP Stylesheets</span>
+</h4></div></div>
+<p>
+ The GDP uses its own DocBook stylesheets. To use the GDP
+ stylesheets, you should download the file
+ <tt>gdp-both.dsl</tt> from the <tt>gnome-docu/gdp/dsssl</tt> module in
+ CVS (or from <a href="http://developer.gnome.org/projects/gdp/stylesheets.html" target="_top">
+ GDP Custom DSSSL Stylesheet</a>)and copy it
+
+ over the file
+ <tt>/usr/lib/sgml/stylesheets/cygnus-both.dsl</tt>.
+ Alternately, you can download and install the
+ <a href="http://people.redhat.com/dcm/software.html" target="_top">gnome-doc-tools package</a> which will set
+ up the stylesheets as well as the DTD discussed below.
+ </p>
+</div>
+<div class="sect3">
+<a name="gdpdtd"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="gdpdtd"></a>
+<span class="title">GDP DTD (PNG Image Support)</span>
+</h4></div></div>
+<p>
+ Due to some license issues involved with the creation of
+ gifs, the GNOME Documentation Project has decided to use the
+ PNG image format for all images in GNOME documentation. You
+ can read more about the issues involved with gifs at <a href="http://www.gnu.org/philosophy/gif.html" target="_top">http://www.gnu.org/philosophy/gif.html</a>.
+ </p>
+<p>
+ The current DocBook DTD(3.1) does not include support for
+ embedding PNG images in your documents. Since the GDP uses
+ many screenshots in its documentation, we use our own
+ variation on the DocBook DTD which has PNG image support.
+ We encourage everybody to use this DTD instead of the
+ default DocBook DTD since your source document header and
+ your output document appearance subtly vary between the two
+ DTD's. To install the GDP custom DTD with PNG image support
+ by hand:
+ </p>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2719895"></a>
+ Download <a href="http://www.labs.redhat.com/png/png-support.html" target="_top">the
+ GDP DocBook DTD for PNG support</a> and install it
+ where you keep your DTD's. (On Red Hat use <tt>/usr/lib/sgml/</tt>.) Note that
+ the 3.0 DTD is missing support for the
+ <tt><legalnotice></tt> tag, so it is
+ recommended that you use version 3.1
+ </p></li>
+<li style="list-style-type: disc"><p>
+<a name="id2720062"></a>
+ Add the new DTD to your SGML CATALOG file. The location
+ of your SGML CATALOG file may vary depending upon your
+ distribution. (On Red Hat it is usually in
+ /usr/lib/sgml/CATALOG.) Add the following line to this
+ file:
+ <pre class="programlisting">
+PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.0//EN" "png-support-3.0.dtd"
+ </pre>
+ If you are using the 3.1 DTD, use:
+ <pre class="programlisting">
+PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN" "png-support-3.1.dtd"
+ </pre>
+ </p></li>
+</ul></div>
+<p>
+ Alternately, you can download and install the
+ <a href="http://people.redhat.com/dcm/software.html" target="_top">gnome-doc-tools package</a> which will set
+ up the custom stylesheets and DTD for you.
+ </p>
+<p>
+ To include PNG files in your documents, you will need to
+ indicate that you are using this special DTD. To do
+ this, use the following headers:
+ </p>
+<p>
+ Articles:
+ <pre class="programlisting">
+<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant
+V1.1//EN"[]>
+ </pre>
+ </p>
+<p>
+ Books:
+ <pre class="programlisting">
+<!DOCTYPE Book PUBLIC "-//GNOME//DTD DocBook PNG Variant
+V1.1//EN"[]>
+ </pre>
+ </p>
+</div>
+<div class="sect3">
+<a name="editors"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="editors"></a>
+<span class="title">Editors</span>
+</h4></div></div>
+<p>
+ There are many editors on Linux and UNIX systems available
+ to you. Which editor you use to work on the sgml documents
+ is completely up to you, as long as the editor is able to
+ preserve sgml and produce the source in a format that is
+ readable by everyone.
+ </p>
+<p>
+ Probably the two most popular editors available are
+ Emacs and
+ vi. These and other editors are
+ used regularly by members of the GDP. Emacs has a major
+ mode, psgml, for editing sgml files which can save you time
+ and effort in adding and closing tags. You will find the
+ psgml package in DocBook Tools, which is the standard set of
+ tools for the GDP. You may find out more about DocBook Tools
+ in <a href="#installingdocbook">the section called “Installing DocBook”</a>.
+ </p>
+</div>
+<div class="sect3">
+<a name="make-output"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="make-output"></a>
+<span class="title">Creating Something Useful with your Docs</span>
+</h4></div></div>
+<p>
+ The tools available in DocBook Tools allow you to convert
+ your sgml document to many different formats including html
+ and Postscript. The primary tool used to do the conversion
+ is an application called Jade. In
+ most cases you will not have to work directly with
+ Jade; Instead, you will use the
+ scripts provided by DocBook Tools.
+ </p>
+<p>
+ To preview your DocBook document, it is easiest to convert
+ it to <tt>html</tt>. If you have installed the
+ DocBook tools described above, all you have to do is to run
+ the command <tt>$</tt>
+<b>db2html
+ mydocument.sgml</b>. If there are no sgml syntax
+ errors, this will create a directory <tt>mydocument</tt> and place the
+ resulting html files in it. The title page of the document
+ will typically be
+ <tt>mydocument/index.html</tt>. If you have
+ screenshots in your document, you will have to copy these
+ files into the <tt>mydocument</tt> directory by
+ hand. You can use any web browser to view your document.
+ Note that every time you run <b>db2html</b>, it
+ creates the <tt>mydocument</tt> directory over, so
+ you will have to copy the screenshots over each time.
+ </p>
+<p>
+ You can also convert your document to PostScript by running
+ the command <tt>$</tt>
+<b>db2ps
+ mydocument.sgml</b>, after which you can print out or
+ view the resulting .ps file.
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2719968">NOTE</a></h3>
+<p>
+ The html files you get will not look quite the same as the
+ documentation distributed with GNOME unless you have the
+ custom stylesheets installed on your machine. DocBook
+ Tools' default stylesheets will produce a different look
+ to your docs. You can read more about the GDP stylesheets
+ in <a href="#gdpstylesheets">the section called “GDP Stylesheets”</a>.
+ </p>
+</div>
+</div>
+<div class="sect3">
+<a name="jadeimages"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="jadeimages"></a>
+<span class="title">Images in DocBook Tools</span>
+</h4></div></div>
+<p>
+ If your document uses images you will need to take note of a
+ few things that should take place in order for you to make
+ use of those images in your output.
+ </p>
+<p>
+ The DocBook Tools scripts and applications are smart enough
+ to know that when you are creating html you will be using
+ PNG files and when you are creating Postscript you will be
+ using EPS files (you must use EPS with Postscript).
+ </p>
+<p>
+ Thus, you should never explicitly
+ include the extension of the image file, since DocBook
+ Tools will automatically insert it for you. For example:
+ </p>
+<pre class="programlisting">
+
+<figure>
+ <title>My Image</title>
+ <screenshot>
+ <screeninfo>Sample GNOME Display</screeninfo>
+ <graphic format="png" fileref="myfile" srccredit="me">
+ </graphic>
+ </screenshot>
+</figure>
+ </pre>
+<p>
+ You will notice in this example that the file
+ <tt>myfile.png</tt> was referred to as simply
+ <tt>myfile</tt>. Now when you run
+ <b>db2html</b> to create an html file, it will
+ automatically look for <tt>myfile.png</tt> in
+ the directory.
+ </p>
+<p>
+ If you want to create PostScript ouput, you will need to create an
+ EPS version of your image file to be displayed in the
+ PostScript file. There is a simple script available which
+ allows you to change a PNG image into an EPS file
+ easily. You can download this file - img2eps - from <a href="http://people.redhat.com/dcm/sgml.html" target="_top">http://people.redhat.com/dcm/sgml.html</a>
+ (look for the img2eps section). Note that this script is
+ included in the gnome-doc-tools package, so if you are using
+ this package, you should already have
+ <b>img2eps</b> on you system.
+ </p>
+</div>
+<div class="sect3">
+<a name="moredocbookinfo"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="moredocbookinfo"></a>
+<span class="title">Learning DocBook</span>
+</h4></div></div>
+<p>
+ There are many resources available to help you learn DocBook.
+ The following resources on the web are useful for learning
+ DocBook:
+ </p>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2842047"></a>
+ <a href="http://www.docbook.org" target="_top">http://www.docbook.org</a> - Norman
+ Walsh's <i>DocBook: The Definitive
+ Guide</i>. Online O'Reilly book on using
+ DocBook. Contains an excellent element reference. May be
+ too formal for a beginner.
+ </p></li>
+<li><p>
+<a name="id2842102"></a>
+ <a href="http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html" target="_top">A Practical Introduction to DocBook</a>
+ - The Open Source Writers Group's introduction to using
+ DocBook. This is an excellent HOW-TO type article on
+ getting started.
+ </p></li>
+<li><p>
+<a name="id2842143"></a>
+ <a href="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html" target="_top">Getting Going with DocBook: Notes for
+ Hackers</a> - Mark Galassi's introduction to DocBook
+ for hackers. This has to be one of the first
+ introductions to DocBook ever - still as good as it ever
+ was.
+ </p></li>
+<li><p>
+<a name="id2842182"></a>
+ <a href="http://www.freebsd.org/tutorials/docproj-primer/" target="_top">
+ FreeBSD Documentation Project Primer for New
+ Contributors</a> - FreeBSD documentation project
+ primer. Chapter 4.2 provides a very good introduction to
+ writing documentation using DocBook. Note that it also
+ describes some custom extensions of DocBook;
+ fortunately, they are clearly marked as such.
+ </p></li>
+</ul></div>
+<p>
+ Norman Walsh's book is also available in print.
+ </p>
+<p>
+ The following sections of this document are designed to help
+ documentation authors write correct and consistent DocBook:
+ </p>
+<div class="itemizedlist"><ul><li><p>
+<a name="id2842249"></a>
+ <a href="#docbookbasics">the section called “DocBook Basics ”</a> - Descriptions of
+ commonly used DocBook tags.
+ </p></li></ul></div>
+<p>
+ You may also discuss specific DocBook questions with GDP
+ members on the #docs IRC channel at irc.gnome.org and on the
+ gnome-doc-list mailing list.
+ </p>
+</div>
+</div>
+<div class="sect2">
+<a name="gdptemplates"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="gdptemplates"></a>
+<span class="title">GDP Document Templates</span>
+</h3></div></div>
+<p>
+ Templates for various types of GNOME documents are found in
+ <a href="#templates">Appendix A.</a>. They are kept in CVS in
+ gnome-docu/gdp/templates. The easiest source to get them from
+ is probably the <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
+ Document Templates</a> web page, which is typically kept
+ completely up-to-date with CVS and has a basic description of
+ each file from CVS.
+ </p>
+</div>
+<div class="sect2">
+<a name="screenshots"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="screenshots"></a>
+<span class="title">Screenshots</span>
+</h3></div></div>
+<p>
+ Most GNOME documents will have screenshots of the particular
+ applet, application, GNOME component, or widget being
+ discussed. As discussed above in <a href="#gdpdtd">the section called “GDP DTD (PNG Image Support)”</a> you
+ will need to install the special GDP DocBook DTD which
+ supports PNG images, the format used for all images in GNOME
+ documentation. For the basic DocBook structure used to insert
+ images in a document, see <a href="#jadeimages">the section called “Images in DocBook Tools”</a> above.
+ </p>
+<div class="sect3">
+<a name="screenshotappearance"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="screenshotappearance"></a>
+<span class="title">Screenshot Appearance</span>
+</h4></div></div>
+<p>
+ For all screenshots of windows that typically have border
+ decorations (e.g. applications and dialogs, but not applets
+ in a panel), GDP standards dictate
+ the appearance of the window. (This is to minimize possible
+ confusion to the reader, improve the appearance of GNOME
+ documents, and guarantee the screenshot is readable when
+ printed.) All screenshots should be taken with the SawFish
+ (formerly known as Sawmill) window manager using the
+ MicroGui theme and Helvetica 12pt font. (A different window
+ manager can be used provided the MicroGui theme is available
+ for this window manager and the appearance is identical to
+ that when using the SawFish window manager.) The default
+ GTK+ theme(gtk) and font (Helvetica 12 pt) should be used
+ for all screenshots. If you are unable to provide
+ screenshots in this form, you should create screenshots as
+ you wish them to appear and send them to the
+ <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
+ <i>gnome-doc-list mailing list</i> </a>
+ requesting a GDP member reproduce these screenshots in the
+ correct format and email them to you.
+ </p>
+</div>
+<div class="sect3">
+<a name="screenshottools"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="screenshottools"></a>
+<span class="title">Screenshot Tools</span>
+</h4></div></div>
+<p>
+ There are many tools for taking screenshots in
+ GNOME/Linux. Perhaps the most convenient is the
+ Screen-Shooter Applet. Just click
+ on the window icon in the applet and then on the window you
+ would like to take a screenshot of. (Note that
+ at the time of this writing, PNG images taken by
+ screenshooter do not appear properly in
+ Netscape or the
+ GNOME Help Browser. You
+ should save your screenshot as a GIF and
+ then use <b>convert filename.gif
+ filename.png</b>.) For applets
+ in a Panel,
+ xv can be used to crop the
+ screenshot to only include the relevant portion of the
+ Panel. Note that
+ xv and
+ gimp can both be used for taking
+ screenshots, cropping screenshots, and converting image
+ formats.
+ </p>
+</div>
+<div class="sect3">
+<a name="screenshotfiles"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="screenshotfiles"></a>
+<span class="title">Screenshot Files</span>
+</h4></div></div>
+<p>
+ Screenshots should be kept in the main documentation
+ directory with your SGML file for applets, or should be
+ kept in a directory called "figs" for application and other
+ documentation. After you use <b>db2html</b> to
+ convert your SGML file to HTML (see <a href="#make-output">the section called “Creating Something Useful with your Docs”</a>), you will need to copy your
+ screenshots (either the individual PNG files for applet
+ documentation, or the whole "figs" directory for other
+ documentation) into the newly created HTML directory. Note
+ that every time you use <b>db2html</b> the HTML
+ directory is erased and rewritten, so do not store your only
+ copy of the screenshots in that directory. If you wish to
+ create PostScript or PDF output, you will need to manually
+ convert the PNG images to EPS as described in <a href="#jadeimages">the section called “Images in DocBook Tools”</a>, but will not need to copy these
+ images from their default location, as they are included
+ directly into the output(PostScript of PDF) file.
+ </p>
+</div>
+</div>
+<div class="sect2">
+<a name="applicationbugs"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="applicationbugs"></a>
+<span class="title">Application Bugs</span>
+</h3></div></div>
+<p>
+ Documentation authors tend to investigate and test applets and
+ applications more thoroughly than most
+ users. Often documentation authors will discover one or
+ more bugs in the software. These bugs vary from small ones,
+ such as mis-spelled words or missing
+ About dialogs in the menu, to large
+ ones which cause the applet to crash. As all users, you
+ should be sure to report these bugs so that application
+ developers know of them and can fix them. The easiest way to
+ submit a bug report is by using the Bug
+ Buddy applet which is part of the gnome-applets
+ package.
+ </p>
+</div>
+<div class="sect2">
+<a name="cvs"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="cvs"></a>
+<span class="title">Using CVS</span>
+</h3></div></div>
+<p>
+ CVS (Concurrent Versions System) is a tool that allows
+ multiple developers to concurrently work on a set of
+ documents, keeping track of the modifications made by each
+ person. The files are stored on a server and each developer
+ checks files out, modifies them, and then checks in their
+ modified version of the files. Many GNOME programs and
+ documents are stored in CVS. The GNOME CVS server allows
+ users to anonymously check out CVS files. Most GDP members
+ will need to use anonymous CVS to download the most up-to-date
+ version of documentation or programs. Modified documents will
+ typically be emailed to the the application developer. Core
+ GDP members may also be granted login CVS privileges so they
+ may commit modified files directly to CVS.
+ </p>
+<div class="sect3">
+<a name="anonymouscvs"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="anonymouscvs"></a>
+<span class="title">Anonymous CVS</span>
+</h4></div></div>
+<p>
+ To anonymously check out documents from CVS, you must first
+ log in. From the bash shell, you should set your CVSROOT
+ shell variable with <b> export
+ CVSROOT=':pserver:anonymous@anoncvs.gnome.org:/cvs/gnome'</b>
+ and then login with <b>cvs login</b>(there is no
+ password, just hit return). As an example, we will use the
+ "gnome-docu/gdp" module which contains this and several
+ other documents. To check these documents out for the first
+ time, type <b>cvs -z3 checkout
+ gnome-docu/gdp</b>. After you have this document
+ checked out and you would like to download any updates on
+ the CVS server, use <b>cvs -z3 update -Pd</b>.
+ </p>
+</div>
+<div class="sect3">
+<a name="logincvs"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="logincvs"></a>
+<span class="title">Login CVS</span>
+</h4></div></div>
+<p> If you have been given a
+ login for the GNOME CVS server, you may commit your file
+ modifications to CVS. Be sure to read the following section
+ on CVS etiquette before making any commits to CVS. To log in
+ to the CVS server as user
+ <b><i><tt>username</tt></i></b> with a
+ password, you must first set your CVSROOT shell variable with
+ <b> export
+ CVSROOT=':pserver:<i><tt>username</tt></i>@cvs.gnome.org:/cvs/gnome'</b>.
+ Log in with <b>cvs login</b> and enter your
+ password. You may check out and update modules as described
+ above for anonymous CVS access. As a login CVS user, you may
+ also check modified versions of a file into the CVS server.
+ To check
+ <b><i><tt>filename</tt></i></b> into
+ the CVS server, type <b>cvs -z3 commit
+ <i><tt>filename</tt></i>
+</b>. You will be
+ given a vi editor window to type in a brief log entry,
+ summarizing your changes. The default editor can be changed
+ using the <tt>EDITOR</tt> environment variable or
+ with the <b><tt>-e</tt></b> option. You
+ may also check in any modifications to files in the working
+ directory and subdirectories using <b>cvs -z3
+ commit</b>. To
+ add a new file to the CVS server, use <b>cvs -z3 add
+ <i><tt>filename</tt></i>
+</b>, followed by the
+ commit command.
+ </p>
+</div>
+<div class="sect3">
+<a name="cvsetiquette"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="cvsetiquette"></a>
+<span class="title">CVS Etiquette</span>
+</h4></div></div>
+<p>
+ Because files in CVS are typically used and modified by
+ multiple developers and documentation authors, users should
+ exercise a few simple practices out of courtesy towards the
+ other CVS users and the project leader. First, you should
+ not make CVS commits to a package without first discussing
+ your plans with the project leader. This way, the project
+ leader knows who is modifying the files and generally, what
+ sort of changes/development is being done. Also, whenever a
+ CVS user commits a file to CVS, they should make an entry in
+ the CVS log and in the <tt>ChangeLog</tt> so
+ that other users know who is making modifications and what
+ is being modified. When modifying files created by others,
+ you should follow the indentation scheme used by the initial
+ author.
+ </p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<a name="gnomedocsystem"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="gnomedocsystem"></a>
+<span class="title">The GNOME Documentation System</span>
+</h2></div></div>
+<div class="sect2">
+<a name="gnomehelpbrowser"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="gnomehelpbrowser"></a>
+<span class="title">The GNOME Help Browser</span>
+</h3></div></div>
+<p>
+ At the core of the GNOME help system is the GNOME
+ Help Browser. The Help
+ Browser provides a unified interface to several
+ distinct documentation systems on Linux/Unix systems: man
+ pages, texinfo pages, Linux Documentation Project(LDP)
+ documents, GNOME application documentation, and other GNOME
+ documents.
+ </p>
+<p>
+ The GNOME Help Browser works by
+ searching standard directories for documents which are to be
+ presented. Thus, the documentation that appears in the GHB is
+ specific to each computer and will typically only represent
+ software that is installed on the computer.
+ </p>
+</div>
+<div class="sect2">
+<a name="gnomehelpbrowser2"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="gnomehelpbrowser2"></a>
+<span class="title">The GNOME Help Browser (GNOME-2.0)</span>
+</h3></div></div>
+<p> In
+ GNOME 2.0, the GNOME Help Browser
+ will be replaced by Nautilus.
+ Nautilus will be the file manager/graphical shell for GNOME 2.0
+ and will also implement a more sophisticated help system than
+ that used by the GNOME Help Browser
+ used in GNOME 1.0. It will read and display DocBook files
+ directly, avoiding the need for duplicating documents in both
+ DocBook and HTML formats. Its display engine for DocBook will
+ be much faster than running jade to
+ convert to HTML for rendering. Because it uses the original
+ DocBook source for documentation, it will be possible to do more
+ sophisticated searching using the meta information included in
+ the documents. And since Nautilus is a virtual file system
+ layer which is Internet-capable, it will be able to find and
+ display documents which are on the web as well as those on the
+ local file system. For more information on
+ Nautilus, visit the #nautilus IRC
+ channel on irc.gnome.org. </p>
+</div>
+<div class="sect2">
+<a name="gnomehelponthefly"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="gnomehelponthefly"></a>
+<span class="title">Dynamic Document Synthesis(GNOME-2.0)</span>
+</h3></div></div>
+<p>
+ GNOME uses the documentation presented by all the various
+ GNOME components and applications installed on the system to
+ present a complete and customized documentation environment
+ describing only components which are currently installed on a
+ users system. Some of this documentation, such as the manuals
+ for applets, will be combined in such a way that it appears to
+ be a single document.
+ </p>
+<p>
+ By using such a system, you can be sure that any GNOME app you
+ install that has documentation will show up in the index,
+ table of contents, any search you do in the help browser.
+ </p>
+</div>
+<div class="sect2">
+<a name="gnomehelpcomponents"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="gnomehelpcomponents"></a>
+<span class="title">The GNOME Documentation Components</span>
+</h3></div></div>
+<div class="sect3">
+<a name="applicationmanualsintro"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="applicationmanualsintro"></a>
+<span class="title">Application Manuals</span>
+</h4></div></div>
+<p>
+ Every GNOME application should have an application manual.
+ An application manual is a document specific to the
+ particular application which explains the various windows
+ and features of the application. Application Manuals
+ typically use screenshots (PNG format) for clarity. Writing
+ application manuals is discussed in more detail in <a href="#writingapplicationmanuals">the section called “Writing Application and Applet Manuals”</a> below.
+ </p>
+</div>
+<div class="sect3">
+<a name="applicationhelpintro"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="applicationhelpintro"></a>
+<span class="title">Application Help</span>
+</h4></div></div>
+<p>
+ Applications should have a Help
+ button on screens on which users may need help. These
+ Help buttons should pull up the
+ default help browser, determined by the
+ <tt>ghelp</tt> URL Handler (configured using the
+ Control Center), typically the
+ GNOME Help Browser. The help
+ browser should show either the first page of the application
+ manual, or else the relevant page thereof. Application help
+ is described in more detail in <a href="#applicationhelpbuttons">the section called “Application Help Buttons”</a> below.
+ </p>
+</div>
+<div class="sect3">
+<a name="contextsensitivehelpintro"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="contextsensitivehelpintro"></a>
+<span class="title">Application Context Sensitive Help (coming in
+ GNOME-2.0)</span>
+</h4></div></div>
+<p>
+ Context sensitive help is a system which will allow the user
+ to query any part (button, widget, etc.) of an application
+ window. This is done by either entering a CS Help mode by
+ clicking on an icon or by right clicking on the application
+ part and selecting "What's This" or whatever is decided on
+ at the time. Context sensitive help is described in more
+ detail in <a href="#writingcontextsensitivehelp">the section called “Writing Context Sensitive Help (coming in GNOME-2.0)”</a>
+ below.
+ </p>
+</div>
+<div class="sect3">
+<a name="userguide"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="userguide"></a>
+<span class="title">The GNOME User Guide</span>
+</h4></div></div>
+<p>
+ The <i>GNOME User Guide</i> describes the
+ GNOME desktop environment and core components of GNOME such
+ as the panel and
+ control center. In GNOME 1.x this
+ was the main and only source of documentation. In GNOME 2.0
+ this will become a document for the web and for printing
+ that is derived from various parts chosen in the system that
+ are necessary for the new user to understand.
+ </p>
+</div>
+<div class="sect3">
+<a name="userdocs"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="userdocs"></a>
+<span class="title">User Documents</span>
+</h4></div></div>
+<p>
+ Aside from the <i>GNOME User Guide</i>,
+ there are several other documents to help GNOME users learn
+ GNOME, including the <i>GNOME FAQ</i>,
+ <i>GNOME Installation and Configuration
+ Guide</i>, and the <i>GNOME Administrators
+ Guide</i>.
+ </p>
+</div>
+<div class="sect3">
+<a name="developerdocs"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="developerdocs"></a>
+<span class="title">Developer Documents</span>
+</h4></div></div>
+<p>
+ There are many White Papers, Tutorials, HOWTO's and FAQ's to
+ make programming GNOME and GNOME applications as easy as
+ possible.
+ </p>
+<p>
+ API documentation is also available for the GNOME libraries. This is
+ detailed documentation of the code that is used to build GNOME
+ apps. You can keep up with the GNOME API docs on the <a href="http://developer.gnome.org/doc/API/" target="_top">GNOME API
+ Reference</a> page.
+ </p>
+</div>
+<div class="sect3">
+<a name="projectdocs"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="projectdocs"></a>
+<span class="title">Project Documents</span>
+</h4></div></div>
+<p>
+ Some GNOME projects have documentation to maintain
+ consistency in their product and to help new contributors
+ get up to speed quickly. Among these are the GDP documents,
+ such as the one you are reading now.
+ </p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<a name="docbookbasics"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="docbookbasics"></a>
+<span class="title">DocBook Basics </span>
+</h2></div></div>
+<div class="sect2">
+<a name="introtodocbook"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="introtodocbook"></a>
+<span class="title">Introduction to DocBook</span>
+</h3></div></div>
+<p>
+ To understand DocBook, a basic understanding of SGML is
+ helpful. SGML stands for Standard General Markup Language and
+ is one of the first markup languages every created. HTML is
+ actually derived from SGML and XML is a subset of SGML. SGML
+ uses what is called a Document Type Definition to specify
+ <i>elements</i> which are contained between
+ brackets, < and >. Text is marked by both beginning and
+ ending elements, for example in the DocBook DTD, one denotes a
+ title with <tt><title></tt>The
+ Title<tt></title></tt>.
+ </p>
+<p>
+ The DTD (in the case of the GDP, DocBook) defines rules for how the
+ elements can be used. For example, if one element can only be used when
+ embedded within another, this is defined in the DTD.
+ </p>
+<p>
+ An SGML file is just a plain ASCII file containing the text
+ with the markup specified above. To convert it to some easily
+ readable format, you need special tools. The GDP uses <i>DocBook
+ Tools</i>, a free package of utilities for working with DocBook
+ which includes <i>Jade</i>, which does the SGML/DSSL
+ parsing. You can read more about DocBook Tools in <a href="#installingdocbook">the section called “Installing DocBook”</a>.
+ </p>
+<p>
+ The final appearance of the output (e.g. PostScript or HTML)
+ is determined by a
+ <i>stylesheet</i>. Stylesheets are files,
+ written in a special language (DSSSL -- Document Style
+ Semantics and Specification Language), which specify the
+ appearance of various DocBook elements, for example,
+ what fonts to use for titles and various inline elements, page
+ numbering style, and much more. DocBook tools come with a
+ collection of stylesheets (Norman Walsh's modular
+ stylesheets); GNOME Document Project uses some customized
+ version of this stylesheets -- see <a href="#gdpstylesheets">the section called “GDP Stylesheets”</a>.
+ </p>
+<p>
+ The advantage of specifying the <i>structure</i>
+ of a document with SGML instead of specifying the
+ <i>appearance</i> of the document with a typical
+ word processor, or with html, is that the resulting document
+ can be processed in a variety of ways using the structural
+ information. Whereas formatting a document for appearance
+ assumes a medium (typically written text on a standard-sized
+ piece of paper), SGML can be processed to produce output for a
+ large variety of media such as text, postscript, HTML,
+ Braille, audio, and potentially many other formats.
+ </p>
+<p>
+ Using 'content' as the elements to define the text of a document also
+ allows for search engines to make use of the actual elements to make a
+ "smarter search". For example, if you are searching for all documents
+ written by the author "Susie" your search engine could be made smart
+ enough to only search <author> elements, making for a faster and more
+ accurate search.
+ </p>
+<p>
+ Since the overall appearance of the output is determined not by the DTD
+ or the SGML document, but rather by a stylesheet, the appearance of a
+ document can be easily changed just by changing the stylesheet. This
+ allows everyone in the project to create documents that all look the
+ same.
+ </p>
+<p>
+ As stated before, the GDP uses the DocBook DTD. For a list of
+ introductory and reference resources on DocBook, see <a href="#resources">the section called “Resources”</a>. The following sections also provide
+ convenient instructions on which markup tags to use in various
+ circumstances. Be sure to read <a href="#conventions">the section called “GDP Documentation Conventions ”</a>
+ for GDP documentation-specific guidelines.
+ </p>
+</div>
+<div class="sect2">
+<a name="xml"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="xml"></a>
+<span class="title">XML and SGML</span>
+</h3></div></div>
+<p> In not so distant future (probably before GNOME 2.0),
+ DocBook itself and GNOME Documentation project will migrate from
+ SGML to XML. This transition should be relatively painless:
+ (almost) all DocBook tags will remain the same. However, XML has
+ stricter syntax rules than SGML; thus, some constructions which
+ are valid in SGML will not be valid in XML. Therefore, to be
+ ready for this transistion, it is <i>strongly
+ advised</i> that the documentation writers conform to XML
+ syntax rules. Here are most important differences:
+ </p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2844541"></a>
+<span class="term"> <i>Minimization</i>
+</span>
+</dt>
+<dd><p>
+<a name="id2844559"></a>
+ It is possible with some implementations of SGML to use
+ minimizations to close elements in a document by using
+ </>, for example:
+ <tt>
+<tt><title></tt>The
+ Title<tt></></tt>
+</tt>. This is not
+ allowed in XML. You can use <b>sgmlnorm</b> command,
+ included in DocBook Tools package, to expand minimized tags;
+ if you are using Emacs with psgml
+ mode, you can also use menu command
+ Modify->Normalize.
+ </p></dd>
+<dt>
+<a name="id2844642"></a>
+<span class="term"> <i>Self-closing tags</i>
+</span>
+</dt>
+<dd><p>
+<a name="id2844662"></a>
+ Also, in SGML some tags are allowed not to have closing
+ tags. For example, it is legal for
+ <tt><xref></tt> not to have a closing tag:
+ <tt><tt><xref
+ linkend="someid"></tt></tt>. In
+ XML, it is illegal; instead, you should use
+ <tt><tt><xref
+ linkend="someid"/></tt></tt> (note the
+ slash!).
+ </p></dd>
+<dt>
+<a name="id2844715"></a>
+<span class="term"> <i>Case sensitive tags</i>
+</span>
+</dt>
+<dd><p>
+<a name="id2844734"></a>
+ In XML, unlike SGML, tags are case-senstive
+ <tt><title></tt> and
+ <tt><TITLE></tt> are different tags!
+ Therefore, please always use lowercase tags (except for
+ things like <tt>DOCTYPE, CDATA</tt> and
+ <tt>ENTITY</tt>, which are not DocBook tags).
+ </p></dd>
+</dl></div>
+</div>
+<div class="sect2">
+<a name="structure"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="structure"></a>
+<span class="title"> Structure Elements</span>
+</h3></div></div>
+<div class="sect3">
+<a name="section"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="section"></a>
+<span class="title">Sections and paragraphs</span>
+</h4></div></div>
+<p>
+ Top-level element of a book body must be
+ <tt><chapter></tt>; it may contain one or more
+ <tt><sect1></tt>, each of them may contain
+ <tt><sect2></tt> and so on up to
+ <tt><sect5></tt>. The top-level element of an
+ article body is always
+ <tt><sect1></tt>. Regardless of which elements
+ you use, give each structural element a unique id, so that
+ you can link to it. For usage example, see the template.
+ </p>
+<p> Please try to avoid using deeply nested sections; for
+ most situations, <tt><sect1></tt> and
+ <tt><sect2></tt> should be sufficient. If not,
+ you probably should split your <tt><sect1></tt>
+ into several smaller ones.
+ </p>
+<p> Use the tag <tt><para></tt> for
+ paragraphs, even if there is only one paragraph in a
+ section--see template for examples.
+ </p>
+</div>
+<div class="sect3">
+<a name="notes"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="notes"></a>
+<span class="title">Notes, Warnings, And Tips</span>
+</h4></div></div>
+<p>
+ For notes, tips, warnings, and important information, which
+ should be set apart from the main text (usually as a
+ paragraph with some warning sign on the margin), use tags
+ <tt><note></tt>, <tt><tip></tt>,
+ <tt><warning></tt>,
+ <tt><important></tt> respectively. For example:
+ <pre class="programlisting">
+
+<tip>
+ <title>TIP</title>
+ <para>
+ To speed up program compilation, use <application>gcc</application>
+ compiler with Pentium optimization.
+ </para>
+</tip> </pre> produces
+ </p>
+<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="extip">TIP</a></h3>
+<p>
+ To speed up program compilation, use
+ gcc compiler with Pentium
+ optimization. </p>
+</div>
+<p>
+ Note that this should not be inside a
+ <tt><para></tt> but between paragraphs.
+ </p>
+</div>
+<div class="sect3">
+<a name="figures"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="figures"></a>
+<span class="title"> Screenshots and other figures</span>
+</h4></div></div>
+<p>
+ To include screenshots and other figures, use the following
+ tags:
+
+ <pre class="programlisting">
+
+<figure id="shot1">
+ <title>Screenshot</title>
+ <screenshot>
+ <screeninfo>Screenshot of a program</screeninfo>
+ <graphic format="PNG" fileref="figures/example_screenshot" srccredit="ME">
+ </graphic>
+ </screenshot>
+</figure>
+ </pre>
+ replacing <tt>example_screenshot</tt> with the
+ actual file name (without extension). The result will look like this:
+
+ <div class="figure">
+<p>
+<a name="shot1"></a>
+<b>Figure 1. Screenshot</b>
+</p>
+<div class="screenshot"><p><img src="figures/example_screenshot"></p></div>
+</div>
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2845206">NOTE</a></h3>
+<p>
+ Notice in this example that the screenshot file name does
+ not include the file type extension -- to find out
+ why, please read <a href="#jadeimages">the section called “Images in DocBook Tools”</a>.
+ </p>
+</div>
+</div>
+<div class="sect3">
+<a name="listing"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="listing"></a>
+<span class="title">Program listings and terminal session</span>
+</h4></div></div>
+<p>
+ To show a file fragment--for example, program
+ listing--use <tt><programlisting></tt> tag:
+ <pre class="programlisting">
+
+<programlisting>
+[Desktop Entry]
+Name=Gnumeric spreadsheet
+Exec=gnumeric
+Icon=gnome-gnumeric.png
+Terminal=0
+Type=Application
+</programlisting>
+ </pre>
+ which produces
+ <pre class="programlisting">
+[Desktop Entry]
+Name=Gnumeric spreadsheet
+Exec=gnumeric
+Icon=gnome-gnumeric.png
+Terminal=0
+Type=Application
+ </pre>
+ As a matter of fact, all examples in this document were
+ produced using <tt><programlisting></tt>.
+ </p>
+<p>
+ To show a record of terminal session--i.e., sequence of
+ commands entered at the command line--use
+ <tt><screen></tt> tag:
+ <pre class="programlisting">
+
+<screen>
+<prompt>bash$</prompt><userinput>make love</userinput>
+make: *** No rule to make target `love'. Stop.
+</screen>
+ </pre>
+ which produces
+ <pre class="screen">
+<tt>bash$</tt>
+<b><tt>make love</tt></b>
+make: *** No rule to make target `love'. Stop.
+ </pre>
+ Note the use of tags <tt><prompt></tt> and
+ <tt><userinput></tt> for marking system prompt
+ and commands entered by user.
+ <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2845418">NOTE</a></h3>
+<p>
+ Note that both <tt><programlisting></tt>
+ and <tt><screen></tt> preserve linebreaks,
+ but interpret SGML tags (unlike LaTeX
+ verbatim environment). Take a look at
+ the source of this document to see how you can have SGML
+ tags literally shown but not interpreted,
+ </p>
+</div>
+ </p>
+</div>
+<div class="sect3">
+<a name="lists"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="lists"></a>
+<span class="title"> Lists</span>
+</h4></div></div>
+<p>
+ The most common list types in DocBook are
+ <tt><itemizedlist></tt>,
+ <tt><orderedlist></tt>, and
+ <tt><variablelist></tt>.
+ </p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2845537"></a>
+<span class="term"> <tt><itemizedlist></tt>
+</span>
+</dt>
+<dd>
+<p>
+<a name="id2845557"></a>
+ This is the simplest unnumbered list, parallel to
+ <tt><ul></tt> in HTML. Here is an example:
+ <pre class="programlisting">
+
+<itemizedlist>
+ <listitem>
+ <para>
+ <guilabel>Show backup files</guilabel> &mdash; This will
+ show any backup file that might be on your system.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Show hidden files</guilabel> &mdash; This will
+ show all "dot files" or files that begin with a dot. This
+ files typically include configuration files and directories.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guilabel>Mix files and directories</guilabel> &mdash; This
+ option will display files and directories in the order you
+ sort them instead of
+ always having directories shown above files.
+ </para>
+ </listitem>
+</itemizedlist>
+
+ </pre>
+ and output:
+ </p>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2845575"></a>
+ Show backup files --
+ This will show any backup file that might be on
+ your system.
+ </p></li>
+<li><p>
+<a name="id2845637"></a>
+ Show hidden files --
+ This will show all "dot files" or files that
+ begin with a dot. This files typically include
+ configuration files and directories.
+ </p></li>
+<li><p>
+<a name="id2845664"></a>
+ Mix files and directories
+ -- This option will display files and
+ directories in the order you sort them instead
+ of always having directories shown above files.
+ </p></li>
+</ul></div>
+<p> Note the use of <tt>&mdash;</tt>
+ for long dash (see <a href="#specsymb">the section called “ Special symbols ”</a>). Also,
+ please note that the result looks much nicer because the
+ terms being explained (Show backup
+ files, etc.) are set in a different font. In
+ this case, it was achieved by using <a href="#gui"><tt><guilabel></tt></a>
+ tag. In other cases, use appropriate tags such as
+ <a href="#gui"><tt><guimenuitem></tt></a>,
+ <a href="#filenames"><tt><command></tt></a>,
+ or -- if none of
+ this applies -- use
+ <a href="#gui"><tt><emphasis></tt></a>.
+ </p>
+</dd>
+<dt>
+<a name="id2845831"></a>
+<span class="term"> <tt><orderedlist></tt>
+</span>
+</dt>
+<dd><p>
+<a name="id2845848"></a>
+ This list is completely analogous to
+ <tt><itemizedlist></tt> and has the same
+ syntax, but it produces numbered list. By default,
+ this list uses Arabic numerals for numbering entries;
+ you can override this using <tt>numeration</tt>,
+ for example <tt><orderedlist
+ numeration="lowerroman"></tt>. Possible values of
+ these attribute are <tt>arabic</tt>,
+ <tt>upperalpha</tt>,
+ <tt>loweralpha</tt>,
+ <tt>upperroman</tt>,
+ <tt>lowerroman</tt>.
+ </p></dd>
+<dt>
+<a name="id2845929"></a>
+<span class="term"> <tt><variablelist></tt>
+</span>
+</dt>
+<dd><p>
+<a name="id2845949"></a> This list is used when each entry is
+ rather long, so it should be formatted as a block of text
+ with some subtitle, like a small subsection. The
+ <tt><variablelist></tt> is more complicated
+ than itemizedlists, but for larger blocks of text, or when
+ you're explaining or defining something, it's best to use
+ them. Their greatest advantage is that it's easier for a
+ computer to search. The lines you are reading now were
+ produced by <tt><variablelist></tt>. The
+ source looked liked this:
+ <pre class="programlisting">
+
+<variablelist>
+ <varlistentry>
+ <term> <sgmltag>&lt;itemizedlist></sgmltag></term>
+ <listitem><para>
+ This is the simplest unnumbered list, parallel to
+ <sgmltag>&lt;ul></sgmltag> in HTML. Here is an example:...
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <sgmltag>&lt;orderedlist></sgmltag></term>
+ <listitem><para>
+ This list is completely analogous to
+ <sgmltag>&lt;itemizedlist></sgmltag>
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <sgmltag>&lt;variablelist></sgmltag></term>
+ <listitem><para>
+ This list is used when each entry is rather long,...
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+
+ </pre>
+ </p></dd>
+</dl></div>
+<p>
+ Lists can be nested; in this case, the stylesheets
+ are smart enough to change the numeration (for
+ <tt><orderedlist></tt>) or marks of each entry
+ (in <tt><itemizedlist></tt>) for sub-lists
+ </p>
+</div>
+</div>
+<div class="sect2">
+<a name="inline"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="inline"></a>
+<span class="title">Inline Elements</span>
+</h3></div></div>
+<div class="sect3">
+<a name="gui"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="gui"></a>
+<span class="title">GUI elements</span>
+</h4></div></div>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2846106"></a>
+ <tt><guibutton></tt> -- used for
+ buttons, including checkbuttons and radio buttons
+ </p></li>
+<li><p>
+<a name="id2846132"></a>
+ <tt><guimenu></tt>,
+ <tt><guisubmenu></tt> --used for
+ top-level menus and submenus
+ respectively, for example <tt>
+ <guisubmenu>Utilities</guisubmenu> submenu of the
+ <guimenu>Main Menu</guimenu></tt>
+ </p></li>
+<li><p>
+<a name="id2846176"></a>
+ <tt><guimenuitem></tt>--an entry in a
+ menu
+ </p></li>
+<li><p>
+<a name="id2846202"></a>
+ <tt><guiicon></tt>--an icon
+ </p></li>
+<li><p>
+<a name="id2846226"></a>
+ <tt><guilabel></tt>--for items which have
+ labels, like tabs, or bounding boxes.
+ </p></li>
+<li><p>
+<a name="id2846251"></a>
+ <tt><interface></tt>-- for most everything
+ else... a window, a dialog box, the Panel, etc.
+ </p></li>
+</ul></div>
+<p>
+ If you need to refer to a sequence of menu choices, such as
+ Main Menu->Utilities->GNOME
+ terminal
+ there is a special construction for this, too:
+ <pre class="programlisting">
+
+<menuchoice>
+ <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
+ <guimenuitem>GNOME terminal</guimenuitem> </menuchoice>
+ </pre>
+ </p>
+</div>
+<div class="sect3">
+<a name="links"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="links"></a>
+<span class="title">Links and references</span>
+</h4></div></div>
+<p>
+ To refer to another place in the same document, you can use
+ tags <tt><xref></tt> and
+ <tt><link></tt>. The first of them
+ automatically inserts the full name of the element you refer
+ to (section, figure, etc.), while the second just creates a
+ link (in HTML output). Here is an example:
+ <pre class="programlisting">
+An example of a <link linkend="extip">tip</link> was given in
+<xref linkend="notes" />.
+ </pre>
+ which produces: An example of a <a href="#extip">tip</a> was given in <a href="#notes">the section called “Notes, Warnings, And Tips”</a>.
+ </p>
+<p>
+ Here <tt>notes</tt> and <tt>extip</tt>
+ are the id attributes of <a href="#notes">the section called “Notes, Warnings, And Tips”</a> and of the
+ example of a tip in it.
+ </p>
+<p> To produce a link to an external source, such as a
+ Web page or a local file, use <tt><ulink></tt>
+ tag, for example:
+ <pre class="programlisting">
+ To find more about GNOME, please visit <ulink type="http"
+url="http://www.gnome.org">GNOME Web page</ulink>
+ </pre>
+ which produces: To find more about GNOME, please visit
+ <a href="http://www.gnome.org" target="_top">The GNOME Web
+ Site</a> You can use any of the standard URL types, such
+ as <tt>http, ftp, file, telnet, mailto</tt> (in
+ most cases, however, use of <tt>mailto</tt> is
+ unnecessary--see discussion of
+ <tt><email></tt> tag).
+ </p>
+</div>
+<div class="sect3">
+<a name="filenames"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="filenames"></a>
+<span class="title">Filenames, commands, and other
+ computer-related things</span>
+</h4></div></div>
+<p>
+ Here are some tags used to describe operating system-related
+ things:
+ </p>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2846608"></a> <tt><filename></tt> -- used
+ for filenames,
+ e.g.<tt><filename></tt>
+ foo.sgml
+ <tt></filename></tt>
+ produces: <tt>foo.sgml</tt>.
+ </p></li>
+<li><p>
+<a name="id2846657"></a> <tt><filename
+ class="directory"></tt> -- used for
+ directories, e.g.<tt><filename
+ class="directory"></tt>/usr/bin
+ <tt></filename></tt>
+ produces: <tt>/usr/bin</tt>.
+ </p></li>
+<li><p>
+<a name="id2846714"></a>
+ <tt><application></tt> -- used for
+ application names,
+ e.g. <tt><application></tt>Gnumeric
+ <tt></application></tt> produces:
+ Gnumeric.
+ </p></li>
+<li><p>
+<a name="id2846764"></a>
+ <tt><envar></tt> -- used for
+ environment variables, e.g.
+ <tt><envar></tt>PATH<tt></envar></tt>.
+ </p></li>
+<li><p>
+<a name="id2846804"></a>
+ <tt><command></tt> -- used for
+ commands entered on command line, e.g.
+ <tt><command></tt>make install
+ <tt></command></tt> produces:
+ <b>make install</b>.
+ </p></li>
+<li><p>
+<a name="id2846854"></a>
+ <tt><replaceable></tt> -- used for
+ replaceable text, e.g.
+ <tt><command></tt>db2html<tt><replaceable></tt>
+ foo.sgml
+ <tt></replaceable></tt>
+<tt></command></tt>
+ produces: <b>db2html
+ <i><tt>foo.sgml</tt></i>
+</b>.
+ </p></li>
+</ul></div>
+</div>
+<div class="sect3">
+<a name="keys"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="keys"></a>
+<span class="title">Keyboard input</span>
+</h4></div></div>
+<p> To mark up text input by the user, use
+ <tt><userinput></tt>.
+ </p>
+<p> To mark keystrokes such as shortcuts and other
+ commands, use <tt><keycap></tt>.
+ This is used for marking up what is printed on the top
+ of the physical key on the keyboard. There are a couple of
+ other tags for keys, too: <tt><keysym></tt>
+ and <tt><keycode></tt>. However you are
+ unlikely to need these for most documentation. For reference,
+ <tt><keysym></tt> is for the `symbolic
+ name' of a key. <tt><keycode></tt> is
+ for the `scan code' of a key. These are not
+ terms commonly required in GNOME documentation,
+ although <tt><keysym></tt> is useful for marking
+ up control codes.
+ </p>
+<p>
+ To mark up a combination of keystrokes, use the
+ <tt><keycombo></tt> wrapper:
+ <pre class="programlisting">
+
+<keycombo>
+ <keycap>Ctrl</keycap>
+ <keycap>Alt</keycap>
+ <keycap>F1</keycap>
+</keycombo>
+ </pre>
+ </p>
+<p>
+ Finally, if you want to show a shortcut for some menu
+ command, here are the appropriate tags (rather long):
+ <pre class="programlisting">
+
+<menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
+ </shortcut>
+ <guimenuitem> Quit</guimenuitem>
+</menuchoice>
+ </pre>
+ which produces simply
+ Quit (<b>Ctrl-q</b>)
+ </p>
+</div>
+<div class="sect3">
+<a name="email"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="email"></a>
+<span class="title">E-mail addresses</span>
+</h4></div></div>
+<p> To mark up e-mail
+ address, use <tt><email></tt>:
+ <pre class="programlisting">
+ The easiest way to get in touch with me is by e-mail
+(<email>me@mydomain.com</email>)
+ </pre>
+ which produces: The easiest way to get in touch with me is
+ by e-mail (<tt><<a href="mailto:me@mydomain.com">me@mydomain.com</a>></tt>) Note that
+ <tt><email></tt> automatically produces a link
+ in html version.
+ </p>
+</div>
+<div class="sect3">
+<a name="specsymb"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="specsymb"></a>
+<span class="title"> Special symbols </span>
+</h4></div></div>
+<p>
+ DocBook also provides special means for entering
+ typographic symbols which can not be entered directly
+ form the keyboard (such as copyright sign). This is done using
+ <i>entities</i>, which is SGML analogue of
+ macros, or commands, of LaTeX. They generally have the form
+ <tt>&entityname;</tt>. Note that the semicolon
+ is required.
+ </p>
+<p>
+ here is partial list of most commonly used enitites:
+ </p>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2847294"></a>
+ <tt>&amp;</tt> -- ampersend (&)
+ </p></li>
+<li><p>
+<a name="id2847313"></a>
+ <tt>&lt;</tt> -- left angle bracket (<)
+ </p></li>
+<li><p>
+<a name="id2847332"></a>
+ <tt>&copy;</tt> -- copyright sign (©)
+ </p></li>
+<li><p>
+<a name="id2847351"></a>
+ <tt>&mdash;</tt> -- long dash (--)
+ </p></li>
+<li><p>
+<a name="id2847370"></a>
+ <tt>&hellip;</tt> -- ellipsis (...)
+ </p></li>
+</ul></div>
+<p>
+ Note that the actual look of the resulting symbols depends
+ on the fonts used by your browser; for example, it might
+ happen that long dash (<tt>&mdash;</tt>) looks
+ exactly like the usual dash (-). However, in the PostScript
+ (and thus, in print) the output will look markedly better if
+ you use appropriate tags.
+ </p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<a name="conventions"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="conventions"></a>
+<span class="title">GDP Documentation Conventions </span>
+</h2></div></div>
+<div class="sect2">
+<a name="conventionsalldocs"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="conventionsalldocs"></a>
+<span class="title">Conventions for All GDP Documentation</span>
+</h3></div></div>
+<div class="sect3">
+<a name="xmlcomp"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="xmlcomp"></a>
+<span class="title"> XML compatibility </span>
+</h4></div></div>
+<p>
+ All GNOME documentation should conform to XML syntax
+ requirements, which are stricter than SGML ones -- see
+ <a href="#xml">the section called “XML and SGML”</a> for more informaion.
+ </p>
+</div>
+<div class="sect3">
+<a name="authorsnames"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="authorsnames"></a>
+<span class="title"> Authors' names</span>
+</h4></div></div>
+<p>
+ All GNOME documentation should contain the names of both the
+ application authors and documentation authors, as well as a
+ link to the application web page (if it exists) and
+ information for bug submission -- see templates for an
+ example.
+ </p>
+</div>
+</div>
+<div class="sect2">
+<a name="conventionsappdocs"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="conventionsappdocs"></a>
+<span class="title">Conventions for Application Documentation</span>
+</h3></div></div>
+<div class="sect3">
+<a name="applicationversionid"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="applicationversionid"></a>
+<span class="title">Application Version Identification</span>
+</h4></div></div>
+<p>
+ Application documentation should identify the version of the
+ application for which the documentation is written:
+ <pre class="programlisting">
+
+<sect1 id="intro">
+ <title>Introduction</title>
+ <para>
+ blah-blah-blah This document describes version 1.0.53 of gfoo.
+ </para>
+</sect1>
+ </pre>
+ </p>
+</div>
+<div class="sect3">
+<a name="license"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="license"></a>
+<span class="title"> Copyright information </span>
+</h4></div></div>
+<p> Application
+ documentation should contain a copyright notice, stating the
+ licensing terms. It is suggested that you use the GNU Free
+ Documentation License. You could also use some other license
+ allowing free redistribution, such as GPL or Open Content
+ license. If documentation uses some trademarks (such as UNIX,
+ Linux, Windows, etc.), proper legal junk should also be
+ included (see templates).
+ </p>
+</div>
+<div class="sect3">
+<a name="license2"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="license2"></a>
+<span class="title">Software license</span>
+</h4></div></div>
+<p>
+ All GNOME applications must contain information about the
+ license (for software, not for documentation), either in the
+ "About" box or in the manual.
+ </p>
+</div>
+<div class="sect3">
+<a name="bugtraq"></a>
+<div class="titlepage"><div><h4 class="title">
+<a name="bugtraq"></a>
+<span class="title"> Bug reporting</span>
+</h4></div></div>
+<p>
+ Application documentation should give an address for
+ reporting bugs and for submitting comments about the
+ documentaion (see templates for an example).
+ </p>
+</div>
+</div>
+</div>
+<div class="sect1">
+<a name="writingapplicationmanuals"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="writingapplicationmanuals"></a>
+<span class="title">Writing Application and Applet Manuals</span>
+</h2></div></div>
+<p>
+ Every GNOME application or applet should have a manual specific
+ to that particular application. This manual should be a complete
+ and authoritative guide. The manual should describe what the
+ program does and how to use it. Manuals will typically describe
+ each window or panel presented to the user using screenshots (in
+ PNG format only) when appropriate. They should also describe
+ each feature and preference option available.
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2847828">Documentation Availability</a></h3>
+<p>
+ Applications and applets should not rely on documentation
+ which is only available on the internet. All manuals and
+ other documentation should be packaged with the application or
+ applet and be made available to the user through the standard
+ GNOME help system methods described below.
+ </p>
+</div>
+<p> Application manuals should be based on the template in
+ <a href="#template1">the section called “Template 1: Application Manual”</a>. Applet manuals should be based on
+ the templates in <a href="#template2-1x">the section called “Template 2: Applet Manual For GNOME 1.x”</a> for GNOME
+ versions 1.x and the templates in <a href="#template2-2x">the section called “Template 2: Applet Manual For GNOME 2.x”</a>
+ for GNOME versions 2.x.
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2847868">Manuals For Large Applications</a></h3>
+<p>
+ Manuals for very large applications, such as GNOME Workshop
+ components should be a <tt><book></tt> (and thus
+ use <tt><chapter></tt> for each primary section)
+ , instead of <tt><article></tt> which most
+ applications use(with each primary section being a
+ <tt><sect1></tt>).
+ </p>
+</div>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2847983">Applet Manuals in GNOME 2.0</a></h3>
+<p>
+ Note that applet manuals in GNOME 2.0 are treated in a special
+ way. The manuals for all applets are merged into a single
+ virtual document by Nautilus. For this reason, the header
+ information for applet manuals is omitted and the first
+ section of each applet is
+ <tt><sect1></tt>. Applet manuals will typically
+ have several sections, each of which is
+ <tt><sect2></tt>.
+ </p>
+</div>
+<p>
+ Application manuals should be made available by having a
+ "Manual" entry in the Help pull-down menu
+ at the top of the
+ application, as described in <a href="#listingdocsinhelpmenu">the section called “Listing Documents in the Help Menu”</a>.
+ Applets should make their manuals available by
+ right-clicking on the applet.
+ </p>
+</div>
+<div class="sect1">
+<a name="listingdocsinhelpmenu"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="listingdocsinhelpmenu"></a>
+<span class="title">Listing Documents in the Help Menu</span>
+</h2></div></div>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2848101">Developer Information</a></h3>
+<p>
+ This section is for developers. Documentation authors
+ generally do not need to know this material.
+ </p>
+</div>
+<p>
+ Typically the application manual and possibly additional help
+ documents will be made available to the user under the
+ Help menu at the top right of the
+ application. To do this, you must first write a
+ <tt>topic.dat</tt> file. The format for this file is:
+ <pre class="programlisting">
+One line for each 'topic'.
+
+Two columns, as defined by perl -e 'split(/\s+/,$aline,2)'
+
+First column is the HTML file (and optional section) for the topic,
+relative to the app's help file dir.
+
+Second column is the user-visible topic name.
+ </pre>
+ For example, Gnumeric's
+ <tt>topic.dat</tt> file is:
+ <pre class="programlisting">
+gnumeric.html Gnumeric manual
+function-reference.html Gnumeric function reference
+ </pre>
+ When the application is installed, the
+ <tt>topic.dat</tt> file should be placed in the
+ <tt>$prefix/share/gnome/help/<i><tt>appname</tt></i>/C/</tt> directory
+ where <i><tt>appname</tt></i> is replaced by the
+ application's name. The application documentation (converted
+ from SGML into HTML with <b>db2html</b>) should be
+ placed in this directory too.
+ </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2848245">Note</a></h3>
+<p>
+ If the help files are not present in the correct directory, the
+ menu items will NOT appear when the program is run.
+ </p>
+</div>
+<p>
+ The <tt>topic.dat</tt> file is used by the GNOME
+ menu building code to generate the Help
+ menu. When you define your menu:
+<pre class="programlisting">
+GnomeUIInfo helpmenu[] = {
+ {GNOME_APP_UI_ITEM,
+ N_("About"), N_("Info about this program"),
+ about_cb, NULL, NULL,
+ GNOME_APP_PIXMAP_STOCK, GNOME_STOCK_MENU_ABOUT,
+ 0, 0, NULL},
+ GNOMEUIINFO_SEPARATOR,
+ GNOMEUIINFO_HELP("<i>appname</i>"),
+ GNOMEUIINFO_END
+ };
+</pre>
+ the line specifying <tt>GNOMEUIINFO_HELP</tt> causes
+ GNOME to create a menu entry which is tied to the documentation
+ in the directory mentioned above. Also, all the topics in the
+ <tt>topic.dat</tt> file will get menu entries in the
+ Help menu. When the user selects any of these
+ topics from the Help menu, a help browser
+ will be started with the associated HTML documentation.
+ </p>
+</div>
+<div class="sect1">
+<a name="applicationhelpbuttons"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="applicationhelpbuttons"></a>
+<span class="title">Application Help Buttons</span>
+</h2></div></div>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2848382">Developer Information</a></h3>
+<p>
+ This section is for developers. Documentation authors
+ generally do not need to know this material.
+ </p>
+</div>
+<p>
+ Most GNOME applications will have Help
+ buttons. These are most often seen in Preference windows. (All
+ Preference windows should have Help
+ buttons.) Most Help buttons will connect
+ to the application manual, although some may connect to special
+ documents. Because the Help buttons do
+ not generally have their own special documentation, the
+ documentation author(s) do not need to do very much. However,
+ the application author must be careful to guarantee that the
+ application correctly opens the help documentation when the
+ Help buttons are pressed.
+ </p>
+<p>
+ To make the Help buttons call the correct document in the GNOME Help
+ Browser the developer should add code based on the following example:
+ </p>
+<pre class="programlisting">
+gchar *tmp;
+tmp = gnome_help_file_find_file ("module", "page.html");
+if (tmp) {
+ gnome_help_goto(0, tmp);
+ g_free(tmp);
+}
+ </pre>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2848488">NOTE</a></h3>
+<p>
+ The example above is in the C language, please refer to other
+ documentation or forums for other GNOME language bindings.
+ </p>
+</div>
+</div>
+<div class="sect1">
+<a name="packagingappletdocs"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="packagingappletdocs"></a>
+<span class="title">Packaging Applet Documentation</span>
+</h2></div></div>
+<div class="sect2">
+<a name="appletfiles"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="appletfiles"></a>
+<span class="title">Applet Documentation Files</span>
+</h3></div></div>
+<p>
+ In GNOME 2.0 each applet will have its own documentation
+ installed separately, and the GNOME 2.0 help
+ browser (Nautilus) will dynamically
+ merge the applet documents into a single virtual book
+ called <i>GNOME Applets</i>. During the
+ transitionary stage between GNOME 1.0 and GNOME 2.0, each
+ applet in the gnome-applets package has its own manual(stored
+ with the applet in CVS), but they are merged together manually
+ to create the <i>GNOME Applets</i> book before
+ distribution. Telsa
+ <tt><<a href="mailto:hobbit@aloss.ukuu.org.uk">hobbit@aloss.ukuu.org.uk</a>></tt> is the maintainer of
+ this document. Applet documentation should be sent to Telsa
+ (or placed in CVS) who will make sure they are correctly
+ packaged with the applets. The applet author should be
+ contacted to modify the menu items and help buttons to bind to
+ the applet documentation if necessary.
+ </p>
+<p>
+ Images which are part of the applet documentation should be in
+ PNG format and should reside in the same directory as the SGML
+ document file in CVS(gnome-applets/APPLETNAME/help/C).
+ </p>
+<p>
+ Applets which are not part of the gnome-applets package must
+ package their documentation with the particular applet
+ package. They should use the same applet template as other
+ applets. However, the <tt><xref></tt> links to
+ the introductory chapter of the <i>GNOME
+ Applets</i> book must be removed (as the 1.x
+ GNOME Help Browser does not allow
+ you to create links between separate documents) and replaced
+ with suitable text. Note that since this document is not part
+ of the <i>GNOME Applets</i> book, you must
+ remember to add <tt><legalnotice></tt> and
+ <tt><copyright></tt> sections.
+ </p>
+</div>
+<div class="sect2">
+<a name="appletmenu"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="appletmenu"></a>
+<span class="title">Adding Documentation to an Applet Menu</span>
+</h3></div></div>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2848730">Developer Information</a></h3>
+<p>
+ This section is for developers. Documentation authors
+ generally do not need to know this material.
+ </p>
+</div>
+<p>
+ Applets should have About and
+ Manual menu items, typically as the first
+ and second top-most items in the menu respectively. This
+ section describes how the developer creates these menu items
+ and links them to the documentation.
+ </p>
+<p>
+ To add an applet's manual to its applet menu, use:
+<pre class="programlisting">
+/* add an item to the applet menu */
+applet_widget_register_callback(APPLET_WIDGET(applet), "manual",
+_("Manual"), &open_manual, NULL);
+</pre>
+ Here the second argument is an arbitrary name for the
+ callback, the third argument is the label which will appear
+ when the user right clicks on the applet, and the fourth
+ argument is the callback function.
+ </p>
+<p>
+ You will need to write a simple callback function to open the
+ help browser to the appropriate document. This is done using
+ the <tt>gnome_help_file_find_file</tt> function,
+ as described in <a href="#applicationhelpbuttons">the section called “Application Help Buttons”</a>.
+ </p>
+<p>
+ You will also want to add an About menu
+ item to the applet's menu. This is a
+ stock menu item and is done:
+<pre class="programlisting">
+applet_widget_register_stock_callback (APPLET_WIDGET(applet), "about",
+ GNOME_STOCK_MENU_ABOUT, _("About"), &my_applet_cb_about,
+ NULL);
+</pre>
+ </p>
+<p>
+ More information can be found at <a href="http://developer.gnome.org/doc/tutorials/applet/index.html" target="_top">Writing
+ GNOME panel applets using the GTK+/GTK-- widget set</a>.
+ </p>
+</div>
+</div>
+<div class="sect1">
+<a name="writingcontextsensitivehelp"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="writingcontextsensitivehelp"></a>
+<span class="title">Writing Context Sensitive Help (coming in GNOME-2.0)</span>
+</h2></div></div>
+<p>
+ Context sensitive help, also known as "pop-up" help, will allow
+ a user to obtain help information about specific buttons or
+ parts of an application.
+ </p>
+<p>
+ Context sensitive help is still under development and not all
+ the details are available at this time. However, the basics can
+ be shown here so that you can understand how the system will
+ work.
+ </p>
+<p>
+ The Context Sensitive Help system is designed to allow the
+ developer to give an id to a particular portion of the User
+ Interface, for example, a button. Once the interface is complete
+ a Perl script can then be run against the interface code to
+ create a "map" file. This map file allows the developer or
+ writer to associate particular paragraph sections from an XML
+ document to the interface items.
+ </p>
+<p>
+ The XML used for the document is a small XML DTD that is being
+ developed to use the same tags (albeit, much fewer) as DocBook
+ so that writers do not have to re-learn a new DTD.
+ </p>
+<p>
+ Once the document is written and map file is complete, when the
+ user launches context sensitive help on the interface (either by
+ pressing a button and then clicking on the interface item they
+ want information on, or by right mouse clicking on the interface
+ item and selecting a pop-up menu item like "What's This") a
+ small transient window will appear with brief but detailed
+ information on the interface item.
+ </p>
+</div>
+<div class="sect1">
+<a name="referring"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="referring"></a>
+<span class="title">Referring to Other GNOME Documentation (coming in
+ GNOME-2.0)</span>
+</h2></div></div>
+<p>
+ In the GNOME 2.0 Help System, you will be able to create links
+ from one document to another. The exact mechanism for doing
+ this is in development.
+ </p>
+</div>
+<div class="sect1">
+<a name="basics"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="basics"></a>
+<span class="title">Basics of Documentation Style</span>
+</h2></div></div>
+<p>
+ Most people have never enjoyed reading a software manual, and
+ they probably never will. Many times, they'll read the
+ documentation only when they run into problems, and they'll be
+ frustrated and upset before they even read a word. On the
+ other hand, some readers will read the manual all the way
+ through, or at least look at the introduction before they
+ start. Your document might serve as a reference for an expert
+ or a guide to a beginner, and it must have enough depth to
+ satisfy the first without overwhelming the second. Ideally, it
+ will serve beginners as they <i>become</i>
+ experts. Remember, your goal is to produce <i>complete,
+ intuitive and clear</i> documentation.
+ </p>
+<p>
+ In order to write useful documentation, you'll have to know who
+ your audience is likely to be. Then, you can look for the
+ problems they're likely to run into, and solve them. It will
+ also help if you focus on the tasks users will perform, and
+ group features accordingly, rather than simply describing
+ features at random.
+ </p>
+<div class="sect2">
+<a name="styleplanning"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="styleplanning"></a>
+<span class="title">Planning</span>
+</h3></div></div>
+<p>
+ Begin documenting by learning how to use the application and
+ reading over any existing documentation. Pay attention to
+ places where your document will differ from the template. It
+ may help to develop a document skeleton: a valid XML or SGML
+ document that has little or no content. For very large
+ applications, you will need to make significant departures
+ from the templates, since you'll be using the
+ <tt><book></tt> tag instead of
+ <tt><chapter></tt> or
+ <tt><article></tt>.
+ </p>
+</div>
+<div class="sect2">
+<a name="balance"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="balance"></a>
+<span class="title">Achieving a Balanced Style</span>
+</h3></div></div>
+<p>
+ Just as you need to juggle expert and novice readers,
+ you'll have to juggle a number of other extremes as you write:
+ <div class="itemizedlist"><ul>
+<li><p>
+<a name="id2849250"></a>
+ Documents should be complete, yet concise. You should
+ describe every feature, but you'll have decide how much
+ detail is really necessary. It's not, for example,
+ necessary to describe every button and form field in a
+ dialog box, but you should make sure that your readers
+ know how to bring up the dialog and what it does. If
+ you spend fewer words on the obvious, you can spend more
+ time clarifying the ambiguous labels and explaining
+ items that are more complex.
+ </p></li>
+<li><p>
+<a name="id2849277"></a>
+ Be engaging and friendly, yet professional. Games
+ documents may be less formal than productivity
+ application documents (people don't
+ <i>use</i> games, they
+ <i>play</i> them), but all of them should
+ maintain a standard of style which holds the reader's
+ interest without resorting to jokes and untranslatable
+ allusions or puns.
+ </p></li>
+<li><p>
+<a name="id2849316"></a>
+ Examples, tips, notes, and screenshots are useful to
+ break up long stretches of text, but too many can get in
+ the way, and make your documents too choppy to read.
+ It's good to provide a screenshot of any dialog windows
+ a user might run into, but if a dialog box has several
+ tabs, it's not usually necessary to have one for each.
+ </p></li>
+<li><p>
+<a name="id2849340"></a>
+ The GDP strives to have all of its documentation conform
+ to certain standards of style and content, but every
+ document (and every writer) is different. You will need
+ to use your judgement, and write documents to fit with
+ the rest of the project, without compromising the
+ individual needs of your subject, or your own
+ individuality as a writer.
+ </p></li>
+</ul></div>
+ </p>
+</div>
+<div class="sect2">
+<a name="stylestructure"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="stylestructure"></a>
+<span class="title">Structure</span>
+</h3></div></div>
+<p>
+ In general, you won't have to worry too much about structure,
+ because the templates provide you with an excellent example.
+ As a general rule, try to follow that structural example.
+ That means using links, hierarchical nesting, and, if
+ necessary, a glossary or index. You probably won't need to
+ use every available structural tag, but take advantage of
+ what DocBook provides you.
+ </p>
+<p>
+ As to linking, there's some disagreement about whether to use
+ <tt><xref></tt> <tt><link></tt>
+ when you make links within your documents. You'll have to
+ decide, based on the different ways that they are presented
+ in output, which is more appropriate given the context.
+ Regardless of which you use, you should not forget to use
+ them. Help your readers find information that relevant to
+ the issue at hand.
+ </p>
+<p>
+ The table of contents will be generated automatically, but
+ you will probably have to develop your own index if you wish
+ to have one. The Nautilus Help Browser will have new, and
+ currently unknown, indexing capabilities, so index style and
+ structure are still under discussion. The GNOME User's Guide
+ will contain a glossary in its next versions; unless you're
+ writing a<tt><book></tt>, it will probably be best to
+ contribute to that rather than developing your own.
+ </p>
+</div>
+<div class="sect2">
+<a name="stylegrammar"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="stylegrammar"></a>
+<span class="title">Grammar and Spelling</span>
+</h3></div></div>
+<p>
+ Nobody expects you to be perfect; they just expect the
+ documentation for their software to be error-free. That means
+ that, in the same way that developers look for bugs and accept
+ bug reports, writers must check for errors in their documents.
+ Poor grammar, bad spelling, and gross technical errors in
+ draft documents are fine. However, if those problems show up
+ in a "real" release, they can count against the credibility of
+ GNOME and Linux. They'll also make you look bad.
+ </p>
+<p>
+ There is no substitute for a human proofreader; use a
+ spell-check program, then read it over yourself, and then find
+ someone else to help you. Other GDP members are, of course,
+ willing and able to help you, but non-writers are often at
+ least as helpful.
+ </p>
+<p>
+ Proofreading documents is both a also a good way to
+ familiarize yourself with documentation, and it certainly
+ makes you valuable to the GDP. Help other writers proof their
+ documents, and they will help you with yours.
+ </p>
+</div>
+</div>
+<div class="sect1">
+<a name="teamwork"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="teamwork"></a>
+<span class="title">Teamwork</span>
+</h2></div></div>
+<div class="sect2">
+<a name="teamworkgdp"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="teamworkgdp"></a>
+<span class="title">Working With The GDP Team</span>
+</h3></div></div>
+<p>
+ The GDP team is a valuable resource for any documentation
+ author. GDP members can answer most questions documentation
+ authors have during the course of their work. It is also
+ important to make sure you are not duplicating work of other
+ GDP members by visiting the <i>GDP Documentation
+ Status Table</i> (<a href="http://www.gnome.org/gdp/doctable/" target="_top">http://www.gnome.org/gdp/doctable/</a>) and
+ assigning a documentation item to yourself. This table also
+ provides a forum for making suggestions and announcements for
+ each documentation item. The best way to get in touch with
+ GDP members is on the #docs IRC channel at irc.gnome.org or
+ else by emailing the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
+ <i>gnome-doc-list mailing list</i>
+</a>.
+ </p>
+<p>
+ After an author has finished a document (or even a draft
+ version of the document), it is a good idea to ask a member of
+ the GDP team to read the document, checking it for grammar,
+ proper DocBook markup, and clarity. One may typically find
+ another author to do this by either asking on the #docs IRC
+ channel at irc.gnome.org or by emailing the <a href="http://mail.gnome.org/mailman/listinfo/gnome-doc-list/" target="_top">
+ <i>gnome-doc-list mailing list</i>
+</a>.
+ </p>
+</div>
+<div class="sect2">
+<a name="teamworkdevelopers"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="teamworkdevelopers"></a>
+<span class="title">Working With Developers</span>
+</h3></div></div>
+<p>
+ Writing documentation typically involves a certain amount of
+ interaction with the developers of GNOME or the application
+ which is being documented. Often a document author will need
+ to ask the developer technical questions during the course of
+ writing a document. After the document is finished, it is good
+ idea to ask the developer to read the document to make sure it
+ is technically correct. The documentation author should also
+ make sure that the application author correctly binds and
+ packages the documentation with the application.
+ </p>
+</div>
+</div>
+<div class="sect1">
+<a name="finishing"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="finishing"></a>
+<span class="title">Finishing A Document</span>
+</h2></div></div>
+<div class="sect2">
+<a name="editting"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="editting"></a>
+<span class="title">Editing The Document</span>
+</h3></div></div>
+<p>
+ When the document is finished, the document should be edited
+ by another member of the GDP for spelling, clarity, and
+ DocBook markup. It should also be read by an application
+ author to make sure the document is technically accurate.
+ </p>
+</div>
+<div class="sect2">
+<a name="submitting"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="submitting"></a>
+<span class="title">Submitting The Document</span>
+</h3></div></div>
+<p>
+ After the document has been edited and checked for technical
+ accuracy, it is ready to be combined with the application or
+ documentation package. This is typically done by passing the
+ document to the application or package developer. In some
+ cases, the documents can be committed directly into CVS,
+ however this should only be done after obtaining permission to
+ make CVS commits from the developer. Note that in many cases,
+ the application may need to be modified to correctly link to
+ the documentation. The packaging system (tarballs and binary
+ packages) may also need to be modified to include the
+ documentation in the package. Generally, this should be done
+ by the developers.
+ </p>
+<p>
+ The final step is to email the GNOME Translation Team at
+ <tt><<a href="mailto:gnome-i18n@nuclecu.unam.mx">gnome-i18n@nuclecu.unam.mx</a>></tt> to notify them that
+ there is a new document for them to translate.
+ </p>
+</div>
+</div>
+<div class="sect1">
+<a name="resources"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="resources"></a>
+<span class="title">Resources</span>
+</h2></div></div>
+<div class="sect2">
+<a name="resourcesweb"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="resourcesweb"></a>
+<span class="title">Resources On The Web</span>
+</h3></div></div>
+<p> The <a href="http://developer.gnome.org/projects/gdp/" target="_top">GNOME
+ Documentation Project Web page</a> lists current GDP
+ projects and members.
+ </p>
+<p>
+ The <a href="http://www.gnome.org/gdp/doctable/" target="_top">GDP Documentation Status Table</a> tracks the
+ status of all the various documentation components of GNOME.
+ </p>
+<p>
+ Norman Walsh's <a href="http://www.docbook.org" target="_top"> <i>DocBook: The Definitive
+ Guide</i>
+</a> in an excellent book on DocBook,
+ available both online and in print.
+ </p>
+</div>
+<div class="sect2">
+<a name="resourcesbooks"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="resourcesbooks"></a>
+<span class="title">Books</span>
+</h3></div></div>
+<p>
+ Docbook: The Definitive Guide is available in both printed
+ form and on the web at:
+ <a href="http://www.docbook.org/tdg/index.html" target="_top">
+ <i>Docbook: The Definitive Guide</i>
+ </a>
+ </p>
+</div>
+<div class="sect2">
+<a name="mailinglists"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="mailinglists"></a>
+<span class="title">Mailing Lists</span>
+</h3></div></div>
+<p>
+ The <i>gnome-docs-list</i> mailing list is the
+ main discussion area for all contributors to the GNOME
+ Documentation Project. You can find out how to subscribe to
+ this list on <a href="http://www.gnome.org/resources/mailing-lists.html" target="_top">GNOME Mailing Lists</a>. This is a rather
+ low-volume list, so you will not be flooded with messages.
+ </p>
+</div>
+<div class="sect2">
+<a name="irc"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="irc"></a>
+<span class="title">IRC</span>
+</h3></div></div>
+<p>
+ Internet Relay Chat (IRC) is a fast and easy way to get in
+ touch with other GDP members. There are generally at least a
+ few members here who can answer questions or discuss
+ documentation issues. The IRC channel is #docs at
+ irc.gnome.org.
+ </p>
+</div>
+</div>
+<div id="templates" class="appendix">
+<h2 class="title" style="clear: all">
+<a name="templates"></a>Appendix A. Document Templates</h2>
+<div class="sect1">
+<a name="template1"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="template1"></a>
+<span class="title">Template 1: Application Manual</span>
+</h2></div></div>
+<p>
+ The following template should be used for all application
+ manuals. You can always get the latest copy of this
+ template from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
+ Documentation Templates</a>.
+ <pre class="programlisting">
+
+
+<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
+ <!-- if not using PNG graphic, replace reference above with
+ .....PUBLIC "-//OASIS//DTD DocBook V3.1//EN"[
+ -->
+<!ENTITY version "1.0.53">
+ <!-- replace version above with actual application version number-->
+ <!-- Template Version: 1.0.1 (do not remove this line) -->
+]>
+
+
+<!-- This is a GNOME documentation template, designed by the GNOME
+ Documentation Project Team. Please use it for writing GNOME
+ documentation, making obvious changes. In particular, all the words
+ written in UPPERCASE (with the exception of GNOME) should be
+ replaced. As for "legalnotice", please leave the reference
+ unchanged.
+
+ Remember that this is a guide, rather than a perfect model to follow
+ slavishly. Make your manual logical and readable. And don't forget
+ to remove these comments in your final documentation! ;-)
+ -->
+
+<!-- =============Document Header ============================= -->
+
+<article id="index"> <!-- please do not change the id -->
+
+ <artheader>
+ <title>MY-GNOME-APP</title>
+ <copyright>
+ <year>2000</year>
+ <holder>ME-THE-AUTHOR</holder>
+ </copyright>
+
+ <!-- translators: uncomment this:
+
+ <copyright>
+ <year>2000</year>
+ <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
+ </copyright>
+
+ -->
+
+ <!-- do not put authorname in the header except in copyright - use
+ section "authors" below -->
+
+ <legalnotice>
+ <para>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the <citetitle>GNU Free
+ Documentation License</citetitle>, Version 1.1 or any later
+ version published by the Free Software Foundation with no
+ Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. You may obtain a copy of the <citetitle>GNU Free
+ Documentation License</citetitle> from the Free Software
+ Foundation by visiting <ulink type="http"
+ url="http://www.fsf.org">their Web site</ulink> or by writing
+ to: Free Software Foundation, Inc., 59 Temple Place - Suite
+ 330, Boston, MA 02111-1307, USA.
+ </para>
+ <para>
+ Many of the names used by companies to distinguish their
+ products and services are claimed as trademarks. Where those
+ names appear in any GNOME documentation, and those trademarks
+ are made aware to the members of the GNOME Documentation
+ Project, the names have been printed in caps or initial caps.
+ </para>
+ </legalnotice>
+
+ <!-- this is the version of manual, not application -->
+ <releaseinfo>
+ This is version 1.0 of MY-GNOME-APP manual.
+ </releaseinfo>
+
+ </artheader>
+
+ <!-- ============= Document Body ============================= -->
+
+ <!-- ============= Introduction ============================== -->
+ <sect1 id="intro">
+ <title>Introduction</title>
+
+ <para>
+ <application>MY-GNOME-APP</application> is an application which
+ proves mathematical theorems. It has all the basic features
+ expected from a mathematical theorem prover, as well as a number
+ of advanced ones, such as proof by confusion. In fact, many of
+ the proofs produced by <application>MY-GNOME-APP</application>
+ are so complex that they are capable of proving almost anything
+ with a virtually null likelihood of being disproven. It also has
+ the very popular predecessor of proof by confusion, proof by
+ dialog, first implemented by Plato.
+ </para>
+ <para>
+ It also allows you to save and print theorem proofs and to add
+ comments to the proofs it produces.
+ </para>
+
+ <para>
+ To run <application>MY-GNOME-APP</application>, select
+ <menuchoice>
+ <guisubmenu>SUBMENU</guisubmenu>
+ <guimenuitem>MY-GNOME-APP</guimenuitem>
+ </menuchoice>
+ from the <guimenu>Main Menu</guimenu>, or type
+ <command>MYGNOMEAPP</command> on the command line.
+ </para>
+
+ <para>
+ <application>MY-GNOME-APP</application> is included in the
+ <filename>GNOME-PACKAGE</filename> package, which is part of the
+ GNOME desktop environment. This document describes version
+ &version; of <application>MY-GNOME-APP</application>.
+ </para>
+ </sect1>
+
+
+ <!-- ================ Usage ================================ -->
+ <!-- This section should describe basic usage of the application. -->
+
+ <sect1 id="usage">
+ <title>Using MY-GNOME-APP</title>
+ <para>
+ <application>MY-GNOME-APP</application> can be used to produce a
+ perfect proof of <emphasis>any</emphasis> mathematical theorem
+ (provided, of course, that this theorem is correct), thus
+ providing for new users an easy-to-use graphical interface to
+ modern mathematics. This section describes basic usage of
+ <application>MY-GNOME-APP</application>.
+ </para>
+
+ <!-- ========= Basic Usage =========================== -->
+ <sect2 id="mainwin">
+ <title>Basic usage</title>
+ <para>
+ Starting <application>MY-GNOME-APP</application> opens the
+ <interface>Main window</interface>, shown in <xref
+ linkend="mainwindow-fig">. The window is at first empty.
+
+ <!-- ==== Figure ==== -->
+ <figure id="mainwindow-fig">
+ <title>MY-GNOME-APP Main Window</title>
+ <screenshot>
+ <screeninfo>MY-GNOME-APP Main Window</screeninfo>
+ <graphic fileref="SCREENSHOT" format="png" srccredit="ME">
+ </graphic>
+ </screenshot>
+ </figure>
+ <!-- ==== End of Figure ==== -->
+ </para>
+
+
+ <!-- For this app, one could put "proving" or "edit" (probably even
+ both of them) as sect2's seperate from the main window
+ section. Since they were both so closely involved with the main
+ window, I decided to have them as sect3's isntead. Judgement
+ call. -->
+
+ <sect3 id="proving">
+ <title>Proving a Theorem</title>
+ <para>
+ To get a proof of a theorem, select
+ <menuchoice>
+ <guisubmenu>File</guisubmenu>
+ <guimenuitem>New</guimenuitem>
+ </menuchoice>,
+ which will
+ bring up the <interface>New Proof</interface> dialog box.
+ Enter the statement of the theorem in the
+ <guilabel>Theorem statement</guilabel> field, select your
+ desired proof type from the drop-down menu, and and press
+ <guibutton>Prove!</guibutton>.
+ </para>
+ <para>
+ If <application>MY-GNOME-APP</application> cannot prove the
+ theorem by the method you have chosen, or if you have not
+ selected a proof type at all,
+ <application>MY-GNOME-APP</application> will attempt to
+ choose the one that it thinks is most conclusive. In order,
+ it will attempt to prove the theorem with the following techniques:
+
+ <variablelist>
+ <varlistentry>
+ <term>Deduction</term>
+ <listitem>
+ <para>
+ This is a proof method that is generally accepted
+ for full credit by Logic professors.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Induction</term>
+ <listitem>
+ <para>
+ This logical style will also earn you full credit on
+ your homework.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Dialog</term>
+ <listitem>
+ <para>
+ This logical method is best for Philosophy classes,
+ and will probably only merit partial credit on Logic
+ or Mathematics homework.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Confusion</term>
+ <listitem>
+ <para>
+ Suitable only for political debates, battles of wits
+ against the unarmed, and Philosophy classes focusing
+ on the works of Kant. Use with caution.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <!-- You might want to include a note, warning, or tip, e.g. -->
+
+ <warning>
+ <title>Proving Incorrect Theorms</title>
+ <para>
+ <application>MY-GNOME-APP</application> cannot prove
+ incorrect theorems. If the theorem you have entered is not
+ demonstrably true, you will get a message to that effect
+ in the main window. To disprove a theorem, ask
+ <application>MY-GNOME-APP</application> to prove its
+ logical inverse.
+ </para>
+ </warning>
+ </sect3>
+ <sect3 id="editing">
+ <title>Editing Proofs</title>
+ <para>
+ Once you have proven the theorem, it will be displayed in
+ the <interface>main window</interface>. There, you can read
+ it over, choose text styles for different portions of it,
+ and make comments on it. This section will guide you through
+ that process.
+ </para>
+ <para>
+ To alter text styles, first select the statement you wish to
+ change by clicking on it once. You can select several
+ statements by Then, choose the style you want to apply from
+ the <guisubmenu>Style</guisubmenu> submenu of the
+ <guimenu>Edit</guimenu> menu.
+ <application>MY-GNOME-APP</application> will convert the
+ text to that style.
+ </para>
+ <para>
+ You can also enter comments on a statement by selecting that
+ statement, and then beginning to type. Comments will appear
+ after the statement you have selected.
+ </para>
+
+ <note>
+ <title>Altering The Proofs Themselves</title>
+ <para>
+ <application>MY-GNOME-APP</application> does not allow you
+ to alter a proof it has produced itself. You can, save
+ your proof as a plain text file (using the
+ <guimenuitem>Save as...</guimenuitem> menu), and alter it
+ that way. Be aware, however, that
+ <application>MY-GNOME-APP</application> uses its own file
+ format for saved proofs, and cannot re-open a file unless
+ it is in the .mga format.
+ </para>
+ </note>
+ </sect3>
+
+
+ <!-- If there are other functions performed from the main window,
+ they belong here. -->
+
+ </sect2>
+
+ <!-- =========================================================
+ Additional Sect2's should describe additional windows, such as
+ larger dialog boxes, or functionality that differs significantly
+ from the most immediate functions of the application. Make the
+ structure logical.
+ ============================================================= -->
+
+
+ <sect2 id="toolbar">
+ <title>Toolbar</title>
+ <para>
+ The toolbar (shown in <xref linkend="figure-usage-toolbar">)
+ provides access to several commonly used routines.
+ <figure id="figure-usage-toolbar">
+ <title>MY-GNOME-APP Toolbar</title>
+ <screenshot>
+ <screeninfo>MY-GNOME-APP Toolbar</screeninfo>
+ <graphic fileref="usage-toolbar.png" format="png"></graphic>
+ </screenshot>
+ </figure>
+ <variablelist>
+ <varlistentry>
+ <term>New</term>
+ <listitem>
+ <para>
+ Brings up the <interface>New Theorem</interface>
+ dialog.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Open</term>
+ <listitem>
+ <para>
+ Open an exisiting theorem you want to prove, or a
+ completed proof you wish to print or format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Save</term>
+ <listitem>
+ <para>
+ Save the current theorem permanently in a
+ file.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+ <!-- ========= Menus =========================== -->
+
+ <sect2 id="menubar">
+
+ <!-- Describing the menubar ensures comprehensive feature
+ coverage. Nest itemizedlists inside variablelists so that each
+ menu is easily located by indexing software. Proper indentation
+ makes it easier! -->
+
+ <title>Menus</title>
+ <para>
+ The menu bar, located at the top of the <interface>Main
+ Window</interface>, contains the following menus:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><guimenu>File</guimenu></term>
+ <listitem>
+ <para>
+ This menu contains:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycap>F3</keycap>
+ </shortcut>
+ <guimenuitem>Open</guimenuitem>
+ </menuchoice>
+ &mdash; This opens a file which is saved on your computer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo>
+ </shortcut>
+ <guimenuitem>Save</guimenuitem>
+ </menuchoice>
+ &mdash; This saves your file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo>
+ </shortcut>
+ <guimenuitem>Close</guimenuitem>
+ </menuchoice>
+ &mdash; This closes your file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
+ </shortcut>
+ <guimenuitem>Exit</guimenuitem>
+ </menuchoice>
+ &mdash; This quits the application.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><guimenu>Edit</guimenu></term>
+ <listitem>
+ <para>
+ This menu contains:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo>
+ </shortcut>
+ <guimenuitem>Cut</guimenuitem>
+ </menuchoice>
+ &mdash; This removes any text or data which is selected and
+ places it in the buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
+ </shortcut>
+ <guimenuitem>Copy</guimenuitem>
+ </menuchoice>
+ &mdash; This copies any text or data which is selected into
+ the buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo>
+ </shortcut>
+ <guimenuitem>Paste</guimenuitem>
+ </menuchoice>
+ &mdash; This pastes any text or data which is copied into
+ the buffer.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guimenuitem>COMMAND1&hellip;</guimenuitem>
+ &mdash; This opens the <interface>COMMAND1</interface>
+ dialog, which is used to ....
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guimenuitem>COMMAND2</guimenuitem>
+ &mdash; This ....
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term><guimenu>Settings</guimenu></term>
+ <listitem>
+ <para>
+ This menu contains:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guimenuitem>Preferences&hellip;</guimenuitem>
+ &mdash; This opens the <link
+ linkend="prefs"><interface>Preferences
+ Dialog</interface></link>, which allows you to configure
+ many settings.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guimenuitem>COMMAND3</guimenuitem> &mdash;
+ This command does something.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><guimenu>Help</guimenu></term>
+ <listitem>
+ <para>
+ This menu contains:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guimenuitem>Manual</guimenuitem> &mdash; This
+ opens the <application>GNOME Help
+ Browser</application> and displays this manual.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <guimenuitem>About</guimenuitem> &mdash; This
+ opens the <interface>About</interface> dialog
+ which shows basic information about
+ <application>MY-GNOME-APP</application>, such as
+ the author's name, the application version number,
+ and the URL for the application's Web page if one
+ exists.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </sect2>
+ </sect1>
+
+
+
+ <!-- ============= Customization ============================= -->
+
+ <sect1 id="prefs">
+ <title>Customization</title>
+ <para>
+ To change the application settings, select
+ <menuchoice>
+ <guimenu>Settings</guimenu>
+ <guimenuitem>Preferences...</guimenuitem>
+ </menuchoice>. This opens the
+ <interface>Preferences</interface> dialog, shown in <xref
+ linkend="preferences-fig">.
+ </para>
+
+ <figure id="preferences-fig">
+ <title>Preferences Dialog</title>
+ <screenshot>
+ <screeninfo>Preferences Dialog</screeninfo>
+ <graphic fileref="SCREENSHOT" format="png"
+ srccredit="ME">
+ </graphic>
+ </screenshot>
+ </figure>
+
+ <para>
+ The properties in the <guilabel>PREFSTABNAME</guilabel> tab are:
+
+ <!--many people use itemizedlists in cases like this. Variablelists
+ are more appropriate -->
+
+ <variablelist>
+ <varlistentry>
+ <term> <guilabel>Default Text Style</guilabel></term>
+ <listitem>
+ <para>
+ Select the default text style for statements in your
+ proof. You can still change the style for individual
+ proofs or sections of a proof at a later date.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>(Configuration Item Label)</term>
+ <listitem>
+ <para>
+ (Description of Configuration)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>(Configuration Item Label)</term>
+ <listitem>
+ <para>
+ (Description of Configuration)
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ The properties in the <guilabel>SECONDTABNAME</guilabel> tab are:
+ <variablelist>
+ <varlistentry>
+ <term>(Configuration Item Label)</term>
+ <listitem>
+ <para>
+ (Description of Configuration)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>(Configuration Item Label)</term>
+ <listitem>
+ <para>
+ (Description of Configuration)
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ After you have made all the changes you want, click on
+ <guibutton>OK</guibutton> to apply the changes and close the
+ <interface>Properties</interface> dialog. To cancel the changes
+ and return to previous values, click the
+ <guibutton>Close</guibutton> button.
+ </para>
+
+ </sect1>
+
+
+ <!-- ============= Various Sections ============================= -->
+
+ <!-- Here you should add, if necessary, several more sect1's,
+ describing other windows (besides the main one), file formats,
+ preferences dialogs, etc. as appropriate. Try not to make any of
+ these sections too long. -->
+
+
+ <!-- ============= Bugs ================================== -->
+ <!-- This section should describe known bugs and limitations of
+ the program if there are any - please be frank and list all
+ problems you know of. -->
+ <sect1 id="bugs">
+ <title>Known Bugs and Limitations</title>
+ <para>
+ This application has no known bugs.
+ </para>
+ </sect1>
+
+
+<!-- ============= Authors ================================ -->
+
+ <sect1 id="authors">
+ <title>Authors</title>
+ <para>
+ <application>MY-GNOME-APP</application> was written by GNOME-HACKER
+ (<email>hacker@gnome.org</email>). To find more information about
+ <application>MY-GNOME-APP</application>, please visit the <ulink
+ url="http://www.my-gnome-app.org" type="http">MY-GNOME-APP Web
+ page</ulink>. Please send all comments, suggestions, and bug
+ reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
+ bug tracking database</ulink>. (Instructions for submitting bug
+ reports can be found <ulink
+ url="http://bugs.gnome.org/Reporting.html" type="http">
+ on-line</ulink>.) You can also use <application>Bug Report
+ Tool</application> (<command>bug-buddy</command>), available in the
+ <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
+ Menu</guimenu>, for submitting bug reports.
+ </para>
+
+ <para>
+ This manual was written by ME
+ (<email>MYNAME@MYADDRESS</email>). Please send all comments and
+ suggestions regarding this manual to the <ulink type="http"
+ url="http://developer.gnome.org/projects/gdp">GNOME Documentation
+ Project</ulink> by sending an email to
+ <email>docs@gnome.org</email>. You can also add your comments online
+ by using the <ulink type="http"
+ url="http://www.gnome.org/gdp/doctable/">GNOME Documentation Status
+ Table</ulink>.
+ </para>
+
+ <!-- For translations: uncomment this:
+
+ <para>
+ Latin translation was done by ME
+ (<email>MYNAME@MYADDRESS</email>). Please send all comments and
+ suggestions regarding this translation to SOMEWHERE.
+ </para>
+
+ -->
+
+ </sect1>
+
+
+ <!-- ============= Application License ============================= -->
+
+ <sect1 id="license">
+ <title>License</title>
+ <para>
+ This program is free software; you can redistribute it and/or
+ modify it under the terms of the <citetitle>GNU General Public
+ License</citetitle> as published by the Free Software Foundation;
+ either version 2 of the License, or (at your option) any later
+ version.
+ </para>
+ <para>
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ <citetitle>GNU General Public License</citetitle> for more details.
+ </para>
+ <para>
+ A copy of the <citetitle>GNU General Public License</citetitle> is
+ included as an appendix to the <citetitle>GNOME Users
+ Guide</citetitle>. You may also obtain a copy of the
+ <citetitle>GNU General Public License</citetitle> from the Free
+ Software Foundation by visiting <ulink type="http"
+ url="http://www.fsf.org">their Web site</ulink> or by writing to
+ <address>
+ Free Software Foundation, Inc.
+ <street>59 Temple Place</street> - Suite 330
+ <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
+ <country>USA</country>
+ </address>
+ </para>
+ </sect1>
+</article>
+
+
+
+
+
+
+
+
+
+
+
+
+</pre>
+ </p>
+</div>
+<div class="sect1">
+<a name="template2-1x"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="template2-1x"></a>
+<span class="title">Template 2: Applet Manual For GNOME 1.x</span>
+</h2></div></div>
+<p>
+ The following templates should be used for all applet
+ manuals in GNOME 1.x releases. You can always get the latest
+ copy of these templates from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
+ Documentation Templates</a>. Note that the template
+ consists of two files; the first file calls the second as an
+ entity. You should name the first file
+ <tt>
+<i><tt>appletname</tt></i>-applet.sgml</tt>
+ and the second file should be named
+ <tt>
+<i><tt>appletname</tt></i>.sgml</tt>,
+ where
+ <tt><i><tt>appletname</tt></i></tt> is
+ the name of the applet.
+ <pre class="programlisting">
+
+
+<!DOCTYPE Article PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
+ <!entity APPLETNAME.sgml SYSTEM "applet_template_1.sgml">
+ <!-- Template Version: 1.0.1 (do not remove this line) -->
+]>
+
+<!-- This is a GNOME documentation template, designed by the GNOME
+ Documentation Project Team. Please use it for writing GNOME
+ documentation, making obvious changes. In particular, all the words
+ written in UPPERCASE (with the exception of GNOME) should be
+ replaced. As for "legalnotice", please leave the reference
+ unchanged,make sure to add/remove trademarks to the list as
+ appropriate for your document.
+
+ Please don't forget to remove these comments in your final documentation,
+ thanks ;-).
+-->
+
+<article id="index"> <!-- please do not change the id -->
+
+ <!-- ============= Document Header ============================= -->
+ <artheader>
+ <title>APPLETNAME Applet</title>
+ <copyright>
+ <year>2000</year>
+ <holder>YOURFULLNAME</holder>
+ </copyright>
+
+ <!-- translators: uncomment this:
+
+ <copyright>
+ <year>2000</year>
+ <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
+ </copyright>
+
+ -->
+
+ <!-- do not put authorname in the header except in copyright - use
+ section "authors" below -->
+
+ <legalnotice>
+ <para>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the <citetitle>GNU Free Documentation
+ License</citetitle>, Version 1.1 or any later version published
+ by the Free Software Foundation with no Invariant Sections, no
+ Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy
+ of the <citetitle>GNU Free Documentation License</citetitle> from
+ the Free Software Foundation by visiting <ulink type="http"
+ url="http://www.fsf.org">their Web site</ulink> or by writing to:
+ Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ Boston, MA 02111-1307, USA.
+ </para>
+ <para>
+ Many of the names used by companies to distinguish their products and
+ services are claimed as trademarks. Where those names appear in any
+ GNOME documentation, and those trademarks are made aware to the members
+ of the GNOME Documentation Project, the names have been printed in caps
+ or initial caps.
+ </para>
+ </legalnotice>
+
+ <releaseinfo>
+ This is version XXX of the APPLETNAME applet manual.
+ </releaseinfo>
+ </artheader>
+
+ <!-- ============= Document Body ============================= -->
+
+ &APPLETNAME.sgml;
+
+</article>
+
+
+
+
+
+</pre>
+ <pre class="programlisting">
+
+ <!-- Template Version: 1.0.1 (do not remove this line) -->
+
+ <sect1 id="APPLET">
+ <title>APPLET Applet</title>
+
+ <para>
+ <application>APPLET</application> applet, shown in <xref
+ linkend="APPLETapplet-fig">, allows you to &hellip;. To add this
+ applet to a <interface>Panel</interface>,
+ right-click on the <interface>Panel</interface> and choose
+ <menuchoice>
+ <guimenu>Panel</guimenu>
+ <guisubmenu>Add to panel</guisubmenu>
+ <guisubmenu>Applet</guisubmenu>
+ <guisubmenu>SECTION</guisubmenu>
+ <guimenuitem>APPLET</guimenuitem>
+ </menuchoice>.
+ </para>
+
+ <figure id="APPLETapplet-fig">
+ <title>APPLET Applet</title>
+ <screenshot>
+ <screeninfo>APPLET Applet</screeninfo>
+ <graphic format="png" fileref="APPLET_applet"
+ srccredit="YOURNAME">
+ </graphic>
+ </screenshot>
+ </figure>
+
+ <!-- ============= Usage ================================ -->
+ <sect2 id="APPLET-usage">
+ <title>Usage</title>
+ <para>
+ (Place a short description of how to use the applet here.)
+ </para>
+
+ <para>
+ Right-clicking on the applet brings up a menu containing the
+ following items:
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <guimenuitem>Properties&hellip;</guimenuitem> &mdash;
+ opens the <link linkend="APPLET-prefs">
+ <guilabel>Properties</guilabel></link> dialog.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <guimenuitem>Help</guimenuitem> &mdash;
+ displays this document.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <guimenuitem>About&hellip;</guimenuitem> &mdash;
+ shows basic information about <application>APPLET
+ Applet</application>, including the applet's version and the
+ author's name.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ </sect2>
+
+
+ <!-- ============= Customization ============================= -->
+ <sect2 id="APPLET-prefs">
+ <title>Customization</title>
+ <para>
+ You can customize <application>APPLET</application>
+ applet by right-clicking on it and choosing
+ <guimenuitem>Properties&hellip;</guimenuitem>. This will open the
+ <interface>Properties</interface> dialog(shown in <xref
+ linkend="APPLET-settings-fig">), which allows you to
+ change various settings.
+ </para>
+
+ <figure id="APPLET-settings-fig">
+ <title>Properties dialog</title>
+ <screenshot>
+ <screeninfo>Properties dialog</screeninfo>
+ <graphic format="png" fileref="APPLET_settings"
+ srccredit="YOURNAME">
+ </graphic>
+ </screenshot>
+ </figure>
+
+ <para>
+ The properties are:
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ (Configuration Item Label) &mdash; If this button is
+ checked&hellip;(description)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ (Configuration Item Label) &mdash; Selecting this
+ button&hellip;(description)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ (Configuration Item Label) &mdash; Enter the name of
+ &hellip;(description)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ After you have made all the changes you want, click on
+ <guibutton>OK</guibutton> to apply the changes and close the
+ <interface>Properties</interface> dialog. To cancel the changes
+ and return to previous values, click the
+ <guibutton>Close</guibutton> button.
+ </para>
+ </sect2>
+
+
+ <!-- ============= Bugs ================================== -->
+ <!-- This section should describe known bugs and limitations of
+ the program if there are any - please be frank and list all
+ problems you know of -->
+ <sect2 id="bugs">
+ <title>Known Bugs and Limitations</title>
+ <para>
+ This applet has no known bugs.
+ </para>
+ </sect2>
+
+
+ <!-- ============= Authors ================================ -->
+
+ <sect2 id="authors">
+ <title>Authors</title>
+ <para>
+ <application>APPLET</application> was written by GNOME-HACKER
+ (<email>hacker@gnome.org</email>). Please send all comments,
+ suggestions, and bug
+ reports to the <ulink url="http://bugs.gnome.org" type="http">GNOME
+ bug tracking database</ulink>. (Instructions for submitting bug
+ reports can be found <ulink
+ url="http://bugs.gnome.org/Reporting.html" type="http">
+ on-line</ulink>. You can also use <application>Bug Report
+ Tool</application> (<command>bug-buddy</command>), available in the
+ <guisubmenu>Utilities</guisubmenu> submenu of <guimenu>Main
+ Menu</guimenu>, for submitting bug reports.
+ </para>
+
+ <para>
+ This manual was written by ME
+ (<email>MYNAME@MYADDRESS</email>). Please send all comments and
+ suggestions regarding this manual to the <ulink type="http"
+ url="http://developer.gnome.org/projects/gdp">GNOME Documentation
+ Project</ulink> by sending an email to
+ <email>docs@gnome.org</email>. You can also submit comments online
+ by using the <ulink type="http"
+ url="http://www.gnome.org/gdp/doctable/">GNOME Documentation
+ Status Table</ulink>.
+ </para>
+
+ <!-- For translations: uncomment this:
+
+ <para>
+ Latin translation was done by ME
+ (<email>MYNAME@MYADDRESS</email>). Please send all comments and
+ suggestions regarding this translation to SOMEWHERE.
+ </para>
+
+ -->
+
+ </sect2>
+
+
+ <!-- ============= Application License ============================= -->
+
+ <sect2 id="license">
+ <title>License</title>
+ <para>
+ This program is free software; you can redistribute it and/or
+ modify it under the terms of the <citetitle>GNU General Public
+ License</citetitle> as published by the Free Software Foundation;
+ either version 2 of the License, or (at your option) any later
+ version.
+ </para>
+ <para>
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ <citetitle>GNU General Public License</citetitle> for more details.
+ </para>
+ <para>
+ A copy of the <citetitle>GNU General Public License</citetitle> is
+ included as an appendix to the <citetitle>GNOME Users
+ Guide</citetitle>. You may also obtain a copy of the
+ <citetitle>GNU General Public License</citetitle> from the Free
+ Software Foundation by visiting <ulink type="http"
+ url="http://www.fsf.org">their Web site</ulink> or by writing to
+ <address>
+ Free Software Foundation, Inc.
+ <street>59 Temple Place</street> - Suite 330
+ <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
+ <country>USA</country>
+ </address>
+ </para>
+ </sect2>
+
+ </sect1>
+
+
+
+
+
+
+
+
+</pre>
+ </p>
+</div>
+<div class="sect1">
+<a name="template2-2x"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="template2-2x"></a>
+<span class="title">Template 2: Applet Manual For GNOME 2.x</span>
+</h2></div></div>
+<p>
+ The following templates should be used for all applet
+ manuals in GNOME 2.x releases. You can always get the latest
+ copy of these templates from <a href="http://developer.gnome.org/projects/gdp/templates.html" target="_top">GDP
+ Documentation Templates</a>.
+ </p>
+<p>
+ Note that this template consists of two files. The first file
+ is an introductory chapter. You should not modify this
+ chapter. The second file is the actual applet document, which
+ you should modify to describe the applet you are documenting.
+ You can name the first file whatever you like, such as
+ <tt>gnome-applets.sgml</tt>. Name the second file
+ according to the applet's name:
+ <tt>
+<i><tt>appletname</tt></i>-applet.sgml</tt>.
+ Make sure you update the entity
+ at the top of the shell document to reflect the new name of
+ the applet document.
+ </p>
+<p>
+ <pre class="programlisting">
+
+<!DOCTYPE book PUBLIC "-//GNOME//DTD DocBook PNG Variant V1.1//EN"[
+<!ENTITY TEMPLATE-APPLET SYSTEM "gnome-applet-template.sgml.part">
+
+]>
+
+<book id="gnome-applets">
+
+ <bookinfo>
+ <title>GNOME Applets</title>
+ <authorgroup>
+ <author><firstname>Telsa</firstname><surname>Gwynne</surname></author>
+ <author><firstname>John</firstname><surname>Fleck</surname></author>
+ <author><firstname>David</firstname><surname>Mason</surname>
+ <affiliation><orgname>Red Hat, Inc.</orgname></affiliation>
+ </author>
+ <author><firstname>Dan</firstname><surname>Mueth</surname></author>
+ <author><firstname>Alexander</firstname><surname>Kirillov</surname></author>
+ </authorgroup>
+ <edition>GNOME Applets version 0.1 for GNOME 1.1.5</edition>
+ <pubdate>2000</pubdate>
+ <copyright>
+ <year>2000</year>
+ <holder>Telsa Gwynne, John Fleck, Red Hat Inc., Dan Mueth, and
+ Alexander Kirillov</holder>
+ </copyright>
+ <legalnotice>
+ <para>
+ Permission is granted to make and distribute verbatim copies of this
+ manual provided the copyright notice and this permission notice are
+ preserved on all copies.
+ </para>
+ <para>
+ Permission is granted to copy and distribute modified versions of
+ this manual under the conditions for verbatim copying, provided that
+ the entire resulting derived work is distributed under the terms of a
+ permission notice identical to this one.
+ </para>
+ <para>
+ Permission is granted to copy and distribute translations of this
+ manual into another language, under the above conditions for modified
+ versions, except that this permission notice may be stated in a
+ translation approved by the Free Software Foundation.
+ </para>
+ <para>
+ Many of the names used by companies to distinguish their products and
+ services are claimed as trademarks. Where those names appear in any
+ GNOME documentation, and those trademarks are made aware to the members
+ of the GNOME Documentation Project, the names have been printed in caps
+ or initial caps.
+ </para>
+ </legalnotice>
+ </bookinfo>
+
+ <!-- #### Introduction ###### -->
+ <chapter id="applets-intro">
+ <title>Introduction</title>
+
+ <!-- #### Intro | What Are Applets? ###### -->
+ <sect1 id="applets-what-are">
+ <title>What Are Applets?</title>
+ <para>
+ Applets are one of the most popular and useful objects you can add
+ to your <interface>Panel</interface> to customize your desktop.
+ An applet is a small application which runs inside a small area of
+ your <interface>Panel</interface>. Applets have been written for
+ a wide range of purposes. Some are very powerful interactive
+ tools, such as the <application>Tasklist</application> Applet
+ which allows you to easily
+ control all of your main applications. Others are simple system
+ monitors, displaying information such as the amount of power left
+ in the battery on your laptop (see <application>Battery Charge
+ Monitor</application>) or weather
+ information(see <application>GNOME Weather</application>). Some
+ are simply for amusement(see <application>Fish</application>).
+ </para>
+
+ <para>
+ Applets are similar to swallowed applications in that both of them
+ reside within the <interface>Panel</interface>. However,
+ swallowed applications are generally applications which were
+ not designed to run within the <interface>Panel</interface>.
+ Typically one will swallow an application which already exists in
+ the main <interface>desktop</interface> area, putting it into your
+ <interface>Panel</interface>. The application will continue to
+ run in the <interface>Panel</interface> until you end the
+ application or unswallow it, placing it back onto the main part of
+ your desktop when you need to.
+ </para>
+
+ <para>
+ <figure id="example-applets-fig">
+ <title>Example Applets</title>
+ <screenshot>
+ <screeninfo>Example Applets</screeninfo>
+ <graphic fileref="example_applets" format="png"
+ srccredit="muet">
+ </graphic>
+ </screenshot>
+ </figure>
+ Several example applets are shown in <xref
+ linkend="example-applets-fig">. From left to right, they are: (1)
+ <application>Mixer Applet</application>, which allows you to turn
+ on/off sound and control its volume by clicking on the applet. (2)
+ <application>Sound Monitor</application> Applet, which displays
+ the current volume of sound being played and allows you to control
+ various sound features. (3) <application>GTCD</application>
+ Applet, a CD player which has all its controls
+ available in the applet and displays the track and time. (4)
+ <application>Drive Mount</application> Applet, used to mount and
+ unmount drives with a single click of the mouse. (5)
+ <application>Desk Guide</application> which allows you to view
+ and control multiple virtual screens. (6)
+ <application>Tasklist</application> Applet which allows you to
+ control your various windows and applications.
+ </para>
+ <para>
+ There are many other applets to choose from. The rest of this
+ chapter will explain the basic information to get you started
+ adding, moving, and removing applets from your
+ <interface>Panels</interface> and using them. The following
+ chapters go through each of the standard GNOME applets describing
+ them in detail. There are also additional applets which can be
+ downloaded off the Web. See <ulink type="http"
+ url="http://www.gnome.org/applist/list-martin.phtml">The GNOME
+ Software Map</ulink> for lists of additional GNOME applications
+ and applets.
+ </para>
+ <para>
+ As you read through the the rest of this chapter, you should try
+ adding and removing applets from your <interface>Panel</interface> and
+ experiment with them freely.
+ </para>
+ </sect1>
+
+ <!-- #### Intro | Adding, Moving, and Removing Applets ###### -->
+ <sect1 id="applet-add-move-replace">
+ <title>Adding, Moving, and Removing Applets</title>
+
+ <sect2 id="adding-applets">
+ <title>Adding Applets to a Panel</title>
+ <para>
+ To add an applet to a <interface>Panel</interface>, right-click
+ on the <interface>Panel</interface> and select
+ <menuchoice><guimenu>Panel</guimenu><guisubmenu>Add to panel</guisubmenu>
+ <guisubmenu>Applet</guisubmenu></menuchoice>. This will show you
+ the menu of all the applets on your system, divided into
+ categories. Choosing any applet from this menu will add it to the
+ <interface>Panel</interface>.
+ </para>
+ </sect2>
+
+ <sect2 id="moving-applets">
+ <title>Moving Applets In or Between Panels</title>
+ <para>
+ It is easy to move applets in a <interface>Panel</interface> or
+ between two <interface>Panels</interface>. If you have a
+ three-button mouse, just move the mouse over the applet, depress
+ the middle mouse button and drag the applet to its new location,
+ releasing the middle mouse button when you are finished. Note
+ that you can drag applets within a <interface>Panel</interface>
+ or between two <interface>Panels</interface> this way. If you
+ don't have a three-button mouse, just
+ right-click on the applet and choose
+ <guimenuitem>Move</guimenuitem>. The cursor will turn into a
+ cross and the applet will move with your mouse until you press
+ any mouse button to indicate you are finished moving it.
+ If, in the course of this movement, it hits
+ other objects, the behavior depends on the global preferences
+ you have set for your <interface>Panels</interface> in the
+ <application>GNOME Control Center</application>: the applet you are
+ moving can switch places with other objects, "push" all objects
+ it meets, or "jump" over all other objects without disturbing
+ them. You can also override the default behavior by holding
+ <keycap>Shift</keycap> button (for "push" mode),
+ <keycap>Ctrl</keycap> (for "switched" mode), or
+ <keycap>Alt</keycap> (for "free" mode, i.e. jumping other other
+ objects without disturbing them) button while dragging.
+ </para>
+ <para>
+ To change the global Panel preferences, right-click on any applet
+ or <interface>Panel</interface> and select
+ <menuchoice>
+ <guimenu>Panel</guimenu>
+ <guimenuitem>Global Preferences...</guimenuitem>
+ </menuchoice>.
+ The <guilabel>Default movement mode</guilabel> is set under the
+ <guilabel>Applets</guilabel> tab.
+ </para>
+ </sect2>
+
+ <sect2 id="removing-applets">
+ <title>Removing Applets from a Panel</title>
+ <para>
+ To remove an applet from a <interface>Panel</interface>,
+ right-click on the applet and select <guimenuitem>Remove from
+ panel...</guimenuitem>.
+ </para>
+ </sect2>
+ </sect1>
+
+
+ <!-- #### Intro | The Right-Click Pop-Up Menu ###### -->
+ <sect1 id="right-click-pop-up-menu">
+ <title>The Right-Click Pop-Up Menu</title>
+ <para>
+ Clicking the right mouse button on any applet brings up
+ a <guimenu>pop-up menu</guimenu>. This
+ menu always has certain standard menu items in it and
+ often has additional items which vary depending on the particular
+ applet.
+ </para>
+ <sect2 id="standard-right-click-items">
+ <title>Standard Pop-Up Items</title>
+ <para>
+ All applets should have the following items in their right-click
+ <guimenu>pop-up menu</guimenu>:
+ <variablelist>
+ <varlistentry>
+ <term>Remove from panel</term>
+ <listitem>
+ <para>
+ The <guimenuitem>Remove from panel</guimenuitem> menu item
+ removes the applet from the <interface>Panel</interface>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Move</term>
+ <listitem>
+ <para>
+ After selecting <guimenuitem>Move</guimenuitem>, your mouse
+ pointer will change appearance (typically to a cross with
+ arrows in each direction). As you move your mouse, the applet
+ will move with it. When you have finished moving the applet,
+ click any mouse button and the applet will anchor in its
+ current position. Note that applets can be moved between two
+ <interface>Panels</interface> this way.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Panel</term>
+ <listitem>
+ <para>
+ The <guisubmenu>Panel</guisubmenu> submenu contains various
+ items and submenus for adding and removing
+ <interface>Panels</interface> and applets and for changing
+ the configuration.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>About</term>
+ <listitem>
+ <para>
+ The <guimenuitem>About...</guimenuitem> menu item brings up a
+ dialogue box containing various information about the applet,
+ typically including the applet's name, version, author,
+ copyright, license and desciption.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Help</term>
+ <listitem>
+ <para>
+ The <guimenuitem>Help</guimenuitem> menu item brings up the help
+ manual for the applet.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+
+ <sect2 id="applet-properties-dialog">
+ <title>The Applet Properties Dialog</title>
+ <para>
+ Many applets have customizable properties. These applets will
+ have a <guimenuitem>Properties...</guimenuitem> menu item in their
+ right-click <guimenu>pop-up menu</guimenu> which brings up the
+ <interface>Properties</interface> dialog where you can alter the
+ appearance or behaviour of the applet.
+ <figure id="example-props-dialog-fig">
+ <title>An Example Applet Properties Dialog</title>
+ <screenshot>
+ <screeninfo>An Example Applets Properties Dialog</screeninfo>
+ <graphic fileref="applet_props_dialog" format="png"
+ srccredit="muet">
+ </graphic>
+ </screenshot>
+ </figure>
+ All <interface>Properties</interface> dialogs have the following
+ buttons at the bottom of the dialog:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guibutton>OK</guibutton> &mdash;
+ Pressing <guibutton>OK</guibutton> will activate any changes
+ in the properties you have made and close the
+ <interface>Properties</interface> dialog.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guibutton>Apply</guibutton> &mdash;
+ Pressing <guibutton>Apply</guibutton> at any time will
+ make your changes active without closing the
+ <interface>Properties</interface> dialog. This is helpful if
+ you would like to test the effects of the changes you have
+ made but may want to continue changing the properties.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guibutton>Close</guibutton> &mdash;
+ Pressing <guibutton>Close</guibutton> will close the
+ <interface>Properties</interface> dialog. Only changes in the
+ configuration which were previously applied with the
+ <guibutton>Apply</guibutton> button will persist. Other
+ changes will not be made active.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guibutton>Help</guibutton> &mdash;
+ Pressing <guibutton>Help</guibutton> brings up the manual for
+ the application, opening it to the page describing the
+ <interface>Properties</interface> dialog.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+
+ <sect2 id="common-right-click-items">
+ <title>Other Common Pop-Up Items</title>
+ <para>
+ Many applets also have one or more of the following items in their
+ right-click pop-up menu:
+ <variablelist>
+ <varlistentry>
+ <term>Run...</term>
+ <listitem>
+ <para>
+ The <guimenuitem>Run...</guimenuitem> menu item generally
+ invokes a program which is related to the applet in some way
+ but which runs in its own window rather than in the
+ panel. For example:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The <application>CPU Load</application> applet, which monitors
+ what programs are running, has a <guimenuitem>Run
+ gtop...</guimenuitem> menu item. Selecting this menu item
+ starts <application>GTop</application>, which allows you to
+ view and control programs which are running.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <application>CD Player</application> applet has a
+ <guimenuitem>Run gtcd...</guimenuitem> menu item which
+ starts the GNOME <application>CD Player</application> when
+ selected, which has more capabilities than the applet.
+ </para>
+ </listitem>
+ </orderedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="feedback">
+ <title>Feedback</title>
+ <sect2 id="reporting-bugs">
+ <title>Reporting Applet Bugs</title>
+ <para>
+ GNOME users are encouraged to report bugs to <ulink type="http"
+ url="http://bugs.gnome.org">The GNOME Bug Tracking
+ System</ulink>. The easiest way to submit bugs is to use the
+ <application>Bug Report Tool</application> program by selecting
+ <menuchoice>
+ <guimenu>Main Menu</guimenu> <guisubmenu>Utilities</guisubmenu>
+ <guimenuitem>Bug Report Tool</guimenuitem>
+ </menuchoice>.
+ Be sure to be complete in describing what you did to cause the
+ bug to surface and, if possible, describe how the developer can
+ reproduce the the scenario.
+ </para>
+ </sect2>
+ <sect2 id="documentation-feedback">
+ <title>Providing Feedback</title>
+ <para>
+ GNOME users are welcome to provide suggestions for how
+ applications and documentation can be improved. Suggestions for
+ application changes should be submitted using the
+ <application>Bug Report Tool</application> discussed above.
+ Suggestions for documentation changes can be emailed directly to
+ the documentation author (whose email should be included in the
+ "Authors" section of the document) or by sending an email to
+ <email>docs@gnome.org</email>.
+ </para>
+ </sect2>
+ <sect2 id="joining-gnome">
+ <title>Joining GNOME</title>
+ <para>
+ GNOME is a community project, created by hundreds of programmers,
+ documentation writers, icon design artists, web masters, and
+ other people, most of whom work on a volunteer basis. New GNOME
+ contributors are always welcome. To join the GNOME team, visit
+ these web sites: developers &mdash; <ulink type="http"
+ url="http://developer.gnome.org">The GNOME Development
+ Site</ulink>, documentation writers &mdash; <ulink type="http"
+ url="http://developer.gnome.org/projects/gdp">The GNOME Documentation
+ Project</ulink>, icon design artists &mdash; <ulink type="http"
+ url="http://gnome-icons.sourceforge.net/">Gnome Icon Web</ulink>,
+ general &mdash; <ulink type="http"
+ url="http://developer.gnome.org/helping/">Helping GNOME</ulink>,
+ or just join the gnome-list email list (see <ulink type="http"
+ url="http://www.gnome.org/resources/mailing-lists.html">GNOME Mailing
+ Lists</ulink>) to discuss what you are interested in doing.
+ </para>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <!-- ############### Template Applets ##################### -->
+ <chapter id="template-applets">
+ <title>Template Applets</title>
+
+ &TEMPLATE-APPLET
+
+ </chapter>
+
+</book>
+
+
+
+
+
+
+
+
+ </pre>
+
+ <pre class="programlisting">
+
+
+ <!-- Please replace everywhere below GNOMEAPPLET with the name of -->
+ <!-- your applet. Most importantly, all id attributes should start -->
+ <!-- with the name of your applet - this is necessary to avoid name -->
+ <!-- conflict among different applets -->
+ <!-- Please replace YOUR-NAME with your name and YOUR-EMAIL with your email-->
+ <!-- Please replace HACKER-NAME with the applet author's name and -->
+ <!-- HACKER-EMAIL with the applet author's email -->
+
+ <!-- You should name your file: GNOMEAPPLET-applet.sgml -->
+ <!-- Screenshots should be in PNG format and placed in the -->
+ <!-- same directory as GNOMEAPPLET-applet.sgml -->
+
+ <!-- Applet docs will be merged into <chapter>'s inside a -->
+ <!-- <book>. Thus, the indentation below (2 spaces before the <sect1>) is -->
+ <!-- correct.-->
+
+ <!-- Permission is granted to make and distribute verbatim copies of -->
+ <!-- this manual provided the copyright notice and this permission -->
+ <!-- notice are preserved on all copies. -->
+ <!-- -->
+ <!-- Permission is granted to copy and distribute modified versions of -->
+ <!-- this manual under the conditions for verbatim copying, provided -->
+ <!-- that the entire resulting derived work is distributed under the -->
+ <!-- terms of a permission notice identical to this one. -->
+ <!-- -->
+ <!-- Permission is granted to copy and distribute translations of this -->
+ <!-- manual into another language, under the above conditions for -->
+ <!-- modified versions, except that this permission notice may be -->
+ <!-- stated in a translation approved by the Foundation. -->
+
+ <!-- ############### GNOMEAPPLET ############### -->
+ <sect1 id="GNOMEAPPLET">
+ <title>GNOMEAPPLET Applet</title>
+
+ <para>
+ <application>GNOMEAPPLET</application> applet, shown in <xref
+ linkend="GNOMEAPPLET-fig">, does this and that. To learn how to
+ add this applet to a <interface>Panel</interface>, see <xref
+ linkend="adding-applets">.
+ </para>
+
+
+ <figure id="GNOMEAPPLET-fig">
+ <title>GNOMEAPPLET</title>
+ <screenshot>
+ <screeninfo>GNOMEAPPLET</screeninfo>
+ <graphic format="png" fileref="GNOMEAPPLET-fig" srccredit="ME">
+ </graphic>
+ </screenshot>
+ </figure>
+
+ <sect2 id="GNOMEAPPLET-usage">
+ <title>Usage</title>
+ <para>
+ This applet does nothing. To use it, just
+ left-click on it and it will instantly do nothing.
+ </para>
+ </sect2>
+
+ <sect2 id="GNOMEAPPLET-right-click">
+ <title>Right-Click Pop-Up Menu Items</title>
+ <para>
+ In addition to the standard menu items (see <xref
+ linkend="standard-right-click-items">), the right-click pop-up menu has
+ the following items:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <guimenuitem>Properties...</guimenuitem> &mdash; This menu
+ item opens the <interface>Properties</interface> dialog (see
+ <xref linkend="GNOMEAPPLET-properties">) which allows you to
+ customize the appearance and behavior of this applet.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <guimenuitem>Run Hello World...</guimenuitem> &mdash; This
+ menu item starts the program <application>Hello
+ World</application>, used to say "hello" to the world.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+
+ <sect2 id="GNOMEAPPLET-properties">
+ <title>Properties</title>
+ <para>
+ You can configure <application>GNOMEAPPLET</application> applet by
+ right-clicking on the applet and choosing the
+ <guimenuitem>Properties...</guimenuitem> menu item. This will open the
+ <interface>Properties</interface> dialog, shown in <xref
+ linkend="GNOMEAPPLET-properties-fig">.
+ </para>
+ <figure id="GNOMEAPPLET-properties-fig">
+ <title>Properties Dialog</title>
+ <screenshot>
+ <screeninfo>Properties Dialog</screeninfo>
+ <graphic format="png" fileref="GNOMEAPPLET-properties" srccredit="ME">
+ </graphic>
+ </screenshot>
+ </figure>
+
+ <para>
+ To change the color of the applet, click on the
+ <guibutton>color</guibutton> button. To change other properties,
+ click on other buttons.
+ </para>
+
+ <para>
+ For more information on the <interface>Properties</interface>
+ dialog, including descriptions of the <guibutton>OK</guibutton>,
+ <guibutton>Apply</guibutton>, <guibutton>Cancel</guibutton>, and
+ <guibutton>Help</guibutton> buttons, see <xref
+ linkend="applet-properties-dialog">.
+ </para>
+ </sect2>
+
+ <sect2 id="GNOMEAPPLET-bugs">
+ <title> Known Bugs and Limitations</title>
+ <para>
+ There are no known bugs in the
+ <application>GNOMEAPPLET</application> applet.
+ </para>
+ </sect2>
+
+ <sect2 id="GNOMEAPPLET-authors">
+ <title>Authors</title>
+ <para>
+ This applet was writen by HACKER-NAME
+ <email>HACKER-EMAIL</email>. The documentation for this applet
+ which you are reading now was written by
+ YOUR-NAME <email>YOUR-EMAIL</email>. For information on submitting
+ bug reports and suggestions for improvements, see <xref
+ linkend="feedback">.
+ </para>
+ </sect2>
+
+ </sect1>
+
+
+
+
+
+
+
+
+</pre>
+ </p>
+</div>
+</div>
+</div></body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html>
+<head>
+<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type">
+<title>the kwrite handbook</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.29">
+<meta name="keywords" content="kde, kwrite, text, editor">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" id="id2815529">
+<div class="titlepage">
+<div><h1 class="title">
+<a name="id2815529"></a>the kwrite handbook</h1></div>
+<div>
+<h3 class="author">thad mcginnis</h3>
+<div class="affiliation"><pre class="address"><tt><<a href="mailto:ctmcginnis@compuserve.com">ctmcginnis@compuserve.com</a>></tt></pre></div>
+<h3 class="othercredit">jochen wilhelmy</h3>
+<div class="affiliation"><pre class="address"><tt><<a href="mailto:digisnap@cs.tu-berlin.de">digisnap@cs.tu-berlin.de</a>></tt></pre></div>
+<h3 class="othercredit">glen parker</h3>
+<div class="affiliation"><pre class="address"><tt><<a href="mailto:glenebob@nwlink.com">glenebob@nwlink.com</a>></tt></pre></div>
+<h3 class="othercredit">michael koch</h3>
+<div class="affiliation"><pre class="address"><tt><<a href="mailto:koch@kde.org">koch@kde.org</a>></tt></pre></div>
+<h3 class="othercredit">christian tibirna</h3>
+<div class="affiliation"><pre class="address"><tt><<a href="mailto:tibirna@kde.org">tibirna@kde.org</a>></tt></pre></div>
+<h3 class="othercredit">lauri watts</h3>
+<div class="affiliation"><pre class="address"><tt><<a href="mailto:vampyr@atconnex.net">vampyr@atconnex.net</a>></tt></pre></div>
+</div>
+<div><span class="releaseinfo">2.00.00<br>
+</span></div>
+<div><p class="copyright">Copyright © 2000, 2001 by thad mcginnis</p></div>
+<div><div class="legalnotice"><p>permission is granted to copy, distribute and/or modify this
+document under the terms of the gnu free documentation license,
+version 1.1 or any later version published by the free software
+foundation; with no invariant sections, with no front-cover texts, and
+with no back-cover texts. a copy of the license is included in <a href="#gnu-fdl">the section entitled gnu free documentation license</a>.</p></div></div>
+<div><div class="abstract">
+<p>
+<a name="id2719526"></a>
+<b>Abstract</b>
+</p>
+<p>this handbook describes kwrite version 2.0</p>
+<p>kwrite is a text editor for kde 2.0</p>
+</div></div>
+<hr>
+</div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt>1. <a href="#introduction">introduction</a>
+</dt>
+<dt>2. <a href="#on-screen-fundamentals">some fundamentals</a>
+</dt>
+<dd><dl>
+<dt> <a href="#drag-and-drop">drag and drop</a>
+</dt>
+<dt> <a href="#command-line-options">command line options</a>
+</dt>
+<dd><dl>
+<dt> <a href="#specify-a-file">specify a file</a>
+</dt>
+<dt> <a href="#editing-files-on-the-internet">specify a file on the internet</a>
+</dt>
+<dt> <a href="#other-command-line-options">other command line options</a>
+</dt>
+</dl></dd>
+<dt> <a href="#keybindings">key bindings</a>
+</dt>
+</dl></dd>
+<dt>3. <a href="#the-menu-entries">the menu entries</a>
+</dt>
+<dd><dl>
+<dt> <a href="#file">the file menu</a>
+</dt>
+<dt> <a href="#edit">the edit menu</a>
+</dt>
+<dt> <a href="#go">the go menu</a>
+</dt>
+<dt> <a href="#tools">the tools menu</a>
+</dt>
+<dt> <a href="#settings">the settings menu</a>
+</dt>
+<dt> <a href="#help">the help menu</a>
+</dt>
+</dl></dd>
+<dt>4. <a href="#pref-dialog">configure kwrite</a>
+</dt>
+<dd><dl>
+<dt> <a href="#prefcolors">colors</a>
+</dt>
+<dt> <a href="#pref-indent">indent</a>
+</dt>
+<dt> <a href="#pref-select">select</a>
+</dt>
+<dt> <a href="#pref-edit">edit</a>
+</dt>
+<dt> <a href="#prefspellchecker">spelling</a>
+</dt>
+</dl></dd>
+<dt>5. <a href="#pref-highlighting">highlighting</a>
+</dt>
+<dt>6. <a href="#credits">credits and licenses</a>
+</dt>
+<dt>A. <a href="#installation">installation</a>
+</dt>
+</dl>
+</div>
+<div id="introduction" class="chapter">
+<div class="titlepage"><div><h2 class="title">
+<a name="introduction"></a>Chapter 1. introduction</h2></div></div>
+<p>kwrite is more than a text editor for the kde desktop. it is meant
+to be a programmer's editor, and could be considered as at least a partial
+alternative to more powerful editors. it may be best used in conjunction
+with konqueror for source file browsing for
+different languages. kwrite also works very well as a simple text editor.
+one of kwrite's main features is the colorized syntax, customized for
+many different programming languages such as: c/c++, java, python, perl,
+bash, modula 2, html, and ada.</p>
+</div>
+<div id="on-screen-fundamentals" class="chapter">
+<div class="titlepage"><div><h2 class="title">
+<a name="on-screen-fundamentals"></a>Chapter 2. some fundamentals</h2></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt> <a href="#drag-and-drop">drag and drop</a>
+</dt>
+<dt> <a href="#command-line-options">command line options</a>
+</dt>
+<dd><dl>
+<dt> <a href="#specify-a-file">specify a file</a>
+</dt>
+<dt> <a href="#editing-files-on-the-internet">specify a file on the internet</a>
+</dt>
+<dt> <a href="#other-command-line-options">other command line options</a>
+</dt>
+</dl></dd>
+<dt> <a href="#keybindings">key bindings</a>
+</dt>
+</dl>
+</div>
+<p>kwrite is very simple to use. anyone that has used a text editor should
+have no problems. </p>
+<div class="sect1">
+<a name="drag-and-drop"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="drag-and-drop"></a>
+<span class="title">drag and drop</span>
+</h2></div></div>
+<p>kwrite uses the kde drag and drop protocol. files may be dragged
+and dropped onto kwrite from the desktop,
+konqueror or some remote ftp site opened in one
+of konqueror's windows. </p>
+</div>
+<div class="sect1">
+<a name="command-line-options"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="command-line-options"></a>
+<span class="title">command line options</span>
+</h2></div></div>
+<p>though kwrite may most often be started from the kde program menu,
+or a desktop icon, it can also be opened at the command line prompt of a
+terminal window. there are a few useful options that are available when
+doing this.</p>
+<div class="sect2">
+<a name="specify-a-file"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="specify-a-file"></a>
+<span class="title">specify a file</span>
+</h3></div></div>
+<p>by specifying the path and name of a particular file the user can
+have kwrite open (or create) that file immediately upon startup. this
+option might look something like the following:</p>
+<div class="informalexample" id="id2720012">
+<p>
+<a name="id2720012"></a>
+<pre class="screen">
+<tt>%</tt> <b><tt>
+<b>kwrite</b> <tt><i><tt>/home/myhome/docs/myfile.txt</tt></i></tt>
+</tt></b>
+</pre>
+<p>
+</div>
+</div>
+<div class="sect2">
+<a name="editing-files-on-the-internet"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="editing-files-on-the-internet"></a>
+<span class="title">specify a file on the internet</span>
+</h3></div></div>
+<p>the above-mentioned method could even be used to open files on the
+internet (if the user has an active connection at the time.) an example of
+this might look like the following:</p>
+<div class="informalexample" id="id2720100">
+<p>
+<a name="id2720100"></a>
+<pre class="screen">
+<tt>%</tt> <b><tt>
+<b>kwrite</b> <tt><i><tt>ftp://ftp.kde.org/pub/kde/welcome.msg</tt></i></tt>
+</tt></b>
+</pre>
+<p>
+</div>
+</div>
+<div class="sect2">
+<a name="other-command-line-options"></a>
+<div class="titlepage"><div><h3 class="title">
+<a name="other-command-line-options"></a>
+<span class="title">other command line options</span>
+</h3></div></div>
+<p>the following command line help options are available</p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2720189"></a>
+<span class="term"><b><tt>
+<b>kwrite</b> <tt>--help</tt>
+</tt></b></span>
+</dt>
+<dd><p>
+<a name="id2720216"></a>this lists the most basic options available at the command
+line.</p></dd>
+<dt>
+<a name="id2720232"></a>
+<span class="term"><b><tt>
+<b>kwrite</b> <tt>--help-qt</tt>
+</tt></b></span>
+</dt>
+<dd><p>
+<a name="id2720260"></a>this lists the options available for changing the way
+kwrite interacts with qt.</p></dd>
+<dt>
+<a name="id2720291"></a>
+<span class="term"><b><tt>
+<b>kwrite</b> <tt>--help-kde</tt>
+</tt></b></span>
+</dt>
+<dd><p>
+<a name="id2720318"></a>this lists the options available for changing the way
+kwrite interacts with kde.</p></dd>
+<dt>
+<a name="id2720345"></a>
+<span class="term"><b><tt>
+<b>kwrite</b> <tt>--help-all</tt>
+</tt></b></span>
+</dt>
+<dd><p>
+<a name="id2720372"></a>this lists all of the command line options.</p></dd>
+<dt>
+<a name="id2720389"></a>
+<span class="term"><b><tt>
+<b>kwrite</b> <tt>--author</tt>
+</tt></b></span>
+</dt>
+<dd><p>
+<a name="id2720416"></a>lists kwrite's authors in the terminal window</p></dd>
+<dt>
+<a name="id2720442"></a>
+<span class="term"><b><tt>
+<b>kwrite</b> <tt>--version</tt>
+</tt></b></span>
+</dt>
+<dd><p>
+<a name="id2720469"></a>lists version information for qt, kde, and kwrite. also available through <b><tt>
+<b>kwrite</b> <tt>-v</tt>
+</tt></b> </p></dd>
+</dl></div>
+</div>
+</div>
+<div class="sect1">
+<a name="keybindings"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="keybindings"></a>
+<span class="title">key bindings</span>
+</h2></div></div>
+<p>many of the key bindings (shortcuts) are configurable by way of the <a href="#settings">settings</a> menu. by default kwrite honors the
+following key bindings.</p>
+<div class="informaltable" id="id2719795">
+<p>
+<a name="id2719795"></a>
+<table border="1">
+<colgroup>
+<col>
+<col>
+</colgroup>
+<tbody>
+<tr>
+<td><p>insert</p></td>
+<td><p> toggle between insert and overwrite mode. when in insert mode the
+editor will add any typed characters to the text while pushing along any data to
+the right of the text cursor. overwrite mode causes the entry of each character
+to eliminate the character immediately to the right of the text
+cursor.</p></td>
+</tr>
+<tr>
+<td><p>left arrow</p></td>
+<td><p>move the cursor one character to the left </p></td>
+</tr>
+<tr>
+<td><p>right arrow</p></td>
+<td><p> move the cursor one character to the right </p></td>
+</tr>
+<tr>
+<td><p>up arrow</p></td>
+<td><p> move the cursor up one line </p></td>
+</tr>
+<tr>
+<td><p>down arrow</p></td>
+<td><p> move the cursor down one line </p></td>
+</tr>
+<tr>
+<td><p>page up</p></td>
+<td><p> move the cursor up one page </p></td>
+</tr>
+<tr>
+<td><p>page down</p></td>
+<td><p>move the cursor down one page </p></td>
+</tr>
+<tr>
+<td><p>backspace</p></td>
+<td><p> delete the character to the left of the cursor </p></td>
+</tr>
+<tr>
+<td><p>home</p></td>
+<td><p> move the cursor to the beginning of the line </p></td>
+</tr>
+<tr>
+<td><p>end</p></td>
+<td><p> move the cursor to the end of the line </p></td>
+</tr>
+<tr>
+<td><p>delete</p></td>
+<td><p>delete the character to the right of the cursor (or any selected
+text)</p></td>
+</tr>
+<tr>
+<td><p>shift-left arrow</p></td>
+<td><p> mark text one character to the left </p></td>
+</tr>
+<tr>
+<td><p>shift-right arrow</p></td>
+<td><p> mark text one character to the right </p></td>
+</tr>
+<tr>
+<td><p>f1</p></td>
+<td><p> help</p></td>
+</tr>
+<tr>
+<td><p>shift-f1</p></td>
+<td><p><a href="#whats-this">what's this?</a></p></td>
+</tr>
+<tr>
+<td><p>ctrl-f</p></td>
+<td><p><a href="#find"> find</a></p></td>
+</tr>
+<tr>
+<td><p>f3</p></td>
+<td><p><a href="#find-again"> find again</a></p></td>
+</tr>
+<tr>
+<td><p>ctrl-c</p></td>
+<td><p> copy the marked text to the clipboard. </p></td>
+</tr>
+<tr>
+<td><p>ctrl-m</p></td>
+<td><p>set a bookmark</p></td>
+</tr>
+<tr>
+<td><p>ctrl-n</p></td>
+<td><p> <a href="#new">new</a> document</p></td>
+</tr>
+<tr>
+<td><p>ctrl-p</p></td>
+<td><p>
+<a href="#print">print</a> </p></td>
+</tr>
+<tr>
+<td><p>ctrl-q</p></td>
+<td><p>quit - close active copy of editor </p></td>
+</tr>
+<tr>
+<td><p>ctrl-r</p></td>
+<td><p><a href="#replace"> replace</a></p></td>
+</tr>
+<tr>
+<td><p>ctrl-s</p></td>
+<td><p>invokes the <a href="#save">save</a> command.</p></td>
+</tr>
+<tr>
+<td><p>ctrl-v</p></td>
+<td><p> paste the clipboard text into line edit. </p></td>
+</tr>
+<tr>
+<td><p>ctrl-x</p></td>
+<td><p>delete the marked text and copy it to the clipboard. </p></td>
+</tr>
+<tr>
+<td><p>ctrl-z</p></td>
+<td><p><a href="#undo">undo</a></p></td>
+</tr>
+<tr>
+<td><p>ctrl-shift-z</p></td>
+<td><p><a href="#redo">redo</a></p></td>
+</tr>
+</tbody>
+</table>
+<p>
+</div>
+</div>
+</div>
+<div id="the-menu-entries" class="chapter">
+<div class="titlepage"><div><h2 class="title">
+<a name="the-menu-entries"></a>Chapter 3. the menu entries</h2></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt> <a href="#file">the file menu</a>
+</dt>
+<dt> <a href="#edit">the edit menu</a>
+</dt>
+<dt> <a href="#go">the go menu</a>
+</dt>
+<dt> <a href="#tools">the tools menu</a>
+</dt>
+<dt> <a href="#settings">the settings menu</a>
+</dt>
+<dt> <a href="#help">the help menu</a>
+</dt>
+</dl>
+</div>
+<div class="sect1">
+<a name="file"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="file"></a>
+<span class="title">the file menu</span>
+</h2></div></div>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2842287"></a>
+<span class="term">
+<a name="new"></a>file->new (<b>ctrl-n</b>)</span>
+</dt>
+<dd><p>
+<a name="id2842372"></a>this starts a new document in the editor. if there is a current
+document with unsaved changes the user is given a chance to save it.</p></dd>
+<dt>
+<a name="id2842392"></a>
+<span class="term">
+<a name="open"></a>file->0pen (<b>ctrl-o</b>)</span>
+</dt>
+<dd>
+<p>
+<a name="id2842477"></a>this command opens a file. it does this by means of a dialog box
+which allows the user to navigate the file system. the dialog operates
+like a small file manager. clicking on directories displayed in the
+central window directs the dialog to enter that directory - displaying its
+contents. there is an entry/dropdown box which can be used to type in
+directly the location and name of the file or by clicking the arrow at the
+side choose from a dropdown list of recently used locations. below this is
+a filter which similarly may have data entered directly or chosen from a
+dropdown list of recent filter types. the filter facility lets only files
+that meet its specifications be displayed in the central window. if the
+filter contained text such as <tt>*.txt</tt> then only files
+with the txt extension would be visible in the selection window. below the filter
+is a status bar giving information about the number of files and subdirectories
+within the current directory.</p>
+<p>the toolbar, which is located at the top of the dialog, has left and right
+arrow buttons that let the user move back and forth through previously selected
+directories as well as an up arrow button for moving up the directory tree. the
+button with the little house takes the user to his or her home directory and the one
+with the two arrows curved in on each other updates the view of the current
+directory. the flag button lets the user set a new bookmark at the current directory
+or go to one that was previously set.
+ the last button on the toolbar allows you to create a new
+directory, and finally there is dropdown box with a list of some commonly
+frequented directories.</p>
+</dd>
+<dt>
+<a name="id2842547"></a>
+<span class="term">
+<a name="open-recent"></a>file->open
+recent</span>
+</dt>
+<dd><p>
+<a name="id2842603"></a>this is a shortcut to open recently saved documents. clicking on
+this item opens a list to the side of the menu with several of the most recently
+saved files. clicking on a specific file will open it in kwrite - if the file
+still resides at the same location. </p></dd>
+<dt>
+<a name="id2842633"></a>
+<span class="term">
+<a name="save"></a>file->save (<b>ctrl-s</b>)</span>
+</dt>
+<dd><p>
+<a name="id2842718"></a>this saves the current document. if there has already been a
+save of the document then this will overwrite the previously saved file without
+asking for the user's consent. if it is the first save of a new document the
+save as dialog (described below) will be invoked.</p></dd>
+<dt>
+<a name="id2842741"></a>
+<span class="term">
+<a name="save-as"></a>file->save
+as</span>
+</dt>
+<dd><p>
+<a name="id2842798"></a>this allows a document to be saved with a new file name. this is
+done by means of the file dialog box described above in the <a href="#open">open</a> section of this help file.</p></dd>
+<dt>
+<a name="id2842838"></a>
+<span class="term">
+<a name="print"></a>file->print (<b>ctrl-p</b>)</span>
+</dt>
+<dd><p>
+<a name="id2842923"></a>opens a simple print dialog allowing the user to specify what, where, and how to print</p></dd>
+<dt>
+<a name="id2842942"></a>
+<span class="term">
+<a name="new-window"></a>file->new window</span>
+</dt>
+<dd><p>
+<a name="id2842999"></a>this creates a new window, i.e. a new instance of kwrite. in this way the user can easily work
+on more than one file at a time with kwrite.</p></dd>
+<dt>
+<a name="id2843042"></a>
+<span class="term">
+<a name="new-view"></a>file->new view</span>
+</dt>
+<dd><p>
+<a name="id2843098"></a>this creates a new view of the current document, i.e., a new instance of
+kwrite (as explained in the previous entry) but containing the same
+document.</p></dd>
+<dt>
+<a name="id2843134"></a>
+<span class="term">
+<a name="close"></a>file->quit (<b>ctrl-q</b>)</span>
+</dt>
+<dd><p>
+<a name="id2843219"></a>this will close the editor window, if you have more than one
+instance of kwrite running, through the new view or
+new window menu items, those instances will not be
+closed.</p></dd>
+</dl></div>
+</div>
+<div class="sect1">
+<a name="edit"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="edit"></a>
+<span class="title">the edit menu</span>
+</h2></div></div>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2843304"></a>
+<span class="term">
+<a name="undo"></a>edit->undo (<b>ctrl-z</b>)</span>
+</dt>
+<dd><p>
+<a name="id2843389"></a>this is used to eliminate or reverse the most recent user action or operation. just what
+constitutes such an action may be better understood by referring to the <a href="#group-undos">group undos</a> portion of this help file.</p></dd>
+<dt>
+<a name="id2843430"></a>
+<span class="term">
+<a name="redo"></a>edit->redo (<b>ctrl-shift-z</b>)</span>
+</dt>
+<dd><p>
+<a name="id2843526"></a>this will reverse the most recent change (if any) made using undo</p></dd>
+<dt>
+<a name="id2843545"></a>
+<span class="term">
+<a name="undohistory"></a>edit->undo/redo history</span>
+</dt>
+<dd><p>
+<a name="id2843601"></a>this will call a display box showing a list of the most recent actions on
+the left and another list of actions which have been 'undone' on the right.
+there are also three buttons at the right of the box labeled
+undo, redo, and
+close. clicking on the undo
+button will cause the action at the top of the undo list to be reversed which
+will place that particular action at the top of the redo list. likewise,
+clicking on the redo button will reinstate the reversed
+action and move it back to the top of the undo list. clicking on an item below
+the top item in either list will select all the items from the top down to that
+point. a subsequent click on the corresponding button will cause all the
+selected actions to be undone or redone accordingly. this would be particularly
+useful when the user knows precisely the point to which she or he would like to
+proceed - making it unnecessary to go through a series of single undo or redo
+actions.</p></dd>
+<dt>
+<a name="id2843686"></a>
+<span class="term">
+<a name="cut"></a>edit->cut (<b>ctrl-x</b>)</span>
+</dt>
+<dd><p>
+<a name="id2843773"></a>this command deletes the current selection and places it on the clipboard. the
+clipboard is a feature of kde that works invisibly to provide a way to transfer data between
+applications.</p></dd>
+<dt>
+<a name="id2843794"></a>
+<span class="term">
+<a name="copy"></a>edit->copy (<b>ctrl-c</b>)</span>
+</dt>
+<dd><p>
+<a name="id2843879"></a>this copies the currently selected text to the clipboard so that it may be
+pasted elsewhere. the clipboard is a feature of kde that works invisibly to
+provide a way to transfer data between applications.</p></dd>
+<dt>
+<a name="id2843901"></a>
+<span class="term">
+<a name="paste"></a>edit->paste (<b>ctrl-v</b>)</span>
+</dt>
+<dd><p>
+<a name="id2843986"></a>this will insert the contents of the clipboard at the cursor position. the
+clipboard is feature of kde that works invisibly to provide a way to transfer
+data between applications.</p></dd>
+<dt>
+<a name="id2844007"></a>
+<span class="term">
+<a name="select-all"></a>edit->select all (<b>ctrl-a</b>)</span>
+</dt>
+<dd><p>
+<a name="id2844095"></a>this will select the entire document. this could be very useful for
+copying the entire file to another application.</p></dd>
+<dt>
+<a name="id2844115"></a>
+<span class="term">
+<a name="invert-the-selection"></a>edit->invert selection</span>
+</dt>
+<dd><p>
+<a name="id2844173"></a>this selects any unselected text while unselecting any selected text -
+effectively reversing the current state of selection.</p></dd>
+<dt>
+<a name="id2844193"></a>
+<span class="term">
+<a name="find"></a>edit->find (<b>ctrl-f</b>)</span>
+</dt>
+<dd><p>
+<a name="id2844278"></a>this opens the find dialog which is used to specify the text to
+find in the document. there is small text box for entering the search
+pattern which also doubles as a dropdown box. clicking on the dropdown arrow at
+the side of the box makes available other recent search patterns. other
+parameters are included to make the search more efficient. selecting
+case sensitive will limit finds to entries that match the
+case (upper or lower) of each of the characters in the search
+pattern. find backwards directs the search to proceed in an
+upwardly direction. the selected text option keeps the
+search within currently selected text. checking whole words
+only prevents the search from stopping on words that contain the
+searched for pattern. the search from cursor option begins
+the search from the current position of the cursor within the document rather
+than from the beginning.</p></dd>
+<dt>
+<a name="id2844358"></a>
+<span class="term">
+<a name="find-again"></a>edit->find next (<b>f3</b>)</span>
+</dt>
+<dd><p>
+<a name="id2844438"></a>this repeats the last find operation, if any, without calling the find
+dialog box.</p></dd>
+<dt>
+<a name="id2844458"></a>
+<span class="term">
+<a name="replace"></a>edit->replace (<b>ctrl-r</b>)</span>
+</dt>
+<dd><p>
+<a name="id2844543"></a>this command opens the replace dialog box. the replace dialog is
+almost identical to the above-mentioned find dialog. in addition to the features in
+the find dialog it contains a replace with: text
+entry/dropdown box. using this dialog the user can specify both the text to be found
+and text with which to replace it. the additional prompt
+on replace option allows the user to have kwrite ask for
+confirmation before each replacement.</p></dd>
+<dt>
+<a name="id2844592"></a>
+<span class="term">
+<a name="insertfile"></a>
+edit->insert file</span>
+</dt>
+<dd><p>
+<a name="id2844649"></a>this opens the file <a href="#open">open</a> dialog box whereby the
+user can insert a complete file in the open document. the the contents of
+the file will be entered at the position of the blinking text
+cursor.</p></dd>
+</dl></div>
+</div>
+<div class="sect1">
+<a name="go"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="go"></a>
+<span class="title">the go menu</span>
+</h2></div></div>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2844744"></a>
+<span class="term">
+<a name="go-to-line"></a>go->go to line</span>
+</dt>
+<dd><p>
+<a name="id2844798"></a>this opens the goto line dialog box which is used to have the cursor jump
+to a particular line (specified by number) in the document. the line number may
+be entered directly into the text box or graphically by clicking on the up or
+down arrow spin controls at the side of the text box. the little up arrow will
+increase the line number and the down arrow decrease it. there is also a slide
+control to the right of the text box which allows the user to move the goto
+point in the document in an analog manner.</p></dd>
+<dt>
+<a name="id2844826"></a>
+<span class="term">
+<a name="add-marker"></a>go->add marker (<b>ctrl-m</b>)</span>
+</dt>
+<dd>
+<p>
+<a name="id2844911"></a>this creates a marker in the document at the line where the cursor is
+located and places it at the bottom of the list of markers located at the
+bottom of the go menu.</p>
+<p>markers are points within a kwrite document
+marked for easy return. if the user thinks (s)he may need to return to a specific
+point (s)he may by way of this feature instruct kwrite to remember it. </p>
+</dd>
+<dt>
+<a name="id2844958"></a>
+<span class="term">
+<a name="set-bookmark"></a>go->set marker</span>
+</dt>
+<dd><p>
+<a name="id2845013"></a>this creates a marker in the document at the line where the cursor is
+located, and allows the user to choose its position in the list of bookmarks
+which is appended at the bottom of this menu item.</p></dd>
+<dt>
+<a name="id2845034"></a>
+<span class="term">
+<a name="clear-bookmarks"></a>go->clear markers</span>
+</dt>
+<dd><p>
+<a name="id2845089"></a>this command will remove all the markers from the docucument as well as the
+list of markers which is appended at the bottom of this menu item.</p></dd>
+</dl></div>
+<p>at the bottom of this menu, a list of markers appears if any
+markers are available for this window.</p>
+</div>
+<div class="sect1">
+<a name="tools"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="tools"></a>
+<span class="title">the tools menu</span>
+</h2></div></div>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2845160"></a>
+<span class="term">
+<a name="spelling..."></a>tools->spelling...</span>
+</dt>
+<dd>
+<p>
+<a name="id2845215"></a>this initiates the spell checking program - a program
+designed to help the user catch and correct any spelling errors.
+clicking on this entry will start the checker and bring up the speller dialog
+box through which the user can control the process. there are three text boxes
+lined up vertically in the center of the dialog with their corresponding labels
+just to the left. starting at the top they are:</p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2845249"></a>
+<span class="term">misspelled word:</span>
+</dt>
+<dd><p>
+<a name="id2845266"></a>here, the spell checker indicates the word currently under
+consideration. this happens when the checker encounters a word not in its
+dictionary - a file containing a list of correctly spelled words against which
+it compares each word in the editor.</p></dd>
+<dt>
+<a name="id2845288"></a>
+<span class="term">replacement:</span>
+</dt>
+<dd><p>
+<a name="id2845305"></a> if the checker has any similar words in its dictionary the
+first one will be listed here. the user can accept the suggestion, type in his
+or her own correction, or choose a different suggestion from the next
+box.</p></dd>
+<dt>
+<a name="id2845327"></a>
+<span class="term">suggestions:</span>
+</dt>
+<dd><p>
+<a name="id2845344"></a> the checker may list here a number of possible replacements for
+the word under consideration. clicking on any one of the suggestions will cause
+that word to be entered in the replacement: box,
+above.</p></dd>
+</dl></div>
+<p>on the right side of the dialog box are 6 buttons that allow the user to
+control the spell check process. they are:</p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2845392"></a>
+<span class="term">replace</span>
+</dt>
+<dd><p>
+<a name="id2845408"></a> this button has the checker replace the word under
+consideration in the document with the word in the
+replacement: box.</p></dd>
+<dt>
+<a name="id2845436"></a>
+<span class="term">replace all</span>
+</dt>
+<dd><p>
+<a name="id2845453"></a> this button causes the checker to replace not only the current
+misspelled word: but to automatically make the same
+substitution for any other occurences of this misspelled
+word: in the document.</p></dd>
+<dt>
+<a name="id2845489"></a>
+<span class="term">ignore</span>
+</dt>
+<dd><p>
+<a name="id2845506"></a>activating this button will have the checker move on without
+making any changes.</p></dd>
+<dt>
+<a name="id2845525"></a>
+<span class="term">ignore all</span>
+</dt>
+<dd>
+<p>
+<a name="id2845542"></a> this button tells the checker to do nothing with the current
+misspelled word: and to pass over any other instances of
+the same word.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2845566">Note</a></h3>
+<p>this only applies to the current spell check
+run. if the checker is run again later it will stop on this same
+word.</p>
+</div>
+</dd>
+<dt>
+<a name="id2845587"></a>
+<span class="term">add</span>
+</dt>
+<dd><p>
+<a name="id2845604"></a>pressing this button adds the word in the misspelled
+word: box to the checker's dictionary. this means that in the future
+the checker will always consider this word to be correctly
+spelled.</p></dd>
+<dt>
+<a name="id2845633"></a>
+<span class="term">stop</span>
+</dt>
+<dd><p>
+<a name="id2845650"></a> this button stops the spell check process.</p></dd>
+</dl></div>
+<p>located horizontally along the bottom of the spell check dialog is a
+progress bar. as the checking process proceeds the bar will fill from left to
+right providing a graphical representation of how far along in the document the
+process has reached. in addition, the progress is displayed numerically in
+the center of the progress bar.</p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2845684">Note</a></h3>
+<p>a numerical display of the spell check
+process is simultaneously displayed in the status bar of the editor. the <a href="#show-statusbar">status bar</a> is the horizontal strip at the bottom
+of the editor just outside of the text entry area.</p>
+</div>
+<p>two more buttons are located below the progress bar. they are:</p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2845739"></a>
+<span class="term">help</span>
+</dt>
+<dd><p>
+<a name="id2845756"></a> this invokes the kde help system starting at the kwrite help
+pages (this document).</p></dd>
+<dt>
+<a name="id2845783"></a>
+<span class="term">cancel</span>
+</dt>
+<dd><p>
+<a name="id2845799"></a> this button cancels the spell check process.</p></dd>
+<dt>
+<a name="id2845818"></a>
+<span class="term">
+<a name="indent"></a>tools->indent</span>
+</dt>
+<dd><p>
+<a name="id2845862"></a>this increases the paragraph's indentation by one step. the size of the
+step depends on the <a href="#pref-indent"> indentation
+settings</a>.</p></dd>
+<dt>
+<a name="id2845902"></a>
+<span class="term">
+<a name="unindent"></a>tools->unindent</span>
+</dt>
+<dd><p>
+<a name="id2845946"></a>this reduces the paragraph's indentation by one step. the size of the step
+depends on the <a href="#pref-indent"> indentation settings</a>.</p></dd>
+<dt>
+<a name="id2845982"></a>
+<span class="term">
+<a name="cleanindent"></a>tools->clean
+indentation</span>
+</dt>
+<dd><p>
+<a name="id2846026"></a>not yet implemented</p></dd>
+<dt>
+<a name="id2846044"></a>
+<span class="term">tools->comment</span>
+</dt>
+<dd><p>
+<a name="id2846077"></a>this adds one space to the beginning of the line
+where the text cursor is located or to the beginning of any
+selected lines.</p></dd>
+<dt>
+<a name="id2846097"></a>
+<span class="term">tools->uncomment</span>
+</dt>
+<dd><p>
+<a name="id2846129"></a>this removes one space (if any exist) from the beginning of the line
+where the text cursor is located or from the beginning of any
+selected lines.</p></dd>
+</dl></div>
+</dd>
+</dl></div>
+</div>
+<div class="sect1">
+<a name="settings"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="settings"></a>
+<span class="title">the settings menu</span>
+</h2></div></div>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2846196"></a>
+<span class="term">
+<a name="show-toolbar"></a>settings->show toolbar</span>
+</dt>
+<dd><p>
+<a name="id2846254"></a>when checked, this displays a movable toolbar containing buttons used to
+initiate frequently used commands. when unchecked the toolbar is hidden.</p></dd>
+<dt>
+<a name="id2846274"></a>
+<span class="term">
+<a name="show-statusbar"></a>settings->show statusbar</span>
+</dt>
+<dd><p>
+<a name="id2846332"></a>when checked, this displays a small bar at the bottom of the editor
+containing information about the status of the current document. when unchecked
+the statusbar is hidden.</p></dd>
+<dt>
+<a name="id2846353"></a>
+<span class="term">
+<a name="show-path"></a>settings->show path</span>
+</dt>
+<dd><p>
+<a name="id2846410"></a>when selected, this displays in the title bar the path (its location in the
+file system) of the current document. when unchecked the path is hidden.</p></dd>
+<dt>
+<a name="id2846431"></a>
+<span class="term">
+<a name="configure-keybindings"></a>settings->configure key bindings</span>
+</dt>
+<dd><p>
+<a name="id2846489"></a>this command opens a dialog box whereby the <a href="#keybindings">key bindings</a> may be changed. a display window at
+the top of the dialog box shows the list of commands (actions) that can have
+keyboard shortcuts. below the display are three radio buttons. the user may choose
+between no key, default key, and custom key. (note that a set of radio buttons only
+allows the selection of one of the offered items - in the way that buttons on a car
+radio only offer the selection of one preset station. also, the default key
+selection is only available for those commands that actually have a 'default'
+shortcut.) selecting the custom key option activates the three check boxes and key
+button at the bottom of the dialog. the user may then select a key
+combination for the command in question by means of the check boxes and key
+button. for example, with the about kde command selected in the display window,
+the user could select <b>ctrl</b> and <b>alt</b>, click on
+the key button, and then press the <b>k</b> key on the keyboard. this
+would mean that anytime he or she held down the <b>ctrl</b> and
+<b>alt</b> buttons and pressed <b>k</b> (while using
+kwrite) the about kde display box would be called. </p></dd>
+<dt>
+<a name="id2846603"></a>
+<span class="term">
+<a name="configure-toolbars"></a>settings->configure toolbars</span>
+</dt>
+<dd><p>
+<a name="id2846661"></a>this will open the dialog whereby the toolbar configuration may
+be changed. the user can choose which shortcut buttons should appear on the
+toolbar. a display window on the left lists the commands available to placed
+on the toolbar. a display on the right lists those commands already on the
+toolbar. a set of four arrow buttons between the two displays manipulates the
+selections. the right pointing arrow places any command selected in the left
+pane onto the right pane, i.e., it is added to the toolbar.
+the left arrow does just the opposite, removing any action selected in the right
+window from the toolbar. the up and down pointing arrows change the position of
+an action selected in the right window which changes the position of its button
+in the toolbar.</p></dd>
+<dt>
+<a name="id2846701"></a>
+<span class="term">
+<a name="preferences"></a>settings->preferences</span>
+</dt>
+<dd><p>
+<a name="id2846756"></a>this menu item opens a dialog whereby several different <a href="#pref-dialog">settings</a> may be adjusted.</p></dd>
+<dt>
+<a name="id2846795"></a>
+<span class="term">settings->configure
+highlighting</span>
+</dt>
+<dd><p>
+<a name="id2846841"></a>opens a dialog box allowing configuration of the syntax
+highlighting. the dialog is described in <a href="#pref-highlighting">Chapter 5., <i>highlighting</i></a>.</p></dd>
+<dt>
+<a name="id2846878"></a>
+<span class="term">
+<a name="vertical-selection"></a>settings->vertical
+selection</span>
+</dt>
+<dd><p>
+<a name="id2846933"></a>this is used to turn on or off the vertical selection feature. vertical
+selection allows text to be selected by column as well as by row. in other
+words with this feature the user is able to select text contained in only
+particular contiguous columns and rows. in affect the user can select a
+rectangular area of text anywhere in the document.</p></dd>
+<dt>
+<a name="id2846958"></a>
+<span class="term">
+<a name="set-highlight"></a>settings->highlight mode</span>
+</dt>
+<dd><p>
+<a name="id2847012"></a>this allows the user to choose the style of color highlighting which the
+editor uses to display the text. the styles are selected by programming
+language. the font/color information is not stored with the document.</p></dd>
+<dt>
+<a name="id2847034"></a>
+<span class="term">
+<a name="end-of-line"></a>settings->end of line</span>
+</dt>
+<dd><p>
+<a name="id2847089"></a>this opens a sub-menu from which the user can select the type of `end of
+line' code for kwrite to use, i.e., the accepted standard
+used by unix, mac® or msdos/windows® systems.</p></dd>
+</dl></div>
+</div>
+<div class="sect1">
+<a name="help"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="help"></a>
+<span class="title">the help menu</span>
+</h2></div></div>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2847199"></a>
+<span class="term">
+<a name="contents"></a>help->contents (<b>f1</b>)</span>
+</dt>
+<dd><p>
+<a name="id2847276"></a>this invokes the kde help system starting at the kwrite help pages (this document).</p></dd>
+<dt>
+<a name="id2847303"></a>
+<span class="term">
+<a name="whats-this"></a>help->what's this? (<b>shift-f1</b>)</span>
+</dt>
+<dd><p>
+<a name="id2847391"></a>this changes the mouse cursor to a combination arrow and question mark.
+clicking on items within kwrite with this arrow will open a help window (if
+one exists for the particular item) explaining the item's function.</p></dd>
+<dt>
+<a name="id2847420"></a>
+<span class="term">
+<a name="report-bug"></a>help->report bug</span>
+</dt>
+<dd><p>
+<a name="id2847474"></a>this calls a dialog box to help
+the user help the kde team to track down and solve any
+problems(bugs) in the program. the dialog attempts to do this by
+means of email using the information given by the user.</p></dd>
+<dt>
+<a name="id2847498"></a>
+<span class="term">
+<a name="about-kwrite"></a>help->about kwrite</span>
+</dt>
+<dd><p>
+<a name="id2847553"></a>this will display version and author information</p></dd>
+<dt>
+<a name="id2847571"></a>
+<span class="term">
+<a name="about-kde"></a>help->about kde</span>
+</dt>
+<dd><p>
+<a name="id2847628"></a>this displays the kde version and other basic information.</p></dd>
+</dl></div>
+</div>
+</div>
+<div id="pref-dialog" class="chapter">
+<div class="titlepage"><div><h2 class="title">
+<a name="pref-dialog"></a>Chapter 4. configure kwrite</h2></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt> <a href="#prefcolors">colors</a>
+</dt>
+<dt> <a href="#pref-indent">indent</a>
+</dt>
+<dt> <a href="#pref-select">select</a>
+</dt>
+<dt> <a href="#pref-edit">edit</a>
+</dt>
+<dt> <a href="#prefspellchecker">spelling</a>
+</dt>
+</dl>
+</div>
+<p>selecting
+settings->configure
+kwrite from the menu brings up the configure-kwrite
+dialog box. this dialog can be used to alter a number of different settings. the
+settings available for change vary according to which category the user chooses from
+a vertical list on the left side of the dialog. by means of three buttons
+along the bottom of the box the user can control the process. she or he may invoke
+the help system, accept the current settings and close the
+dialog by means of the ok button, or
+cancel the process. the categories
+colors, indent,
+select, edit, and
+spelling are detailed below.</p>
+<div class="sect1">
+<a name="prefcolors"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="prefcolors"></a>
+<span class="title">colors</span>
+</h2></div></div>
+<p>this section provides access to <a href="#pref-color-settings">five different color settings</a>,
+described below. each of these settings may be changed by clicking on its
+corresponding button. these are special wide buttons that are the color of
+the current setting. clicking on one of the buttons calls a special color
+dialog box used to change the setting.</p>
+<p>the color dialog box provides a convenient and graphical way to
+select a color. in the upper left of the box is a rectangular display of a
+spectrum of colors. to the immediate right of this, is vertical bar
+displaying a range of intensity from the most dark at the bottom to the
+most light at the top. the user may select and adjust a color by clicking
+in these two boxes. clicking in the rectangular display selects a
+particular mix of red, green, and blue colors and in the vertical bar
+selects a level of intensity (value). the various color attributes are displayed
+in numerical form in small text boxes located directly below the spectral
+rectangle and the user can see them change as the color is adjusted. these
+attributes include the mix of the basic color components (red, green, and
+blue) as well as hue and saturation levels. alternatively the user can
+enter figures directly in these boxes. there is also a square at the
+bottom center of the dialog box which displays the color which is under
+consideration at any time. to the right of this display is another text
+box labeled html: this shows the user the color code
+that would be used to specify the particular displayed color in
+html code which is widely used for web pages.</p>
+<p>in addition to the above, the color dialog allows the capture of any
+color currently displayed on the desktop or in another program. clicking
+on the button with the dropper icon (located on the right side of the
+dialog box,) changes the shape of the mouse cursor to a set of crosshairs.
+clicking again will pick up the color attributes of whatever color is
+displayed under the cross hairs.</p>
+<p>furthermore the user has the option of adding any color to a personal
+palette of “custom colors” by clicking on the wide button labeled
+add to custom colors (which is located directly above the
+display square.) this adds the current color to the custom color palette. this
+palette and any other available palettes can be displayed using the drop down
+selection box located directly above the palette display at the top right of the
+dialog box. besides the custom colors, the user can access a number of
+pre-prepared palettes.</p>
+<div class="variablelist"><dl>
+<dt>
+<a name="pref-color-settings"></a>
+<span class="term">background</span>
+</dt>
+<dd><p>
+<a name="id2847970"></a>here the user can specify a color for the general background of
+kwrite.</p></dd>
+<dt>
+<a name="id2847996"></a>
+<span class="term">text background</span>
+</dt>
+<dd><p>
+<a name="id2848014"></a>this is used to set a particular color to display in the
+background of those areas of the document containing text.</p></dd>
+<dt>
+<a name="id2848033"></a>
+<span class="term">selected</span>
+</dt>
+<dd><p>
+<a name="id2848050"></a>this allows the user to select a color to be used for indicating
+selected (or highlighted) portions of the document.</p></dd>
+<dt>
+<a name="id2848070"></a>
+<span class="term">found</span>
+</dt>
+<dd><p>
+<a name="id2848087"></a>this specifies the preferred color with which to mark text
+encountered as the result of a <a href="#find">find</a>
+operation.</p></dd>
+<dt>
+<a name="id2848123"></a>
+<span class="term">selected + found</span>
+</dt>
+<dd><p>
+<a name="id2848140"></a>this sets the color for text that has not only been found as in
+the previous entry above but that has also been selected.</p></dd>
+</dl></div>
+</div>
+<div class="sect1">
+<a name="pref-indent"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="pref-indent"></a>
+<span class="title">indent</span>
+</h2></div></div>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2848192"></a>
+<span class="term">auto indent</span>
+</dt>
+<dd><p>
+<a name="id2848209"></a>this causes
+new lines to begin with the same indentation level as the previous
+line.</p></dd>
+<dt>
+<a name="id2848228"></a>
+<span class="term">indent with spaces</span>
+</dt>
+<dd><p>
+<a name="id2848245"></a>this
+replaces tabs with the number of spaces selected in the tab width window in
+the <a href="#pref-edit">edit</a> section of the preferences
+dialog.</p></dd>
+<dt>
+<a name="id2848284"></a>
+<span class="term">backspace key indents</span>
+</dt>
+<dd><p>
+<a name="id2848302"></a>this allows the
+backspace key to be used to
+indent.</p></dd>
+<dt>
+<a name="id2848336"></a>
+<span class="term">tab key indents</span>
+</dt>
+<dd><p>
+<a name="id2848353"></a>this
+allows the tab key to be used to
+indent.</p></dd>
+<dt>
+<a name="id2848387"></a>
+<span class="term">keep indent profile</span>
+</dt>
+<dd><p>
+<a name="id2848404"></a>this
+retains current indentation settings for future documents.</p></dd>
+<dt>
+<a name="id2848423"></a>
+<span class="term">keep extra spaces</span>
+</dt>
+<dd><p>
+<a name="id2848440"></a>indentations of more than the selected number of spaces
+will not be shortened.</p></dd>
+</dl></div>
+</div>
+<div class="sect1">
+<a name="pref-select"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="pref-select"></a>
+<span class="title">select</span>
+</h2></div></div>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2848492"></a>
+<span class="term">persistent selections</span>
+</dt>
+<dd>
+<p>
+<a name="id2848509"></a>this prevents key input or cursor movement by way of the
+arrow keys from causing the elimination of text
+selection. </p>
+<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title"><a name="id2848525">Note</a></h3>
+<p>(note: if the overwrite selections option is
+activated then any typed character input or paste operation will replace
+the selected text.)</p>
+</div>
+</dd>
+<dt>
+<a name="id2848547"></a>
+<span class="term">overwrite selections</span>
+</dt>
+<dd><p>
+<a name="id2848565"></a>any keyed character input or paste operation will replace
+the selected text. </p></dd>
+<dt>
+<a name="id2848584"></a>
+<span class="term">mouse autocopy</span>
+</dt>
+<dd><p>
+<a name="id2848601"></a>any text
+selected with the mouse will be automatically copied to the
+clipboard.</p></dd>
+<dt>
+<a name="id2848620"></a>
+<span class="term">x11-like single selection</span>
+</dt>
+<dd><p>
+<a name="id2848637"></a>not implemented yet.</p></dd>
+<dt>
+<a name="id2848655"></a>
+<span class="term">vertical selections</span>
+</dt>
+<dd><p>
+<a name="id2848672"></a>this
+activates the <a href="#vertical-selection">vertical selection</a>
+option.</p></dd>
+<dt>
+<a name="id2848711"></a>
+<span class="term">toggle old</span>
+</dt>
+<dd><p>
+<a name="id2848725"></a>not yet implemented</p></dd>
+</dl></div>
+</div>
+<div class="sect1">
+<a name="pref-edit"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="pref-edit"></a>
+<span class="title">edit</span>
+</h2></div></div>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2848775"></a>
+<span class="term">word wrap</span>
+</dt>
+<dd><p>
+<a name="id2848802"></a>word wrap is a feature that causes the editor to
+automatically start a new line of text and move (wrap) the cursor to the
+beginning of that new line. kwrite will automatically start a new line of text
+when the current line reaches the length specified by the <a href="#pref-wrap-words-at">wrap words at:</a>
+option.</p></dd>
+<dt>
+<a name="id2848852"></a>
+<span class="term">wrap words
+at:</span>
+</dt>
+<dd><p>
+<a name="id2848878"></a>if the <a href="#pref-word-wrap">word wrap</a> option is selected this entry
+determines the length (in characters) at which the editor will
+automatically start a new line.</p></dd>
+<dt>
+<a name="id2848918"></a>
+<span class="term">replace tabs by
+spaces</span>
+</dt>
+<dd><p>
+<a name="id2848945"></a>kwrite will replace any tabs
+with the number of spaces indicated in the <a href="#pref-tab-width">tab width:</a> entry.</p></dd>
+<dt>
+<a name="id2848989"></a>
+<span class="term">tab width</span>
+</dt>
+<dd><p>
+<a name="id2849014"></a>if the <a href="#pref-word-wrap">replace tabs by spaces</a>
+option is selected this entry determines the number of spaces with which
+the editor will automatically replace tabs.</p></dd>
+<dt>
+<a name="id2849053"></a>
+<span class="term">remove trailing spaces</span>
+</dt>
+<dd><p>
+<a name="id2849070"></a>kwrite will automatically eliminate extra spaces at the
+ends of lines of text.</p></dd>
+<dt>
+<a name="id2849094"></a>
+<span class="term">auto brackets</span>
+</dt>
+<dd><p>
+<a name="id2849111"></a>when the
+user types a left bracket ([,(, or {) kwrite automatically
+enters the right bracket (}, ), or ]) to the right of the
+cursor.</p></dd>
+<dt>
+<a name="id2849139"></a>
+<span class="term">group undos</span>
+</dt>
+<dd>
+<p>
+<a name="id2849165"></a>groups of similar actions are to be considered a single
+<a href="#undo">undo</a> step by kwrite. in other words, a series
+of regular character keystrokes (words or expressions) would be considered
+one step and therefore be removed by a single undo operation. if the
+series of character entries were interrupted by a non-character entry
+operation (such as a backspace), invoking undo would only remove the
+entries made since that operation. the next undo would then reverse that
+operation and so on.</p>
+<p> when this option is not selected kwrite considers
+each keystroke to be a single step. so if the user (with this option
+active) were to type several words or even sentences without having to make
+corrections or cut or paste or some other non-character entry operation
+then a click of the undo button would eliminate all that had been typed
+since the last non-entry operation. a second click would eliminate that
+operation and a third any operation or series of entries that occurred
+before the operation and so on. when not selected three clicks of the undo
+button would only remove the last three letters typed, or the last three
+operations.</p>
+</dd>
+<dt>
+<a name="id2849243"></a>
+<span class="term">show tabs</span>
+</dt>
+<dd><p>
+<a name="id2849260"></a>the editor will display a symbol to indicate the presence
+of a tab in the text.</p></dd>
+<dt>
+<a name="id2849279"></a>
+<span class="term">smart home</span>
+</dt>
+<dd><p>
+<a name="id2849296"></a>not yet implemented</p></dd>
+<dt>
+<a name="id2849314"></a>
+<span class="term">page up/down moves cursor</span>
+</dt>
+<dd><p>
+<a name="id2849331"></a>this option changes the behavior of the cursor when
+the user presses the <b>page up</b> or <b>page down</b> key. if
+unselected the text cursor will maintain its relative position within the visible
+text in kwrite as new text becomes visible as a result of the operation. so if
+the cursor is in the middle of the visible text when the operation occurs it will
+remain there (except when one reaches the beginning or end.) with this
+option selected, the first key press will cause the cursor to move to either the top
+or bottom of the visible text as a new page of text is displayed.</p></dd>
+<dt>
+<a name="id2849382"></a>
+<span class="term">wrap cursor</span>
+</dt>
+<dd><p>
+<a name="id2849396"></a>when this option is chosen, moving
+the cursor with the arrow keys off the end of a line (to the right) causes
+it to jump down to the beginning of the next line. likewise when the
+cursor is moved past the beginning of a line (to the left) it jumps up to
+the end of the preceding line. when this option is not selected, moving the
+cursor right past the end of a line merely causes it to continue
+horizontally in the same line and trying to move it left past the beginning
+does nothing.</p></dd>
+<dt>
+<a name="id2849423"></a>
+<span class="term">
+<a href="#undo">undo</a> steps:</span>
+</dt>
+<dd><p>
+<a name="id2849451"></a>here
+the user may specify the number of steps kwrite will retain in memory for
+purposes of undoing entries and actions. this means that the higher the
+number of steps set the more memory kwrite will use for this. setting
+this entry to 10 would mean that the user would be be able reverse the last
+ten operations, i.e.i>, click the undo
+button 10 times and obtain results.</p></dd>
+</dl></div>
+</div>
+<div class="sect1">
+<a name="prefspellchecker"></a>
+<div class="titlepage"><div><h2 class="title" style="clear: all">
+<a name="prefspellchecker"></a>
+<span class="title">spelling</span>
+</h2></div></div>
+<p>a spell checker is a program designed to
+help the user catch and correct any spelling errors. this section of the
+preferences dialog allows certain important settings to be adjusted in this
+regard.</p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2849551"></a>
+<span class="term">create root/affix combinations not in
+dictionary</span>
+</dt>
+<dd><p>
+<a name="id2849569"></a>selecting this option allows
+the spell checker to register as 'correct' combinations of root words with
+suffixes or prefixes even if the particular combination is not listed in
+its dictionary data base of words.</p></dd>
+<dt>
+<a name="id2849590"></a>
+<span class="term">consider run-together words as spelling
+errors</span>
+</dt>
+<dd><p>
+<a name="id2849608"></a>selecting this will cause the
+spell checker to register as 'misspelled' two or more correctly spelled
+words that are 'run-together', i.e., that do not have spaces
+separating them.</p></dd>
+<dt>
+<a name="id2849637"></a>
+<span class="term">dictionary:</span>
+</dt>
+<dd><p>
+<a name="id2849653"></a>depending on
+the user's installation one or more different language spelling
+dictionaries may be available. this drop down box allows the user to
+choose which language the spell checker should use.</p></dd>
+<dt>
+<a name="id2849675"></a>
+<span class="term">encoding:</span>
+</dt>
+<dd><p>
+<a name="id2849692"></a>there are
+different coding systems used to associate particular codes with particular
+characters and symbols. if the user knows which code he or she is using
+this drop down box allows this code to be specified so that the spell
+checker can do its job correctly. </p></dd>
+<dt>
+<a name="id2849714"></a>
+<span class="term">client:</span>
+</dt>
+<dd><p>
+<a name="id2849731"></a>since kwrite
+does not contain its own spell checker, an external one must be chosen.
+this is where the user may specify which spell check program to
+use.</p></dd>
+</dl></div>
+</div>
+</div>
+<div id="pref-highlighting" class="chapter">
+<div class="titlepage"><div><h2 class="title">
+<a name="pref-highlighting"></a>Chapter 5. highlighting</h2></div></div>
+<p>the configure highlighting dialog consists of two
+pages, defaults and highlighting
+modes. the user can select which page to view by clicking on the
+appropriate tab at the top of the dialog</p>
+<p>items available on the defaults page are as
+follows:</p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2849846"></a>
+<span class="term">default item styles</span>
+</dt>
+<dd>
+<p>
+<a name="id2849863"></a>the user can configure the default appearance for particular items.
+this would allow a programmer to more easily identify different items (types of
+entries) in his or her code.
+
+</p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2849887"></a>
+<span class="term">item</span>
+</dt>
+<dd><p>
+<a name="id2849904"></a>this drop down list offers a variety of items that the user
+might want to highlight. they include normal for
+text does not fit in any of the other categories, comment,
+string, keyword and many more. not
+all of these entries will need to be configured for every language and so may be
+selected as needed. the options in the rest of this section apply
+to the entry selected in this box.</p></dd>
+<dt>
+<a name="id2849959"></a>
+<span class="term">normal</span>
+</dt>
+<dd><p>
+<a name="id2849976"></a>this allows the user to choose the item's normal
+(unselected) color. this is done by means of a color selection
+dialog box, a further explanation of which may be found in the <a href="#prefcolors">colors</a> section of <a href="#pref-dialog">configure kwrite</a>.</p></dd>
+<dt>
+<a name="id2850032"></a>
+<span class="term">bold</span>
+</dt>
+<dd><p>
+<a name="id2850049"></a>this option determines whether or not the item should be displayed in
+bold text.</p></dd>
+<dt>
+<a name="id2850068"></a>
+<span class="term">italic</span>
+</dt>
+<dd><p>
+<a name="id2850085"></a>this option determines whether or not the item should be displayed in italic
+text.</p></dd>
+<dt>
+<a name="id2850104"></a>
+<span class="term">selected</span>
+</dt>
+<dd><p>
+<a name="id2850121"></a>this allows the user to choose the item's color
+when selected. this is done by means of a color selection
+dialog box, a further explanation of which may be found in the <a href="#prefcolors">colors</a> section of <a href="#pref-dialog">configure kwrite</a>.</p></dd>
+</dl></div>
+</dd>
+<dt>
+<a name="id2850178"></a>
+<span class="term">default font</span>
+</dt>
+<dd>
+<p>
+<a name="id2850196"></a>here the user can choose the default font for all
+text.</p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2850217"></a>
+<span class="term">family</span>
+</dt>
+<dd><p>
+<a name="id2850234"></a>this is used to choose the font family. the default is fixed.
+for most programming purposes, a monospaced font (one in which a w takes up the same
+amount of space as an i) may be the best choice.</p></dd>
+<dt>
+<a name="id2850256"></a>
+<span class="term">size</span>
+</dt>
+<dd><p>
+<a name="id2850272"></a>the font size can be changed here. the default is 12
+points.</p></dd>
+<dt>
+<a name="id2850291"></a>
+<span class="term">charset</span>
+</dt>
+<dd><p>
+<a name="id2850308"></a>here the user can choose which character set to work in.</p></dd>
+</dl></div>
+</dd>
+</dl></div>
+<p>items on the highlight modes tab allow the user to define
+more specific highlighting depending on the language style.</p>
+<p>one need not set every available option, items not configured
+specifically will use the default configuration specified on the previous
+(defaults tab.</p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2850376"></a>
+<span class="term">config select</span>
+</dt>
+<dd>
+<p>
+<a name="id2850393"></a>this group of options is used to customize the highlighting styles
+for each programming language type. any changes you made in
+other areas of this dialog apply only to this type.</p>
+<div class="variablelist"><dl>
+<dt>
+<a name="id2850417"></a>
+<span class="term">highlight</span>
+</dt>
+<dd><p>
+<a name="id2850434"></a>this is used to choose the language type to
+configure</p></dd>
+<dt>
+<a name="id2850452"></a>
+<span class="term">item</span>
+</dt>
+<dd><p>
+<a name="id2850469"></a>this is to choose the syntax item to configure. remember
+this only configures <i>this</i> item for <i>this</i>
+language.</p></dd>
+</dl></div>
+<p>as an example, if the user wished to configure the appearance of
+“comments” while writing c++, she or he could choose c++ in the
+highlight drop down list, and then choose comment in the
+item drop down list. to have “comments” look
+the same across all languages, the user would need to configure this in the
+defaults page of this dialog box while leaving
+“comments” unconfigured within the more specific
+highlight modes page.</p>
+</dd>
+<dt>
+<a name="id2850578"></a>
+<span class="term">item style</span>
+</dt>
+<dd><p>
+<a name="id2850594"></a>here the user can configure the general appearance of the above
+selected item. checking the default checkbox causes the default
+style as configured on the previous tab to be set, or the
+appearance can be configured directly. the available options are the same as on the
+defaults tab: normal,
+selected, bold and
+italic.</p></dd>
+<dt>
+<a name="id2850664"></a>
+<span class="term">highlight auto select</span>
+</dt>
+<dd><p>
+<a name="id2850681"></a>kwrite can apply syntax highlighting automatically, depending
+on the file extension or mime-type of the opened file. the defaults are fairly
+comprehensive, but users that regularly edit files with non-standard extensions
+can add them here. wildcards are allowed in the file
+extensions text box. for example, the default entry for the c++
+language is <b><tt>*.cpp;*.cc;*.c;*.h</tt></b>. opening a file called
+<tt>foo.h</tt> would automatically apply the c++ style to it.</p></dd>
+<dt>
+<a name="id2850740"></a>
+<span class="term">item font</span>
+</dt>
+<dd>
+<p>
+<a name="id2850757"></a>here the user can choose the font for the selected item.</p>
+<p>the default style can be applied by checking the
+default checkbox or the user can choose a specific font
+family, size and
+charset. the available options are the same as those on
+the defaults tab.</p>
+</dd>
+</dl></div>
+</div>
+<div id="credits" class="chapter">
+<div class="titlepage"><div><h2 class="title">
+<a name="credits"></a>Chapter 6. credits and licenses</h2></div></div>
+<p>kwrite copyright 2000 by jochen wilhelmy
+<tt><<a href="mailto:digisnap@cs.tu-berlin.de">digisnap@cs.tu-berlin.de</a>></tt>
+</p>
+<p>contributions:</p>
+<div class="itemizedlist"><ul>
+<li><p>
+<a name="id2850886"></a>additional contributions by glen parker <tt><<a href="mailto:glenebob@nwlink.com">glenebob@nwlink.com</a>></tt>
+</p></li>
+<li><p>
+<a name="id2850908"></a>michael koch <tt><<a href="mailto:koch@kde.org">koch@kde.org</a>></tt>
+</p></li>
+</ul></div>
+<p>documentation by thad mcginnis <tt><<a href="mailto:ctmcginnis@compuserve.com">ctmcginnis@compuserve.com</a>></tt>
+</p>
+<div class="itemizedlist"><ul><li><p>
+<a name="id2850951"></a>this version of the kwrite handbook is based on the original by cristian tibirna <tt><<a href="mailto:tibirna@kde.org">tibirna@kde.org</a>></tt>
+</p></li></ul></div>
+<p>converted to docbook/proofreading by lauri watts <tt><<a href="mailto:vampyr@atconnex.net">vampyr@atconnex.net</a>></tt>
+</p>
+<p>
+<a name="gnu-fdl"></a>this documentation is licensed under the terms of the <a href="common/fdl-license.html" target="_top">gnu free documentation
+license</a>.</p>
+<p>this program is licensed under the terms of the <a href="common/gpl-translated.html" target="_top">gnu general public license</a>.</p>
+</div>
+<div id="installation" class="appendix">
+<div class="titlepage"><div><h2 class="title">
+<a name="installation"></a>Appendix A. installation</h2></div></div>
+<p>kwrite is packaged as part of the kdebase package. for more information
+on installing and compiling kde please see <a href="http://www.kde.org" target="_top">www.kde.org</a>.</p>
+</div>
+</div></body>
+</html>
--- /dev/null
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "../dtd/4.1.2/docbookx.dtd" [
+<!ENTITY version "1.0.53">
+<!ENTITY mdash "--">
+<!ENTITY hellip "...">
+ <!-- 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 ouput, 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 seperate from the main window
+ section. Since they were both so closely involved with the main
+ window, I decided to have them as sect3's isntead. Judgement
+ call. -->
+
+ <sect3 id="proving">
+ <title>Proving a Theorem</title>
+ <para>
+ To get a proof of a theorem, select
+ <menuchoice>
+ <guisubmenu>File</guisubmenu>
+ <guimenuitem>New</guimenuitem>
+ </menuchoice>,
+ which will
+ bring up the <interface>New Proof</interface> dialog box.
+ Enter the statement of the theorem in the
+ <guilabel>Theorem statement</guilabel> field, select your
+ desired proof type from the drop-down menu, and and press
+ <guibutton>Prove!</guibutton>.
+ </para>
+ <para>
+ If <application>MY-GNOME-APP</application> cannot prove the
+ theorem by the method you have chosen, or if you have not
+ selected a proof type at all,
+ <application>MY-GNOME-APP</application> will attempt to
+ choose the one that it thinks is most conclusive. In order,
+ it will attempt to prove the theorem with the following techniques:
+
+ <variablelist>
+ <varlistentry>
+ <term>Deduction</term>
+ <listitem>
+ <para>
+ This is a proof method that is generally accepted
+ for full credit by Logic professors.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Induction</term>
+ <listitem>
+ <para>
+ This logical style will also earn you full credit on
+ your homework.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Dialog</term>
+ <listitem>
+ <para>
+ This logical method is best for Philosophy classes,
+ and will probably only merit partial credit on Logic
+ or Mathematics homework.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Confusion</term>
+ <listitem>
+ <para>
+ Suitable only for political debates, battles of wits
+ against the unarmed, and Philosophy classes focusing
+ on the works of Kant. Use with caution.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <!-- You might want to include a note, warning, or tip, e.g. -->
+
+ <warning>
+ <title>Proving Incorrect Theorms</title>
+ <para>
+ <application>MY-GNOME-APP</application> cannot prove
+ incorrect theorems. If the theorem you have entered is not
+ demonstrably true, you will get a message to that effect
+ in the main window. To disprove a theorem, ask
+ <application>MY-GNOME-APP</application> to prove its
+ logical inverse.
+ </para>
+ </warning>
+ </sect3>
+ <sect3 id="editing">
+ <title>Editing Proofs</title>
+ <para>
+ Once you have proven the theorem, it will be displayed in
+ the <interface>main window</interface>. There, you can read
+ it over, choose text styles for different portions of it,
+ and make comments on it. This section will guide you through
+ that process.
+ </para>
+ <para>
+ To alter text styles, first select the statement you wish to
+ change by clicking on it once. You can select several
+ statements by Then, choose the style you want to apply from
+ the <guisubmenu>Style</guisubmenu> submenu of the
+ <guimenu>Edit</guimenu> menu.
+ <application>MY-GNOME-APP</application> will convert the
+ text to that style.
+ </para>
+ <para>
+ You can also enter comments on a statement by selecting that
+ statement, and then beginning to type. Comments will appear
+ after the statement you have selected.
+ </para>
+
+ <note>
+ <title>Altering The Proofs Themselves</title>
+ <para>
+ <application>MY-GNOME-APP</application> does not allow you
+ to alter a proof it has produced itself. You can, save
+ your proof as a plain text file (using the
+ <guimenuitem>Save as...</guimenuitem> menu), and alter it
+ that way. Be aware, however, that
+ <application>MY-GNOME-APP</application> uses its own file
+ format for saved proofs, and cannot re-open a file unless
+ it is in the .mga format.
+ </para>
+ </note>
+ </sect3>
+
+
+ <!-- If there are other functions performed from the main window,
+ they belong here. -->
+
+ </sect2>
+
+ <!-- =========================================================
+ Additional Sect2's should describe additional windows, such as
+ larger dialog boxes, or functionality that differs significantly
+ from the most immediate functions of the application. Make the
+ structure logical.
+ ============================================================= -->
+
+
+ <sect2 id="toolbar">
+ <title>Toolbar</title>
+ <para>
+ The toolbar (shown in <xref linkend="figure-usage-toolbar">)
+ provides access to several commonly used routines.
+ <figure id="figure-usage-toolbar">
+ <title>MY-GNOME-APP Toolbar</title>
+ <screenshot>
+ <screeninfo>MY-GNOME-APP Toolbar</screeninfo>
+ <graphic fileref="usage-toolbar.png" format="png"></graphic>
+ </screenshot>
+ </figure>
+ <variablelist>
+ <varlistentry>
+ <term>New</term>
+ <listitem>
+ <para>
+ Brings up the <interface>New Theorem</interface>
+ dialog.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Open</term>
+ <listitem>
+ <para>
+ Open an exisiting theorem you want to prove, or a
+ completed proof you wish to print or format.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Save</term>
+ <listitem>
+ <para>
+ Save the current theorem permanently in a
+ file.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </sect2>
+ <!-- ========= Menus =========================== -->
+
+ <sect2 id="menubar">
+
+ <!-- Describing the menubar ensures comprehensive feature
+ coverage. Nest itemizedlists inside variablelists so that each
+ menu is easily located by indexing software. Proper indentation
+ makes it easier! -->
+
+ <title>Menus</title>
+ <para>
+ The menu bar, located at the top of the <interface>Main
+ Window</interface>, contains the following menus:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><guimenu>File</guimenu></term>
+ <listitem>
+ <para>
+ This menu contains:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <menuchoice>
+ <shortcut>
+ <keycap>F3</keycap>
+ </shortcut>
+ <guimenuitem>Open</guimenuitem>
+ </menuchoice>
+ — 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>
--- /dev/null
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.0//EN"
+ "../dtd/4.0/docbookx.dtd">
+<book lang="en">
+<bookinfo>
+<title>the <application>kwrite</application> handbook</title>
+<authorgroup>
+<author>
+<firstname>thad</firstname>
+<surname>mcginnis</surname>
+<affiliation>
+<address><email>ctmcginnis@compuserve.com</email></address>
+</affiliation>
+</author>
+<othercredit role="developer">
+<firstname>jochen</firstname>
+<surname>wilhelmy</surname>
+<contrib>principal developer</contrib>
+<affiliation>
+<address><email>digisnap@cs.tu-berlin.de</email></address>
+</affiliation>
+</othercredit>
+<othercredit role="developer">
+<firstname>glen</firstname>
+<surname>parker</surname>
+<contrib>additional development</contrib>
+<affiliation>
+<address><email>glenebob@nwlink.com</email></address>
+</affiliation>
+</othercredit>
+<othercredit role="developer">
+<firstname>michael</firstname>
+<surname>koch</surname>
+<contrib>additional development</contrib>
+<affiliation>
+<address><email>koch@kde.org</email></address>
+</affiliation>
+</othercredit>
+<othercredit role="developer">
+<firstname>christian</firstname>
+<surname>tibirna</surname>
+<contrib>original help document</contrib>
+<affiliation>
+<address><email>tibirna@kde.org</email></address>
+</affiliation>
+</othercredit>
+<othercredit role="reviewer">
+<firstname>lauri</firstname>
+<surname>watts</surname>
+<contrib>reviewer</contrib>
+<affiliation>
+<address><email>vampyr@atconnex.net</email></address>
+</affiliation>
+</othercredit>
+</authorgroup>
+<copyright>
+<year>2000</year>
+<year>2001</year>
+<holder>thad mcginnis</holder>
+</copyright>
+<legalnotice>
+<para>permission is granted to copy, distribute and/or modify this
+document under the terms of the gnu free documentation license,
+version 1.1 or any later version published by the free software
+foundation; with no invariant sections, with no front-cover texts, and
+with no back-cover texts. a copy of the license is included in <xref linkend="gnu-fdl"/>.</para>
+</legalnotice>
+<date>15/02/2001</date>
+<releaseinfo>2.00.00</releaseinfo>
+<abstract>
+<para>this handbook describes <application>kwrite</application> version 2.0</para>
+<para><application>kwrite</application> is a text editor for kde 2.0</para>
+</abstract>
+<keywordset>
+<keyword>kde</keyword>
+<keyword>kwrite</keyword>
+<keyword>text</keyword>
+<keyword>editor</keyword>
+</keywordset>
+</bookinfo>
+<chapter id="introduction">
+<title>introduction</title>
+<para><application>kwrite</application> is more than a text editor for the kde desktop. it is meant
+to be a programmer's editor, and could be considered as at least a partial
+alternative to more powerful editors. it may be best used in conjunction
+with <application>konqueror</application> for source file browsing for
+different languages. <application>kwrite</application> also works very well as a simple text editor.
+one of <application>kwrite</application>'s main features is the colorized syntax, customized for
+many different programming languages such as: c/c++, <trademark>java</trademark>, python, perl,
+bash, modula 2, <acronym>html</acronym>, and ada.</para>
+</chapter>
+<chapter id="on-screen-fundamentals">
+<title>some fundamentals</title>
+<para><application>kwrite</application> is very simple to use. anyone that has used a text editor should
+have no problems. </para>
+<sect1 id="drag-and-drop">
+<title>drag and drop</title>
+<para><application>kwrite</application> uses the kde drag and drop protocol. files may be dragged
+and dropped onto <application>kwrite</application> from the desktop,
+<application>konqueror</application> or some remote ftp site opened in one
+of <application>konqueror</application>'s windows. </para>
+</sect1>
+<sect1 id="command-line-options">
+<title>command line options</title>
+<para>though <application>kwrite</application> may most often be started from the kde program menu,
+or a desktop icon, it can also be opened at the command line prompt of a
+terminal window. there are a few useful options that are available when
+doing this.</para>
+<sect2 id="specify-a-file">
+<title>specify a file</title>
+<para>by specifying the path and name of a particular file the user can
+have <application>kwrite</application> open (or create) that file immediately upon startup. this
+option might look something like the following:</para>
+<informalexample>
+<screen><prompt>%</prompt> <userinput><command>kwrite</command> <option><replaceable>/home/myhome/docs/myfile.txt</replaceable></option></userinput></screen>
+</informalexample>
+</sect2>
+<sect2 id="editing-files-on-the-internet">
+<title>specify a file on the internet</title>
+<para>the above-mentioned method could even be used to open files on the
+internet (if the user has an active connection at the time.) an example of
+this might look like the following:</para>
+<informalexample>
+<screen><prompt>%</prompt> <userinput><command>kwrite</command> <option><replaceable>ftp://ftp.kde.org/pub/kde/welcome.msg</replaceable></option></userinput></screen>
+</informalexample>
+</sect2>
+<sect2 id="other-command-line-options">
+<title>other command line options</title>
+<para>the following command line help options are available</para>
+<variablelist>
+<varlistentry>
+<term><userinput><command>kwrite</command> <option>--help</option></userinput></term>
+<listitem>
+<para>this lists the most basic options available at the command
+line.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><userinput><command>kwrite</command> <option>--help-qt</option></userinput></term>
+<listitem>
+<para>this lists the options available for changing the way
+<application>kwrite</application> interacts with <trademark>qt</trademark>.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><userinput><command>kwrite</command> <option>--help-kde</option></userinput></term>
+<listitem>
+<para>this lists the options available for changing the way
+<application>kwrite</application> interacts with kde.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><userinput><command>kwrite</command> <option>--help-all</option></userinput></term>
+<listitem>
+<para>this lists all of the command line options.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><userinput><command>kwrite</command> <option>--author</option></userinput></term>
+<listitem>
+<para>lists <application>kwrite</application>'s authors in the terminal window</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><userinput><command>kwrite</command> <option>--version</option></userinput></term>
+<listitem>
+<para>lists version information for <trademark>qt</trademark>, kde, and <application>kwrite</application>. also available through <userinput><command>kwrite</command> <option>-v</option></userinput> </para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect2>
+</sect1>
+<sect1 id="keybindings">
+<title>key bindings</title>
+<para>many of the key bindings (shortcuts) are configurable by way of the <link linkend="settings">settings</link> menu. by default <application>kwrite</application> honors the
+following key bindings.</para>
+<informaltable>
+<tgroup cols="2">
+<tbody>
+<row>
+<entry><para><keycombo>
+<keycap>insert</keycap>
+</keycombo></para></entry>
+<entry><para> toggle between insert and overwrite mode. when in insert mode the
+editor will add any typed characters to the text while pushing along any data to
+the right of the text cursor. overwrite mode causes the entry of each character
+to eliminate the character immediately to the right of the text
+cursor.</para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>left arrow</keycap>
+</keycombo></para></entry>
+<entry><para>move the cursor one character to the left </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>right arrow</keycap>
+</keycombo></para></entry>
+<entry><para> move the cursor one character to the right </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>up arrow</keycap>
+</keycombo></para></entry>
+<entry><para> move the cursor up one line </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>down arrow</keycap>
+</keycombo></para></entry>
+<entry><para> move the cursor down one line </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>page up</keycap>
+</keycombo></para></entry>
+<entry><para> move the cursor up one page </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>page down</keycap>
+</keycombo></para></entry>
+<entry><para>move the cursor down one page </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>backspace</keycap>
+</keycombo></para></entry>
+<entry><para> delete the character to the left of the cursor </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>home</keycap>
+</keycombo></para></entry>
+<entry><para> move the cursor to the beginning of the line </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>end</keycap>
+</keycombo></para></entry>
+<entry><para> move the cursor to the end of the line </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>delete</keycap>
+</keycombo></para></entry>
+<entry><para>delete the character to the right of the cursor (or any selected
+text)</para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>shift</keycap>
+<keycap>left arrow</keycap>
+</keycombo></para></entry>
+<entry><para> mark text one character to the left </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>shift</keycap>
+<keycap>right arrow</keycap>
+</keycombo></para></entry>
+<entry><para> mark text one character to the right </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>f1</keycap>
+</keycombo></para></entry>
+<entry><para> help</para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>shift</keycap>
+<keycap>f1</keycap>
+</keycombo></para></entry>
+<entry><para><link linkend="whats-this">what's this?</link></para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>ctrl</keycap>
+<keycap>f</keycap>
+</keycombo></para></entry>
+<entry><para><link linkend="find"> find</link></para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>f3</keycap>
+</keycombo></para></entry>
+<entry><para><link linkend="find-again"> find again</link></para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>ctrl</keycap>
+<keycap>c</keycap>
+</keycombo></para></entry>
+<entry><para> copy the marked text to the clipboard. </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>ctrl</keycap>
+<keycap>m</keycap>
+</keycombo></para></entry>
+<entry><para>set a bookmark</para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>ctrl</keycap>
+<keycap>n</keycap>
+</keycombo></para></entry>
+<entry><para> <link linkend="new">new</link> document</para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>ctrl</keycap>
+<keycap>p</keycap>
+</keycombo></para></entry>
+<entry><para><link linkend="print">print</link> </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>ctrl</keycap>
+<keycap>q</keycap>
+</keycombo></para></entry>
+<entry><para>quit - close active copy of editor </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>ctrl</keycap>
+<keycap>r</keycap>
+</keycombo></para></entry>
+<entry><para><link linkend="replace"> replace</link></para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>ctrl</keycap>
+<keycap>s</keycap>
+</keycombo></para></entry>
+<entry><para>invokes the <link linkend="save"><guilabel>save</guilabel></link> command.</para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>ctrl</keycap>
+<keycap>v</keycap>
+</keycombo></para></entry>
+<entry><para> paste the clipboard text into line edit. </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>ctrl</keycap>
+<keycap>x</keycap>
+</keycombo></para></entry>
+<entry><para>delete the marked text and copy it to the clipboard. </para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>ctrl</keycap>
+<keycap>z</keycap>
+</keycombo></para></entry>
+<entry><para><link linkend="undo">undo</link></para></entry>
+</row>
+<row>
+<entry><para><keycombo>
+<keycap>ctrl</keycap>
+<keycap>shift</keycap>
+<keycap>z</keycap>
+</keycombo></para></entry>
+<entry><para><link linkend="redo">redo</link></para></entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+</sect1>
+</chapter>
+<chapter id="the-menu-entries">
+<title>the menu entries</title>
+<sect1 id="file">
+<title>the <guimenu>file</guimenu> menu</title>
+<variablelist>
+<varlistentry>
+<term><anchor id="new"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>n</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>f</accel>ile</guimenu>
+<guimenuitem><accel>n</accel>ew</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this starts a new document in the editor. if there is a current
+document with unsaved changes the user is given a chance to save it.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="open"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>o</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>f</accel>ile</guimenu>
+<guimenuitem><accel>0</accel>pen</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this command opens a file. it does this by means of a dialog box
+which allows the user to navigate the file system. the dialog operates
+like a small file manager. clicking on directories displayed in the
+central window directs the dialog to enter that directory - displaying its
+contents. there is an entry/dropdown box which can be used to type in
+directly the location and name of the file or by clicking the arrow at the
+side choose from a dropdown list of recently used locations. below this is
+a filter which similarly may have data entered directly or chosen from a
+dropdown list of recent filter types. the filter facility lets only files
+that meet its specifications be displayed in the central window. if the
+filter contained text such as <literal role="extension">*.txt</literal> then only files
+with the txt extension would be visible in the selection window. below the filter
+is a status bar giving information about the number of files and subdirectories
+within the current directory.</para>
+<para>the toolbar, which is located at the top of the dialog, has left and right
+arrow buttons that let the user move back and forth through previously selected
+directories as well as an up arrow button for moving up the directory tree. the
+button with the little house takes the user to his or her home directory and the one
+with the two arrows curved in on each other updates the view of the current
+directory. the flag button lets the user set a new bookmark at the current directory
+or go to one that was previously set.
+ the last button on the toolbar allows you to create a new
+directory, and finally there is dropdown box with a list of some commonly
+frequented directories.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="open-recent"/><menuchoice>
+<guimenu><accel>f</accel>ile</guimenu>
+<guimenuitem>open
+<accel>r</accel>ecent</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this is a shortcut to open recently saved documents. clicking on
+this item opens a list to the side of the menu with several of the most recently
+saved files. clicking on a specific file will open it in <application>kwrite</application> - if the file
+still resides at the same location. </para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="save"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>s</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>f</accel>ile</guimenu>
+<guimenuitem><accel>s</accel>ave</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this saves the current document. if there has already been a
+save of the document then this will overwrite the previously saved file without
+asking for the user's consent. if it is the first save of a new document the
+save as dialog (described below) will be invoked.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="save-as"/><menuchoice>
+<guimenu><accel>f</accel>ile</guimenu>
+<guimenuitem>save
+<accel>a</accel>s</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this allows a document to be saved with a new file name. this is
+done by means of the file dialog box described above in the <link linkend="open">open</link> section of this help file.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="print"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>p</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>f</accel>ile</guimenu>
+<guimenuitem><accel>p</accel>rint</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>opens a simple print dialog allowing the user to specify what, where, and how to print</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="new-window"/><menuchoice>
+<guimenu><accel>f</accel>ile</guimenu>
+<guimenuitem>new <accel>w</accel>indow</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this creates a new window, <abbrev>i.e.</abbrev> a new instance of <application>kwrite</application>. in this way the user can easily work
+on more than one file at a time with <application>kwrite</application>.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="new-view"/><menuchoice>
+<guimenu><accel>f</accel>ile</guimenu>
+<guimenuitem>new <accel>v</accel>iew</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this creates a new view of the current document, <abbrev>i.e.</abbrev>, a new instance of
+<application>kwrite</application> (as explained in the previous entry) but containing the same
+document.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="close"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>q</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>f</accel>ile</guimenu>
+<guimenuitem><accel>q</accel>uit</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this will close the editor window, if you have more than one
+instance of <application>kwrite</application> running, through the <guimenuitem>new view</guimenuitem> or
+<guimenuitem>new window</guimenuitem> menu items, those instances will not be
+closed.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+<sect1 id="edit">
+<title>the <guimenu>edit</guimenu> menu</title>
+<variablelist>
+<varlistentry>
+<term><anchor id="undo"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>z</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>e</accel>dit</guimenu>
+<guimenuitem>und<accel>o</accel></guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this is used to eliminate or reverse the most recent user action or operation. just what
+constitutes such an action may be better understood by referring to the <link linkend="group-undos">group undos</link> portion of this help file.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="redo"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>shift</keycap>
+<keycap>z</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>e</accel>dit</guimenu>
+<guimenuitem>re<accel>d</accel>o</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this will reverse the most recent change (if any) made using undo</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="undohistory"/><menuchoice>
+<guimenu><accel>e</accel>dit</guimenu>
+<guimenuitem>undo/redo <accel>h</accel>istory</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this will call a display box showing a list of the most recent actions on
+the left and another list of actions which have been 'undone' on the right.
+there are also three buttons at the right of the box labeled
+<guibutton>undo</guibutton>, <guibutton>redo</guibutton>, and
+<guibutton>close</guibutton>. clicking on the <guibutton>undo</guibutton>
+button will cause the action at the top of the undo list to be reversed which
+will place that particular action at the top of the redo list. likewise,
+clicking on the <guibutton>redo</guibutton> button will reinstate the reversed
+action and move it back to the top of the undo list. clicking on an item below
+the top item in either list will select all the items from the top down to that
+point. a subsequent click on the corresponding button will cause all the
+selected actions to be undone or redone accordingly. this would be particularly
+useful when the user knows precisely the point to which she or he would like to
+proceed - making it unnecessary to go through a series of single undo or redo
+actions.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="cut"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>x</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>e</accel>dit</guimenu>
+<guimenuitem>c<accel>u</accel>t</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this command deletes the current selection and places it on the clipboard. the
+clipboard is a feature of kde that works invisibly to provide a way to transfer data between
+applications.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="copy"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>c</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>e</accel>dit</guimenu>
+<guimenuitem><accel>c</accel>opy</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this copies the currently selected text to the clipboard so that it may be
+pasted elsewhere. the clipboard is a feature of kde that works invisibly to
+provide a way to transfer data between applications.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="paste"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>v</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>e</accel>dit</guimenu>
+<guimenuitem><accel>p</accel>aste</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this will insert the contents of the clipboard at the cursor position. the
+clipboard is feature of kde that works invisibly to provide a way to transfer
+data between applications.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="select-all"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>a</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>e</accel>dit</guimenu>
+<guimenuitem>select <accel>a</accel>ll</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this will select the entire document. this could be very useful for
+copying the entire file to another application.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="invert-the-selection"/><menuchoice>
+<guimenu><accel>e</accel>dit</guimenu>
+<guimenuitem>invert <accel>s</accel>election</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this selects any unselected text while unselecting any selected text -
+effectively reversing the current state of selection.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="find"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>f</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>e</accel>dit</guimenu>
+<guimenuitem><accel>f</accel>ind</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this opens the find dialog which is used to specify the <guilabel>text to
+find</guilabel> in the document. there is small text box for entering the search
+pattern which also doubles as a dropdown box. clicking on the dropdown arrow at
+the side of the box makes available other recent search patterns. other
+parameters are included to make the search more efficient. selecting
+<guilabel>case sensitive</guilabel> will limit finds to entries that match the
+case (upper or lower) of each of the characters in the search
+pattern. <guilabel>find backwards</guilabel> directs the search to proceed in an
+upwardly direction. the <guilabel>selected text</guilabel> option keeps the
+search within currently selected text. checking <guilabel>whole words
+only</guilabel> prevents the search from stopping on words that contain the
+searched for pattern. the <guilabel>search from cursor</guilabel> option begins
+the search from the current position of the cursor within the document rather
+than from the beginning.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="find-again"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>f3</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>e</accel>dit</guimenu>
+<guimenuitem>find <accel>n</accel>ext</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this repeats the last find operation, if any, without calling the find
+dialog box.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="replace"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>r</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>e</accel>dit</guimenu>
+<guimenuitem><accel>r</accel>eplace</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this command opens the replace dialog box. the replace dialog is
+almost identical to the above-mentioned find dialog. in addition to the features in
+the find dialog it contains a <guilabel>replace with:</guilabel> text
+entry/dropdown box. using this dialog the user can specify both the text to be found
+and text with which to replace it. the additional <guilabel>prompt
+on replace</guilabel> option allows the user to have <application>kwrite</application> ask for
+confirmation before each replacement.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="insertfile"/>
+<menuchoice>
+<guimenu><accel>e</accel>dit</guimenu>
+<guimenuitem><accel>i</accel>nsert file</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this <action>opens</action> the <guimenu>file</guimenu> <link linkend="open"><guimenuitem>open</guimenuitem></link> dialog box whereby the
+user can insert a complete file in the open document. the the contents of
+the file will be entered at the position of the blinking text
+cursor.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+<sect1 id="go">
+<title>the <guimenu>go</guimenu> menu</title>
+<variablelist>
+<varlistentry>
+<term><anchor id="go-to-line"/><menuchoice>
+<guimenu><accel>g</accel>o</guimenu>
+<guimenuitem><accel>g</accel>o to line</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this opens the goto line dialog box which is used to have the cursor jump
+to a particular line (specified by number) in the document. the line number may
+be entered directly into the text box or graphically by clicking on the up or
+down arrow spin controls at the side of the text box. the little up arrow will
+increase the line number and the down arrow decrease it. there is also a slide
+control to the right of the text box which allows the user to move the goto
+point in the document in an analog manner.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="add-marker"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>ctrl</keycap>
+<keycap>m</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>g</accel>o</guimenu>
+<guimenuitem><accel>a</accel>dd marker</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this creates a marker in the document at the line where the cursor is
+located and places it at the bottom of the list of markers located at the
+bottom of the go menu.</para>
+<para>markers are points within a <application>kwrite</application> document
+marked for easy return. if the user thinks (s)he may need to return to a specific
+point (s)he may by way of this feature instruct <application>kwrite</application> to remember it. </para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="set-bookmark"/><menuchoice>
+<guimenu><accel>g</accel>o</guimenu>
+<guimenuitem><accel>s</accel>et marker</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this creates a marker in the document at the line where the cursor is
+located, and allows the user to choose its position in the list of bookmarks
+which is appended at the bottom of this menu item.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="clear-bookmarks"/><menuchoice>
+<guimenu><accel>g</accel>o</guimenu>
+<guimenuitem><accel>c</accel>lear markers</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this command will remove all the markers from the docucument as well as the
+list of markers which is appended at the bottom of this menu item.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>at the bottom of this menu, a list of markers appears if any
+markers are available for this window.</para>
+</sect1>
+<sect1 id="tools">
+<title>the <guimenu>tools</guimenu> menu</title>
+<variablelist>
+<varlistentry>
+<term><anchor id="spelling..."/><menuchoice>
+<guimenu><accel>t</accel>ools</guimenu>
+<guimenuitem><accel>s</accel>pelling...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>this initiates the spell checking program - a program
+designed to help the user catch and correct any spelling errors.</action>
+clicking on this entry will start the checker and bring up the speller dialog
+box through which the user can control the process. there are three text boxes
+lined up vertically in the center of the dialog with their corresponding labels
+just to the left. starting at the top they are:</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>misspelled word:</guilabel></term>
+<listitem>
+<para>here, the spell checker indicates the word currently under
+consideration. this happens when the checker encounters a word not in its
+dictionary - a file containing a list of correctly spelled words against which
+it compares each word in the editor.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>replacement:</guilabel></term>
+<listitem>
+<para> if the checker has any similar words in its dictionary the
+first one will be listed here. the user can accept the suggestion, type in his
+or her own correction, or choose a different suggestion from the next
+box.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>suggestions:</guilabel></term>
+<listitem>
+<para> the checker may list here a number of possible replacements for
+the word under consideration. clicking on any one of the suggestions will cause
+that word to be entered in the <guilabel>replacement:</guilabel> box,
+above.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>on the right side of the dialog box are 6 buttons that allow the user to
+control the spell check process. they are:</para>
+<variablelist>
+<varlistentry>
+<term><guibutton>replace</guibutton></term>
+<listitem>
+<para> this button has the checker replace the word under
+consideration in the document with the word in the
+<guilabel>replacement:</guilabel> box.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>replace all</guibutton></term>
+<listitem>
+<para> this button causes the checker to replace not only the current
+<guilabel>misspelled word:</guilabel> but to automatically make the same
+substitution for any other occurences of this <guilabel>misspelled
+word:</guilabel> in the document.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>ignore</guibutton></term>
+<listitem>
+<para>activating this button will have the checker move on without
+making any changes.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>ignore all</guibutton></term>
+<listitem>
+<para> this button tells the checker to do nothing with the current
+<guilabel>misspelled word:</guilabel> and to pass over any other instances of
+the same word.</para>
+<note>
+<para>this only applies to the current spell check
+run. if the checker is run again later it will stop on this same
+word.</para>
+</note>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>add</guibutton></term>
+<listitem>
+<para>pressing this button adds the word in the <guilabel>misspelled
+word:</guilabel> box to the checker's dictionary. this means that in the future
+the checker will always consider this word to be correctly
+spelled.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>stop</guibutton></term>
+<listitem>
+<para> this button stops the spell check process.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>located horizontally along the bottom of the spell check dialog is a
+progress bar. as the checking process proceeds the bar will fill from left to
+right providing a graphical representation of how far along in the document the
+process has reached. in addition, the progress is displayed numerically in
+the center of the progress bar.</para>
+<note>
+<para>a numerical display of the spell check
+process is simultaneously displayed in the status bar of the editor. the <link linkend="show-statusbar">status bar</link> is the horizontal strip at the bottom
+of the editor just outside of the text entry area.</para>
+</note>
+<para>two more buttons are located below the progress bar. they are:</para>
+<variablelist>
+<varlistentry>
+<term><guibutton>help</guibutton></term>
+<listitem>
+<para> this invokes the kde help system starting at the <application>kwrite</application> help
+pages (this document).</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>cancel</guibutton></term>
+<listitem>
+<para> this button cancels the spell check process.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="indent"/><menuchoice>
+<guimenu>tools</guimenu>
+<guimenuitem>indent</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this increases the paragraph's indentation by one step. the size of the
+step depends on the <link linkend="pref-indent"> indentation
+settings</link>.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="unindent"/><menuchoice>
+<guimenu>tools</guimenu>
+<guimenuitem>unindent</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this reduces the paragraph's indentation by one step. the size of the step
+depends on the <link linkend="pref-indent"> indentation settings</link>.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="cleanindent"/><menuchoice>
+<guimenu>tools</guimenu>
+<guimenuitem>clean
+indentation</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>not yet implemented</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<guimenu>tools</guimenu>
+<guimenuitem>comment</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this adds one space to the beginning of the line
+where the text cursor is located or to the beginning of any
+selected lines.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<guimenu>tools</guimenu>
+<guimenuitem>uncomment</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this removes one space (if any exist) from the beginning of the line
+where the text cursor is located or from the beginning of any
+selected lines.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+<sect1 id="settings">
+<title>the <guimenu>settings</guimenu> menu</title>
+<variablelist>
+<varlistentry>
+<term><anchor id="show-toolbar"/><menuchoice>
+<guimenu><accel>s</accel>ettings</guimenu>
+<guimenuitem>show <accel>t</accel>oolbar</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>when checked, this displays a movable toolbar containing buttons used to
+initiate frequently used commands. when unchecked the toolbar is hidden.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="show-statusbar"/><menuchoice>
+<guimenu><accel>s</accel>ettings</guimenu>
+<guimenuitem>show <accel>s</accel>tatusbar</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>when checked, this displays a small bar at the bottom of the editor
+containing information about the status of the current document. when unchecked
+the statusbar is hidden.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="show-path"/><menuchoice>
+<guimenu><accel>s</accel>ettings</guimenu>
+<guimenuitem>sho<accel>w</accel> path</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>when selected, this displays in the title bar the path (its location in the
+file system) of the current document. when unchecked the path is hidden.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="configure-keybindings"/><menuchoice>
+<guimenu><accel>s</accel>ettings</guimenu>
+<guimenuitem>configure <accel>k</accel>ey bindings</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this command opens a dialog box whereby the <link linkend="keybindings">key bindings</link> may be changed. a display window at
+the top of the dialog box shows the list of commands (actions) that can have
+keyboard shortcuts. below the display are three radio buttons. the user may choose
+between no key, default key, and custom key. (note that a set of radio buttons only
+allows the selection of one of the offered items - in the way that buttons on a car
+radio only offer the selection of one preset station. also, the default key
+selection is only available for those commands that actually have a 'default'
+shortcut.) selecting the custom key option activates the three check boxes and key
+button at the bottom of the dialog. the user may then select a key
+combination for the command in question by means of the check boxes and key
+button. for example, with the about kde command selected in the display window,
+the user could select <keycap>ctrl</keycap> and <keycap>alt</keycap>, click on
+the key button, and then press the <keycap>k</keycap> key on the keyboard. this
+would mean that anytime he or she held down the <keycap>ctrl</keycap> and
+<keycap>alt</keycap> buttons and pressed <keycap>k</keycap> (while using
+<application>kwrite</application>) the about kde display box would be called. </para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="configure-toolbars"/><menuchoice>
+<guimenu><accel>s</accel>ettings</guimenu>
+<guimenuitem>configure tool<accel>b</accel>ars</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this will open the dialog whereby the toolbar configuration may
+be changed. the user can choose which shortcut buttons should appear on the
+toolbar. a display window on the left lists the commands available to placed
+on the toolbar. a display on the right lists those commands already on the
+toolbar. a set of four arrow buttons between the two displays manipulates the
+selections. the right pointing arrow places any command selected in the left
+pane onto the right pane, <abbrev>i.e.</abbrev>, it is added to the toolbar.
+the left arrow does just the opposite, removing any action selected in the right
+window from the toolbar. the up and down pointing arrows change the position of
+an action selected in the right window which changes the position of its button
+in the toolbar.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="preferences"/><menuchoice>
+<guimenu><accel>s</accel>ettings</guimenu>
+<guimenuitem><accel>p</accel>references</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this menu item opens a dialog whereby several different <link linkend="pref-dialog">settings</link> may be adjusted.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice>
+<guimenu><accel>s</accel>ettings</guimenu>
+<guimenuitem>configure
+highlighti<accel>n</accel>g</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>opens a dialog box allowing configuration of the syntax
+highlighting. the dialog is described in <xref linkend="pref-highlighting"/>.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="vertical-selection"/><menuchoice>
+<guimenu><accel>s</accel>ettings</guimenu>
+<guimenuitem><accel>v</accel>ertical
+selection</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this is used to turn on or off the vertical selection feature. vertical
+selection allows text to be selected by column as well as by row. in other
+words with this feature the user is able to select text contained in only
+particular contiguous columns and rows. in affect the user can select a
+rectangular area of text anywhere in the document.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="set-highlight"/><menuchoice>
+<guimenu><accel>s</accel>ettings</guimenu>
+<guimenuitem><accel>h</accel>ighlight mode</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this allows the user to choose the style of color highlighting which the
+editor uses to display the text. the styles are selected by programming
+language. the font/color information is not stored with the document.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="end-of-line"/><menuchoice>
+<guimenu><accel>s</accel>ettings</guimenu>
+<guisubmenu><accel>e</accel>nd of line</guisubmenu>
+</menuchoice></term>
+<listitem>
+<para>this opens a sub-menu from which the user can select the type of <quote>end of
+line</quote> code for <application>kwrite</application> to use, <abbrev>i.e.</abbrev>, the accepted standard
+used by unix, <trademark class="registered">mac</trademark> or msdos/<trademark class="registered">windows</trademark> systems.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+<sect1 id="help">
+<title>the <guimenuitem>help</guimenuitem> menu</title>
+<variablelist>
+<varlistentry>
+<term><anchor id="contents"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>f1</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>h</accel>elp</guimenu>
+<guimenuitem><accel>c</accel>ontents</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this invokes the kde help system starting at the <application>kwrite</application> help pages (this document).</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="whats-this"/><menuchoice>
+<shortcut>
+<keycombo>
+<keycap>shift</keycap>
+<keycap>f1</keycap>
+</keycombo>
+</shortcut>
+<guimenu><accel>h</accel>elp</guimenu>
+<guimenuitem>what's <accel>t</accel>his?</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this changes the mouse cursor to a combination arrow and question mark.
+clicking on items within <application>kwrite</application> with this arrow will open a help window (if
+one exists for the particular item) explaining the item's function.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="report-bug"/><menuchoice>
+<guimenu><accel>h</accel>elp</guimenu>
+<guimenuitem><accel>r</accel>eport bug</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para><action>this calls a dialog box to help
+the user help the kde team to track down and solve any
+problems(bugs) in the program. the dialog attempts to do this by
+means of email using the information given by the user.</action></para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="about-kwrite"/><menuchoice>
+<guimenu><accel>h</accel>elp</guimenu>
+<guimenuitem><accel>a</accel>bout kwrite</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this will display version and author information</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><anchor id="about-kde"/><menuchoice>
+<guimenu><accel>h</accel>elp</guimenu>
+<guimenuitem>about <accel>k</accel>de</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>this displays the kde version and other basic information.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+</chapter>
+<chapter id="pref-dialog">
+<title>configure <application>kwrite</application></title>
+<para>selecting
+<menuchoice>
+<guimenu>settings</guimenu>
+<guimenuitem>configure
+kwrite</guimenuitem>
+</menuchoice> from the menu brings up the configure-kwrite
+dialog box. this dialog can be used to alter a number of different settings. the
+settings available for change vary according to which category the user chooses from
+a vertical list on the left side of the dialog. by means of three buttons
+along the bottom of the box the user can control the process. she or he may invoke
+the <guilabel>help</guilabel> system, accept the current settings and close the
+dialog by means of the <guibutton>ok</guibutton> button, or
+<guibutton>cancel</guibutton> the process. the categories
+<guilabel>colors</guilabel>, <guilabel>indent</guilabel>,
+<guilabel>select</guilabel>, <guilabel>edit</guilabel>, and
+<guilabel>spelling</guilabel> are detailed below.</para>
+<sect1 id="prefcolors">
+<title>colors</title>
+<para>this section provides access to <link linkend="pref-color-settings">five different color settings</link>,
+described below. each of these settings may be changed by clicking on its
+corresponding button. these are special wide buttons that are the color of
+the current setting. clicking on one of the buttons calls a special color
+dialog box used to change the setting.</para>
+<para>the color dialog box provides a convenient and graphical way to
+select a color. in the upper left of the box is a rectangular display of a
+spectrum of colors. to the immediate right of this, is vertical bar
+displaying a range of intensity from the most dark at the bottom to the
+most light at the top. the user may select and adjust a color by clicking
+in these two boxes. clicking in the rectangular display selects a
+particular mix of red, green, and blue colors and in the vertical bar
+selects a level of intensity (value). the various color attributes are displayed
+in numerical form in small text boxes located directly below the spectral
+rectangle and the user can see them change as the color is adjusted. these
+attributes include the mix of the basic color components (red, green, and
+blue) as well as hue and saturation levels. alternatively the user can
+enter figures directly in these boxes. there is also a square at the
+bottom center of the dialog box which displays the color which is under
+consideration at any time. to the right of this display is another text
+box labeled <guilabel>html:</guilabel> this shows the user the color code
+that would be used to specify the particular displayed color in
+<acronym>html</acronym> code which is widely used for web pages.</para>
+<para>in addition to the above, the color dialog allows the capture of any
+color currently displayed on the desktop or in another program. clicking
+on the button with the dropper icon (located on the right side of the
+dialog box,) changes the shape of the mouse cursor to a set of crosshairs.
+clicking again will pick up the color attributes of whatever color is
+displayed under the cross hairs.</para>
+<para>furthermore the user has the option of adding any color to a personal
+palette of <quote>custom colors</quote> by clicking on the wide button labeled
+<guibutton>add to custom colors</guibutton> (which is located directly above the
+display square.) this adds the current color to the custom color palette. this
+palette and any other available palettes can be displayed using the drop down
+selection box located directly above the palette display at the top right of the
+dialog box. besides the custom colors, the user can access a number of
+pre-prepared palettes.</para>
+<variablelist>
+<varlistentry id="pref-color-settings">
+<term><guilabel>background</guilabel></term>
+<listitem>
+<para>here the user can specify a color for the general background of
+<application>kwrite</application>.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>text background</guilabel></term>
+<listitem>
+<para>this is used to set a particular color to display in the
+background of those areas of the document containing text.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>selected</guilabel></term>
+<listitem>
+<para>this allows the user to select a color to be used for indicating
+selected (or highlighted) portions of the document.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>found</guilabel></term>
+<listitem>
+<para>this specifies the preferred color with which to mark text
+encountered as the result of a <link linkend="find">find</link>
+operation.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>selected + found</guilabel></term>
+<listitem>
+<para>this sets the color for text that has not only been found as in
+the previous entry above but that has also been selected.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+<sect1 id="pref-indent">
+<title>indent</title>
+<variablelist>
+<varlistentry>
+<term><guilabel>auto indent</guilabel></term>
+<listitem>
+<para>this causes
+new lines to begin with the same indentation level as the previous
+line.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>indent with spaces</guilabel></term>
+<listitem>
+<para>this
+replaces tabs with the number of spaces selected in the tab width window in
+the <link linkend="pref-edit">edit</link> section of the preferences
+dialog.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>backspace key indents</guilabel></term>
+<listitem>
+<para>this allows the
+<keycombo>
+<keycap>backspace</keycap>
+</keycombo> key to be used to
+indent.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>tab key indents</guilabel></term>
+<listitem>
+<para>this
+allows the <keycombo>
+<keycap>tab</keycap>
+</keycombo> key to be used to
+indent.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>keep indent profile</guilabel></term>
+<listitem>
+<para>this
+retains current indentation settings for future documents.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>keep extra spaces</guilabel></term>
+<listitem>
+<para>indentations of more than the selected number of spaces
+will not be shortened.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+<sect1 id="pref-select">
+<title>select</title>
+<variablelist>
+<varlistentry>
+<term><guilabel>persistent selections</guilabel></term>
+<listitem>
+<para>this prevents key input or cursor movement by way of the
+arrow keys from causing the elimination of text
+selection. </para>
+<note>
+<para>(note: if the overwrite selections option is
+activated then any typed character input or paste operation will replace
+the selected text.)</para>
+</note>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>overwrite selections</guilabel></term>
+<listitem>
+<para>any keyed character input or paste operation will replace
+the selected text. </para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>mouse autocopy</guilabel></term>
+<listitem>
+<para>any text
+selected with the mouse will be automatically copied to the
+clipboard.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>x11-like single selection</guilabel></term>
+<listitem>
+<para>not implemented yet.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>vertical selections</guilabel></term>
+<listitem>
+<para>this
+activates the <link linkend="vertical-selection">vertical selection</link>
+option.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>toggle old</term>
+<listitem>
+<para>not yet implemented</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+<sect1 id="pref-edit">
+<title>edit</title>
+<variablelist>
+<varlistentry>
+<term id="pref-word-wrap"><guilabel>word wrap</guilabel></term>
+<listitem>
+<para>word wrap is a feature that causes the editor to
+automatically start a new line of text and move (wrap) the cursor to the
+beginning of that new line. <application>kwrite</application> will automatically start a new line of text
+when the current line reaches the length specified by the <link linkend="pref-wrap-words-at">wrap words at:</link>
+option.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term id="pref-wrap-words-at"><guilabel>wrap words
+at:</guilabel></term>
+<listitem>
+<para>if the <link linkend="pref-word-wrap">word wrap</link> option is selected this entry
+determines the length (in characters) at which the editor will
+automatically start a new line.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term id="pref-replace-tabs-by-spaces"><guilabel>replace tabs by
+spaces</guilabel></term>
+<listitem>
+<para><application>kwrite</application> will replace any tabs
+with the number of spaces indicated in the <link linkend="pref-tab-width">tab width:</link> entry.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term id="pref-tab-width">tab width</term>
+<listitem>
+<para>if the <link linkend="pref-word-wrap"><guilabel>replace tabs by spaces</guilabel></link>
+option is selected this entry determines the number of spaces with which
+the editor will automatically replace tabs.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>remove trailing spaces</guilabel></term>
+<listitem>
+<para><application>kwrite</application> will automatically eliminate extra spaces at the
+ends of lines of text.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>auto brackets</guilabel></term>
+<listitem>
+<para>when the
+user types a left bracket ([,(, or {) <application>kwrite</application> automatically
+enters the right bracket (}, ), or ]) to the right of the
+cursor.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term id="group-undos"><guilabel>group undos</guilabel></term>
+<listitem>
+<para>groups of similar actions are to be considered a single
+<link linkend="undo">undo</link> step by <application>kwrite</application>. in other words, a series
+of regular character keystrokes (words or expressions) would be considered
+one step and therefore be removed by a single undo operation. if the
+series of character entries were interrupted by a non-character entry
+operation (such as a backspace), invoking undo would only remove the
+entries made since that operation. the next undo would then reverse that
+operation and so on.</para>
+<para> when this option is not selected <application>kwrite</application> considers
+each keystroke to be a single step. so if the user (with this option
+active) were to type several words or even sentences without having to make
+corrections or cut or paste or some other non-character entry operation
+then a click of the undo button would eliminate all that had been typed
+since the last non-entry operation. a second click would eliminate that
+operation and a third any operation or series of entries that occurred
+before the operation and so on. when not selected three clicks of the undo
+button would only remove the last three letters typed, or the last three
+operations.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>show tabs</guilabel></term>
+<listitem>
+<para>the editor will display a symbol to indicate the presence
+of a tab in the text.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>smart home</guilabel></term>
+<listitem>
+<para>not yet implemented</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>page up/down moves cursor</guilabel></term>
+<listitem>
+<para>this option changes the behavior of the cursor when
+the user presses the <keycap>page up</keycap> or <keycap>page down</keycap> key. if
+unselected the text cursor will maintain its relative position within the visible
+text in <application>kwrite</application> as new text becomes visible as a result of the operation. so if
+the cursor is in the middle of the visible text when the operation occurs it will
+remain there (except when one reaches the beginning or end.) with this
+option selected, the first key press will cause the cursor to move to either the top
+or bottom of the visible text as a new page of text is displayed.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>wrap cursor</term>
+<listitem>
+<para>when this option is chosen, moving
+the cursor with the arrow keys off the end of a line (to the right) causes
+it to jump down to the beginning of the next line. likewise when the
+cursor is moved past the beginning of a line (to the left) it jumps up to
+the end of the preceding line. when this option is not selected, moving the
+cursor right past the end of a line merely causes it to continue
+horizontally in the same line and trying to move it left past the beginning
+does nothing.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><link linkend="undo">undo</link> steps:</term>
+<listitem>
+<para>here
+the user may specify the number of steps <application>kwrite</application> will retain in memory for
+purposes of undoing entries and actions. this means that the higher the
+number of steps set the more memory <application>kwrite</application> will use for this. setting
+this entry to 10 would mean that the user would be be able reverse the last
+ten operations, <abbrev>i.e.</abbrev>i>, click the <guibutton>undo</guibutton>
+button 10 times and obtain results.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+<sect1 id="prefspellchecker">
+<title>spelling</title>
+<para>a spell checker is a program designed to
+help the user catch and correct any spelling errors. this section of the
+preferences dialog allows certain important settings to be adjusted in this
+regard.</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>create root/affix combinations not in
+dictionary</guilabel></term>
+<listitem>
+<para>selecting this option allows
+the spell checker to register as 'correct' combinations of root words with
+suffixes or prefixes even if the particular combination is not listed in
+its dictionary data base of words.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>consider run-together words as spelling
+errors</guilabel></term>
+<listitem>
+<para>selecting this will cause the
+spell checker to register as 'misspelled' two or more correctly spelled
+words that are 'run-together', <abbrev>i.e.</abbrev>, that do not have spaces
+separating them.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>dictionary:</guilabel></term>
+<listitem>
+<para>depending on
+the user's installation one or more different language spelling
+dictionaries may be available. this drop down box allows the user to
+choose which language the spell checker should use.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>encoding:</guilabel></term>
+<listitem>
+<para>there are
+different coding systems used to associate particular codes with particular
+characters and symbols. if the user knows which code he or she is using
+this drop down box allows this code to be specified so that the spell
+checker can do its job correctly. </para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>client:</guilabel></term>
+<listitem>
+<para>since <application>kwrite</application>
+does not contain its own spell checker, an external one must be chosen.
+this is where the user may specify which spell check program to
+use.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+</chapter>
+<chapter id="pref-highlighting">
+<title>highlighting</title>
+<para>the <guilabel>configure highlighting</guilabel> dialog consists of two
+pages, <guilabel>defaults</guilabel> and <guilabel>highlighting
+modes</guilabel>. the user can select which page to view by clicking on the
+appropriate tab at the top of the dialog</para>
+<para>items available on the <guilabel>defaults</guilabel> page are as
+follows:</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>default item styles</guilabel></term>
+<listitem>
+<para>the user can configure the default appearance for particular items.
+this would allow a programmer to more easily identify different items (types of
+entries) in his or her code.
+
+</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>item</guilabel></term>
+<listitem>
+<para>this drop down list offers a variety of items that the user
+might want to highlight. they include <guilabel>normal</guilabel> for
+text does not fit in any of the other categories, <guilabel>comment</guilabel>,
+<guilabel>string</guilabel>, <guilabel>keyword</guilabel> and many more. not
+all of these entries will need to be configured for every language and so may be
+selected as needed. the options in the rest of this section apply
+to the entry selected in this box.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>normal</guilabel></term>
+<listitem>
+<para>this allows the user to choose the item's normal
+(unselected) color. this is done by means of a color selection
+dialog box, a further explanation of which may be found in the <link linkend="prefcolors">colors</link> section of <link linkend="pref-dialog">configure kwrite</link>.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>bold</guilabel></term>
+<listitem>
+<para>this option determines whether or not the item should be displayed in
+bold text.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>italic</guilabel></term>
+<listitem>
+<para>this option determines whether or not the item should be displayed in italic
+text.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>selected</guilabel></term>
+<listitem>
+<para>this allows the user to choose the item's color
+when selected. this is done by means of a color selection
+dialog box, a further explanation of which may be found in the <link linkend="prefcolors">colors</link> section of <link linkend="pref-dialog">configure kwrite</link>.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>default font</guilabel></term>
+<listitem>
+<para>here the user can choose the default font for all
+text.</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>family</guilabel></term>
+<listitem>
+<para>this is used to choose the font family. the default is fixed.
+for most programming purposes, a monospaced font (one in which a w takes up the same
+amount of space as an i) may be the best choice.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>size</guilabel></term>
+<listitem>
+<para>the font size can be changed here. the default is 12
+points.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>charset</guilabel></term>
+<listitem>
+<para>here the user can choose which character set to work in.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>items on the <guilabel>highlight modes</guilabel> tab allow the user to define
+more specific highlighting depending on the language style.</para>
+<para>one need not set every available option, items not configured
+specifically will use the default configuration specified on the previous
+(<guilabel>defaults</guilabel> tab.</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>config select</guilabel></term>
+<listitem>
+<para>this group of options is used to customize the highlighting styles
+for each programming language type. any changes you made in
+other areas of this dialog apply only to this type.</para>
+<variablelist>
+<varlistentry>
+<term><guilabel>highlight</guilabel></term>
+<listitem>
+<para>this is used to choose the language type to
+configure</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>item</guilabel></term>
+<listitem>
+<para>this is to choose the syntax item to configure. remember
+this only configures <emphasis>this</emphasis> item for <emphasis>this</emphasis>
+language.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+<para>as an example, if the user wished to configure the appearance of
+<quote>comments</quote> while writing c++, she or he could choose c++ in the
+<guilabel>highlight</guilabel> drop down list, and then choose comment in the
+<guilabel>item</guilabel> drop down list. to have <quote>comments</quote> look
+the same across all languages, the user would need to configure this in the
+<guilabel>defaults</guilabel> page of this dialog box while leaving
+<quote>comments</quote> unconfigured within the more specific
+<guilabel>highlight modes</guilabel> page.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>item style</guilabel></term>
+<listitem>
+<para>here the user can configure the general appearance of the above
+selected item. checking the <guilabel>default</guilabel> checkbox causes the default
+style as configured on the previous tab to be set, or the
+appearance can be configured directly. the available options are the same as on the
+<guilabel>defaults</guilabel> tab: <guilabel>normal</guilabel>,
+<guilabel>selected</guilabel>, <guilabel>bold</guilabel> and
+<guilabel>italic</guilabel>.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>highlight auto select</guilabel></term>
+<listitem>
+<para><application>kwrite</application> can apply syntax highlighting automatically, depending
+on the file extension or mime-type of the opened file. the defaults are fairly
+comprehensive, but users that regularly edit files with non-standard extensions
+can add them here. wildcards are allowed in the <guilabel>file
+extensions</guilabel> text box. for example, the default entry for the c++
+language is <userinput>*.cpp;*.cc;*.c;*.h</userinput>. opening a file called
+<filename>foo.h</filename> would automatically apply the c++ style to it.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>item font</guilabel></term>
+<listitem>
+<para>here the user can choose the font for the selected item.</para>
+<para>the default style can be applied by checking the
+<guilabel>default</guilabel> checkbox or the user can choose a specific font
+<guilabel>family</guilabel>, <guilabel>size</guilabel> and
+<guilabel>charset</guilabel>. the available options are the same as those on
+the <guilabel>defaults</guilabel> tab.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+</chapter>
+<chapter id="credits">
+<title>credits and licenses</title>
+<para><application>kwrite</application> copyright 2000 by jochen wilhelmy
+<email>digisnap@cs.tu-berlin.de</email></para>
+<para>contributions:</para>
+<itemizedlist>
+<listitem>
+<para>additional contributions by glen parker <email>glenebob@nwlink.com</email></para>
+</listitem>
+<listitem>
+<para>michael koch <email>koch@kde.org</email></para>
+</listitem>
+</itemizedlist>
+<para>documentation by thad mcginnis <email>ctmcginnis@compuserve.com</email></para>
+<itemizedlist>
+<listitem>
+<para>this version of the <application>kwrite</application> handbook is based on the original by cristian tibirna <email>tibirna@kde.org</email></para>
+</listitem>
+</itemizedlist>
+<para>converted to docbook/proofreading by lauri watts <email>vampyr@atconnex.net</email></para>
+<para id="gnu-fdl" xreflabel="the section entitled gnu free documentation license">this documentation is licensed under the terms of the <ulink url="common/fdl-license.html">gnu free documentation
+license</ulink>.</para>
+<para>this program is licensed under the terms of the <ulink url="common/gpl-translated.html">gnu general public license</ulink>.</para>
+</chapter>
+<appendix id="installation">
+<title>installation</title>
+<para><application>kwrite</application> is packaged as part of the kdebase package. for more information
+on installing and compiling kde please see <ulink url="http://www.kde.org">www.kde.org</ulink>.</para>
+</appendix>
+</book>
projects / platform / upstream / libxslt.git / commitdiff