Merge pull request cpp-netlib#434 from deanberris/0.11-devel-docfix-https-refinement

0.11 devel docfix https refinement

Author: deanberris

libs/network/doc/getting_started.rst

@@ -133,8 +133,13 @@ additional parameters::
 
 If you intend to use the SSL support when using the HTTP client libraries in
 :mod:`cpp-netlib`, you may need to build it with OpenSSL_ installed or at least
-available to CMake. One example for building the library with OpenSSL_ support
-is by doing the following::
+available to CMake. If you have the development headers for OpenSSL_ installed
+on your system when you build :mod:`cpp-netlib`, CMake will be able to detect it
+and set the ``BOOST_NETWORK_ENABLE_HTTPS`` macro when building the library to
+support HTTPS URIs.
+
+One example for building the library with OpenSSL_ support with a custom
+(non-installed) version of OpenSSL_ is by doing the following::
 
     $ cmake -DCMAKE_BUILD_TYPE=Debug \
     >       -DCMAKE_C_COMPILER=clang \

libs/network/doc/html/_sources/getting_started.txt

@@ -133,8 +133,13 @@ additional parameters::
 
 If you intend to use the SSL support when using the HTTP client libraries in
 :mod:`cpp-netlib`, you may need to build it with OpenSSL_ installed or at least
-available to CMake. One example for building the library with OpenSSL_ support
-is by doing the following::
+available to CMake. If you have the development headers for OpenSSL_ installed
+on your system when you build :mod:`cpp-netlib`, CMake will be able to detect it
+and set the ``BOOST_NETWORK_ENABLE_HTTPS`` macro when building the library to
+support HTTPS URIs.
+
+One example for building the library with OpenSSL_ support with a custom
+(non-installed) version of OpenSSL_ is by doing the following::
 
     $ cmake -DCMAKE_BUILD_TYPE=Debug \
     >       -DCMAKE_C_COMPILER=clang \

libs/network/doc/html/_sources/reference/http_client.txt

@@ -39,8 +39,19 @@ only in the following situations:
     code.** It is best to define this either at compile-time of all code using
     the library, or before including any of the client headers.
 
-.. _OpenSSL: http://www.openssl.org/
+To use the client implementations that support HTTPS URIs, you may explicitly
+do the following:
+
+.. code-block:: c++
 
+   #define BOOST_NETWORK_ENABLE_HTTPS
+   #include <boost/network/include/http/client.hpp>
+
+This forces HTTPS support to be enabled and forces a dependency on OpenSSL_.
+This dependency is imposed by `Boost.Asio`_
+
+.. _OpenSSL: http://www.openssl.org/
+.. _`Boost.Asio`: http://www.boost.org/libs/asio
 
 Implementations
 ---------------

libs/network/doc/html/_sources/reference/http_server.txt

@@ -156,10 +156,8 @@ And that the following typedef's have been put in place:
     typedef boost::network::http::server<handler_type> http_server;
 
     struct handler_type {
-        void operator()(
-            http_server::request const & request,
-            http_server::response & response
-        ) {
+        void operator()(http_server::request const & request,
+                        http_server::response & response) {
             // do something here
         }
     };
@@ -227,13 +225,12 @@ To use the above supported named parameters, you'll have code that looks like th
 
     using namespace boost::network::http; // parameters are in this namespace
     handler handler_instance;
-    async_server<handler>::options options(handler_instance);
+    sync_server<handler>::options options(handler_instance);
     options.address("0.0.0.0")
            .port("80")
            .io_service(boost::make_shared<boost::asio::io_service>())
-           .thread_pool(boost::make_shared<boost::network::utils::thread_pool>(2))
            .reuse_address(true);
-    async_server<handler> instance(options);
+    sync_server<handler> instance(options);
     instance.run();
 
 Public Members
@@ -391,10 +388,8 @@ And that the following typedef's have been put in place:
     typedef boost::network::http::server<handler_type> http_server;
 
     struct handler_type {
-        void operator()(
-            http_server::request const & request,
-            http_server::connection_ptr connection
-        ) {
+        void operator()(http_server::request const & request,
+                        http_server::connection_ptr connection) {
             // do something here
         }
     };
@@ -537,31 +532,28 @@ used are defined in the link.
 
 .. code-block:: c++
 
-	// Initialize SSL context
-	boost::shared_ptr<boost::asio::ssl::context> ctx = boost::make_shared<boost::asio::ssl::context>(boost::asio::ssl::context::sslv23);
-	ctx->set_options(
+    // Initialize SSL context
+    boost::shared_ptr<boost::asio::ssl::context> ctx = boost::make_shared<boost::asio::ssl::context>(boost::asio::ssl::context::sslv23);
+    ctx->set_options(
                 boost::asio::ssl::context::default_workarounds
                 | boost::asio::ssl::context::no_sslv2
                 | boost::asio::ssl::context::single_dh_use);
-	
-	// Set keys
-	ctx->set_password_callback(password_callback);
-	ctx->use_certificate_chain_file("server.pem");
-	ctx->use_private_key_file("server.pem", boost::asio::ssl::context::pem);
-	ctx->use_tmp_dh_file("dh512.pem");
-	
+    
+    // Set keys
+    ctx->set_password_callback(password_callback);
+    ctx->use_certificate_chain_file("server.pem");
+    ctx->use_private_key_file("server.pem", boost::asio::ssl::context::pem);
+    ctx->use_tmp_dh_file("dh512.pem");
+    
     handler_type handler;
     http_server::options options(handler);
     options.thread_pool(boost::make_shared<boost::network::utils::thread_pool>(2));
     http_server server(options.address("127.0.0.1").port("8442").context(ctx));
 
-	
-.. code-block:: c++
-
-	std::string password_callback(std::size_t max_length, boost::asio::ssl::context_base::password_purpose purpose) {
-		return std::string("test");
-	}
-	
+    std::string password_callback(std::size_t max_length, boost::asio::ssl::context_base::password_purpose purpose) {
+        return std::string("test");
+    }
+    
 .. _Boost.Range: http://www.boost.org/libs/range
 .. _Boost.Function: http://www.boost.org/libs/function
 .. _Boost.Asio.SSL.Context: http://www.boost.org/doc/libs/1_55_0/doc/html/boost_asio/reference/ssl__context.html

libs/network/doc/html/contents.html

@@ -282,7 +282,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
         &copy; Copyright 2008-2014, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
-      Last updated on Sep 01, 2014.
+      Last updated on Sep 02, 2014.
       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
     </div>
   </body>

libs/network/doc/html/getting_started.html

@@ -159,8 +159,12 @@ <h2>Building with CMake<a class="headerlink" href="#building-with-cmake" title="
 </div>
 <p>If you intend to use the SSL support when using the HTTP client libraries in
 <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>, you may need to build it with <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> installed or at least
-available to CMake. One example for building the library with <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> support
-is by doing the following:</p>
+available to CMake. If you have the development headers for <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> installed
+on your system when you build <tt class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></tt>, CMake will be able to detect it
+and set the <tt class="docutils literal"><span class="pre">BOOST_NETWORK_ENABLE_HTTPS</span></tt> macro when building the library to
+support HTTPS URIs.</p>
+<p>One example for building the library with <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> support with a custom
+(non-installed) version of <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> is by doing the following:</p>
 <div class="highlight-python"><div class="highlight"><pre>$ cmake -DCMAKE_BUILD_TYPE=Debug \
 &gt;       -DCMAKE_C_COMPILER=clang \
 &gt;       -DCMAKE_CXX_COMPILER=clang++ \
@@ -346,7 +350,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
         &copy; Copyright 2008-2014, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
-      Last updated on Sep 01, 2014.
+      Last updated on Sep 02, 2014.
       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
     </div>
   </body>

libs/network/doc/html/index.html

@@ -203,7 +203,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
         &copy; Copyright 2008-2014, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
-      Last updated on Sep 01, 2014.
+      Last updated on Sep 02, 2014.
       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
     </div>
   </body>

libs/network/doc/html/objects.inv

@@ -135,7 +135,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
         &copy; Copyright 2008-2014, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
-      Last updated on Sep 01, 2014.
+      Last updated on Sep 02, 2014.
       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
     </div>
   </body>

libs/network/doc/html/reference.html

@@ -94,6 +94,14 @@ <h2>Features<a class="headerlink" href="#features" title="Permalink to this head
 the library, or before including any of the client headers.</li>
 </ul>
 </div></blockquote>
+<p>To use the client implementations that support HTTPS URIs, you may explicitly
+do the following:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define BOOST_NETWORK_ENABLE_HTTPS</span>
+<span class="cp">#include &lt;boost/network/include/http/client.hpp&gt;</span>
+</pre></div>
+</div>
+<p>This forces HTTPS support to be enabled and forces a dependency on <a class="reference external" href="http://www.openssl.org/">OpenSSL</a>.
+This dependency is imposed by <a class="reference external" href="http://www.boost.org/libs/asio">Boost.Asio</a></p>
 </div>
 <div class="section" id="implementations">
 <h2>Implementations<a class="headerlink" href="#implementations" title="Permalink to this headline">¶</a></h2>
@@ -652,7 +660,7 @@ <h3>Navigation</h3>
     </div>
     <div class="footer">
         &copy; Copyright 2008-2014, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
-      Last updated on Sep 01, 2014.
+      Last updated on Sep 02, 2014.
       Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
     </div>
   </body>