[Boost-commit] svn:boost r65929 - sandbox/chrono/libs/ratio/doc

Subject: [Boost-commit] svn:boost r65929 - sandbox/chrono/libs/ratio/doc
From: vicente.botet_at_[hidden]
Date: 2010-10-12 16:02:00

Author: viboes
Date: 2010-10-12 16:01:58 EDT (Tue, 12 Oct 2010)
New Revision: 65929
URL: http://svn.boost.org/trac/boost/changeset/65929

Log:
Ratio:
* Update doc after review
Text files modified: 
   sandbox/chrono/libs/ratio/doc/ratio.qbk |   488 +++++++++++++++++---------------------- 
   1 files changed, 216 insertions(+), 272 deletions(-)

Modified: sandbox/chrono/libs/ratio/doc/ratio.qbk
==============================================================================
--- sandbox/chrono/libs/ratio/doc/ratio.qbk	(original)
+++ sandbox/chrono/libs/ratio/doc/ratio.qbk	2010-10-12 16:01:58 EDT (Tue, 12 Oct 2010)
@@ -9,7 +9,7 @@
 
 [article Boost.Ratio
     [quickbook 1.5]
-    [version 0.2.1]
+    [version 1.0.0]
     [authors [Hinnant, Howard]]
     [authors [Dawes, Beman]]
     [authors [Botet Escriba, Vicente J.]]
@@ -49,130 +49,43 @@
 
 [template ratio_conf[link_text] [link boost_ratio.reference.ratio_hpp.conf [link_text]]]
 
-[template ratio_pp[link_text] [link boost_ratio.reference.ratio_hpp.pp [link_text]]]
-
-[def __BOOST_RATIO_USES_STATIC_ASSERT [ratio_conf `BOOST_RATIO_USES_STATIC_ASSERT`]]
-[def __BOOST_RATIO_USES_MPL_ASSERT [ratio_conf `BOOST_RATIO_USES_MPL_ASSERT`]]
-[def __BOOST_RATIO_USES_ARRAY_ASSERT [ratio_conf `BOOST_RATIO_USES_ARRAY_ASSERT`]]
+[def __BOOST_RATIO_USES_STATIC_ASSERT [link boost_ratio.reference.ratio_hpp.conf `BOOST_RATIO_USES_STATIC_ASSERT`]]
+[def __BOOST_RATIO_USES_MPL_ASSERT [link boost_ratio.reference.ratio_hpp.conf `BOOST_RATIO_USES_MPL_ASSERT`]]
+[def __BOOST_RATIO_USES_ARRAY_ASSERT [link boost_ratio.reference.ratio_hpp.conf `BOOST_RATIO_USES_ARRAY_ASSERT`]]
 
 [template ratio_arithmetic[link_text] [link boost_ratio.reference.ratio_hpp.ratio_arithmetic [link_text]]]
-[def __ratio_add [ratio_arithmetic `ratio_add`]]
-[def __ratio_subtract [ratio_arithmetic `ratio_subtract`]]
-[def __ratio_multiply [ratio_arithmetic `ratio_multiply`]]
-[def __ratio_divide [ratio_arithmetic `ratio_divide`]]
+[def __ratio_add [link boost_ratio.reference.ratio_hpp.ratio_arithmetic `ratio_add`]]
+[def __ratio_subtract [link boost_ratio.reference.ratio_hpp.ratio_arithmetic `ratio_subtract`]]
+[def __ratio_multiply [link boost_ratio.reference.ratio_hpp.ratio_arithmetic `ratio_multiply`]]
+[def __ratio_divide [link boost_ratio.reference.ratio_hpp.ratio_arithmetic `ratio_divide`]]
 
 
 [template ratio_comparison[link_text] [link boost_ratio.reference.ratio_hpp.ratio_comparison [link_text]]]
-[def __ratio_equal [ratio_comparison `ratio_equal`]]
-[def __ratio_not_equal [ratio_comparison `ratio_not_equal`]]
-[def __ratio_less [ratio_comparison `ratio_less`]]
-[def __ratio_less_equal [ratio_comparison `ratio_less_equal`]]
-[def __ratio_greater [ratio_comparison `ratio_greater`]]
-[def __ratio_greater_equal [ratio_comparison `ratio_greater_equal`]]
+[def __ratio_equal [link boost_ratio.reference.ratio_hpp.ratio_comparison `ratio_equal`]]
+[def __ratio_not_equal [link boost_ratio.reference.ratio_hpp.ratio_comparison `ratio_not_equal`]]
+[def __ratio_less [link boost_ratio.reference.ratio_hpp.ratio_comparison `ratio_less`]]
+[def __ratio_less_equal [link boost_ratio.reference.ratio_hpp.ratio_comparison `ratio_less_equal`]]
+[def __ratio_greater [link boost_ratio.reference.ratio_hpp.ratio_comparison `ratio_greater`]]
+[def __ratio_greater_equal [link boost_ratio.reference.ratio_hpp.ratio_comparison `ratio_greater_equal`]]
 
 
 [template ratio_si_typedefs[link_text] [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs [link_text]]]
-[def __atto [ratio_si_typedefs `atto`]]
-[def __femto [ratio_si_typedefs `femto`]]
-[def __pico [ratio_si_typedefs `pico`]]
-[def __nano [ratio_si_typedefs `nano`]]
-[def __micro [ratio_si_typedefs `micro`]]
-[def __milli [ratio_si_typedefs `milli`]]
-[def __centi [ratio_si_typedefs `centi`]]
-[def __deci [ratio_si_typedefs `deci`]]
-[def __deca [ratio_si_typedefs `deca`]]
-[def __hecto [ratio_si_typedefs `hecto`]]
-[def __kilo [ratio_si_typedefs `kilo`]]
-[def __mega [ratio_si_typedefs `mega`]]
-[def __giga [ratio_si_typedefs `giga`]]
-[def __tera [ratio_si_typedefs `tera`]]
-[def __peta [ratio_si_typedefs `peta`]]
-[def __exa [ratio_si_typedefs `exa`]]
-
-
-[/==================]
-
-
-[template chrono_conf[link_text] [link_text]]
-
-
-[def __BOOST_CHRONO_USES_STATIC_ASSERT [chrono_conf `BOOST_CHRONO_USES_STATIC_ASSERT`]]
-[def __BOOST_CHRONO_USES_MPL_ASSERT [chrono_conf `BOOST_CHRONO_USES_MPL_ASSERT`]]
-[def __BOOST_CHRONO_USES_ARRAY_ASSERT [chrono_conf `BOOST_CHRONO_USES_ARRAY_ASSERT`]]
-
-[def __BOOST_CHRONO_HAS_CLOCK_MONOTONIC `BOOST_CHRONO_HAS_CLOCK_MONOTONIC`]
-
-
-
-[template clock_concept_link[link_text] [link_text]]
-[def __clock_concept__ [clock_concept_link `Clock` concept]]
-[def __clock_concept_type__ [clock_concept_link `Clock`]]
-[def __clock_req__ [clock_concept_link `Clock` requirements]]
-[def __Clock__ [clock_concept_link `Clock`]]
-[def __Clock_s__ [clock_concept_link `Clock`'s]]
-
-
-[template duration_link[link_text] [link_text]]
-[def __duration__ [duration_link `duration`]]
-[def __duration_s__ [duration_link `duration`'s]]
-
-[/==================]
-[template time_point_link[link_text] [link_text]]
-[def __time_point__ [time_point_link `time_point`]]
-[def __time_point_s__ [time_point_link `time_point`'s]]
-
-[/==================]
-[template system_clock_link[link_text] [link_text]]
-[def __system_clock__ [system_clock_link `system_clock`]]
-
-[/==================]
-[template monotonic_clock_link[link_text] [link_text]]
-[def __monotonic_clock__ [monotonic_clock_link `monotonic_clock`]]
-
-[/==================]
-[template high_resolution_clock_link[link_text] [link_text]]
-[def __high_resolution_clock__ [high_resolution_clock_link `high_resolution_clock`]]
-
-[def __duration_cast__ `duration_cast`]
-
-[def __time_point_cast__ `time_point_cast`]
-
-
-[template duration_typedefs[link_text] [link_text]]
-[def __nanoseconds__ [duration_typedefs `nanoseconds`]]
-[def __microseconds__ [duration_typedefs `microseconds`]]
-[def __milliseconds__ [duration_typedefs `milliseconds`]]
-[def __seconds__ [duration_typedefs `seconds`]]
-[def __minutes__ [duration_typedefs `minutes`]]
-[def __hours__ [duration_typedefs `hours`]]
-[def __days__ [duration_typedefs `days`]]
-
-
-[/==================]
-[def __treat_as_floating_point__ `treat_as_floating_point`]
-[def __duration_values__ `duration_values`]
-[def __zero__ `zero`]
-[def __max__ `max`]
-[def __min__ `min`]
-
-
-[/==================]
-[template SuspendibleClock_concept_link[link_text] [link_text]]
-[def __SuspendibleClock_concept__ [SuspendibleClock_concept_link `SuspendibleClock` concept]]
-[def __SuspendibleClock_concept_type__ [SuspendibleClock_concept_link `SuspendibleClock`]]
-[def __SuspendibleClock_req__ [SuspendibleClock_concept_link `SuspendibleClock` requirements]]
-[def __SuspendibleClock__ [SuspendibleClock_concept_link `SuspendibleClock`]]
-
-
-[def __process_real_cpu_clock__ [link boost_ratio.reference.other_clocks.process_cpu_clocks_hpp.process_real_cpu_clock `process_real_cpu_clock`]]
-
-[def __process_system_cpu_clock__ [link boost_ratio.reference.other_clocks.process_cpu_clocks_hpp.process_system_cpu_clock `process_system_cpu_clock`]]
-
-[def __process_user_cpu_clock__ [link boost_ratio.reference.other_clocks.process_cpu_clocks_hpp.process_user_cpu_clock `process_user_cpu_clock`]]
-
-[def __thread_clock__ `thread_clock`]
-[def __suspendible_clock__ `suspendible_clock`]
-
+[def __atto [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `atto`]]
+[def __femto [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `femto`]]
+[def __pico [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `pico`]]
+[def __nano [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `nano`]]
+[def __micro [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `micro`]]
+[def __milli [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `milli`]]
+[def __centi [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `centi`]]
+[def __deci [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `deci`]]
+[def __deca [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `deca`]]
+[def __hecto [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `hecto`]]
+[def __kilo [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `kilo`]]
+[def __mega [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `mega`]]
+[def __giga [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `giga`]]
+[def __tera [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `tera`]]
+[def __peta [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `peta`]]
+[def __exa [link boost_ratio.reference.ratio_hpp.ratio_si_typedefs `exa`]]
 
 
 [warning Ratio is not part of the Boost libraries.]
@@ -220,7 +133,7 @@
 
 * A class template, __ratio__, for specifying compile time rational constants such as 1/3 of a nanosecond or the number of inches per meter.  __ratio__ represents a compile time ratio of compile time constants with support for compile time arithmetic with overflow and division by zero protection
 
-* It provides a textual representation of `boost::ratio<N, D>` in the form of a `std::basic_string`. Other types such as `boost::duration` can use these strings to aid in their I/O.
+* It provides a textual representation of `boost::ratio<N, D>` in the form of a `std::basic_string` which can be useful for I/O.
 
 [endsect]
 
@@ -228,7 +141,7 @@
 
 
 [/==============================]
-[section:users_guide Users'Guide]
+[section:users_guide User's Guide]
 [/==============================]
 
 [/======================================]
@@ -301,10 +214,10 @@
 
 
 [/=========================]
-[heading Exceptions safety ]
+[heading Exception safety ]
 [/=========================]
 
-All functions in the library are exception-neutral and provide strong guarantee of exception safety as long as the underlying parameters provide it.
+All functions in the library are exception-neutral, providing the strong exception safety guarantee.
 
 [/=====================]
 [heading Thread safety ]
@@ -316,8 +229,7 @@
 [heading Tested compilers ]
 [/========================]
 
-The implementation will eventually work with most C++03 conforming compilers.
-Current version has been tested on:
+__Boost_Ratio__ should work with an C++03 conforming compiler.  The current version has been tested on:
 
 Windows with
 
@@ -369,9 +281,11 @@
 
 [section Tutorial]
 
-__ratio__ is a general purpose utility inspired by Walter Brown allowing one to easily and safely compute rational values at compile time. The __ratio__ class catches all errors (such as divide by zero and overflow) at compile time. It is used in the __duration__ and __time_point__ classes to efficiently create units of time. It can also be used in other "quantity" libraries (both std-defined and user-defined), or anywhere there is a rational constant which is known at compile time. The use of this utility can greatly reduce the chances of run time overflow because the __ratio__ (and any ratios resulting from __ratio__ arithmetic) are always reduced to lowest terms.
+[heading Ratio]
+
+__ratio__ is a general purpose utility inspired by Walter Brown allowing one to easily and safely compute rational values at compile time. The __ratio__ class catches all errors (such as divide by zero and overflow) at compile time. It is used in the duration and __time_point__ classes to efficiently create units of time. It can also be used in other "quantity" libraries or anywhere there is a rational constant which is known at compile time. The use of this utility can greatly reduce the chances of run time overflow because the __ratio__ (and any ratios resulting from __ratio__ arithmetic) are always reduced to lowest terms.
 
-__ratio__ is a template taking two intmax_ts, with the second defaulted to 1. In addition to copy constructors and assignement, it only has two public members, both of which are static const intmax_t. One is the numerator of the __ratio__ and the other is the denominator. The __ratio__ is always normalized such that it is expressed in lowest terms, and the denominator is always positive. When the numerator is 0, the denominator is always 1.
+__ratio__ is a template taking two intmax_ts, with the second defaulted to 1. In addition to copy constructors and assignment, it only has two public members, both of which are static const intmax_t. One is the numerator of the __ratio__ and the other is the denominator. The __ratio__ is always normalized such that it is expressed in lowest terms, and the denominator is always positive. When the numerator is 0, the denominator is always 1.
 
 [*Example:]
 
@@ -384,7 +298,7 @@
     typedef ratio_divide<five_thirds, also_five_thirds>::type one;  
     // one::num == 1, one::den == 1
 
-This facility also includes convenience typedefs for the SI prefixes __atto through __exa corresponding to their internationally recognized definitions (in terms of __ratio__). This is a tremendous syntactic convenience. It will prevent errors in specifying constants as one no longer has to double count the number of zeros when trying to write million or billion.
+This facility also includes convenience typedefs for the SI prefixes __atto through __exa corresponding to their internationally recognized definitions (in terms of __ratio__). This is a tremendous syntactic convenience. It will prevent errors in specifying constants as one no longer has to double count the number of zeros when trying to write millions or billions.
 
 [*Example:]
 
@@ -394,20 +308,69 @@
     typedef ratio_multiply<__ratio__<5>, nano>::type _5nano;  
     // _5nano::num == 1, _5nano::den == 200000000
 
+[heading Ratio I/O]
+
+For each `ratio<N, D>` there exists a `ratio_string<ratio<N, D>, CharT>` for which you can query two strings: `short_name` and `long_name`. For those `ratio`'s that correspond to an [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes SI prefix] long_name corresponds to the internationally recognized prefix, stored as a `basic_string<CharT>`. For example `ratio_string<mega, char>::long_name()` returns `string("mega")`. For those `ratio`'s that correspond to an [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes SI prefix] `short_name` corresponds to the internationally recognized symbol, stored as a `basic_string<CharT>`. For example `ratio_string<mega, char>::short_name()` returns `string("M")`. For all other `ratio`'s, both `long_name()` and `short_name()` return a `basic_string` containing "[`ratio::num/ratio::den`]".
+
+`ratio_string<ratio<N, D>, CharT>` is only defined for four character types:
+
+* `char`: UTF-8 
+* `char16_t`: UTF-16
+* `char32_t`: UTF-32
+* `wchar_t`: UTF-16 (if wchar_t is 16 bits) or UTF-32
+
+When the character is char, UTF-8 will be used to encode the names. When the character is `char16_t`, UTF-16 will be used to encode the names. When the character is `char32_t`, UTF-32 will be used to encode the names. When the character is `wchar_t`, the encoding will be UTF-16 if `wchar_t` is 16 bits, and otherwise UTF-32.
+
+The `short_name` for micro is defined by [@http://www.unicode.org/charts/PDF/U0080.pdf Unicode] to be U+00B5. 
 
+[*Examples:]
+
+    #include <boost/ratio/ratio_io.hpp>
+    #include <iostream>
+
+    int main()
+    {
+        using namespace std;
+        using namespace boost;
+
+        cout << "ratio_string<deca, char>::long_name() = "
+             <<  ratio_string<deca, char>::long_name() << '\n';
+        cout << "ratio_string<deca, char>::short_name() = "
+             <<  ratio_string<deca, char>::short_name() << '\n';
+
+        cout << "ratio_string<giga, char>::long_name() = "
+             <<  ratio_string<giga, char>::long_name() << '\n';
+        cout << "ratio_string<giga, char>::short_name() = "
+             <<  ratio_string<giga, char>::short_name() << '\n';
+
+        cout << "ratio_string<ratio<4, 6>, char>::long_name() = "
+             <<  ratio_string<ratio<4, 6>, char>::long_name() << '\n';
+        cout << "ratio_string<ratio<4, 6>, char>::short_name() = "
+             <<  ratio_string<ratio<4, 6>, char>::short_name() << '\n';
+    }
+
+The output will be
+
+    ratio_string<deca, char>::long_name() = deca
+    ratio_string<deca, char>::short_name() = da
+    ratio_string<giga, char>::long_name() = giga
+    ratio_string<giga, char>::short_name() = G
+    ratio_string<ratio<4, 6>, char>::long_name() = [2/3]
+    ratio_string<ratio<4, 6>, char>::short_name() = [2/3]
+    
 [endsect]
 [/===============]
-[section Examples]
+[section:Examples Example]
 [/===============]
 
 [/===============]
-[section SI-units]
+[section SI units]
 [/===============]
 
-Type-safe "physics" code interoperating with boost::chrono::__duration__ types and taking advantage of the boost::__ratio__ infrastructure and design philosophy.
+This example illustrates the use of type-safe physics code interoperating with `boost::chrono::duration` types, taking advantage of the __Boost_Ratio__ infrastructure and design philosophy.
+
+Let's start by defining a `length` class template that mimics `boost::chrono::duration`, which represents a time duration in various units, but restricts the representation to `double` and uses __Boost_Ratio__ for length unit conversions:
 
-length - mimics boost::chrono::__duration__ except restricts representation to double.
-Uses boost::__ratio__ facilities for length units conversions.
 
     template <class Ratio>
     class length {
@@ -436,29 +399,29 @@
     };
 
 
-Sparse sampling of length units
+Here's a small sampling of length units:
 
     typedef length<boost::__ratio__<1> >          meter;        // set meter as "unity"
     typedef length<boost::__centi>              centimeter;   // 1/100 meter
     typedef length<boost::__kilo>               kilometer;    // 1000  meters
     typedef length<boost::__ratio__<254, 10000> > inch;         // 254/10000 meters
 
-length takes __ratio__ instead of two integral types so that definitions can be made like so:
+Note that since `length`'s template parameter is actually a generic ratio type, so we can use boost::ratio allowing for more complex length units:
 
     typedef length<boost::ratio_multiply<boost::__ratio__<12>, inch::__ratio__>::type>   foot;  // 12 inchs
     typedef length<boost::ratio_multiply<boost::__ratio__<5280>, foot::__ratio__>::type> mile;  // 5280 feet
 
-Need a floating point definition of seconds
+Now we need a floating point-based definition of seconds:
 
-    typedef boost::chrono::__duration__<double> seconds;                         // unity
+    typedef boost::chrono::duration<double> seconds;                         // unity
 
-Demo of (scientific) support for sub-nanosecond resolutions
+We can even support sub-nanosecond durations:
 
-    typedef boost::chrono::__duration__<double,  boost::__pico> picosecond;  // 10^-12 seconds
-    typedef boost::chrono::__duration__<double, boost::__femto> femtosecond; // 10^-15 seconds
-    typedef boost::chrono::__duration__<double,  boost::__atto> attosecond;  // 10^-18 seconds
+    typedef boost::chrono::duration<double,  boost::__pico> picosecond;  // 10^-12 seconds
+    typedef boost::chrono::duration<double, boost::__femto> femtosecond; // 10^-15 seconds
+    typedef boost::chrono::duration<double,  boost::__atto> attosecond;  // 10^-18 seconds
 
-A very brief proof-of-concept for SIUnits-like library. Hard-wired to floating point seconds and meters, but accepts other units.
+Finally, we can write a proof-of-concept of an SI units library, hard-wired for meters and floating point seconds, though it will accept other units:
 
     template <class R1, class R2>
     class quantity
@@ -509,7 +472,7 @@
         void set(double q) {q_ = q;}
     };
 
-Example of SI-Units
+That allows us to create some useful SI-based unit types:
 
     typedef quantity<boost::__ratio__<0>, boost::__ratio__<0> >  Scalar;
     typedef quantity<boost::__ratio__<1>, boost::__ratio__<0> >  Time;         // second
@@ -517,7 +480,7 @@
     typedef quantity<boost::__ratio__<-1>, boost::__ratio__<1> > Speed;        // meter/second
     typedef quantity<boost::__ratio__<-2>, boost::__ratio__<1> > Acceleration; // meter/second^2
 
-Quantity arithmetics
+To make quantity useful, we need to be able to do arithmetic:
 
     template <class R1, class R2, class R3, class R4>
     quantity<typename boost::ratio_subtract<R1, R3>::type, 
@@ -563,7 +526,7 @@
         return r;
     }
 
-Example type-safe physics function
+With all of the foregoing scaffolding, we can now write an exemplar of a type-safe physics function:
 
     Distance
     compute_distance(Speed v0, Time t, Acceleration a)
@@ -572,10 +535,7 @@
     }
 
 
-Exercise example type-safe physics function and show interoperation
-of custom time durations (User1::seconds) and standard time durations (boost::hours).
-Though input can be arbitrary (but type-safe) units, output is always in SI-units
-(a limitation of the simplified Units lib demoed here).
+Finally, we can exercise what we've created, even using custom time durations (`User1::seconds`) as well as Boost time durations (`boost::chrono::hours`).  The input can be in arbitrary, though type-safe, units, the output is always in SI units.  (A complete Units library would support other units, of course.)
 
     int main()
     {
@@ -623,10 +583,10 @@
         std::cout << "1 second is " << as.count() << " attoseconds\n";
         std::cout << "as = sec;  // compiles\n";
         std::cout << "\n";
-      return 0;
+        return 0;
     }
 
-['See the source file [@../../test/ratio_test.cpp test/ratio_test.cpp]]
+['See the source file [@../../example/si_physics.cpp example/si_physics.cpp]]
 
 [endsect]
 
@@ -641,7 +601,7 @@
 
 [
     [[@http://www.open-std.org/jtc1/sc22/wg21 [*C++ Standards Committee's current Working Paper]]]
-    [The most authoritative reference material for the library is the C++ Standards Committee's current Working Paper (WP).  20.9 Time utilities "time", 20.4 Compile-time rational arithmetic "ratio", 20.6.7 Other transformations "meta.trans.other"]
+    [The most authoritative reference material for the library is the C++ Standards Committee's current Working Paper (WP). 20.6 Compile-time rational arithmetic "ratio"]
 ]
 
 [
@@ -655,11 +615,6 @@
     [From Vicente Juan Botet Escriba.]
 ]
 
-[
-    [[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3131.html [*N3131: Compile-time rational arithmetic and overflow]]]
-    [From 	Anthony Williams.]
-]
-
 
 ]
 
@@ -672,15 +627,10 @@
 [/=================]
 
 [/===========================================]
-[section:ratio_hpp Header `<boost/ratio.hpp>`]
+[section:ratio_fwdhpp Header `<boost/ratio_fwd.hpp>`]
 [/===========================================]
 
-__ratio__ is a facility which is useful in specifying compile time rational constants. Compile time rational arithmetic is supported with protection against overflow and divide by zero. Such a facility is very handy when needing to efficiently represent  1/3 of a nanosecond, or specifying an inch in terms of meters (for example 254/10000 meters - which __ratio__ will reduce to 127/5000 meters).
-
-    // configuration macros
-    #define __BOOST_RATIO_USES_STATIC_ASSERT
-    #define __BOOST_RATIO_USES_MPL_ASSERT
-    #define __BOOST_RATIO_USES_ARRAY_ASSERT
+This header provides forward declarations for the `<boost/ratio.hpp>` file.
 
     namespace boost  {
 
@@ -719,29 +669,43 @@
         typedef ratio<1000000000000000000LL, 1LL> __exa;
     }
 
+[endsect]
+
+[/===========================================]
+[section:ratio_hpp Header `<boost/ratio.hpp>`]
+[/===========================================]
+
+__ratio__ is a facility which is useful in specifying compile time rational constants. Compile time rational arithmetic is supported with protection against overflow and divide by zero. Such a facility is very handy when needing to efficiently represent  1/3 of a nanosecond, or specifying an inch in terms of meters (for example 254/10000 meters - which __ratio__ will reduce to 127/5000 meters).
+
+    // configuration macros
+    #define __BOOST_RATIO_USES_STATIC_ASSERT
+    #define __BOOST_RATIO_USES_MPL_ASSERT
+    #define __BOOST_RATIO_USES_ARRAY_ASSERT
+
 
-[section:conf Configuration macros]
+
+[section:conf Configuration Macros]
 
 When BOOST_NO_STATIC_ASSERT is defined, the user can select the way static assertions are reported. Define
 
-* BOOST_RATIO_USES_STATIC_ASSERT: define it if you want to use Boost.StaticAssert
-* BOOST_RATIO_USES_MPL_ASSERT: define it if you want to use Boost.MPL static asertions
-* BOOST_RATIO_USES_ARRAY_ASSERT: define it if you want to use internal static asertions
+* BOOST_RATIO_USES_STATIC_ASSERT to use Boost.StaticAssert
+* BOOST_RATIO_USES_MPL_ASSERT to use Boost.MPL static assertions
+* BOOST_RATIO_USES_RATIO_ASSERT to use __Boost_Ratio__  static assertions
 
-The default behavior is as BOOST_RATIO_USES_ARRAY_ASSERT was defined.
+The default behavior is as if BOOST_RATIO_USES_ARRAY_ASSERT is defined.
 
 
-When BOOST_RATIO_USES_MPL_ASSERT is not defined the following symbols are defined as
+When BOOST_RATIO_USES_MPL_ASSERT is not defined the following symbols are defined as shown:
 
     #define BOOST_RATIO_OVERFLOW_IN_ADD "overflow in ratio add"
     #define BOOST_RATIO_OVERFLOW_IN_SUB "overflow in ratio sub"
     #define BOOST_RATIO_OVERFLOW_IN_MUL "overflow in ratio mul"
     #define BOOST_RATIO_OVERFLOW_IN_DIV "overflow in ratio div"
-    #define BOOST_RATIO_RATIO_NUMERATOR_IS_OUT_OF_RANGE "ratio numerator is out of range"
-    #define BOOST_RATIO_RATIO_DIVIDE_BY_0 "ratio divide by 0"
-    #define BOOST_RATIO_RATIO_DENOMINATOR_IS_OUT_OF_RANGE "ratio denominator is out of range"
+    #define BOOST_RATIO_NUMERATOR_IS_OUT_OF_RANGE "ratio numerator is out of range"
+    #define BOOST_RATIO_DIVIDE_BY_0 "ratio divide by 0"
+    #define BOOST_RATIO_DENOMINATOR_IS_OUT_OF_RANGE "ratio denominator is out of range"
 
-Depending on the static assertion used system you will have an hint of the failing assertion either through the symbol or through the texte.
+Depending upon the static assertion system used, a hint as to the failing assertion will appear in some form in the compiler diagnostic output.
 
 [endsect]
 
@@ -765,17 +729,18 @@
 
 A diagnostic will be emitted if __ratio__ is instantiated with `D == 0`, or if the absolute value of `N` or `D` can not be represented. [*Note:] These rules ensure that infinite ratios are avoided and that for any negative input, there exists a representable value of its absolute value which is positive. In a two's complement representation, this excludes the most negative value.
 
-Let `gcd` denote the greatest common divisor of `N`'s absolute value and of `D`'s absolute value.
+The members num and den will be normalized values of the template arguments N and D computed as follows.  Let `gcd` denote the greatest common divisor of `N`'s absolute value and of `D`'s absolute value. Then:
 
 * `num` has the value `sign(N)*sign(D)*abs(N)/gcd`.
 
 * `den` has the value `abs(D)/gcd`.
 
-The nested typedef `type` denotes the normalized form of this __ratio__ type. It should be used when the template parameters doesn't give a normalized form.
+The nested typedef `type` denotes the normalized form of this __ratio__ type. It should be 
+used when the normalized form of the template arguments are required, since the arguments are not necessarily normalized.
 
 Two __ratio__ classes `__ratio__<N1,D1>` and `__ratio__<N2,D2>` have the same normalized form if `__ratio__<N1,D1>::type` is the same type as `__ratio__<N2,D2>::type`
 
-[section:ca Construction and assignment]
+[section:ca Construction and Assignment]
 
     template <intmax_t N2, intmax_t D2>
       ratio(const __ratio__<N2, D2>& r);
@@ -799,9 +764,11 @@
 [endsect]
 
 
-[section:ratio_arithmetic `ratio` arithmetic]
+[section:ratio_arithmetic `ratio` Arithmetic]
+
+For each of the class templates in this section, each template parameter refers to a `ratio`. If the implementation is unable to form the indicated __ratio__ due to overflow, a diagnostic will be issued.
 
-For each of the class templates in this clause, each template parameter refers to a `ratio`. If the implementation is unable to form the indicated __ratio__ due to overflow, a diagnostic will be issued.
+[heading `ratio_add<>`]
 
         template <class R1, class R2> struct ratio_add {
            typedef [/see below] type;
@@ -809,18 +776,24 @@
 
 The nested typedef `type` is a synonym for `__ratio__<R1::num * R2::den + R2::num * R1::den, R1::den * R2::den>::type`.
 
+[heading `ratio_subtract<>`]
+
         template <class R1, class R2> struct ratio_subtract {
            typedef  [/see below]  type;
         };
 
 The nested typedef `type` is a synonym for `__ratio__<R1::num * R2::den - R2::num * R1::den, R1::den * R2::den>::type`.
 
+[heading `ratio_multiply<>`]
+
         template <class R1, class R2> struct ratio_multiply {
            typedef  [/see below]  type;
         };
 
 The nested typedef `type` is a synonym for `__ratio__<R1::num * R2::num, R1::den * R2::den>::type`.
 
+[heading `ratio_divide<>`]
+
         template <class R1, class R2> struct ratio_divide {
            typedef  [/see below]  type;
         };
@@ -829,28 +802,40 @@
 
 [endsect]
 
-[section:ratio_comparison `ratio` comparison]
+[section:ratio_comparison `ratio` Comparison]
+
+[heading `ratio_equal<>`]
 
         template <class R1, class R2>  struct ratio_equal
             : public boost::integral_constant<bool, [/see below] > {};
 
 If R1::num == R2::num && R1::den == R2::den, ratio_equal derives from true_type, else derives from false_type.
 
+[heading `ratio_not_equal<>`]
+
+    template <class R1, class R2>  struct ratio_not_equal
+        : public boost::integral_constant<bool, !ratio_equal<R1, R2>::value> {};
+
+[heading `ratio_less<>`]
+
         template <class R1, class R2>
         struct ratio_less
             : public boost::integral_constant<bool, [/see below] > {};
 
 If R1::num * R2::den < R2::num * R1::den, ratio_less derives from true_type, else derives from false_type.
 
-    template <class R1, class R2>  struct ratio_not_equal
-        : public boost::integral_constant<bool, !ratio_equal<R1, R2>::value> {};
+[heading `ratio_less_equal<>`]
 
     template <class R1, class R2> struct ratio_less_equal
         : public boost::integral_constant<bool, !ratio_less<R2, R1>::value> {};
 
+[heading `ratio_greater<>`]
+
     template <class R1, class R2> struct ratio_greater
         : public boost::integral_constant<bool, ratio_less<R2, R1>::value> {};
 
+[heading `ratio_greater_equal<>`]
+
     template <class R1, class R2> struct ratio_greater_equal
         : public boost::integral_constant<bool, !ratio_less<R1, R2>::value> {};
 
@@ -859,6 +844,8 @@
 
 [section:ratio_si_typedefs SI typedefs]
 
+The [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes International System of Units]  specifies twenty SI prefixes. __Boost_Ratio__ defines all except  `yocto`, `zepto`, `zetta`, and `yotta`
+
         // convenience SI typedefs
         typedef __ratio__<1LL, 1000000000000000000LL> atto;
         typedef __ratio__<1LL,    1000000000000000LL> femto;
@@ -882,23 +869,13 @@
 
 [section:limitations Limitations and Extensions]
 
-Next follows limitation respect to the C++0x recomendations:
-
-* Four of the typedefs in the recomendation which can be conditionally supported are not supported: `yocto`, `zepto`, `zetta` and `yotta`.
-
-    typedef __ratio__<1, 1000000000000000000000000> yocto;  // conditionally supported
-    typedef __ratio__<1,    1000000000000000000000> zepto;  // conditionally supported
-    typedef __ratio__<   1000000000000000000000, 1> zetta;  // conditionally supported
-    typedef __ratio__<1000000000000000000000000, 1> yotta;  // conditionally supported
-
-* [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3135.html#1121 Ratio values should be constexpr]: `constexpr` don't used as no compiler supports it today. `const` is used instead when appropiated.
-
-* [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3134.html#921 Rational Arithmetic should use template aliases]: In the absence of compiler support of template aliases the C++03 emulation define a nested typedef `type`.
-
-The current implementation provides in addition:
-
-* the [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3133.html#1281 copy constructor and assignement between ratios having the same normalized form].
-
+The following are limitations of Boost.Ratio relative to the specification in the C++0x draft standard:
+ 
+* Four of the SI units typedefs -- `yocto`, `zepto`, `zetta`, and `yotta` -- are to be conditionally supported, if the range of `intmax_t` allows, but are not supported by __Boost_Ratio__.
+* Ratio values should be of type static `constexpr intmax_t` (see [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3135.html#1121 Ratio values should be constexpr]), but no compiler supports `constexpr` today, so __Boost_Ratio__ uses `static const intmax_t` instead.
+* Rational arithmetic should use template aliases (see [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3134.html#921 Rational Arithmetic should use template aliases]), but those are not available in C++03, so inheritance is used instead.
+ 
+The current implementation extends the requirements of the C++0x draft standard by making the copy constructor and copy assignment operator have the same normalized form (see [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3133.html#1281 copy constructor and assignment between ratios having the same normalized form]).
 
 [endsect]
 
@@ -908,69 +885,19 @@
 [section:ratio_io_hpp Header `<boost/ratio_io.hpp>`]
 [/===========================================]
 
-It provides a textual representation of `boost::ratio<N, D>` in the form of a `std::basic_string`. Other types such as `boost::duration` can use these strings to aid in their I/O.
-
-This source has been adapted from the experimental header `<ratio_io>` from Howard Hinnant. Porting to Boost has been trivial. 
+This header provides `ratio_string<>` which can generate a textual representation of a `ratio<>` in the form of a `std::basic_string<>`.  These strings can be useful for I/O."
 
     namespace boost {
         
         template <class Ratio, class CharT>
         struct ratio_string
         {
-            static std::basic_string<CharT> short_name() {return long_name();}
+            static std::basic_string<CharT> short_name();
             static std::basic_string<CharT> long_name();
         };
 
     }
 
-For each `ratio<N, D>` there exists a `ratio_string<ratio<N, D>, CharT>` for which you can query two strings: `short_name` and `long_name`. For those `ratio`'s that correspond to an [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes SI prefix] long_name corresponds to the internationally recognized prefix, stored as a `basic_string<CharT>`. For example `ratio_string<mega, char>::long_name()` returns `string("mega")`. For those `ratio`'s that correspond to an [@http://en.wikipedia.org/wiki/SI_prefix#List_of_SI_prefixes SI prefix] `short_name` corresponds to the internationally recognized symbol, stored as a `basic_string<CharT>`. For example `ratio_string<mega, char>::short_name()` returns `string("M")`. For all other `ratio`'s, both `long_name()` and `short_name()` return a `basic_string` containing "[`ratio::num/ratio::den`]".
-
-`ratio_string<ratio<N, D>, CharT>` is only defined for four character types:
-
-* `char`
-* `char16_t`
-* `char32_t`
-* `wchar_t`
-
-When the character is char, UTF-8 will be used to encode the names. When the character is `char16_t`, UTF-16 will be used to encode the names. When the character is `char32_t`, UTF-32 will be used to encode the names. When the character is `wchar_t`, the encoding will be UTF-16 if `wchar_t` is 16 bits, and otherwise UTF-32.
-
-The `short_name` for micro is defined by [@http://www.unicode.org/charts/PDF/U0080.pdf Unicode] to be U+00B5. 
-
-[*Examples:]
-
-    #include <boost/ratio/ratio_io.hpp>
-    #include <iostream>
-
-    int main()
-    {
-        using namespace std;
-        using namespace boost;
-
-        cout << "ratio_string<deca, char>::long_name() = "
-             <<  ratio_string<deca, char>::long_name() << '\n';
-        cout << "ratio_string<deca, char>::short_name() = "
-             <<  ratio_string<deca, char>::short_name() << '\n';
-
-        cout << "ratio_string<giga, char>::long_name() = "
-             <<  ratio_string<giga, char>::long_name() << '\n';
-        cout << "ratio_string<giga, char>::short_name() = "
-             <<  ratio_string<giga, char>::short_name() << '\n';
-
-        cout << "ratio_string<ratio<4, 6>, char>::long_name() = "
-             <<  ratio_string<ratio<4, 6>, char>::long_name() << '\n';
-        cout << "ratio_string<ratio<4, 6>, char>::short_name() = "
-             <<  ratio_string<ratio<4, 6>, char>::short_name() << '\n';
-    }
-
-The output will be
-
-    ratio_string<deca, char>::long_name() = deca
-    ratio_string<deca, char>::short_name() = da
-    ratio_string<giga, char>::long_name() = giga
-    ratio_string<giga, char>::short_name() = G
-    ratio_string<ratio<4, 6>, char>::long_name() = [2/3]
-    ratio_string<ratio<4, 6>, char>::short_name() = [2/3]
-
 [endsect]
 [endsect]
 
@@ -982,6 +909,10 @@
 [section:history Appendix A: History]
 [/==================================]
 
+[section [*Version 1.0.0, ?? ??, 2010] ]
+[endsect]
+
+[/
 [section [*Version 0.2.1, September 27, 2010] ]
 
 [*Fixes:]
@@ -1014,7 +945,7 @@
 
 [endsect]
 
-
+]
 
 [endsect]
 
@@ -1034,12 +965,15 @@
 fails to compile in (1). Other example
 
     __ratio__<1,3> r1;
-    ratio_substract<__ratio__<2,3>,__ratio__<1,3> > r2=r1;  // (2)
+    ratio_subtract<__ratio__<2,3>,__ratio__<1,3> > r2=r1;  // (2)
 
-The type of ratio_substract<__ratio__<2,3>,__ratio__<1,3> > could be __ratio__<3,9> so the compilation could fail in (2). It could also be __ratio__<1,3> and the compilation succeeds.
+The type of ratio_subtract<__ratio__<2,3>,__ratio__<1,3> > could be __ratio__<3,9> so the compilation could fail in (2). It could also be __ratio__<1,3> and the compilation succeeds.
 
 [heading Why ratio needs the nested normalizer typedef type]
 
+The current resolution of issue LWG 1281 acknowledges the need for a nested type typedef, so Boost.Ratio is tracking the likely final version of std::ratio.
+
+[/
 In [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n3000.pdf [*N3000]] 20.4.2 and similar clauses
 
 ['3 The nested typedef type shall be a synonym for __ratio__<T1, T2> where T1 has the value R1::num * R2::den - R2::num * R1::den and T2 has the value R1::den * R2::den.]
@@ -1051,7 +985,7 @@
     __ratio__<1,3>::type r1;
     __ratio__<3,9>::type r2;
     r1 = r2; // compiles as both types are the same.
-
+]
 [endsect]
 
 [/======================================================]
@@ -1065,10 +999,9 @@
 
 * The `num` and `den` `ratio<>` fields are normalized.
 * Use the gcd of some of the possible products that can overflow, and simplify before doing the product.
-* Use some equivalences relations that avoid addition or substraction can overflow or underflow.
-
+* Use some equivalences relations that avoid addition or subtraction that can overflow or underflow.
 
-Next follows more detail:
+The following subsections cover each case in more detail.
 
 [*ratio_add]
 
@@ -1079,14 +1012,14 @@
 either n1*d2+n2*d1 or d1*d2 can overflow. 
 
       ( (n1 * d2)  + (n2 * d1) )
-    / (d1 * d2)   
+      --------------------------
+               (d1 * d2)   
 
 Dividing by gcd(d1,d2) on both num and den
 
-      ( (n1 * (d2/gcd(d1,d2)))  + 
-        (n2 * (d1/gcd(d1,d2))) 
-      )
-    / ((d1 * d2) / gcd(d1,d2))  
+      ( (n1 * (d2/gcd(d1,d2)))  + (n2 * (d1/gcd(d1,d2))) )
+      ----------------------------------------------------
+                     ((d1 * d2) / gcd(d1,d2))  
 
 
 Multipliying and diving by gcd(n1,n2) in numerator
@@ -1094,28 +1027,32 @@
       ( ((gcd(n1,n2)*(n1/gcd(n1,n2))) * (d2/gcd(d1,d2)))  + 
         ((gcd(n1,n2)*(n2/gcd(n1,n2))) * (d1/gcd(d1,d2))) 
       )
-    / ( (d1 * d2) / gcd(d1,d2) )
+      --------------------------------------------------
+               ( (d1 * d2) / gcd(d1,d2) )
 
 Factorizing gcd(n1,n2)
 
       ( gcd(n1,n2) * 
         ( ((n1/gcd(n1,n2)) * (d2/gcd(d1,d2))) + ((n2/gcd(n1,n2)) * (d1/gcd(d1,d2))) )
       )
-    / ( (d1 * d2) / gcd(d1,d2) )
+      -------------------------------------------------------------------------------
+                                  ( (d1 * d2) / gcd(d1,d2) )
 
 Regrouping
 
       ( gcd(n1,n2) * 
         ( ((n1/gcd(n1,n2)) * (d2/gcd(d1,d2))) + ((n2/gcd(n1,n2)) * (d1/gcd(d1,d2))) )
       )
-    / ( (d1 / gcd(d1,d2)) * d2 )
+      -------------------------------------------------------------------------------
+                                ( (d1 / gcd(d1,d2)) * d2 )
 
 Dividing by (d1 / gcd(d1,d2))
 
       ( ( gcd(n1,n2) / (d1 / gcd(d1,d2)) ) * 
         ( ((n1/gcd(n1,n2)) * (d2/gcd(d1,d2))) + ((n2/gcd(n1,n2)) * (d1/gcd(d1,d2))) )
       )
-    / d2
+      -------------------------------------------------------------------------------
+                                             d2
 
 
 Dividing by d2
@@ -1139,12 +1076,14 @@
 Dividing by gcc(n1,d2) numerator and denominator
 
         (((n1/gcc(n1,d2))*n2)
-    /   (d1*(d2/gcc(n1,d2))))
+        ---------------------
+        (d1*(d2/gcc(n1,d2))))
 
 Dividing by gcc(n2,d1)
 
         ((n1/gcc(n1,d2))*(n2/gcc(n2,d1)))
-    /   ((d1/gcc(n2,d1))*(d2/gcc(n1,d2)))
+        ---------------------------------
+        ((d1/gcc(n2,d1))*(d2/gcc(n1,d2)))
 
 And now all the initial numerator and denominators have been reduced, avoiding the overflow.
 
@@ -1252,10 +1191,13 @@
 
 Much thanks to Andrei Alexandrescu, Walter Brown, Peter Dimov, Jeff Garland, Terry Golubiewski, Daniel Krugler, Anthony Williams.
 
+The ratio.hpp source has been adapted from the experimental header `<ratio_io>` from Howard Hinnant.
+
 Thanks to Adrew Chinoff for his help polishing the documentation.
 
 [endsect]
 
+[/
 [/====================================================]
 [section:tests  Appendix F: Tests]
 
@@ -1296,11 +1238,11 @@
 [table
     [[Name]                 [kind]          [Description]                                           [Result] [Ticket]]
     [[ratio_add.pass]       [run]           [check ratio_add metafunction class]                    [Pass]   [#]]
-    [[ratio_substract.pass] [run]           [check ratio_substract metafunction  class]             [Pass]   [#]]
+    [[ratio_subtract.pass] [run]           [check ratio_subtract metafunction  class]             [Pass]   [#]]
     [[ratio_multiply.pass]  [run]           [check ratio_multiply metafunction class]               [Pass]   [#]]
     [[ratio_divide.pass]    [run]           [check ratio_divide metafunction class]                 [Pass]   [#]]
     [[ratio_add.fail]       [compile-fails] [check ratio_add overflow metafunction class]           [Pass]   [#]]
-    [[ratio_substract.fail] [compile-fails] [check ratio_substract underflow metafunction  class]   [Pass]   [#]]
+    [[ratio_subtract.fail] [compile-fails] [check ratio_subtract underflow metafunction  class]   [Pass]   [#]]
     [[ratio_multiply.fail]  [compile-fails] [check ratio_multiply overflow metafunction class]      [Pass]   [#]]
     [[ratio_divide.fail]    [compile-fails] [check ratio_divide overflow metafunction class]        [Pass]   [#]]
 ]
@@ -1324,14 +1266,16 @@
 
 [endsect]
 
-[
+]
 [/=====================================]
-[section:todo  Appendix H: Future plans]
+[section:todo  Appendix F: Future Plans]
 [/=====================================]
 
 [heading For later releases]
 
-Implement [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3135.html#3135 multiple arguments] ratio arithmetic.
+* Use constexpr on compiler providing it
+* Use template aliases on compiler providing it
+* Implement [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2010/n3135.html#3135 multiple arguments] ratio arithmetic.
 
 [endsect]