Documentation work

doc/0_main.qbk

@@ -87,7 +87,7 @@
 [import ../test/websocket/doc_snippets.cpp]
 [import ../test/websocket/ssl/doc_snippets.cpp]
 
-[include 1_overview.qbk]
+[include 1_intro.qbk]
 [include 2_examples.qbk]
 [include 3_0_core.qbk]
 [include 5_00_http.qbk]

doc/1_intro.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:overview Introduction]
+[section Introduction]
 
 Beast is a C++ header-only library serving as a foundation for writing
 interoperable networking libraries by providing [*low-level HTTP/1,

doc/2_examples.qbk

@@ -5,15 +5,9 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:example Examples]
+[section Quick Start]
 [block'''<?dbhtml stop-chunking?>''']
 
-These complete programs are intended to quickly impress upon readers the
-flavor of the library. Source code and build scripts for them are located
-in the examples directory.
-
-
-
 [section HTTP Client]
 
 Use HTTP to make a GET request to a website and print the response:
@@ -24,6 +18,38 @@ File: [repo_file example/http-client/http_client.cpp]
 
 [endsect]
 
+[section WebSocket Client]
+
+Establish a WebSocket connection, send a message and receive the reply:
+
+File: [repo_file example/websocket-client/websocket_client.cpp]
+
+[example_websocket_client]
+
+[endsect]
+
+[endsect]
+
+
+
+[section Examples]
+[block'''<?dbhtml stop-chunking?>''']
+
+These complete programs are intended to quickly impress upon readers the
+flavor of the library. Source code and build scripts for them are located
+in the examples directory.
+
+
+
+[section HTTP Crawl]
+
+This example retrieves the page at each of the most popular domains
+as measured by Alexa.
+
+* [repo_file example/http-crawl/http_crawl.cpp]
+
+[endsect]
+
 
 
 [section HTTP Client (with SSL)]
@@ -37,29 +63,6 @@ over a TLS connection. Requires OpenSSL to build.
 
 
 
-[section HTTP Crawl]
-
-This example retrieves the page at each of the most popular domains
-as measured by Alexa.
-
-* [repo_file example/http-crawl/http_crawl.cpp]
-
-[endsect]
-
-
-
-[section WebSocket Client]
-
-Establish a WebSocket connection, send a message and receive the reply:
-
-File: [repo_file example/websocket-client/websocket_client.cpp]
-
-[example_websocket_client]
-
-[endsect]
-
-
-
 [section WebSocket Client (with SSL)]
 
 Establish a WebSocket connection over an encrypted TLS connection,
@@ -71,6 +74,33 @@ send a message and receive the reply. Requires OpenSSL to build.
 
 
 
+[section Documentation Samples]
+
+Here are all of the example functions and classes presented
+throughout the documentation, they can be included and used
+in your program without modification
+
+* [repo_file example/doc/core_examples.hpp]
+
+* [repo_file example/doc/http_examples.hpp]
+
+[endsect]
+
+
+
+[section Composed Operations]
+
+This program shows how to use Beast's network foundations to build a
+composable asynchronous initiation function with associated composed
+operation implementation. This is a complete, runnable version of
+the example described in the Core Foundations document section.
+
+* [repo_file example/echo-op/echo_op.cpp]
+
+[endsect]
+
+
+
 [section Server Framework]
 
 This is a complete program and framework of classes implementing
@@ -96,31 +126,4 @@ for writing their own servers. It serves both HTTP and WebSocket.
 
 
 
-[section Composed Operations]
-
-This program shows how to use Beast's network foundations to build a
-composable asynchronous initiation function with associated composed
-operation implementation. This is a complete, runnable version of
-the example described in the Core Foundations document section.
-
-* [repo_file example/echo-op/echo_op.cpp]
-
-[endsect]
-
-
-
-[section Documentation Samples]
-
-Here are all of the example functions and classes presented
-throughout the documentation, they can be included and used
-in your program without modification
-
-* [repo_file example/doc/core_examples.hpp]
-
-* [repo_file example/doc/http_examples.hpp]
-
-[endsect]
-
-
-
 [endsect]

doc/3_0_core.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:core Using Networking]
+[section Using Networking]
 
 This library makes network primitives used by the implementation publicly
 available so users can take advantage of them in their own libraries.

doc/3_1_asio.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:asio Boost.Asio Refresher]
+[section Asio Refresher]
 
 [warning
     Beast does not manage sockets, make outgoing connections,

doc/3_2_streams.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:streams Stream Types]
+[section Stream Types]
 
 A __Stream__ is a communication channel where data is transferred as
 an ordered sequence of octet buffers. Streams are either synchronous

doc/3_3_buffers.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:buffers Buffer Types]
+[section Buffer Types]
 
 __Asio__ provides the __ConstBufferSequence__ and __MutableBufferSequence__
 concepts, whose models provide ranges of buffers, as well as the __streambuf__

doc/3_4_composed.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:composed Composed Operations]
+[section Composed Operations]
 [block'''<?dbhtml stop-chunking?>''']
 
 Asynchronous operations are started by calling a free function or member
@@ -103,7 +103,7 @@ available:
 
 
 
-[section Asynchronous Echo]
+[section Echo]
 
 Here we develop an asynchronous composed operation called [*echo].
 This operation will read up to the first newline on a stream, and

doc/3_5_detect_ssl.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:detect_tls Example: Detect SSL]
+[section Example: Detect SSL]
 
 In this example we will build a simple function to detect the presence
 of the SSL handshake given an input buffer sequence. Then we build on

doc/5_00_http.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:http Using HTTP]
+[section Using HTTP]
 
 [warning
     Higher level functions such as Basic

doc/5_01_primer.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:primer Protocol Primer]
+[section Protocol Primer]
 
 The HTTP protocol defines the
 [@https://tools.ietf.org/html/rfc7230#section-2.1 client and server roles]:

doc/5_02_message.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:message Message Containers]
+[section Message Containers]
 
 Beast provides a single class template __message__ which models
 HTTP/1 and

doc/5_03_streams.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:streams Message Stream Operations]
+[section Message Stream Operations]
 
 Beast provides synchronous and asynchronous algorithms to parse and
 serialize HTTP/1 wire format messages on streams. These functions form

doc/5_04_serializer_streams.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:serializer_streams Serializer Stream Operations]
+[section Serializer Stream Operations]
 
 Non-trivial algorithms need to do more than send entire messages
 at once, such as:

doc/5_05_parser_streams.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:parser_streams Parser Stream Operations]
+[section Parser Stream Operations]
 
 Non-trivial algorithms need to do more than receive entire messages
 at once, such as:

doc/5_06_serializer_buffers.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:serializer_buffers Buffer-Oriented Serializing]
+[section Buffer-Oriented Serializing]
 [block'''<?dbhtml stop-chunking?>''']
 
 An instance of __serializer__ can be invoked directly, without using

doc/5_07_parser_buffers.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:parser_buffers Buffer-Oriented Parsing]
+[section Buffer-Oriented Parsing]
 [block'''<?dbhtml stop-chunking?>''']
 
 A subclass of __basic_parser__ can be invoked directly, without using 

doc/5_08_custom_body.qbk

@@ -5,14 +5,31 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:custom_body Custom Body Types]
+[section Custom Body Types]
 [block'''<?dbhtml stop-chunking?>''']
 
 User-defined types are possible for the message body, where the type meets the
 __Body__ requirements. This simplified class declaration
 shows the customization points available to user-defined body types:
+```
+/// Defines a Body type
+struct body
+{
+    /// This determines the type of the `message::body` member
+    using value_type = ...;
 
-[$images/body.png [width 525px] [height 190px]]
+    /// An optional function, returns the body's payload size
+    static
+    std::uint64_t
+    size(value_type const& v);
+
+    /// The algorithm used for extracting buffers
+    class reader;
+
+    /// The algorithm used for inserting buffers
+    class writer;
+}
+```
 
 The meaning of the nested types is as follows
 
@@ -80,7 +97,7 @@ those bodies may be serialized or parsed.
 
 
 
-[section File Body Type]
+[section File Body]
 
 Use of the flexible __Body__ concept customization point enables authors to
 preserve the self-contained nature of the __message__ object while allowing

doc/5_09_custom_parsers.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:custom_parsers Custom Parsers]
+[section Custom Parsers]
 
 While the parsers included in the library will handle a broad number of
 use-cases, the __basic_parser__ interface can be subclassed to implement

doc/7_0_websocket.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:websocket Using WebSocket]
+[section Using WebSocket]
 
 The WebSocket Protocol enables two-way communication between a client
 running untrusted code in a controlled environment to a remote host that has

doc/7_1_streams.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:streams Creating Streams]
+[section Creating Streams]
 
 The interface to the WebSocket implementation is a single template class
 [link beast.ref.beast__websocket__stream `stream`]

doc/7_2_connect.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:connect Establishing Connections]
+[section Establishing Connections]
 
 Connections are established by invoking functions directly on the next layer
 object. For example, to make an outgoing connection using a standard TCP/IP

doc/7_3_client.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:client Handshaking (Clients)]
+[section Handshaking (Clients)]
 
 A WebSocket session begins when a client sends the HTTP/1
 [@https://tools.ietf.org/html/rfc7230#section-6.7 Upgrade]

doc/7_4_server.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:server Handshaking (Servers)]
+[section Handshaking (Servers)]
 
 A
 [link beast.ref.beast__websocket__stream `stream`]

doc/7_5_messages.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:messages Send and Receive Messages]
+[section Send and Receive Messages]
 
 After the WebSocket handshake is accomplished, callers may send and receive
 messages using the message oriented interface. This interface requires that

doc/7_6_control.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:control Control Frames]
+[section Control Frames]
 
 Control frames are small (less than 128 bytes) messages entirely contained
 in an individual WebSocket frame. They may be sent at any time by either

doc/7_7_notes.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:notes Notes]
+[section Notes]
 
 Because calls to read data may return a variable amount of bytes, the
 interface to calls that read data require an object that meets the requirements

doc/9_0_design.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:design Design Choices]
+[section Design Choices]
 
 The implementations were originally driven by business needs of cryptocurrency
 server applications (e.g.  [@https://github.com/ripple/rippled rippled]),

doc/9_1_http_message.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:http_message HTTP Message Container]
+[section HTTP Message Container]
 
 In this section we describe the problem of modeling HTTP messages and explain
 how the library arrived at its solution, with a discussion of the benefits

doc/9_2_http_comparison.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:http_comparison HTTP Comparison to Other Libraries]
+[section HTTP Comparison to Other Libraries]
 
 There are a few C++ published libraries which implement some of the HTTP
 protocol. We analyze the message model chosen by those libraries and discuss

doc/9_3_websocket_zaphoyd.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:websocket_zaphoyd Comparison to Zaphoyd Studios WebSocket++]
+[section Comparison to Zaphoyd Studios WebSocket++]
 
 [variablelist
 

doc/9_4_faq.qbk

@@ -5,7 +5,7 @@
     file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 ]
 
-[section:faq FAQ]
+[section FAQ]
 
 To set realistic expectations and prevent a litany of duplicate review
 statements, these notes address the most common questions and comments

doc/Jamfile

@@ -32,7 +32,6 @@ install images
     :
         [ glob $(broot)/doc/src/images/*.png ]
         images/beast.png
-        images/body.png
         images/message.png
     :
         <location>$(out)/html/images