doc work

doc/modules/ROOT/nav.adoc

@@ -1,31 +1,33 @@
-* xref:1.primer.adoc[]
-* xref:2.messages.adoc[]
-* xref:sans_io_philosophy.adoc[]
-* xref:http_protocol_basics.adoc[]
-// * xref:header_containers.adoc[]
-* xref:message_bodies.adoc[]
-* Serializing
-* Parsing
-* xref:Message.adoc[]
-* Server
-** xref:server/servers-intro.adoc[Servers]
-** xref:server/route-handlers.adoc[Route Handlers]
-** xref:server/router.adoc[Router]
-** xref:server/routers.adoc[Routers Deep Dive]
-** xref:server/route-patterns.adoc[Route Patterns]
-** xref:server/serve-static.adoc[Serving Static Files]
-** xref:server/serve-index.adoc[Directory Listings]
-** xref:server/bcrypt.adoc[BCrypt Password Hashing]
-// ** xref:server/middleware.adoc[Middleware]
-// ** xref:server/errors.adoc[Error Handling]
-// ** xref:server/params.adoc[Route Parameters]
-// ** xref:server/advanced.adoc[Advanced Topics]
-// ** xref:server/cors.adoc[CORS]
-* Compression
-** xref:compression/zlib.adoc[ZLib]
-** xref:compression/brotli.adoc[Brotli]
-* Design Requirements
-** xref:design_requirements/serializer.adoc[Serializer]
-** xref:design_requirements/parser.adoc[Parser]
-// * xref:reference:boost/http.adoc[Reference]
-* xref:reference.adoc[Reference]
+* xref:2.http-tutorial/2.http-tutorial.adoc[HTTP Tutorial]
+** xref:2.http-tutorial/2a.what-is-http.adoc[What is HTTP]
+** xref:2.http-tutorial/2b.urls-and-resources.adoc[URLs and Resources]
+** xref:2.http-tutorial/2c.message-anatomy.adoc[Message Anatomy]
+** xref:2.http-tutorial/2d.methods.adoc[Methods]
+** xref:2.http-tutorial/2e.status-codes.adoc[Status Codes]
+** xref:2.http-tutorial/2f.headers.adoc[Headers]
+** xref:2.http-tutorial/2g.content-negotiation.adoc[Content Negotiation and Body Encoding]
+** xref:2.http-tutorial/2h.connection-management.adoc[Connection Management]
+** xref:2.http-tutorial/2i.caching.adoc[Caching]
+** xref:2.http-tutorial/2j.authentication.adoc[Authentication and Security]
+** xref:2.http-tutorial/2k.http2.adoc[HTTP/2]
+** xref:2.http-tutorial/2l.http3.adoc[HTTP/3 and QUIC]
+* xref:3.messages/3.messages.adoc[HTTP Messages]
+** xref:3.messages/3a.containers.adoc[Containers]
+** xref:3.messages/3b.serializing.adoc[Serializing]
+** xref:3.messages/3c.parsing.adoc[Parsing]
+* xref:4.servers/4.servers.adoc[HTTP Servers]
+** xref:4.servers/4a.http-worker.adoc[HTTP Worker]
+** xref:4.servers/4b.route-handlers.adoc[Route Handlers]
+** xref:4.servers/4c.routers.adoc[Routers]
+** xref:4.servers/4d.route-patterns.adoc[Route Patterns]
+** xref:4.servers/4e.serve-static.adoc[Serving Static Files]
+** xref:4.servers/4f.serve-index.adoc[Directory Listings]
+** xref:4.servers/4g.bcrypt.adoc[BCrypt]
+* xref:5.compression/5.compression.adoc[Compression]
+** xref:5.compression/5a.zlib.adoc[ZLib]
+** xref:5.compression/5b.brotli.adoc[Brotli]
+* xref:6.design/6.design.adoc[Design]
+** xref:6.design/6a.sans-io.adoc[Sans-I/O Philosophy]
+** xref:6.design/6b.parser.adoc[Parser]
+** xref:6.design/6c.serializer.adoc[Serializer]
+* xref:7.reference/7.reference.adoc[Reference]

doc/modules/ROOT/pages/2.http-tutorial/2.http-tutorial.adoc

@@ -0,0 +1,43 @@
+//
+// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
+//
+// 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)
+//
+// Official repository: https://github.com/cppalliance/http
+//
+
+= Introduction to HTTP
+
+Every time you click a link, a small conversation takes place between
+two machines. One asks a question; the other answers it. The language
+they speak is HTTP, and it is the most widely used application protocol
+on Earth. Billions of requests flow through it every hour--web pages,
+images, API calls, video streams--all carried by the same simple
+exchange of text messages that Tim Berners-Lee sketched on a notepad
+in 1990.
+
+You are about to learn that language from the ground up.
+
+We start with the basics: what HTTP actually is, and how clients and
+servers find each other through URLs. From there you will look inside
+the messages themselves--their structure, the methods that give them
+purpose, and the status codes that report what happened. You will see
+how headers quietly orchestrate everything from content types to
+caching policies, and how content negotiation lets a single resource
+serve different representations to different clients.
+
+Then the picture gets more interesting. You will learn how connections
+are opened, reused, and closed--and why getting this right matters more
+than most people realize. Caching will show you how the Web avoids
+doing the same work twice. Authentication will reveal how identity and
+trust are woven into the protocol without breaking its stateless design.
+
+Finally, you will follow HTTP's evolution into its modern forms: the
+binary multiplexing of HTTP/2, and the QUIC-based transport of HTTP/3
+that eliminates decades-old performance bottlenecks at the transport
+layer.
+
+None of this requires prior networking experience. Each section builds
+on the last, and by the end you will read raw HTTP traffic the way a
+mechanic reads an engine--seeing not just what is happening, but _why_.