0.9.3 Docs.

Author: glynos

images/boost.png renamed to _images/boost.png

@@ -0,0 +1,76 @@
+.. _atom_reader:
+
+*************
+ Atom reader
+*************
+
+The next examples show some simple, more practical applications using
+the HTTP client.  The first one reads a simple Atom feed and prints
+the titles of each entry to the console.
+
+The code
+========
+
+.. code-block:: c++
+
+   #include "atom.hpp"
+   #include <boost/network/protocol/http/client.hpp>
+   #include <boost/foreach.hpp>
+   #include <iostream>
+
+   int main(int argc, char * argv[]) {
+       using namespace boost::network;
+
+       if (argc != 2) {
+           std::cout << "Usage: " << argv[0] << " <url>" << std::endl;
+           return 1;
+       }
+
+       try {
+           http::client client;
+           http::client::request request(argv[1]);
+           request << header("Connection", "close");
+           http::client::response response = client.get(request);
+           atom::feed feed(response);
+
+           std::cout << "Feed: " << feed.title()
+	   	     << " (" << feed.subtitle() << ")" << std::endl;
+           BOOST_FOREACH(const atom::entry &entry, feed) {
+               std::cout << entry.title()
+	       		 << " (" << entry.published() << ")" << std::endl;
+           }
+       }
+       catch (std::exception &e) {
+           std::cerr << e.what() << std::endl;
+       }
+
+       return 0;
+   }
+
+Building and running ``atom_reader``
+====================================
+
+.. code-block:: bash
+
+    $ cd ~/cpp-netlib-build
+    $ make atom_reader
+
+And to run the example from the command line to access the feed that
+lists of all the commits on cpp-netlib's master repository:
+
+.. code-block:: bash
+
+    $ ./example/atom_reader https://github.com/cpp-netlib/cpp-netlib/commits/master.atom
+
+Diving into the code
+====================
+
+Most of this will now be familiar.  The response is passed to the
+constructor to the ``atom::feed`` class, which parses the resultant
+XML.  To keep this example as simple as possible, `rapidxml`_, a
+header-only XML parser library, was used to parse the response.
+
+.. _`rapidxml`: http://rapidxml.sourceforge.net/
+
+A similar example using RSS feeds exists in
+``libs/network/example/rss``.

static/boost.png renamed to _images/boost1.png

@@ -5,14 +5,10 @@ The :mod:`cpp-netlib` is a practical library that is designed to aid
 the development of applications for that need to communicate using
 common networking protocols.  The following set of examples describe a
 series of realistic examples that use the :mod:`cpp-netlib` for these
-kinds of application.
-
-.. todo::
-
-    Make the examples more accessible.
+kinds of application.  All examples are built using CMake.
 
 .. toctree::
    :maxdepth: 2
 
    examples_http.rst
-..   examples_xmpp.rst
+

_images/ftp_uri.png

@@ -9,5 +9,8 @@ embedded into larger applications.
    :maxdepth: 2
 
    http_client.rst
+   simple_wget.rst
    hello_world_server.rst
    hello_world_client.rst
+   atom_reader.rst
+   twitter_search.rst

_images/ftp_uri1.png

@@ -0,0 +1,199 @@
+.. _getting_started:
+
+*****************
+ Getting Started
+*****************
+
+Downloading an official release
+===============================
+
+All stable versions of :mod:`cpp-netlib` can be downloaded from
+Github_ from this url:
+
+    http://github.com/cpp-netlib/cpp-netlib/downloads
+
+Each release is available as gzipped (Using the command
+``tar xzf cpp-netlib.tar.gz``) or bzipped (Using ``tar xjf
+cpp-netlib.tar.bz2``) tarball, or as a zipfile (``unzip
+cpp-netlib.zip``, or on Windows using a tool such as 7zip_).
+
+.. _Github: http://github.com/cpp-netlib/cpp-netlib/downloads
+.. _7zip: http://www.7-zip.org/
+
+Downloading a development version
+=================================
+
+The :mod:`cpp-netlib` uses Git_ for source control, so to use any
+development versions Git must be installed on your system.
+
+Using the command line, the command to get the latest code is:
+
+::
+
+    shell$ git clone git://github.com/mikhailberis/cpp-netlib.git
+
+This should be enough information get to started.  To do more complex
+things with Git, such as pulling changes or checking out a new branch,
+refer to the `Git documentation`_.
+
+.. note:: If you look at the Git repository closely, this is the repository of
+   *mikhailberis* instead of *cpp-netlib*. The reason is that the main developer
+   and maintainer of the project is Dean Michael Berris, who goes by the alias
+   *mikhailberis* on the Internet.
+
+   Dean does the merging and maintenance of the whole library, similar to how
+   `Linus Torvalds`_ of the Linux project acts as the gatekeeper of the project.
+
+.. _`Linus Torvalds`: http://en.wikipedia.org/wiki/Linus_Torvalds
+
+Windows users need to use msysGit_, and to invoke the command above
+from a shell.
+
+For fans of Subversion_, the same code can be checked out from
+http://svn.github.com/mikhailberis/cpp-netlib.git.
+
+.. _Git: http://git-scm.com/
+.. _`Git documentation`: http://git-scm.com/documentation
+.. _msysGit: http://code.google.com/p/msysgit/downloads/list
+.. _Subversion: http://subversion.tigris.org/
+
+.. note:: The :mod:`cpp-netlib` project is hosted on GitHub_ and follows the
+   prescribed development model for GitHub_ based projects. This means in case
+   you want to submit patches, you will have to create a fork of the project
+   (read up on forking_) and then submit a pull request (read up on submitting
+   `pull requests`_).
+
+.. _forking: http://help.github.com/forking/
+.. _`pull requests`: http://help.github.com/pull-requests/
+
+Getting Boost
+=============
+
+:mod:`cpp-netlib` depends on Boost_.  It should work for any version
+of Boost above 1.45.0.  If Boost is not installed on your system, the
+latest package can be found on the `Boost web-site`_.  The environment
+variable ``BOOST_ROOT`` must be defined, which must be the full path
+name of the top directory of the Boost distribution.  Although Boost
+is mostly header only, applications built using :mod:`cpp-netlib`
+still requires linking with `Boost.System`_, `Boost.Date_time`_, and
+`Boost.Regex`_.
+
+.. _Boost: http://www.boost.org/doc/libs/release/more/getting_started/index.html
+.. _`Boost web-site`: http://www.boost.org/users/download/
+.. _`Boost.System`: http://www.boost.org/libs/system/index.html
+.. _`Boost.Date_time`: http://www.boost.org/libs/date_time/index.html
+.. _`Boost.Regex`: http://www.boost.org/libs/regex/index.html
+
+.. note:: You can follow the steps in the `Boost Getting Started`_ guide to
+   install Boost into your development system.
+
+.. _`Boost Getting Started`:
+   http://www.boost.org/doc/libs/release/more/getting_started/index.html
+
+.. warning:: There is a known incompatibility between :mod:`cpp-netlib` and
+   Boost 1.46.1 on some compilers. It is not recommended to use :mod:`cpp-netlib`
+   with Boost 1.46.1. Some have reported though that Boost 1.47.0
+   and :mod:`cpp-netlib` work together better.
+
+Getting CMake
+=============
+
+The :mod:`cpp-netlib` uses CMake_ to generate platform-specific build files. If
+you intend to run the test suite, you can follow the instructions below.
+Otherwise, you don't need CMake to use :mod:`cpp-netlib` in your project. The
+:mod:`cpp-netlib` requires CMake version 2.8 or higher.
+
+.. _CMake: http://www.cmake.org/
+
+Let's assume that you have unpacked the :mod:`cpp-netlib` at the top of your
+HOME directory. On Unix-like systems you will typically be able to change into
+your HOME directory using the command ``cd ~``. This sample below assumes that
+the ``~/cpp-netlib`` directory exists, and is the top-level directory of the
+:mod:`cpp-netlib` release.
+
+Building with CMake
+===================
+
+To build the tests that come with cpp-netlib, we first need to configure the
+build system to use our compiler of choice. This is done by running the
+``cmake`` command at the top-level directory of :mod:`cpp-netlib` with
+additional parameters::
+
+    $ mkdir ~/cpp-netlib-build
+    $ cd ~/cpp-netlib-build
+    $ cmake -DCMAKE_BUILD_TYPE=Debug \
+    >       -DCMAKE_C_COMPILER=gcc   \
+    >       -DCMAKE_CXX_COMPILER=g++ \
+    >       ../cpp-netlib
+
+.. note:: While it's not compulsory, it's recommended that
+          :mod:`cpp-netlib` is built outside the source directory.
+          For the purposes of documentation, we'll assume that all
+          builds are done in ``~/cpp-netlib-build``.
+
+Building on Linux
+~~~~~~~~~~~~~~~~~
+
+On Linux, this will generate the appropriate Makefiles that will enable you to
+build and run the tests and examples that come with :mod:`cpp-netlib`. To build
+the tests, you can run ``make`` in the same top-level directory of
+``~/cpp-netlib-build``::
+
+    $ make
+
+.. note:: Just like with traditional GNU Make, you can add the ``-j`` parameter
+   to specify how many parallel builds to run. In case you're in a sufficiently
+   powerful system and would like to parallelize the build into 4 jobs, you can
+   do this with::
+
+       make -j4
+
+   As a caveat, :mod:`cpp-netlib` is heavy on template metaprogramming and will
+   require a lot of computing and memory resources to build the individual
+   tests. Do this at the risk of thrashing_ your system.  However, this
+   compile-time burden is much reduced in recent versions.
+
+.. _thrashing: http://en.wikipedia.org/wiki/Thrashing_(computer_science)
+
+Once the build has completed, you can now run the test suite by issuing::
+
+    $ make test
+
+Building On Windows
+~~~~~~~~~~~~~~~~~~~
+
+If you're using the Microsoft Visual C++ compiler or the Microsoft Visual Studio
+IDE and you would like to build cpp-netlib from within Visual Studio, you can
+look for the solution and project files as the artifacts of the call to
+``cmake`` -- the file should be named ``CPP-NETLIB.sln`` (the solution) along
+with a number of project files for Visual Studio.
+
+.. note:: As of version 0.9.3, :mod:`cpp-netlib` produces three static
+          libraries.  Using GCC on Linux these are::
+
+   	     libcppnetlib-client-connections.a
+	     libcppnetlib-server-parsers.a
+	     libcppnetlib-uri.a
+
+	  And using Visual C++ on Windows they are::
+
+   	     cppnetlib-client-connections.lib
+	     cppnetlib-server-parsers.lib
+	     cppnetlib-uri.lib
+
+	  Users can find them in ``~/cpp-netlib-build/libs/network/src``.
+
+Reporting Issues, Getting Support
+=================================
+
+In case you find yourself stuck or if you've found a bug (or you want to just
+join the discussion) you have a few options to choose from.
+
+For reporting bugs, feature requests, and asking questions about the
+implementation and/or the documentation, you can go to the GitHub issues page
+for the project at http://github.com/cpp-netlib/cpp-netlib/issues.
+
+You can also opt to join the developers mailing list for a more personal
+interaction with the developers of the project. You can join the mailing list
+through http://groups.google.com/forum/#!forum/cpp-netlib.
+

_images/http_uri.png

@@ -0,0 +1,94 @@
+.. _hello_world_http_client:
+
+***************************
+ "Hello world" HTTP client
+***************************
+
+Since we have a "Hello World" HTTP server, let's then create an HTTP client to
+access that server. This client will be similar to the HTTP client we made
+earlier in the documentation.
+
+The code
+========
+
+We want to create a simple HTTP client that just makes a request to the HTTP
+server that we created earlier. This really simple client will look like this:
+
+.. code-block:: c++
+
+    #include <boost/network/protocol/http/client.hpp>
+    #include <string>
+    #include <sstream>
+    #include <iostream>
+
+    namespace http = boost::network::http;
+
+    int main(int argc, char * argv[]) {
+        if (argc != 3) {
+            std::cerr << "Usage: " << argv[0] << " address port" << std::endl;
+            return 1;
+        }
+
+        try {
+            http::client client;
+            std::ostringstream url;
+            url << "http://" << argv[1] << ":" << argv[2] << "/";
+            http::client::request request(url.str());
+            http::client::response response =
+                client.get(request);
+            std::cout << body(response) << std::endl;
+        } catch (std::exception & e) {
+            std::cerr << e.what() << std::endl;
+            return 1;
+        }
+        return 0;
+    }
+
+Building and running the client
+===============================
+
+Just like with the HTTP Server and HTTP client example before, we can build this
+example by doing the following on the shell:
+
+.. code-block:: bash
+
+    $ cd ~/cpp-netlib-build
+    $ make hello_world_client
+
+This example can be run from the command line as follows:
+
+.. code-block:: bash
+
+    $ ./example/hello_world_client http://127.0.0.1:8000
+
+.. note:: This assumes that you have the ``hello_world_server`` running on
+   localhost port 8000.
+
+Diving into the code
+====================
+
+All this example shows is how easy it is to write an HTTP client that connects
+to an HTTP server, and gets the body of the response. The relevant lines are:
+
+.. code-block:: c++
+
+    http::client client;
+    http::client::request request(url.str());
+    http::client::response response =
+        client.get(request);
+    std::cout << body(response) << std::endl;
+
+You can then imagine using this in an XML-RPC client, where you can craft the
+XML-RPC request as payload which you can pass as the body to a request, then
+perform the request via HTTP:
+
+.. code-block:: c++
+
+    http::client client;
+    http::client::request request("http://my.webservice.com/");
+    http::client::response =
+        client.post(request, "application/xml", some_xml_string);
+    std::data = body(response);
+
+The next set of examples show some more practical applications using
+the :mod:`cpp-netlib` HTTP client.