diff options
Diffstat (limited to 'doc/en/details-formats.docbook')
| -rw-r--r-- | doc/en/details-formats.docbook | 185 |
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> + |