[Boost-commit] svn:boost r67874 - trunk/libs/chrono/doc

Subject: [Boost-commit] svn:boost r67874 - trunk/libs/chrono/doc
From: pbristow_at_[hidden]
Date: 2011-01-09 13:11:06

Author: pbristow
Date: 2011-01-09 13:11:03 EST (Sun, 09 Jan 2011)
New Revision: 67874
URL: http://svn.boost.org/trac/boost/changeset/67874

Log:
Paul B's many minor revisions, nearly all editorial (spelling etc)
Text files modified: 
   trunk/libs/chrono/doc/chrono.qbk |   202 +++++++++++++++++++-------------------- 
   1 files changed, 99 insertions(+), 103 deletions(-)

Modified: trunk/libs/chrono/doc/chrono.qbk
==============================================================================
--- trunk/libs/chrono/doc/chrono.qbk	(original)
+++ trunk/libs/chrono/doc/chrono.qbk	2011-01-09 13:11:03 EST (Sun, 09 Jan 2011)
@@ -44,6 +44,8 @@
 [def __pre_conditions [*PreConditions:]]
 [def __requires [*Requires:]]
 
+[template mu[]'''μ'''] [/ µ Greek small letter mu]
+[template plusminus[]'''±'''] [/  ? plus or minus sign]
 
 
 [/===============================================]
@@ -162,7 +164,7 @@
 [section Overview]
 [/===============]
 
-[:["What is time, then? If nobody asks me, I know; if I have to explain it to someone who has asked me, I do not know.]]
+[:["What is time, then? If nobody asks me, I know; if I have to explain it to someone who has asked me, I do not know."]]
 [:[*['-- Augustine ]]]
 
 
@@ -194,12 +196,12 @@
 
 [heading Time]
 
-We all deal with time every day of our lives. We've intuitively known it since birth. Thus we are all very familiar with it and believe it to be a simple matter. The modeling of time in computer programs should be similarly simple. The unfortunate truth is that this perceived simplicity is only skin deep. Fortunately however, we do not need a terribly complicated solution to meet the bulk of our needs. However, overly simplistic solutions can be dangerous and inefficient, and won't adapt as the computer industry evolves.
+We all deal with time every day of our lives. We've intuitively known it since birth. Thus we are all very familiar with it and believe it to be a simple matter. The modeling of time in computer programs should be similarly simple. The unfortunate truth is that this perceived simplicity is only skin deep. Fortunately, we do not need a terribly complicated solution to meet the bulk of our needs. However, overly simplistic solutions can be dangerous and inefficient, and won't adapt as the computer industry evolves.
 
 __Boost_Chrono__ aims to implement the new time facilities in C++0x, as proposed in [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2008/n2661.htm [*N2661 - A Foundation to Sleep On]].  That document provides background and motivation for key design decisions and is the source of a good deal of information in this documentation.
 
 [/
-__Boost_Chrono__ proposes a solution that is precision neutral, with a very simple end user interface which supports multiple clocks, multiple precisions (both coarser and finer than we will ever need), separate types for points in time and time durations, efficiency, and compile time enforced safety.
+__Boost_Chrono__ proposes a solution that is precision neutral, with a very simple end user interface which supports multiple clocks, multiple precisions (both coarser and finer than we will ever need), separate types for points in time and time durations, efficiency, and compile-time enforced safety.
 ]
 
 [/
@@ -258,7 +260,7 @@
 * __process_user_cpu_clock, captures user-CPU time spent by the current process.
 * __process_system_cpu_clock, captures system-CPU time  spent by the current process.
 * A tuple-like class __process_cpu_clock, that captures real, user-CPU, and system-CPU process times together.
-* A __thread_clock thread steady clock giving the time spent by the current threrad( when supported by a platform).
+* A __thread_clock thread steady clock giving the time spent by the current thread (when supported by a platform).
 
 
 [/It is also helpful if such timing information is broken down into real (wall clock) time, CPU time spent by the user, and CPU time spent by the operating system servicing user requests. process clocks provide a thin wrapper around the operating system's process timer API. For POSIX-like systems, that's the times() function, while for Windows, it's the GetProcessTimes() function.
@@ -313,7 +315,7 @@
 [heading Building Boost.Chrono ]
 [/=================================]
 
-__Boost_Chrono__ can be configured as a header only library. When __BOOST_CHRONO_INLINED is defined the lib is header only library. Otherwise is not a header only library and you need to compile it before use.
+__Boost_Chrono__ can be configured as a header-only library. When __BOOST_CHRONO_INLINED is defined the Boost.Chrono is a header-only library. Otherwise is not a header only library and you need to compile it and build the library before use, for example using:
 
     bjam libs/chrono/build
 
@@ -321,7 +323,7 @@
 [heading Requirements]
 [/===================]
 
-__Boost_Chrono__ depends on some new traits in [*Boost.TypeTraits] which have been added on Boost 1.45. 
+[caution __Boost_Chrono__ depends on some new traits in [*Boost.TypeTraits] which have been added on Boost 1.45.]
 
 In particular, __Boost_Chrono__ depends on:
 
@@ -361,7 +363,7 @@
 [/=========================================================]
 
 In addition to link with the __Boost_Chrono__ library you need also to link with the [*Boost.System] library.
-Once [*Boost.System] will be configurable to be a header only using __BOOST_SYSTEM_INLINED you will no need to link with.
+Once [*Boost.System] will be configurable to be a header only using __BOOST_SYSTEM_INLINED you will no need to link with it.
 
 
 [/=========================]
@@ -377,7 +379,7 @@
 
 All functions in the library are thread-unsafe except when noted explicitly.
 
-As Boost.Chrono doesn't use mutable global variables the thread safety analysis is limited to the access to each instance variable. It is not thread safe to use a function that modifies the access to a user variable if another can be reading or writing it.
+As Boost.Chrono doesn't use mutable global variables the thread-safety analysis is limited to the access to each instance variable. It is not thread safe to use a function that modifies the access to a user variable if another can be reading or writing it.
 
 
 [/========================]
@@ -453,7 +455,7 @@
 
 [section Duration]
 
-The __duration is the heart of this library. The interface that the user will see in everyday use is nearly identical to that of [*Boost.DateTime] time __duration_s authored by Jeff Garland, both in syntax and in behavior. This has been a very popular boost library for 7 years. There is an enormous positive history with this interface.
+The __duration is the heart of this library. The interface that the user will see in everyday use is nearly identical to that of [*Boost.DateTime] time __durations authored by Jeff Garland, both in syntax and in behavior. This has been a very popular boost library for 7 years. There is an enormous positive history with this interface.
 
 The library consists of six units of time __duration:
 
@@ -464,19 +466,19 @@
 * __microseconds
 * __nanoseconds
 
-These units were chosen as a subset of the boost library because they are the most common units used when sleeping, waiting on a condition variable, or waiting to obtain the lock on a mutex. Each of these units is nothing but a thin wrapper around a signed integral count. That is, when you construct __minutes`(3)`, all that happens is a `3` is stored inside of minutes. When you construct __microseconds`(3)`, all that happens is a `3` is stored inside of __microseconds.
+These units were chosen as a subset of the boost library because they are the most common units used when sleeping, waiting on a condition variable, or waiting to obtain the lock on a mutex. Each of these units is nothing but a thin wrapper around a signed integral count. That is, when you construct __minutes`(3)`, all that happens is a `3` is stored inside `minutes`. When you construct __microseconds`(3)`, all that happens is a `3` is stored inside __microseconds.
 
-The only context in which these different types differ is when being converted to one another. At this time, unit-specific compile-time conversion constants are used to convert the source unit to the target unit. Only conversions from coarser units to finer units are allowed (in boost). This restriction ensures that all conversions are always exact. That is, __microseconds can always represent any value __minutes has.
+The only context in which these different types differ is when being converted to one another. At this time, unit-specific compile-time conversion constants are used to convert the source unit to the target unit. Only conversions from coarser units to finer units are allowed (in Boost). This restriction ensures that all conversions are always exact. That is, __microseconds can always represent any value __minutes has.
 
 In [*Boost.DateTime], these units are united via inheritance. __Boost_Chrono__ instead unites these units through the class template __duration. That is, in __Boost_Chrono__ all six of the above units are nothing but typedefs to different instantiations of __duration. This change from Boost.DateTime has a far reaching positive impact, while not changing the syntax of the everyday use at all.
 
-The most immediate positive impact is that the library can immediately generate any unit, any precision it needs. This is sometimes necessary when doing comparisons or arithmetic between __duration_s of differing precision, assuming one wants the comparison and arithmetic to be exactly correct.
+The most immediate positive impact is that the library can immediately generate any unit, with any precision it needs. This is sometimes necessary when doing comparisons or arithmetic between __durations of differing precision, assuming one wants the comparison and arithmetic to be exact.
 
-A secondary benefit is that by publishing the class template __duration interface, user code can very easily create __duration_s with any precision they desire. The __ratio utility is used to specify the precision, so as long as the precision can be expressed by a rational constant with respect to seconds, this framework can exactly represent it (one third of a second is no problem, and neither is one third of a __femto second). All of this utility and flexibility comes at no cost just by making use of the no-run-time-overhead __ratio facility.
+A secondary benefit is that by publishing the class template __duration interface, user code can very easily create __durations with any precision they desire. The __ratio utility is used to specify the precision, so as long as the precision can be expressed by a rational constant with respect to seconds, this framework can exactly represent it (one third of a second is no problem, and neither is one third of a __femto second). All of this utility and flexibility comes at no cost just by making use of the no-run-time-overhead __ratio facility.
 
 In Boost.DateTime, __hours does not have the same representation as __nanoseconds. The former is usually represented with a `long` whereas a `long long` is required for the latter. The reason for this is simply range. You don't need many hours to cover an extremely large range of time. But this isn't true of nanoseconds. Being able to reduce the sizeof overhead for some units when possible, can be a significant performance advantage.
 
-__Boost_Chrono__ continues, and generalizes that philosophy. Not only can one specify the precision of a __duration, one can also specify its representation. This can be any integral type, or even a floating point type. Or it can be a user-defined type which emulates an arithmetic type. The six predefined units all use signed integral types as their representation. And they all have a minimum range of +/- 292 years. __nanoseconds needs 64 bits to cover that range. __hours needs only 23 bits to cover that range.
+__Boost_Chrono__ continues, and generalizes that philosophy. Not only can one specify the precision of a __duration, one can also specify its representation. This can be any integral type, or even a floating-point type. Or it can be a user-defined type which emulates an arithmetic type. The six predefined units all use signed integral types as their representation. And they all have a minimum range of [plusminus] 292 years. __nanoseconds needs 64 bits to cover that range. __hours needs only 23 bits to cover that range.
 
 
 [section  So What Exactly is a `duration` and How Do I Use One?]
@@ -485,7 +487,7 @@
 
     template <class Rep, class Period = __ratio<1> > class duration;
 
-The representation is simply any arithmetic type, or an emulation of such a type. The representation stores a count of ticks. This count is the only data member stored in a __duration. If the representation is floating point, it can store fractions of a tick to the precision of the representation. The tick period is represented by a __ratio and is encoded into the __duration's type, instead of stored. The tick period only has an impact on the behavior of the __duration when a conversion between different __duration's is attempted. The tick period is completely ignored when simply doing arithmetic among like __duration_s.
+The representation is simply any arithmetic type, or an emulation of such a type. The representation stores a count of ticks. This count is the only data member stored in a __duration. If the representation is floating-point, it can store fractions of a tick to the precision of the representation. The tick period is represented by a __ratio and is encoded into the __duration_s type, instead of stored. The tick period only has an impact on the behavior of the __duration when a conversion between different __durations is attempted. The tick period is completely ignored when simply doing arithmetic among like __durations.
 
 __example
 
@@ -507,7 +509,7 @@
 
     long long tc = us4.count();    // tc is 300000005
 
-These __duration_s have very simple, very predictable, and very observable behavior. After all, this is really nothing but the time tested interface of Jeff's boost time __duration library (unified with templates instead of inheritance).
+These __duration_s have very simple, very predictable, and very observable behavior. After all, this is really nothing but the time-tested interface of Jeff's boost time __duration library (unified with templates instead of inheritance).
 
 [endsect]
 
@@ -515,7 +517,7 @@
 
     minutes m4 = m3 + us3;
 
-It won't compile. The rationale is that implicit truncation error should not be allowed to happen. If this were to compile, then `m4` would hold `5`, the same value as `m3`. The value associated with `us3` has been effectively ignored. This is similar to the problem of assigning a double to an `int`: the fractional part gets silently discarded.
+It won't compile! The rationale is that implicit truncation error should not be allowed to happen. If this were to compile, then `m4` would hold `5`, the same value as `m3`. The value associated with `us3` has been effectively ignored. This is similar to the problem of assigning a double to an `int`: the fractional part gets silently discarded.
 [endsect]
 
 [section But What if the Truncation Behavior is What I Want to Do?]
@@ -524,7 +526,7 @@
 
     minutes m4 = bchrono::__duration_cast<minutes>(m3 + us3);  // m4.count() == 5
 
-In general, one can perform __duration arithmetic at will. If __duration_cast isn't used, and it compiles, the arithmetic is exact. Any place one wants to override this exact arithmetic behavior, __duration_cast can be used to explicitly specify that desire. The __duration_cast has the same efficiency as the implicit conversion, and will even be exact as often as it can.
+In general, one can perform __duration arithmetic at will. If __duration_cast isn't used, and it compiles, the arithmetic is exact. If one wants to override this exact arithmetic behavior, __duration_cast can be used to explicitly specify that desire. The __duration_cast has the same efficiency as the implicit conversion, and will even be exact as often as it can.
 
 You can use __duration_cast`<>` to convert the __duration into whatever units you desire.  This facility will round down (truncate) if an exact conversion is not possible.  For example:
 
@@ -543,13 +545,13 @@
     ns d = end - start;
     std::cout << ns.count() << "ns\n";
 
-If you need seconds with a floating point representation you can also eliminate the __duration_cast`<>`:
+If you need seconds with a floating-point representation you can also eliminate the __duration_cast`<>`:
 
     typedef bchrono::__duration<double> sec;  // seconds, stored with a double
     sec d = end - start;
     std::cout << sec.count() << "s\n";
 
-If you're not sure if you need __duration_cast`<>` or not, feel free to try it without.  If the conversion is exact, or if the destination has a floating point representation, it will compile: else it will not compile.
+If you're not sure if you need __duration_cast`<>` or not, feel free to try it without.  If the conversion is exact, or if the destination has a floating-point representation, it will compile: else it will not compile.
 
 
 If you need to use __duration_cast`<>`, but want to round up, instead of down when the conversion is inexact, here is a handy little helper function to do so.  Writing it is actually a good starter project for understanding __Boost_Chrono__:
@@ -572,11 +574,11 @@
 
 [endsect]
 
-[section Trafficking in Floating Point Durations]
+[section Trafficking in floating-point Durations]
 
-I don't want to deal with writing `duration_cast` all over the place. I'm content with the precision of my floating point representation
+I don't want to deal with writing `duration_cast` all over the place. I'm content with the precision of my floating-point representation.
 
-Not a problem. When the destination of a conversion has floating point representation, all conversions are allowed to happen implicitly.
+Not a problem. When the destination of a conversion has floating-point representation, all conversions are allowed to happen implicitly.
 
     typedef bchrono::__duration<double, __ratio<60> > dminutes;
     dminutes dm4 = m3 + us3;  // dm4.count() == 5.000000083333333
@@ -585,7 +587,7 @@
 
 [section How Expensive is All of this?]
 
-If you were writing these conversions by hand, you could not make it more efficient. The use of __ratio ensures that all conversion constants are simplified as much as possible at compile time. This usually results in the numerator or denominator of the conversion factor simplifying to `1`, and being subsequently ignored in converting the run time values of the tick counts.
+If you were writing these conversions by hand, you could not make it more efficient. The use of __ratio ensures that all conversion constants are simplified as much as possible at compile-time. This usually results in the numerator or denominator of the conversion factor simplifying to `1`, and being subsequently ignored in converting the run-time values of the tick counts.
 
 [endsect]
 
@@ -593,16 +595,16 @@
 
 There are several options open to the user:
 
-* If the author of the function wants to accept any __duration, and is willing to work in floating point __duration_s, he can simply use any floating point __duration as the parameter:
+* If the author of the function wants to accept any __duration, and is willing to work in floating-point __durations, he can simply use any floating-point __duration as the parameter:
 
-          void f(bchrono::duration<double> d)  // accept floating point seconds
+          void f(bchrono::duration<double> d)  // accept floating-point seconds
           {
               // d.count() == 3.e-6 when passed bchrono::microseconds(3)
           }
 
           f(bchrono::microseconds(3));
 
-* If the author of the function wants to traffic only in integral __duration_s, and is content with handling nothing finer than say nanoseconds (just as an example), he can simply specify nanoseconds as the parameter:
+* If the author of the function wants to traffic only in integral __durations, and is content with handling nothing finer than say nanoseconds (just as an example), he can simply specify nanoseconds as the parameter:
 
           void f(bchrono::nanoseconds d)
           {
@@ -611,7 +613,7 @@
 
           f(bchrono::microseconds(3));
 
-In this design, if the client wants to pass in a floating point __duration, or a __duration of finer precision than nanoseconds, then the client is responsible for choosing his own rounding mode in the conversion to nanoseconds.
+In this design, if the client wants to pass in a floating-point __duration, or a __duration of finer precision than nanoseconds, then the client is responsible for choosing his own rounding mode in the conversion to nanoseconds.
 
           bchrono::__duration<double> s(1./3);  // 1/3 of a second
           f(bchrono::duration_cast<bchrono::nanoseconds>(s));  // round towards zero in conversion to nanoseconds
@@ -629,12 +631,12 @@
             bchrono::nanoseconds ns = bchrono::duration_cast<bchrono::nanoseconds>(d);
             if (ns < d)
                 ++ns;
-            // ns.count() == 333333334 when passed 1/3 of a floating point second
+            // ns.count() == 333333334 when passed 1/3 of a floating-point second
         }
 
           f(bchrono::__duration<double>(1./3));
 
-*  If the author in the example does not want to accept floating point based __duration_s, he can enforce that behavior like so:
+*  If the author in the example does not want to accept floating-point based __durations, he can enforce that behavior like so:
 
         template <class Period>
         void f(bchrono::__duration<long long, Period> d)
@@ -648,7 +650,7 @@
         // About 1/3 of a second worth of picoseconds
         f(bchrono::__duration<long long, boost::pico>(333333333333));
 
-Clients with floating point __duration_s who want to use f will now have to convert to an integral __duration themselves before passing the result to f.
+Clients with floating-point __durations who want to use f will now have to convert to an integral __duration themselves before passing the result to f.
 
 In summary, the author of f has quite a bit of flexibility and control in the interface he wants to provide his clients with, and easy options for manipulating that __duration internal to his function.
 [endsect]
@@ -662,7 +664,7 @@
 
 [section Clocks]
 
-While __duration_s only have precision and representation to concern themselves, clocks and __time_point_s are intimately related and refer to one another. Because clocks are simpler to explain, we will do so first without fully explaining __time_point_s. Once clocks are introduced, it will be easier to then fill in what a __time_point is.
+While __durations only have precision and representation to concern themselves, clocks and __time_points are intimately related and refer to one another. Because clocks are simpler to explain, we will do so first without fully explaining __time_points. Once clocks are introduced, it will be easier to then fill in what a __time_point is.
 
 A clock is a concept which bundles 3 things:
 
@@ -702,7 +704,7 @@
 
     Clock::time_point t1 = Clock::now();
 
-And one can get the time __duration between two __time_point_s associated with Clock with:
+And one can get the time __duration between two __time_points associated with Clock with:
 
     Clock::duration d = Clock::now() - t1;
 
@@ -718,15 +720,15 @@
 
 [section Time Point]
 
-A __time_point represents a point in time, as opposed to a __duration of time. Another way of saying the same thing, is that a __time_point represents an epoch plus or minus a __duration. Examples of __time_point_s include:
+A __time_point represents a point in time, as opposed to a __duration of time. Another way of saying the same thing, is that a __time_point represents an epoch plus or minus a __duration. Examples of __time_points include:
 
 * 3 minutes after the computer booted.
 * 03:14:07 UTC on Tuesday, January 19, 2038
 * 20 milliseconds after I started that timer.
 
-In each of the examples above, a different epoch is implied. Sometimes an epoch has meaning for several millennia. Other times the meaning of an epoch is lost after a while (such as the start of a timer, or when the computer booted). However, if two __time_point_s are known to share the same epoch, they can be subtracted, yielding a valid __duration, even if the definition of the epoch no longer has meaning.
+In each of the examples above, a different epoch is implied. Sometimes an epoch has meaning for several millennia. Other times the meaning of an epoch is lost after a while (such as the start of a timer, or when the computer booted). However, if two __time_points are known to share the same epoch, they can be subtracted, yielding a valid __duration, even if the definition of the epoch no longer has meaning.
 
-In __Boost_Chrono__, an epoch is a purely abstract and unspecified concept. There is no type representing an epoch. It is simply an idea that relates (or doesn't) __time_point_s to a clock, and in the case that they share a clock, __time_point_s to one another. __time_point_s associated with different clocks are generally not interoperable unless the relationship between the epochs associated with each clock is known.
+In __Boost_Chrono__, an epoch is a purely abstract and unspecified concept. There is no type representing an epoch. It is simply an idea that relates (or doesn't) __time_points to a clock, and in the case that they share a clock, __time_points to one another. __time_points associated with different clocks are generally not interoperable unless the relationship between the epochs associated with each clock is known.
 
 [section  So What Exactly is a `time_point` and How Do I Use One?]
 
@@ -736,10 +738,10 @@
 
 The __time_point's clock is not stored. It is simply embedded into the __time_point's type and serves two purposes:
 
-# Because __time_point_s originating from different clocks have different types, the compiler can be instructed to fail if incompatible __time_point_s are used in inappropriate ways.
+# Because __time_points originating from different clocks have different types, the compiler can be instructed to fail if incompatible __time_points are used in inappropriate ways.
 # Given a __time_point, one often needs to compare that __time_point to "now". This is very simple as long as the __time_point knows what clock it is defined with respect to.
 
-A __time_point's __duration is stored as the only data member of the __time_point. Thus __time_point_s and their corresponding __duration have exactly the same layout. But they have very different meanings. For example, it is one thing to say I want to sleep for 3 minutes. It is a completely different thing to say I want to sleep until 3 minutes past the time I started that timer (unless you just happened to start that timer now). Both meanings (and options for sleeping) have great practical value in common use cases for sleeping, waiting on a condition variable, and waiting for a mutex's lock. These same concepts and tools are found (for example) in Ada.
+A __time_point's __duration is stored as the only data member of the __time_point. Thus __time_points and their corresponding __duration have exactly the same layout. But they have very different meanings. For example, it is one thing to say I want to sleep for 3 minutes. It is a completely different thing to say I want to sleep until 3 minutes past the time I started that timer (unless you just happened to start that timer now). Both meanings (and options for sleeping) have great practical value in common use cases for sleeping, waiting on a condition variable, and waiting for a mutex's lock. These same concepts and tools are found (for example) in Ada.
 
 A timer example:
 
@@ -752,7 +754,7 @@
         cout << "f() took " << sec.count() << " seconds\n";
     }
 
-Note that if one is using the __duration between two clock __time_point_s in a way where the precision of the __duration matters, it is good practice to convert the clock's  __duration to a known __duration. This insulates the code from future changes which may be made to the clock's  precision in the future. For example __steady_clock could easily be based on the clock speed of the cpu. When you upgrade to a faster machine, you do not want your code that assumed a certain tick period of this clock to start experiencing run time failures because your timing code has silently changed meaning.
+Note that if one is using the __duration between two clock __time_points in a way where the precision of the __duration matters, it is good practice to convert the clock's  __duration to a known __duration. This insulates the code from future changes which may be made to the clock's  precision in the future. For example __steady_clock could easily be based on the clock speed of the cpu. When you upgrade to a faster machine, you do not want your code that assumed a certain tick period of this clock to start experiencing run-time failures because your timing code has silently changed meaning.
 
 A delay loop example:
 
@@ -835,9 +837,9 @@
 [endsect]
 [section steady_clock]
 
-__steady_clock is useful when you need to wait for a specific amount of time. __steady_clock time can not be reset. As other steady clocks, it is usualy based on the processor tick.
+__steady_clock is useful when you need to wait for a specific amount of time. __steady_clock time can not be reset. As other steady clocks, it is usually based on the processor tick.
 
-Next is presented a polling solution, which will however be too inefficient:
+Here is a polling solution, but it will probably be too inefficient:
 
     bchrono::__steady_clock::time_point start= chrono::__steady_clock::now();
     bchrono::__steady_clock::duration delay= chrono::seconds(5);
@@ -847,15 +849,13 @@
 
 [section high_resolution_clock]
 
-When available, __high_resolution_clock is usualy more expensive than the other system-wide clocks, so they are used only when the provided resolution is required to the application.
+When available, __high_resolution_clock is usually more expensive than the other system-wide clocks, so they are used only when the provided resolution is required to the application.
 
 [endsect]
 
 [section process_cpu_clock]
 
-Process and thread clocks are used usualy to measure the time spent by code blocks, as a basic time-spent profiling of different blocks of code (Boost.Stopwatch is clear example of this use).
-
-
+Process and thread clocks are used usually to measure the time spent by code blocks, as a basic time-spent profiling of different blocks of code (Boost.Stopwatch is a clear example of this use).
 
 [endsect]
 
@@ -864,16 +864,16 @@
 You can use __thread_clock whenever you want to measure the time spent by the current thread. For example:
 
     bchrono::__thread_clock::time_point start=bchrono::__thread_clock::now();
-    //do something
+    // ... do something ...
 
     typedef bchrono::__milliseconds__ ms;
     ms d = bchrono::__thread_clock::now() - start;
     // d now holds the number of milliseconds from start to end.
     std::cout << ms.count() << "ms\n";
 
-If you need seconds with a floating point representation you can do:
+If you need seconds with a floating-point representation you can do:
 
-    typedef bchrono::__duration<double> sec;  // seconds, stored with a double
+    typedef bchrono::__duration<double> sec;  // seconds, stored with a double.
     sec d = end - start;
     std::cout << sec.count() << "s\n";
 
@@ -884,7 +884,7 @@
 
 [section I/O]
 
-Any __duration can be streamed out to a `basic_ostream`. The run time value of the __duration is formatted according to the rules and current format settings for __duration`::rep`. This is followed by a single space and then the compile time unit name of the __duration. This unit name is built on the string returned from `ratio_string<>` and the data used to construct the __duration_punct which was inserted into the stream's locale. If a __duration_punct has not been inserted into the stream's locale, a default constructed __duration_punct will be added to the stream's locale.
+Any __duration can be streamed out to a `basic_ostream`. The run-time value of the __duration is formatted according to the rules and current format settings for __duration`::rep`. This is followed by a single space and then the compile-time unit name of the __duration. This unit name is built on the string returned from `ratio_string<>` and the data used to construct the __duration_punct which was inserted into the stream's locale. If a __duration_punct has not been inserted into the stream's locale, a default constructed __duration_punct will be added to the stream's locale.
 
 __duration unit names come in two varieties: long and short. The default constructed __duration_punct provides names in the long format. These names are English descriptions. Other languages are supported by constructing a __duration_punct with the proper spellings for "hours", "minutes" and "seconds", and their abbreviations (for the short format). The short or long format can be easily chosen by streaming a `duration_short()` or `duration_long()` manipulator respectively.
 
@@ -941,7 +941,7 @@
     ClockTick(3) + nanoseconds(10) = 56 [1/5000000000]seconds
 
     Set cout to use short names:
-    milliseconds(3) + microseconds(10) = 3010 µs
+    milliseconds(3) + microseconds(10) = 3010 [mu]s
     hours(3) + minutes(10) = 190 m
     ClockTick(3) + nanoseconds(10) = 56 [1/5000000000]s
 
@@ -951,7 +951,7 @@
     Set cout to use long names:
     high_resolution_clock::now() = 37297387655134 nanoseconds since boot
 
-Parsing a __duration follows rules analogous to the __duration converting constructor. A value and a unit (short or long) are read from the `basic_istream`. If the __duration has an integral representation, then the value parsed must be exactly representable in the target __duration (after conversion to the target __duration units), else `failbit` is set. __duration_s based on floating point representations can be parsed using any units that do not cause overflow.
+Parsing a __duration follows rules analogous to the __duration converting constructor. A value and a unit (short or long) are read from the `basic_istream`. If the __duration has an integral representation, then the value parsed must be exactly representable in the target __duration (after conversion to the target __duration units), else `failbit` is set. __durations based on floating-point representations can be parsed using any units that do not cause overflow.
 
 For example a stream containing "5000 milliseconds" can be parsed into seconds, but if the stream contains "5001 milliseconds", parsing into `seconds` will cause `failbit` to be set.
 
@@ -1056,7 +1056,7 @@
 [/===============]
 [section How you Override the Duration's Default Constructor]
 
-Next follows how you override the duration's default constructor to do anything you want (in this case set it to zero). All we need to do is to change the representation
+Next we show how to override the __duration_s default constructor to do anything you want (in this case set it to zero). All we need to do is to change the representation
 
     namespace I_dont_like_the_default_duration_behavior {
 
@@ -1119,7 +1119,7 @@
 [/=========================]
 [section runtime_resolution]
 
-This example shows how to handle duration with resolution not known until run time
+This example shows how to handle duration with resolution not known until run-time
 
     class duration
     {
@@ -1182,11 +1182,10 @@
 [/================]
 [section Saturating]
 
-A "saturating" signed integral type is developed.  This type has +/- infinity and a nan (like IEEE floating point) but otherwise obeys signed integral arithmetic. This class is subsequently used as the rep in bchrono::__duration to demonstrate a duration class that does not silently ignore overflow.
+A "saturating" signed integral type is developed.  This type has +/- infinity and a NaN (like IEEE floating-point) but otherwise obeys signed integral arithmetic. This class is subsequently used as the template parameter Rep in bchrono::__duration to demonstrate a duration class that does not silently ignore overflow.
 
 ['See the source file [@../../example/saturating.cpp example/saturating.cpp]]
 
-
 [endsect]
 
 
@@ -1214,7 +1213,7 @@
         return result;
     }
 
-Demonstrate interaction with xtime-like facility:
+To demonstrate interaction with an xtime-like facility:
 
 
     struct xtime
@@ -1268,7 +1267,7 @@
         print(xt);
 
 
-['See the source file [@../../example/xtime.cpp here]]
+['See the source file [@../../example/xtime.cpp xtime.cpp]]
 
 [endsect]
 
@@ -1327,14 +1326,14 @@
         }
     };
 
-['See the source file [@../../example/cycle_count.cpp here]]
+['See the source file [@../../example/cycle_count.cpp cycle_count.cpp]]
 
 [endsect]
 
 [/==================]
 [section xtime_clock]
 
-This example demonstrates the use of a timeval-like struct to be used as the representation type for both __duraiton__ and __time_point.
+This example demonstrates the use of a timeval-like struct to be used as the representation type for both __duration and __time_point.
 
     class xtime {
     private:
@@ -1504,7 +1503,6 @@
 
 ['See the source file [@../../example/min_time_point.cpp example/min_time_point.cpp]]
 
-
 [endsect]
 
 
@@ -1576,6 +1574,8 @@
 The output of this program run looks like this:
 
 
+
+
 ['See the source file [@../../example/await_keystroke.cpp example/await_keystroke.cpp]]
 
 [endsect]
@@ -1630,11 +1630,11 @@
 
 [section 24 Hours Display]
 
-In the example above we take advantage of the fact that __time_point_s convert as long as they have the same clock, and as long as their internal __duration_s convert. We also take advantage of the fact that a __duration with a floating point representation will convert from anything. Finally the I/O system discovers the more readable "hours" unit for our `duration<double, ratio<3600>>`.
+In the example above we take advantage of the fact that __time_points convert as long as they have the same clock, and as long as their internal __durations convert. We also take advantage of the fact that a __duration with a floating-point representation will convert from anything. Finally the I/O system discovers the more readable "hours" unit for our `duration<double, ratio<3600>>`.
 
 There are many other ways to format __durations and __time_points. For example see [@http://en.wikipedia.org/wiki/ISO_8601#Durations ISO 8601]. Instead of coding every possibility into `operator<<`, which would lead to significant code bloat for even the most trivial uses, this document seeks to inform the reader how to write custom I/O when desired.
 
-As an example, the function below streams arbitrary durations to arbitrary `basic_ostreams` using the format:
+As an example, the function below streams arbitrary __durations to arbitrary `basic_ostreams` using the format:
 
     [-]d/hh:mm:ss.cc
 
@@ -1728,7 +1728,7 @@
 [/=======================================================]
 [section Simulated Thread Interface Demonstration Program]
 
-The C++0x standard library's multi-threading library requires the ability to deal with the representation of time in a manner consistent with modern C++ practices. Next follows a simulation of this interface.
+The C++0x standard library's multi-threading library requires the ability to deal with the representation of time in a manner consistent with modern C++ practices. Next is a simulation of this interface.
 
 The non-member sleep functions can be emulated as follows:
 
@@ -1765,7 +1765,7 @@
     }}
 
 
-Next follows the `boost::thread::timed_mutex` modified fuctions
+Next is the `boost::thread::timed_mutex` modified fuctions
 
     namespace boost {
     struct timed_mutex {
@@ -1856,7 +1856,7 @@
     cv.wait_for(m, chrono::__minutes(1));    // real code would put this in a loop
     cv.wait_until(m, time_limit);  // real code would put this in a loop
 
-    // For those who prefer floating point
+    // For those who prefer floating-point
     this_thread::sleep_for(chrono::__duration<double>(0.25));
     this_thread::sleep_until(chrono::__system_clock::now() + chrono::__duration<double>(1.5));
 
@@ -1893,7 +1893,7 @@
         cout << h << ", " << m << ", " << s << " et " << ms << '\n';
     }
 
-Output is: 
+Output is:
 
     5 heures, 45 minutes, 15 secondes et 763 millisecondes
 
@@ -1975,9 +1975,9 @@
 
 When `BOOST_NO_STATIC_ASSERT` is defined, the user can select the way static assertions are reported. Define
 
-* `BOOST_CHRONO_USES_STATIC_ASSERT`: define it if you want to use Boost.StaticAssert
-* `BOOST_CHRONO_USES_MPL_ASSERT`: define it if you want to use Boost.MPL static asertions
-* `BOOST_CHRONO_USES_ARRAY_ASSERT`: define it if you want to use internal static asertions
+* `BOOST_CHRONO_USES_STATIC_ASSERT`: define it if you want to use Boost.StaticAssert.
+* `BOOST_CHRONO_USES_MPL_ASSERT`: define it if you want to use Boost.MPL static asertions.
+* `BOOST_CHRONO_USES_ARRAY_ASSERT`: define it if you want to use internal static asertions.
 
 The default behavior is as `BOOST_CHRONO_USES_ARRAY_ASSERT` was defined.
 
@@ -2077,7 +2077,7 @@
             const Rep1& s,
             const duration<Rep2, Period>& d);
         #endif
-        
+
         // duration comparisons
         template <class Rep1, class Period1, class Rep2, class Period2>
         constexpr bool operator==(
@@ -2131,7 +2131,7 @@
     template <class Rep> struct treat_as_floating_point
         : boost::is_floating_point<Rep> {};
 
-The __duration template uses the __treat_as_floating_point trait to help determine if a __duration with one tick period can be converted to another __duration with a different tick period. If `treat_as_floating_point<Rep>::value` is `true`, then `Rep` is a floating point type and implicit conversions are allowed among __duration_s. Otherwise, the implicit convertibility depends on the tick periods of the __duration_s. If `Rep` is a class type which emulates a floating point type, the author of `Rep` can specialize __treat_as_floating_point so that __duration will treat this `Rep` as if it were a floating point type. Otherwise `Rep` is assumed to be an integral type, or a class emulating an integral type.
+The __duration template uses the __treat_as_floating_point trait to help determine if a __duration with one tick period can be converted to another __duration with a different tick period. If `treat_as_floating_point<Rep>::value` is `true`, then `Rep` is a floating-point type and implicit conversions are allowed among __durations. Otherwise, the implicit convertibility depends on the tick periods of the __durations. If `Rep` is a class type which emulates a floating-point type, the author of `Rep` can specialize __treat_as_floating_point so that __duration will treat this `Rep` as if it were a floating-point type. Otherwise `Rep` is assumed to be an integral type, or a class emulating an integral type.
 
 
 [endsect]
@@ -2190,7 +2190,7 @@
 
 The period of the __duration indicated by this specialization of __common_type is the greatest common divisor of `Period1` and `Period2`. This can be computed by forming a __ratio of the greatest common divisor of `Period1::num` and `Period2::num`, and the least common multiple of `Period1::den` and `Period2::den`.
 
-[*Note:] The typedef type is the __duration with the largest tick period possible where both __duration arguments will convert to it without requiring a division operation. The representation of this type is intended to be able to hold any value resulting from this conversion, with the possible exception of round-off error when floating point __duration_s are involved (but not truncation error).
+[*Note:] The typedef type is the __duration with the largest tick period possible where both __duration arguments will convert to it without requiring a division operation. The representation of this type is intended to be able to hold any value resulting from this conversion, with the possible exception of round-off error when floating-point __durations are involved (but not truncation error).
 
 [endsect]
 
@@ -2268,7 +2268,7 @@
 * `treat_as_floating_point<rep>::value` is `true`, or
 * `!treat_as_floating_point<rep>::value && !treat_as_floating_point<Rep2>::value` is `true`.
 
-If these constraints are not met, this constructor will not participate in overload resolution. [*Note:] This requirement prevents construction of an integral-based __duration with a floating point representation. Such a construction could easily lead to confusion about the value of the __duration.
+If these constraints are not met, this constructor will not participate in overload resolution. [*Note:] This requirement prevents construction of an integral-based __duration with a floating-point representation. Such a construction could easily lead to confusion about the value of the __duration.
 
 __example
 
@@ -2285,7 +2285,7 @@
     template <class Rep2, class Period2>
     constexpr __duration(const __duration<Rep2, Period2>& d);
 
-__remarks `treat_as_floating_point<rep>::value`, or `ratio_divide<Period2, period>::type::den == 1`, else this constructor will not participate in overload resolution. [*note] This requirement prevents implicit truncation error when converting between integral-based __duration_s. Such a construction could easily lead to confusion about the value of the __duration.
+__remarks `treat_as_floating_point<rep>::value`, or `ratio_divide<Period2, period>::type::den == 1`, else this constructor will not participate in overload resolution. [*note] This requirement prevents implicit truncation error when converting between integral-based __durations. Such a construction could easily lead to confusion about the value of the __duration.
 
 __example
 
@@ -2609,7 +2609,7 @@
                                                                static_cast<CR>(CF::num)   /
                                                                static_cast<CR>(CF::den)))`
 
-__remarks This function does not rely on any implicit conversions. All conversions must be accomplished through `static_cast`. The implementation avoids all multiplications or divisions when it is known at compile time that it can be avoided because one or more arguments are `1`. All intermediate computations are carried out in the widest possible representation and only converted to the destination representation at the final step.
+__remarks This function does not rely on any implicit conversions. All conversions must be accomplished through `static_cast`. The implementation avoids all multiplications or divisions when it is known at compile-time that it can be avoided because one or more arguments are `1`. All intermediate computations are carried out in the widest possible representation and only converted to the destination representation at the final step.
 
 
 [endsect]
@@ -2641,7 +2641,7 @@
     [[`C1::rep`]        [An arithmetic type or class emulating an arithmetic type. ]  [The representation type of the  __duration and __time_point.]]
     [[`C1::period`]        [`ratio`]  [The tick period of the clock in seconds.]]
     [[`C1::duration`]        [`chrono::duration<C1::rep, C1::period>`]  [The  __duration type of the `clock`.]]
-    [[`C1::time_point`]        [`chrono::time_point<C1> or chrono::time_point<C2, C1::duration>`]  [The  __time_point type of the `clock`. Different clocks are permitted to share a __time_point definition if it is valid to compare their time_points by comparing their respective __duration_s. `C1` and `C2` must refer to the same epoch.]]
+    [[`C1::time_point`]        [`chrono::time_point<C1> or chrono::time_point<C2, C1::duration>`]  [The  __time_point type of the `clock`. Different clocks are permitted to share a __time_point definition if it is valid to compare their time_points by comparing their respective __durations. `C1` and `C2` must refer to the same epoch.]]
     [[`C1::is_steady`]        [`constexpr bool`]  [`true` if `t1 <= t2` is always `true`, else `false`. *Note*: A `clock` that can be adjusted backwards is not steady]]
     [[`C1::now()`]        [`C1::time_point`]  [Returns a __time_point representing the current point in time.]]
 ]
@@ -2731,7 +2731,7 @@
         typedef chrono::__time_point<Clock, typename __common_type<Duration1, Duration2>::type> type;
     };
 
-The __common_type of two __time_point_s is a __time_point with the same `clock` (both have the same `clock`), and the __common_type of the two __duration_s.
+The __common_type of two __time_points is a __time_point with the same `clock` (both have the same `clock`), and the __common_type of the two __durations.
 
 [endsect]
 
@@ -3166,7 +3166,7 @@
         static std::basic_string<CharT> name();
         static std::basic_string<CharT> since();
 
-`clock_string<>::name()` return the clock name, which usualy corresponds to the class name.
+`clock_string<>::name()` return the clock name, which usually corresponds to the class name.
 `clock_string<>::since()` return the textual format of the clock epoch.
 
 
@@ -3288,7 +3288,7 @@
             std::basic_ostream<CharT, Traits>&
             duration_short(std::basic_ostream<CharT, Traits>& os);
 
-__effects Set the __duration_punct facet to stream __durations and __time_points as abreviations.
+__effects Set the __duration_punct facet to stream __durations and __time_points as abbreviations.
 
 __returns the output stream
 
@@ -3306,7 +3306,7 @@
 
 [section:streams I/O Streams Operations]
 
-Any __duration can be streamed out to a `basic_ostream`. The run time value of the __duration is formatted according to the rules and current format settings for __duration`::rep`. This is followed by a single space and then the compile time unit name of the __duration. This unit name is built on the string returned from `ratio_string<>` and the data used to construct the __duration_punct which was inserted into the stream's locale. If a __duration_punct has not been inserted into the stream's locale, a default constructed __duration_punct will be added to the stream's locale.
+Any __duration can be streamed out to a `basic_ostream`. The run-time value of the __duration is formatted according to the rules and current format settings for __duration`::rep`. This is followed by a single space and then the compile-time unit name of the __duration. This unit name is built on the string returned from `ratio_string<>` and the data used to construct the __duration_punct which was inserted into the stream's locale. If a __duration_punct has not been inserted into the stream's locale, a default constructed __duration_punct will be added to the stream's locale.
 
 A __time_point is formatted by outputting its internal __duration followed by a string that describes the __time_point`::clock` epoch. This string will vary for each distinct clock, and for each implementation of the supplied clocks.
 
@@ -3559,11 +3559,11 @@
 
 Notes
 
-* `min()` returns the tuple of min's
-* `max()` returns the tuple of max's
-* `lowest()' returns the tuple of lowest's
-* `digits' is the sum of digits's
-* `digits10' is the sum of digits10's
+* `min()` returns the tuple of mins.
+* `max()` returns the tuple of maxs.
+* `lowest()` returns the tuple of lowests.
+* `digits` is the sum of (binary) digits.
+* `digits10` is the sum of digits10s.
 
 [endsect]
 
@@ -3769,7 +3769,7 @@
 [endsect]
 [section:run_timer Class `run_timer`]
 
-class `run_timer` provides a complete run time reporting package that can be invoked in a single line of code. The reporting is controlled by two parameters:
+class `run_timer` provides a complete run-time reporting package that can be invoked in a single line of code. The reporting is controlled by two parameters:
 
 * format : The output format
 * places(precision): the number of decimal placess used.
@@ -3842,20 +3842,14 @@
 [section:history Appendix A: History]
 [/==================================]
 
-[/
 [section [*Version 1.0.0, January 6, 2011] ]
 
 * Moved chrono to trunk taking in account the review remarks.
 * Documentation revision.
 
-[endsect]
-]
-[/
-[section [*Version 0.7.0, October 30, 2010] ]
-
 [*Features:]
 
-* Boost_Chrono is now a configurable header only lib that allows the user to choose in addition if the windows file is included or not.
+* Boost_Chrono is now a configurable header-only library version (that also allows the user to choose if the `windows.h` file is included or not).
 * Added clock_string<> traits.
 * Define chrono-io for all the clocks
 * Add input of process_times representation
@@ -3883,7 +3877,8 @@
 
 * Removed some not useful parts as the history, the test and the tickets.
 
-[endsect]
+[endsect] [/section [*Version 1.0.0, January 6, 2011] ]
+
 [section [*Version 0.6.0, September 22, 2010] ]
 
 [*Features:]
@@ -4238,11 +4233,11 @@
 
 Each clock has his own features. It depends on what do you need to benchmark. Most of the time, you could be interested in using a thread clock, but if you need to measure code subject to synchronization a process clock would be better. If you have a multi-process application, a system-wide clock could be needed.
 
-[heading Which clocsk should be used to watching?]
+[heading Which clocks should be used for watching?]
 
-For trace purposes it seems better to use a system-wide clock.
+For trace purposes, it is probably best to use a system-wide clock.
 
-[endsect]
+[endsect] [/section:faq Appendix D: FAQ]
 
 [/====================================================]
 [section:acknowledgements Appendix E: Acknowledgements]
@@ -4257,13 +4252,13 @@
 
 Howard Hinnant, who is the real author of the library, has provided valuable feedback and suggestions during the development of the library. In particular, The chrono_io_io.hpp source has been adapted from the experimental header `<chrono_io>` from Howard Hinnant.
 
-The acceptance review of Boost.Ratio took place between November 5th and 15th 2010. Many thanks to Anthony Williams, the review manager, and to all the reviewers: David Deakins, John Bytheway, Roland Bock and Paul A. Bristol.
+The acceptance review of Boost.Ratio took place between November 5th and 15th 2010. Many thanks to Anthony Williams, the review manager, and to all the reviewers: David Deakins, John Bytheway, Roland Bock and Paul A. Bristow.
 
-Thanks to Ronald Bock, Andrew Chinoff, Paul A. Bristol and John Bytheway for his help polishing the documentation.
+Thanks to Ronald Bock, Andrew Chinoff, Paul A. Bristow and John Bytheway for his help polishing the documentation.
 
 Thanks to Tom Tan for reporting some compiler issues with MSVC V10 beta and MinGW-gcc-4.4.0 and for the many pushing for an homogeneous `process_cpu_clock` clock.
 
-Thanks to Ronald Bock for reporting Valgind issues and for the many suggestion he did concerning the documentation.
+Thanks to Ronald Bock for reporting Valgind issues and for the many suggestions he made concerning the documentation.
 
 [endsect]
 
@@ -4375,10 +4370,10 @@
     [[Name]                         [kind]          [Description]           [Result] [Ticket]]
 
     [[cons.convert_exact.pass]              [run]           [check exact conversions allowed for integral reps.]                    [Pass]   [#]]
-    [[cons.convert_float_to_int.fail]       [compile-fail]  [check conversions from floating point to integral durations disallowed.]   [Pass]   [#]]
+    [[cons.convert_float_to_int.fail]       [compile-fail]  [check conversions from floating-point to integral durations disallowed.]   [Pass]   [#]]
     [[cons.convert_inexact.fail]            [compile-fail]  [check inexact conversions disallowed for integral reps.]               [Pass]   [#]]
-    [[cons.convert_inexact.pass]            [run]           [check inexact conversions allowed for floating point reps.]            [Pass]   [#]]
-    [[cons.convert_int_to_float.pass]       [run]           [check conversions from integral to floating point durations allowed.]  [Pass]   [#]]
+    [[cons.convert_inexact.pass]            [run]           [check inexact conversions allowed for floating-point reps.]            [Pass]   [#]]
+    [[cons.convert_int_to_float.pass]       [run]           [check conversions from integral to floating-point durations allowed.]  [Pass]   [#]]
     [[cons.default.pass]                    [run]           [check Rep must be default initialized, not initialized with 0.]        [Pass]   [#]]
     [[cons.rep.pass]                        [run]           [check explicit duration(const Rep2& r).]                               [Pass]   [#]]
     [[cons.rep01.fail]                      [compile-fail]  [test for explicit.]                                                    [Pass]   [#]]
@@ -4549,4 +4544,5 @@
 * Add chrono utilities as defined By Howard Hinnant in [@http://home.roadrunner.com/~hinnant/duration_io/chrono_util.html here].
 
 [endsect]
+
 [endsect]