aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/C/Makefile.am18
-rw-r--r--doc/C/evolution-faq.sgml750
2 files changed, 762 insertions, 6 deletions
diff --git a/doc/C/Makefile.am b/doc/C/Makefile.am
index 90b0e0ea2f..cdf9d47dbe 100644
--- a/doc/C/Makefile.am
+++ b/doc/C/Makefile.am
@@ -1,6 +1,6 @@
evolution_helpdir = $(datadir)/gnome/help/evolution/C
-SGML_FILES = \
+GUIDE_SGML_FILES = \
evolution.sgml \
apx-authors.sgml \
apx-bugs.sgml \
@@ -15,15 +15,21 @@ SGML_FILES = \
usage-mainwindow.sgml \
usage-sync.sgml
+FAQ_SGML_FILES = \
+ evolution-faq.sgml
-EXTRA_DIST = \
- $(SGML_FILES)
+EXTRA_DIST = \
+ $(FAQ_SGML_FILES) \
+ $(GUIDE_SGML_FILES)
-all: evolution-guide
+all: evolution-guide evolution-faq
-evolution-guide: $(SGML_FILES)
+evolution-guide: $(GUIDE_SGML_FILES)
-db2html $(srcdir)/evolution.sgml
+evolution-faq: $(FAQ_SGML_FILES)
+ -db2html $(srcdir)/evolution-faq.sgml
+
dist-hook:
mkdir $(distdir)/evolution
-cp evolution/*.html evolution/*.css $(distdir)/evolution
@@ -32,7 +38,7 @@ dist-hook:
mkdir $(distdir)/evolution/stylesheet-images
-cp evolution/stylesheet-images/* $(distdir)/evolution/stylesheet-images
-install-data-local: evolution-guide
+install-data-local: evolution-guide evolution-faq
$(top_srcdir)/mkinstalldirs $(DESTDIR)$(evolution_helpdir)
-for file in $(srcdir)/evolution/*.html $(srcdir)/evolution/*.css; do \
basefile=`basename $$file`; \
diff --git a/doc/C/evolution-faq.sgml b/doc/C/evolution-faq.sgml
new file mode 100644
index 0000000000..cca5fb8a25
--- /dev/null
+++ b/doc/C/evolution-faq.sgml
@@ -0,0 +1,750 @@
+<!doctype article PUBLIC "-//Davenport//DTD DocBook V3.0//EN" []>
+
+ <article id="index">
+ <artheader>
+ <authorgroup>
+ <author>
+ <firstname>Ettore</firstname>
+ <surname>Perazzoli</surname>
+ </author>
+ <author>
+ <firstname>Duncan</firstname>
+ <surname>Mak</surname>
+ </author>
+ </authorgroup>
+
+ <title>Evolution Frequently Asked questions</title>
+ <abstract>
+ <para>
+ This is a FAQ list and yadda yadda.
+ </para>
+ </abstract>
+ </artheader>
+
+
+ <!-- Section: Getting and compiling -->
+
+ <sect1>
+ <title>
+ Getting and compiling
+ </title>
+
+ <!-- -->
+ <sect2>
+ <title>
+ Where can I get the latest Evolution release?
+ </title>
+
+ <para>
+ There are two main ways to install the latest Evolution
+ release:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ If you have Ximian GNOME installed, you can start Red
+ Carpet, Ximian's software updating system, and subscribe
+ to the Evolution channel. This will let you install a
+ binary for the latest release, and will also warn you
+ when a new version has been made available.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you want to compile from source, you can download the
+ latest official Evolution tarball from:
+ </para>
+
+ <para>
+ <ulink url="ftp://ftp.gnome.org/pub/GNOME/unstable/sources/evolution">
+ ftp://ftp.gnome.org/pub/GNOME/unstable/sources/evolution
+ </ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ Are binary snapshots available?
+ </title>
+
+ <para>
+ Yes, if you have Ximian GNOME installed. Just run Red
+ Carpet and subscribe to the Evolution Snapshot channel.
+ </para>
+
+ <para>
+ The snapshot builds are logged at <ulink
+ url="http://primates.ximian.com/~snapshot">http://primates.ximian.com/~snapshot</ulink>.
+ </para>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ Why isn't a new snapshot available today?
+ </title>
+
+ <para>
+ Sometimes the build might fail because of problems with the
+ source on CVS. In this case, just wait for next day's
+ snapshot.
+ </para>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ How do I get Evolution from CVS?
+ </title>
+
+ <para>
+ If you already have <ulink url="http://cvs.gnome.org">GNOME
+ CVS</ulink> access, simply checkout the following modules:
+ evolution, gtkhtml, gal.
+ </para>
+
+ <para>
+ If you don't have a CVS account, you could use anoncvs
+ instead. Bear in mind that anoncvs is only synchronized once a
+ day, and code received from anoncvs may not be latest version
+ available.
+ </para>
+
+ <para>
+ Before using the anoncvs server, you have to log into it.
+ This only needs to be done once.
+ </para>
+
+ <programlisting>
+cvs -z3 -d :pserver:anonymous@anoncvs.gnome.org:/cvs/gnome login
+ </programlisting>
+
+ <para>
+ Then you can retrieve the modules needed to compile Evolution
+ using the following command:
+ </para>
+
+ <programlisting>
+cvs -z3 -d :pserver:anonymous@anoncvs.gnome.org:/cvs/gnome co evolution gtkhtml gal
+ </programlisting>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ How should I compile Evolution avoiding conflicts with my
+ existing GNOME installation?
+ </title>
+
+ <para>
+ The best way is to install Evolution into a separate prefix.
+ In order to specify a non-default installation prefix, you can
+ pass the <parameter>--prefix</parameter> option to
+ <filename>configure</filename> or <filename>autogen.sh</filename>. For
+ example:
+ </para>
+
+ <programlisting>
+cd /cvs/evolution
+./autogen.sh --prefix=/opt/gnome
+ </programlisting>
+
+ <para>
+ If you install Evolution and the Evolution libraries in a
+ non-standard prefix, make sure you set the appropriate
+ environment variables in your shell's startup script:
+ </para>
+
+ <programlisting>
+export PATH=/opt/gnome:$PATH
+export GNOME_PATH=/opt/gnome:/usr
+ </programlisting>
+
+ <para>
+ You may also need to add <filename>$prefix/lib</filename>
+ (e.g. <filename>/opt/gnome/lib</filename>) to your
+ <filename>/etc/ld.so.conf</filename>. <!-- FIXME portable? -->
+ </para>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ I get <computeroutput>make: *** No rule to make target
+ `all-no-@BUILD_INCLUDED_LIBINTL@'</computeroutput>
+ </title>
+
+ <para>
+ You probably have <filename>gettext</filename> 0.10.36 or
+ later installed. Try downgrading to 0.10.35; unfortunately,
+ 0.10.36 introduced some incompatibilities with the current
+ <filename>xml-i18n-tools</filename>.
+ </para>
+ </sect2>
+
+ </sect1> <!-- End Section: Getting and compiling -->
+
+ <!-- Section: Troubleshooting -->
+
+ <sect1>
+ <title>Troubleshooting</title>
+
+ <!-- -->
+ <sect2>
+ <title>
+ I get <computeroutput>Cannot initialize the Evolution
+ shell</computeroutput>.
+ </title>
+
+ <para>
+ Check that:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename>oafd</filename> is listen in your <envar>PATH</envar>
+ environment variable.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename>GNOME_Evolution_Shell.oaf</filename> and
+ the other      
+ <filename>GNOME_Evolution_*.oaf</filename> files are
+ readable and installed in
+ <filename>$prefix/share/oaf</filename>, where
+ <filename>$prefix</filename> is one of the prefixes
+ listed in <envar>GNOME_PATH</envar> or
+ <envar>OAF_INFO_PATH</envar>.  (These variables are
+ supposed to contain $PATH-like colon-separated lists of
+ paths.  If the installation prefix for Evolution is
+ different from that). Run `oaf-slay' once before running
+ `evolution' again if you change $GNOME_PATH or
+ $OAF_INFO_PATH.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <filename>evolution</filename>,
+ <filename>evolution-mail</filename> and the other
+ <filename>evolution-*</filename> executables are in your
+ $PATH.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ I get <computeroutput>Cannot open composer window</computeroutput>.
+ </title>
+
+ <para>
+ This actually means that Evolution cannot activate the HTML
+ editor component from GtkHTML. The comments in the previous
+ answer still apply; also make sure that
+ <command>gnome-gtkhtml-editor</command> is in your
+ <envar>PATH</envar>.
+ </para>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ I updated my Evolution, but my addressbook contacts are no
+ longer there, what should I do?
+ </title>
+
+ <para>
+ Evolution uses the <filename>libdb</filename> library to
+ handle the addressbook database. Two versions of
+ <filename>libdb</filename> can be used with Evolution: version
+ 1.88 and version 2.
+ </para>
+
+ <para>
+ Unfortunately, an Evolution executable that is linked against
+ a certain version of <filename>libdb</filename> will only be
+ able to read addressbook files written by another Evolution
+ executable that is linked with the same version of the
+ library. If your addressbook is not readable by Evolution
+ anymore, it probably means that you used to have Evolution
+ linked with a certain version of <filename>libdb</filename>,
+ but now it gets linked to a different version.
+ </para>
+
+ <para>
+ Because of the way <filename>libdb</filename> is designed, it
+ is not easy for Evolution to automatically do the conversion
+ between the two formats. But, if your Evolution used to be
+ linked against version 1.85 and now is linked to version 2,
+ there is a very simple way to convert the database and recover
+ your data.
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ First of all, check the format of the database using the
+ <command>file</command> command:
+ </para>
+
+ <programlisting>
+file ~/evolution/local/Contacts/addressbook.db
+ </programlisting>
+
+ <para>
+ You want version 1.85 there. If version is 2, then your
+ current Evolution is probably linked against version 1.85
+ and you cannot convert the database to the old format.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Quit Evolution.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Make a copy of the addressbook database for backup
+ purposes.
+ </para>
+
+ <programlisting>
+cd ~/evolution/local/Contacts
+cp addressbook.db addressbook.db.backup
+ </programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ Convert the contacts to the new format using
+ <command>db_dump185</command> and
+ <command>db_load</command>:
+ </para>
+
+ <programlisting>
+db_dump185 ~/evolution/local/Contacts/addressbook.db.backup | db_load ~/evolution/local/Contacts/addressbook.db
+ </programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ Restart Evolution.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ Evolution crashes reporting that it couldn't allocate N
+ billion bytes; how do I fix this?
+ </title>
+
+ <para>
+ This usually happens when a component tries talking a
+ certain version of a CORBA interface to another component
+ that supports a different version. For example, this can
+ happen when you recompile and install a single component
+ without recompiling/installing the rest of Evolution.
+ </para>
+
+ <para>
+ So, if this occurs to you, make sure all the components are
+ compiled and installed at the same time. This also applies
+ to GtkHTML upgrades; after upgrading and installing a newer
+ GtkHTML, always re-compile and re-install Evolution against
+ it.
+ </para>
+
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ What is <command>killev</command> and why do I need to use it?
+ </title>
+
+ <para>
+ Evolution is actually made up of several components that run
+ as separate processes. Evolution's shell is not very good
+ at cleaning up stale processes, so it is possible that
+ sometimes already-running components cause unexpected and/or
+ broken behavior.
+ </para>
+
+ <para>
+ It's always a good idea to run <command>killev</command>
+ after a crash in Evolution, especially if the Evolution
+ shell itself crashed. (If a component crashes instead, you
+ should try to exit the shell cleanly first, so you give a
+ chance to the other components to clean things up properly.)
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>
+ What is <command>oaf-slay</command> and why do I need to use it?
+ </title>
+
+ <para>
+ <command>oaf-slay</command> is an utility which comes with
+ OAF, the Object Activation Framework that is used in the
+ GNOME Desktop to activate components. It will kill the
+ object activation daemon (<command>oafd</command>) as well
+ as all the active components on the system.
+ </para>
+
+ <para>
+ Normally, you shouldn't need t run
+ <command>oaf-slay</command>, unless <command>oafd</command>
+ gets stuck or confused. For example, it might help in case
+ Evolution cannot activate components.
+ </para>
+
+ <para>
+ Notice that <command>oaf-slay</command> will also confuse
+ Nautilus; a <command>nautilus-cleanup.sh -x</command> should
+ be enough to restart it properly, though.
+ </para>
+
+ </sect1> <!-- End Section: Troubleshooting -->
+
+
+ <!-- Section: Debugging -->
+
+ <sect1>
+ <title>
+ Debugging
+ </title>
+
+ <!-- -->
+ <sect2>
+ <title>
+ Where should I report bugs for Evolution?
+ </title>
+
+ <para>
+ You should report bugs about Evolution into the Ximian bug
+ reporting system (Bugzilla), located at <ulink
+ url="http://bugzilla.ximian.com">http://bugzilla.ximian.com</ulink>.
+ </para>
+
+ <para>
+ Please use the query function to check if a bug has been
+ submitted already before submitting it.
+ </para>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ Can I just use Bug-Buddy?
+ </title>
+
+ <para>
+ No. The Ximian bug tracker doesn't have an email-based
+ interface (yet), so Bug Buddy cannot talk to it. This will
+ be fixed eventually.
+ </para>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ What is a stack trace (backtrace) and how do I get one?
+ </title>
+
+ <para>
+ A stack trace is a list of the chain of function calls that
+ lead to some point in the program. Typically, you want to
+ get a stack trace when Evolution crashes or hangs and you
+ want to try to figure out where in the code that happened
+ and why. For this reason, stack traces are extremely useful
+ for the Evolution developers, so it's important that you
+ learn how to get them, and always include them in crash
+ reports.
+ </para>
+
+ <para>
+ First of all, in order to get a stack trace, your executable
+ (and possibly the libraries) must be compiled with debugging
+ symbols. Debugging symbols are created by default if you
+ compile from CVS, and are included in the; but if you decide
+ to compile by yourself with some custom CFLAGS value, make
+ sure <command>-g</command> is included in them.
+ </para>
+
+ <para>
+ Finally, you must run the component that crashes into
+ <command>gdb</command> before starting Evolution. Make sure
+ all the components are dead (exit Evolution and
+ <command>killev</command>), then run the following command:
+ </para>
+
+ <programlisting>
+gdb name-of-component
+ </programlisting>
+
+ <para>
+ Then, at the gdb prompt, type <userinput>r</userinput> (for
+ "run") and wait a few seconds to make sure the component has
+ registered with the name service. Then start Evolution
+ normally from a different terminal.
+ </para>
+
+ <para>
+ Then get Evolution to crash or to hang normally, and go back
+ to the terminal where you ran <command>gdb</command>. If
+ the component crashed, you should have a prompt there; otherwise, just hit
+ <keycombo action=simul>
+ <keycap>Control</keycap>
+ <keycap>C</keycap>
+ </keycombo>.
+ At the prompt, type:
+ </para>
+
+ <programlisting>
+info threads
+ </programlisting>
+
+ <para>
+ This will give you a list of the current running threads,
+ e.g.
+ </para>
+
+ <screen>
+(gdb) info threads
+ 8 Thread 6151 (LWP 14908) 0x409778fe in sigsuspend () from /lib/libc.so.6
+ 7 Thread 5126 (LWP 14907) 0x409778fe in sigsuspend () from /lib/libc.so.6
+ 6 Thread 4101 (LWP 1007) 0x409778fe in sigsuspend () from /lib/libc.so.6
+ 5 Thread 3076 (LWP 1006) 0x409778fe in sigsuspend () from /lib/libc.so.6
+ 4 Thread 2051 (LWP 1005) 0x409778fe in sigsuspend () from /lib/libc.so.6
+ 3 Thread 1026 (LWP 1004) 0x409778fe in sigsuspend () from /lib/libc.so.6
+ 2 Thread 2049 (LWP 1003) 0x40a10d90 in poll () from /lib/libc.so.6
+ 1 Thread 1024 (LWP 995) 0x40a10d90 in poll () from /lib/libc.so.6
+ </screen>
+
+ <para>
+ (Notice that, normally, only
+ <command>evolution-mail</command> will have more than one
+ thread.)
+ </para>
+
+ <para>
+ Now, for each of the thread listed, type the following
+ commands:
+ </para>
+
+ <programlisting>
+thread N
+bt
+ </programlisting>
+
+ <para>
+ Where `N' is the thread number. (In this example, you would
+ have to do it with N as 1, 2, 3... 8.) Then cut and paste
+ all the output into some text file, and quit
+ <command>gdb</command> by typing
+ <userinput>quit</userinput>.
+ </para>
+
+ <para>
+ You can also get a stack trace from a running component or a
+ component that has just crashed. Just start
+ <command>gdb</command> normally and, instead of using the
+ <userinput>r</userinput> command, use
+ <userinput>attach</userinput> to attach to the running
+ process:
+ </para>
+
+ <programlisting>
+attach PID
+ </programlisting>
+
+ <para>
+ Where <userinput>PID</userinput> is the PID of the
+ component. Notice that this also works if you attach right
+ after a crash dialog appears, before hitting "OK" or "Submit
+ bug report".
+ </para>
+ </sect2>
+
+ </sect1> <!-- End Section: Debugging -->
+
+
+ <!-- Section: Features -->
+
+ <sect1>
+ <title>
+ Features
+ </title>
+
+ <!-- -->
+ <sect2>
+ <title>
+ How can I remove a folder?
+ </title>
+
+ <para>
+ Currently there is no command in Evolution to remove a
+ folder, so you have to remove it by hand.
+ </para>
+
+ <para>
+ All the folders are stored in
+ <filename>~/evolution/local</filename>. Each folder is a
+ directory containing the data files, as well as a
+ <filename>subfolders</filename> directory that contains all
+ its subfolders. So for example if you have a subfolder of
+ the <filename>Inbox</filename> called
+ <filename>Foo</filename>, you can run the following command
+ to get rid of it (and all it subfolders):
+ </para>
+
+ <programlisting>
+rm -rf ~/evolution/local/Inbox/subfolders/Foo
+ </programlisting>
+
+ <para>
+ You should do this after exiting Evolution.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>
+ Why doesn't drag and drop between folders seem to work?
+ </title>
+
+ <para>
+ The implementation isn't finished, although it's planned to
+ be finished soon.
+ </para>
+
+ <para>
+ In the meantime, you can copy the folders' contents by hand
+ from the shell (please do this after quitting Evolution).
+ For example:
+ </para>
+
+ <programlisting>
+cp -r ~/evolution/local/Inbox/subfolders/Foo ~/evolution/local/Inbox/subfolders/Bar
+ </programlisting>
+
+ <para>
+ Likewise, you can use <command>mv</command> to rename or
+ move folders.
+ </para>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ Can I read mail from a mailbox file created by some other
+ application (e.g. Mutt) without importing mail from it?
+ </title>
+
+ <para>
+ No, but it's a planned feature.
+ </para>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ Can Evolution sync to my Palm OS (tm) device?
+ </title>
+
+ <para>
+ Yes. Evolution needs to be compiled with Palm syncing
+ support for this to work though. Please refer to the
+ <filename>README</filename> file for additional information
+ on the requirements.
+ </para>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ What is the difference between a virtual folder (vfolder)
+ and a regular folder?
+ </title>
+
+ <para>
+ FIXME: Put a description that doesn't suck here.
+ </para>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ Can Evolution spell-check the messages while I compose them?
+ </title>
+
+ <para>
+ Yes. The Evolution composer is able to highlight
+ mis-spelled word on the fly as you type them, and also give
+ you suggestions for possible corrections. In order for this
+ to work you need the <filename>gnome-spell</filename>
+ component which is not shipped with Ximian GNOME yet.
+ </para>
+
+ <para>
+ If you are brave enough, you can check out module
+ <filename>gnome-spell</filename> from the GNOME CVS and
+ compile it yourself. Check out its README file for a list
+ of <filename>gnome-spell</filename>'s requirements for
+ compilation.
+ </para>
+
+ <para>
+ Note that you don't need to recompile Evolution after
+ installing <filename>gnome-spell</filename>; it will be
+ picked up automatically.
+ </para>
+ </sect2>
+
+ <!-- -->
+ <sect2>
+ <title>
+ I cannot see the images that are contained in some HTML mail
+ message I am getting. Why?
+ </title>
+
+ <para>
+ Evolution currently doesn't support this, but it's a planned
+ feature.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>
+ Can I change the font that Evolution uses for compose and
+ displaying mail messages?
+ </title>
+
+ <para>
+ You have to change the GtkHTML settings for that: in the
+ GNOME Control Center, go to the "HTML Viewer" configuration
+ page, which is under the "Document Handlers" category.
+ </para>
+ </sect2>
+
+ </sect1> <!-- End Section: Features -->
+
+ </article>