|
- Home | -Libraries | -People | -FAQ | -More | -
+
Portability Hints: Borland C++ 5.5.1
++
+
|
-
|
- Home | -Libraries | -People | -FAQ | -More | -
+
+
+
It is a general aim for boost libraries to be portable. The primary means for achieving + this goal is to adhere to ISO Standard C++. However, ISO C++ is a broad and + complex standard and most compilers are not fully conformant to ISO C++ + yet. In order to achieve portability in the light of this restriction, it + seems advisable to get acquainted with those language features that some + compilers do not fully implement yet.
-This page gives portability hints on some language features of the + Borland C++ version 5.5.1 compiler. Furthermore, the appendix presents + additional problems with Borland C++ version 5.5. Borland C++ 5.5.1 is a + freely available command-line compiler for Win32 available at http://www.borland.com/.
-The preprocessor symbol__BORLANDC__ is defined for all
-Borland C++ compilers. Its value is the version number of the
-compiler interpreted as a hexadecimal number. The following table
-lists some known values.
-+
Each entry in the following list describes a particular issue, complete + with sample source code to demonstrate the effect. Most sample code herein + has been verified to compile with gcc 2.95.2 and Comeau C++ 4.2.44.
-| Compiler | -__BORLANDC__ value |
-
|---|---|
| Borland C++ Builder 4 | -0x0540 | -
| Borland C++ Builder 5 | -0x0550 | -
| Compiler | -|
|---|---|
| Borland C++ 5.5 | -0x0550 | -__BORLANDC__ value |
+
-
| Borland C++ 5.5.1 | -0x0551 | -
| Borland C++ Builder 4 | -|
| Borland C++ Builder 6 | -0x0560 | -0x0540 | + -
using-declarations and
-using-directivesusing-directives (which refer to whole namespaces)
-and namespace-level using-declarations (which refer to
-individual identifiers within foreign namespaces) causes ambiguities
-where there are none. The following code fragment illustrates this:
+ ++ + +Borland C++ 5.5.1 + +0x0551 ++ +Borland C++ Builder 6 + +0x0560 +
using-declarations and
+ using-directivesMixing using-directives (which refer to whole namespaces)
+ and namespace-level using-declarations (which refer to
+ individual identifiers within foreign namespaces) causes ambiguities where
+ there are none. The following code fragment illustrates this:
namespace N {
int x();
}
@@ -111,15 +119,13 @@ int main()
}
+ using-declarations for class
+ templatesusing-declarations for class
-templatesusing-declarations as any other identifier. However, the
-following code fails to compile with Borland C++:
-
-+Identifiers for class templates can be used as arguments to +
+using-declarations as any other identifier. However, the + following code fails to compile with Borland C++:template<class T> class X { }; @@ -130,14 +136,12 @@ namespace N };+[template const arg] Deduction of constant arguments to function + templates
-[template const arg] Deduction of constant arguments to function -templates
- -Template function type deduction should omit top-level constness. -However, this code fragment instantiates "f<const int>(int)": - -+Template function type deduction should omit top-level constness. + However, this code fragment instantiates "f<const int>(int)":
+template<class T> void f(T x) { @@ -155,16 +159,11 @@ int main() }-The boost/rational.hpp header exhibits this problem in connection with -the gcd() function. +[function address] Resolving addresses of overloaded functions
- -[function address] Resolving addresses of overloaded -functions
- -Addresses of overloaded functions are not in all contexts properly -resolved (std:13.4 [over.over]); here is a small example: -+Addresses of overloaded functions are not in all contexts properly + resolved (std:13.4 [over.over]); here is a small example:
+template<class Arg> void f( void(*g)(Arg) ); @@ -191,17 +190,16 @@ int main() }-Workaround: Always use C-style casts when determining -addresses of (potentially) overloaded functions. +Workaround: Always use C-style casts when determining + addresses of (potentially) overloaded functions.
-[string conversion] Converting
+const char *to -std::string[string conversion] Converting
-Implicitly convertingconst char *to +std::stringconst char *parameters to -std::stringarguments fails if template functions are -explicitly instantiated (it works in the usual cases, though): - -+Implicitly converting
+const char *parameters to +std::stringarguments fails if template functions are + explicitly instantiated (it works in the usual cases, though):#include <string> template<class T> @@ -215,22 +213,19 @@ int main()-Workaround: Avoid explicit template function -instantiations (they have significant problems with Microsoft Visual -C++) and pass default-constructed unused dummy arguments with the -appropriate type. Alternatively, if you wish to keep to the explicit -instantiation, you could use an explicit conversion to -std::stringor declare the template function as taking a -const char *parameter. +Workaround: Avoid explicit template function + instantiations (they have significant problems with Microsoft Visual C++) + and pass default-constructed unused dummy arguments with the appropriate + type. Alternatively, if you wish to keep to the explicit instantiation, you + could use an explicit conversion to
+std::stringor declare the + template function as taking aconst char *parameter.[template value defaults] Dependent default arguments for template + value parameters
-[template value defaults] Dependent default arguments for template -value parameters
- -Template value parameters which default to an expression dependent on -previous template parameters don't work: - -+Template value parameters which default to an expression dependent on + previous template parameters don't work:
+template<class T> struct A { @@ -248,33 +243,29 @@ int main()+Workaround: If the relevant non-type template parameter + is an implementation detail, use inheritance and a fully qualified + identifier (for example, ::N::A<T>::value).
-Workaround: If the relevant non-type template -parameter is an implementation detail, use inheritance and a fully -qualified identifier (for example, ::N::A<T>::value). +[function partial ordering] Partial ordering of function templates
- -[function partial ordering] Partial ordering of function -templates
- -Partial ordering of function templates, as described in std:14.5.5.2 -[temp.func.order], does not work: - -+Partial ordering of function templates, as described in std:14.5.5.2 + [temp.func.order], does not work:
+#include <iostream> template<class T> struct A {}; template<class T1> -void f(const A<T1> &) +void f(const A<T1> &) { - std::cout << "f(const A<T1>&)\n"; + std::cout << "f(const A<T1>&)\n"; } template<class T> void f(T) { - std::cout << "f(T)\n"; + std::cout << "f(T)\n"; } int main() @@ -285,16 +276,16 @@ int main() }-Workaround: Declare all such functions uniformly as -either taking a value or a reference parameter. +Workaround: Declare all such functions uniformly as + either taking a value or a reference parameter.
+[instantiate memfun ptr] Instantiation with member function + pointer
-[instantiate memfun ptr] Instantiation with member function pointer
- -When directly instantiating a template with some member function -pointer, which is itself dependent on some template parameter, the -compiler cannot cope: -+When directly instantiating a template with some member function + pointer, which is itself dependent on some template parameter, the compiler + cannot cope:
+template<class U> class C { }; template<class T> class A @@ -303,9 +294,9 @@ class A };-Workaround: Use an intermediatetypedef: - -+Workaround: Use an intermediate +
+typedef:template<class U> class C { }; template<class T> class A @@ -315,20 +306,16 @@ class A };-(Extracted from e-mail exchange of David Abrahams, Fernando Cacciola, -and Peter Dimov; not actually tested.) +(Extracted from e-mail exchange of David Abrahams, Fernando Cacciola, + and Peter Dimov; not actually tested.)
+Library
-Library
+[cmath.abs] Function
- -double std::abs(double)missing[cmath.abs] Function
- -The functiondouble std::abs(double)-missingdouble std::abs(double)should be defined -(std:26.5-5 [lib.c.math]), but it is not: - -+The function
+double std::abs(double)should be defined + (std:26.5-5 [lib.c.math]), but it is not:#include <cmath> int main() @@ -337,40 +324,39 @@ int main() }-Note thatint std::abs(int)will be used without warning -if you writestd::abs(5.1). --Similar remarks apply to seemingly all of the other standard math -functions, where Borland C++ fails to provide
floatand -long doubleoverloads. --Workaround: Use
std::fabsinstead if -type genericity is not required. +Note that
-int std::abs(int)will be used without warning if + you writestd::abs(5.1).Appendix: Additional issues with Borland C++ version 5.5
+Similar remarks apply to seemingly all of the other standard math + functions, where Borland C++ fails to provide
-These issues are documented mainly for historic reasons. If you are -still using Borland C++ version 5.5, you are strongly encouraged to -obtain an upgrade to version 5.5.1, which fixes the issues described -in this section. +floatand +long doubleoverloads.Workaround: Use
-std::fabsinstead if type + genericity is not required.[inline friend] Inline friend functions in template classes
+Appendix: Additional issues with Borland C++ version 5.5
-If a friend function of some class has not been declared before the -friend function declaration, the function is declared at the namespace -scope surrounding the class definition. Together with class templates -and inline definitions of friend functions, the code in the following -fragment should declare (and define) a non-template function "bool -N::f(int,int)", which is a friend of class N::A<int>. However, -Borland C++ v5.5 expects the function f to be declared beforehand: +These issues are documented mainly for historic reasons. If you are + still using Borland C++ version 5.5, you are strongly encouraged to obtain + an upgrade to version 5.5.1, which fixes the issues described in this + section.
-+[inline friend] Inline friend functions in template classes
+ +If a friend function of some class has not been declared before the + friend function declaration, the function is declared at the namespace + scope surrounding the class definition. Together with class templates and + inline definitions of friend functions, the code in the following fragment + should declare (and define) a non-template function "bool N::f(int,int)", + which is a friend of class N::A<int>. However, Borland C++ v5.5 + expects the function f to be declared beforehand:
+namespace N { template<class T> class A { // "f is not a member of 'N' in function main()" - friend bool f(T x, T y) { return x < y; } + friend bool f(T x, T y) { return x < y; } }; } @@ -380,19 +366,29 @@ int main() }-This technique is extensively used in boost/operators.hpp. Giving in -to the wish of the compiler doesn't work in this case, because then -the "instantiate one template, get lots of helper functions at -namespace scope" approach doesn't work anymore. Defining -BOOST_NO_OPERATORS_IN_NAMESPACE (a define -BOOST_NO_INLINE_FRIENDS_IN_CLASS_TEMPLATES would match this case -better) works around this problem and leads to another one, see -[using-template]. +This technique is extensively used in boost/operators.hpp. Giving in to + the wish of the compiler doesn't work in this case, because then the + "instantiate one template, get lots of helper functions at namespace scope" + approach doesn't work anymore. Defining BOOST_NO_OPERATORS_IN_NAMESPACE (a + define BOOST_NO_INLINE_FRIENDS_IN_CLASS_TEMPLATES would match this case + better) works around this problem and leads to another one, see + [using-template].
+
-+
-
+Revised + 03 + December, 2006
-2000-09-30 Jens Maurer +Copyright © 2000-2002 Jens + Maurer
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or copy + at http://www.boost.org/LICENSE_1_0.txt)
diff --git a/count_bdy.htm b/count_bdy.htm index 0dd6f0b..67e9087 100644 --- a/count_bdy.htm +++ b/count_bdy.htm @@ -1,564 +1,313 @@ - + + + + + + + + + + +Counted Body Techniques + + + +Counted Body Techniques
+ ++ + + +++Reference counting techniques? Nothing new, you might think. Every good + C++ text that takes you to an intermediate or advanced level will + introduce the concept. It has been explored with such thoroughness in the + past that you might be forgiven for thinking that everything that can be + said has been said. Well, let's start from first principles and see if we + can unearth something new....
+
+ +And then there were none...
+ +++The principle behind reference counting is to keep a running usage + count of an object so that when it falls to zero we know the object is + unused. This is normally used to simplify the memory management for + dynamically allocated objects: keep a count of the number of references + held to that object and, on zero, delete the object.
+ +How to keep a track of the number of users of an object? Well, normal + pointers are quite dumb, and so an extra level of indirection is required + to manage the count. This is essentially the PROXY + pattern described in Design Patterns [Gamma, Helm, Johnson & + Vlissides, Addison-Wesley, ISBN 0-201-63361-2]. The + intent is given as
+ +++ +Provide a surrogate or placeholder for another object to control + access to it.
+Coplien [Advanced C++ Programming Styles and Idioms, + Addison-Wesley, ISBN 0-201-56365-7] defines a set + of idioms related to this essential separation of a handle and a body + part. The Taligent Guide to Designing Programs [Addison-Wesley, + ISBN 0-201-40888-0] identifies a number of specific + categories for proxies (aka surrogates). Broadly speaking they fall into + two general categories:
+ ++
+- Hidden: The handle is the object of interest, hiding the body + itself. The functionality of the handle is obtained by delegation to the + body, and the user of the handle is unaware of the body. Reference + counted strings offer a transparent optimisation. The body is shared + between copies of a string until such a time as a change is needed, at + which point a copy is made. Such a COPY ON WRITE + pattern (a specialisation of LAZY EVALUATION) requires the use of a hidden reference counted + body.
+ +- Explicit: Here the body is of interest and the handle merely + provides intelligence for its access and housekeeping. In C++ this is + often implemented as the SMART POINTER idiom. One such application is that of reference + counted smart pointers that collaborate to keep a count of an object, + deleting it when the count falls to zero.
+
+ +Attached vs detached
+ +++For reference counted smart pointers there are two places the count can + exist, resulting in two different patterns, both outlined in + Software Patterns [Coplien, SIGS, ISBN + 0-884842-50-X]:
+ ++
+ +- COUNTED BODY or ATTACHED + COUNTED + HANDLE/BODY places the + count within the object being counted. The benefits are that + countability is a part of the object being counted, and that reference + counting does not require an additional object. The drawbacks are + clearly that this is intrusive, and that the space for the reference + count is wasted when the object is not heap based. Therefore the + reference counting ties you to a particular implementation and style of + use.
+ +- DETACHED COUNTED + HANDLE/BODY places the + count outside the object being counted, such that they are handled + together. The clear benefit of this is that this technique is completely + unintrusive, with all of the intelligence and support apparatus in the + smart pointer, and therefore can be used on classes created + independently of the reference counted pointer. The main disadvantage is + that frequent use of this can lead to a proliferation of small objects, + i.e. the counter, being created on the heap.
+Even with this simple analysis, it seems that the DETACHED COUNTED HANDLE/BODY approach is ahead. Indeed, + with the increasing use of templates this is often the favourite, and is + the principle behind the common - but not standard - counted_ptr. [The Boost name is shared_ptr rather than counted_ptr.]
+ +A common implementation of COUNTED BODY is to provide the counting mechanism in a base class that + the counted type is derived from. Either that, or the reference counting + mechanism is provided anew for each class that needs it. Both of these + approaches are unsatisfactory because they are quite closed, coupling a + class into a particular framework. Added to this the non-cohesiveness of + having the count lying dormant in a non-counted object, and you get the + feeling that excepting its use in widespread object models such as COM and + CORBA the COUNTED BODY + approach is perhaps only of use in specialised situations.
+
+ +A requirements based approach
+ +++It is the question of openness that convinced me to revisit the + problems with the COUNTED BODY idiom. Yes, there is a certain degree of intrusion + expected when using this idiom, but is there anyway to minimise this and + decouple the choice of counting mechanism from the smart pointer type + used?
+ +In recent years the most instructive body of code and specification for + constructing open general purpose components has been the Stepanov and + Lee's STL (Standard Template Library), now part of the C++ standard + library. The STL approach makes extensive use of compile time polymorphism + based on well defined operational requirements for types. For instance, + each container, contained and iterator type is defined by the operations + that should be performable on an object of that type, often with + annotations describing additional constraints. Compile time polymorphism, + as its name suggests, resolves functions at compile time based on function + name and argument usage, i.e. overloading. This is less intrusive, + although less easily diagnosed if incorrect, than runtime poymorphism that + is based on types, names and function signatures.
+ +This requirements based approach can be applied to reference counting. + The operations we need for a type to be Countable are loosely:
+ ++
+ +- An acquire operation that registers + interest in a Countable object.
+ +- A release operation unregisters + interest in a Countable object.
+ +- An acquired query that returns + whether or not a Countable object is currently acquired.
+ +- A dispose operation that is + responsible for disposing of an object that is no longer acquired.
+Note that the count is deduced as a part of the abstract state of this + type, and is not mentioned or defined in any other way. The openness of + this approach derives in part from the use of global functions, meaning + that no particular member functions are implied; a perfect way to wrap up + an existing counted body class without modifying the class itself. The + other aspect to the openness comes from a more precise specification of + the operations.
+ +For a type to be Countable it must satisfy the following + requirements, where ptr is a non-null + pointer to a single object (i.e. not an array) of the type, and + #function indicates number of calls + to function(ptr):
+ ++ - ++
++ + +Expression + +Return type + +Semantics and notes ++ + +acquire(ptr) + +no requirement + +post: acquired(ptr) ++ - +release(ptr) + +no requirement - +pre: acquired(ptr) +
+ post: acquired(ptr) == #acquire - + #release+ - +acquired(ptr) -Counted Body Techniques +convertible to bool - +return: #acquire > #release ++ +dispose(ptr, ptr) - +no requirement - +pre: !acquired(ptr) +
+ post: *ptr no longer usableNote that the two arguments to dispose + are to support selection of the appropriate type safe version of the + function to be called. In the general case the intent is that the first + argument determines the type to be deleted, and would typically be + templated, while the second selects which template to use, e.g. by + conforming to a specific base class.
+In addition the following requirements must also be satisfied, where + null is a null pointer to the + Countable type:
++ - ++
++ +Expression -Counted Body Techniques
+Return type +Semantics and notes ++ +acquire(null) -+ no requirement -(kevlin@acm.org, khenney@qatraining.com)action: none ++ -release(null) +no requirement -+
action: none +Reference counting techniques? Nothing new, you might think. Every good +
+ -you might be forgiven for thinking that everything that can be said has +acquired(null) -C++ text that takes you to an intermediate or advanced level will introduce +convertible to bool -the concept. It has been explored with such thoroughness in the past that +return: false ++ +dispose(null, null) -been said. Well, let's start from first principles and see if we can unearth +no requirement -something new.... +action: none +Note that there are no requirements on these functions in terms of + exceptions thrown or not thrown, except that if exceptions are thrown the + functions themselves should be exception safe.
+
+Getting smart
+++Given the Countable requirements for a type, it is possible to + define a generic smart pointer type that uses them for reference counting:
- -
-And then there were none...
- - -- -
- - - - -The principle behind reference counting is to keep a running usage count - -of an object so that when it falls to zero we know the object is unused. - -This is normally used to simplify the memory management for dynamically - -allocated objects: keep a count of the number of references held to that - -object and, on zero, delete the object.
- - - -How to keep a track of the number of users of an object? Well, normal - -pointers are quite dumb, and so an extra level of indirection is required - -to manage the count. This is essentially the PROXY - -pattern described in Design Patterns [Gamma, Helm, Johnson & - -Vlissides, Addison-Wesley, ISBN 0-201-63361-2]. The - -intent is given as
- - - -- -
- - - -Provide a surrogate or placeholder for another object to control - -access to it.
- -Coplien [Advanced C++ Programming Styles and Idioms, Addison-Wesley, - -ISBN 0-201-56365-7] defines a set of idioms related - -to this essential separation of a handle and a body part. The Taligent - -Guide to Designing Programs [Addison-Wesley, ISBN 0-201-40888-0] - -identifies a number of specific categories for proxies (aka surrogates). - -Broadly speaking they fall into two general categories:
- - - -- -
- -- Hidden: The handle is the object of interest, hiding the body - -itself. The functionality of the handle is obtained by delegation to the - -body, and the user of the handle is unaware of the body. Reference counted - -strings offer a transparent optimisation. The body is shared between copies - -of a string until such a time as a change is needed, at which point a copy - -is made. Such a COPY ON WRITE - -pattern (a specialisation of LAZY EVALUATION) - -requires the use of a hidden reference counted body.
- - - -- Explicit: Here the body is of interest and the handle merely - -provides intelligence for its access and housekeeping. In C++ this is often - -implemented as the SMART POINTER - -idiom. One such application is that of reference counted smart pointers - -that collaborate to keep a count of an object, deleting it when the count - -falls to zero.
- -
-Attached vs detached
- - -- -
- - - -For reference counted smart pointers there are two places the count - -can exist, resulting in two different patterns, both outlined in Software - -Patterns [Coplien, SIGS, ISBN 0-884842-50-X]:
- - - -- -
- - - -- COUNTED BODY or ATTACHED - -COUNTED HANDLE/BODY - -places the count within the object being counted. The benefits are that - -countability is a part of the object being counted, and that reference - -counting does not require an additional object. The drawbacks are clearly - -that this is intrusive, and that the space for the reference count is wasted - -when the object is not heap based. Therefore the reference counting ties - -you to a particular implementation and style of use.
- - - -- DETACHED COUNTED HANDLE/BODY - -places the count outside the object being counted, such that they are handled - -together. The clear benefit of this is that this technique is completely - -unintrusive, with all of the intelligence and support apparatus in the - -smart pointer, and therefore can be used on classes created independently - -of the reference counted pointer. The main disadvantage is that frequent - -use of this can lead to a proliferation of small objects, i.e. the counter, - -being created on the heap.
- -Even with this simple analysis, it seems that the DETACHED - -COUNTED HANDLE/BODY - -approach is ahead. Indeed, with the increasing use of templates this is - -often the favourite, and is the principle behind the common - but not standard - -- counted_ptr. -[The Boost name is shared_ptr - -rather than counted_ptr.]
- - - -A common implementation of COUNTED BODY - -is to provide the counting mechanism in a base class that the counted type - -is derived from. Either that, or the reference counting mechanism is provided - -anew for each class that needs it. Both of these approaches are unsatisfactory - -because they are quite closed, coupling a class into a particular framework. - -Added to this the non-cohesiveness of having the count lying dormant in - -a non-counted object, and you get the feeling that excepting its use in - -widespread object models such as COM and CORBA the COUNTED - -BODY approach is perhaps only of use in specialised - -situations.
- -
-A requirements based approach
- - -- -
- - - -It is the question of openness that convinced me to revisit the problems - -with the COUNTED BODY idiom. - -Yes, there is a certain degree of intrusion expected when using this idiom, - -but is there anyway to minimise this and decouple the choice of counting - -mechanism from the smart pointer type used?
- - - -In recent years the most instructive body of code and specification - -for constructing open general purpose components has been the Stepanov - -and Lee's STL (Standard Template Library), now part of the C++ standard - -library. The STL approach makes extensive use of compile time polymorphism - -based on well defined operational requirements for types. For instance, - -each container, contained and iterator type is defined by the operations - -that should be performable on an object of that type, often with annotations - -describing additional constraints. Compile time polymorphism, as its name - -suggests, resolves functions at compile time based on function name and - -argument usage, i.e. overloading. This is less intrusive, although less - -easily diagnosed if incorrect, than runtime poymorphism that is based on - -types, names and function signatures.
- - - -This requirements based approach can be applied to reference counting. - -The operations we need for a type to be Countable are loosely:
- - - -- -
- - - -- An acquire operation that registers interest - -in a Countable object.
- - - -- A release operation unregisters interest - -in a Countable object.
- - - -- An acquired query that returns whether - -or not a Countable object is currently acquired.
- - - -- A dispose operation that is responsible - -for disposing of an object that is no longer acquired.
- -Note that the count is deduced as a part of the abstract state of this - -type, and is not mentioned or defined in any other way. The openness of - -this approach derives in part from the use of global functions, meaning - -that no particular member functions are implied; a perfect way to wrap - -up an existing counted body class without modifying the class itself. The - -other aspect to the openness comes from a more precise specification of - -the operations.
- - - -For a type to be Countable it must satisfy the following requirements, - -where ptr is a non-null pointer to a single - -object (i.e. not an array) of the type, and #function - -indicates number of calls to function(ptr):
- - - -- - - - - -
- - - - - -Expression - - - -Return type - - - -Semantics and notes - -- - - - - -acquire(ptr) - - - -no requirement - - - -post: acquired(ptr) - -- - - - - -release(ptr) - - - -no requirement - - - -pre: acquired(ptr) - -
- -post: acquired(ptr) == #acquire - - -#release- - - - - -acquired(ptr) - - - -convertible to bool - - - -return: #acquire > #release - -- - - -dispose(ptr, ptr) - - - -no requirement - - - -pre: !acquired(ptr) - -
- -post: *ptr no longer usableNote that the two arguments to dispose - -are to support selection of the appropriate type safe version of the function - -to be called. In the general case the intent is that the first argument - -determines the type to be deleted, and would typically be templated, while - -the second selects which template to use, e.g. by conforming to a specific - -base class.
- - - -In addition the following requirements must also be satisfied, where - -null is a null pointer to the Countable - -type:
- - - -- - - - - -
- - - - - -Expression - - - -Return type - - - -Semantics and notes - -- - - - - -acquire(null) - - - -no requirement - - - -action: none - -- - - - - -release(null) - - - -no requirement - - - -action: none - -- - - - - -acquired(null) - - - -convertible to bool - - - -return: false - -- - - -dispose(null, null) - - - -no requirement - - - -action: none - -Note that there are no requirements on these functions in terms of exceptions - -thrown or not thrown, except that if exceptions are thrown the functions - -themselves should be exception safe.
- -
-Getting smart
- - -- -
Given the Countable requirements for a type, it is possible to - -define a generic smart pointer type that uses them for reference counting:
- - - --
template<typename countable_type> ++- ++template<typename countable_type> class countable_ptr { public: // construction and destruction @@ -585,27 +334,19 @@ private: // representation countable_type *body; }; -+ + +The interface to this class has been kept intentionally simple, e.g. + member templates and throw specs have been + omitted, for exposition. The majority of the functions are quite simple in + implementation, relying very much on the assign member as a keystone function:
- - -The interface to this class has been kept intentionally simple, e.g. - -member templates and throw specs have been - -omitted, for exposition. The majority of the functions are quite simple - -in implementation, relying very much on the assign - -member as a keystone function:
- - - -- -
template<typename countable_type> ++++template<typename countable_type> countable_ptr<countable_type>::countable_ptr(countable_type *initial) : body(initial) { @@ -678,33 +419,24 @@ countable_ptr<countable_type> &countable_ptr<countable_type>::op { return assign(rhs); } -+ + +
- +Public accountability
- +++Conformance to the requirements means that a type can be used with + countable_ptr. Here is an implementation + mix-in class (mix-imp) that confers countability on its derived + classes through member functions. This class can be used as a class + adaptor:
- - -
-Public accountability
- - -- -
Conformance to the requirements means that a type can be used with countable_ptr. - -Here is an implementation mix-in class (mix-imp) that confers countability - -on its derived classes through member functions. This class can be used - -as a class adaptor:
- - - -- -
class countability ++- ++class countability { public: // manipulation @@ -727,41 +459,27 @@ private: // prevention countability &operator=(const countability &); }; -+ + +Notice that the manipulation functions are const and that the count + member itself is mutable. This is because + countability is not a part of an object's abstract state: memory + management does not depend on the const-ness or otherwise of an object. I won't include the + definitions of the member functions here as you can probably guess them: + increment, decrement and return the current count, respectively for the + manipulation functions. In a multithreaded environment you should ensure + that such read and write operations are atomic.
+So how do we make this class Countable? A simple set of + forwarding functions does the job:
- -Notice that the manipulation functions are const - -and that the count member itself is mutable. - -This is because countability is not a part of an object's abstract state: - -memory management does not depend on the const-ness - -or otherwise of an object. I won't include the definitions of the member - -functions here as you can probably guess them: increment, decrement and - -return the current count, respectively for the manipulation functions. - -In a multithreaded environment you should ensure that such read and write - -operations are atomic.
- - - -So how do we make this class Countable? A simple set of forwarding - -functions does the job:
- - - -- -
void acquire(const countability *ptr) ++- ++void acquire(const countability *ptr) { if(ptr) { @@ -787,21 +505,17 @@ void dispose(const countability_derived *ptr, const countability *) { delete ptr; } -+ + +Any type that now derives from countability may now be used with countable_ptr:
- - -Any type that now derives from countability - -may now be used with countable_ptr:
- - - -- -
class example : public countability ++++class example : public countability { ... }; @@ -812,91 +526,59 @@ void simple() countable_ptr<example> qtr(ptr); ptr.clear(); // set ptr to point to null } // allocated object deleted when qtr destructs -- - + + +
+Runtime mixin
+++The challenge is to apply COUNTED BODY in a non-intrusive fashion, such that there is no overhead + when an object is not counted. What we would like to do is confer this + capability on a per object rather than on a per class basis. Effectively + we are after Countability on any object, i.e. anything pointed to + by a void *! It goes without saying that + void is perhaps the least committed of any type.
+The forces to resolve on this are quite interesting, to say the least. + Interesting, but not insurmountable. Given that the class of a runtime + object cannot change dynamically in any well defined manner, and the + layout of the object must be fixed, we have to find a new place and time + to add the counting state. The fact that this must be added only on heap + creation suggests the following solution:
-
-Runtime mixin
- - -- -
The challenge is to apply COUNTED BODY - -in a non-intrusive fashion, such that there is no overhead when an object - -is not counted. What we would like to do is confer this capability on a - -per object rather than on a per class basis. Effectively we are after Countability - -on any object, i.e. anything pointed to by a void - -*! It goes without saying that void - -is perhaps the least committed of any type.
- - - -The forces to resolve on this are quite interesting, to say the least. - -Interesting, but not insurmountable. Given that the class of a runtime - -object cannot change dynamically in any well defined manner, and the layout - -of the object must be fixed, we have to find a new place and time to add - -the counting state. The fact that this must be added only on heap creation - -suggests the following solution:
- - - -- -
struct countable_new; ++++struct countable_new; extern const countable_new countable; void *operator new(size_t, const countable_new &); -void operator delete(void *, const countable_new &);- +void operator delete(void *, const countable_new &); + +We have overloaded operator new with a + dummy argument to distinguish it from the regular global operator new. This is comparable to the use of the + std::nothrow_t type and std::nothrow object in the standard library. The + placement operator delete is there to + perform any tidy up in the event of failed construction. Note that this is + not yet supported on all that many compilers.
+The result of a new expression using + countable is an object allocated on the + heap that has a header block that holds the count, i.e. we have extended + the object by prefixing it. We can provide a couple of features in an + anonymous namespace (not shown) in the implementation file for for + supporting the count and its access from a raw pointer:
-We have overloaded operator new with a - -dummy argument to distinguish it from the regular global operator - -new. This is comparable to the use of the std::nothrow_t - -type and std::nothrow object in the standard - -library. The placement operator delete is - -there to perform any tidy up in the event of failed construction. Note - -that this is not yet supported on all that many compilers.
- - - -The result of a new expression using countable - -is an object allocated on the heap that has a header block that holds the - -count, i.e. we have extended the object by prefixing it. We can provide - -a couple of features in an anonymous namespace (not shown) in the implementation - -file for for supporting the count and its access from a raw pointer:
- - - -- -
struct count ++- ++struct count { size_t value; }; @@ -905,49 +587,33 @@ count *header(const void *ptr) { return const_cast<count *>(static_cast<const count *>(ptr) - 1); } -+ + +An important constraint to observe here is the alignment of + count should be such that it is suitably + aligned for any type. For the definition shown this will be the case on + almost all platforms. However, you may need to add a padding member for + those that don't, e.g. using an anonymous union to coalign count + and the most aligned type. Unfortunately, there is no portable way of + specifying this such that the minimum alignment is also observed - this is + a common problem when specifying your own allocators that do not directly + use the results of either new or + malloc.
+Again, note that the count is not considered to be a part of the + logical state of the object, and hence the conversion from + const to non-const - count is in + effect a mutable type.
+The allocator functions themselves are fairly straightforward:
-An important constraint to observe here is the alignment of count - -should be such that it is suitably aligned for any type. For the definition - -shown this will be the case on almost all platforms. However, you may need - -to add a padding member for those that don't, e.g. using an anonymous union - -to coalign count and the most aligned type. - -Unfortunately, there is no portable way of specifying this such that the - -minimum alignment is also observed - this is a common problem when specifying - -your own allocators that do not directly use the results of either new - -or malloc.
- - - -Again, note that the count is not considered to be a part of the logical - -state of the object, and hence the conversion from const - -to non-const - count - -is in effect a mutable type.
- - - -The allocator functions themselves are fairly straightforward:
- - - -- -
void *operator new(size_t size, const countable_new &) ++- ++void *operator new(size_t size, const countable_new &) { count *allocated = static_cast<count *>(::operator new(sizeof(count) + size)); *allocated = count(); // initialise the header @@ -958,23 +624,17 @@ void operator delete(void *ptr, const countable_new &) { ::operator delete(header(ptr)); } -+ + +Given a correctly allocated header, we now need the Countable + functions to operate on const void * to + complete the picture:
- - -Given a correctly allocated header, we now need the Countable functions - -to operate on const void * to complete the - -picture:
- - - -- -
void acquire(const void *ptr) ++- ++void acquire(const void *ptr) { if(ptr) { @@ -1001,49 +661,32 @@ void dispose(const countable_type *ptr, const void *) ptr->~countable_type(); operator delete(const_cast<countable_type *>(ptr), countable); } -+ + +The most complex of these is the dispose function that must ensure that the correct type + is destructed and also that the memory is collected from the correct + offset. It uses the value and type of first argument to perform this + correctly, and the second argument merely acts as a strategy selector, + i.e. the use of const void * + distinguishes it from the earlier dispose shown for const countability *.
+
+Getting smarter
+++Now that we have a way of adding countability at creation for objects + of any type, what extra is needed to make this work with the + countable_ptr we defined earlier? Good + news: nothing!
-The most complex of these is the dispose - -function that must ensure that the correct type is destructed and also - -that the memory is collected from the correct offset. It uses the value - -and type of first argument to perform this correctly, and the second argument - -merely acts as a strategy selector, i.e. the use of const - -void * distinguishes it from the earlier dispose shown for - -const countability *.
- - - - - - -
-Getting smarter
- - - -- -
Now that we have a way of adding countability at creation for objects - -of any type, what extra is needed to make this work with the countable_ptr - -we defined earlier? Good news: nothing!
- - - -- -
class example +++ ++class example { ... }; @@ -1054,113 +697,78 @@ void simple() countable_ptr<example> qtr(ptr); ptr.clear(); // set ptr to point to null } // allocated object deleted when qtr destructs -- - - - - -The new(countable) expression defines - -a different policy for allocation and deallocation and, in common with - -other allocators, any attempt to mix your allocation policies, e.g. call - -delete on an object allocated with new(countable), - -results in undefined behaviour. This is similar to what happens when you - -mix new[] with delete - -or malloc with delete. - -The whole point of Countable conformance is that Countable objects - -are used with countable_ptr, and this ensures - -the correct use.
- - - -However, accidents will happen, and inevitably you may forget to allocate - -using new(countable) and instead use new. - -This error and others can be detected in most cases by extending the code - -shown here to add a check member to the count, - -validating the check on every access. A benefit of ensuring clear separation - -between header and implementation source files means that you can introduce - -a checking version of this allocator without having to recompile your code.
- - - - - - -
-Conclusion
- - - -- -
- - - -There are two key concepts that this article has introduced:
- - - -- -
- - - -- The use of a generic requirements based approach to simplify and adapt - -the use of the COUNTED BODY pattern.
- - - -- The ability, through control of allocation, to dynamically and non-intrusively - -add capabilities to fixed types using the RUNTIME - -MIXIN pattern.
- -The application of the two together gives rise to a new variant of the - -essential COUNTED BODY pattern, - -UNINTRUSIVE COUNTED BODY. - -You can take this theme even further and contrive a simple garbage collection - -system for C++.
- - - -The complete code for countable_ptr, countability, - -and the countable new is also available.
- -- - - - - - - + + +- -
First published in Overload 25, - -April 1998, ISSN 1354-3172
- -© Copyright Kevlin Henney, 1998, 1999The new(countable) expression defines a + different policy for allocation and deallocation and, in common with other + allocators, any attempt to mix your allocation policies, e.g. call + delete on an object allocated with + new(countable), results in undefined + behaviour. This is similar to what happens when you mix new[] with delete or + malloc with delete. The whole point of Countable conformance + is that Countable objects are used with countable_ptr, and this ensures the correct use.
+ +However, accidents will happen, and inevitably you may forget to + allocate using new(countable) and instead + use new. This error and others can be + detected in most cases by extending the code shown here to add a check + member to the count, validating the check + on every access. A benefit of ensuring clear separation between header and + implementation source files means that you can introduce a checking + version of this allocator without having to recompile your code.
+
+ +Conclusion
+ +++ +There are two key concepts that this article has introduced:
+ ++
+ +- The use of a generic requirements based approach to simplify and + adapt the use of the COUNTED BODY pattern.
+ +- The ability, through control of allocation, to dynamically and + non-intrusively add capabilities to fixed types using the RUNTIME MIXIN pattern.
+The application of the two together gives rise to a new variant of the + essential COUNTED BODY + pattern, UNINTRUSIVE COUNTED BODY. You can take this theme + even further and contrive a simple garbage collection system for C++.
+ +The complete code for countable_ptr, + countability, and the countable new is also available.
+++ +
+ First published in Overload 25, + April 1998, ISSN 1354-3172 ++ +
Revised + 04 December, 2006
+ +Copyright © 1998-1999 Kevlin Henney
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or copy + at http://www.boost.org/LICENSE_1_0.txt)
+ + diff --git a/discussion_policy.htm b/discussion_policy.htm index c171f0b..3a584af 100644 --- a/discussion_policy.htm +++ b/discussion_policy.htm @@ -2,17 +2,17 @@ - + - + +Boost Discussion Policy -
|
@@ -153,7 +153,6 @@
|
-
|
- Home | -Libraries | -People | -FAQ | -More | -
+
+
Similar to the portability hints for Borland + C++, this page provides hints on some language features of the + Microsoft Visual C++ version 6.0 service pack 4 compiler. A list of + acknowledged deficiencies can be found at the Microsoft + support site.
-The preprocessor symbol_MSC_VER is defined for all
-Microsoft C++ compilers. Its value is the internal version number of the
-compiler interpreted as a decimal number. Since a few other compilers
-also define this symbol, boost provides the symbol
-BOOST_MSVC, which is defined in
-boost/config.hpp
-to the value of _MSC_VER if and only if the compiler is really
-Microsoft Visual C++.
+ Each entry in the following list describes a particular issue, complete + with sample source code to demonstrate the effect. Most sample code herein + has been verified to compile with gcc 2.95.2 and Comeau C++ 4.2.44.
-The following table lists some known values. -+
| Compiler | -BOOST_MSVC value |
-
|---|---|
| Microsoft Visual C++ 6.0 (up to SP6) | -1200 | -
| Compiler | -|
|---|---|
| Microsoft embedded Visual C++ 4.0 | -1200-1202 (cross compilers) | -BOOST_MSVC value |
+
-
using-declarationsusing-declarations does not work.
-+Core Language
+ +[chained using] Chaining
+ +using-declarationsChaining
+using-declarations does not work.void f(); namespace N { @@ -86,39 +92,33 @@ void g() }+[explicit-instantiation] Explicit function template instantiation
-[explicit-instantiation] Explicit function template -instantiation
- -Trying to explicitly instantiate a function template leads to the -wrong function being called silently. - -+Trying to explicitly instantiate a function template leads to the wrong + function being called silently.
+#include <stdio.h> template<class T> void f() { - printf("%d\n", sizeof(T)); + printf("%d\n", sizeof(T)); } int main() { - f<double>(); // output: "1" - f<char>(); // output: "1" + f<double>(); // output: "1" + f<char>(); // output: "1" return 0; }+[for-scoping] Scopes of definitions in for-loops
-[for-scoping] Scopes of definitions in for-loops
- -The scope of variable definitions inforloops should be -local to the loop's body, but it is instead local to the enclosing -block. - - -+The scope of variable definitions in
+forloops should be + local to the loop's body, but it is instead local to the enclosing + block.int main() { for(int i = 0; i < 5; ++i) @@ -129,51 +129,46 @@ int main() }-Workaround: Enclose the offendingfor-loops in another pair of curly braces. --Another possible workaround (brought to my attention by Vesa Karvonen) -is this: -
+Workaround: Enclose the offending
+ +for+ loops in another pair of curly braces.Another possible workaround (brought to my attention by Vesa Karvonen) + is this:
+#ifndef for #define for if (0) {} else for #endif-Note that platform-specific inline functions in included headers might -depend on the old-styleforscoping. +Note that platform-specific inline functions in included headers might + depend on the old-style
+forscoping.[inclass-member-init] In-class member initialization
-[inclass-member-init] In-class member initialization
- -In-class member initialization, required to implement a -Standard-conformingstd::numeric_limitstemplate, does -not work. - -+In-class member initialization, required to implement a + Standard-conforming
+std::numeric_limitstemplate, does not + work.struct A { - static const int i = 5; // "invalid syntax for pure virtual method" + static const int i = 5; // "invalid syntax for pure virtual method" };-Workaround: Either use an enum (which has incorrect -type, but can be used in compile-time constant expressions), or define -the value out-of-line (which allows for the correct type, but prohibits -using the constant in compile-time constant expressions). See -Coding Guidelines for Integral Constant Expressions -for guidelines how to define member constants portably in boost -libraries. +Workaround: Either use an enum (which has incorrect + type, but can be used in compile-time constant expressions), or define the + value out-of-line (which allows for the correct type, but prohibits using + the constant in compile-time constant expressions). See Coding Guidelines for Integral Constant + Expressions for guidelines how to define member constants portably in + boost libraries.
+[koenig-lookup] Argument-dependent lookup
-[koenig-lookup] Argument-dependent lookup
- -Argument-dependent lookup, also called Koenig lookup, works for -overloaded operators, but not for ordinary functions. No -additional namespaces induced from the argument types seem to be -considered. - -+Argument-dependent lookup, also called Koenig lookup, works for + overloaded operators, but not for ordinary functions. No additional + namespaces induced from the argument types seem to be considered.
+namespace N { struct A {}; void f(A); @@ -186,29 +181,26 @@ void g() }+[template-friend] Templates as friends
-[template-friend] Templates as friends
- -A Template cannot be declared a friend of a class. - -+A Template cannot be declared a friend of a class.
+template<class T> struct A {}; struct B { template<class T> - friend struct A; // "syntax error" + friend struct A; // "syntax error" };+[member-template-outofline] Out-of-line definitions of member + templates
-[member-template-outofline] Out-of-line definitions of member -templates
- -Defining member templates outside their enclosing class does not work. - -+Defining member templates outside their enclosing class does not + work.
+template<class T> struct A { @@ -217,21 +209,19 @@ struct A }; template<class T> -template<class U> // "syntax error" -void A<T>::f() // "T: undeclared identifier" +template<class U> // "syntax error" +void A<T>::f() // "T: undeclared identifier" { }-Workaround: Define member templates in-line within -their enclosing class. +Workaround: Define member templates in-line within + their enclosing class.
+[partial-spec] Partial specialization
-[partial-spec] Partial specialization
- -Partial specialization of class templates does not work. - -+Partial specialization of class templates does not work.
+template<class T> struct A {}; @@ -242,52 +232,45 @@ template<class T> struct A<B<T> > {}; // template class was already defined as a non-template-Workaround: In some situations where interface -does not matter, class member templates can simulate partial -specialization. +Workaround: In some situations where interface does not + matter, class member templates can simulate partial specialization.
+[template-value] Dependent template value parameters
-[template-value] Dependent template value parameters
- -Template value parameters whose type depends on a previous template -parameter provoke an internal compiler error if the correct syntax -(with "typename") is used. - -+Template value parameters whose type depends on a previous template + parameter provoke an internal compiler error if the correct syntax (with + "typename") is used.
+template<class T, typename T::result_type> // C1001: INTERNAL COMPILER ERROR: msc1.cpp, line 1794 struct B {}; - // (omit "typename" and it compiles) + // (omit "typename" and it compiles)-Workaround: Leave off the "typename" keyword. That makes -the program non-conforming, though. +Workaround: Leave off the "typename" keyword. That + makes the program non-conforming, though.
+[wchar_t]
-wchar_tis not built-in[wchar_t]
- -The typewchar_tis not built-inwchar_tis not a built-in type. - --wchar_t x; // "missing storage class or type identifier" +The type
+wchar_tis not a built-in type.+wchar_t x; // "missing storage class or type identifier"-Workaround: When using Microsoft Visual C++, the -header -boost/config.hpp -includes<cstddef>, which defines -wchar_tas a typedef forunsigned -short. Note that this means that the compiler does not regard -wchar_tandunsigned shortas distinct -types, as is required by the standard, and so ambiguities may emanate -when overloading onwchar_t. The macro -BOOST_NO_INTRINSIC_WCHAR_Tis defined in this situation. +Workaround: When using Microsoft Visual C++, the header + boost/config.hpp includes +
+<cstddef>, which defineswchar_tas a + typedef forunsigned short. Note that this means that the + compiler does not regardwchar_tandunsigned + shortas distinct types, as is required by the standard, and so + ambiguities may emanate when overloading onwchar_t. The macro +BOOST_NO_INTRINSIC_WCHAR_Tis defined in this situation.[delete-const-pointer] Deleting
-const X *does not + work[delete-const-pointer] Deleting
- -Trying to delete a pointer to a cv-qualified type gives an error: -const X *does not work+Trying to delete a pointer to a cv-qualified type gives an error:
+void f() { const int *p = new int(5); @@ -295,29 +278,49 @@ void f() }-Workaround: Define the function -+Workaround: Define the function
+inline void operator delete(const void *p) throw() -{ operator delete(const_cast<void*>(p)); } +{ operator delete(const_cast<void*>(p)); }-and similar functions for the other cv-qualifier combinations, for -operator delete[], and for thestd::nothrowvariants. +and similar functions for the other cv-qualifier combinations, for + operator delete[], and for the
+std::nothrowvariants.Standard Library
-Standard Library
+[clib-namespace] C library names in global namespace instead of + std
-[clib-namespace] C library names in global namespace instead of std
-Library names from the <c...> headers are in the global namespace -instead of namespace std.
Workaround: The header boost/config.hpp -will define BOOST_NO_STDC_NAMESPACE. It can be used as follows: -
# ifdef BOOST_NO_STDC_NAMESPACE +-2001-05-04 Jens Maurer +Library names from the <c...> headers are in the global namespace + instead of namespace std.
+ +Workaround: The header boost/config.hpp will define + BOOST_NO_STDC_NAMESPACE. It can be used as follows:
++# ifdef BOOST_NO_STDC_NAMESPACE namespace std { using ::abs; using ::fabs; } -# endif-Because std::size_t and std::ptrdiff_t are so commonly used, the workaround -for these is already provided in boost/config.hpp.
-
+# endif +Because std::size_t and std::ptrdiff_t are so commonly used, the + workaround for these is already provided in boost/config.hpp.
+
+ ++ +
Revised + 04 December, 2006
+ +Copyright © 2001-2002 Jens + Maurer
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or copy + at http://www.boost.org/LICENSE_1_0.txt)
diff --git a/writingdoc/design.html b/writingdoc/design.html index 56d3e64..7e95a63 100644 --- a/writingdoc/design.html +++ b/writingdoc/design.html @@ -1,377 +1,576 @@ + + - - -Writing Documentation for Boost - HTML Design + + + + +Writing Documentation for Boost - HTML Design - -
|
- |
-
- Writing Documentation for Boost-HTML Design- |
-
|
+ |
+
+
+ Writing Documentation for Boost+ +HTML Design+ |
+
Boost places no requirements on the design of HTML documentation for library - submitters. If you are submitting a library for which documentation already - exists in either HTML or in a form easily converted to HTML then there is no - need for you to read this document. However, if you have not yet written the - documentation, or if you expect to have to translate documentation written in - a format not easily convertible to HTML then this document can give you a lot - of information on how to go about writing documentation in HTML.
-In several places this document assumes you're writing the documentation to - conform to the structure described in the Documentation - Structure document. There is no requirement that your documentation content - follow these guidelines, but they provide an effective way to communicate technical - specifications for a library in a terse yet precise manner that's familiar to - many Boost users.
-This document also contains links to HTML template files - that can be used to rapidly develop documentation for a library submission. - These templates follow the guidelines presented here and in the Documentation - Structure document.
-Most HTML documentation projects will contain some common pages. General guidelines - for these common pages are provided below.
-The index page is the first page presented to a user when he browses the documentation. - Generally this page should not contain any actual content, but instead contains - a list of links to specific content. At a minimum this list should contain a - link to every HTML page contained in the documentation. Optionally, sub-lists - may be provided for individual pages linking to specific subjects within the - page. These sub-lists should form a "tree" hierarchy based on the - level of heading tag used for the specific subject. Inclusion of such sub-lists - for every page can make the index rather lengthy, and since each page should - include its own Page Index, it may make the navigation - of the documentation easier if such sub-lists are avoided. However, there is - one exception to this guideline: reference documentation should contain a link - to every header file in the library and a sub-list with a link to every macro, - value, type, class, function and object (see Documentation - Structure) found in the header. Users aren't always sure what header file - any of these may be contained in, so this structure in the index allows for - easy navigation of the reference documentation.
-The index list should generally be constructed using an HTML "definition
- list" (<dl> and <dt> tags). A definition list has no bullets
- or ordered specifications and produces a cleaner layout then an unordered list
- (<ul> and <li> tags) or an ordered list (<ol> and <li>
- tags). If you choose to use the common Boost Style
- Sheet you should add a class="index" attribute/value pair to
- the <dl> tag.
An Index page template is provided for use.
-The Overview page is used to introduce the reader to the library. It should - give a high-level overview of the purpose of the library and introduce the reader - to any concepts they may be unfamiliar with. This may also be an appropriate - place for some "light" rationale, though more thorough presentation - of any rationale would be better placed in the Rational - Page.
-Like most content pages, the Overview page should include a Page - Index.
-An Overview page template is provided for + +
Boost places no requirements on the design of HTML documentation for + library submitters. If you are submitting a library for which documentation + already exists in either HTML or in a form easily converted to HTML then + there is no need for you to read this document. However, if you have not + yet written the documentation, or if you expect to have to translate + documentation written in a format not easily convertible to HTML then this + document can give you a lot of information on how to go about writing + documentation in HTML.
+ +In several places this document assumes you're writing the documentation + to conform to the structure described in the Documentation Structure document. There is no + requirement that your documentation content follow these guidelines, but + they provide an effective way to communicate technical specifications for a + library in a terse yet precise manner that's familiar to many Boost + users.
+ +This document also contains links to HTML template + files that can be used to rapidly develop documentation for a library + submission. These templates follow the guidelines presented here and in the + Documentation Structure document.
+ +Most HTML documentation projects will contain some common pages. General + guidelines for these common pages are provided below.
+ +The index page is the first page presented to a user when he browses the + documentation. Generally this page should not contain any actual content, + but instead contains a list of links to specific content. At a minimum this + list should contain a link to every HTML page contained in the + documentation. Optionally, sub-lists may be provided for individual pages + linking to specific subjects within the page. These sub-lists should form a + "tree" hierarchy based on the level of heading tag used for the specific + subject. Inclusion of such sub-lists for every page can make the index + rather lengthy, and since each page should include its own Page Index, it may make the navigation of the + documentation easier if such sub-lists are avoided. However, there is one + exception to this guideline: reference documentation should contain a link + to every header file in the library and a sub-list with a link to every + macro, value, type, class, function and object (see Documentation Structure) found in the header. Users + aren't always sure what header file any of these may be contained in, so + this structure in the index allows for easy navigation of the reference + documentation.
+ +The index list should generally be constructed using an HTML "definition
+ list" (<dl> and <dt> tags). A definition list has no bullets or
+ ordered specifications and produces a cleaner layout then an unordered list
+ (<ul> and <li> tags) or an ordered list (<ol> and
+ <li> tags). If you choose to use the common Boost Style Sheet you should add a
+ class="index" attribute/value pair to the <dl> tag.
An Index page template is provided for use.
-The Definitions page is used to provide a list of definitions for terms that - a user may be unfamiliar with.
-The definition list should generally be constructed using an HTML "definition
- list" (<dl> and <DT> tags). A definition list has no bullets
- or ordered specifications and produces a cleaner layout then an unordered list
- (<UL> and <li> tags) or an ordered list (<ol> and <li>
- tags). If you choose to use the common Boost Style
- Sheet you should add a class="definition" attribute/value pair
- to the <dl> tag.
Because this page's content should only contain a list of definitions, it should - not have a Page Index.
- -A Definitions page template is provided + +
The Overview page is used to introduce the reader to the library. It + should give a high-level overview of the purpose of the library and + introduce the reader to any concepts they may be unfamiliar with. This may + also be an appropriate place for some "light" rationale, though more + thorough presentation of any rationale would be better placed in the + Rational Page.
+ +Like most content pages, the Overview page should include a Page Index.
+ +An Overview page template is provided for use.
-The Rationale page is used to provide lengthy descriptions of the rationale - behind the library's design. This information helps users to understand why - a library was designed the way it was and may reduce the frequency of a number - of frequently asked questions. For a better description of why rationale is - important see the Rationale - rationale in the general submission guidelines.
-Like most content pages, the Rationale page should include a Page - Index.
- -A Rationale page template is provided for - use.
-The Configuration Information page is used to document configuration macros
- used by the library. Such macros belong in one of three groups: macros used
- by library implenters defined in <boost/config.hpp>, macros
- used by library users to detect platform configuration information and macros
- defined by library users to configure library behavior.
Like most content pages, the Overview page should include a Page - Index.
- -A Configuration page template is provided - for use.
-As a library matures the users will have questions about the usage of the library. - Often users will ask the same questions over and over again. Rather than having - to deal with answering the question every time it's asked, a Frequently Asked - Questions (commonly known as FAQs) page can be used to document the questions - and answers. This is such a valuable piece of documentation not only for the - users but for the maintainers as well, that a FAQ page should be provided from - the outset. If there are no questions that will obviously become a FAQ, the - initial page may just indicate that there are no FAQs yet. This empty place - holder helps to indicate to the users that you plan to address any FAQs as they - occur.
-The Page Index for the FAQ page should contain a - list of all the questions contained in the document. The actual question entries - should be formatted with the question in a heading tag and the answers in standard - paragraph format. This provides a clean presentation that's easy to read.
-A Frequently Asked Questions page template is provided - for use.
-The Bibliography page is used to document any bibliographical information associated - with references made within the documentation to external resources. Parenthetical - references are used within the documentation which link to entries in the Bibliography - page. Bibliographical entries provide detailed information about the external - resource and may contain hyper links to the resource if it's available online. - There are several formal styles used for writing bibliographies. You may use - what ever style you want, but one of the better styles to consider using can - be referenced here.
-Since the Bibliography page should contain only bibliographical information - there is no need for a Page Index.
-A Bibliography page template is provided - for use.
-The Acknowledgment page is used to give credit where credit is due. When individuals - provide input on the design or implementation, or when you make use of someone - else's work, you should acknowledge them. This is a courtesy that you'd expect - others to extend to you, so you should strive to acknowledge the efforts of - everyone else in your own documentation.
-Since the Acknowledgment page should contain only a list of acknowledgment - there is no need for a Page Index.
-An Acknowledgments page template is + +
The Definitions page is used to provide a list of definitions for terms + that a user may be unfamiliar with.
+ +The definition list should generally be constructed using an HTML
+ "definition list" (<dl> and <DT> tags). A definition list has
+ no bullets or ordered specifications and produces a cleaner layout then an
+ unordered list (<UL> and <li> tags) or an ordered list
+ (<ol> and <li> tags). If you choose to use the common Boost Style Sheet you should add a
+ class="definition" attribute/value pair to the <dl>
+ tag.
Because this page's content should only contain a list of definitions, + it should not have a Page Index.
+ +A Definitions page template is provided for use.
-The Header Reference pages are the most important pages in your documentation. - They document all library headers, including all the macros, values, types, - classes, functions and objects defined in them. In general it may prove useful - to follow the guidelines in Documentation Structure - when writing the content for these pages.
-Like most content pages, the Header Reference pages should include a Page - Index.
-A Header Reference page template is provided + +
The Rationale page is used to provide lengthy descriptions of the + rationale behind the library's design. This information helps users to + understand why a library was designed the way it was and may reduce the + frequency of a number of frequently asked questions. For a better + description of why rationale is important see the Rationale rationale + in the general submission guidelines.
+ +Like most content pages, the Rationale page should include a Page Index.
+ +A Rationale page template is provided for use.
-There are certain page layout concepts that will be used frequently in many - of your pages. This section outlines some general guidelines that you can follow - when designing each of these layout concepts for your documentation.
-The Page Banner is located at the very top of a page and provides quick information - about the page contents. This includes the Boost logo, which indicates to the - reader that this page is part of the Boost web site, a title for the documentation - (generally the library name) and the page title. The Boost logo should hyper - link to the Boost home page on the index page and to the index page on all other - pages. This allows the user to easily navigate through the Boost web site and - through the documentation. The <title> tag for the HTML page should consist - of the documentation title and the page title separated by a hyphen.
-The Page Banner should be separated from the rest of the page by the use of - an <hr> tag. This helps to clearly separate the actual content from the - title information and produces cleaner text.
-The page index is used to quickly navigate to the various sections of the documentation - on the page, and when present should be located just below the Page Banner.
-The index list should generally be constructed using an HTML "definition
- list" (<dl> and <DT> tags). A definition list has no bullets
- or ordered specifications and produces a cleaner layout then an unordered list
- (<UL> and <li> tags) or an ordered list (<ol> and <li>
- tags). If you choose to use the Boost Style Sheet you should add a class="page-index"
- attribute/value pair to the <dl> tag.
Most pages should include a Page Index.
-The page's actual documentation content will be formatted according to the - specific needs of individual pages, and should be placed right after the Page - Index if present, or after the Page Banner if not. In general the documentation - content will take the form of paragraph text contained underneath section headings.
-Footnotes may be used within a page's documentation. Within the documentation
- content a footnote reference should take the form of a footnote number in parentheses
- (the parentheses make it easier for the reader to click on the hyper link) hyper
- linking to the actual footnote at the bottom of the page's documentation content.
- You may either use the <sup> tag to format such footnote numbers, or,
- preferably, you can use a CSS style class in order to distinguish the number
- as a footnote instead of as part of the actual text. If you choose to use the
- common Boost Style Sheet, a footnote
+
+
The Configuration Information page is used to document configuration
+ macros used by the library. Such macros belong in one of three groups:
+ macros used by library implenters defined in
+ <boost/config.hpp>, macros used by library users to
+ detect platform configuration information and macros defined by library
+ users to configure library behavior.
Like most content pages, the Overview page should include a Page Index.
+ +A Configuration page template is + provided for use.
+ +As a library matures the users will have questions about the usage of + the library. Often users will ask the same questions over and over again. + Rather than having to deal with answering the question every time it's + asked, a Frequently Asked Questions (commonly known as FAQs) page can be + used to document the questions and answers. This is such a valuable piece + of documentation not only for the users but for the maintainers as well, + that a FAQ page should be provided from the outset. If there are no + questions that will obviously become a FAQ, the initial page may just + indicate that there are no FAQs yet. This empty place holder helps to + indicate to the users that you plan to address any FAQs as they occur.
+ +The Page Index for the FAQ page should contain + a list of all the questions contained in the document. The actual question + entries should be formatted with the question in a heading tag and the + answers in standard paragraph format. This provides a clean presentation + that's easy to read.
+ +A Frequently Asked Questions page template + is provided for use.
+ +The Bibliography page is used to document any bibliographical + information associated with references made within the documentation to + external resources. Parenthetical references are used within the + documentation which link to entries in the Bibliography page. + Bibliographical entries provide detailed information about the external + resource and may contain hyper links to the resource if it's available + online. There are several formal styles used for writing bibliographies. + You may use what ever style you want, but one of the better styles to + consider using can be referenced here.
+ +Since the Bibliography page should contain only bibliographical + information there is no need for a Page + Index.
+ +A Bibliography page template is + provided for use.
+ +The Acknowledgment page is used to give credit where credit is due. When + individuals provide input on the design or implementation, or when you make + use of someone else's work, you should acknowledge them. This is a courtesy + that you'd expect others to extend to you, so you should strive to + acknowledge the efforts of everyone else in your own documentation.
+ +Since the Acknowledgment page should contain only a list of + acknowledgment there is no need for a Page + Index.
+ +An Acknowledgments page template is provided for use.
+ +The Header Reference pages are the most important pages in your + documentation. They document all library headers, including all the macros, + values, types, classes, functions and objects defined in them. In general + it may prove useful to follow the guidelines in Documentation Structure when writing the content for + these pages.
+ +Like most content pages, the Header Reference pages should include a + Page Index.
+ +A Header Reference page template is + provided for use.
+ +There are certain page layout concepts that will be used frequently in + many of your pages. This section outlines some general guidelines that you + can follow when designing each of these layout concepts for your + documentation.
+ +The Page Banner is located at the very top of a page and provides quick + information about the page contents. This includes the Boost logo, which + indicates to the reader that this page is part of the Boost web site, a + title for the documentation (generally the library name) and the page + title. The Boost logo should hyper link to the Boost home page on the index + page and to the index page on all other pages. This allows the user to + easily navigate through the Boost web site and through the documentation. + The <title> tag for the HTML page should consist of the documentation + title and the page title separated by a hyphen.
+ +The Page Banner should be separated from the rest of the page by the use + of an <hr> tag. This helps to clearly separate the actual content + from the title information and produces cleaner text.
+ +The page index is used to quickly navigate to the various sections of + the documentation on the page, and when present should be located just + below the Page Banner.
+ +The index list should generally be constructed using an HTML "definition
+ list" (<dl> and <DT> tags). A definition list has no bullets or
+ ordered specifications and produces a cleaner layout then an unordered list
+ (<UL> and <li> tags) or an ordered list (<ol> and
+ <li> tags). If you choose to use the Boost Style Sheet you should add
+ a class="page-index" attribute/value pair to the <dl>
+ tag.
Most pages should include a Page Index.
+ +The page's actual documentation content will be formatted according to + the specific needs of individual pages, and should be placed right after + the Page Index if present, or after the Page Banner if not. In general the + documentation content will take the form of paragraph text contained + underneath section headings.
+ +Footnotes may be used within a page's documentation. Within the
+ documentation content a footnote reference should take the form of a
+ footnote number in parentheses (the parentheses make it easier for the
+ reader to click on the hyper link) hyper linking to the actual footnote at
+ the bottom of the page's documentation content. You may either use the
+ <sup> tag to format such footnote numbers, or, preferably, you can
+ use a CSS style class in order to distinguish the number as a footnote
+ instead of as part of the actual text. If you choose to use the common
+ Boost Style Sheet, a footnote
class is defined for this purpose.
At the bottom of every page should be some revision information indicating - when the page was last revised. This information should be separated from the - rest of the page above by an <hr> tag. The following HTML code snippet - can be used to track this revision information (this code uses some server components - that exist on the Boost web site to automatically track revision dates with - out the need for hand editing the date text):
-<hr> + +Revision + Information
+ +At the bottom of every page should be some revision information + indicating when the page was last revised. This information should be + separated from the rest of the page above by an <hr> tag. The + following HTML code snippet can be used to track this revision information + (this code uses some server components that exist on the Boost web site to + automatically track revision dates with out the need for hand editing the + date text):
++<hr> <p>Revised - <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> + <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> 01 January, 2001 - <!--webbot bot="Timestamp" endspan i-checksum="39359" --> + <!--webbot bot="Timestamp" endspan i-checksum="39359" --> </p>-Copyright Information
-The very bottom of the page should contain any copyright information that applies - to the document.
-Format
-This section provides general guidelines for formatting documentation using - HTML. The description of the various "common pages" gave specific - details for formatting specific sections of the documentation, which should + +
Copyright Information
+ +The very bottom of the page should contain any copyright information + that applies to the document.
+ +Format
+ +This section provides general guidelines for formatting documentation + using HTML. The description of the various "common pages" gave specific + details for formatting specific sections of the documentation, which should override these guidelines.
-Code
-Code within the documentation should be placed within either <code></code> - or <pre></pre> tags. For code that's placed inline with other text - you use <code></code> tags, while <pre></pre> tags are - used for code "blocks". If a cascading style sheet is used to specify - formatting for these tags, a fixed width sans serif font should be used. This - insures that the code is easily distinguishable from the rest of the text. It - may also be beneficial to set the style for <pre></pre> tags to - indent the text, to help separate code blocks from other structural HTML blocks. - The Boost Style Sheet specifies formatting - for these tags.
-Note: "Code" includes variable names, function names, etc.
-Lists
-Lists should be constructed as unordered (<UL> and <li> tags), - ordered (<ol> and <li> tags) or definition (<dl> and <DT> - tags) lists in HTML. You use an unordered list when you need a collection of - items that don't have any kind of logical ordering, such as a list of data types - that are defined by the library and can be used for a template argument. You - use an ordered list when the collection of items must be grouped in a logical - ordering, such as when enumerating the steps that an action logically performs. - You use a definition list when the list consists of not only items that have - no logical ordering, but also contains definitions/descriptions/etc. of the - items. A good example of this is the function specifications as described in - Documentation Structure.
-Graphics
-Graphics should be used very sparingly, if at all. Graphic images greatly effect - the download time for many people, which can discourage users from reading the - documentation. If you need graphic images to help illustrate something in your - documentation consider supplying only a link to the image within the documentation, - instead of embedding it directly in the text. If an image is going to be included - in the text of the document you should specify the image's size in the <img> - tag, in order to allow the user's browser to optimize the formatting of the - text before the image is loaded.
-Non-breaking Spaces
-Non-breaking spaces ( ) should be avoided in HTML text. Generally - there are more appropriate ways to format the document, such as using list constructs - or specifying indentation as a style attribute or in cascading style sheets.
-Cascading Style Sheets
-Cascading style sheets allow you to apply some advanced formatting styles to - an HTML document. More importantly, they allow you to change the formatting - in a single file and effect all pages using the style sheet. Instead of struggling - to produce a specific format in HTML it's often easier and more flexible to - specify the formatting in a style sheet.
-Boost Style Sheet
-The concept of using cascading style sheets to format HTML is such a good idea - that it can be beneficial to apply this across the entire Boost site. Of course - we can't require this (if Boost were to require such trivia for submissions - it's likely that many programmers would be discouraged from contributing). However, - a "standard" Boost style sheet (http://www.boost.org/boost.css) is - supplied anyway, so that a contributer can quickly and easily produce clear - and consistent documentation that reflects a Boost "brand" if they - so choose. If, at a later date, it's decided to update the Boost "brand", - it may be done in this single file and all documents using the style sheet will - automatically be updated.
-The Boost supplied style sheet not only specifies styles for many standard - tags, it also specifies several style "classes". A class is specified - for a given tag instead of being applied to all instances of a given tag type. - Below is a list of the classes specified in the Boost style sheet and a description - of when to use them:
-
Instead of hand coding every HTML page, HTML "templates" can be used instead. - The list below provides links to templates that may be used when writing documentation - for a contribution to Boost. Links provided in these templates assume the files - will reside in the "traditional" directory hierarchy of boost/libs/library/doc. - They may need correcting if the file will reside in some other location.
-Note: Since these "templates" are just HTML pages simply clicking - on the links below will load the template in your browser. You will need to - use a browser specific method to download the files instead of loading them - into the browser (for instance, on most Windows browsers you can right click - on the link and select the appropriate command from the context sensitive menu).
-Code within the documentation should be placed within either + <code></code> or <pre></pre> tags. For code that's + placed inline with other text you use <code></code> tags, while + <pre></pre> tags are used for code "blocks". If a cascading + style sheet is used to specify formatting for these tags, a fixed width + sans serif font should be used. This insures that the code is easily + distinguishable from the rest of the text. It may also be beneficial to set + the style for <pre></pre> tags to indent the text, to help + separate code blocks from other structural HTML blocks. The Boost Style Sheet specifies formatting for these + tags.
+ +Note: "Code" includes variable names, function names, etc.
+ +Lists should be constructed as unordered (<UL> and <li> + tags), ordered (<ol> and <li> tags) or definition (<dl> + and <DT> tags) lists in HTML. You use an unordered list when you need + a collection of items that don't have any kind of logical ordering, such as + a list of data types that are defined by the library and can be used for a + template argument. You use an ordered list when the collection of items + must be grouped in a logical ordering, such as when enumerating the steps + that an action logically performs. You use a definition list when the list + consists of not only items that have no logical ordering, but also contains + definitions/descriptions/etc. of the items. A good example of this is the + function specifications as described in Documentation Structure.
+ +Graphics should be used very sparingly, if at all. Graphic images + greatly effect the download time for many people, which can discourage + users from reading the documentation. If you need graphic images to help + illustrate something in your documentation consider supplying only a link + to the image within the documentation, instead of embedding it directly in + the text. If an image is going to be included in the text of the document + you should specify the image's size in the <img> tag, in order to + allow the user's browser to optimize the formatting of the text before the + image is loaded.
+ +Non-breaking spaces ( ) should be avoided in HTML text. + Generally there are more appropriate ways to format the document, such as + using list constructs or specifying indentation as a style attribute or in + cascading style sheets.
+ +Cascading style sheets allow you to apply some advanced formatting + styles to an HTML document. More importantly, they allow you to change the + formatting in a single file and effect all pages using the style sheet. + Instead of struggling to produce a specific format in HTML it's often + easier and more flexible to specify the formatting in a style sheet.
+ +The concept of using cascading style sheets to format HTML is such a + good idea that it can be beneficial to apply this across the entire Boost + site. Of course we can't require this (if Boost were to require such trivia + for submissions it's likely that many programmers would be discouraged from + contributing). However, a "standard" Boost style sheet + (http://www.boost.org/boost.css) is supplied anyway, so that a contributer + can quickly and easily produce clear and consistent documentation that + reflects a Boost "brand" if they so choose. If, at a later date, it's + decided to update the Boost "brand", it may be done in this single file and + all documents using the style sheet will automatically be updated.
+ +The Boost supplied style sheet not only specifies styles for many + standard tags, it also specifies several style "classes". A class is + specified for a given tag instead of being applied to all instances of a + given tag type. Below is a list of the classes specified in the Boost style + sheet and a description of when to use them:
+ +Instead of hand coding every HTML page, HTML "templates" can be used + instead. The list below provides links to templates that may be used when + writing documentation for a contribution to Boost. Links provided in these + templates assume the files will reside in the "traditional" directory + hierarchy of boost/libs/library/doc. They may need correcting if the + file will reside in some other location.
+ +Note: Since these "templates" are just HTML pages simply clicking + on the links below will load the template in your browser. You will need to + use a browser specific method to download the files instead of loading them + into the browser (for instance, on most Windows browsers you can right + click on the link and select the appropriate command from the context + sensitive menu).
+ +Revised - 29 November, 2003 -
-© Copyright William E. Kempf - 2001. All Rights Reserved.
+ +Revised + 04 + December, 2006
+ +Copyright © 2001 William E. Kempf
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)
- \ No newline at end of file + diff --git a/writingdoc/index.html b/writingdoc/index.html index d1cf7a4..869c590 100644 --- a/writingdoc/index.html +++ b/writingdoc/index.html @@ -1,36 +1,57 @@ + + - - -|
- |
-
- Writing Documentation for Boost-Index- |
-
Revised - - 05 November, 2001 - -
-© Copyright William E. Kempf - 2001. All Rights Reserved.
+ + +|
+ |
+
+
+ Writing Documentation for Boost+ +Index+ |
+
Revised + 04 + December, 2006
+ +Copyright © 2001 William E. Kempf
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)
diff --git a/writingdoc/introduction.html b/writingdoc/introduction.html index f3ae895..29f737b 100644 --- a/writingdoc/introduction.html +++ b/writingdoc/introduction.html @@ -1,46 +1,68 @@ + + - - -|
- |
-
- Writing Documentation for Boost-Introduction- |
-
Boost does not have any requirements on how you write your documentation. If - you are submitting a library that already has written documentation in HTML - format, there is no reason to change it to follow any of the guidelines presented - here. However, if you have documentation that's not in HTML format and can't - be easily converted to HTML, or if you're starting on a library from scratch - or have a library with no documentation then these guidelines can make writing - the documentation much easier.
-The section on Documentation Structure describes - how to go about structuring the documentation's content. This section may be - helpful even for libraries that already have documentation. If there's a desire - to present the library for possible inclusion by the C++ Standards Committee - then there may be a need to restructure the documentation's content in order - to insure the content meets explicit requirements for library components (Section - 17.3).
-The section on HTML Design gives general rules to - follow when writing HTML documentation in order to give a professional and consistent - look. This section also contains some template files that can be used to rapidly - create documentation pages.
-Revised - 29 November, 2003 -
-© Copyright William E. Kempf - 2001. All Rights Reserved.
+ + +|
+ |
+
+
+ Writing Documentation for Boost+ +Introduction+ |
+
Boost does not have any requirements on how you write your + documentation. If you are submitting a library that already has written + documentation in HTML format, there is no reason to change it to follow any + of the guidelines presented here. However, if you have documentation that's + not in HTML format and can't be easily converted to HTML, or if you're + starting on a library from scratch or have a library with no documentation + then these guidelines can make writing the documentation much easier.
+ +The section on Documentation Structure + describes how to go about structuring the documentation's content. This + section may be helpful even for libraries that already have documentation. + If there's a desire to present the library for possible inclusion by the + C++ Standards Committee then there may be a need to restructure the + documentation's content in order to insure the content meets explicit + requirements for library components (Section 17.3).
+ +The section on HTML Design gives general rules + to follow when writing HTML documentation in order to give a professional + and consistent look. This section also contains some template files that + can be used to rapidly create documentation pages.
+Revised + 04 + December, 2006
+ +Copyright © 2001 William E. Kempf
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)
- \ No newline at end of file + diff --git a/writingdoc/structure.html b/writingdoc/structure.html index 2429a12..d3783fc 100644 --- a/writingdoc/structure.html +++ b/writingdoc/structure.html @@ -1,254 +1,433 @@ + + - - -|
- |
-
- Writing Documentation for Boost-Documentation Structure- |
-
|
+ |
+
+
+ Writing Documentation for Boost+ +Documentation Structure+ |
+
Boost itself does not require any specific documentation structure. The C++ - Standard, however, has very explicit requirements for the description of library - components (Section 17.3). So for Boost libraries likely to be proposed for - inclusion in the standard, it is highly desirable to structure documentation - in a way that meets the requirements of the the standard. Doing so eliminates - the need to rewrite the documentation for standardization.
-Library developers should remember that for a library to be accepted as part - of the C++ Standard Library, the proposal must include full wording. The committee - will not do that work for you.
-Beyond that, the documentation structure required for the standard is an effective - way to communicate the technical specifications for a library. Although terse, - it is already familiar to many Boost users, and is far more precise than most - ad hoc documentation structures.
-The following description is for the structure of documentation required by - the standard. Boost libraries should also provided additional documentation, - such as introductory, tutorial, example, and rationale material.
-Each document contains the following elements, as applicable(1):
-The Summary provides a synopsis of the category, and introduces the first-level - subclauses. Each subclause also provides a summary, listing the headers specified - in the subclause and the library entities provided in each header.
-Paragraphs labeled "Note(s):" or "Example(s):" are informative, other paragraphs - are normative.
-The summary and the detailed specifications are presented in the order:
-The library can be extended by a C++ program. Each clause, as applicable, describes - the requirements that such extensions must meet. Such extensions are generally - one of the following:
-Interface convention requirements are stated as generally as possible. Instead
- of stating "class X has to define a member function operator++(),"
- the interface requires "for any object x of class X,
- ++x is defined." That is, whether the operator is a member is unspecified.
Requirements are stated in terms of well-defined expressions, which define - valid terms of the types that satisfy the requirements. For every set of requirements - there is a table that specifies an initial set of the valid expressions and - their semantics. Any generic algorithm that uses the requirements is described - in terms of the valid expressions for its formal type parameters.
-Template argument requirements are sometimes referenced by name.
-In some cases the semantic requirements are presented as C++ code. Such code - is intended as a specification of equivalance of a construct to another construct, - not necessarily as the way the construct must be implemented.(2)
-The detailed specifications each contain the following elements:
-Descriptions of class member functions follow the order (as appropriate)(3):
-Descriptions of function semantics contain the following elements - (as appropriate)(4):
-Boost itself does not require any specific documentation structure. The + C++ Standard, however, has very explicit requirements for the description + of library components (Section 17.3). So for Boost libraries likely to be + proposed for inclusion in the standard, it is highly desirable to structure + documentation in a way that meets the requirements of the the standard. + Doing so eliminates the need to rewrite the documentation for + standardization.
+ +Library developers should remember that for a library to be accepted as + part of the C++ Standard Library, the proposal must include full wording. + The committee will not do that work for you.
+ +Beyond that, the documentation structure required for the standard is an + effective way to communicate the technical specifications for a library. + Although terse, it is already familiar to many Boost users, and is far more + precise than most ad hoc documentation structures.
+ +The following description is for the structure of documentation required + by the standard. Boost libraries should also provided additional + documentation, such as introductory, tutorial, example, and rationale + material.
+ +Each document contains the following elements, as applicable(1):
+ +The Summary provides a synopsis of the category, and introduces the + first-level subclauses. Each subclause also provides a summary, listing the + headers specified in the subclause and the library entities provided in + each header.
+ +Paragraphs labeled "Note(s):" or "Example(s):" are informative, other + paragraphs are normative.
+ +The summary and the detailed specifications are presented in the + order:
+ +The library can be extended by a C++ program. Each clause, as + applicable, describes the requirements that such extensions must meet. Such + extensions are generally one of the following:
+ +Interface convention requirements are stated as generally as possible.
+ Instead of stating "class X has to define a member function
+ operator++()," the interface requires "for any object
+ x of class X, ++x is defined." That
+ is, whether the operator is a member is unspecified.
Requirements are stated in terms of well-defined expressions, which + define valid terms of the types that satisfy the requirements. For every + set of requirements there is a table that specifies an initial set of the + valid expressions and their semantics. Any generic algorithm that uses the + requirements is described in terms of the valid expressions for its formal + type parameters.
+ +Template argument requirements are sometimes referenced by name.
+ +In some cases the semantic requirements are presented as C++ code. Such + code is intended as a specification of equivalance of a construct to + another construct, not necessarily as the way the construct must be + implemented.(2)
+ +The detailed specifications each contain the following elements:
+ +Descriptions of class member functions follow the order (as + appropriate)(3):
+ +Descriptions of function semantics contain the following elements (as + appropriate)(4):
+ +Complexity requirements specified in the library clauses are upper bounds, - and implementations that provide better complexity guarantees satisfy the requirements.
-These conventions are for describing implementation-defined types, and member - functions.
-The Requirements subclauses may describe names that are used to specify constraints - on template arguments.
-The function semantic element description above - is taken directly from the C++ standard, and is quite terse. Here is a more - detailed explanation of each of the elements.
-Note the use of the <code> ... </code> font tag to
- distinguish actual C++ usage from English prose.
Preconditions for calling the function, typically expressed as predicates. - The most common preconditions are requirements on the value of arguments, often - in the form of C++ expressions. For example, -
+ +
Complexity requirements specified in the library clauses are upper + bounds, and implementations that provide better complexity guarantees + satisfy the requirements.
+ +These conventions are for describing implementation-defined types, and + member functions.
+ +The Requirements subclauses may describe names that are used to specify + constraints on template arguments.
+ +The function semantic element description above is taken directly from the C++ standard, and + is quite terse. Here is a more detailed explanation of each of the + elements.
+ +Note the use of the <code> ... </code> font tag
+ to distinguish actual C++ usage from English prose.
Preconditions for calling the function, typically expressed as + predicates. The most common preconditions are requirements on the value of + arguments, often in the form of C++ expressions. For example,
+
+
void limit( int * p, int min, int max );
-p != 0 && min <= maxRequirements already enforced by the C++ language rules (such as the type of - arguments) are not repeated in Requires paragraphs.
-The actions performed by the function, described either in prose or in C++. - A description in prose is often less limiting on implementors, but is often - less precise than C++ code.
-If an effect is specified in one of the other elements, particularly postconditions, - returns, or throws, it is not also described in the effects - paragraph. Having only a single description ensures that there is one and only - one specification, and thus eliminates the risk of divergence.
-The observable results of the function, such as the value of variables. Postconditions - are often expressed as predicates that are true after the function completes, - in the form of C++ expressions. For example:
-+ +
p != 0 && min <= maxRequirements already enforced by the C++ language rules (such as the + type of arguments) are not repeated in Requires paragraphs.
+ +The actions performed by the function, described either in prose or in + C++. A description in prose is often less limiting on implementors, but is + often less precise than C++ code.
+ +If an effect is specified in one of the other elements, particularly + postconditions, returns, or throws, it is not also + described in the effects paragraph. Having only a single description + ensures that there is one and only one specification, and thus eliminates + the risk of divergence.
+ +The observable results of the function, such as the value of variables. + Postconditions are often expressed as predicates that are true after the + function completes, in the form of C++ expressions. For example:
++ void make_zero_if_negative( int & x );-
x >= 0The value returned by the function, usually in the form of a C++ expression. - For example:
-int sum( int x, int y ); + +
x >= 0The value returned by the function, usually in the form of a C++ + expression. For example:
++int sum( int x, int y );-
x + yOnly specify the return value; the type is already dictated by C++ language - rules. -
Specify both the type of exception thrown, and the condition that causes the
- exception to be thrown. For example, the std::basic_string class
- specifies:
-
+ +
x + yOnly specify the return value; the type is already dictated by C++ + language rules.
+ +Specify both the type of exception thrown, and the condition that causes
+ the exception to be thrown. For example, the std::basic_string
+ class specifies:
+ void resize(size_type n, charT c);-
length_error if n > max_size().Specifying the time and/or space complexity of a function is often not desirable - because it over-constrains implementors and is hard to specify correctly. Complexity - is thus often best left as a quality of implementation issue.
-A library component, however, can become effectively non-portable if there - is wide variation in performance between conforming implementations. Containers - are a prime example. In these cases it becomes worthwhile to specify complexity.
-Complexity is often specified in generalized - "Big-O" notation.
-Specifying the rationale for a function's design or existence can often give users - a lot of insight into why a library is designed the way it is. More importantly, it - can help prevent "fixing" something that wasn't really broken as the library matures.
-length_error if n >
+ max_size().Specifying the time and/or space complexity of a function is often not + desirable because it over-constrains implementors and is hard to specify + correctly. Complexity is thus often best left as a quality of + implementation issue.
+ +A library component, however, can become effectively non-portable if + there is wide variation in performance between conforming implementations. + Containers are a prime example. In these cases it becomes worthwhile to + specify complexity.
+ +Complexity is often specified in generalized "Big-O" + notation.
+ +Specifying the rationale for a function's design or existence can often + give users a lot of insight into why a library is designed the way it is. + More importantly, it can help prevent "fixing" something that wasn't really + broken as the library matures.
+ +Revised - 29 November, 2003 -
-© Copyright William E. Kempf - 2001. All Rights Reserved.
+ +Revised + 04 + December, 2006
+ +Copyright © 2001 William E. Kempf
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)
- \ No newline at end of file + diff --git a/writingdoc/template/acknowledgments.html b/writingdoc/template/acknowledgments.html index 90556b0..bfb9e5d 100644 --- a/writingdoc/template/acknowledgments.html +++ b/writingdoc/template/acknowledgments.html @@ -1,31 +1,48 @@ + + - - -|
- |
-
- {{Library}}-Acknowledgments- |
-
Revised - - 05 November, 2001 - -
-© Copyright {{author}} - 2002. All Rights Reserved.
+ + +|
+ |
+
+
+ {{Library}}+ +Acknowledgments+ |
+
Revised + 04 + December, 2006
+ +Copyright © 2006 {{author}}
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)
diff --git a/writingdoc/template/bibliography.html b/writingdoc/template/bibliography.html index 5faed0b..c824b07 100644 --- a/writingdoc/template/bibliography.html +++ b/writingdoc/template/bibliography.html @@ -1,31 +1,48 @@ + + - - -|
- |
-
- {{Library}}-Bibliography- |
-
Revised - - 05 November, 2001 - -
-© Copyright {{author}} - 2002. All Rights Reserved.
+ + +|
+ |
+
+
+ {{Library}}+ +Bibliography+ |
+
Revised + 04 + December, 2006
+ +Copyright © 2006 {{author}}
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)
diff --git a/writingdoc/template/configuration.html b/writingdoc/template/configuration.html index edf2216..6eaebf0 100644 --- a/writingdoc/template/configuration.html +++ b/writingdoc/template/configuration.html @@ -1,90 +1,145 @@ + + - - -|
- |
-
- {{Library}}-Configuration- |
-
{{library}} uses several configuration macros in <boost/config.hpp>, - as well as configuration macros meant to be supplied by the application. These - macros are documented here.
-These are the macros that may be defined by an application using {{library}}.
-| Macro | -Meaning | -
| {{macro}} | -{{meaning}} | -
| {{macro}} | -{{meaning}} | -
These macros are defined by {{library}} but are expected to be used by application - code.
-| Macro | -Meaning | -
| {{macro}} | -{{meaning}} | -
| {{macro}} | -{{meaning}} | -
These macros are defined by {{library}} and are implementation details of interest - only to implementers.
-| Macro | -Meaning | -
| {{macro}} | -{{meaning}} | -
| {{macro}} | -{{meaning}} | -
Revised - - 05 November, 2001 - -
-© Copyright {{author}} - 2002. All Rights Reserved.
+ + +|
+ |
+
+
+ {{Library}}+ +Configuration+ |
+
{{library}} uses several configuration macros in <boost/config.hpp>, + as well as configuration macros meant to be supplied by the application. + These macros are documented here.
+ +These are the macros that may be defined by an application using + {{library}}.
+ +| Macro | + +Meaning | +
| {{macro}} | + +{{meaning}} | +
| {{macro}} | + +{{meaning}} | +
These macros are defined by {{library}} but are expected to be used by + application code.
+ +| Macro | + +Meaning | +
| {{macro}} | + +{{meaning}} | +
| {{macro}} | + +{{meaning}} | +
These macros are defined by {{library}} and are implementation details + of interest only to implementers.
+ +| Macro | + +Meaning | +
| {{macro}} | + +{{meaning}} | +
| {{macro}} | + +{{meaning}} | +
Revised + 04 + December, 2006
+ +Copyright © 2006 {{author}}
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)
diff --git a/writingdoc/template/definitions.html b/writingdoc/template/definitions.html index 08fff59..25b22d5 100644 --- a/writingdoc/template/definitions.html +++ b/writingdoc/template/definitions.html @@ -1,47 +1,78 @@ + + - - -|
- |
-
- {{Library}}-Definitions- |
-
|
+ |
+
+
+ {{Library}}+ +Definitions+ |
+
{{Introductory text}}
-Revised - - 05 November, 2001 - -
-© Copyright {{author}} - 2002. All Rights Reserved.
+{{Introductory text}}
+ +Revised + 04 + December, 2006
+ +Copyright © 2006 {{author}}
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)
diff --git a/writingdoc/template/faq.html b/writingdoc/template/faq.html index 82773d9..3133fae 100644 --- a/writingdoc/template/faq.html +++ b/writingdoc/template/faq.html @@ -1,38 +1,61 @@ + + - - -|
- |
-
- {{Library}}-Frequently Asked Questions (FAQs)- |
-
{{answer}}
-{{answer}}
-Revised - - 05 November, 2001 - -
-© Copyright {{author}} - 2002. All Rights Reserved.
+ + +|
+ |
+
+
+ {{Library}}+ +Frequently Asked Questions (FAQs)+ |
+
{{answer}}
+ +{{answer}}
+Revised + 04 + December, 2006
+ +Copyright © 2006 {{author}}
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)
diff --git a/writingdoc/template/header.html b/writingdoc/template/header.html index 201c198..e16500d 100644 --- a/writingdoc/template/header.html +++ b/writingdoc/template/header.html @@ -1,195 +1,346 @@ + + - - -|
- |
-
- {{library}}-Header <{{header}}>- |
-
|
+ |
+
+
+ {{library}}+ +Header <{{header}}>+ |
+
{{class name}}{{class name}}{{Introductory text}}
-{{class name}}{{class overview text}}
-{{class name}} synopsis+
+ +Introduction
+ +{{Introductory text}}
+ +Macros
+ + + +Values
+ + + +Types
+ + + +Classes
+ +Class
+ +{{class + name}}{{class overview text}}
+ +Class +
+{{class name}}synopsisnamespace boost { class {{class name}} - { - }; + { + }; };-Class
-{{class name}}constructors and destructor+ +Class +
+{{class name}}constructors and destructor{{constructor}}-
+ +
{{destructor}}
-{{class name}} comparison functions+ +
{{class name}} comparison functions
{{function}}
-{{class name}} modifier functions+ +
{{class name}} modifier functions
{{function}}
-{{class name}} observer functions+ +
{{class name}} observer functions
{{function}}
-{{class name}} static functions+ +
{{class name}} static functions
{{function}}
--{{function}} + +
+{{function}}-
{{Example(s)}}
-Revised - - 05 November, 2001 - -
-© Copyright {{author}} - 2002. All Rights Reserved.
+ +{{Example(s)}}
+Revised + 04 + December, 2006
+ +Copyright © 2006 {{author}}
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)
diff --git a/writingdoc/template/index.html b/writingdoc/template/index.html index fe5bb0d..e360ab3 100644 --- a/writingdoc/template/index.html +++ b/writingdoc/template/index.html @@ -1,70 +1,126 @@ + + - - -|
- |
-
- {{Library}}-Index- |
-
|
+ |
+
+
+ {{Library}}+ +Index+ |
+
Revised - - 05 November, 2001 - -
-© Copyright {{author}} - 2002. All Rights Reserved.
+Revised + 04 + December, 2006
+ +Copyright © 2006 {{author}}
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)
diff --git a/writingdoc/template/overview.html b/writingdoc/template/overview.html index 742afc8..c931bc5 100644 --- a/writingdoc/template/overview.html +++ b/writingdoc/template/overview.html @@ -1,47 +1,79 @@ + + - - -|
- |
-
- {{Library}}-Overview- |
-
{{text}}
-{{text}}
-{{text}}
-Revised - - 05 November, 2001 - -
-© Copyright {{author}} - 2002. All Rights Reserved.
+ + +|
+ |
+
+
+ {{Library}}+ +Overview+ |
+
{{text}}
+ +{{text}}
+ +{{text}}
+ +Revised + 04 + December, 2006
+ +Copyright © 2006 {{author}}
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)
diff --git a/writingdoc/template/rationale.html b/writingdoc/template/rationale.html index 3476928..bb450a0 100644 --- a/writingdoc/template/rationale.html +++ b/writingdoc/template/rationale.html @@ -1,47 +1,79 @@ + + - - -|
- |
-
- {{Library}}-Rationale- |
-
{{text}}
-{{text}}
-{{text}}
-Revised - - 05 November, 2001 - -
-© Copyright {{author}} - 2002. All Rights Reserved.
+ + +|
+ |
+
+
+ {{Library}}+ +Rationale+ |
+
{{text}}
+ +{{text}}
+ +{{text}}
+ +Revised + 04 + December, 2006
+ +Copyright © 2006 {{author}}
+ +Distributed under the Boost Software License, Version 1.0. (See + accompanying file LICENSE_1_0.txt or + copy at http://www.boost.org/LICENSE_1_0.txt)