bitbake: user-manual-metadata.xml: Re-write of "Events" section.

General cleanup of the text.

(Bitbake rev: 112dd4279826dc7587e1b8acb4a107374b5bd0fd)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 76 insertions, 33 deletions

diff --git a/bitbake/doc/user-manual/user-manual-metadata.xml b/bitbake/doc/user-manual/user-manual-metadata.xml
index ab3dcb19e4..5d7a9d753c 100644
--- a/bitbake/doc/user-manual/user-manual-metadata.xml
+++ b/bitbake/doc/user-manual/user-manual-metadata.xml
@@ -1340,19 +1340,21 @@
     <section id='events'>
         <title>Events</title>
 
-        <note>
-            This is only supported in <filename>.bb</filename>
-            and <filename>.bbclass</filename> files.
-        </note>
-
         <para>
-            BitBake allows installation of event handlers.
+            BitBake allows installation of event handlers within
+            recipe and class files.
             Events are triggered at certain points during operation,
             such as the beginning of operation against a given
             <filename>.bb</filename>, the start of a given task,
             task failure, task success, and so forth.
             The intent is to make it easy to do things like email
             notification on build failure.
+        </para>
+
+        <para>
+            Following is an example event handler that
+            prints the name of the event and the content of
+            the <filename>FILE</filename> variable:
             <literallayout class='monospaced'>
      addhandler myclass_eventhandler
      python myclass_eventhandler() {
@@ -1364,42 +1366,83 @@
             </literallayout>
             This event handler gets called every time an event is
             triggered.
-            A global variable "<filename>e</filename>" is defined.
+            A global variable "<filename>e</filename>" is defined and
             "<filename>e.data</filename>" contains an instance of
             "<filename>bb.data</filename>".
-            With the <filename>getName(e)</filename> method one can get
+            With the <filename>getName(e)</filename> method, one can get
             the name of the triggered event.
         </para>
 
         <para>
-            The above event handler prints the name of the event
-            and the content of the <filename>FILE</filename> variable.
-            During a Build, the following common events occur:
+            During all builds, the following common events occur:
             <itemizedlist>
-                <listitem><para><filename>bb.event.ConfigParsed()</filename></para></listitem>
-                <listitem><para><filename>bb.event.ParseStarted()</filename></para></listitem>
-                <listitem><para><filename>bb.event.ParseProgress()</filename></para></listitem>
-                <listitem><para><filename>bb.event.ParseCompleted()</filename></para></listitem>
-                <listitem><para><filename>bb.event.BuildStarted()</filename></para></listitem>
-                <listitem><para><filename>bb.build.TaskStarted()</filename></para></listitem>
-                <listitem><para><filename>bb.build.TaskInvalid()</filename></para></listitem>
-                <listitem><para><filename>bb.build.TaskFailedSilent()</filename></para></listitem>
-                <listitem><para><filename>bb.build.TaskFailed()</filename></para></listitem>
-                <listitem><para><filename>bb.build.TaskSucceeded()</filename></para></listitem>
-                <listitem><para><filename>bb.event.BuildCompleted()</filename></para></listitem>
-                <listitem><para><filename>bb.cooker.CookerExit()</filename></para></listitem>
+                <listitem><para>
+                    <filename>bb.event.ConfigParsed()</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.ParseStarted()</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.ParseProgress()</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.ParseCompleted()</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.BuildStarted()</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.build.TaskStarted()</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.build.TaskInvalid()</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.build.TaskFailedSilent()</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.build.TaskFailed()</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.build.TaskSucceeded()</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.BuildCompleted()</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.cooker.CookerExit()</filename>
+                    </para></listitem>
             </itemizedlist>
-            Other events that occur based on specific requests to the server:
+            Here is a list of other events that occur based on specific requests
+            to the server:
             <itemizedlist>
-                <listitem><para><filename>bb.event.TreeDataPreparationStarted()</filename></para></listitem>
-                <listitem><para><filename>bb.event.TreeDataPreparationProgress</filename></para></listitem>
-                <listitem><para><filename>bb.event.TreeDataPreparationCompleted</filename></para></listitem>
-                <listitem><para><filename>bb.event.DepTreeGenerated</filename></para></listitem>
-                <listitem><para><filename>bb.event.CoreBaseFilesFound</filename></para></listitem>
-                <listitem><para><filename>bb.event.ConfigFilePathFound</filename></para></listitem>
-                <listitem><para><filename>bb.event.FilesMatchingFound</filename></para></listitem>
-                <listitem><para><filename>bb.event.ConfigFilesFound</filename></para></listitem>
-                <listitem><para><filename>bb.event.TargetsTreeGenerated</filename></para></listitem>
+                <listitem><para>
+                    <filename>bb.event.TreeDataPreparationStarted()</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.TreeDataPreparationProgress</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.TreeDataPreparationCompleted</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.DepTreeGenerated</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.CoreBaseFilesFound</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.ConfigFilePathFound</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.FilesMatchingFound</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.ConfigFilesFound</filename>
+                    </para></listitem>
+                <listitem><para>
+                    <filename>bb.event.TargetsTreeGenerated</filename>
+                    </para></listitem>
             </itemizedlist>
         </para>
     </section>