Merge remote-tracking branch 'origin/fastpath'

* origin/fastpath:
  Update script doc-generation README.
  Omission of bro.init from doc generation fixed.
  Fixing docstrings to make docutils happy.
  Updated submodules to current master

CHANGES

@@ -1,4 +1,21 @@
 
+1.6-dev-1038 | 2011-08-05 18:25:44 -0700
+
+  * Smaller updates to script docs and their generation. (Jon Siwek)
+
+  * When using a `print` statement to write to a file that has raw output
+    enabled, NUL characters in string are no longer interpreted into "\0",
+    no newline is appended afterwards, and each argument to `print` is
+    written to the file without any additional separation. (Jon Siwek)
+
+  * Test portatibility tweaks. (Jon Siwek)
+
+  * Fixing PktSrc::Statistics() which retured bogus information
+    offline mode. Closes #500. (Jon Siwek)
+
+  * --with-perftools configure option now assumes --enable-perftools.
+    Closes #527. (Jon Siwek)
+
 1.6-dev-1018 | 2011-07-31 21:30:31 -0700
 
   * Updating CHANGES. (Robin Sommer)

VERSION

@@ -1 +1 @@
-1.6-dev-1018
+1.6-dev-1038

doc/scripts/DocSourcesList.cmake

@@ -13,6 +13,7 @@
 set(psd ${PROJECT_SOURCE_DIR}/policy)
 
 rest_target(${CMAKE_CURRENT_SOURCE_DIR} example.bro internal)
+rest_target(${psd} bro.init internal)
 
 rest_target(${CMAKE_BINARY_DIR}/src bro.bif.bro)
 rest_target(${CMAKE_BINARY_DIR}/src const.bif.bro)

doc/scripts/README

@@ -38,20 +38,26 @@ by CMake:
 
     This target removes Sphinx inputs and outputs from the CMake ``build/`` dir.
 
-To schedule a script to be documented, edit ``DocSourcesList.cmake`` inside
+The ``genDocSourcesList.sh`` script can be run to automatically generate
-this directory add a call to the ``rest_target()`` macro.  Calling that macro
+``DocSourcesList.cmake``, which is the file CMake uses to define the list
-with a group name for the script is optional.  If the group is omitted, the
+of documentation targets.  This script should be run after adding new
-only links to the script will be in the master TOC tree for all policy scripts
+Bro script source files, and the changes commited to git.
-as well as the master TOC tree for script packages (derived from the path
-component of the second argument to ``rest_target()``), with the exception
-of ``.bif`` files which are grouped automatically.
 
-When adding a new logical grouping e.g. "my/group" (groups are allowed
+If a script shouldn't have documentation generated for it, there's also a
-to contain slashes specifying a path) for generated scripts,
+blacklist variable that can be maintained in the ``genDocSourcesList.sh``
-create a new reST document in ``source/my/group.rst`` and add some default
+script.
-documentation for the group.  References to (and summaries of) documents
+
-associated with the group get appended to this pre-created file during the
+The blacklist can also be used if you want to define a certain grouping for
-``make doc`` process.
+the script's generated docs to belong to (as opposed to the automatic grouping
+the happens for script packages/directories).  To do that, add the
+script's name to the blacklist, then append a ``rest_target()`` to the
+``statictext`` variable where the first argument is the source directory
+containing the policy script to document, the second argument is the file
+name of the policy script, and the third argument is the path/name of a
+pre-created reST document in the ``source/`` directory to which the
+``make doc`` process can append script documentation references.  This
+pre-created reST document should also then be linked to from the TOC tree
+in ``source/index.rst``.
 
 The Sphinx source tree template in ``source/`` can be modified to add more
 common/general documentation, style sheets, JavaScript, etc.  The Sphinx

doc/scripts/genDocSourcesList.sh

@@ -30,6 +30,7 @@ statictext="\
 set(psd \${PROJECT_SOURCE_DIR}/policy)
 
 rest_target(\${CMAKE_CURRENT_SOURCE_DIR} example.bro internal)
+rest_target(\${psd} bro.init internal)
 "
 
 if [[ $# -ge 1 ]]; then

doc/scripts/source/index.rst

@@ -14,7 +14,6 @@ Contents:
    internal
    bifs
    packages
-   collections
    policy/index
 
 Indices and tables

policy/frameworks/control/base/main.bro

@@ -2,12 +2,14 @@
 ##! consts to a remote Bro then sends the :bro:id:`configuration_update` event
 ##! and terminates processing.
 ##!
-##! Intended to be used from the command line like this when starting a controller:
+##! Intended to be used from the command line like this when starting a controller::
+##!
 ##!     bro <scripts> frameworks/control/controller Control::host=<host_addr> Control::port=<host_port> Control::cmd=<command> [Control::arg=<arg>]
 ##! 
 ##! A controllee only needs to load the controllee script in addition
 ##! to the specific analysis scripts desired.  It may also need a noded 
-##! configured as a controller node in the communications nodes configuration.
+##! configured as a controller node in the communications nodes configuration::
+##!
 ##!     bro <scripts> frameworks/control/controllee
 ##!
 ##! To use the framework as a controllee, it only needs to be loaded and

policy/frameworks/notice/base/main.bro

@@ -103,7 +103,7 @@ export {
 	
 	## This is the record that defines the items that make up the notice policy.
 	type PolicyItem: record {
-		## This is the exact positional order in which the :id:type:`PolicyItem`
+		## This is the exact positional order in which the :bro:type:`PolicyItem`
 		## records are checked.  This is set internally by the notice framework.
 		position: count                            &log &optional;
 		## Define the priority for this check.  Items are checked in ordered

policy/protocols/smtp/base/software.bro

@@ -3,6 +3,7 @@
 ##! currently detected.
 ##! 
 ##! TODO:
+##!
 ##! * Find some heuristic to determine if email was sent through 
 ##!   a MS Exhange webmail interface as opposed to a desktop client.