Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

2 files changed, 286 insertions, 0 deletions

diff --git a/doc/kwatchgnupg/Makefile.am b/doc/kwatchgnupg/Makefile.am
new file mode 100644
index 000000000..085981d9b
--- /dev/null
+++ b/doc/kwatchgnupg/Makefile.am
@@ -0,0 +1,4 @@
+
+KDE_LANG = en
+KDE_DOCS = AUTO
+
diff --git a/doc/kwatchgnupg/index.docbook b/doc/kwatchgnupg/index.docbook
new file mode 100644
index 000000000..21b614b19
--- /dev/null
+++ b/doc/kwatchgnupg/index.docbook
@@ -0,0 +1,282 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY gnupg "<acronym>GnuPG</acronym>">
+  <!ENTITY gpgconf "<application>GPGConf</application>">
+  <!ENTITY watchgnupg "<application>WatchGnuPG</application>">
+  <!ENTITY kwatchgnupg "<application>KWatchGnuPG</application>">
+  <!ENTITY kappname "&kwatchgnupg;">
+  <!ENTITY package "kdepim">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE">
+]>
+
+<book lang="&language;">
+
+<bookinfo>
+<title>The &kwatchgnupg; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Marc</firstname>
+<othername></othername>
+<surname>Mutz</surname>
+<affiliation>
+<address><email>mutz@kde.org</email></address>
+</affiliation>
+</author>
+
+<othercredit role="developer">
+<firstname>Steffen</firstname>
+<surname>Hansen</surname>
+<contrib>Developer</contrib>
+<affiliation>
+<address><email>steffen@klaralvdalens-datakonsult.se</email></address>
+</affiliation>
+</othercredit>
+
+<othercredit role="developer">
+<firstname>David</firstname>
+<surname>Faure</surname>
+<affiliation>
+<address><email>faure@kde.org</email></address>
+</affiliation>
+<contrib>Developer</contrib>
+</othercredit>
+
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<legalnotice>&GPLNotice;</legalnotice>
+
+<date>2004-05-09</date>
+<releaseinfo>1.0</releaseinfo>
+
+<abstract>
+<para>
+&kwatchgnupg; is a simple &gnupg; log viewer.
+</para>
+</abstract>
+
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>Kapp</keyword>
+<keyword>gpg</keyword>
+<keyword>gpgsm</keyword>
+<keyword>GnuPG</keyword>
+<keyword>Log viewer</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction"> <title>Introduction</title> 
+
+<para>&kwatchgnupg; is simple &gnupg; log viewer for the upcoming
+&gnupg; versions 1.4 and 2.0. It works as a <acronym>GUI</acronym>
+wrapper around the command line tool &watchgnupg;, which listens on a
+socket for log lines from the &gnupg; backend applications. See
+<userinput>info watchgnupg</userinput> for more information about
+&watchgnupg;.</para>
+
+<para>&kwatchgnupg; can be started from the
+<menuchoice><guimenu>Tools</guimenu></menuchoice> menu of both
+<application>Kleopatra</application> and
+<application>KMail</application>, as well as from the command
+line. The &kwatchgnupg; executable is named
+<userinput>kwatchgnupg</userinput>.
+</para>
+
+</chapter>
+
+<chapter id="mainfunc"><title>Main Functions</title>
+
+<sect1 id="mainfunc.viewing"><title>Viewing the Log</title>
+
+<para>
+&kwatchgnupg;'s main function is of course to present the &gnupg;
+debugging and logging information to the user. The main window is
+divided into a large text viewing area, where &gnupg; messages will
+appear as they are generated, a toolbar giving quick access to the most
+often needed functions, as well as the obligatory menu bar.
+</para>
+
+<para>
+Each line in the text view is normally prefixed with a
+<acronym>FD</acronym> identifier and a time stamp in ISO format. The
+<acronym>FD</acronym> identifier can be used to distinguish between
+output from different &gnupg; instances running in parallel. Following
+the timestamp is the name of the component that is the source of the
+log line, together with some internal information in sqare brackets,
+followed by the original debugging or log output as printed by the
+component.
+</para>
+
+<para>
+By default, the number of log lines that are kept in the history is
+limited to 1000 lines. You can configure the history size in the
+configuration dialog.
+</para>
+
+</sect1>
+
+<sect1 id="mainfunc.saving">
+<title>Saving the Contents of the Log Window to a File</title>
+
+<para>
+Sometimes it might be convenient to save the current log window
+contents to a file, e.g. to mail it to the developers as part of a bug
+report. There are two ways to achieve this in &kwatchgnupg;:
+</para>
+
+<para>
+First, you can choose
+<menuchoice><guilabel>File</guilabel><guimenuitem>Save
+As...</guimenuitem></menuchoice> (or the corresponding toolbar icon)
+to save the complete log window contents to a file. You will be
+prompted to specify a save file location.
+</para>
+
+<para>
+Second, you can select the interesting lines with normal left-mouse
+selection and paste them into a word processor or mail user agent,
+just like any other text. You should make sure, though, that lines are
+not broken, since this reduces the readability of the log.
+</para>
+
+</sect1>
+
+<sect1 id="mainfunc.clear"><title>Clearing the Log Window</title>
+
+<para>
+For convenience, you can instruct &kwatchgnupg; to clear the log
+window using <menuchoice><guimenu>File</guimenu><guimenuitem>Clear
+History</guimenuitem></menuchoice> (or the corresponding toolbar
+icon).
+</para>
+
+<para>
+Use this prior to starting the crypto operation that you want to
+monitor to get only the output from that operation. You can then save
+the log using <menuchoice><guimenu>File</guimenu><guimenuitem>Save
+As...</guimenuitem></menuchoice> as described above.
+</para>
+
+<para>
+Clearing the log discards any previous log window contents. If you are
+unsure about whether you'll need the current contents afterwards, you
+should save them to a file (see above) before clearing.
+</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="configure"><title>Configuring &kwatchgnupg;</title>
+
+<para>
+To configure &kwatchgnupg;, select
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure
+&kwatchgnupg;</guimenuitem></menuchoice>, or the corresponding toolbar
+icon. &kwatchgnupg;'s configure dialog is divided into two parts, each
+of which will be described below.
+</para>
+
+<sect1 id="configure.watchgnupg"><title>&watchgnupg; Settings</title>
+
+<para>
+&watchgnupg; is the process that actually monitors the logging socket
+for activity and formats the lines as seen in the &kwatchgnupg; text
+view. Settings in this group are passed down to the backend using
+the &gpgconf; mechanism.
+</para>
+
+<para>
+<guilabel>Executable</guilabel> contains the path to the &watchgnupg;
+application. If &watchgnupg; is in your <varname>$PATH</varname>, you
+can keep the default <userinput>watchgnupg</userinput>. If
+&watchgnupg; is not in your <varname>$PATH</varname>, or if you have
+more than one version installed, enter the absolute filename of the
+watchgnupg executable here.
+</para>
+
+<para>
+<guilabel>Socket</guilabel> contains the socket that &watchgnupg;
+should listen on. A change here is distributed to all &gnupg; backend
+modules using &gpgconf;, so you don't need to change this setting if
+your &gnupg; config files have another <varname>log-file</varname>
+set.
+</para>
+
+<para>
+<guilabel>Default log level</guilabel> determines the amount of
+logging information returned by the backend modules. See the
+&watchgnupg; documentation for what level includes which
+information. A change here is distributed to all &gnupg; backend
+modules using &gpgconf;, so you don't need to change this setting if
+your &gnupg; config files have another <varname>log-level</varname>
+set.
+</para>
+
+</sect1>
+
+<sect1 id="configure.logwindow"><title>Log Window Settings</title>
+
+<para>
+Here, you can configure the size of the history buffer, &ie; the
+number of log lines that is kept. If more lines have been emitted by
+the &gnupg; backend since the last clearance of the history, then the
+oldest lines are discarded until there is enough room for the new
+lines again.
+</para>
+
+<para>
+You can disable the history size limit by clicking <guibutton>Set
+Unlimited</guibutton>. Note, however, that &kwatchgnupg;'s memory
+consumption will grow with the number of lines it currently
+displays. If you use an unlimited history size, then make sure to run
+&kwatchgnupg; only for short operations, or regularly clear the
+history manually.
+</para>
+
+</sect1>
+
+</chapter>
+
+<chapter id="credits-and-license">
+<title>Credits and License</title>
+
+<para>&kwatchgnupg; copyright 2004 Klar&auml;lvdalens Datakonsult AB</para>
+
+<para>Documentation copyright 2004 Klar&auml;lvdalens Datakonsult AB</para>
+
+<itemizedlist>
+<title>Contributors</title>
+<listitem>
+<para>Steffen Hansen <email>hansen@kde.org</email></para>
+</listitem>
+<listitem>
+<para>Marc Mutz <email>mutz@kde.org</email></para>
+</listitem>
+<listitem>
+<para>David Faure <email>faure@kde.org</email></para>
+</listitem>
+</itemizedlist>
+
+&underGPL;
+&underFDL;
+</chapter>
+
+&documentation.index; 
+</book>
+
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+
+// vim:ts=2:sw=2:tw=78:noet
+-->