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

Subject: [Boost-commit] svn:boost r50073 - sandbox/math_toolkit/libs/math/doc/sf_and_dist
From: pbristow_at_[hidden]
Date: 2008-12-02 10:30:58

Author: pbristow
Date: 2008-12-02 10:30:57 EST (Tue, 02 Dec 2008)
New Revision: 50073
URL: http://svn.boost.org/trac/boost/changeset/50073

Log:
Typo corrected
Text files modified: 
   sandbox/math_toolkit/libs/math/doc/sf_and_dist/implementation.qbk |   156 +++++++++++++++++++++------------------ 
   1 files changed, 82 insertions(+), 74 deletions(-)

Modified: sandbox/math_toolkit/libs/math/doc/sf_and_dist/implementation.qbk
==============================================================================
--- sandbox/math_toolkit/libs/math/doc/sf_and_dist/implementation.qbk	(original)
+++ sandbox/math_toolkit/libs/math/doc/sf_and_dist/implementation.qbk	2008-12-02 10:30:57 EST (Tue, 02 Dec 2008)
@@ -72,12 +72,12 @@
 `static_cast<RealType>(1) / 3;`
 
 If a function is very sensitive to changes in input,
-specifying an inexact value as input (such as 0.1) can throw 
+specifying an inexact value as input (such as 0.1) can throw
 the result off by a noticeable amount: 0.1f is "wrong"
-by ~1e-7 for example (because 0.1 has no exact binary representation). 
+by ~1e-7 for example (because 0.1 has no exact binary representation).
 That is why exact binary values - halves, quarters, and eighths etc -
-are used in test code along with the occasional fraction `a/b` with `b` 
-a power of two (in order to ensure that the result is an exactly 
+are used in test code along with the occasional fraction `a/b` with `b`
+a power of two (in order to ensure that the result is an exactly
 representable binary value).
 
 [h4 Tolerance of Tests]
@@ -87,7 +87,7 @@
 * Some epsilon value.
 * The accuracy of the data (often only near 64-bit double).
 
-Otherwise when long double has more digits than the test data, then no 
+Otherwise when long double has more digits than the test data, then no
 amount of tweaking an epsilon based tolerance will work.
 
 A common problem is when tolerances that are suitable for implementations
@@ -127,13 +127,13 @@
 [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf Draft Technical Report on C++ Library Extensions, 2005-06-24, section 5.2.1, paragraph 5].
 [link math_toolkit.main_overview.error_handling See also domain_error].
 
-See __policy_ref for details of the error handling policies that should allow 
+See __policy_ref for details of the error handling policies that should allow
 a user to comply with any of these recommendations, as well as other behaviour.
 
 See [link math_toolkit.main_overview.error_handling error handling]
 for a detailed explanation of the mechanism, and
 [link math_toolkit.dist.stat_tut.weg.error_eg error_handling example]
-and 
+and
 [@../../../example/error_handling_example.cpp error_handling_example.cpp]
 
 [caution If you enable throw but do NOT have try & catch block,
@@ -146,14 +146,14 @@
 
 Functions that are not mathematically defined,
 like the Cauchy mean, fail to compile by default.
-[link math_toolkit.policy.pol_ref.assert_undefined A policy] 
+[link math_toolkit.policy.pol_ref.assert_undefined A policy]
 allows control of this.
 
 If the policy is to permit undefined functions, then calling them
 throws a domain error, by default.  But the error policy can be set
-to not throw, and to return NaN instead.  For example, 
+to not throw, and to return NaN instead.  For example,
 
-`#define BOOST_MATH_DOMAIN_ERROR_POLICY ignore_error` 
+`#define BOOST_MATH_DOMAIN_ERROR_POLICY ignore_error`
 
 appears before the first Boost include,
 then if the un-implemented function is called,
@@ -161,7 +161,7 @@
 
 [warning If `std::numeric_limits<T>::has_quiet_NaN` is false
 (for example T is a User-defined type),
-then an exception will always be thrown when a domain error occurs. 
+then an exception will always be thrown when a domain error occurs.
 Catching exceptions is therefore strongly recommended.]
 
 [h4 Median of distributions]
@@ -186,19 +186,19 @@
 
 [h4 Handling of Floating-Point Infinity]
 
-Some functions and distributions are well defined with + or - infinity as 
-argument(s), but after some experiments with handling infinite arguments 
+Some functions and distributions are well defined with + or - infinity as
+argument(s), but after some experiments with handling infinite arguments
 as special cases, we concluded that it was generally more useful to forbid this,
-and instead to return the result of __domain_error.  
+and instead to return the result of __domain_error.
 
-Handling infinity as special cases is additionally complicated 
-because, unlike built-in types on most - but not all - platforms, 
-not all User-Defined Types are 
+Handling infinity as special cases is additionally complicated
+because, unlike built-in types on most - but not all - platforms,
+not all User-Defined Types are
 specialized to provide `std::numeric_limits<RealType>::infinity()`
 and would return zero rather than any representation of infinity.
 
-The rationale is that non-finiteness may happen because of error 
-or overflow in the users code, and it will be more helpful for this 
+The rationale is that non-finiteness may happen because of error
+or overflow in the users code, and it will be more helpful for this
 to be diagnosed promptly rather than just continuing.
 The code also became much more complicated, more error-prone,
 much more work to test, and much less readable.
@@ -207,7 +207,7 @@
 we have permitted argument(s) to be infinity,
 provided infinity is implemented for the realType on that implementation.
 
-Users who require special handling of infinity (or other specific value) can, 
+Users who require special handling of infinity (or other specific value) can,
 of course, always intercept this before calling a distribution or function
 and return their own choice of value, or other behavior.
 This will often be simpler than trying to handle the aftermath of the error policy.
@@ -235,7 +235,7 @@
     }
     return (upper - lower);
   }
-  
+
 but found that these concepts are not defined (or their definition too contentious)
 for too many distributions to be generally applicable.
 Because they are non-member functions, they can be added if required.
@@ -253,7 +253,7 @@
 
 Some of the special functions in this library are implemented via
 rational approximations.  These are either taken from the literature,
-or devised by John Maddock using 
+or devised by John Maddock using
 [link math_toolkit.toolkit.internals2.minimax our Remez code].
 
 Rational rather than Polynomial approximations are used to ensure
@@ -266,24 +266,24 @@
 literature methods were unavailable or under non-BSL
 compatible license.  Our Remez code is known to produce good
 agreement with literature results in fairly simple "toy" cases.
-All approximations were checked 
+All approximations were checked
 for convergence and to ensure that
-they were not ill-conditioned (the coefficients can give a 
-theoretically good solution, but the resulting rational function 
-may be un-computable at fixed precision).  
+they were not ill-conditioned (the coefficients can give a
+theoretically good solution, but the resulting rational function
+may be un-computable at fixed precision).
 
 Recomputing using different
 Remez implementations may well produce differing coefficients: the
 problem is well known to be ill conditioned in general, and our Remez implementation
 often found a broad and ill-defined minima for many of these approximations
-(of course for simple "toy" examples like approximating `exp` the minima 
+(of course for simple "toy" examples like approximating `exp` the minima
 is well defined, and the coeffiecents should agree no matter whose Remez
 implementation is used).  This should not in general effect the validity
-of the approximations: there's good literature supporting the idea that 
-coefficients can be "in error" without necessarily adversely effecting 
+of the approximations: there's good literature supporting the idea that
+coefficients can be "in error" without necessarily adversely effecting
 the result.  Note that "in error" has a special meaning in this context,
-see [@http://front.math.ucdavis.edu/0101.5042 
-"Approximate construction of rational approximations and the effect 
+see [@http://front.math.ucdavis.edu/0101.5042
+"Approximate construction of rational approximations and the effect
 of error autocorrection.", Grigori Litvinov, eprint arXiv:math/0101042].
 Therefore the coefficients still need to be accurately calculated, even if they can
 be in error compared to the "true" minimax solution.
@@ -294,8 +294,8 @@
 to provide high accuracy constants to mathematical functions and distributions,
 since it is important to provide values uniformly for both built-in
 float, double and long double types,
-and for User Defined types like NTL::quad_float and NTL::RR.  
-                                        
+and for User Defined types like NTL::quad_float and NTL::RR.
+
 To permit calculations in this Math ToolKit and its tests, (and elsewhere)
 at about 100 decimal digits with NTL::RR type,
 it is obviously necessary to define constants to this accuracy.
@@ -316,7 +316,7 @@
   BOOST_DEFINE_MATH_CONSTANT(pi,
     3.141592653589793238462643383279502884197169399375105820974944,
     5923078164062862089986280348253421170679821480865132823066470938446095505,
-    0)                                              
+    0)
 
 And used thus:
 
@@ -324,19 +324,19 @@
 
   double diameter = 1.;
   double radius = diameter * pi<double>();
-  
+
   or boost::math::constants::pi<NTL::RR>()
 
 Note that it is necessary (if inconvenient) to specify the type explicitly.
 
 So you cannot write
 
-  double p = boost::math::constants::pi<>();  // could not deduce template argument for 'T'  
+  double p = boost::math::constants::pi<>();  // could not deduce template argument for 'T'
 
 Neither can you write:
 
-  double p = boost::math::constants::pi; // Context does not allow for disambiguation of overloaded function     
-  double p = boost::math::constants::pi(); // Context does not allow for disambiguation of overloaded function     
+  double p = boost::math::constants::pi; // Context does not allow for disambiguation of overloaded function
+  double p = boost::math::constants::pi(); // Context does not allow for disambiguation of overloaded function
 
 [h4 Thread safety]
 
@@ -344,16 +344,16 @@
 (otherwise none of the std lib math functions would be thread safe?).
 If you turn on reporting of errors via exceptions, errno gets left unused anyway.
 
-Other than that, the code is intended to be thread safe *for built in 
+Other than that, the code is intended to be thread safe *for built in
 real-number types* : so float, double and long double are all thread safe.
 
-For non-built-in types - NTL::RR for example - initialisation of the various 
-constants used in the implementation is potentially *not* thread safe.  
+For non-built-in types - NTL::RR for example - initialisation of the various
+constants used in the implementation is potentially *not* thread safe.
 This most undesiable, but it would be a signficant challenge to fix it.
-Some compilers may offer the option of having 
-static-constants initialised in a thread safe manner (Commeau, and maybe 
-others?), if that's the case then the problem is solved.  This is a topic of 
-hot debate for the next C++ std revision, so hopefully all compilers 
+Some compilers may offer the option of having
+static-constants initialised in a thread safe manner (Commeau, and maybe
+others?), if that's the case then the problem is solved.  This is a topic of
+hot debate for the next C++ std revision, so hopefully all compilers
 will be required to do the right thing here at some point.
 
 [h4 Sources of Test Data]
@@ -386,32 +386,32 @@
 & critical values for 5 tail values.
 
 It is also the only independent source found for the Weibull distribution;
-unfortunately it appears to suffer from very poor accuracy in areas where 
+unfortunately it appears to suffer from very poor accuracy in areas where
 the underlying special function is known to be difficult to implement.
 
 [h4 Creating and Managing the Equations]
 
-The primary source for the equations is now 
-[@http://www.w3.org/Math/ MathML]: see the 
+The primary source for the equations is now
+[@http://www.w3.org/Math/ MathML]: see the
 *.mml files in libs\/math\/doc\/sf_and_dist\/equations\/.
 
-These are most easily edited by a GUI editor such as 
+These are most easily edited by a GUI editor such as
 [@http://mathcast.sourceforge.net/home.html Mathcast],
 please note that the equation editor supplied with Open Office
 currently mangles these files and should not currently be used.
 
-Convertion to SVG was achieved using 
+Convertion to SVG was achieved using
 [@http://www.grigoriev.ru/svgmath/ SVGMath] and a command line
 such as:
 
-[pre 
-$for file in *.mml; do 
+[pre
+$for file in *.mml; do
 >/cygdrive/c/Python25/python.exe 'C:\download\open\SVGMath-0.3.1\math2svg.py' \\
 >>$file > $(basename $file .mml).svg
 >done
 ]
 
-Note that SVGMath requires that the mml files are *not* wrapped in an XHTML 
+Note that SVGMath requires that the mml files are *not* wrapped in an XHTML
 XML wrapper - this is added by Mathcast by default - one workaround is to
 copy an existing mml file and then edit it with Mathcast: the existing
 format should then be preserved.  This is a bug in the XML parser used by
@@ -444,7 +444,7 @@
 Also note that the SVG files in the repository are almost certainly
 Windows-specific since they reference various Windows Fonts.
 
-PNG files can be created from the SVG's using 
+PNG files can be created from the SVG's using
 [@http://xmlgraphics.apache.org/batik/tools/rasterizer.html Batik]
 and a command such as:
 
@@ -452,8 +452,8 @@
 
 Or using Inkscape and a command such as:
 
-[pre for file in *.svg; do 
-  /cygdrive/c/progra~1/Inkscape/inkscape -d 120 -e $(cygpath -a -w $(basename $file .svg).png) $(cygpath -a -w $file); 
+[pre for file in *.svg; do
+  /cygdrive/c/progra~1/Inkscape/inkscape -d 120 -e $(cygpath -a -w $(basename $file .svg).png) $(cygpath -a -w $file);
 done]
 
 Currently Inkscape seems to generate the better looking png's.
@@ -462,19 +462,25 @@
 using a command from a shell or command window with current directory
 \math_toolkit\libs\math\doc\sf_and_dist, typically:
 
-[pre bjam -a pdf]
+[pre bjam -a pdf >math_pdf.log]
 
-Note that XEP will have to be configured to *use and embed* 
+Note that XEP will have to be configured to *use and embed*
 whatever fonts are used by the SVG equations
-(if necessary editing the sample xep.xml provided by the XEP installation). 
+(almost certainly editing the sample xep.xml provided by the XEP installation).
+If you fail to do this you will get XEP warnings in the log file like
 
-(html is generated at math_toolkit\libs\math\doc\sf_and_dist\html\index.html
-using just bjam -a).
+[pre \[warning\]could not find any font family matching "Times New Roman"; replaced by Helvetica]
 
-JM's XEP config file has the following font configuration section added:
+(html is the default so it is generated at math_toolkit\libs\math\doc\sf_and_dist\html\index.html
+using command line >bjam -a > math_docs.log).
+
+ <!-- Sample configuration for Windows TrueType fonts.  -->
+is provided in the xep.xml downloaded, but the Windows TrueType fonts are commented out.
+
+JM's XEP config file \xep\xep.xml has the following font configuration section added:
 
 [pre
-    <font\-group xml:base\="file:\/C:\/Windows\/Fonts\/" label\="Windows TrueType" embed\="true" subset\="true"> 
+    <font\-group xml:base\="file:\/C:\/Windows\/Fonts\/" label\="Windows TrueType" embed\="true" subset\="true">
       <font\-family name\="Arial">
         <font><font\-data ttf\="arial.ttf"\/><\/font>
         <font style\="oblique"><font\-data ttf\="ariali.ttf"\/><\/font>
@@ -514,18 +520,20 @@
         <font weight\="bold"><font\-data ttf\="palab.ttf"\/><\/font>
         <font weight\="bold" style\="italic"><font\-data ttf\="palabi.ttf"\/><\/font>
       <\/font\-family>
-      
-    <font\-family name\="Lucida Sans Unicode">
-         <font><font\-data ttf\="lsansuni.ttf"\/><\/font>
-    <\/font\-family>
+
+    <font-family name="Lucida Sans Unicode">
+         <!-- <font><font-data ttf="lsansuni.ttf"></font> -->
+         <!-- actually called l_10646.ttf on Windows 2000 and Vista Sp1 -->
+         <font><font-data ttf="l_10646.ttf"/></font>
+    </font-family>
 ]
 
 PAB had to alter his because the Lucida Sans Unicode font had a different name.
-Changes are very likely to be required if you are not using Windows.
+Other changes are very likely to be required if you are not using Windows.
 
 XZ authored his equations using the venerable Latex, JM converted these to
 MathML using [@http://gentoo-wiki.com/HOWTO_Convert_LaTeX_to_HTML_with_MathML mxlatex].
-This process is currently unreliable and required some manual intervention: 
+This process is currently unreliable and required some manual intervention:
 consequently Latex source is not considered a viable route for the automatic
 production of SVG versions of equations.
 
@@ -543,24 +551,24 @@
 </inlinemediaobject>
 ]
 
-MathML is not currently present in the Docbook output, or in the 
+MathML is not currently present in the Docbook output, or in the
 generated HTML: this needs further investigation.
 
 [h4 Producing Graphs]
 
 Graphs were produced in SVG format and then converted to PNG's using the same
-process as the equations.  
+process as the equations.
 
-The programs 
+The programs
 /libs/math/doc/sf_and_dist/graphs/dist_graphs.cpp
 and /libs/math/doc/sf_and_dist/graphs/sf_graphs.cpp
-generate the SVG's directly using the 
+generate the SVG's directly using the
 [@http://code.google.com/soc/2007/boost/about.html Google Summer of Code 2007]
 project of Jacob Voytko (whose work so far is at .\boost-sandbox\SOC\2007\visualization).
 
 [endsect] [/section:implementation Implementation Notes]
 
-[/ 
+[/
   Copyright 2006, 2007 John Maddock and Paul A. Bristow.
   Distributed under the Boost Software License, Version 1.0.
   (See accompanying file LICENSE_1_0.txt or copy at