[Boost-commit] svn:boost r39069 - sandbox/math_toolkit/libs/math/doc

From: john_at_[hidden]
Date: 2007-08-30 08:44:28

Author: johnmaddock
Date: 2007-08-30 08:44:26 EDT (Thu, 30 Aug 2007)
New Revision: 39069
URL: http://svn.boost.org/trac/boost/changeset/39069

Log:
More tidying up of the introduction.
Text files modified: 
   sandbox/math_toolkit/libs/math/doc/common_overviews.qbk |    12 +++++-                                  
   sandbox/math_toolkit/libs/math/doc/math.qbk             |    65 +++++++++++++++++++++++++-------------- 
   sandbox/math_toolkit/libs/math/doc/minimax.qbk          |     6 ++-                                     
   sandbox/math_toolkit/libs/math/doc/result_type_calc.qbk |    17 +++++++++-                              
   sandbox/math_toolkit/libs/math/doc/structure.qbk        |    12 ++++--                                  
   5 files changed, 77 insertions(+), 35 deletions(-)

Modified: sandbox/math_toolkit/libs/math/doc/common_overviews.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/common_overviews.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/common_overviews.qbk	2007-08-30 08:44:26 EDT (Thu, 30 Aug 2007)
@@ -36,11 +36,17 @@
   
 You can control policies:
 
-* Using [link math_toolkit.policy.pol_ref.policy_defaults macros] to change any default policy.
-* At your chosen [link math_toolkit.policy.pol_ref.namespace_pol namespace scope] for distributions and/or functions.
+* Using [link math_toolkit.policy.pol_ref.policy_defaults macros] to 
+change any default policy: the is the prefered method for installation
+wide policies.
+* At your chosen [link math_toolkit.policy.pol_ref.namespace_pol 
+namespace scope] for distributions and/or functions: this is the 
+prefered method for project, namespace, or translation unit scope
+policies.
 * In an ad-hoc manner [link math_toolkit.policy.pol_tutorial.ad_hoc_sf_policies 
 by passing a specific policy to a special function], or to a 
-[link math_toolkit.policy.pol_tutorial.ad_hoc_dist_policies statistical distribution].
+[link math_toolkit.policy.pol_tutorial.ad_hoc_dist_policies 
+statistical distribution].
 
 ]
 

Modified: sandbox/math_toolkit/libs/math/doc/math.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/math.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/math.qbk	2007-08-30 08:44:26 EDT (Thu, 30 Aug 2007)
@@ -56,8 +56,8 @@
 [def __evaluation_error [link evaluation_error evaluation_error]]
 [def __checked_narrowing_cast [link checked_narrowing_cast checked_narrowing_cast]]
 
-[def __arg_pomotion_rules [link math_toolkit.special.result_type ['result type calculation rules]]]
-[def __sf_result [link math_toolkit.special.result_type ['calculated-result-type]]]
+[def __arg_pomotion_rules [link math_toolkit.main_overview.result_type ['result type calculation rules]]]
+[def __sf_result [link math_toolkit.main_overview.result_type ['calculated-result-type]]]
 
 [/ The following macros expand to links to the various special functions
 and use the function's name as the link text]
@@ -263,26 +263,29 @@
 [h4 Statistical Distributions]
 
 Provide a reasonably comprehensive set of
-[@http://en.wikipedia.org/wiki/List_of_probability_distributions statistical distributions],
+[link math_toolkit.dist statistical distributions],
 upon which higher level statistical tests can be built.
 
 The initial focus is on the central
 [@http://en.wikipedia.org/wiki/Univariate univariate ]
 [@http://mathworld.wolfram.com/StatisticalDistribution.html distributions].
 Both [@http://mathworld.wolfram.com/ContinuousDistribution.html continuous]
-(like [@http://mathworld.wolfram.com/NormalDistribution.html normal]
-& [@http://mathworld.wolfram.com/F-Distribution.html Fisher])
+(like [link math_toolkit.dist.dist_ref.dists.normal_dist normal]
+& [link math_toolkit.dist.dist_ref.dists.f_dist Fisher])
 and [@http://mathworld.wolfram.com/DiscreteDistribution.html discrete]
-(like [@http://mathworld.wolfram.com/BinomialDistribution.html binomial]
-& [@http://mathworld.wolfram.com/PoissonDistribution.html Poisson]) distributions are provided.
-
-A tutorial is provided, along with a series of worked examples illustrating
+(like [link math_toolkit.dist.dist_ref.dists.binomial_dist binomial]
+& [link math_toolkit.dist.dist_ref.dists.poisson_dist Poisson]) 
+distributions are provided.
+
+A [link math_toolkit.dist.stat_tut comprehensive tutorial is provided], 
+along with a series of 
+[link math_toolkit.dist.stat_tut.weg worked examples] illustrating
 how the library is used to conduct statistical tests.
 
 [h4 Mathematical Special Functions]
 
 Provides a small number of high quality 
-[@http://en.wikipedia.org/wiki/Special_functions special functions],
+[link math_toolkit.special special functions],
 initially these were concentrated on functions used in statistical applications
 along with those in the [tr1].
 
@@ -303,29 +306,45 @@
 
 [h4 Implementation Toolkit]
 
-Provides many of the tools required to implement 
+Provides [link math_toolkit.toolkit many of the tools] required to implement 
 mathematical special functions: hopefully the presence of 
 these will encourage other authors to contribute more special
-function implementations in the future.  
-
-There are helpers for the evaluation of infinite series, continued
-fractions and rational approximations.  
+function implementations in the future.  These tools are currently
+considered experimental: they are "exposed implementation details"
+whose interfaces and\/or implementations may change.
+
+There are helpers for the 
+[link math_toolkit.toolkit.internals1.series_evaluation 
+evaluation of infinite series], 
+[link math_toolkit.toolkit.internals1.cf continued
+fractions] and [link math_toolkit.toolkit.internals1.rational
+rational approximations].
+
+There is a fairly comprehensive set of root finding and 
+[link math_toolkit.toolkit.internals1.minima function minimisation 
+algorithms]: the root finding algorithms are both 
+[link math_toolkit.toolkit.internals1.roots with] and 
+[link math_toolkit.toolkit.internals1.roots2 without] derivative support.
 
-There is a fairly comprehensive set of root finding and function minimisation 
-algorithms: both with and without derivative support.
-
-A Remez algorithm implementation allows for the locating of minimax rational
+A [link math_toolkit.toolkit.internals2.minimax 
+Remez algorithm implementation] allows for the locating of minimax rational
 approximations.
 
-There are also (experimental) classes for the manipulation of polynomials, for 
-testing a special function against tabulated test data, and for 
-the rapid generation of test data and/or data for output to an 
+There are also (experimental) classes for the 
+[link math_toolkit.toolkit.internals2.polynomials manipulation of polynomials], for 
+[link math_toolkit.toolkit.internals2.error_test 
+testing a special function against tabulated test data], and for 
+the [link math_toolkit.toolkit.internals2.test_data
+rapid generation of test data] and/or data for output to an 
 external graphing application.
 
 [endsect] [/section:intro Introduction]
 
 [include structure.qbk] [/getting about]
 
+[include result_type_calc.qbk]
+[include error_handling.qbk]
+
 [section:pol_overview Configuration and Policies]
 [policy_overview]
 [endsect][/section:pol_overview Configuration and Policies]
@@ -392,8 +411,6 @@
 [include sinc.qbk]
 [include inv_hyper.qbk]
 [include fpclassify.qbk]
-[include error_handling.qbk]
-[include result_type_calc.qbk]
 [endsect] [/section:special Special Functions]
 
 [section:toolkit Internal Details and Tools (Experimental)]

Modified: sandbox/math_toolkit/libs/math/doc/minimax.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/minimax.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/minimax.qbk	2007-08-30 08:44:26 EDT (Thu, 30 Aug 2007)
@@ -12,8 +12,10 @@
 To use this tool, you will need to have a reasonable grasp of what the Remez
 algorithm is, and the general form of the approximation you want to achieve.
 
-There is a background article explaining the principals behind the Remez
-algorithm [link math_toolkit.backgrounders.remez here].
+Unless you already familar with the Remez method
+you should first read the [link math_toolkit.backgrounders.remez 
+brief background article explaining the principals behind the 
+Remez algorithm].
 
 The program consists of two parts:
 

Modified: sandbox/math_toolkit/libs/math/doc/result_type_calc.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/result_type_calc.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/result_type_calc.qbk	2007-08-30 08:44:26 EDT (Thu, 30 Aug 2007)
@@ -1,11 +1,24 @@
 
 [section:result_type Calculation of the Type of the Result]
 
+The functions in this library are all overloaded to accept
+mixed floating point (or mixed integer and floating point type)
+arguments.  So for example:
+
+   foo(1.0, 2.0);
+   foo(1.0f, 2);
+   foo(1.0, 2L);
+
+etc, are all valid calls, as long as "foo" is a function taking two 
+floating-point arguments.  But that leaves the question:
+
 [blurb ['"Given a special function with N arguments of
 types T1, T2, T3 ... TN, then what type is the result?"]]
 
-If all the arguments are of the same (floating point) type then the 
-result is the same type as the arguments, otherwise, the type of the result
+[*If all the arguments are of the same (floating point) type then the 
+result is the same type as the arguments.]
+
+Otherwise, the type of the result
 is computed using the following logic:
 
 # Any arguments that are not template arguments are disregarded from 

Modified: sandbox/math_toolkit/libs/math/doc/structure.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/structure.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/structure.qbk	2007-08-30 08:44:26 EDT (Thu, 30 Aug 2007)
@@ -16,7 +16,7 @@
 
 [endsect]
 
-[section:directories Directory File Structure for Boost Math Functions, Math Constants, & Statistics Distributions]
+[section:directories Directory and File Structure]
 
 [h4 boost\/math]
 
@@ -37,7 +37,7 @@
    [Distributions used in mathematics and, especially, statistics: 
    Gaussian, Students-t, Fisher, Binomial etc]]
 
-[[\/policy\/]
+[[\/policies\/]
    [Policy framework, for handling user requested behaviour modifications.]]
                      
 [[\/special_functions\/]
@@ -78,7 +78,7 @@
 
 [endsect]
    
-[section:namespaces Namespaces for Boost Math Functions, Math Constants and Statistics Distributions]
+[section:namespaces Namespaces]
    
 All math functions and distributions are in `namespace boost::math`
    
@@ -94,7 +94,11 @@
    
 Functions not intended for use by applications are in `boost::math::detail`.
 
-Functions that may have more general use, like `digits` (significand), `max_value`, `min_value` and `epsilon` are in `boost::math::tools`.
+Functions that may have more general use, like `digits` 
+(significand), `max_value`, `min_value` and `epsilon` are in 
+`boost::math::tools`.
+
+__Policy and configuration information is in namespace `boost::math::policies`.
 
 [endsect]