Evolution users worldwide, rejoice! We have a FAQ. (Yes, it still

sucks, but it will get better.)

svn path=/trunk/; revision=9831

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>