diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.xml b/en_US.ISO8859-1/books/handbook/x11/chapter.xml
index 071530b4b2..cd331ff1dc 100644
--- a/en_US.ISO8859-1/books/handbook/x11/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/x11/chapter.xml
@@ -1239,6 +1239,198 @@ DisplayManager.requestPort: 0</screen>
</sect2>
</sect1>
+ <sect1 xml:id="x-compiz-fusion">
+ <title>Installing Compiz Fusion</title>
+
+ <para>One way to increase the pleasantness of using a desktop
+ computer is by having nice 3D effects.</para>
+
+ <para>Installing the <application>Compiz Fusion</application>
+ package is easy, but configuring it requires a few steps that
+ are not described in the port's documentation.</para>
+
+ <sect2 xml:id="x-compiz-video-card">
+ <title>Setting up the &os; nVidia driver</title>
+
+ <para>Desktop effects can cause quite a load on the graphics card.
+ For an an nVidia-based graphics card, the proprietary driver
+ is required for good performance. Users of other graphics
+ cards can skip this section and continue with the
+ <filename>xorg.conf</filename> configuration.</para>
+
+ <para>
+ To determine which nVidia driveris needed see the <link xlink:href="&url.books.faq;/x.html#idp59950544">FAQ question
+ on the subject</link>.
+ </para>
+
+ <para>Having determined the correct driver to use for your card,
+ installation is as simple as installing any other package.</para>
+
+ <para>For example, to install the latest driver:</para>
+
+ <screen>&prompt.root; <userinput>pkg install x11/nvidia-driver</userinput></screen>
+
+ <para>The driver will create a kernel module, which needs to be loaded
+ at system startup. Add the following line to
+ <filename>/boot/loader.conf</filename>:</para>
+
+ <programlisting>nvidia_load="YES"</programlisting>
+
+ <note>
+ <para>To immediately load the kernel module into the
+ running kernel by issuing a command like
+ <command>kldload nvidia</command>, however it has been noted that
+ the some versions of <application>&xorg;</application> will not
+ function properly if the driver is not loaded at boot time. After
+ editing <filename>/boot/loader.conf</filename>, a reboot is
+ recommended.</para>
+ </note>
+
+ <para>With the kernel module loaded, you normally only need to change
+ a single line in your <filename>xorg.conf</filename> file to enable
+ the proprietary driver:</para>
+
+ <para>Find the following line in
+ <filename>/etc/X11/xorg.conf</filename>:</para>
+
+ <programlisting>Driver "nv"</programlisting>
+
+ <para>and change it to:</para>
+
+ <programlisting>Driver "nvidia"</programlisting>
+
+ <para>Start the GUI as usual, and you should be greeted by the
+ nVidia splash. Everything should work as usual.</para>
+ </sect2>
+
+ <sect2 xml:id="xorg-configuration">
+ <title>Configuring xorg.conf for desktop effects</title>
+
+ <para>To enable <application>Compiz Fusion</application>,
+ <filename>/etc/X11/xorg.conf</filename> needs to be
+ modified:</para>
+
+ <para>Add the following section to enable composite effects:</para>
+
+ <programlisting>Section "Extensions"
+ Option "Composite" "Enable"
+ EndSection</programlisting>
+
+ <para>Locate the <quote>Screen</quote> section which should look similar
+ to the one below:</para>
+
+ <programlisting>Section "Screen"
+ Identifier "Screen0"
+ Device "Card0"
+ Monitor "Monitor0"
+ ...</programlisting>
+
+ <para>and add the following two lines (after <quote>Monitor</quote> will
+ do):</para>
+
+ <programlisting>DefaultDepth 24
+ Option "AddARGBGLXVisuals" "True"</programlisting>
+
+ <para>Locate the <quote>Subsection</quote> that refers to the
+ screen resolution that you wish to use. For example, if you wish to
+ use 1280x1024, locate the section that follows. If the desired
+ resolution does not appear in any subsection, you may add the relevant
+ entry by hand:</para>
+
+ <programlisting>SubSection "Display"
+ Viewport 0 0
+ Modes "1280x1024"
+ EndSubSection</programlisting>
+
+ <para>A color depth of 24 bits is needed for desktop composition,
+ change the above subsection to:</para>
+
+ <programlisting>SubSection "Display"
+ Viewport 0 0
+ Depth 24
+ Modes "1280x1024"
+ EndSubSection</programlisting>
+
+ <para>Finally, confirm that the <quote>glx</quote> and
+ <quote>extmod</quote> modules are loaded in the <quote>Module</quote>
+ section:</para>
+
+ <programlisting>Section "Module"
+ Load "extmod"
+ Load "glx"
+ ...</programlisting>
+
+ <para>The preceding can be done automatically with
+ <package>x11/nvidia-xconfig</package> by running (as
+ root):</para>
+
+ <screen>&prompt.root; <userinput>nvidia-xconfig --add-argb-glx-visuals</userinput>
+ &prompt.root; <userinput>nvidia-xconfig --composite</userinput>
+ &prompt.root; <userinput>nvidia-xconfig --depth=24</userinput></screen>
+ </sect2>
+
+ <sect2 xml:id="compiz-fusion">
+ <title>Installing and configuring Compiz Fusion</title>
+
+ <para>Installing <application>Compiz Fusion</application>
+ is as simple as any other package:</para>
+
+ <screen>&prompt.root; <userinput>pkg install x11-wm/compiz-fusion</userinput></screen>
+
+ <para>When the installation is finished, start your graphic desktop and
+ at a terminal, enter the following commands (as a normal user):</para>
+
+ <screen>&prompt.user; <userinput>compiz --replace --sm-disable --ignore-desktop-hints ccp &</userinput>
+ &prompt.user; <userinput>emerald --replace &</userinput></screen>
+
+ <para>Your screen will flicker for a few seconds, as your window manager
+ (e.g. <application>Metacity</application> if you are using
+ <application>GNOME</application>) is replaced by
+ <application>Compiz Fusion</application>.
+ <application>Emerald</application> takes care of the window
+ decorations (i.e. close, minimize, maximize buttons, title bars
+ and so on).</para>
+
+ <para>You may convert this to a trivial script and have it run at
+ startup automatically (e.g. by adding to <quote>Sessions</quote> in
+ a <application>GNOME</application> desktop):</para>
+
+ <programlisting>#! /bin/sh
+ compiz --replace --sm-disable --ignore-desktop-hints ccp &
+ emerald --replace &</programlisting>
+
+ <para>Save this in your home directory as, for example,
+ <filename>start-compiz</filename> and make it executable:</para>
+
+ <screen>&prompt.user; <userinput>chmod +x ~/start-compiz</userinput></screen>
+
+ <para>Then use the GUI to add it to
+ <guimenuitem>Startup Programs</guimenuitem>
+ (located in <guimenuitem>System</guimenuitem>,
+ <guimenuitem>Preferences</guimenuitem>,
+ <guimenuitem>Sessions</guimenuitem> on a
+ <application>GNOME</application> desktop).</para>
+
+ <para>To actually select all the desired effects and their settings,
+ execute (again as a normal user) the
+ <application>Compiz Config Settings Manager</application>:</para>
+
+ <screen>&prompt.user; <userinput>ccsm</userinput></screen>
+
+ <note>
+ <para>In <application>GNOME</application>, this can also be found in
+ the <guimenuitem>System</guimenuitem>,
+ <guimenuitem>Preferences</guimenuitem> menu.</para>
+ </note>
+
+ <para>If you have selected <quote>gconf support</quote> during the build,
+ you will also be able to view these settings using
+ <command>gconf-editor</command> under <literal>apps/compiz</literal>.
+ </para>
+ </sect2>
+
+ </sect1>
+
<sect1 xml:id="x11-understanding">
<title>Troubleshooting</title>
@@ -1520,5 +1712,52 @@ EndSection</programlisting>
<para>Now having completed these simple editing steps, X
should start on your new widescreen monitor.</para>
</sect2>
- </sect1>
- </chapter>
+
+ <sect2 xml:id="compiz-troubleshooting">
+ <title>Troubleshooting Compiz Fusion</title>
+
+ <qandaset>
+ <qandaentry>
+ <question xml:id="no-decorations">
+ <para>I have installed
+ <application>Compiz Fusion</application>,
+ and after running the commands you mention, my windows are left
+ without title bars and buttons. What is wrong?</para>
+ </question>
+
+ <answer>
+ <para>You are probably missing a setting in
+ <filename>/etc/X11/xorg.conf</filename>. Review this file
+ carefully and check especially the <literal>DefaultDepth</literal>
+ and <literal>AddARGBGLXVisuals</literal> directives.</para>
+ </answer>
+ </qandaentry>
+
+ <qandaentry>
+ <question xml:id="xorg-crash">
+ <para>When I run the command to start
+ <application>Compiz Fusion</application>, the X server
+ crashes and I am back at the console. What is wrong?</para>
+ </question>
+
+ <answer>
+ <para>If you check your <filename>/var/log/Xorg.0.log</filename>
+ file, you will probably find error messages during the X
+ startup. The most common would be:</para>
+
+ <screen>(EE) NVIDIA(0): Failed to initialize the GLX module; please check in your X
+ (EE) NVIDIA(0): log file that the GLX module has been loaded in your X
+ (EE) NVIDIA(0): server, and that the module is the NVIDIA GLX module. If
+ (EE) NVIDIA(0): you continue to encounter problems, Please try
+ (EE) NVIDIA(0): reinstalling the NVIDIA driver.</screen>
+
+ <para>This is usually the case when you upgrade
+ <application>&xorg;</application>. You will need to reinstall the
+ <package>x11/nvidia-driver</package> package so
+ glx is built again.</para>
+ </answer>
+ </qandaentry>
+ </qandaset>
+ </sect2>
+ </sect1>
+</chapter>