Updating plugin documentation.

Extending debugging section a bit, and claryyhing why some content is
missing. Also linking into new development section at top-level.

CHANGES

@@ -1,4 +1,8 @@
 
+2.3-225 | 2014-10-07 15:13:35 -0700
+
+  * Updating plugin documentation. (Robin Sommer)
+
 2.3-224 | 2014-10-07 14:32:17 -0700
 
   * Improved the log file reference documentation. (Jeannette Dopheide

VERSION

@@ -1 +1 @@
-2.3-224
+2.3-225

doc/devel/plugins.rst

@@ -265,23 +265,25 @@ plugins to unconditionally activate, even in bare mode.
 activated plugins. Note that plugins compiled statically into Bro are
 always activated, and hence show up as such even in bare mode.
 
-Plugin Component
+Plugin Components
-================
+=================
 
-The following gives additional information about providing individual
+The following subsections detail providing individual types of
-types of functionality via plugins. Note that a single plugin can
+functionality via plugins. Note that a single plugin can provide more
-provide more than one type. For example, a plugin could provide
+than one component type. For example, a plugin could provide multiple
-multiple protocol analyzers at once; or both a logging backend and
+protocol analyzers at once; or both a logging backend and input reader
-input reader at the same time.
+at the same time.
 
-We now walk briefly through the specifics of providing a specific type
+.. todo::
-of functionality (a *component*) through a plugin. We'll focus on
+
-their interfaces to the plugin system, rather than specifics on
+    These subsections are mostly missing right now, as much of their
-writing the corresponding logic (usually the best way to get going on
+    content isn't actually plugin-specific, but concerns generally
-that is to start with an existing plugin providing a corresponding
+    writing such functionality for Bro. The best way to get started
-component and adapt that). We'll also point out how the CMake
+    right now is to look at existing code implementing similar
-infrastructure put in place by the ``init-plugin`` helper script ties
+    functionality, either as a plugin or inside Bro proper. Also, for
-the various pieces together.
+    each component type there's a unit test in
+    ``testing/btest/plugins`` creating a basic plugin skeleton with a
+    corresponding component.
 
 Bro Scripts
 -----------
@@ -412,25 +414,32 @@ Run the test-suite::
 Debugging Plugins
 =================
 
-Plugins can use Bro's standard debug logger by using the
+If your plugin isn't loading as expected, Bro's debugging facilities
-``PLUGIN_DBG_LOG(<plugin>, <args>)`` macro (defined in
+can help to illuminate what's going on. To enable, recompile Bro
-``DebugLogger.h``), where ``<plugin>`` is the ``Plugin`` instance and
+with debugging support (``./configure --enable-debug``), and
-``<args>`` are printf-style arguments, just as with Bro's standard
+afterwards rebuild your plugin as well. If you then run Bro with ``-B
-debuggging macros.
+plugins``, it will produce a file ``debug.log`` that records details
+about the process for searching, loading, and activating plugins. 
 
-At runtime, one then activates a plugin's debugging output with ``-B
+To generate your own debugging output from inside your plugin, you can
-plugin-<name>``, where ``<name>`` is the name of the plugin as
+add a custom debug stream by using the ``PLUGIN_DBG_LOG(<plugin>,
-returned by its ``Configure()`` method, yet with the
+<args>)`` macro (defined in ``DebugLogger.h``), where ``<plugin>`` is
-namespace-separator ``::`` replaced with a simple dash. Example: If
+the ``Plugin`` instance and ``<args>`` are printf-style arguments,
-the plugin is called ``Bro::Demo``, use ``-B plugin-Bro-Demo``. As
+just as with Bro's standard debugging macros (grep for ``DBG_LOG`` in
-usual, the debugging output will be recorded to ``debug.log`` if Bro's
+Bro's ``src/`` to see examples). At runtime, you can then activate
-compiled in debug mode.
+your plugin's debugging output with ``-B plugin-<name>``, where
+``<name>`` is the name of the plugin as returned by its
+``Configure()`` method, yet with the namespace-separator ``::``
+replaced with a simple dash. Example: If the plugin is called
+``Bro::Demo``, use ``-B plugin-Bro-Demo``. As usual, the debugging
+output will be recorded to ``debug.log`` if Bro's compiled in debug
+mode.
 
 
 Documenting Plugins
 ===================
 
-..todo::
+.. todo::
 
     Integrate all this with Broxygen.
 

doc/index.rst

@@ -45,7 +45,13 @@ Reference Section
    script-reference/index.rst
    components/index.rst
 
-..
+Development
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+   devel/plugins.rst
 
 * :ref:`General Index <genindex>`
 * :ref:`search`