diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/C/Makefile.am | 18 | ||||
| -rw-r--r-- | doc/C/evolution-faq.sgml | 750 |
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> |