[gimp-help-2] Add documentation for GEGL Operation tool

[Ulf-D. Ehlert <ulfehlert src gnome org>]

commit 7a54654942b9b67534af97f71053ddca77646be4
Author: Ulf-D. Ehlert <ulfehlert svn gnome org>
Date:   Thu Feb 18 20:16:34 2010 +0100

    Add documentation for GEGL Operation tool

 images/C/toolbox/gegl-operation-gaussian-blur.png |  Bin 0 -> 8903 bytes
 images/C/toolbox/gegl-operation.png               |  Bin 0 -> 7883 bytes
 src/toolbox/gegl-operation.xml                    |  191 +++++++++++++++++++++
 src/toolbox/other-tools.xml                       |    6 +-
 4 files changed, 195 insertions(+), 2 deletions(-)
---
diff --git a/images/C/toolbox/gegl-operation-gaussian-blur.png b/images/C/toolbox/gegl-operation-gaussian-blur.png
new file mode 100644
index 0000000..36b0aea
Binary files /dev/null and b/images/C/toolbox/gegl-operation-gaussian-blur.png differ
diff --git a/images/C/toolbox/gegl-operation.png b/images/C/toolbox/gegl-operation.png
new file mode 100644
index 0000000..2af29d1
Binary files /dev/null and b/images/C/toolbox/gegl-operation.png differ
diff --git a/src/toolbox/gegl-operation.xml b/src/toolbox/gegl-operation.xml
new file mode 100644
index 0000000..0cbc1c3
--- /dev/null
+++ b/src/toolbox/gegl-operation.xml
@@ -0,0 +1,191 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+                       "http://www.docbook.org/xml/4.3/docbookx.dtd";>
+<!-- section history
+  2010-02-18 ude: created
+-->
+<sect2 id="gimp-tool-gegl">
+  <title>GEGL Operation</title>
+
+  <indexterm>
+    <primary>Tools</primary>
+    <secondary>GEGL operation</secondary>
+  </indexterm>
+  <indexterm>
+    <primary>GEGL operation</primary>
+  </indexterm>
+
+  <figure>
+    <title>GEGL Operation tool</title>
+    <mediaobject>
+      <imageobject>
+        <imagedata fileref="images/toolbox/gegl-operation.png" format="PNG"/>
+      </imageobject>
+    </mediaobject>
+  </figure>
+
+  <para>
+    <acronym>GEGL</acronym> (<quote>Generic Graphical Library</quote>) is a
+    graph based image processing library designed to handle various image
+    processing tasks needed in <acronym>GIMP</acronym>.
+  </para>
+  <para>
+    The <acronym>GEGL</acronym> Operation tool has been added in <link
+    linkend="gimp-introduction-whats-new"><acronym>GIMP</acronym> 2.6</link>
+    and was originally meant as an useful experimental tool for
+    <acronym>GIMP</acronym> developers. The <acronym>GEGL</acronym> Operation
+    tool enables applying <acronym>GEGL</acronym> operations to the image and
+    gives on-canvas previews of the results.
+  </para>
+  <warning>
+    <para>
+      <acronym>GEGL</acronym> is in a very early phase and still under
+      construction.
+    </para>
+    <para>
+      The GEGL Operation tool is <emphasis>experimental</emphasis>.
+    </para>
+  </warning>
+
+  <sect3>
+    <title>Activating the Tool</title>
+    <para>
+      You can get to this tool only from the image menu:
+      <menuchoice>
+        <guimenu>Tools</guimenu>
+        <guimenuitem>GEGL Operation</guimenuitem>
+      </menuchoice>.
+    </para>
+    <tip>
+      <para>
+        In addition to this tool for performing special
+        <acronym>GEGL</acronym> operations you can configure
+        <acronym>GIMP</acronym> to <link linkend="gimp-config-use-gegl">use
+        GEGL</link> for all color operations.
+      </para>
+    </tip>
+  </sect3>
+
+  <sect3>
+    <title>Options</title>
+    <figure>
+      <title>GEGEL Operation tool options</title>
+      <mediaobject>
+        <imageobject>
+          <imagedata format="PNG"
+            fileref="images/toolbox/gegl-operation.png"/>
+        </imageobject>
+        <caption>
+          <para>GEGEL Operation tool with no operation selected.</para>
+        </caption>
+      </mediaobject>
+    </figure>
+    <variablelist>
+      <varlistentry>
+        <term>Operation</term>
+        <listitem>
+          <para>
+            Click on this button to select the operation you want to apply to
+            the active selection or, if there is no selection, to the active
+            layer.
+          </para>
+          <para>
+            Some of these operations are very basic operations like
+            <quote>color</quote> which fills the active selection or layer
+            with the specified color, while operations like
+            <quote>fractal-explorer</quote> produce fairly complex patterns
+            &mdash; just like a <link linkend="filters-render">rendering
+            filter</link>.
+          </para>
+          <para>
+            Remember that this is an experimental tool, so some operations may
+            not work or even crash <acronym>GIMP</acronym>. As a consquence,
+            it doesn't make sense to describe the operations here as long as
+            the GEGL Operation tool is experimental
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>Operation Settings</term>
+        <listitem>
+          <para>
+            The operation settings depend on the selected
+            <guilabel>Operation</guilabel>:
+          </para>
+          <figure>
+            <title><quote>Operation Settings</quote> example</title>
+            <mediaobject>
+              <imageobject>
+                <imagedata format="PNG"
+                  fileref="images/toolbox/gegl-operation-gaussian-blur.png"/>
+              </imageobject>
+              <caption>
+                <para>
+                  GEGEL operation <quote>Gaussian Blur</quote> selected.
+                </para>
+              </caption>
+            </mediaobject>
+          </figure>
+          <para>
+            If the options of the selected <acronym>GEGL</acronym> operation
+            are not self-explanatory (guess what's the purpose of the
+            <quote>color</quote> operation's <quote>Color</quote> option)
+            you can look for a corresponding non-<acronym>GEGL</acronym> tool.
+            For example, the <link linkend="plug-in-fractalexplorer">Fractal
+            Explorer</link> filter may have the same or similar options as the
+            <quote>fractal-explorer</quote> operation.
+          </para>
+          <para>
+            Or you can make use of the nice realtime preview feature and just
+            experiment with different settings.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>Preview</term>
+        <listitem>
+          <para>
+            If this options is checked, as it is by default, you will get an
+            on-canvas preview of the selected operation as soon as the
+            operation in finished. You will have to press the
+            <guibutton>OK</guibutton> button to actually apply the operation
+            to the image.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+    <variablelist>
+      <title>The tool buttons</title>
+      <varlistentry>
+        <term>Reset</term>
+        <listitem>
+          <para>
+            Pressing this button resets the operation settings the to their
+            defaults.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>Cancel</term>
+        <listitem>
+          <para>
+            Clicking on this button aborts the <acronym>GEGL</acronym>
+            operation tool and leaves your image untouched. This is equivalent
+            to close the dialog window using the usual
+            <guibutton>Close</guibutton> button provided by your window
+            manager.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>OK</term>
+        <listitem>
+          <para>
+            You have to press this button to apply the selected operation to
+            the image. Then the dialog window will be closed.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </sect3>
+</sect2>
diff --git a/src/toolbox/other-tools.xml b/src/toolbox/other-tools.xml
index 7ab16d0..32c57fc 100644
--- a/src/toolbox/other-tools.xml
+++ b/src/toolbox/other-tools.xml
@@ -2,9 +2,10 @@
 <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
                        "http://www.docbook.org/xml/4.3/docbookx.dtd";>
 <!-- section history:
+  2010-02-18 ude: added GEGL Operations
   2007-06-03 kost: added 'no'
-  050817 axel.wernicke relocated blend to paint tools
-  050815 axel.wernicke relocated bucket fill to paint tools
+  2005-08-17 axel.wernicke relocated blend to paint tools
+  2005-08-15 axel.wernicke relocated bucket fill to paint tools
 -->
 <sect1 xmlns:xi="http://www.w3.org/2001/XInclude"; id="gimp-tools-other">
   <title>Other</title>
@@ -13,4 +14,5 @@
   <xi:include href="tool-zoom.xml"/>
   <xi:include href="tool-measure.xml"/>
   <xi:include href="tool-text.xml"/>
+  <xi:include href="gegl-operation.xml"/>
 </sect1>