summaryrefslogtreecommitdiffstats
path: root/doc/en/details-formats.docbook
diff options
context:
space:
mode:
authortpearson <tpearson@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2011-07-04 22:38:03 +0000
committertpearson <tpearson@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>2011-07-04 22:38:03 +0000
commitdadc34655c3ab961b0b0b94a10eaaba710f0b5e8 (patch)
tree99e72842fe687baea16376a147619b6048d7e441 /doc/en/details-formats.docbook
downloadkmymoney-dadc34655c3ab961b0b0b94a10eaaba710f0b5e8.tar.gz
kmymoney-dadc34655c3ab961b0b0b94a10eaaba710f0b5e8.zip
Added kmymoney
git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/applications/kmymoney@1239792 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
Diffstat (limited to 'doc/en/details-formats.docbook')
-rw-r--r--doc/en/details-formats.docbook185
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>
+