Added kmymoney

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

1 files changed, 185 insertions, 0 deletions

diff --git a/doc/en/details-formats.docbook b/doc/en/details-formats.docbook
new file mode 100644
index 0000000..a6fe07f
--- /dev/null
+++ b/doc/en/details-formats.docbook
@@ -0,0 +1,185 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="details.formats">
+<chapterinfo>
+  <authorgroup>
+    <author>
+      <firstname>Thomas</firstname>
+      <surname>Baumgart</surname>
+      <affiliation>
+       <address><email>ipwizard@users.sourceforge.net</email></address>
+      </affiliation>
+    </author>
+  </authorgroup>
+  <date>2009-05-08</date>
+  <releaseinfo>1.0</releaseinfo>
+</chapterinfo>
+
+<title>File Formats</title>
+
+<para>
+  This chapter describes the formats in which &kappname; stores its data in
+  permanent form on the user's storage device. In general, &kappname; stores its
+  information in form of an &XML; document. Depending on the actual format, this
+  &XML; document will be written
+
+<itemizedlist>
+  <listitem><para>as a <link linkend="details.formats.plain">plain text
+    file</link> encoded in UTF-8,</para></listitem>
+
+  <listitem><para>as a <link linkend="details.formats.compressed">compressed
+    file</link> using GZIP compression,</para></listitem>
+
+  <listitem><para>as an <link linkend="details.formats.encrypted">encrypted
+  file</link> using GPG encryption, or</para></listitem>
+
+  <listitem><para>as an <link linkend="details.formats.anonymous">anonymous
+    plain text file</link> encoded in UTF-8 but with all your personal data
+    scrambled.</para></listitem>
+</itemizedlist>
+</para>
+
+<sect1 id="details.formats.plain">
+<title>Plain text file</title>
+<para>
+  This is the most space consuming format supported, as no compression is
+  performed. It is not intended for normal use, and is provided to support
+  debugging purposes and the capability to modify the file manually. If you end
+  a filename in <literal role="extension">.xml</literal>, the file will be
+  stored in this format.
+
+<caution>
+  <para>
+    Manual modification of the file is not recommended to the normal user, and
+    should only be performed if the internal working of &kappname; is fully
+    understood or if instructions from the developers tell you what to do. Don't
+    blame the &kappname; developers if you screw up your data: You have been
+    warned!
+  </para>
+</caution>
+</para>
+</sect1>
+
+<sect1 id="details.formats.compressed">
+<title>GZIP-compressed file</title>
+<para>
+  This is the normal format used by &kappname; when you store a file with the
+  extension <literal role="extension">.kmy</literal>.
+</para>
+
+<note>
+  <para>
+    If <link linkend="details.formats.encrypted">encryption</link> has been
+    selected, the file will be stored encrypted.
+  </para>
+</note>
+
+<para>
+  If you want to look at the contents of a GZIP compressed file, rename it to a
+  filename ending in <literal role="extension">.gz</literal> (e.g.,
+  rename <filename>myfinances.kmy</filename>
+  to <filename>myfinances.kmy.gz</filename>), then use <command>gunzip</command>
+  to uncompress the file and look at it. You don't have to compress it before
+  loading it into &kappname; the next time, because &kappname; can read the
+  uncompressed data as well. Nevertheless, if you save it thereafter, it will be
+  saved compressed again. Use
+  the <link linkend="details.formats.plain">.xml</link> extension to write it in
+  uncompressed format.
+</para>
+</sect1>
+
+<sect1 id="details.formats.encrypted">
+<title>GPG-encrypted file</title>
+<para>
+  Using the GPG-encrypted file format is a very secure method of storing your
+  personal finance data on your storage device. When &kappname; has been
+  instructed through the settings dialog to store your data encrypted, it will
+  cipher the data using GPG and the key you provided before actually storing
+  it. When opening an encrypted file, you have to provide the passphrase
+  necessary to open your keyring. The encrypted file itself will be stored in
+  GPG's <emphasis>ASCII armored</emphasis> format.
+  <note>
+    <para>
+      When using GPG encryption, GPG also compresses the file, so no extra
+      compression is necessary.
+    </para>
+  </note>
+</para>
+
+<sect2 id="details.formats.encrypted.gpgkeys">
+<title>GPG-Keys</title>
+<para>
+  If you have not done so already for mail encryption, you need to generate a
+  key-pair in order to use the GPG encryption feature of
+  &kappname;. Also, <application>GPG</application> must be installed on your
+  system.
+</para>
+
+<para>
+  The details about how to generate a key-pair and how to take care of it are
+  beyond the scope of this document.  A Mini Howto on this subject can be found
+  at <ulink url="http://www.gnupg.org/documentation/howtos.en.html">http://www.gnupg.org/documentation/howtos.en.html</ulink>.
+</para>
+</sect2>
+
+<sect2 id="details.formats.encrypted.keysettings">
+<title>Setting the keys in &kappname;</title>
+<para>
+  On the encryption page of the settings dialog, there is a drop down 
+  list where you can select the key that should be used for encryption and 
+  decryption. Additionally you can find a field where you can enter the 
+  key-id of a key not in the listbox. You can use either the key-id, the 
+  email address associated with this key, or any other valid GPG key 
+  identification as the value for this field. When you enter the key-id, 
+  &kappname; will check its validity and display a green LED icon in the 
+  dialog if a key is found.
+  <caution>
+    <para>
+      Make sure you have both the public and the private key for this id. If you
+      do not own the private key for the id entered, you will not be able to
+      open the file again.
+    </para>
+  </caution>
+</para>
+</sect2>
+
+<sect2 id="details.formats.encrypted.recoverkey">
+<title>The &kappname; recover key</title>
+<para>
+  Also on this page of the settings dialog you have the choice of selecting
+  supplemental encryption with the &kappname; recover key. This option is
+  available to you if that key is stored in your <application>GPG</application>
+  keyring. Selecting this option will allow you to recover your data even in the
+  case you lose your own private key. This is possible because the data is not
+  only encrypted for your own key, but also for the &kappname; recover key. This
+  key is only available to selected &kappname; developers (at the time of
+  writing only to the author).
+</para>
+
+<para>
+  Under normal circumstances, you will open/save/close your file as usual. In
+  the abnormal case of loss of your key, you have the chance to contact one of
+  the developers who has access to the &kappname; recover key and request help
+  to recover your data. You may contact the developers via email to the
+  &kappname; developer mailing list at &devlist;.
+</para>
+</sect2>
+</sect1>
+
+<sect1 id="details.formats.anonymous">
+<title>Anonymous file</title>
+<para>
+  This format is not intended to be used for normal data storage. It is
+  supported in case of a problem as a method of supplying the &kappname;
+  development team with your file without disclosing any of your financial
+  data. If instructed by the developers, use the <guimenuitem>Save
+  as...</guimenuitem> menu item to store your data in anonymous format by
+  selecting <literal role="extension">.anon.xml</literal> as the file
+  extension. To verify that your problem still exists, reload this anonymized
+  file and try to duplicate your problem. If the problem is still present, send
+  the file to the developer mailing list at &devlist; for further
+  investigation. If the problem does not show ... well, I don't want to think
+  about this scenario right now.
+</para>
+</sect1>
+</chapter>
+