[kde-doc-english] [kleopatra] doc: Add kwatchgnupg handbook

Mon Mar 7 11:59:22 UTC 2016

Git commit e903137ab2e7f2141381433416bb7e801f95ebd7 by Andre Heinecke.
Committed on 07/03/2016 at 11:58.
Pushed by aheinecke into branch 'master'.

Add kwatchgnupg handbook

With handbooks for kwatchgnupg and kleopatra we need subdirs in
doc, too.

M  +2    -2    doc/CMakeLists.txt
C  +0    -0    doc/kleopatra/CMakeLists.txt [from: doc/CMakeLists.txt - 100% similarity]
R  +0    -0    doc/kleopatra/index.docbook [from: doc/index.docbook - 100% similarity]
A  +2    -0    doc/kwatchgnupg/CMakeLists.txt
A  +280  -0    doc/kwatchgnupg/index.docbook

http://commits.kde.org/kleopatra/e903137ab2e7f2141381433416bb7e801f95ebd7

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 9061c41..0931343 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -1,2 +1,2 @@
-kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${KDE_INSTALL_DOCBUNDLEDIR}/en SUBDIR kleopatra)
-########### install files ###############
+add_subdirectory(kleopatra)
+add_subdirectory(kwatchgnupg)
diff --git a/doc/CMakeLists.txt b/doc/kleopatra/CMakeLists.txt
similarity index 100%
copy from doc/CMakeLists.txt
copy to doc/kleopatra/CMakeLists.txt
diff --git a/doc/index.docbook b/doc/kleopatra/index.docbook
similarity index 100%
rename from doc/index.docbook
rename to doc/kleopatra/index.docbook
diff --git a/doc/kwatchgnupg/CMakeLists.txt b/doc/kwatchgnupg/CMakeLists.txt
new file mode 100644
index 0000000..9bceb55
--- /dev/null
+++ b/doc/kwatchgnupg/CMakeLists.txt
@@ -0,0 +1,2 @@
+kdoctools_create_handbook(index.docbook INSTALL_DESTINATION ${KDE_INSTALL_DOCBUNDLEDIR}/en SUBDIR kwatchgnupg)
+
diff --git a/doc/kwatchgnupg/index.docbook b/doc/kwatchgnupg/index.docbook
new file mode 100644
index 0000000..6e7986a
--- /dev/null
+++ b/doc/kwatchgnupg/index.docbook
@@ -0,0 +1,280 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.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 id="kwatchgnupg" lang="&language;">
+
+<bookinfo id="kwatchgnupginfo">
+<title>The &kwatchgnupg; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Marc</firstname>
+<surname>Mutz</surname>
+<affiliation>
+<address>&Marc.Mutz.mail;</address>
+</affiliation>
+</author>
+
+<othercredit role="developer">
+<firstname>Steffen</firstname>
+<surname>Hansen</surname>
+<contrib>Developer</contrib>
+<affiliation>
+<address>&Steffen.Hansen.mail;</address>
+</affiliation>
+</othercredit>
+
+<othercredit role="developer">
+<firstname>David</firstname>
+<surname>Faure</surname>
+<affiliation>
+<address>&David.Faure.mail;</address>
+</affiliation>
+<contrib>Developer</contrib>
+</othercredit>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+<legalnotice>&GPLNotice;</legalnotice>
+
+<date>2013-07-03</date>
+<releaseinfo>1.0 (&kde; 4.11)</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 
+&gnupg; versions 1.4 and 2.0. It works as a &GUI;
+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><guimenuitem>GnuPG Log Viewer</guimenuitem></menuchoice> menu of both
+&kleopatra; and &kmail;, 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 10000 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, ⪚ 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älvdalens Datakonsult AB</para>
+
+<para>Documentation copyright 2004 Klarälvdalens Datakonsult AB</para>
+
+<itemizedlist>
+<title>Contributors</title>
+<listitem>
+<para>&Steffen.Hansen; <email>hansen at kde.org</email></para>
+</listitem>
+<listitem>
+<para>&Marc.Mutz; &Marc.Mutz.mail;</para>
+</listitem>
+<listitem>
+<para>&David.Faure; &David.Faure.mail;</para>
+</listitem>
+</itemizedlist>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+&underFDL;
+&underGPL;
+</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
+-->
