diff options
Diffstat (limited to 'tests')
| -rw-r--r-- | tests/XSLTMark/Makefile.am | 255 | ||||
| -rw-r--r-- | tests/docbook/result/html/gdp-handbook.html | 4494 | ||||
| -rw-r--r-- | tests/docbook/result/html/kwrite.html | 1724 | ||||
| -rw-r--r-- | tests/docbook/test/gdp-handbook.xml | 4448 | ||||
| -rw-r--r-- | tests/docbook/test/kwrite.xml | 1784 |
5 files changed, 12582 insertions, 123 deletions
diff --git a/tests/XSLTMark/Makefile.am b/tests/XSLTMark/Makefile.am index 9716cf67..2ed853a5 100644 --- a/tests/XSLTMark/Makefile.am +++ b/tests/XSLTMark/Makefile.am @@ -47,6 +47,10 @@ EXTRA_DIST = \ xslbench3.out xslbench3.xsl \ xslbenchdream.xml +if WITH_PERL +PERL = perl +endif + $(top_builddir)/libxslt/xsltproc: @(cd ../../libxslt ; make xsltproc) @@ -60,14 +64,16 @@ all: alphabetize attsets avts axis backwards bottles breadth brutal chart \ 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) @@ -77,17 +83,8 @@ alphabetize: db100.xml 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) @@ -99,6 +96,128 @@ avts: db100.xml # 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) @@ -159,16 +278,6 @@ chart: # 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) @@ -179,36 +288,6 @@ 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) @@ -219,26 +298,6 @@ 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) @@ -259,26 +318,6 @@ html: # 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) @@ -309,26 +348,6 @@ oddtemplate: # 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) @@ -369,16 +388,6 @@ reverser: # 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) diff --git a/tests/docbook/result/html/gdp-handbook.html b/tests/docbook/result/html/gdp-handbook.html new file mode 100644 index 00000000..73c16c01 --- /dev/null +++ b/tests/docbook/result/html/gdp-handbook.html @@ -0,0 +1,4494 @@ +<!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> diff --git a/tests/docbook/result/html/kwrite.html b/tests/docbook/result/html/kwrite.html new file mode 100644 index 00000000..33183cb3 --- /dev/null +++ b/tests/docbook/result/html/kwrite.html @@ -0,0 +1,1724 @@ +<!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> diff --git a/tests/docbook/test/gdp-handbook.xml b/tests/docbook/test/gdp-handbook.xml new file mode 100644 index 00000000..6fe62531 --- /dev/null +++ b/tests/docbook/test/gdp-handbook.xml @@ -0,0 +1,4448 @@ +<?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> diff --git a/tests/docbook/test/kwrite.xml b/tests/docbook/test/kwrite.xml new file mode 100644 index 00000000..5889cb75 --- /dev/null +++ b/tests/docbook/test/kwrite.xml @@ -0,0 +1,1784 @@ +<!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> |