[Boost-commit] svn:boost r41150 - in sandbox/logging/boost/logging/detail: . raw_doc

From: john.groups_at_[hidden]
Date: 2007-11-16 12:30:15

Author: jtorjo
Date: 2007-11-16 12:30:14 EST (Fri, 16 Nov 2007)
New Revision: 41150
URL: http://svn.boost.org/trac/boost/changeset/41150

Log:
[logging]
v0.11.17, 16 nov 2007
- more changes in the documentation ; also "refactored" table of contents
Text files modified: 
   sandbox/logging/boost/logging/detail/logger.hpp                        |     4 ++                                      
   sandbox/logging/boost/logging/detail/manipulator.hpp                   |    38 +++++++++++++++++++++++++--             
   sandbox/logging/boost/logging/detail/raw_doc/common_usage_steps_fd.hpp |    16 +++++-----                              
   sandbox/logging/boost/logging/detail/raw_doc/namespace_concepts.hpp    |     8 +++--                                   
   sandbox/logging/boost/logging/detail/raw_doc/scenarios.hpp             |     3 +                                       
   sandbox/logging/boost/logging/detail/raw_doc/table_of_contents.hpp     |    54 ++++++++++++++++++--------------------- 
   sandbox/logging/boost/logging/detail/raw_doc/thread_safety.hpp         |     1                                         
   sandbox/logging/boost/logging/detail/raw_doc/workflow.hpp              |    18 +++++++++++--                           
   8 files changed, 94 insertions(+), 48 deletions(-)

Modified: sandbox/logging/boost/logging/detail/logger.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/logger.hpp	(original)
+++ sandbox/logging/boost/logging/detail/logger.hpp	2007-11-16 12:30:14 EST (Fri, 16 Nov 2007)
@@ -79,12 +79,14 @@
     Check out writer::format_write - which allows you to use
     several formatters to further format the message, and then write it to destinations.
 
+    \n\n
+    You will seldom need to use the logger class directly. You can use @ref defining_your_logger "other wrapper classes".
 
 
     \n\n    
     The logger forwards 
     the gathering of the message to the @c gather_msg class. Once all message is gathered, it's passed on to the writer.
-    This is usually done through a @ref macros "macro".
+    This is usually done through a @ref macros_use "macro".
 
     @code
     typedef logger< ... > log_type;

Modified: sandbox/logging/boost/logging/detail/manipulator.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/manipulator.hpp	(original)
+++ sandbox/logging/boost/logging/detail/manipulator.hpp	2007-11-16 12:30:14 EST (Fri, 16 Nov 2007)
@@ -118,7 +118,7 @@
 
 They are: <tt>formatter::base<> </tt> and <tt>destination::base<> </tt>.
 
-The default formatter %base class is computed based on your usage of the @c BOOST_LOG_FORMAT_MSG macro:
+The default formatter %base class is computed based on your usage of the @ref BOOST_LOG_FORMAT_MSG macro:
 - if you haven't used it, it's <tt>std::(w)string & </tt>
 - if you've used it, it's the type you specified there; see below
 
@@ -133,7 +133,7 @@
 
 
 
-The default destination %base class is computed based on your usage of the @c BOOST_LOG_DESTINATION_MSG macro:
+The default destination %base class is computed based on your usage of the @ref BOOST_LOG_DESTINATION_MSG macro:
 - if you haven't used it, it's <tt>const std::(w)string & </tt>
 - if you've used it, it's the type you specified there; see below
 
@@ -156,7 +156,7 @@
 Now, you will define your @ref logger "logger(s)", to use the @ref boost::logging::writer::format_write "format_write" class:
 
 @code
-BOOST_DECLARE_LOG(g_l, logger< ... format_write<formatter_base,destination_base> > );
+BOOST_DECLARE_LOG(g_l, logger_format_write< formatter_base,destination_base> > );
 @endcode
 
 After this, you'll add formatter and/or destination classes to your logger(s):
@@ -192,10 +192,12 @@
 - formatters: in the formatter namespace. Here are a few examples:
   - formatter::idx - prepends an index
   - formatter::append_newline - appends an enter after the message
+  - formatter::append_newline_if_needed - appends an enter after the message, if not already there
   - formatter::time - prepends the time
   - formatter::thread_id - prepends the current thread id
 - destinations: in the destination namespace
   - destination::cout - writes to console
+  - destination::stream - writes to a stream
   - destination::file - writes to file
   - destination::rolling_file - writes to a rolling file
   - destination::shared_memory - writes into shared memory (using @c boost::shmem::named_shared_object)
@@ -273,6 +275,36 @@
 @endcode
 
 
+\n\n\n
+@section manipulator_use_it Using loggers in code
+
+Now that you've @ref manipulator_generic "added" formatters and/or destinations, you'll @ref macros_use "define the macros through which you'll do logging", 
+and then do logging in your code:
+
+@code
+// macros through which you'll do logging
+#define LDBG_ BOOST_LOG_USE_LOG_IF_LEVEL(g_l, g_log_level, debug )
+#define LERR_ BOOST_LOG_USE_LOG_IF_LEVEL(g_l, g_log_level, error )
+#define LAPP_ BOOST_LOG_USE_LOG_IF_LEVEL(g_l, g_log_level, info )
+
+// doing logging in code
+int i = 1;
+LDBG_ << "this is so cool " << i++;
+LERR_ << "first error " << i++;
+
+std::string hello = "hello", world = "world";
+LAPP_ << hello << ", " << world;
+
+g_log_level->set_enabled(level::error);
+LDBG_ << "this will not be written anywhere";
+LAPP_ << "this won't be written anywhere either";
+LERR_ << "second error " << i++;
+
+g_log_level->set_enabled(level::info);
+LAPP_ << "good to be back ;) " << i++;
+LERR_ << "third error " << i++;
+
+@endcode
 
 */
 namespace manipulator {

Modified: sandbox/logging/boost/logging/detail/raw_doc/common_usage_steps_fd.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/raw_doc/common_usage_steps_fd.hpp	(original)
+++ sandbox/logging/boost/logging/detail/raw_doc/common_usage_steps_fd.hpp	2007-11-16 12:30:14 EST (Fri, 16 Nov 2007)
@@ -4,16 +4,16 @@
 @page common_usage_steps_fd Common steps when using Formatters and destinations
 
 The usual steps when using the Boost Logging Lib are:
-- Step 1: (optional) Specify your format and/or message class. By default, it's <tt>std::(w)string</tt>.
-  You'll use this when you want an @ref "optimize string class".
+- Step 1: (optional) Specify your @ref BOOST_LOG_FORMAT_MSG "format message class" and/or @ref BOOST_LOG_DESTINATION_MSG "destination message class". By default, it's <tt>std::(w)string</tt>.
+  You'll use this when you want a @ref optimize "optimize string class".
 - Step 2: (optional) Specify your @ref boost::logging::manipulator "formatter & destination base classes"
-- Step 3: Specify your logger class(es)
-- Step 4: Declare the loggers and the filters you'll use (in a header file)
-- Step 5: Define the macros through which you'll log
-- Step 6: Define the loggers and the filters you'll use (in a source file). We need this separation
-  (into declaring and defining the logs/filters), in order to make compilation times fast.
+- Step 3: @ref defining_your_logger "Specify your logger class(es)"
+- Step 4: Declare the @ref defining_your_filter "filters" and @ref defining_your_logger "loggers" you'll use (in a header file)
+- Step 5: Define the @ref macros_use "macros through which you'll do logging"
+- Step 6: Define the @ref defining_your_logger "loggers" and the @ref defining_your_filter "filters" you'll use (in a source file). We need this separation
+  (into declaring and defining the logs/filters), in order to @ref macros_compile_time "make compilation times fast".
 - Step 7: Add @ref boost::logging::manipulator "formatters and destinations". That is, how the message is to be formatted...
-- Step 8: Use it
+- Step 8: @ref manipulator_use_it "Use it"
 - Step 9: Enjoy the results!
 
 */

Modified: sandbox/logging/boost/logging/detail/raw_doc/namespace_concepts.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/raw_doc/namespace_concepts.hpp	(original)
+++ sandbox/logging/boost/logging/detail/raw_doc/namespace_concepts.hpp	2007-11-16 12:30:14 EST (Fri, 16 Nov 2007)
@@ -4,6 +4,7 @@
 @page namespace_concepts Concepts as namespaces
 
 - @ref namespace_general
+- @ref namespace_process 
 - @ref namespace_manipulator
 - @ref namespace_write
 
@@ -19,10 +20,10 @@
 - filter - available filter implementations
 - level - in case you want to use Log Levels
 - writer - %writer objects; they do the actual write of the message 
-
+- scenario - in case you want to easily specify the logger and filter class(es), based on your application's needs
 
 \n\n
-_at_section namespace_process Processing the message 
+@section namespace_process Logging (Processing) the message 
 (for more info, see logger class)
 - gather - gathering the message
 - writer - %writer objects; they do the actual write of the message 
@@ -34,7 +35,8 @@
 - manipulator - what a manipulator is: a formatter or a destination
 - formatter - available formatters
 - destination - available destinations
-
+- tag - available tags
+- formatter::tag - available tag formatters
 
 \n\n
 @section namespace_write Writing concepts

Modified: sandbox/logging/boost/logging/detail/raw_doc/scenarios.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/raw_doc/scenarios.hpp	(original)
+++ sandbox/logging/boost/logging/detail/raw_doc/scenarios.hpp	2007-11-16 12:30:14 EST (Fri, 16 Nov 2007)
@@ -1,7 +1,7 @@
 namespace boost { namespace logging {
 
 /** 
-_at_page common_scenarios Usage Scenarios
+@page common_scenarios Usage Scenarios (together with code)
 
 - @ref common_scenarios_1
 - @ref common_scenarios_2
@@ -22,6 +22,7 @@
     - @ref scenario_multiple_files_log_cpp 
     - @ref scenario_multiple_files_main 
 
+\n\n\n
 @copydoc common_usage_steps_fd 
 
 

Modified: sandbox/logging/boost/logging/detail/raw_doc/table_of_contents.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/raw_doc/table_of_contents.hpp	(original)
+++ sandbox/logging/boost/logging/detail/raw_doc/table_of_contents.hpp	2007-11-16 12:30:14 EST (Fri, 16 Nov 2007)
@@ -8,6 +8,16 @@
     - @ref main_motivation
     - @ref page_changelog
         - @ref changelog_cur_ver 
+    - @ref acknowledgements
+
+- @ref workflow
+    - @ref workflow_introduction 
+    - @ref workflow_filter 
+    - @ref workflow_processing 
+    - @ref workflow_2a 
+    - @ref workflow_2b 
+    - @ref workflow_formatters_destinations 
+
 - @ref common_scenarios
     - @ref common_scenarios_1
     - @ref common_scenarios_2
@@ -18,28 +28,30 @@
     - @ref scenario_multiple_files
     - @ref starter_project 
 
-- @ref defining_your_logger_filter 
 - @ref headers_to_include "Headers to #include"
+- @ref defining_your_logger_filter 
 - @ref scenario::usage "Choose the best filter/logger class, based on your application's needs"
 - @ref tag "Using tags"
+- @ref thread_safety 
+- @ref macros
+    - @ref macros_if_else_strategy 
+    - @ref macros_using 
+        - @ref macros_define_declare 
+        - @ref macros_use 
+        - @ref macros_set_formatters 
+        - @ref macros_use_tags 
+        - @ref macros_compile_time 
+        - @ref macros_tss 
 
-
-
-- @ref workflow
-    - @ref workflow_introduction 
-    - @ref workflow_filter 
-    - @ref workflow_processing 
-    - @ref workflow_2a 
-    - @ref workflow_2b 
+- @ref logger "The logger class"
+    - @ref gather "The gather namespace"
+    - @ref writer "The writer namespace"
+- @ref filter "The filters (namespace)"
 - @ref namespace_concepts
     - @ref namespace_general
     - @ref namespace_process 
     - @ref namespace_manipulator
     - @ref namespace_write
-- @ref logger "The logger class"
-    - @ref gather "The gather namespace"
-    - @ref writer "The writer namespace"
-- @ref filter "The filters (namespace)"
 - @ref manipulator "Formatters and/or destinations (manipulators namespace)"
     - @ref manipulator_common 
     - @ref manipulator_base_class 
@@ -50,24 +62,8 @@
     - @ref formatter "Formatters"
     - @ref destination "Destinations"
 
-- @ref thread_safety 
-
-- @ref override_defaults
-
-
-- @ref macros
-    - @ref macros_if_else_strategy 
-    - @ref macros_using 
-        - @ref macros_define_declare 
-        - @ref macros_use 
-        - @ref macros_set_formatters 
-        - @ref macros_use_tags 
-        - @ref macros_compile_time 
-        - @ref macros_tss 
-
 - @ref boost_logging_requirements 
 
-- @ref acknowledgements
 
 
 */

Modified: sandbox/logging/boost/logging/detail/raw_doc/thread_safety.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/raw_doc/thread_safety.hpp	(original)
+++ sandbox/logging/boost/logging/detail/raw_doc/thread_safety.hpp	2007-11-16 12:30:14 EST (Fri, 16 Nov 2007)
@@ -2,6 +2,7 @@
 
 /** 
 @page thread_safety Thread safety
+
 FIXME
 
 */

Modified: sandbox/logging/boost/logging/detail/raw_doc/workflow.hpp
==============================================================================
--- sandbox/logging/boost/logging/detail/raw_doc/workflow.hpp	(original)
+++ sandbox/logging/boost/logging/detail/raw_doc/workflow.hpp	2007-11-16 12:30:14 EST (Fri, 16 Nov 2007)
@@ -9,7 +9,7 @@
 - @ref workflow_processing 
 - @ref workflow_2a 
 - @ref workflow_2b 
-
+- @ref workflow_formatters_destinations 
 
 
 @section workflow_introduction Introduction
@@ -97,7 +97,7 @@
 - or any combination of the above
 
 Depending on your needs, gathering can be complex or not. However, it's completely decoupled from the other steps.
-Gathering goes hand in hand with @ref macros "macros".
+Gathering goes hand in hand with @ref macros_use "macros".
 
 The cool thing is that you decide how the <i>Logging syntax</i> is - depending on how you want to gather the message.
 All of the below are viable options:
@@ -109,7 +109,7 @@
 L_(err,"chart")("Cannot load chart")(chart_path);
 @endcode
 
-How you gather your message, depends on how you <tt>\#define L_ ...</tt>.
+How you gather your message, depends on how you @ref macros_use "#define L_ ...".
 
 In other words, gathering the message means getting all the message in "one piece", so that it can be written. \n
 See the 
@@ -181,7 +181,19 @@
 
 
 
+\n\n
+@section workflow_formatters_destinations Workflow when using formatters and destinations
+
+When using @ref manipulator "formatters and destinations", there are some steps you'll usually take.
+
+Remember:
+- formatter - allows formatting the message before writing it (like, prepending extra information - an index, the time, thread id, etc)
+- destination - is a place where the message is to be written to (like, the console, a file, a socket, etc)
+
+
+@copydoc common_usage_steps_fd
 
+There are plenty of @ref common_scenarios "examples" together with @ref scenarios_code "code".
 
 */