doc: use auto-resolved xref titles and reference macros

Author: ashtum

doc/modules/ROOT/nav.adoc

@@ -1,22 +1,22 @@
 * xref:index.adoc[Introduction]
-* xref:quick-start.adoc[Quick Start]
+* xref:quick-start.adoc[]
 * Guide
-** xref:2.guide/2a.making-requests.adoc[Making Requests]
-** xref:2.guide/2b.request-bodies.adoc[Request Bodies]
-** xref:2.guide/2c.responses.adoc[Responses]
-** xref:2.guide/2d.error-handling.adoc[Error Handling]
-** xref:2.guide/2e.headers.adoc[Headers]
-** xref:2.guide/2f.query-parameters.adoc[Query Parameters]
-** xref:2.guide/2g.authentication.adoc[Authentication]
-** xref:2.guide/2h.redirects.adoc[Redirects]
-** xref:2.guide/2i.cookies.adoc[Cookies]
-** xref:2.guide/2j.timeouts.adoc[Timeouts]
-** xref:2.guide/2k.connection-pool.adoc[Connection Pool]
-** xref:2.guide/2l.proxies.adoc[Proxies]
-** xref:2.guide/2m.compression.adoc[Compression]
-** xref:2.guide/2n.extending.adoc[Extending]
+** xref:2.guide/2a.making-requests.adoc[]
+** xref:2.guide/2b.request-bodies.adoc[]
+** xref:2.guide/2c.responses.adoc[]
+** xref:2.guide/2d.error-handling.adoc[]
+** xref:2.guide/2e.headers.adoc[]
+** xref:2.guide/2f.query-parameters.adoc[]
+** xref:2.guide/2g.authentication.adoc[]
+** xref:2.guide/2h.redirects.adoc[]
+** xref:2.guide/2i.cookies.adoc[]
+** xref:2.guide/2j.timeouts.adoc[]
+** xref:2.guide/2k.connection-pool.adoc[]
+** xref:2.guide/2l.proxies.adoc[]
+** xref:2.guide/2m.compression.adoc[]
+** xref:2.guide/2n.extending.adoc[]
 * Examples
-** xref:examples/usage.adoc[Usage]
-** xref:examples/nlohmann_json.adoc[nlohmann/json]
-* xref:testing.adoc[Testing]
+** xref:examples/usage.adoc[]
+** xref:examples/nlohmann_json.adoc[]
+* xref:testing.adoc[]
 * xref:reference:boost/burl.adoc[Reference]

doc/modules/ROOT/pages/2.guide/2a.making-requests.adoc

@@ -85,7 +85,7 @@ feature. A chain is finished by one of three terminal calls.
 
 == Finishing: send
 
-cpp:request_builder::send[send()] sends the request and reads the status line
+cpp:request_builder::send[send] sends the request and reads the status line
 and headers, leaving the body unread. It yields `(error_code, response)`:
 
 [source,cpp]
@@ -135,7 +135,7 @@ xref:2.guide/2d.error-handling.adoc[error handling] section.
 
 == Finishing: build and execute
 
-cpp:request_builder::build[build()] does not send anything. It returns a
+cpp:request_builder::build[build] does not send anything. It returns a
 cpp:request[] — a plain value holding the method, URL, headers, body, and
 per-request options — that can be stored, passed around, and executed later
 through cpp:client::execute[]:
@@ -159,9 +159,7 @@ client; it can be executed by whichever client is convenient.
 
 == Next Steps
 
-* xref:2.guide/2b.request-bodies.adoc[Request Bodies] — Attaching a payload
-* xref:2.guide/2c.responses.adoc[Responses] — Reading the result
-* xref:2.guide/2d.error-handling.adoc[Error Handling] — What the error code
-  means
-* xref:2.guide/2e.headers.adoc[Headers and Query Parameters] — Shaping the
-  request
+* xref:2.guide/2b.request-bodies.adoc[] — Attaching a payload
+* xref:2.guide/2c.responses.adoc[] — Reading the result
+* xref:2.guide/2d.error-handling.adoc[] — What the error code means
+* xref:2.guide/2e.headers.adoc[] — Shaping the request

doc/modules/ROOT/pages/2.guide/2b.request-bodies.adoc

@@ -83,7 +83,7 @@ auto r = co_await client.post("https://example.com/post")
 == URL-Encoded Forms
 
 cpp:urlencoded_form[] builds an `application/x-www-form-urlencoded` body from
-name and value pairs. Names and values are percent-encoded, with spaces written
+name/value pairs. Names and values are percent-encoded, with spaces written
 as `+`. cpp:urlencoded_form::append[append] chains:
 
 [source,cpp]
@@ -139,8 +139,6 @@ rather than sending a truncated or mis-framed body.
 
 == Next Steps
 
-* xref:2.guide/2c.responses.adoc[Responses] — Reading the body that comes back
-* xref:2.guide/2n.extending.adoc[Extending] — Teaching `body` about your own
-  types
-* xref:2.guide/2e.headers.adoc[Headers and Query Parameters] — Overriding the
-  `Content-Type`
+* xref:2.guide/2c.responses.adoc[] — Reading the body that comes back
+* xref:2.guide/2n.extending.adoc[] — Teaching `body` about your own types
+* xref:2.guide/2e.headers.adoc[] — Overriding the `Content-Type`

doc/modules/ROOT/pages/2.guide/2c.responses.adoc

@@ -30,7 +30,7 @@ r.raise_for_status(); // throws on 4xx and 5xx
 r.version();          // http::version
 r.headers();          // const http::fields_base&
 r.url();              // urls::url_view, the final URL after redirects
-r.content_length();   // optional<uint64_t>, empty for a chunked body
+r.content_length();   // std::optional<std::uint64_t>, empty for a chunked body
 ----
 
 == Reading the Body
@@ -158,11 +158,7 @@ case the connection is simply closed on destruction rather than pooled.
 
 == Next Steps
 
-* xref:2.guide/2d.error-handling.adoc[Error Handling] — What the read can fail
-  with
-* xref:2.guide/2m.compression.adoc[Compression] — Transparent decompression
-  of the body
-* xref:2.guide/2k.connection-pool.adoc[Connection Pool] — Where the connection
-  goes next
-* xref:2.guide/2n.extending.adoc[Extending] — Converting the body to your own
-  types
+* xref:2.guide/2d.error-handling.adoc[] — What the read can fail with
+* xref:2.guide/2m.compression.adoc[] — Transparent decompression of the body
+* xref:2.guide/2k.connection-pool.adoc[] — Where the connection goes next
+* xref:2.guide/2n.extending.adoc[] — Converting the body to your own types

doc/modules/ROOT/pages/2.guide/2d.error-handling.adoc

@@ -114,9 +114,7 @@ the *earliest* failure in this order:
 
 == Next Steps
 
-* xref:2.guide/2c.responses.adoc[Responses] — Reading a body once the status is
-  known
-* xref:2.guide/2j.timeouts.adoc[Timeouts] — A common source of transport
-  failures
-* xref:2.guide/2h.redirects.adoc[Redirects] — Where
+* xref:2.guide/2c.responses.adoc[] — Reading a body once the status is known
+* xref:2.guide/2j.timeouts.adoc[] — A common source of transport failures
+* xref:2.guide/2h.redirects.adoc[] — Where
   cpp:error::too_many_redirects[too_many_redirects] comes from

doc/modules/ROOT/pages/2.guide/2e.headers.adoc

@@ -14,7 +14,7 @@ request, or on an individual request.
 
 == Default Headers
 
-cpp:client::headers[client::headers()] is the set of headers sent with every
+cpp:client::headers[] is the set of headers sent with every
 request. A natural place for things that do not change between requests, such as
 a `User-Agent` or an `Accept`:
 
@@ -77,10 +77,10 @@ known
 | The request URL
 
 | `Authorization`
-| xref:2.guide/2g.authentication.adoc[Authentication]
+| xref:2.guide/2g.authentication.adoc[]
 
 | `Cookie`
-| The xref:2.guide/2i.cookies.adoc[cookie jar]
+| The cpp:client::cookie_jar[cookie jar]
 
 | `Accept-Encoding`
 | The xref:2.guide/2m.compression.adoc[compression] settings, unless you set it
@@ -89,10 +89,7 @@ known
 
 == Next Steps
 
-* xref:2.guide/2f.query-parameters.adoc[Query Parameters] — Adding parameters to
-  the URL
-* xref:2.guide/2g.authentication.adoc[Authentication] — The managed
-  `Authorization` header
-* xref:2.guide/2b.request-bodies.adoc[Request Bodies] — Where `Content-Type`
-  comes from
-* xref:2.guide/2i.cookies.adoc[Cookies] — The managed `Cookie` header
+* xref:2.guide/2f.query-parameters.adoc[] — Adding parameters to the URL
+* xref:2.guide/2g.authentication.adoc[] — The managed `Authorization` header
+* xref:2.guide/2b.request-bodies.adoc[] — Where `Content-Type` comes from
+* xref:2.guide/2i.cookies.adoc[] — The managed `Cookie` header

doc/modules/ROOT/pages/2.guide/2f.query-parameters.adoc

@@ -9,14 +9,14 @@
 
 = Query Parameters
 
-Query parameters are the key-and-value pairs that follow the `?` in a URL. Burl
-lets you add them with the builder's cpp:request_builder::query[query] function,
+Query parameters are the name/value pairs that follow the `?` in a URL. Burl
+lets you add them with the cpp:request_builder::query[] function,
 and they can equally be written straight into the URL you pass to the verb
 function, the two approaches produce the same request.
 
 == The query Function
 
-cpp:request_builder::query[query] appends a key-and-value pair to the URL's
+cpp:request_builder::query[] appends a name/value pair to the URL's
 query string, percent-encoding both:
 
 [source,cpp]
@@ -33,9 +33,8 @@ they appear in the query string.
 
 == Parameters in the URL
 
-You do not have to use cpp:request_builder::query[query] at all: parameters
-written directly into the URL you supply are treated identically. These two
-requests are equivalent:
+Parameters written directly into the URL you supply are treated identically.
+These two requests are equivalent:
 
 [source,cpp]
 ----
@@ -52,7 +51,7 @@ auto b = co_await client.get("https://example.com/search?category=shoes&color=bl
 
 == Combining Both
 
-cpp:request_builder::query[query] appends to whatever the URL already carries:
+cpp:request_builder::query[] appends to whatever the URL already carries:
 
 [source,cpp]
 ----
@@ -64,8 +63,6 @@ auto r = co_await client.get("https://example.com/search?category=shoes")
 
 == Next Steps
 
-* xref:2.guide/2e.headers.adoc[Headers] — Setting request and default headers
-* xref:2.guide/2a.making-requests.adoc[Making Requests] — The verb functions
-  that accept a URL
-* xref:2.guide/2g.authentication.adoc[Authentication] — The managed
-  `Authorization` header
+* xref:2.guide/2e.headers.adoc[] — Setting request and default headers
+* xref:2.guide/2a.making-requests.adoc[] — The verb functions that accept a URL
+* xref:2.guide/2g.authentication.adoc[] — The managed `Authorization` header

doc/modules/ROOT/pages/2.guide/2g.authentication.adoc

@@ -64,12 +64,10 @@ regardless of this setting.
 == Custom Schemes
 
 For an authentication scheme Burl does not build in, you can set the
-`Authorization` header yourself with the builder's
-xref:2.guide/2e.headers.adoc[`header`] function. A header you set explicitly
-is sent as-is.
+`Authorization` header yourself with the cpp:request_builder::header[]
+function. A header you set explicitly is sent as-is.
 
 == Next Steps
 
-* xref:2.guide/2h.redirects.adoc[Redirects] — When credentials are stripped
-* xref:2.guide/2e.headers.adoc[Headers and Query Parameters] — Setting a
-  scheme by hand
+* xref:2.guide/2h.redirects.adoc[] — When credentials are stripped
+* xref:2.guide/2e.headers.adoc[] — Setting a scheme by hand

doc/modules/ROOT/pages/2.guide/2h.redirects.adoc

@@ -44,7 +44,7 @@ std::cout << r.status_int() << '\n';                       // e.g. 301
 std::cout << r.headers().value_or(http::field::location, "") << '\n';
 ----
 
-When redirects are followed, cpp:response::url[response::url()] reports the
+When redirects are followed, cpp:response::url[] reports the
 final URL the response came from:
 
 [source,cpp]
@@ -106,13 +106,12 @@ When a redirect crosses to a different origin, the `Authorization` and
 dropped, so credentials meant for one host are not handed to another.
 cpp:client::config[config::unrestricted_auth] keeps sending them; the
 xref:2.guide/2g.authentication.adoc[authentication] section covers this in full.
-Same- origin redirects always carry credentials through.
+Same-origin redirects always carry credentials through.
 
 == Next Steps
 
-* xref:2.guide/2g.authentication.adoc[Authentication] — Cross-origin credential
-  stripping
-* xref:2.guide/2i.cookies.adoc[Cookies] — How the jar follows redirects
-* xref:2.guide/2d.error-handling.adoc[Error Handling] —
+* xref:2.guide/2g.authentication.adoc[] — Cross-origin credential stripping
+* xref:2.guide/2i.cookies.adoc[] — How the jar follows redirects
+* xref:2.guide/2d.error-handling.adoc[] —
   cpp:error::too_many_redirects[too_many_redirects] and
   cpp:error::bad_redirect_response[bad_redirect_response]

doc/modules/ROOT/pages/2.guide/2i.cookies.adoc

@@ -11,8 +11,8 @@
 
 When cookie handling is enabled, the client stores cookies from `Set-Cookie`
 response headers in its cookie jar and sends matching cookies on later
-requests, following the storage and matching rules of RFC 6265. The jar can be
-inspected directly and persisted between sessions.
+requests, following the storage and matching rules of RFC 6265bis. The jar can
+be inspected directly and persisted between sessions.
 
 == Enabling Cookies
 
@@ -33,7 +33,7 @@ auto r = co_await client.get("https://example.com/account").send();
 
 == The Cookie Jar
 
-cpp:client::cookie_jar[client::cookie_jar()] gives direct access to the jar. The
+cpp:client::cookie_jar[] gives direct access to the jar. The
 cookies can be listed, cleared, or seeded by hand:
 
 [source,cpp]
@@ -86,7 +86,5 @@ an error if a line is malformed. Empty and comment lines are skipped, except the
 
 == Next Steps
 
-* xref:2.guide/2h.redirects.adoc[Redirects] — How cookies and credentials follow
-  hops
-* xref:2.guide/2e.headers.adoc[Headers and Query Parameters] — Setting a
-  `Cookie` header by hand
+* xref:2.guide/2h.redirects.adoc[] — How cookies and credentials follow hops
+* xref:2.guide/2e.headers.adoc[] — Setting a `Cookie` header by hand