Added some docs that came from Dean's BoostCon paper. These still need to be rewritten to better fit the rest of the docs.

glynos · glynos · commit 548573c7ab7c · 2010-06-13T21:56:07.000+02:00
diff --git a/libs/network/doc/.gitignore b/libs/network/doc/.gitignore
@@ -0,0 +1 @@
+html
diff --git a/libs/network/doc/Jamfile.v2 b/libs/network/doc/Jamfile.v2
@@ -5,11 +5,11 @@
 
 path-constant boost-images : doc/src/images ;
 
-xml network : network.qbk ;
+xml cpp-netlib : cpp-netlib.qbk ;
 
 boostbook standalone
     :
-        network
+        cpp-netlib
     :
         # HTML options first:
         # Use graphics not text for navigation:
diff --git a/libs/network/doc/cpp-netlib.qbk b/libs/network/doc/cpp-netlib.qbk
@@ -7,7 +7,7 @@
 
 [article C++ Network Library
     [quickbook 1.4]
-    [version 0.6]
+    [version 0.7]
     [authors [Matthews, Glyn], [Berris, Dean Michael]]
     [copyright 2008, 2009, 2010 Glyn Matthews, Dean Michael Berris]
     [purpose C++ library for general network programming]
@@ -34,24 +34,27 @@
 [def __libcurl__ [@http://curl.haxx.se/ libcurl]]
 [def __mozilla_netlib__ [@http://www.mozilla.org/projects/netlib/ mozilla-netlib]]
 [def __sf_cpp_netlib__ [@http://sourceforge.net/projects/cpp-netlib/ sourceforge]]
+[def __git__ [@http://www.git-scm.org/ Git]]
 [def __github__ [@http://github.com/cpp-netlib/cpp-netlib github]]
 [def __default_constructible__ [@http://www.boost.org/doc/html/DefaultConstructible.html DefaultConstructible]]
 [def __copy_constructible__ [@http://www.boost.org/doc/html/CopyConstructible.html CopyConstructible]]
 [def __assignable__ [@http://www.boost.org/doc/html/Assignable.html Assignable]]
-[def __equality_comparable__ [@http://www.boost.org/doc/html/Assignable.html Assignable]]
+[def __equality_comparable__ [@http://www.boost.org/doc/html/EqualityComparable.html EqualityComparable]]
 
 
 [def __quick_start__ quick start]
 
 
+[include miscellanea.qbk]
 [include quick_start.qbk]
 [include intro.qbk]
 [include using.qbk]
-[/include architecture.qbk]
+[include techniques.qbk]
 [include message.qbk]
 [include uri.qbk]
 [include protocol.qbk]
 [include examples.qbk]
+[include pitfalls.qbk]
 [include reference.qbk]
 [include acknowledgements.qbk]
 [include appendices.qbk]
diff --git a/libs/network/doc/examples.qbk b/libs/network/doc/examples.qbk
@@ -10,4 +10,4 @@
 [/ include examples/hello_world.qbk]
 [/ include examples/http_client.qbk]
 [include examples/simple_wget.qbk]
-[endsect]
+[endsect] [/ examples]
diff --git a/libs/network/doc/http.qbk b/libs/network/doc/http.qbk
@@ -7,12 +7,43 @@
 
 
 [section:http HTTP]
+The cpp-netlib provides full support for a configurable, embedded
+HTTP client and server.
+
+For each sub-librariy, the URI and protocol specific code belong in
+their own namespace and in the relevant sub-directories (i.e. `http`
+defined in `protocol/http/` and `uri::http` defined in `uri/http/`).
+
+[section:http_uri HTTP URI]
+
+Firstly, cpp-netlib provides a specialization and `typedef` for an
+HTTP URI:
+
+ namespace http {
+     template <class T> class basic_uri;
+     typedef basic_uri<default_> uri;
+ }
+    
+`basic_uri` provides a parser which breaks down a URI string passed
+to it's constructor into different parts.
+
+ using namespace boost::network::uri;
+ http::uri uri_("http://www.boost.org/");
+ assert(valid(uri_));
+ assert(scheme(uri_) == "http");
+ assert(host(uri_) == "www.boost.org")
+ assert(port(uri_) == 80)
+ assert(path(uri_) == "/");
+
+The syntax of the HTTP URI are defined in RFC 1738 section 3.3 and the
+default URI provided with cpp-netlib conforms to this.  In such a way,
+specializations that conform to any URI scheme can be provided.
+[endsect] [/ http_uri]
 
 [section:http_server_example HTTP Server]
 
 Here is the server code again from the __quick_start__.
 
-``
  #include <boost/network/protocol/http/server.hpp>
  #include <iostream>
  
@@ -54,7 +85,6 @@ Here is the server code again from the __quick_start__.
      
      return 0;
  }
-``
 
 [heading HTTP Server]
 
@@ -118,7 +148,6 @@ be implemented.
 
 Here is the client code again from the __quick_start__.
 
-``
  #include <boost/network/protocol/http/client.hpp>
  #include <iostream>
  
@@ -146,7 +175,6 @@ Here is the client code again from the __quick_start__.
      
      return 0;
  }
-``
 
 Before walking through exactly what is happening in this example, the
 principal components are described below:
diff --git a/libs/network/doc/message.qbk b/libs/network/doc/message.qbk
@@ -88,7 +88,7 @@ __message__:
  } // namespace network
  } // namespace boost
 
-[endsect] [/tag_dispatching]
+[endsect] [/ tag_dispatching]
 
 [section:transformation_layer Transformation layer]
 The transformation layer defines the algorithms that can be applied on
@@ -101,7 +101,7 @@ the Message concept.  Functions in the transform layer take the form:
      >
  basic_message<Tag> &transform(basic_message<Tag> &, ...);
 
-[endsect] [/transformation_layer]
+[endsect] [/ transformation_layer]
 
 [section:rendering_layer Rendering layer]
 The rendering layer defines the algorithms used to render a message
@@ -114,6 +114,6 @@ layer take the form:
      >
  unspecified &render(const basic_message<Tag> &, ...);
 
-[endsect] [/rendering_layer]
+[endsect] [/ rendering_layer]
 
-[endsect] [/message]
+[endsect] [/ message]
diff --git a/libs/network/doc/miscellanea.qbk b/libs/network/doc/miscellanea.qbk
@@ -0,0 +1,39 @@
+[/
+  (C) Copyright 2009, 2010 Glyn Matthews.
+  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).
+]
+
+
+[section:miscellanea Miscellanea]
+
+[heading Where to find the __cnl__]
+
+Official releases of the __cnl__ can be found [@http://github.com/cpp-netlib/cpp-netlib/downloads on github].
+
+[heading How to get the source code]
+
+Since this project uses __git__, there's not any single place to download the source code.  However, pre-releases are prepared at =git://github.com/mikhailberis/cpp-netlib.git=.  This is where the most up-to-date code can be found.
+
+To clone this repository, run the following command in a shell:
+
+ shell$ git clone git://github.com/mikhailberis/cpp-netlib.git
+
+This is already enough to start looking at the source code.  __git__ is very powerful and it should be enough for now to refer to the [@http://git-scm.com/documentation documentation] to do more complex things.
+
+For users of Git on Windows, more information can be found in [@http://book.git-scm.com/6_git_on_windows.html this screencast].
+
+Finally, for non-users of Git, Github also offers the possibility to download the source as a zip file or tar archive.
+
+[heading How to build the __cnl__]
+
+Since the __cnl__ is a header-only library, it doesn't need to be built to be used (though it does need to link to [@http www.boost.org/doc/libs/release/libs/system/index.html Boost.System].  To build and run the unit tests and examples the preferred way is to use [@http://www.cmake.org/ CMake], although Jamfiles are also provided.
+
+ shell$ cd $CPP_NETLIB_DIR
+ shell$ mkdir -p build
+ shell$ cd build
+ shell$ cmake ..
+ shell$ make
+
+[endsect] [/ miscellanea]
diff --git a/libs/network/doc/pitfalls.qbk b/libs/network/doc/pitfalls.qbk
@@ -0,0 +1,56 @@
+[/
+  (C) Copyright 2010 Dean Michael Berris, Glyn Matthews.
+  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).
+]
+
+[section:pitfalls Common Pitfalls]
+
+There are a number of common pitfalls one gets to when implementing a
+header-only network library. Some of these are briefly discussed in this
+section.
+
+[heading Linear Explosion]
+
+The linear explosion comes up when you start supporting a lot of different tags
+through the tag dispatch mechanism. There is a temptation to implement support 
+a whole slew of tags and the associated variations brought about by these tags.
+Because of this as soon as you start mixing and matching tags you get to a point
+where where there can be a lot of tags and a lot of specializations.
+
+To manage linear explosion, using a moderately robust template metaprogramming
+library like Boost.MPL should be used to remove much of the repetition and
+manage the growth of the variations/combinations.
+
+[heading Compile Time Toll]
+
+Due to the nature of template metaprogramming and the current state of compiler
+technologies, the cost of going header-only can be considerable during
+compilation. It is no secret that template metaprogramming takes a lot out of
+the compiler because the template implementations of most of the popular
+compilers were not built to handle template metaprogramming. The state of the
+art when it comes to compiler technology is changing in C++ with the promise of
+faster, more efficient, and more robust template metaprogramming support.
+
+Aside from doing as much as you can to optimize the compilation times of
+template-based programs, the only solution really is to wait for (or to actually
+help) compilers to get faster and better when compiling template-heavy code.
+
+[heading Contribution Barrier]
+
+Currently there are not a lot of C++ programmers who understand how to do
+template metaprogramming as well as implement efficient network utilities. There
+are a lot of C++ programmers who are looking for an using libraries to make
+network programming easier at a higher level. The disparity between the users
+and the developers can be considerable, and using a relatively niche technique
+like template metaprogramming in the implementation of the library proves to be
+a significant contribution barrier.
+
+Because cpp-netlib is a project that has in its stated goals the implementation
+and the distribution of a header-only collection of network-based libraries, one
+solution to the issue is in the education and dissemination (and documentation)
+of the techniques used and the rationale for why these techniques are used in
+cpp-netlib. This is the goal of this paper and in the future editions of this
+paper.
+[endsect] [/ pitfalls]
diff --git a/libs/network/doc/reference.qbk b/libs/network/doc/reference.qbk
@@ -8,6 +8,14 @@
 
 [section:reference Reference]
 [variablelist
+   [
+      [
+	 [@http://www.boostpro.com/mplbook/ Template Metaprogramming]
+      ]
+      [
+	 The best guide to C++ template metaprogramming
+      ]
+   ]
    [
       [
          [@http://www.w3.org/Protocols/HTTP/1.0/spec.html HTTP 1.0]
diff --git a/libs/network/doc/techniques.qbk b/libs/network/doc/techniques.qbk
@@ -0,0 +1,17 @@
+[/
+  (C) Copyright 2010 Dean Michael Berris, Glyn Matthews.
+  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).
+]
+
+[section:techniques Techniques]
+Throughout the __cnl__ implementation there are some recurring techniques
+used to achieve the generic approach to implementing specific ideas. This
+section covers these recurring techniques -- where appropriate the inspiration
+for the technique is also cited.
+
+[include techniques/tag-metafunctions.qbk]
+[include techniques/directives.qbk]
+[include techniques/static-dynamic.qbk]
+[endsect] [/ techniques]
diff --git a/libs/network/doc/techniques/directives.qbk b/libs/network/doc/techniques/directives.qbk
@@ -0,0 +1,83 @@
+[/
+  (C) Copyright 2010 Dean Michael Berris, Glyn Matthews.
+  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).
+]
+
+
+[section:directives Directives]
+The library also uses a technique for allowing message-passing semantics in a
+chainable fashion in the form of directives. The basic concept for directives
+is, in a general sense, an encapsulated transformation that can be applied
+to objects that abide by the directive protocol.
+
+Using the object-oriented notion of message passing, where an object accepts a
+message (usually a function call) we define a simple DSEL in order for the
+protocol to be supported by certain object types. In cpp-netlib the protocol
+implemented is similar to that of the standard iostream formatting system:
+
+ object << directive1(...)
+        << directive2(...)
+        ...
+        << directiveN(...);
+
+In cpp-netlib the directives are simple function objects that take a target 
+object as reference and returns a reference to the same object as a result. In 
+code the directive pattern looks like the following:
+
+ struct directive_type {
+     template <class Input>
+     Input & operator () (Input &input) const {
+         // do something to input
+         return input;
+     }
+ };
+
+To simplify directive creation, usually factory or generator functions are defined 
+to return concrete objects of the directive's type.
+
+ inline
+ directive_type directive(...) {
+     return directive_type();
+ }
+
+The trivial implementation of the directive protocol then boils down to the
+specialization of the shift-left operator on the target type.
+
+ template <class Directive>
+ inline target_type & operator<< 
+ (target_type & x, Directive const & f) {
+     return f(x);
+ }
+
+The rationale for implementing directives include the following:
+
+* *Encapsulation* - by moving logic into the directive types the target
+  object's interface can remain rudimentary and even hidden to the user's
+  immediate attention. Adding this layer of indirection also allows for
+  changing the underlying implementations while maintaining the same syntactic
+  and semantic properties.
+* *Flexibility* - by allowing the creation of directives that are
+  independent from the target object's type, generic operations can be applied
+  based on the concept being modeled by the target type. The flexibility also 
+  afforded comes in the directive's generator function, which can also generate
+  different concrete directive specializations based on parameters to the
+  function.
+* *Extensibility* - because the directives are independent of the
+  target object's type, new directives can be added and supported without
+  having to change the target object at all.
+* *Reuse* - truly generic directives can then be used for a broad set of
+  target object types that model the same concepts supported by the directive.
+  Because the directives are self-contained objects, the state and other
+  object references it keeps are only accessible to it and can be re-used in
+  different contexts as well.
+
+Extending a system that uses directives is trivial in header-only systems
+because new directives are simply additive. The protocol is simple and can be
+applied to a broad class of situations.
+
+In a header-only library, the static nature of the wiring and chaining of the
+operations lends itself to compiler abuse. A deep enough nesting of the
+directives can lead to prolonged compilation times.
+[endsect] [/ directives]
diff --git a/libs/network/doc/techniques/static-dynamic.qbk b/libs/network/doc/techniques/static-dynamic.qbk
diff --git a/libs/network/doc/techniques/tag-metafunctions.qbk b/libs/network/doc/techniques/tag-metafunctions.qbk
diff --git a/libs/network/doc/using.qbk b/libs/network/doc/using.qbk

Original file line number	Diff line number	Diff line change
`@@ -5,11 +5,11 @@`
`5`	`5`
`6`	`6`	`path-constant boost-images : doc/src/images ;`
`7`	`7`
`8`		`-xml network : network.qbk ;`
	`8`	`+xml cpp-netlib : cpp-netlib.qbk ;`
`9`	`9`
`10`	`10`	`boostbook standalone`
`11`	`11`	`:`
`12`		`- network`
	`12`	`+ cpp-netlib`
`13`	`13`	`:`
`14`	`14`	`# HTML options first:`
`15`	`15`	`# Use graphics not text for navigation:`
Original file line number	Diff line number	Diff line change
`@@ -8,6 +8,14 @@`
`8`	`8`
`9`	`9`	`[section:reference Reference]`
`10`	`10`	`[variablelist`
	`11`	`+ [`
	`12`	`+ [`
	`13`	`+ [@http://www.boostpro.com/mplbook/ Template Metaprogramming]`
	`14`	`+ ]`
	`15`	`+ [`
	`16`	`+ The best guide to C++ template metaprogramming`
	`17`	`+ ]`
	`18`	`+ ]`
`11`	`19`	`[`
`12`	`20`	`[`
`13`	`21`	`[@http://www.w3.org/Protocols/HTTP/1.0/spec.html HTTP 1.0]`