///
/// \addtogroup stk_util_log_control_detail
/// @{
///
/// @brief Log control provides a mechanism reduce excessive log file output.
///
/// During some runs, particularly explicit codes, writing to the log file generates excessive
/// output that is not needed.  Once method of trimming this output is to only send it to the log
/// file at a specified interval.  The LogControl subsystem provides a mechanism for the developer
/// to provide simple output rule and the user to specify the rule to control the desired output.
///
/// The LogControl subsystem does this by directing the output to the log file stream buffer or
/// redirecting it to an in memory stream based on the evaluation of the rule.  This in memory
/// stream can be discarded or can later be written to the log file if an error condition arises.
///
/// By usong this technique, the statements which currently write to the log file are not effected
/// and if the system is not activated, the normal output is produced.
///
/// \anchor stk_util_log_control_howto_control_output
/// \section stk_util_log_control_control_output Log Control Sentry
///
/// A sentry class, LogControl takes an output stream and a rule as an argument.  When the
/// LogControl's next() function is called, the output stream is directed to write to the log file
/// or to the cache based on the result of the evaluation of the rule.
/// 
/// In the following example, the construction of the LogControl sentry stores the sierra::out()
/// stream, its stream buffer, and the rule associated with the m_name.  A cache ostringstream is
/// also created to cache the potentially discarded output.  Each time the log_control's next()
/// function is called, the rule is evaluated and the results determine which stream buffer to
/// attach to the sierra::out() stream; either sierra::out()'s original if the rule returns true or
/// the cache's.  The previously cached text is discarded at each next() execution.
///
/// If the execution fails, the cached stream buffer is written to the original output stream and
/// the cache is cleared.
///
/// \code
///    
///    stk::LogControl log_control(sierra::out(), m_name);
///    
///    while (!done) {
///      .
///      .
///      .
///      log_control.next();
///    
///      try {
///        .
///        .
///        .
///      }
///      catch (std::exception &x) {
///        log_control.fail();
///      }
///    }
///
/// \endcode
///
/// The LogControl's maintain a link to the parent LogControl for each stream.  Therefore, each
/// shares the same log stream and original log stream buffer.  On construction, the root LogControl
/// has the original stream buffer of the log stream, so the root's log stream buffer pointer is
/// copied to new LogControl sentry.  On destruction, since the log streams are all shared, the
/// log stream must have it's stream buffer replaced with the original log stream or it's cache
/// stream depending upon it current state.
///
/// \anchor stk_util_log_control_howto_rules
/// \section stk_util_log_control_register_rules Log Control Rules
///
/// The logging or caching of a log stream is determined by a log rule.  A log rule class consists
/// of a clone() function and a next() function and inherit from LogControlRule.
///
/// \code
///
///    struct LogControlRule
///    {
///      virtual LogControlRule *clone() const = 0;
///      virtual bool next() = 0;
///    };
///
/// \endcode
///
/// The clone() pure virtual function allows the rule to be copied.  And is implemented as
///
/// \code
///    virtual LogControlRule *clone() const {
///      return new MyRuleClass(*this);
///    }
/// \endcode
///
/// The next() function is used to determine the destination of the output stream.  If the next
/// function returns true, the log stream write to its original stream buffer, which is generally
/// the log file.  When it returns false, the output is written to the current log control sentry's
/// cache stream.
///
/// \anchor stk_util_log_control_howto_rules
/// \section stk_util_log_control_rules Predefined Log Control Rules
///
/// The LogControlRuleAlways and LogControlRuleInteval rules are predefined.  The
/// LogControlRuleAlways' next() function always returns true resulting the output always going to
/// the log file.  The LogControlRuleInteval is constructed with an interval and maintains a count.
/// The LogControlRuleInteval's next() function increments the count and returns true of the count
/// mod interval is zero.
///
///
/// \anchor stk_util_log_control_howto_rules_registration
/// \section stk_util_log_control_rules_registration Log Control Rule Registration
///
/// To simplify the usage of rules, the LogControl subsystem maintains a mapping of named rules.
/// These rules are copied during the construction of the LogControl sentries when they are
/// constructed by passing a rule name.
///
/// The addLogControlRule() function adds the rule to the map with specifed name.
///
/// @}
///
