November 2005 - Boost - lists.preview.boost.org

Documentation Wizard
by Rob Stewart 05 Nov '05

05 Nov '05

Quite some time ago, Dave Abrahams announced that I was the new Boost Documentation Wizard. I said I'd write something on the subject and that is long overdue. Herewith, I describe what I think the DocWiz should do and what is needed from volunteers to make it happen. That is, I'm trying to document the new DocWiz role and solicit your help. Please have a look and comment on what I'm proposing. If you don't like the direction I'm planning, say so. If you think I've missed something, let me know. If you think you can help in some way, please let me know; I can't do the job alone. The DocWiz's purpose is to try to foster better documentation for Boost. Since this is something new at Boost, some measures will be grandfathered* of necessity, while others will likely be retrofitted to existing documentation. Some things will be purely stylistic, but most will be substantive. A significant problem with writing library documentation is that English is often not the library author's primary language.* It is all too common that those who can write C++ fluently cannot write English well. Thus, we need a means to ensure that the library author's ideas are well communicated. Another problem with writing library documentation is knowing what to write. How much detail is sufficient? How many code examples should there be? How much material should be relegated to a reference section and how much should be presented in a tutorial? What is a sufficient rationale for the library? Many of these issues can be addressed by seeking insight from what has been written well already and by seeking advice from those expert on the tasks. From that information we can capture best practices to assist new documentation authors. Still another problem is consistency. As Boost grows, having a reasonably consistent look and feel to our documentation becomes increasingly important. Naming and organizing sections in our documentation must be consistent across libraries to simplify locating desired information in each library. Given the rate at which new libraries are proposed, I cannot do this task alone. I'm the father of eight (yes, 8!) children (so far, at least), I have a full time job, etc. Like everyone else, I'm quite busy. Thus, I need help. I intend to be the manager of a group of folks who can divide the workload to make it manageable. To that end, I propose the following positions to assist in improving the state of Boost documentation: Editors - Folks with demonstrably good English skills who can assist library authors by clarifying and correcting the documentation at various times, as determined by the author, so the meaning is clear. Editors also advice the author on structural changes necessary to conform to Boost guidelines. Editors are not so much concerned with content as with clear communication of what is included. Domain Experts*** - Folks with special skills in writing certain types of documentation such as concepts or tutorials; when a library author is struggling to write a portion of the library's documentation, the author can call upon the appropriate domain expert for assistance. Mentors - Folks with skills and desire to write good documentation who can come alongside a new library author to ghost write, share writing tasks, suggest content, etc. The output from author/mentor collaboration must still be approved by an editor. The workload of an editor will be varied since the number of authors writing documentation varies and based upon their update schedules. The workload of a domain expert should be quite low as folks writing concept descriptions, for example, should not need a domain expert's input often or long. The workload of a mentor likely will be as high as the mentor wishes. Initially, anyone acting as an editor will need to prove his/her skills by relying on trusted editors to proof the results. Once proven, a new editor can act autonomously. The expected result of this group of folks is documentation that is acceptable to Boost. I propose that a library cannot be fully accepted by Boost without the DocWiz's approval. IOW, a library can be conditionally accepted pending documentation approval. (That approval may be given based solely upon the word of a trusted editor; the DocWiz needn't read every document to give approval, but the responsibility does lie with the DocWiz for deficient approved documentation.) Note that the DocWiz is not the final authority on what is acceptable documentation. Users of that documentation are. An author will likely need to update documentation based upon user experience. Such changes should be subject to an editorial review, too, in order to maintain high standards. -------- * That means that existing documentation needn't be changed to conform to new policies, but may be if the author chooses. ** Another problem is that English *is* the library author's primary language. :) *** The name "domain expert" smacks too much of someone who is expert in the domain of the library rather than of a particular aspect of library documentation. Please suggest a better name. -- Rob Stewart stewart(a)sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;

6 6

Re: [boost] [ANN] Phoenix-2 prerelease
by David Abrahams 05 Nov '05

05 Nov '05

Joel de Guzman <joel(a)boost-consulting.com> writes: > Comments, feedback very welcome! > Organization > > Care and attention to detail was given, painstakingly, to the design > and implementation of Phoenix. The overall design of the library is > well structured and clean. Remarks like the last one usually cause me to be more suspicious of, than confident in, a library design. I suggest you strike it. > The library is organized in four layers: > > The modules are completely orthogonal. I'm not sure what that means. If you're going to say it, you should explain it. > The relationship between the > layers is totally acyclic. "The modules are orthogonal, with no cyclic dependencies" http://www.asne.org/index.cfm?ID=4364 > Lower layers do not depend nor know the > existence of higher layers. "Lower layers do not depend on higher layers." http://www.asne.org/index.cfm?ID=4364 > Modules in a layer do not depend on > other modules in the same layer. Wonderful! > This means for example that the > client can completely discard Bind if she does not need it; or ^ that should be a comma > perhaps take out Operator and Statement and just use Function, which ^^^^^^^^^^^^ "she can leave" > is desireable in a pure FP application. ^^ "would be" > > The library has grown from the original Phoenix but still comprises > of only header files. There are no object files to link against. ^^ strike > Core > > The lowest two layers comprise the core. > > The Actor is the main concept behind the library. Lazy functions are > abstracted as actors which are actually polymorphic functors. That is one scary sentence. Can you simplify it? What are you really trying to say? > There are only 2 kinds of actors: > > 1. Primitives > 2. Composites > > Composites are composed of zero or more actors. Each actor in a > composite can again be another composite. Primitives are atomic > units and are not decomposable. Again, what does "decomposable" mean? > Modules > > Module Description > > Function Lazy functions support (e.g. add) > > Operator Lazy operators support (e.g. +) > > Statement Lazy statments (e.g. if_, while_) > > Object Lazy casts (e.g. static_cast_), object creation > destruction (e.g. new_, delete_) > Scope Support for scopes, local variables and lambda-lambda "lambda-lambda?" > Bind Lazy functions from simple monomorphic, plain functions, ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Can't you say this with 1 or 2 words instead of 4? > member functions or member variables for deferred evaluation. ^^^^^^^^^^^^^^^^ "data members" What does "for deferred evaluation" add here? > Intrinsic Set of predefined "lazy" functions that work on STL ^^^^^^ strike > containers and sequences (e.g. push_back). I would call that module "container." It isn't the intrinsics of the phoenix library, but of the STL container library. > Algorithm Set of predefined "lazy" versions of the STL ^^^^^^ strike. > algorithms (e.g. find_if). > Includes > Module File > Core #include <boost/spirit/phoenix/core.hpp> > Function #include <boost/spirit/phoenix/function.hpp> > Operator #include <boost/spirit/phoenix/operator.hpp> > Statement #include <boost/spirit/phoenix/statement.hpp> > Object #include <boost/spirit/phoenix/object.hpp> > Scope #include <boost/spirit/phoenix/scope.hpp> > Bind #include <boost/spirit/phoenix/bind.hpp> > Intrinsic #include <boost/spirit/phoenix/intrinsic.hpp> > Algorithm #include <boost/spirit/phoenix/algorithm.hpp> At this point in the docs you'd do better to write it in English: Each module is defined in a header with the same base name. So for example, the core module is in <boost/spirit/phoenix/core>. > Finer grained include files are available per feature. See the ^ a semicolon would be good here > succeeding sections. -- Dave Abrahams Boost Consulting www.boost-consulting.com

3 2

Gender neutral documentation (was RE: [ANN] Phoen ix-2 prerelease)
by Martin Bonner 05 Nov '05

05 Nov '05

David Abrahams <dave(a)boost-consulting.com> writes: > Joel de Guzman <joel(a)boost-consulting.com> writes: >> This means for example that the >> client can completely discard Bind if she does not need it; or > ^ > that should be a comma > >> perhaps take out Operator and Statement and just use Function, which > ^^^^^^^^^^^^ > "she can leave" Is there a boost convention on gender neutral language? I approve of the sentiment behind using "she" (there aren't enough women in technical roles), but I do find myself stumbling every time I read it. My personal preference is to use "they" as the first person singular gender-neutral pronoun. This will be /intensely/ irritating to grammar purists, but does seem to be the way the language is evolving. -- Martin Bonner Martin.Bonner(a)Pitechnology.com Pi Technology, Milton Hall, Ely Road, Milton, Cambridge, CB4 6WZ, ENGLAND Tel: +44 (0)1223 441434

7 8

Boost File Vault broken
by Jose 04 Nov '05

04 Nov '05

http://www.boost-consulting.com/vault/ The html in the page is broken (see near search box). Also, the site is incredibly slow (either the website or the PHP pages) Can anybody fix this ?

3 4

Re: [boost] [ANN] Phoenix-2 prerelease (supported operators)
by David Abrahams 04 Nov '05

04 Nov '05

Joel de Guzman <joel(a)boost-consulting.com> writes: > Comments, feedback very welcome! > Supported operators Style tip: every section should have some introductory text before its first subsection. Every subsection should have at least one sibling. > Unary operators > > prefix: ~, !, -, +, ++, --, & (reference), * (dereference) > postfix: ++, -- > > Binary operators > > =, [], +=, -=, *=, /=, %=, &=, |=, ^=, <<=, >>= > +, -, *, /, %, &, |, ^, <<, >> > ==, !=, <, >, <=, >= > &&, ||, ->* > > Ternary operator > > if_else(c, a, b) > > The ternary operator deserves special mention. Since C++ does not > allow us to overload the conditional expression: c ? a : b, the > if_else pseudo function is provided for this purpose. The behavior > is identical, albeit in a lazy manner. Does it deserve special support? Why not just use if_(c)[a].else[b] ? > Member pointer operator > > a->*member_object_pointer > a->*member_function_pointer > > The left hand side of the member pointer operator must be an actor > returning a pointer type. The right hand side of the member pointer > operator may be either a pointer to member object or pointer to > member function. > > > If the right hand side is a member object pointer, the result is a > composite providing lazy access to that member. "an actor that, when invoked, returns a reference to that member." > For example: > > struct A > { > int member; > }; > > A* a = new A; > ... > > (arg1->*&A::member)(a); // returns member a->member > > If the right hand side is a member function pointer, the result is a > delayed function call. The arguments to this call are then bound to > the returned composite. The wording is confusing. "Delayed function call" has not been defined. Why not just say that "the result is an actor that, when invoked, calls the specified member function?" Is that inaccurate? -- Dave Abrahams Boost Consulting www.boost-consulting.com

2 1

Re: [boost] [ANN] Phoenix-2 prerelease (Operators)
by David Abrahams 04 Nov '05

04 Nov '05

Joel de Guzman <joel(a)boost-consulting.com> writes: > Comments, feedback very welcome! > Operator > > Lazy operators... ^^^^^^^^^^^^^^^^^ What is this doing here? What is the ellipsis for? > This facility provides a mechanism for lazily evaluating > operators. Syntactically, a lazy operator looks and feels like an > ordinary C/C++ infix, prefix or postfix operator. The operator > application looks the same. However, unlike ordinary operators, the > actual operator execution is deferred. Samples: > > arg1 + arg2 > 1 + arg1 * arg2 > 1 / -arg1 > arg1 < 150 > > We have seen the lazy operators in action (see Quick Start). Let's > go back and examine it a little bit further: ^^ "them" > > find_if(c.begin(), c.end(), arg1 % 2 == 1) > > Through operator overloading, the expression arg1 % 2 == 1 actually > generates a composite. The fact that it's a composite (as opposed to a primitive) is of no interest at all to the user at this point. I would say "a function object" or "an actor." There's way too much emphasis on this whole composite/primitive distinction. > This composite object is passed on to STL's > find_if function. This is a place where you really see how not using any qualification hurts. Should be std::find_if, to distinguish it from the library's lazy find_if that can be passed to higher-order functions. > In the viewpoint of STL, the composite is simply a ^^ "From" > function object expecting a single argument > , the container's element. ^^^^^^^^^^^^^^^^^^^^^^^ "of the container's value_type." > For each element in the container c, the element is passed ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ "Each element in c" > on as an argument arg1 to the composite (function object). The ^^^^ strike. That is not the name of the argument. > composite checks if this is an odd value based on the expression > arg1 % 2 == 1 where arg1 is iteratively replaced by the container's ^^^^^^^^^^^ ??? > element. > > A set of classes implement all the C++ free operators. ^^^^^^^ Really, the operators are implemented by a set of classes? Seems bizarre. Also seems irrelevant to the reader. > Like lazy functions (see function), lazy operators are not > immediately executed when invoked. Instead, a composite (see > composite) object is created and returned to the caller. Example: > > (arg1 + arg2) * arg3 > > does nothing more than return a composite. A second function call will evaluate the actual operators. Example: > > int i = 4, j = 5, k = 6; > cout << ((arg1 + arg2) * arg3)(i, j, k); > > will print out "54". > > Arbitrarily complex expressions can be lazily evaluated following > three simple rules: That sentence doesn't make sense to me. "Can be" would apply to what the user can do, but the rules describe what the library does. Maybe "...are lazily evaluated according to these three rules:" I'm not sure that "Arbitrarily complex" adds anything. It would make sense in the context of what the user can do: "Arbitrarily complex epressions can be made lazy by following..." but then, that's incompatible with what follows. > 1. Lazy evaluated binary operators apply when at least one of the > operands is an actor object (see actors, primitives and > composite). Consequently, if one of the operands is not an actor > object, it is implicitly converted, by default, to a value (see > values). > 2. Lazy evaluated unary operators apply only to operands which > are actor objects. > 3. The result of a lazy operator is a composite actor object that > can in turn apply to rule 1 and 2. The actor applies to the rules, or the rules apply to the actor? This may seem like nitpicking, but the above can only make sense if you already know what it's saying, because you'll overlook the logical inconsistencies. It won't help the person who's trying to understand the library from the outside. > The one exception is the member pointer operator ->*, as we shall > see later. As long as you're spelling out the rules in detail, you should add the one exception immediately, so the user can read them all in one place. > Example: > > -(arg1 + 3 + 6) > > 1. Following rule 1, lazy evaluation is triggered since arg1 is > an actor (see primitives). You have to say what part of the expression is being evaluated! In this case, arg1 + 3 > 2. The immediate right operand: 3 is implicitly converted to a > value. Still following rule 1. > > 3. The result of this arg1 + 3 expression is a composite object, > following rule 3. > > 4. Now since arg1 + 3 is a composite, following rule 1 again, its > right operand: 6 is implicitly converted to a value. > > 5. Continuing, the result of arg1 + 3 ... + 6 is again another > composite. Rule 3. > > 6. The expression arg1 + 3 + 6 being a composite, is the operand > of the unary operator -. Following rule 2, the result is an actor > object. > 7. Following rule 3, the whole thing -(arg1 + 3 + 6) is a composite. > > Confused? If so, it's because you're exposing way more detail than the user needs, IMO. All this stuff could be better explained by a section titled How to know when the result of an expression is an actor > well, when in doubt, just wrap the operands in ref(x), val(x) or > cref(x) appropriately and you'll be ok: > > -(arg1 + val(3) + val(6)) How does the above help unconfuse the reader? > Lazy-operator application is highly contagious. In most cases, a ^^^^^^^^^^^^^^^^^^^^^^^^^ "Laziness" > single argN actor infects all its immediate neighbors within a group > (first level or parenthesized expression). > > > Take note that although at least one of the operands of what? > must be a valid actor class in order for lazy evaluation to take > effect, if this is not the case and we still want to lazily evaluate > an expression, we can use ref(x), val(x) or cref(x) to transform the > operand into a valid action object (see primitives). Example: ^^^^^^ actor > > val(1) << 3; Note that at least one operand of any operator must be a valid actor for lazy evaluation to take effect. To force lazy evaluation of an ordinary expression, we can use ref(x), val(x) or cref(x) to transform an operand into a valid actor object. For example, val(1) << 3; -- Dave Abrahams Boost Consulting www.boost-consulting.com

1 0

Re: [boost] Gender neutral documentation
by Martin Bonner 04 Nov '05

04 Nov '05

----Original Message---- From: Angus Leeming [mailto:angus.leeming@btopenworld.com] Sent: 04 November 2005 11:13 To: boost(a)lists.boost.org Subject: Re: [boost] Gender neutral documentation > Anthony Williams wrote: >> The use of "she" implies the person in question is female. Though >> "he" technically also has the implication that the person is male, >> it is general usage that "he" is used as a stand in for "he or she". >> If we really want to be gender neutral, we should write "he or she", >> which is what we really mean. Sometimes this is abbreviated "s/he", >> but that's an ugly kludge. Better would be to rewrite the sentence >> to avoid the issue. > >>> My personal preference is to use "they" as the first person >>> singular gender-neutral pronoun. This will be /intensely/ >>> irritating to grammar purists, but does seem to be the way the >>> language is evolving. > >> I don't like this, but it is preferable to "she". > > We do have a pronoun for just such a usage, albeit one that appears to > be used today only by the British royal family. Perhaps it sounds > archaic, but one understands what one is talking about when one uses > the correct language. We do. However what one *meant* to write was: One's personal preference is to use "they" as the *THIRD* person singular gender-neutral pronoun. As used by the British royal family, "one" is a first person singular pronoun. > Regards from yet another Brit, :-) -- Martin Bonner Martin.Bonner(a)Pitechnology.com Pi Technology, Milton Hall, Ely Road, Milton, Cambridge, CB4 6WZ, ENGLAND Tel: +44 (0)1223 441434

3 2

Re: [boost] Feature Request
by Victor A. Wagner Jr. 04 Nov '05

04 Nov '05

At 22:40 2005-11-03, Abajyan, Hambardzum wrote: >Hi >(I've already been subscribed my address as you told me to do.) > >I would like to now why there isn't an implementation of TCP(UDP) >Sockets ? >I think it's possible to write a good platform-independent architecture >based on Berkeley socket interface (supporting asynchronous >(non-blocking) sockets), because both Linux and Windows systems support >that architecture. >There are many libraries like that: e.g. Boost.Thread library which is >also platform-independent. In my opinion, this feature is very usefull >as with it programmers can develop network applications on Boost. >Thanks I like the approach these guys are taking: http://www.dtilib.dk/ that actually would be 3 libraries, but I like them all. > >Best Regards Hambik > >_______________________________________________ >Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost Victor A. Wagner Jr. http://rudbek.com The five most dangerous words in the English language: "There oughta be a law"

3 2

Re: [boost] [ANN] Phoenix-2 prerelease (Functions)
by David Abrahams 04 Nov '05

04 Nov '05

Joel de Guzman <joel(a)boost-consulting.com> writes: > Comments, feedback very welcome! > Function > > Lazy functions... > > #include <boost/spirit/phoenix/function/function.hpp> > > The function template class provides a mechanism for lazily ^^^^^^^^^^^^^^ class template > evaluating functions. Syntactically, a lazy function looks like an > ordinary C/C++ function. The function call looks familiar and feels > the same as ordinary C++ functions. Except you can't use ADL. > However, unlike ordinary > functions, the actual function execution is deferred. For example > here are sample factorial function calls: Whoa, where did factorial come from? > factorial(4) > factorial(arg1) > factorial(arg1 * 6 / factorial(ref(i))) > > These functions are automatically lazily bound Really? Even the first one? > unlike ordinary function pointers or functor objects that need to be > explicitly bound through the bind function (see Bind). > > A lazy function works in conjunction with a user defined function > object (as usual with a member operator()). I'm lost. What do you mean "in conjunction with?" > Only special forms of function objects are allowed. Even more lost! Allowed where? > This is required to enable true polymorphism I happen to have a clue as to what you mean, but most won't. Probably anyplace you mention polymorphism in this doc, you should link to the discussion of its use in this context. > (STL style monomorphic functors and function pointers can still be > used through the bind facility (see Bind)). > > > This special function object is expected to have a nested template > class apply<T0...TN> (where N is the number of arguments of its > operator()). The nested template class result should have a typedef > type that reflects the return type of its operator(). I guess you might be describing the Eval concept. It's not obvious though. This section needs to be reworked for clarity. > There is a special case Of what? > for functors that accept no arguments. Such nullary functors are > only required By what? > to define a typedef result_type that reflects the > return type of its operator(). > > > Here's an example of a simple functor that computes the factorial of > a number: I would avoid "functor" except as a parenthesized note remarking that function objects are often called functors in the C++ community. That usage of "functor" is sorta deprecated and probably never should have arisen, considering its prior use with other meanings. > struct factorial_impl > { > template <typename Arg> > struct apply > { > typedef Arg type; > }; > > template <typename Arg> > Arg operator()(Arg n) const > { > return (n <= 0) ? 1 : n * this->operator()(n-1); > } > }; > > (See factorial.cpp) Oh, here it is. Way too late. Or mentioned too early. > The functor is polymorphic. Its arguments and return type are not > fixed to a particular type. The example above can handle any Arg > type as long as it can carry out the required operations (i.e. <=, * > and - ). > > We can declare and instantiate a lazy factorial function this way: > > function<factorial_impl> factorial; Oh, this is the point of the section? Then why is it called "Function" set in normal type, instead of "function" set in code font? > Invoking a lazy function factorial does not immediately execute the function object factorial_impl. Instead, a composite object is created and returned to the caller. Example: > > factorial(arg1) Even in factorial(4) ? > does nothing more than return a composite. A second function call > will invoke the actual factorial function. Example: > > int i = 4; > cout << factorial(arg1)(i); > > will print out "24". > > Take note that in certain cases (e.g. for function objects with > state), an instance of the functor may be passed on to the > constructor. Example: > > function<factorial_impl> factorial(ftor); > > where ftor is an instance of factorial_impl (this is not necessary ^^^^ needs antecedent > in this case since factorial is a simple stateless functor). Take ^^^^ too many "this"es. Eliminate the first. > care though when using functors with state because the functors are ^^^^^^ ^ strike , > held by value. I don't think you mean that. I think you mean "Functors are often copied repeatedly, and the state may be changed in one or more copies, rather than in the original." > It is best to keep the data manipulated by a functor > outside the functor itself and keep a reference to this data inside > the functor. Also, it is best to keep functors as small as possible. > -- Dave Abrahams Boost Consulting www.boost-consulting.com

1 0

Re: [boost] [ANN] Phoenix-2 prerelease
by David Abrahams 04 Nov '05

04 Nov '05

Joel de Guzman <joel(a)boost-consulting.com> writes: > Comments, feedback very welcome! > Values > > #include <boost/spirit/phoenix/core/value.hpp> > > Whenever we see a constant in a partially applied function, an > > actor<value<T> > > > (where T is the type of the constant) is automatically created by > default for us. > For instance: > > add(arg1, 6) > > Passing a second argument, 6, an actor<value<int> > is implicitly > created behind the scenes. This is also equivalent to: > > add(arg1, val(6)) > > val(x) generates an actor<value<T> > where T is the type of x. I think the use of "us" here is awkward. "You" would be better. "automatically by default" is confusing language. If you're not prepared to tell people what happens when the default is not taken, you probably shouldn't mention that it's a default at all. Also, I doubt that it's really _wherever_ a constant appears in a partially applied function: foo<2>() + arg1 I suggest: To represent a value of type T as an actor, we can use the value template. actor<value<T> >(x) is an actor that returns x when invoked. For instance, actor<value<int> >(6) is equivalent to val(6) an actor that, when invoked, returns the value 6. In expressions combining actors with values, the val() function is invoked implicitly, so add(arg1, 6) is equivalent to add(arg1, val(6)) an actor that adds 6 to its first argument. > In most cases, there's really no need to explicitly use val. There ^^^^^^ strike > are situations though, as we'll see later on, where this is > unavoidable. ..., but as we'll see later on, there are situations where it is unavoidable. -- Dave Abrahams Boost Consulting www.boost-consulting.com

1 0